ACPICA: String conversions: Cleanup/format comments. No functional changes

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/33e38cd24067
Signed-off-by: Bob Moore <robert.moore@intel.com>
Signed-off-by: Lv Zheng <lv.zheng@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

2 files changed, 74 insertions, 78 deletions

diff --git a/drivers/acpi/acpica/utstrsuppt.c b/drivers/acpi/acpica/utstrsuppt.c
index ca41f037fd9a..2526ba3b4f12 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;