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>

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;