From: Bob Moore <robert.moore@xxxxxxxxx> ACPICA commit 33e38cd2406709b13fa0a7821e588505b3771163 Cleanup some of the language used in the large comments, especially the ones that reference the rules in the ACPI spec. Fixed some typos. Link: https://github.com/acpica/acpica/commit/33e38cd2 Signed-off-by: Bob Moore <robert.moore@xxxxxxxxx> Signed-off-by: Erik Schmauss <erik.schmauss@xxxxxxxxx> --- drivers/acpi/acpica/utstrsuppt.c | 48 ++++++++---------- drivers/acpi/acpica/utstrtoul64.c | 104 +++++++++++++++++++------------------- 2 files changed, 74 insertions(+), 78 deletions(-) diff --git a/drivers/acpi/acpica/utstrsuppt.c b/drivers/acpi/acpica/utstrsuppt.c index 64a5faefccbf..e402cf7cbd4b 100644 --- a/drivers/acpi/acpica/utstrsuppt.c +++ b/drivers/acpi/acpica/utstrsuppt.c @@ -1,6 +1,6 @@ /******************************************************************************* * - * Module Name: utstrsuppt - string-to-integer conversion support functions + * Module Name: utstrsuppt - Support functions for string-to-integer conversion * ******************************************************************************/ @@ -83,7 +83,7 @@ acpi_status acpi_ut_convert_octal_string(char *string, u64 *return_value_ptr) while (*string) { - /* Must be ASCII 0-7, otherwise terminate with no error */ + /* Character must be ASCII 0-7, otherwise terminate with no error */ if (!(ACPI_IS_OCTAL_DIGIT(*string))) { break; @@ -132,7 +132,7 @@ acpi_status acpi_ut_convert_decimal_string(char *string, u64 *return_value_ptr) while (*string) { - /* Must be ASCII 0-9, otherwise terminate with no error */ + /* Character must be ASCII 0-9, otherwise terminate with no error */ if (!isdigit(*string)) { break; @@ -210,18 +210,17 @@ acpi_status acpi_ut_convert_hex_string(char *string, u64 *return_value_ptr) * * PARAMETERS: string - Pointer to input ASCII string * - * RETURN: Next character after the leading zeros. This behavior may be - * Used by the caller to detect end-of-string. + * RETURN: Next character after any leading zeros. This character may be + * used by the caller to detect end-of-string. * - * DESCRIPTION: Remove all leading zeros in the input string. Return the - * next character after the final zero to check for the end - * of the string (NULL terminator). + * DESCRIPTION: Remove any leading zeros in the input string. Return the + * next character after the final ASCII zero to enable the caller + * to check for the end of the string (NULL terminator). * ******************************************************************************/ char acpi_ut_remove_leading_zeros(char **string) { - /* Skip all leading zeros */ while (**string == ACPI_ASCII_ZERO) { *string += 1; @@ -236,9 +235,9 @@ char acpi_ut_remove_leading_zeros(char **string) * * PARAMETERS: string - Pointer to input ASCII string * - * RETURN: TRUE if a 0x prefix was found + * RETURN: TRUE if a "0x" prefix was found at the start of the string * - * DESCRIPTION: Detect and remove a hex 0x prefix + * DESCRIPTION: Detect and remove a hex "0x" prefix * ******************************************************************************/ @@ -260,7 +259,8 @@ u8 acpi_ut_detect_hex_prefix(char **string) * * PARAMETERS: string - Pointer to input ASCII string * - * RETURN: True if an octal 0 prefix was found + * RETURN: True if an octal "0" prefix was found at the start of the + * string * * DESCRIPTION: Detect and remove an octal prefix (zero) * @@ -282,23 +282,22 @@ u8 acpi_ut_detect_octal_prefix(char **string) * FUNCTION: acpi_ut_insert_digit * * PARAMETERS: accumulated_value - Current value of the integer value - * accumulator. The New value is + * accumulator. The new value is * returned here. - * base - Radix, either 8/10/16 supported + * base - Radix, either 8/10/16 * ascii_digit - ASCII single digit to be inserted * - * RETURN: Status and result of convert/insert operation. The only - * exception is numeric overflow of either the multiply or the - * add operations. + * RETURN: Status and result of the convert/insert operation. The only + * possible returned exception code is numeric overflow of + * either the multiply or add conversion operations. * * DESCRIPTION: Generic conversion and insertion function for all bases: * - * 1) Multiply the current accumulated converted value by the + * 1) Multiply the current accumulated/converted value by the * base in order to make room for the new character. * - * 2) Add the current accumulated/converted value the new - * character (after the character has been converted to a binary - * value). + * 2) Convert the new character to binary and add it to the + * current accumulated value. * * Note: The only possible exception indicates an integer * overflow (AE_NUMERIC_OVERFLOW) @@ -318,17 +317,14 @@ acpi_ut_insert_digit(u64 *accumulated_value, u32 base, int ascii_digit) return (status); } - /* Add in the new digit, and store to the caller's accumulated value */ + /* Add in the new digit, and store the sum to the accumulated value */ status = acpi_ut_strtoul_add64(product, acpi_ut_ascii_char_to_hex(ascii_digit), accumulated_value); - if (ACPI_FAILURE(status)) { - return (status); - } - return (AE_OK); + return (status); } /******************************************************************************* 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; -- 2.13.6 -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
