1 /*******************************************************************************
3 * Module Name: utmisc - common utility procedures
5 ******************************************************************************/
8 * Copyright (C) 2000 - 2005, R. Byron Moore
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions, and the following disclaimer,
16 * without modification.
17 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
18 * substantially similar to the "NO WARRANTY" disclaimer below
19 * ("Disclaimer") and any redistribution must be conditioned upon
20 * including a substantially similar Disclaimer requirement for further
21 * binary redistribution.
22 * 3. Neither the names of the above-listed copyright holders nor the names
23 * of any contributors may be used to endorse or promote products derived
24 * from this software without specific prior written permission.
26 * Alternatively, this software may be distributed under the terms of the
27 * GNU General Public License ("GPL") version 2 as published by the Free
28 * Software Foundation.
31 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
34 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
37 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
38 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
40 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
41 * POSSIBILITY OF SUCH DAMAGES.
45 #include <acpi/acpi.h>
46 #include <acpi/acnamesp.h>
49 #define _COMPONENT ACPI_UTILITIES
50 ACPI_MODULE_NAME ("utmisc")
53 /*******************************************************************************
55 * FUNCTION: acpi_ut_strupr (strupr)
57 * PARAMETERS: src_string - The source string to convert
59 * RETURN: Converted src_string (same as input pointer)
61 * DESCRIPTION: Convert string to uppercase
63 * NOTE: This is not a POSIX function, so it appears here, not in utclib.c
65 ******************************************************************************/
74 ACPI_FUNCTION_ENTRY ();
81 /* Walk entire string, uppercasing the letters */
83 for (string = src_string; *string; string++) {
84 *string = (char) ACPI_TOUPPER (*string);
91 /*******************************************************************************
93 * FUNCTION: acpi_ut_print_string
95 * PARAMETERS: String - Null terminated ASCII string
96 * max_length - Maximum output length
100 * DESCRIPTION: Dump an ASCII string with support for ACPI-defined escape
103 ******************************************************************************/
106 acpi_ut_print_string (
114 acpi_os_printf ("<\"NULL STRING PTR\">");
118 acpi_os_printf ("\"");
119 for (i = 0; string[i] && (i < max_length); i++) {
120 /* Escape sequences */
124 acpi_os_printf ("\\a"); /* BELL */
128 acpi_os_printf ("\\b"); /* BACKSPACE */
132 acpi_os_printf ("\\f"); /* FORMFEED */
136 acpi_os_printf ("\\n"); /* LINEFEED */
140 acpi_os_printf ("\\r"); /* CARRIAGE RETURN*/
144 acpi_os_printf ("\\t"); /* HORIZONTAL TAB */
148 acpi_os_printf ("\\v"); /* VERTICAL TAB */
151 case '\'': /* Single Quote */
152 case '\"': /* Double Quote */
153 case '\\': /* Backslash */
154 acpi_os_printf ("\\%c", (int) string[i]);
159 /* Check for printable character or hex escape */
161 if (ACPI_IS_PRINT (string[i]))
163 /* This is a normal character */
165 acpi_os_printf ("%c", (int) string[i]);
169 /* All others will be Hex escapes */
171 acpi_os_printf ("\\x%2.2X", (s32) string[i]);
176 acpi_os_printf ("\"");
178 if (i == max_length && string[i]) {
179 acpi_os_printf ("...");
184 /*******************************************************************************
186 * FUNCTION: acpi_ut_dword_byte_swap
188 * PARAMETERS: Value - Value to be converted
190 * RETURN: u32 integer with bytes swapped
192 * DESCRIPTION: Convert a 32-bit value to big-endian (swap the bytes)
194 ******************************************************************************/
197 acpi_ut_dword_byte_swap (
210 ACPI_FUNCTION_ENTRY ();
215 out.bytes[0] = in.bytes[3];
216 out.bytes[1] = in.bytes[2];
217 out.bytes[2] = in.bytes[1];
218 out.bytes[3] = in.bytes[0];
224 /*******************************************************************************
226 * FUNCTION: acpi_ut_set_integer_width
228 * PARAMETERS: Revision From DSDT header
232 * DESCRIPTION: Set the global integer bit width based upon the revision
233 * of the DSDT. For Revision 1 and 0, Integers are 32 bits.
234 * For Revision 2 and above, Integers are 64 bits. Yes, this
235 * makes a difference.
237 ******************************************************************************/
240 acpi_ut_set_integer_width (
245 acpi_gbl_integer_bit_width = 32;
246 acpi_gbl_integer_nybble_width = 8;
247 acpi_gbl_integer_byte_width = 4;
250 acpi_gbl_integer_bit_width = 64;
251 acpi_gbl_integer_nybble_width = 16;
252 acpi_gbl_integer_byte_width = 8;
257 #ifdef ACPI_DEBUG_OUTPUT
258 /*******************************************************************************
260 * FUNCTION: acpi_ut_display_init_pathname
262 * PARAMETERS: Type - Object type of the node
263 * obj_handle - Handle whose pathname will be displayed
264 * Path - Additional path string to be appended.
265 * (NULL if no extra path)
267 * RETURN: acpi_status
269 * DESCRIPTION: Display full pathname of an object, DEBUG ONLY
271 ******************************************************************************/
274 acpi_ut_display_init_pathname (
276 struct acpi_namespace_node *obj_handle,
280 struct acpi_buffer buffer;
283 ACPI_FUNCTION_ENTRY ();
286 /* Only print the path if the appropriate debug level is enabled */
288 if (!(acpi_dbg_level & ACPI_LV_INIT_NAMES)) {
292 /* Get the full pathname to the node */
294 buffer.length = ACPI_ALLOCATE_LOCAL_BUFFER;
295 status = acpi_ns_handle_to_pathname (obj_handle, &buffer);
296 if (ACPI_FAILURE (status)) {
300 /* Print what we're doing */
303 case ACPI_TYPE_METHOD:
304 acpi_os_printf ("Executing ");
308 acpi_os_printf ("Initializing ");
312 /* Print the object type and pathname */
314 acpi_os_printf ("%-12s %s",
315 acpi_ut_get_type_name (type), (char *) buffer.pointer);
317 /* Extra path is used to append names like _STA, _INI, etc. */
320 acpi_os_printf (".%s", path);
322 acpi_os_printf ("\n");
324 ACPI_MEM_FREE (buffer.pointer);
329 /*******************************************************************************
331 * FUNCTION: acpi_ut_valid_acpi_name
333 * PARAMETERS: Name - The name to be examined
335 * RETURN: TRUE if the name is valid, FALSE otherwise
337 * DESCRIPTION: Check for a valid ACPI name. Each character must be one of:
338 * 1) Upper case alpha
342 ******************************************************************************/
345 acpi_ut_valid_acpi_name (
348 char *name_ptr = (char *) &name;
353 ACPI_FUNCTION_ENTRY ();
356 for (i = 0; i < ACPI_NAME_SIZE; i++) {
357 character = *name_ptr;
360 if (!((character == '_') ||
361 (character >= 'A' && character <= 'Z') ||
362 (character >= '0' && character <= '9'))) {
371 /*******************************************************************************
373 * FUNCTION: acpi_ut_valid_acpi_character
375 * PARAMETERS: Character - The character to be examined
377 * RETURN: 1 if Character may appear in a name, else 0
379 * DESCRIPTION: Check for a printable character
381 ******************************************************************************/
384 acpi_ut_valid_acpi_character (
388 ACPI_FUNCTION_ENTRY ();
390 return ((u8) ((character == '_') ||
391 (character >= 'A' && character <= 'Z') ||
392 (character >= '0' && character <= '9')));
396 /*******************************************************************************
398 * FUNCTION: acpi_ut_strtoul64
400 * PARAMETERS: String - Null terminated string
401 * Base - Radix of the string: 10, 16, or ACPI_ANY_BASE
402 * ret_integer - Where the converted integer is returned
404 * RETURN: Status and Converted value
406 * DESCRIPTION: Convert a string into an unsigned value.
407 * NOTE: Does not support Octal strings, not needed.
409 ******************************************************************************/
415 acpi_integer *ret_integer)
418 acpi_integer return_value = 0;
419 acpi_integer quotient;
422 ACPI_FUNCTION_TRACE ("ut_stroul64");
425 if ((!string) || !(*string)) {
437 return_ACPI_STATUS (AE_BAD_PARAMETER);
440 /* Skip over any white space in the buffer */
442 while (ACPI_IS_SPACE (*string) || *string == '\t') {
447 * If the input parameter Base is zero, then we need to
448 * determine if it is decimal or hexadecimal:
451 if ((*string == '0') &&
452 (ACPI_TOLOWER (*(string + 1)) == 'x')) {
462 * For hexadecimal base, skip over the leading
463 * 0 or 0x, if they are present.
467 (ACPI_TOLOWER (*(string + 1)) == 'x')) {
471 /* Any string left? */
477 /* Main loop: convert the string to a 64-bit integer */
480 if (ACPI_IS_DIGIT (*string)) {
481 /* Convert ASCII 0-9 to Decimal value */
483 this_digit = ((u8) *string) - '0';
487 /* Digit is out of range */
492 this_digit = (u8) ACPI_TOUPPER (*string);
493 if (ACPI_IS_XDIGIT ((char) this_digit)) {
494 /* Convert ASCII Hex char to value */
496 this_digit = this_digit - 'A' + 10;
500 * We allow non-hex chars, just stop now, same as end-of-string.
501 * See ACPI spec, string-to-integer conversion.
507 /* Divide the digit into the correct position */
509 (void) acpi_ut_short_divide ((ACPI_INTEGER_MAX - (acpi_integer) this_digit),
510 base, "ient, NULL);
511 if (return_value > quotient) {
515 return_value *= base;
516 return_value += this_digit;
520 /* All done, normal exit */
522 *ret_integer = return_value;
523 return_ACPI_STATUS (AE_OK);
527 /* Base was set/validated above */
530 return_ACPI_STATUS (AE_BAD_DECIMAL_CONSTANT);
533 return_ACPI_STATUS (AE_BAD_HEX_CONSTANT);
538 /*******************************************************************************
540 * FUNCTION: acpi_ut_create_update_state_and_push
542 * PARAMETERS: Object - Object to be added to the new state
543 * Action - Increment/Decrement
544 * state_list - List the state will be added to
548 * DESCRIPTION: Create a new state and push it
550 ******************************************************************************/
553 acpi_ut_create_update_state_and_push (
554 union acpi_operand_object *object,
556 union acpi_generic_state **state_list)
558 union acpi_generic_state *state;
561 ACPI_FUNCTION_ENTRY ();
564 /* Ignore null objects; these are expected */
570 state = acpi_ut_create_update_state (object, action);
572 return (AE_NO_MEMORY);
575 acpi_ut_push_generic_state (state_list, state);
580 /*******************************************************************************
582 * FUNCTION: acpi_ut_walk_package_tree
584 * PARAMETERS: source_object - The package to walk
585 * target_object - Target object (if package is being copied)
586 * walk_callback - Called once for each package element
587 * Context - Passed to the callback function
591 * DESCRIPTION: Walk through a package
593 ******************************************************************************/
596 acpi_ut_walk_package_tree (
597 union acpi_operand_object *source_object,
599 acpi_pkg_callback walk_callback,
602 acpi_status status = AE_OK;
603 union acpi_generic_state *state_list = NULL;
604 union acpi_generic_state *state;
606 union acpi_operand_object *this_source_obj;
609 ACPI_FUNCTION_TRACE ("ut_walk_package_tree");
612 state = acpi_ut_create_pkg_state (source_object, target_object, 0);
614 return_ACPI_STATUS (AE_NO_MEMORY);
618 /* Get one element of the package */
620 this_index = state->pkg.index;
621 this_source_obj = (union acpi_operand_object *)
622 state->pkg.source_object->package.elements[this_index];
626 * 1) An uninitialized package element. It is completely
627 * legal to declare a package and leave it uninitialized
628 * 2) Not an internal object - can be a namespace node instead
629 * 3) Any type other than a package. Packages are handled in else
632 if ((!this_source_obj) ||
633 (ACPI_GET_DESCRIPTOR_TYPE (this_source_obj) != ACPI_DESC_TYPE_OPERAND) ||
634 (ACPI_GET_OBJECT_TYPE (this_source_obj) != ACPI_TYPE_PACKAGE)) {
635 status = walk_callback (ACPI_COPY_TYPE_SIMPLE, this_source_obj,
637 if (ACPI_FAILURE (status)) {
638 return_ACPI_STATUS (status);
642 while (state->pkg.index >= state->pkg.source_object->package.count) {
644 * We've handled all of the objects at this level, This means
645 * that we have just completed a package. That package may
646 * have contained one or more packages itself.
648 * Delete this state and pop the previous state (package).
650 acpi_ut_delete_generic_state (state);
651 state = acpi_ut_pop_generic_state (&state_list);
653 /* Finished when there are no more states */
657 * We have handled all of the objects in the top level
658 * package just add the length of the package objects
661 return_ACPI_STATUS (AE_OK);
665 * Go back up a level and move the index past the just
666 * completed package object.
672 /* This is a subobject of type package */
674 status = walk_callback (ACPI_COPY_TYPE_PACKAGE, this_source_obj,
676 if (ACPI_FAILURE (status)) {
677 return_ACPI_STATUS (status);
681 * Push the current state and create a new one
682 * The callback above returned a new target package object.
684 acpi_ut_push_generic_state (&state_list, state);
685 state = acpi_ut_create_pkg_state (this_source_obj,
686 state->pkg.this_target_obj, 0);
688 return_ACPI_STATUS (AE_NO_MEMORY);
693 /* We should never get here */
695 return_ACPI_STATUS (AE_AML_INTERNAL);
699 /*******************************************************************************
701 * FUNCTION: acpi_ut_generate_checksum
703 * PARAMETERS: Buffer - Buffer to be scanned
704 * Length - number of bytes to examine
706 * RETURN: The generated checksum
708 * DESCRIPTION: Generate a checksum on a raw buffer
710 ******************************************************************************/
713 acpi_ut_generate_checksum (
721 for (i = 0; i < length; i++) {
722 sum = (signed char) (sum + buffer[i]);
725 return ((u8) (0 - sum));
729 /*******************************************************************************
731 * FUNCTION: acpi_ut_get_resource_end_tag
733 * PARAMETERS: obj_desc - The resource template buffer object
735 * RETURN: Pointer to the end tag
737 * DESCRIPTION: Find the END_TAG resource descriptor in a resource template
739 ******************************************************************************/
743 acpi_ut_get_resource_end_tag (
744 union acpi_operand_object *obj_desc)
751 buffer = obj_desc->buffer.pointer;
752 end_buffer = buffer + obj_desc->buffer.length;
754 while (buffer < end_buffer) {
755 buffer_byte = *buffer;
756 if (buffer_byte & ACPI_RDESC_TYPE_MASK) {
757 /* Large Descriptor - Length is next 2 bytes */
759 buffer += ((*(buffer+1) | (*(buffer+2) << 8)) + 3);
762 /* Small Descriptor. End Tag will be found here */
764 if ((buffer_byte & ACPI_RDESC_SMALL_MASK) == ACPI_RDESC_TYPE_END_TAG) {
765 /* Found the end tag descriptor, all done. */
770 /* Length is in the header */
772 buffer += ((buffer_byte & 0x07) + 1);
776 /* End tag not found */
782 /*******************************************************************************
784 * FUNCTION: acpi_ut_report_error
786 * PARAMETERS: module_name - Caller's module name (for error output)
787 * line_number - Caller's line number (for error output)
788 * component_id - Caller's component ID (for error output)
792 * DESCRIPTION: Print error message
794 ******************************************************************************/
797 acpi_ut_report_error (
803 acpi_os_printf ("%8s-%04d: *** Error: ", module_name, line_number);
807 /*******************************************************************************
809 * FUNCTION: acpi_ut_report_warning
811 * PARAMETERS: module_name - Caller's module name (for error output)
812 * line_number - Caller's line number (for error output)
813 * component_id - Caller's component ID (for error output)
817 * DESCRIPTION: Print warning message
819 ******************************************************************************/
822 acpi_ut_report_warning (
828 acpi_os_printf ("%8s-%04d: *** Warning: ", module_name, line_number);
832 /*******************************************************************************
834 * FUNCTION: acpi_ut_report_info
836 * PARAMETERS: module_name - Caller's module name (for error output)
837 * line_number - Caller's line number (for error output)
838 * component_id - Caller's component ID (for error output)
842 * DESCRIPTION: Print information message
844 ******************************************************************************/
847 acpi_ut_report_info (
853 acpi_os_printf ("%8s-%04d: *** Info: ", module_name, line_number);