diff options
Diffstat (limited to 'drivers/acpi/acpica/utstrtoul64.c')
| -rw-r--r-- | drivers/acpi/acpica/utstrtoul64.c | 104 |
1 files changed, 52 insertions, 52 deletions
diff --git a/drivers/acpi/acpica/utstrtoul64.c b/drivers/acpi/acpica/utstrtoul64.c index e5a2df3f16e5..67a39d97a6d6 100644 --- a/drivers/acpi/acpica/utstrtoul64.c +++ b/drivers/acpi/acpica/utstrtoul64.c @@ -1,7 +1,7 @@ /******************************************************************************* * - * Module Name: utstrtoul64 - string-to-integer support for both 64-bit - * and 32-bit integers + * Module Name: utstrtoul64 - String-to-integer conversion support for both + * 64-bit and 32-bit integers * ******************************************************************************/ @@ -50,21 +50,23 @@ ACPI_MODULE_NAME("utstrtoul64") /******************************************************************************* * - * This module contains the external string to 64/32-bit unsigned integer + * This module contains the top-level string to 64/32-bit unsigned integer * conversion functions: * - * 1) Standard strtoul() function with 64-bit support. This is mostly used by - * the iASL compiler. + * 1) A standard strtoul() function that supports 64-bit integers, base + * 8/10/16, with integer overflow support. This is used mainly by the + * iASL compiler, which implements tighter constraints on integer + * constants than the runtime (interpreter) integer-to-string conversions. * 2) Runtime "Explicit conversion" as defined in the ACPI specification. * 3) Runtime "Implicit conversion" as defined in the ACPI specification. * * Current users of this module: * + * iASL - Preprocessor (constants and math expressions) + * iASL - Main parser, conversion of constants to integers + * iASL - Data Table Compiler parser (constants and math expressions) * interpreter - Implicit and explicit conversions, GPE method names * debugger - Command line input string conversion - * iASL - Main parser, conversion of constants to integers - * iASL - Data Table Compiler parser (constant math expressions) - * iASL - Preprocessor (constant math expressions) * acpi_dump - Input table addresses * acpi_exec - Testing of the acpi_ut_strtoul64 function * @@ -77,15 +79,17 @@ ACPI_MODULE_NAME("utstrtoul64") * a 64-bit constant is wrongly defined in a 32-bit DSDT/SSDT. * * In ACPI, the only place where octal numbers are supported is within - * the ASL language itself. There is no runtime support for octal. + * the ASL language itself. This is implemented via the main acpi_ut_strtoul64 + * interface. According the ACPI specification, there is no ACPI runtime + * support for octal string conversions. * ******************************************************************************/ /******************************************************************************* * * FUNCTION: acpi_ut_strtoul64 * - * PARAMETERS: string - Null terminated input string. - * Must be a valid pointer + * PARAMETERS: string - Null terminated input string, + * must be a valid pointer * return_value - Where the converted integer is * returned. Must be a valid pointer * @@ -98,9 +102,9 @@ ACPI_MODULE_NAME("utstrtoul64") * * Current users of this function: * - * iASL - Preprocessor (constant math expressions) - * iASL - Main parser, conversion of ASL constants to integers - * iASL - Data Table Compiler parser (constant math expressions) + * iASL - Preprocessor (constants and math expressions) + * iASL - Main ASL parser, conversion of ASL constants to integers + * iASL - Data Table Compiler parser (constants and math expressions) * ******************************************************************************/ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) @@ -112,17 +116,14 @@ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) *return_value = 0; - /* Null return string returns a value of zero */ + /* A NULL return string returns a value of zero */ if (*string == 0) { return_ACPI_STATUS(AE_OK); } /* - * 1) The "0x" prefix indicates base 16. Per the ACPI specification, - * the "0x" prefix is only allowed for implicit (non-strict) conversions. - * However, we always allow it for compatibility with older ACPICA and - * just plain on principle. + * 1) Check for a hex constant. A "0x" prefix indicates base 16. */ if (acpi_ut_detect_hex_prefix(&string)) { base = 16; @@ -130,7 +131,7 @@ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) /* * 2) Check for an octal constant, defined to be a leading zero - * followed by an valid octal digit (0-7) + * followed by sequence of octal digits (0-7) */ else if (acpi_ut_detect_octal_prefix(&string)) { base = 8; @@ -142,7 +143,7 @@ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) /* * Perform the base 8, 10, or 16 conversion. A numeric overflow will - * return an exception. + * return an exception (to allow iASL to flag the statement). */ switch (base) { case 8: @@ -154,11 +155,8 @@ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) break; case 16: - status = acpi_ut_convert_hex_string(string, return_value); - break; - default: - status = AE_AML_INTERNAL; /* Should never happen */ + status = acpi_ut_convert_hex_string(string, return_value); break; } @@ -169,8 +167,8 @@ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) * * FUNCTION: acpi_ut_implicit_strtoul64 * - * PARAMETERS: string - Null terminated input string. - * Must be a valid pointer + * PARAMETERS: string - Null terminated input string, + * must be a valid pointer * * RETURN: Converted integer * @@ -178,42 +176,44 @@ acpi_status acpi_ut_strtoul64(char *string, u64 *return_value) * an "implicit conversion" by the ACPI specification. Used by * many ASL operators that require an integer operand, and support * an automatic (implicit) conversion from a string operand - * to the final integer operand. The restriction is that only - * hex strings are supported. + * to the final integer operand. The major restriction is that + * only hex strings are supported. * * ----------------------------------------------------------------------------- * - * Base is always 16, either with or without the 0x prefix. + * Base is always 16, either with or without the 0x prefix. Decimal and + * Octal strings are not supported, as per the ACPI specification. * * Examples (both are hex values): * Add ("BA98", Arg0, Local0) * Subtract ("0x12345678", Arg1, Local1) * - * Rules extracted from the ACPI specification: + * Conversion rules as extracted from the ACPI specification: * * The converted integer is initialized to the value zero. - * The ASCII string is interpreted as a hexadecimal constant. + * The ASCII string is always interpreted as a hexadecimal constant. * - * 1) A "0x" prefix is not allowed. However, ACPICA allows this as an - * ACPI extension on general principle. (NO ERROR) + * 1) According to the ACPI specification, a "0x" prefix is not allowed. + * However, ACPICA allows this as an ACPI extension on general + * principle. (NO ERROR) * - * 2) Terminates when the size of an integer is reached (32 or 64 bits). - * There are no numeric overflow conditions. (NO ERROR) + * 2) The conversion terminates when the size of an integer is reached + * (32 or 64 bits). There are no numeric overflow conditions. (NO ERROR) * * 3) The first non-hex character terminates the conversion and returns * the current accumulated value of the converted integer (NO ERROR). * * 4) Conversion of a null (zero-length) string to an integer is - * technically allowed. However, ACPICA allows as an ACPI extension. - * The conversion returns the value 0. (NO ERROR) + * technically not allowed. However, ACPICA allows this as an ACPI + * extension. The conversion returns the value 0. (NO ERROR) * - * Note: there are no error conditions returned by this function. At + * NOTE: There are no error conditions returned by this function. At * the minimum, a value of zero is returned. * * Current users of this function: * * interpreter - All runtime implicit conversions, as per ACPI specification - * iASL - Data Table Compiler parser (constant math expressions) + * iASL - Data Table Compiler parser (constants and math expressions) * ******************************************************************************/ @@ -247,8 +247,8 @@ u64 acpi_ut_implicit_strtoul64(char *string) * * FUNCTION: acpi_ut_explicit_strtoul64 * - * PARAMETERS: string - Null terminated input string. - * Must be a valid pointer + * PARAMETERS: string - Null terminated input string, + * must be a valid pointer * * RETURN: Converted integer * @@ -258,16 +258,16 @@ u64 acpi_ut_implicit_strtoul64(char *string) * * ----------------------------------------------------------------------------- * - * Base is either 10 (default) or 16 (with 0x prefix). There is no octal - * (base 8), as per the ACPI specification. + * Base is either 10 (default) or 16 (with 0x prefix). Octal (base 8) strings + * are not supported, as per the ACPI specification. * * Examples: * to_integer ("1000") Decimal * to_integer ("0xABCD") Hex * - * Rules extracted from the ACPI specification: + * Conversion rules as extracted from the ACPI specification: * - * 1) Thi input string is either a decimal or hexadecimal numeric string. + * 1) The input string is either a decimal or hexadecimal numeric string. * A hex value must be prefixed by "0x" or it is interpreted as decimal. * * 2) The value must not exceed the maximum of an integer value @@ -275,18 +275,18 @@ u64 acpi_ut_implicit_strtoul64(char *string) * "unpredictable", so ACPICA matches the behavior of the implicit * conversion case. There are no numeric overflow conditions. (NO ERROR) * - * 3) Behavior on the first non-hex character is not specified by the ACPI + * 3) Behavior on the first non-hex character is not defined by the ACPI * specification (for the to_integer operator), so ACPICA matches the * behavior of the implicit conversion case. It terminates the * conversion and returns the current accumulated value of the converted * integer. (NO ERROR) * * 4) Conversion of a null (zero-length) string to an integer is - * technically allowed. However, ACPICA allows as an ACPI extension. - * The conversion returns the value 0. (NO ERROR) + * technically not allowed. However, ACPICA allows this as an ACPI + * extension. The conversion returns the value 0. (NO ERROR) * - * Note: there are no error conditions returned by this function. At - * the minimum, a value of zero is returned. + * NOTE: There are no error conditions returned by this function. At the + * minimum, a value of zero is returned. * * Current users of this function: * @@ -303,7 +303,7 @@ u64 acpi_ut_explicit_strtoul64(char *string) /* * Only Hex and Decimal are supported, as per the ACPI specification. - * 0x prefix means hex; otherwise decimal is assumed. + * A "0x" prefix indicates hex; otherwise decimal is assumed. */ if (acpi_ut_detect_hex_prefix(&string)) { base = 16; |