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
13ACPI_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 ******************************************************************************/
80acpi_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: &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: &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: &string)) {
112 base = 8;
113 }
114
115 if (!acpi_ut_remove_leading_zeros(string: &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_ptr: return_value);
138 break;
139
140 case 16:
141 default:
142 status = acpi_ut_convert_hex_string(string, return_value_ptr: 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
206u64 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: &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: &string);
222
223 if (!acpi_ut_remove_leading_zeros(string: &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, return_value_ptr: &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
287u64 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: &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: &string)) {
303 base = 16;
304 }
305
306 if (!acpi_ut_remove_leading_zeros(string: &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, return_value_ptr: &converted_integer);
319 break;
320
321 case 16:
322 acpi_ut_convert_hex_string(string, return_value_ptr: &converted_integer);
323 break;
324 }
325
326 return_VALUE(converted_integer);
327}
328