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_allocate_owner_id
57 * PARAMETERS: owner_id - Where the new owner ID is returned
59 * DESCRIPTION: Allocate a table or method owner id
61 ******************************************************************************/
64 acpi_ut_allocate_owner_id (
65 acpi_owner_id *owner_id)
71 ACPI_FUNCTION_TRACE ("ut_allocate_owner_id");
74 status = acpi_ut_acquire_mutex (ACPI_MTX_CACHES);
75 if (ACPI_FAILURE (status)) {
76 return_ACPI_STATUS (status);
79 /* Find a free owner ID */
81 for (i = 0; i < 32; i++) {
82 if (!(acpi_gbl_owner_id_mask & (1 << i))) {
83 acpi_gbl_owner_id_mask |= (1 << i);
84 *owner_id = (acpi_owner_id) i;
90 * If we are here, all owner_ids have been allocated. This probably should
91 * not happen since the IDs are reused after deallocation. The IDs are
92 * allocated upon table load (one per table) and method execution, and
93 * they are released when a table is unloaded or a method completes
96 status = AE_OWNER_ID_LIMIT;
98 "Could not allocate new owner_id (32 max), AE_OWNER_ID_LIMIT\n"));
101 (void) acpi_ut_release_mutex (ACPI_MTX_CACHES);
102 return_ACPI_STATUS (status);
106 /*******************************************************************************
108 * FUNCTION: acpi_ut_release_owner_id
110 * PARAMETERS: owner_id - A previously allocated owner ID
112 * DESCRIPTION: Release a table or method owner id
114 ******************************************************************************/
117 acpi_ut_release_owner_id (
118 acpi_owner_id owner_id)
123 ACPI_FUNCTION_TRACE ("ut_release_owner_id");
126 status = acpi_ut_acquire_mutex (ACPI_MTX_CACHES);
127 if (ACPI_FAILURE (status)) {
128 return_ACPI_STATUS (status);
131 /* Free the owner ID */
133 if (acpi_gbl_owner_id_mask & (1 << owner_id)) {
134 acpi_gbl_owner_id_mask ^= (1 << owner_id);
137 /* This owner_id has not been allocated */
139 status = AE_NOT_EXIST;
142 (void) acpi_ut_release_mutex (ACPI_MTX_CACHES);
143 return_ACPI_STATUS (status);
147 /*******************************************************************************
149 * FUNCTION: acpi_ut_strupr (strupr)
151 * PARAMETERS: src_string - The source string to convert
153 * RETURN: Converted src_string (same as input pointer)
155 * DESCRIPTION: Convert string to uppercase
157 * NOTE: This is not a POSIX function, so it appears here, not in utclib.c
159 ******************************************************************************/
168 ACPI_FUNCTION_ENTRY ();
175 /* Walk entire string, uppercasing the letters */
177 for (string = src_string; *string; string++) {
178 *string = (char) ACPI_TOUPPER (*string);
185 /*******************************************************************************
187 * FUNCTION: acpi_ut_print_string
189 * PARAMETERS: String - Null terminated ASCII string
190 * max_length - Maximum output length
194 * DESCRIPTION: Dump an ASCII string with support for ACPI-defined escape
197 ******************************************************************************/
200 acpi_ut_print_string (
208 acpi_os_printf ("<\"NULL STRING PTR\">");
212 acpi_os_printf ("\"");
213 for (i = 0; string[i] && (i < max_length); i++) {
214 /* Escape sequences */
218 acpi_os_printf ("\\a"); /* BELL */
222 acpi_os_printf ("\\b"); /* BACKSPACE */
226 acpi_os_printf ("\\f"); /* FORMFEED */
230 acpi_os_printf ("\\n"); /* LINEFEED */
234 acpi_os_printf ("\\r"); /* CARRIAGE RETURN*/
238 acpi_os_printf ("\\t"); /* HORIZONTAL TAB */
242 acpi_os_printf ("\\v"); /* VERTICAL TAB */
245 case '\'': /* Single Quote */
246 case '\"': /* Double Quote */
247 case '\\': /* Backslash */
248 acpi_os_printf ("\\%c", (int) string[i]);
253 /* Check for printable character or hex escape */
255 if (ACPI_IS_PRINT (string[i]))
257 /* This is a normal character */
259 acpi_os_printf ("%c", (int) string[i]);
263 /* All others will be Hex escapes */
265 acpi_os_printf ("\\x%2.2X", (s32) string[i]);
270 acpi_os_printf ("\"");
272 if (i == max_length && string[i]) {
273 acpi_os_printf ("...");
278 /*******************************************************************************
280 * FUNCTION: acpi_ut_dword_byte_swap
282 * PARAMETERS: Value - Value to be converted
284 * RETURN: u32 integer with bytes swapped
286 * DESCRIPTION: Convert a 32-bit value to big-endian (swap the bytes)
288 ******************************************************************************/
291 acpi_ut_dword_byte_swap (
304 ACPI_FUNCTION_ENTRY ();
309 out.bytes[0] = in.bytes[3];
310 out.bytes[1] = in.bytes[2];
311 out.bytes[2] = in.bytes[1];
312 out.bytes[3] = in.bytes[0];
318 /*******************************************************************************
320 * FUNCTION: acpi_ut_set_integer_width
322 * PARAMETERS: Revision From DSDT header
326 * DESCRIPTION: Set the global integer bit width based upon the revision
327 * of the DSDT. For Revision 1 and 0, Integers are 32 bits.
328 * For Revision 2 and above, Integers are 64 bits. Yes, this
329 * makes a difference.
331 ******************************************************************************/
334 acpi_ut_set_integer_width (
339 acpi_gbl_integer_bit_width = 32;
340 acpi_gbl_integer_nybble_width = 8;
341 acpi_gbl_integer_byte_width = 4;
344 acpi_gbl_integer_bit_width = 64;
345 acpi_gbl_integer_nybble_width = 16;
346 acpi_gbl_integer_byte_width = 8;
351 #ifdef ACPI_DEBUG_OUTPUT
352 /*******************************************************************************
354 * FUNCTION: acpi_ut_display_init_pathname
356 * PARAMETERS: Type - Object type of the node
357 * obj_handle - Handle whose pathname will be displayed
358 * Path - Additional path string to be appended.
359 * (NULL if no extra path)
361 * RETURN: acpi_status
363 * DESCRIPTION: Display full pathname of an object, DEBUG ONLY
365 ******************************************************************************/
368 acpi_ut_display_init_pathname (
370 struct acpi_namespace_node *obj_handle,
374 struct acpi_buffer buffer;
377 ACPI_FUNCTION_ENTRY ();
380 /* Only print the path if the appropriate debug level is enabled */
382 if (!(acpi_dbg_level & ACPI_LV_INIT_NAMES)) {
386 /* Get the full pathname to the node */
388 buffer.length = ACPI_ALLOCATE_LOCAL_BUFFER;
389 status = acpi_ns_handle_to_pathname (obj_handle, &buffer);
390 if (ACPI_FAILURE (status)) {
394 /* Print what we're doing */
397 case ACPI_TYPE_METHOD:
398 acpi_os_printf ("Executing ");
402 acpi_os_printf ("Initializing ");
406 /* Print the object type and pathname */
408 acpi_os_printf ("%-12s %s",
409 acpi_ut_get_type_name (type), (char *) buffer.pointer);
411 /* Extra path is used to append names like _STA, _INI, etc. */
414 acpi_os_printf (".%s", path);
416 acpi_os_printf ("\n");
418 ACPI_MEM_FREE (buffer.pointer);
423 /*******************************************************************************
425 * FUNCTION: acpi_ut_valid_acpi_name
427 * PARAMETERS: Name - The name to be examined
429 * RETURN: TRUE if the name is valid, FALSE otherwise
431 * DESCRIPTION: Check for a valid ACPI name. Each character must be one of:
432 * 1) Upper case alpha
436 ******************************************************************************/
439 acpi_ut_valid_acpi_name (
442 char *name_ptr = (char *) &name;
447 ACPI_FUNCTION_ENTRY ();
450 for (i = 0; i < ACPI_NAME_SIZE; i++) {
451 character = *name_ptr;
454 if (!((character == '_') ||
455 (character >= 'A' && character <= 'Z') ||
456 (character >= '0' && character <= '9'))) {
465 /*******************************************************************************
467 * FUNCTION: acpi_ut_valid_acpi_character
469 * PARAMETERS: Character - The character to be examined
471 * RETURN: 1 if Character may appear in a name, else 0
473 * DESCRIPTION: Check for a printable character
475 ******************************************************************************/
478 acpi_ut_valid_acpi_character (
482 ACPI_FUNCTION_ENTRY ();
484 return ((u8) ((character == '_') ||
485 (character >= 'A' && character <= 'Z') ||
486 (character >= '0' && character <= '9')));
490 /*******************************************************************************
492 * FUNCTION: acpi_ut_strtoul64
494 * PARAMETERS: String - Null terminated string
495 * Base - Radix of the string: 10, 16, or ACPI_ANY_BASE
496 * ret_integer - Where the converted integer is returned
498 * RETURN: Status and Converted value
500 * DESCRIPTION: Convert a string into an unsigned value.
501 * NOTE: Does not support Octal strings, not needed.
503 ******************************************************************************/
509 acpi_integer *ret_integer)
512 acpi_integer return_value = 0;
513 acpi_integer quotient;
516 ACPI_FUNCTION_TRACE ("ut_stroul64");
519 if ((!string) || !(*string)) {
531 return_ACPI_STATUS (AE_BAD_PARAMETER);
534 /* Skip over any white space in the buffer */
536 while (ACPI_IS_SPACE (*string) || *string == '\t') {
541 * If the input parameter Base is zero, then we need to
542 * determine if it is decimal or hexadecimal:
545 if ((*string == '0') &&
546 (ACPI_TOLOWER (*(string + 1)) == 'x')) {
556 * For hexadecimal base, skip over the leading
557 * 0 or 0x, if they are present.
561 (ACPI_TOLOWER (*(string + 1)) == 'x')) {
565 /* Any string left? */
571 /* Main loop: convert the string to a 64-bit integer */
574 if (ACPI_IS_DIGIT (*string)) {
575 /* Convert ASCII 0-9 to Decimal value */
577 this_digit = ((u8) *string) - '0';
581 /* Digit is out of range */
586 this_digit = (u8) ACPI_TOUPPER (*string);
587 if (ACPI_IS_XDIGIT ((char) this_digit)) {
588 /* Convert ASCII Hex char to value */
590 this_digit = this_digit - 'A' + 10;
594 * We allow non-hex chars, just stop now, same as end-of-string.
595 * See ACPI spec, string-to-integer conversion.
601 /* Divide the digit into the correct position */
603 (void) acpi_ut_short_divide ((ACPI_INTEGER_MAX - (acpi_integer) this_digit),
604 base, "ient, NULL);
605 if (return_value > quotient) {
609 return_value *= base;
610 return_value += this_digit;
614 /* All done, normal exit */
616 *ret_integer = return_value;
617 return_ACPI_STATUS (AE_OK);
621 /* Base was set/validated above */
624 return_ACPI_STATUS (AE_BAD_DECIMAL_CONSTANT);
627 return_ACPI_STATUS (AE_BAD_HEX_CONSTANT);
632 /*******************************************************************************
634 * FUNCTION: acpi_ut_create_update_state_and_push
636 * PARAMETERS: Object - Object to be added to the new state
637 * Action - Increment/Decrement
638 * state_list - List the state will be added to
642 * DESCRIPTION: Create a new state and push it
644 ******************************************************************************/
647 acpi_ut_create_update_state_and_push (
648 union acpi_operand_object *object,
650 union acpi_generic_state **state_list)
652 union acpi_generic_state *state;
655 ACPI_FUNCTION_ENTRY ();
658 /* Ignore null objects; these are expected */
664 state = acpi_ut_create_update_state (object, action);
666 return (AE_NO_MEMORY);
669 acpi_ut_push_generic_state (state_list, state);
674 /*******************************************************************************
676 * FUNCTION: acpi_ut_walk_package_tree
678 * PARAMETERS: source_object - The package to walk
679 * target_object - Target object (if package is being copied)
680 * walk_callback - Called once for each package element
681 * Context - Passed to the callback function
685 * DESCRIPTION: Walk through a package
687 ******************************************************************************/
690 acpi_ut_walk_package_tree (
691 union acpi_operand_object *source_object,
693 acpi_pkg_callback walk_callback,
696 acpi_status status = AE_OK;
697 union acpi_generic_state *state_list = NULL;
698 union acpi_generic_state *state;
700 union acpi_operand_object *this_source_obj;
703 ACPI_FUNCTION_TRACE ("ut_walk_package_tree");
706 state = acpi_ut_create_pkg_state (source_object, target_object, 0);
708 return_ACPI_STATUS (AE_NO_MEMORY);
712 /* Get one element of the package */
714 this_index = state->pkg.index;
715 this_source_obj = (union acpi_operand_object *)
716 state->pkg.source_object->package.elements[this_index];
720 * 1) An uninitialized package element. It is completely
721 * legal to declare a package and leave it uninitialized
722 * 2) Not an internal object - can be a namespace node instead
723 * 3) Any type other than a package. Packages are handled in else
726 if ((!this_source_obj) ||
727 (ACPI_GET_DESCRIPTOR_TYPE (this_source_obj) != ACPI_DESC_TYPE_OPERAND) ||
728 (ACPI_GET_OBJECT_TYPE (this_source_obj) != ACPI_TYPE_PACKAGE)) {
729 status = walk_callback (ACPI_COPY_TYPE_SIMPLE, this_source_obj,
731 if (ACPI_FAILURE (status)) {
732 return_ACPI_STATUS (status);
736 while (state->pkg.index >= state->pkg.source_object->package.count) {
738 * We've handled all of the objects at this level, This means
739 * that we have just completed a package. That package may
740 * have contained one or more packages itself.
742 * Delete this state and pop the previous state (package).
744 acpi_ut_delete_generic_state (state);
745 state = acpi_ut_pop_generic_state (&state_list);
747 /* Finished when there are no more states */
751 * We have handled all of the objects in the top level
752 * package just add the length of the package objects
755 return_ACPI_STATUS (AE_OK);
759 * Go back up a level and move the index past the just
760 * completed package object.
766 /* This is a subobject of type package */
768 status = walk_callback (ACPI_COPY_TYPE_PACKAGE, this_source_obj,
770 if (ACPI_FAILURE (status)) {
771 return_ACPI_STATUS (status);
775 * Push the current state and create a new one
776 * The callback above returned a new target package object.
778 acpi_ut_push_generic_state (&state_list, state);
779 state = acpi_ut_create_pkg_state (this_source_obj,
780 state->pkg.this_target_obj, 0);
782 return_ACPI_STATUS (AE_NO_MEMORY);
787 /* We should never get here */
789 return_ACPI_STATUS (AE_AML_INTERNAL);
793 /*******************************************************************************
795 * FUNCTION: acpi_ut_generate_checksum
797 * PARAMETERS: Buffer - Buffer to be scanned
798 * Length - number of bytes to examine
800 * RETURN: The generated checksum
802 * DESCRIPTION: Generate a checksum on a raw buffer
804 ******************************************************************************/
807 acpi_ut_generate_checksum (
815 for (i = 0; i < length; i++) {
816 sum = (signed char) (sum + buffer[i]);
819 return ((u8) (0 - sum));
823 /*******************************************************************************
825 * FUNCTION: acpi_ut_get_resource_end_tag
827 * PARAMETERS: obj_desc - The resource template buffer object
829 * RETURN: Pointer to the end tag
831 * DESCRIPTION: Find the END_TAG resource descriptor in a resource template
833 ******************************************************************************/
837 acpi_ut_get_resource_end_tag (
838 union acpi_operand_object *obj_desc)
845 buffer = obj_desc->buffer.pointer;
846 end_buffer = buffer + obj_desc->buffer.length;
848 while (buffer < end_buffer) {
849 buffer_byte = *buffer;
850 if (buffer_byte & ACPI_RDESC_TYPE_MASK) {
851 /* Large Descriptor - Length is next 2 bytes */
853 buffer += ((*(buffer+1) | (*(buffer+2) << 8)) + 3);
856 /* Small Descriptor. End Tag will be found here */
858 if ((buffer_byte & ACPI_RDESC_SMALL_MASK) == ACPI_RDESC_TYPE_END_TAG) {
859 /* Found the end tag descriptor, all done. */
864 /* Length is in the header */
866 buffer += ((buffer_byte & 0x07) + 1);
870 /* End tag not found */
876 /*******************************************************************************
878 * FUNCTION: acpi_ut_report_error
880 * PARAMETERS: module_name - Caller's module name (for error output)
881 * line_number - Caller's line number (for error output)
882 * component_id - Caller's component ID (for error output)
886 * DESCRIPTION: Print error message
888 ******************************************************************************/
891 acpi_ut_report_error (
897 acpi_os_printf ("%8s-%04d: *** Error: ", module_name, line_number);
901 /*******************************************************************************
903 * FUNCTION: acpi_ut_report_warning
905 * PARAMETERS: module_name - Caller's module name (for error output)
906 * line_number - Caller's line number (for error output)
907 * component_id - Caller's component ID (for error output)
911 * DESCRIPTION: Print warning message
913 ******************************************************************************/
916 acpi_ut_report_warning (
922 acpi_os_printf ("%8s-%04d: *** Warning: ", module_name, line_number);
926 /*******************************************************************************
928 * FUNCTION: acpi_ut_report_info
930 * PARAMETERS: module_name - Caller's module name (for error output)
931 * line_number - Caller's line number (for error output)
932 * component_id - Caller's component ID (for error output)
936 * DESCRIPTION: Print information message
938 ******************************************************************************/
941 acpi_ut_report_info (
947 acpi_os_printf ("%8s-%04d: *** Info: ", module_name, line_number);