[PATCH 5/8] ACPICA: String conversions: Cleanup/format comments. No functional changes

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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/33e38cd24067
Signed-off-by: Bob Moore <robert.moore@xxxxxxxxx>
Signed-off-by: Lv Zheng <lv.zheng@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 64a5fae..e402cf7 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 e5a2df3..67a39d9 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.7.4

--
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



[Index of Archives]     [Linux IBM ACPI]     [Linux Power Management]     [Linux Kernel]     [Linux Laptop]     [Kernel Newbies]     [Share Photos]     [Security]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux