ReactOS  0.4.14-dev-1115-gebeeb9d
utstrtoul64.c
Go to the documentation of this file.
1 /*******************************************************************************
2  *
3  * Module Name: utstrtoul64 - String-to-integer conversion support for both
4  * 64-bit and 32-bit integers
5  *
6  ******************************************************************************/
7 
8 /*
9  * Copyright (C) 2000 - 2020, Intel Corp.
10  * All rights reserved.
11  *
12  * Redistribution and use in source and binary forms, with or without
13  * modification, are permitted provided that the following conditions
14  * are met:
15  * 1. Redistributions of source code must retain the above copyright
16  * notice, this list of conditions, and the following disclaimer,
17  * without modification.
18  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
19  * substantially similar to the "NO WARRANTY" disclaimer below
20  * ("Disclaimer") and any redistribution must be conditioned upon
21  * including a substantially similar Disclaimer requirement for further
22  * binary redistribution.
23  * 3. Neither the names of the above-listed copyright holders nor the names
24  * of any contributors may be used to endorse or promote products derived
25  * from this software without specific prior written permission.
26  *
27  * Alternatively, this software may be distributed under the terms of the
28  * GNU General Public License ("GPL") version 2 as published by the Free
29  * Software Foundation.
30  *
31  * NO WARRANTY
32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
33  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
35  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
36  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
37  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
38  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
39  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
40  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
41  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
42  * POSSIBILITY OF SUCH DAMAGES.
43  */
44 
45 #include "acpi.h"
46 #include "accommon.h"
47 
48 #define _COMPONENT ACPI_UTILITIES
49  ACPI_MODULE_NAME ("utstrtoul64")
50 
51 
52 /*******************************************************************************
53  *
54  * This module contains the top-level string to 64/32-bit unsigned integer
55  * conversion functions:
56  *
57  * 1) A standard strtoul() function that supports 64-bit integers, base
58  * 8/10/16, with integer overflow support. This is used mainly by the
59  * iASL compiler, which implements tighter constraints on integer
60  * constants than the runtime (interpreter) integer-to-string conversions.
61  * 2) Runtime "Explicit conversion" as defined in the ACPI specification.
62  * 3) Runtime "Implicit conversion" as defined in the ACPI specification.
63  *
64  * Current users of this module:
65  *
66  * iASL - Preprocessor (constants and math expressions)
67  * iASL - Main parser, conversion of constants to integers
68  * iASL - Data Table Compiler parser (constants and math expressions)
69  * Interpreter - Implicit and explicit conversions, GPE method names
70  * Interpreter - Repair code for return values from predefined names
71  * Debugger - Command line input string conversion
72  * AcpiDump - ACPI table physical addresses
73  * AcpiExec - Support for namespace overrides
74  *
75  * Notes concerning users of these interfaces:
76  *
77  * AcpiGbl_IntegerByteWidth is used to set the 32/64 bit limit for explicit
78  * and implicit conversions. This global must be set to the proper width.
79  * For the core ACPICA code, the width depends on the DSDT version. For the
80  * AcpiUtStrtoul64 interface, all conversions are 64 bits. This interface is
81  * used primarily for iASL, where the default width is 64 bits for all parsers,
82  * but error checking is performed later to flag cases where a 64-bit constant
83  * is wrongly defined in a 32-bit DSDT/SSDT.
84  *
85  * In ACPI, the only place where octal numbers are supported is within
86  * the ASL language itself. This is implemented via the main AcpiUtStrtoul64
87  * interface. According the ACPI specification, there is no ACPI runtime
88  * support (explicit/implicit) for octal string conversions.
89  *
90  ******************************************************************************/
91 
92 
93 /*******************************************************************************
94  *
95  * FUNCTION: AcpiUtStrtoul64
96  *
97  * PARAMETERS: String - Null terminated input string,
98  * must be a valid pointer
99  * ReturnValue - Where the converted integer is
100  * returned. Must be a valid pointer
101  *
102  * RETURN: Status and converted integer. Returns an exception on a
103  * 64-bit numeric overflow
104  *
105  * DESCRIPTION: Convert a string into an unsigned integer. Always performs a
106  * full 64-bit conversion, regardless of the current global
107  * integer width. Supports Decimal, Hex, and Octal strings.
108  *
109  * Current users of this function:
110  *
111  * iASL - Preprocessor (constants and math expressions)
112  * iASL - Main ASL parser, conversion of ASL constants to integers
113  * iASL - Data Table Compiler parser (constants and math expressions)
114  * Interpreter - Repair code for return values from predefined names
115  * AcpiDump - ACPI table physical addresses
116  * AcpiExec - Support for namespace overrides
117  *
118  ******************************************************************************/
119 
122  char *String,
124 {
126  UINT8 OriginalBitWidth;
127  UINT32 Base = 10; /* Default is decimal */
128 
129 
130  ACPI_FUNCTION_TRACE_STR (UtStrtoul64, String);
131 
132 
133  *ReturnValue = 0;
134 
135  /* A NULL return string returns a value of zero */
136 
137  if (*String == 0)
138  {
140  }
141 
143  {
145  }
146 
147  /*
148  * 1) Check for a hex constant. A "0x" prefix indicates base 16.
149  */
151  {
152  Base = 16;
153  }
154 
155  /*
156  * 2) Check for an octal constant, defined to be a leading zero
157  * followed by sequence of octal digits (0-7)
158  */
159  else if (AcpiUtDetectOctalPrefix (&String))
160  {
161  Base = 8;
162  }
163 
165  {
166  return_ACPI_STATUS (AE_OK); /* Return value 0 */
167  }
168 
169  /*
170  * Force a full 64-bit conversion. The caller (usually iASL) must
171  * check for a 32-bit overflow later as necessary (If current mode
172  * is 32-bit, meaning a 32-bit DSDT).
173  */
174  OriginalBitWidth = AcpiGbl_IntegerBitWidth;
175  AcpiGbl_IntegerBitWidth = 64;
176 
177  /*
178  * Perform the base 8, 10, or 16 conversion. A 64-bit numeric overflow
179  * will return an exception (to allow iASL to flag the statement).
180  */
181  switch (Base)
182  {
183  case 8:
185  break;
186 
187  case 10:
189  break;
190 
191  case 16:
192  default:
194  break;
195  }
196 
197  /* Only possible exception from above is a 64-bit overflow */
198 
199  AcpiGbl_IntegerBitWidth = OriginalBitWidth;
201 }
202 
203 
204 /*******************************************************************************
205  *
206  * FUNCTION: AcpiUtImplicitStrtoul64
207  *
208  * PARAMETERS: String - Null terminated input string,
209  * must be a valid pointer
210  *
211  * RETURN: Converted integer
212  *
213  * DESCRIPTION: Perform a 64-bit conversion with restrictions placed upon
214  * an "implicit conversion" by the ACPI specification. Used by
215  * many ASL operators that require an integer operand, and support
216  * an automatic (implicit) conversion from a string operand
217  * to the final integer operand. The major restriction is that
218  * only hex strings are supported.
219  *
220  * -----------------------------------------------------------------------------
221  *
222  * Base is always 16, either with or without the 0x prefix. Decimal and
223  * Octal strings are not supported, as per the ACPI specification.
224  *
225  * Examples (both are hex values):
226  * Add ("BA98", Arg0, Local0)
227  * Subtract ("0x12345678", Arg1, Local1)
228  *
229  * Conversion rules as extracted from the ACPI specification:
230  *
231  * The converted integer is initialized to the value zero.
232  * The ASCII string is always interpreted as a hexadecimal constant.
233  *
234  * 1) According to the ACPI specification, a "0x" prefix is not allowed.
235  * However, ACPICA allows this as an ACPI extension on general
236  * principle. (NO ERROR)
237  *
238  * 2) The conversion terminates when the size of an integer is reached
239  * (32 or 64 bits). There are no numeric overflow conditions. (NO ERROR)
240  *
241  * 3) The first non-hex character terminates the conversion and returns
242  * the current accumulated value of the converted integer (NO ERROR).
243  *
244  * 4) Conversion of a null (zero-length) string to an integer is
245  * technically not allowed. However, ACPICA allows this as an ACPI
246  * extension. The conversion returns the value 0. (NO ERROR)
247  *
248  * NOTE: There are no error conditions returned by this function. At
249  * the minimum, a value of zero is returned.
250  *
251  * Current users of this function:
252  *
253  * Interpreter - All runtime implicit conversions, as per ACPI specification
254  * iASL - Data Table Compiler parser (constants and math expressions)
255  *
256  ******************************************************************************/
257 
258 UINT64
260  char *String)
261 {
262  UINT64 ConvertedInteger = 0;
263 
264 
265  ACPI_FUNCTION_TRACE_STR (UtImplicitStrtoul64, String);
266 
267 
269  {
270  return_VALUE (0);
271  }
272 
273  /*
274  * Per the ACPI specification, only hexadecimal is supported for
275  * implicit conversions, and the "0x" prefix is "not allowed".
276  * However, allow a "0x" prefix as an ACPI extension.
277  */
279 
281  {
282  return_VALUE (0);
283  }
284 
285  /*
286  * Ignore overflow as per the ACPI specification. This is implemented by
287  * ignoring the return status from the conversion function called below.
288  * On overflow, the input string is simply truncated.
289  */
290  AcpiUtConvertHexString (String, &ConvertedInteger);
291  return_VALUE (ConvertedInteger);
292 }
293 
294 
295 /*******************************************************************************
296  *
297  * FUNCTION: AcpiUtExplicitStrtoul64
298  *
299  * PARAMETERS: String - Null terminated input string,
300  * must be a valid pointer
301  *
302  * RETURN: Converted integer
303  *
304  * DESCRIPTION: Perform a 64-bit conversion with the restrictions placed upon
305  * an "explicit conversion" by the ACPI specification. The
306  * main restriction is that only hex and decimal are supported.
307  *
308  * -----------------------------------------------------------------------------
309  *
310  * Base is either 10 (default) or 16 (with 0x prefix). Octal (base 8) strings
311  * are not supported, as per the ACPI specification.
312  *
313  * Examples:
314  * ToInteger ("1000") Decimal
315  * ToInteger ("0xABCD") Hex
316  *
317  * Conversion rules as extracted from the ACPI specification:
318  *
319  * 1) The input string is either a decimal or hexadecimal numeric string.
320  * A hex value must be prefixed by "0x" or it is interpreted as decimal.
321  *
322  * 2) The value must not exceed the maximum of an integer value
323  * (32 or 64 bits). The ACPI specification states the behavior is
324  * "unpredictable", so ACPICA matches the behavior of the implicit
325  * conversion case. There are no numeric overflow conditions. (NO ERROR)
326  *
327  * 3) Behavior on the first non-hex character is not defined by the ACPI
328  * specification (for the ToInteger operator), so ACPICA matches the
329  * behavior of the implicit conversion case. It terminates the
330  * conversion and returns the current accumulated value of the converted
331  * integer. (NO ERROR)
332  *
333  * 4) Conversion of a null (zero-length) string to an integer is
334  * technically not allowed. However, ACPICA allows this as an ACPI
335  * extension. The conversion returns the value 0. (NO ERROR)
336  *
337  * NOTE: There are no error conditions returned by this function. At the
338  * minimum, a value of zero is returned.
339  *
340  * Current users of this function:
341  *
342  * Interpreter - Runtime ASL ToInteger operator, as per the ACPI specification
343  *
344  ******************************************************************************/
345 
346 UINT64
348  char *String)
349 {
350  UINT64 ConvertedInteger = 0;
351  UINT32 Base = 10; /* Default is decimal */
352 
353 
354  ACPI_FUNCTION_TRACE_STR (UtExplicitStrtoul64, String);
355 
356 
358  {
359  return_VALUE (0);
360  }
361 
362  /*
363  * Only Hex and Decimal are supported, as per the ACPI specification.
364  * A "0x" prefix indicates hex; otherwise decimal is assumed.
365  */
367  {
368  Base = 16;
369  }
370 
372  {
373  return_VALUE (0);
374  }
375 
376  /*
377  * Ignore overflow as per the ACPI specification. This is implemented by
378  * ignoring the return status from the conversion functions called below.
379  * On overflow, the input string is simply truncated.
380  */
381  switch (Base)
382  {
383  case 10:
384  default:
385  AcpiUtConvertDecimalString (String, &ConvertedInteger);
386  break;
387 
388  case 16:
389  AcpiUtConvertHexString (String, &ConvertedInteger);
390  break;
391  }
392 
393  return_VALUE (ConvertedInteger);
394 }
#define return_VALUE(s)
Definition: acoutput.h:499
_In_opt_ ULONG Base
Definition: rtlfuncs.h:2374
static WCHAR String[]
Definition: stringtable.c:55
UINT32 ACPI_STATUS
Definition: actypes.h:460
UINT64 AcpiUtImplicitStrtoul64(char *String)
Definition: utstrtoul64.c:259
ACPI_STATUS AcpiUtConvertOctalString(char *String, UINT64 *ReturnValue)
Definition: utstrsuppt.c:90
UINT32 void void ** ReturnValue
Definition: acevents.h:214
unsigned int UINT32
#define ACPI_MODULE_NAME(Name)
Definition: acoutput.h:216
ACPI_STATUS AcpiUtConvertHexString(char *String, UINT64 *ReturnValuePtr)
Definition: utstrsuppt.c:202
UINT64 AcpiUtExplicitStrtoul64(char *String)
Definition: utstrtoul64.c:347
ACPI_STATUS AcpiUtConvertDecimalString(char *String, UINT64 *ReturnValuePtr)
Definition: utstrsuppt.c:146
char AcpiUtRemoveLeadingZeros(char **String)
Definition: utstrsuppt.c:256
void AcpiUtRemoveHexPrefix(char **String)
Definition: utstrsuppt.c:339
Status
Definition: gdiplustypes.h:24
BOOLEAN AcpiUtDetectOctalPrefix(char **String)
Definition: utstrsuppt.c:364
char AcpiUtRemoveWhitespace(char **String)
Definition: utstrsuppt.c:285
#define return_ACPI_STATUS(s)
Definition: acoutput.h:496
#define ACPI_FUNCTION_TRACE_STR(a, b)
Definition: acoutput.h:483
ACPI_STATUS AcpiUtStrtoul64(char *String, UINT64 *ReturnValue)
Definition: utstrtoul64.c:121
BOOLEAN AcpiUtDetectHexPrefix(char **String)
Definition: utstrsuppt.c:311
unsigned long long UINT64
unsigned char UINT8
#define AE_OK
Definition: acexcep.h:97