195857638SErik Schmauss // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0
25ebd2eaaSBob Moore /*******************************************************************************
35ebd2eaaSBob Moore *
472a29355SBob Moore * Module Name: utstrtoul64 - String-to-integer conversion support for both
572a29355SBob Moore * 64-bit and 32-bit integers
65ebd2eaaSBob Moore *
75ebd2eaaSBob Moore ******************************************************************************/
85ebd2eaaSBob Moore
95ebd2eaaSBob Moore #include <acpi/acpi.h>
105ebd2eaaSBob Moore #include "accommon.h"
115ebd2eaaSBob Moore
125ebd2eaaSBob Moore #define _COMPONENT ACPI_UTILITIES
135ebd2eaaSBob Moore ACPI_MODULE_NAME("utstrtoul64")
145ebd2eaaSBob Moore
155ebd2eaaSBob Moore /*******************************************************************************
165ebd2eaaSBob Moore *
1772a29355SBob Moore * This module contains the top-level string to 64/32-bit unsigned integer
18fe97d287SBob Moore * conversion functions:
195ebd2eaaSBob Moore *
2072a29355SBob Moore * 1) A standard strtoul() function that supports 64-bit integers, base
2172a29355SBob Moore * 8/10/16, with integer overflow support. This is used mainly by the
2272a29355SBob Moore * iASL compiler, which implements tighter constraints on integer
2372a29355SBob Moore * constants than the runtime (interpreter) integer-to-string conversions.
24fe97d287SBob Moore * 2) Runtime "Explicit conversion" as defined in the ACPI specification.
25fe97d287SBob Moore * 3) Runtime "Implicit conversion" as defined in the ACPI specification.
265ebd2eaaSBob Moore *
27fe97d287SBob Moore * Current users of this module:
285ebd2eaaSBob Moore *
2972a29355SBob Moore * iASL - Preprocessor (constants and math expressions)
3072a29355SBob Moore * iASL - Main parser, conversion of constants to integers
3172a29355SBob Moore * iASL - Data Table Compiler parser (constants and math expressions)
325ebd2eaaSBob Moore * interpreter - Implicit and explicit conversions, GPE method names
33c2e56e54SBob Moore * interpreter - Repair code for return values from predefined names
345ebd2eaaSBob Moore * debugger - Command line input string conversion
35c2e56e54SBob Moore * acpi_dump - ACPI table physical addresses
36c2e56e54SBob Moore * acpi_exec - Support for namespace overrides
375ebd2eaaSBob Moore *
38fe97d287SBob Moore * Notes concerning users of these interfaces:
39fe97d287SBob Moore *
40c2e56e54SBob Moore * acpi_gbl_integer_byte_width is used to set the 32/64 bit limit for explicit
41c2e56e54SBob Moore * and implicit conversions. This global must be set to the proper width.
42c2e56e54SBob Moore * For the core ACPICA code, the width depends on the DSDT version. For the
43c2e56e54SBob Moore * acpi_ut_strtoul64 interface, all conversions are 64 bits. This interface is
44c2e56e54SBob Moore * used primarily for iASL, where the default width is 64 bits for all parsers,
45c2e56e54SBob Moore * but error checking is performed later to flag cases where a 64-bit constant
46c2e56e54SBob Moore * is wrongly defined in a 32-bit DSDT/SSDT.
47fe97d287SBob Moore *
48fe97d287SBob Moore * In ACPI, the only place where octal numbers are supported is within
4972a29355SBob Moore * the ASL language itself. This is implemented via the main acpi_ut_strtoul64
5072a29355SBob Moore * interface. According the ACPI specification, there is no ACPI runtime
51c2e56e54SBob Moore * support (explicit/implicit) for octal string conversions.
525ebd2eaaSBob Moore *
535ebd2eaaSBob Moore ******************************************************************************/
54fe97d287SBob Moore /*******************************************************************************
55fe97d287SBob Moore *
56fe97d287SBob Moore * FUNCTION: acpi_ut_strtoul64
57fe97d287SBob Moore *
5872a29355SBob Moore * PARAMETERS: string - Null terminated input string,
5972a29355SBob Moore * must be a valid pointer
60fe97d287SBob Moore * return_value - Where the converted integer is
61fe97d287SBob Moore * returned. Must be a valid pointer
62fe97d287SBob Moore *
63c2e56e54SBob Moore * RETURN: Status and converted integer. Returns an exception on a
64c2e56e54SBob Moore * 64-bit numeric overflow
65fe97d287SBob Moore *
66c2e56e54SBob Moore * DESCRIPTION: Convert a string into an unsigned integer. Always performs a
67c2e56e54SBob Moore * full 64-bit conversion, regardless of the current global
68fe97d287SBob Moore * integer width. Supports Decimal, Hex, and Octal strings.
69fe97d287SBob Moore *
70fe97d287SBob Moore * Current users of this function:
71fe97d287SBob Moore *
7272a29355SBob Moore * iASL - Preprocessor (constants and math expressions)
7372a29355SBob Moore * iASL - Main ASL parser, conversion of ASL constants to integers
7472a29355SBob Moore * iASL - Data Table Compiler parser (constants and math expressions)
75c2e56e54SBob Moore * interpreter - Repair code for return values from predefined names
76c2e56e54SBob Moore * acpi_dump - ACPI table physical addresses
77c2e56e54SBob Moore * acpi_exec - Support for namespace overrides
78fe97d287SBob Moore *
79fe97d287SBob Moore ******************************************************************************/
acpi_ut_strtoul64(char * string,u64 * return_value)80fe97d287SBob Moore acpi_status acpi_ut_strtoul64(char *string, u64 *return_value)
815ebd2eaaSBob Moore {
825ebd2eaaSBob Moore acpi_status status = AE_OK;
83c2e56e54SBob Moore u8 original_bit_width;
84fe97d287SBob Moore u32 base = 10; /* Default is decimal */
855ebd2eaaSBob Moore
865ebd2eaaSBob Moore ACPI_FUNCTION_TRACE_STR(ut_strtoul64, string);
875ebd2eaaSBob Moore
885ebd2eaaSBob Moore *return_value = 0;
895ebd2eaaSBob Moore
9072a29355SBob Moore /* A NULL return string returns a value of zero */
915ebd2eaaSBob Moore
925ebd2eaaSBob Moore if (*string == 0) {
935ebd2eaaSBob Moore return_ACPI_STATUS(AE_OK);
945ebd2eaaSBob Moore }
955ebd2eaaSBob Moore
96c2e56e54SBob Moore if (!acpi_ut_remove_whitespace(&string)) {
97c2e56e54SBob Moore return_ACPI_STATUS(AE_OK);
98c2e56e54SBob Moore }
99c2e56e54SBob Moore
1005ebd2eaaSBob Moore /*
10172a29355SBob Moore * 1) Check for a hex constant. A "0x" prefix indicates base 16.
1025ebd2eaaSBob Moore */
103fe97d287SBob Moore if (acpi_ut_detect_hex_prefix(&string)) {
1045ebd2eaaSBob Moore base = 16;
1055ebd2eaaSBob Moore }
1065ebd2eaaSBob Moore
107fe97d287SBob Moore /*
108fe97d287SBob Moore * 2) Check for an octal constant, defined to be a leading zero
10972a29355SBob Moore * followed by sequence of octal digits (0-7)
110fe97d287SBob Moore */
111fe97d287SBob Moore else if (acpi_ut_detect_octal_prefix(&string)) {
112fe97d287SBob Moore base = 8;
1135ebd2eaaSBob Moore }
1145ebd2eaaSBob Moore
115fe97d287SBob Moore if (!acpi_ut_remove_leading_zeros(&string)) {
1165ebd2eaaSBob Moore return_ACPI_STATUS(AE_OK); /* Return value 0 */
1175ebd2eaaSBob Moore }
1185ebd2eaaSBob Moore
119fe97d287SBob Moore /*
120c2e56e54SBob Moore * Force a full 64-bit conversion. The caller (usually iASL) must
121c2e56e54SBob Moore * check for a 32-bit overflow later as necessary (If current mode
122c2e56e54SBob Moore * is 32-bit, meaning a 32-bit DSDT).
123c2e56e54SBob Moore */
124c2e56e54SBob Moore original_bit_width = acpi_gbl_integer_bit_width;
125c2e56e54SBob Moore acpi_gbl_integer_bit_width = 64;
126c2e56e54SBob Moore
127c2e56e54SBob Moore /*
128c2e56e54SBob Moore * Perform the base 8, 10, or 16 conversion. A 64-bit numeric overflow
129c2e56e54SBob Moore * will return an exception (to allow iASL to flag the statement).
130fe97d287SBob Moore */
131fe97d287SBob Moore switch (base) {
132fe97d287SBob Moore case 8:
133fe97d287SBob Moore status = acpi_ut_convert_octal_string(string, return_value);
134fe97d287SBob Moore break;
1355ebd2eaaSBob Moore
136fe97d287SBob Moore case 10:
137fe97d287SBob Moore status = acpi_ut_convert_decimal_string(string, return_value);
138fe97d287SBob Moore break;
139fe97d287SBob Moore
140fe97d287SBob Moore case 16:
141fe97d287SBob Moore default:
14272a29355SBob Moore status = acpi_ut_convert_hex_string(string, return_value);
143fe97d287SBob Moore break;
1445ebd2eaaSBob Moore }
1455ebd2eaaSBob Moore
146c2e56e54SBob Moore /* Only possible exception from above is a 64-bit overflow */
147c2e56e54SBob Moore
148c2e56e54SBob Moore acpi_gbl_integer_bit_width = original_bit_width;
1495ebd2eaaSBob Moore return_ACPI_STATUS(status);
1505ebd2eaaSBob Moore }
1515ebd2eaaSBob Moore
1525ebd2eaaSBob Moore /*******************************************************************************
1535ebd2eaaSBob Moore *
154fe97d287SBob Moore * FUNCTION: acpi_ut_implicit_strtoul64
1555ebd2eaaSBob Moore *
15672a29355SBob Moore * PARAMETERS: string - Null terminated input string,
15772a29355SBob Moore * must be a valid pointer
1585ebd2eaaSBob Moore *
159fe97d287SBob Moore * RETURN: Converted integer
1605ebd2eaaSBob Moore *
161fe97d287SBob Moore * DESCRIPTION: Perform a 64-bit conversion with restrictions placed upon
162fe97d287SBob Moore * an "implicit conversion" by the ACPI specification. Used by
163fe97d287SBob Moore * many ASL operators that require an integer operand, and support
164fe97d287SBob Moore * an automatic (implicit) conversion from a string operand
16572a29355SBob Moore * to the final integer operand. The major restriction is that
16672a29355SBob Moore * only hex strings are supported.
167fe97d287SBob Moore *
168fe97d287SBob Moore * -----------------------------------------------------------------------------
169fe97d287SBob Moore *
17072a29355SBob Moore * Base is always 16, either with or without the 0x prefix. Decimal and
17172a29355SBob Moore * Octal strings are not supported, as per the ACPI specification.
172fe97d287SBob Moore *
173fe97d287SBob Moore * Examples (both are hex values):
174fe97d287SBob Moore * Add ("BA98", Arg0, Local0)
175fe97d287SBob Moore * Subtract ("0x12345678", Arg1, Local1)
176fe97d287SBob Moore *
17772a29355SBob Moore * Conversion rules as extracted from the ACPI specification:
178fe97d287SBob Moore *
179fe97d287SBob Moore * The converted integer is initialized to the value zero.
18072a29355SBob Moore * The ASCII string is always interpreted as a hexadecimal constant.
181fe97d287SBob Moore *
18272a29355SBob Moore * 1) According to the ACPI specification, a "0x" prefix is not allowed.
18372a29355SBob Moore * However, ACPICA allows this as an ACPI extension on general
18472a29355SBob Moore * principle. (NO ERROR)
185fe97d287SBob Moore *
18672a29355SBob Moore * 2) The conversion terminates when the size of an integer is reached
18772a29355SBob Moore * (32 or 64 bits). There are no numeric overflow conditions. (NO ERROR)
188fe97d287SBob Moore *
189fe97d287SBob Moore * 3) The first non-hex character terminates the conversion and returns
190fe97d287SBob Moore * the current accumulated value of the converted integer (NO ERROR).
191fe97d287SBob Moore *
192fe97d287SBob Moore * 4) Conversion of a null (zero-length) string to an integer is
19372a29355SBob Moore * technically not allowed. However, ACPICA allows this as an ACPI
19472a29355SBob Moore * extension. The conversion returns the value 0. (NO ERROR)
195fe97d287SBob Moore *
19672a29355SBob Moore * NOTE: There are no error conditions returned by this function. At
197fe97d287SBob Moore * the minimum, a value of zero is returned.
198fe97d287SBob Moore *
199fe97d287SBob Moore * Current users of this function:
200fe97d287SBob Moore *
201fe97d287SBob Moore * interpreter - All runtime implicit conversions, as per ACPI specification
20272a29355SBob Moore * iASL - Data Table Compiler parser (constants and math expressions)
2035ebd2eaaSBob Moore *
2045ebd2eaaSBob Moore ******************************************************************************/
2055ebd2eaaSBob Moore
acpi_ut_implicit_strtoul64(char * string)206fe97d287SBob Moore u64 acpi_ut_implicit_strtoul64(char *string)
2075ebd2eaaSBob Moore {
208fe97d287SBob Moore u64 converted_integer = 0;
2095ebd2eaaSBob Moore
210fe97d287SBob Moore ACPI_FUNCTION_TRACE_STR(ut_implicit_strtoul64, string);
2115ebd2eaaSBob Moore
212c2e56e54SBob Moore if (!acpi_ut_remove_whitespace(&string)) {
213c2e56e54SBob Moore return_VALUE(0);
214c2e56e54SBob Moore }
215c2e56e54SBob Moore
216fe97d287SBob Moore /*
217fe97d287SBob Moore * Per the ACPI specification, only hexadecimal is supported for
218fe97d287SBob Moore * implicit conversions, and the "0x" prefix is "not allowed".
219fe97d287SBob Moore * However, allow a "0x" prefix as an ACPI extension.
220fe97d287SBob Moore */
221*089b2becSErik Schmauss acpi_ut_remove_hex_prefix(&string);
2225ebd2eaaSBob Moore
223fe97d287SBob Moore if (!acpi_ut_remove_leading_zeros(&string)) {
224fe97d287SBob Moore return_VALUE(0);
2255ebd2eaaSBob Moore }
2265ebd2eaaSBob Moore
227fe97d287SBob Moore /*
228fe97d287SBob Moore * Ignore overflow as per the ACPI specification. This is implemented by
229c2e56e54SBob Moore * ignoring the return status from the conversion function called below.
230c2e56e54SBob Moore * On overflow, the input string is simply truncated.
231fe97d287SBob Moore */
232fe97d287SBob Moore acpi_ut_convert_hex_string(string, &converted_integer);
233fe97d287SBob Moore return_VALUE(converted_integer);
2345ebd2eaaSBob Moore }
2355ebd2eaaSBob Moore
2365ebd2eaaSBob Moore /*******************************************************************************
2375ebd2eaaSBob Moore *
238fe97d287SBob Moore * FUNCTION: acpi_ut_explicit_strtoul64
2395ebd2eaaSBob Moore *
24072a29355SBob Moore * PARAMETERS: string - Null terminated input string,
24172a29355SBob Moore * must be a valid pointer
2425ebd2eaaSBob Moore *
243fe97d287SBob Moore * RETURN: Converted integer
2445ebd2eaaSBob Moore *
245fe97d287SBob Moore * DESCRIPTION: Perform a 64-bit conversion with the restrictions placed upon
246fe97d287SBob Moore * an "explicit conversion" by the ACPI specification. The
247fe97d287SBob Moore * main restriction is that only hex and decimal are supported.
248fe97d287SBob Moore *
249fe97d287SBob Moore * -----------------------------------------------------------------------------
250fe97d287SBob Moore *
25172a29355SBob Moore * Base is either 10 (default) or 16 (with 0x prefix). Octal (base 8) strings
25272a29355SBob Moore * are not supported, as per the ACPI specification.
253fe97d287SBob Moore *
254fe97d287SBob Moore * Examples:
255fe97d287SBob Moore * to_integer ("1000") Decimal
256fe97d287SBob Moore * to_integer ("0xABCD") Hex
257fe97d287SBob Moore *
25872a29355SBob Moore * Conversion rules as extracted from the ACPI specification:
259fe97d287SBob Moore *
26072a29355SBob Moore * 1) The input string is either a decimal or hexadecimal numeric string.
261fe97d287SBob Moore * A hex value must be prefixed by "0x" or it is interpreted as decimal.
262fe97d287SBob Moore *
263fe97d287SBob Moore * 2) The value must not exceed the maximum of an integer value
264fe97d287SBob Moore * (32 or 64 bits). The ACPI specification states the behavior is
265fe97d287SBob Moore * "unpredictable", so ACPICA matches the behavior of the implicit
266fe97d287SBob Moore * conversion case. There are no numeric overflow conditions. (NO ERROR)
267fe97d287SBob Moore *
26872a29355SBob Moore * 3) Behavior on the first non-hex character is not defined by the ACPI
269fe97d287SBob Moore * specification (for the to_integer operator), so ACPICA matches the
270fe97d287SBob Moore * behavior of the implicit conversion case. It terminates the
271fe97d287SBob Moore * conversion and returns the current accumulated value of the converted
272fe97d287SBob Moore * integer. (NO ERROR)
273fe97d287SBob Moore *
274fe97d287SBob Moore * 4) Conversion of a null (zero-length) string to an integer is
27572a29355SBob Moore * technically not allowed. However, ACPICA allows this as an ACPI
27672a29355SBob Moore * extension. The conversion returns the value 0. (NO ERROR)
277fe97d287SBob Moore *
27872a29355SBob Moore * NOTE: There are no error conditions returned by this function. At the
27972a29355SBob Moore * minimum, a value of zero is returned.
280fe97d287SBob Moore *
281fe97d287SBob Moore * Current users of this function:
282fe97d287SBob Moore *
283fe97d287SBob Moore * interpreter - Runtime ASL to_integer operator, as per the ACPI specification
2845ebd2eaaSBob Moore *
2855ebd2eaaSBob Moore ******************************************************************************/
2865ebd2eaaSBob Moore
acpi_ut_explicit_strtoul64(char * string)287fe97d287SBob Moore u64 acpi_ut_explicit_strtoul64(char *string)
2885ebd2eaaSBob Moore {
289fe97d287SBob Moore u64 converted_integer = 0;
290fe97d287SBob Moore u32 base = 10; /* Default is decimal */
2915ebd2eaaSBob Moore
292fe97d287SBob Moore ACPI_FUNCTION_TRACE_STR(ut_explicit_strtoul64, string);
2935ebd2eaaSBob Moore
294c2e56e54SBob Moore if (!acpi_ut_remove_whitespace(&string)) {
295c2e56e54SBob Moore return_VALUE(0);
296c2e56e54SBob Moore }
297c2e56e54SBob Moore
298fe97d287SBob Moore /*
299fe97d287SBob Moore * Only Hex and Decimal are supported, as per the ACPI specification.
30072a29355SBob Moore * A "0x" prefix indicates hex; otherwise decimal is assumed.
301fe97d287SBob Moore */
302fe97d287SBob Moore if (acpi_ut_detect_hex_prefix(&string)) {
303fe97d287SBob Moore base = 16;
3045ebd2eaaSBob Moore }
3055ebd2eaaSBob Moore
306fe97d287SBob Moore if (!acpi_ut_remove_leading_zeros(&string)) {
307fe97d287SBob Moore return_VALUE(0);
3085ebd2eaaSBob Moore }
3095ebd2eaaSBob Moore
310fe97d287SBob Moore /*
311fe97d287SBob Moore * Ignore overflow as per the ACPI specification. This is implemented by
312c2e56e54SBob Moore * ignoring the return status from the conversion functions called below.
313c2e56e54SBob Moore * On overflow, the input string is simply truncated.
314fe97d287SBob Moore */
315fe97d287SBob Moore switch (base) {
316fe97d287SBob Moore case 10:
317fe97d287SBob Moore default:
318fe97d287SBob Moore acpi_ut_convert_decimal_string(string, &converted_integer);
319fe97d287SBob Moore break;
3205ebd2eaaSBob Moore
321fe97d287SBob Moore case 16:
322fe97d287SBob Moore acpi_ut_convert_hex_string(string, &converted_integer);
323fe97d287SBob Moore break;
3245ebd2eaaSBob Moore }
3255ebd2eaaSBob Moore
326fe97d287SBob Moore return_VALUE(converted_integer);
3275ebd2eaaSBob Moore }
328