drivers/acpi/acpica/utstrtoul64.c

   1 // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0
   2 /*******************************************************************************
   3  *
   4  * Module Name: utstrtoul64 - String-to-integer conversion support for both
   5  *                            64-bit and 32-bit integers
   6  *
   7  ******************************************************************************/
   8
   9 #include <acpi/acpi.h>
  10 #include "accommon.h"
  11
  12 #define _COMPONENT          ACPI_UTILITIES
  13 ACPI_MODULE_NAME("utstrtoul64")
  14
  15 /*******************************************************************************
  16  *
  17  * This module contains the top-level string to 64/32-bit unsigned integer
  18  * conversion functions:
  19  *
  20  *  1) A standard strtoul() function that supports 64-bit integers, base
  21  *     8/10/16, with integer overflow support. This is used mainly by the
  22  *     iASL compiler, which implements tighter constraints on integer
  23  *     constants than the runtime (interpreter) integer-to-string conversions.
  24  *  2) Runtime "Explicit conversion" as defined in the ACPI specification.
  25  *  3) Runtime "Implicit conversion" as defined in the ACPI specification.
  26  *
  27  * Current users of this module:
  28  *
  29  *  iASL        - Preprocessor (constants and math expressions)
  30  *  iASL        - Main parser, conversion of constants to integers
  31  *  iASL        - Data Table Compiler parser (constants and math expressions)
  32  *  interpreter - Implicit and explicit conversions, GPE method names
  33  *  interpreter - Repair code for return values from predefined names
  34  *  debugger    - Command line input string conversion
  35  *  acpi_dump   - ACPI table physical addresses
  36  *  acpi_exec   - Support for namespace overrides
  37  *
  38  * Notes concerning users of these interfaces:
  39  *
  40  * acpi_gbl_integer_byte_width is used to set the 32/64 bit limit for explicit
  41  * and implicit conversions. This global must be set to the proper width.
  42  * For the core ACPICA code, the width depends on the DSDT version. For the
  43  * acpi_ut_strtoul64 interface, all conversions are 64 bits. This interface is
  44  * used primarily for iASL, where the default width is 64 bits for all parsers,
  45  * but error checking is performed later to flag cases where a 64-bit constant
  46  * is wrongly defined in a 32-bit DSDT/SSDT.
  47  *
  48  * In ACPI, the only place where octal numbers are supported is within
  49  * the ASL language itself. This is implemented via the main acpi_ut_strtoul64
  50  * interface. According the ACPI specification, there is no ACPI runtime
  51  * support (explicit/implicit) for octal string conversions.
  52  *
  53  ******************************************************************************/
  54 /*******************************************************************************
  55  *
  56  * FUNCTION:    acpi_ut_strtoul64
  57  *
  58  * PARAMETERS:  string                  - Null terminated input string,
  59  *                                        must be a valid pointer
  60  *              return_value            - Where the converted integer is
  61  *                                        returned. Must be a valid pointer
  62  *
  63  * RETURN:      Status and converted integer. Returns an exception on a
  64  *              64-bit numeric overflow
  65  *
  66  * DESCRIPTION: Convert a string into an unsigned integer. Always performs a
  67  *              full 64-bit conversion, regardless of the current global
  68  *              integer width. Supports Decimal, Hex, and Octal strings.
  69  *
  70  * Current users of this function:
  71  *
  72  *  iASL        - Preprocessor (constants and math expressions)
  73  *  iASL        - Main ASL parser, conversion of ASL constants to integers
  74  *  iASL        - Data Table Compiler parser (constants and math expressions)
  75  *  interpreter - Repair code for return values from predefined names
  76  *  acpi_dump   - ACPI table physical addresses
  77  *  acpi_exec   - Support for namespace overrides
  78  *
  79  ******************************************************************************/
  80 acpi_status acpi_ut_strtoul64(char *string, u64 *return_value)
  81 {
  82         acpi_status status = AE_OK;
  83         u8 original_bit_width;
  84         u32 base = 10;          /* Default is decimal */
  85
  86         ACPI_FUNCTION_TRACE_STR(ut_strtoul64, string);
  87
  88         *return_value = 0;
  89
  90         /* A NULL return string returns a value of zero */
  91
  92         if (*string == 0) {
  93                 return_ACPI_STATUS(AE_OK);
  94         }
  95
  96         if (!acpi_ut_remove_whitespace(&string)) {
  97                 return_ACPI_STATUS(AE_OK);
  98         }
  99
 100         /*
 101          * 1) Check for a hex constant. A "0x" prefix indicates base 16.
 102          */
 103         if (acpi_ut_detect_hex_prefix(&string)) {
 104                 base = 16;
 105         }
 106
 107         /*
 108          * 2) Check for an octal constant, defined to be a leading zero
 109          * followed by sequence of octal digits (0-7)
 110          */
 111         else if (acpi_ut_detect_octal_prefix(&string)) {
 112                 base = 8;
 113         }
 114
 115         if (!acpi_ut_remove_leading_zeros(&string)) {
 116                 return_ACPI_STATUS(AE_OK);      /* Return value 0 */
 117         }
 118
 119         /*
 120          * Force a full 64-bit conversion. The caller (usually iASL) must
 121          * check for a 32-bit overflow later as necessary (If current mode
 122          * is 32-bit, meaning a 32-bit DSDT).
 123          */
 124         original_bit_width = acpi_gbl_integer_bit_width;
 125         acpi_gbl_integer_bit_width = 64;
 126
 127         /*
 128          * Perform the base 8, 10, or 16 conversion. A 64-bit numeric overflow
 129          * will return an exception (to allow iASL to flag the statement).
 130          */
 131         switch (base) {
 132         case 8:
 133                 status = acpi_ut_convert_octal_string(string, return_value);
 134                 break;
 135
 136         case 10:
 137                 status = acpi_ut_convert_decimal_string(string, return_value);
 138                 break;
 139
 140         case 16:
 141         default:
 142                 status = acpi_ut_convert_hex_string(string, return_value);
 143                 break;
 144         }
 145
 146         /* Only possible exception from above is a 64-bit overflow */
 147
 148         acpi_gbl_integer_bit_width = original_bit_width;
 149         return_ACPI_STATUS(status);
 150 }
 151
 152 /*******************************************************************************
 153  *
 154  * FUNCTION:    acpi_ut_implicit_strtoul64
 155  *
 156  * PARAMETERS:  string                  - Null terminated input string,
 157  *                                        must be a valid pointer
 158  *
 159  * RETURN:      Converted integer
 160  *
 161  * DESCRIPTION: Perform a 64-bit conversion with restrictions placed upon
 162  *              an "implicit conversion" by the ACPI specification. Used by
 163  *              many ASL operators that require an integer operand, and support
 164  *              an automatic (implicit) conversion from a string operand
 165  *              to the final integer operand. The major restriction is that
 166  *              only hex strings are supported.
 167  *
 168  * -----------------------------------------------------------------------------
 169  *
 170  * Base is always 16, either with or without the 0x prefix. Decimal and
 171  * Octal strings are not supported, as per the ACPI specification.
 172  *
 173  * Examples (both are hex values):
 174  *      Add ("BA98", Arg0, Local0)
 175  *      Subtract ("0x12345678", Arg1, Local1)
 176  *
 177  * Conversion rules as extracted from the ACPI specification:
 178  *
 179  *  The converted integer is initialized to the value zero.
 180  *  The ASCII string is always interpreted as a hexadecimal constant.
 181  *
 182  *  1)  According to the ACPI specification, a "0x" prefix is not allowed.
 183  *      However, ACPICA allows this as an ACPI extension on general
 184  *      principle. (NO ERROR)
 185  *
 186  *  2)  The conversion terminates when the size of an integer is reached
 187  *      (32 or 64 bits). There are no numeric overflow conditions. (NO ERROR)
 188  *
 189  *  3)  The first non-hex character terminates the conversion and returns
 190  *      the current accumulated value of the converted integer (NO ERROR).
 191  *
 192  *  4)  Conversion of a null (zero-length) string to an integer is
 193  *      technically not allowed. However, ACPICA allows this as an ACPI
 194  *      extension. The conversion returns the value 0. (NO ERROR)
 195  *
 196  * NOTE: There are no error conditions returned by this function. At
 197  * the minimum, a value of zero is returned.
 198  *
 199  * Current users of this function:
 200  *
 201  *  interpreter - All runtime implicit conversions, as per ACPI specification
 202  *  iASL        - Data Table Compiler parser (constants and math expressions)
 203  *
 204  ******************************************************************************/
 205
 206 u64 acpi_ut_implicit_strtoul64(char *string)
 207 {
 208         u64 converted_integer = 0;
 209
 210         ACPI_FUNCTION_TRACE_STR(ut_implicit_strtoul64, string);
 211
 212         if (!acpi_ut_remove_whitespace(&string)) {
 213                 return_VALUE(0);
 214         }
 215
 216         /*
 217          * Per the ACPI specification, only hexadecimal is supported for
 218          * implicit conversions, and the "0x" prefix is "not allowed".
 219          * However, allow a "0x" prefix as an ACPI extension.
 220          */
 221         acpi_ut_remove_hex_prefix(&string);
 222
 223         if (!acpi_ut_remove_leading_zeros(&string)) {
 224                 return_VALUE(0);
 225         }
 226
 227         /*
 228          * Ignore overflow as per the ACPI specification. This is implemented by
 229          * ignoring the return status from the conversion function called below.
 230          * On overflow, the input string is simply truncated.
 231          */
 232         acpi_ut_convert_hex_string(string, &converted_integer);
 233         return_VALUE(converted_integer);
 234 }
 235
 236 /*******************************************************************************
 237  *
 238  * FUNCTION:    acpi_ut_explicit_strtoul64
 239  *
 240  * PARAMETERS:  string                  - Null terminated input string,
 241  *                                        must be a valid pointer
 242  *
 243  * RETURN:      Converted integer
 244  *
 245  * DESCRIPTION: Perform a 64-bit conversion with the restrictions placed upon
 246  *              an "explicit conversion" by the ACPI specification. The
 247  *              main restriction is that only hex and decimal are supported.
 248  *
 249  * -----------------------------------------------------------------------------
 250  *
 251  * Base is either 10 (default) or 16 (with 0x prefix). Octal (base 8) strings
 252  * are not supported, as per the ACPI specification.
 253  *
 254  * Examples:
 255  *      to_integer ("1000")     Decimal
 256  *      to_integer ("0xABCD")   Hex
 257  *
 258  * Conversion rules as extracted from the ACPI specification:
 259  *
 260  *  1)  The input string is either a decimal or hexadecimal numeric string.
 261  *      A hex value must be prefixed by "0x" or it is interpreted as decimal.
 262  *
 263  *  2)  The value must not exceed the maximum of an integer value
 264  *      (32 or 64 bits). The ACPI specification states the behavior is
 265  *      "unpredictable", so ACPICA matches the behavior of the implicit
 266  *      conversion case. There are no numeric overflow conditions. (NO ERROR)
 267  *
 268  *  3)  Behavior on the first non-hex character is not defined by the ACPI
 269  *      specification (for the to_integer operator), so ACPICA matches the
 270  *      behavior of the implicit conversion case. It terminates the
 271  *      conversion and returns the current accumulated value of the converted
 272  *      integer. (NO ERROR)
 273  *
 274  *  4)  Conversion of a null (zero-length) string to an integer is
 275  *      technically not allowed. However, ACPICA allows this as an ACPI
 276  *      extension. The conversion returns the value 0. (NO ERROR)
 277  *
 278  * NOTE: There are no error conditions returned by this function. At the
 279  * minimum, a value of zero is returned.
 280  *
 281  * Current users of this function:
 282  *
 283  *  interpreter - Runtime ASL to_integer operator, as per the ACPI specification
 284  *
 285  ******************************************************************************/
 286
 287 u64 acpi_ut_explicit_strtoul64(char *string)
 288 {
 289         u64 converted_integer = 0;
 290         u32 base = 10;          /* Default is decimal */
 291
 292         ACPI_FUNCTION_TRACE_STR(ut_explicit_strtoul64, string);
 293
 294         if (!acpi_ut_remove_whitespace(&string)) {
 295                 return_VALUE(0);
 296         }
 297
 298         /*
 299          * Only Hex and Decimal are supported, as per the ACPI specification.
 300          * A "0x" prefix indicates hex; otherwise decimal is assumed.
 301          */
 302         if (acpi_ut_detect_hex_prefix(&string)) {
 303                 base = 16;
 304         }
 305
 306         if (!acpi_ut_remove_leading_zeros(&string)) {
 307                 return_VALUE(0);
 308         }
 309
 310         /*
 311          * Ignore overflow as per the ACPI specification. This is implemented by
 312          * ignoring the return status from the conversion functions called below.
 313          * On overflow, the input string is simply truncated.
 314          */
 315         switch (base) {
 316         case 10:
 317         default:
 318                 acpi_ut_convert_decimal_string(string, &converted_integer);
 319                 break;
 320
 321         case 16:
 322                 acpi_ut_convert_hex_string(string, &converted_integer);
 323                 break;
 324         }
 325
 326         return_VALUE(converted_integer);
 327 }