1 /******************************************************************************
3 * Module Name: nsutils - Utilities for accessing ACPI namespace, accessing
4 * parents and siblings and Scope manipulation
6 *****************************************************************************/
9 * Copyright (C) 2000 - 2015, Intel Corp.
10 * All rights reserved.
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions
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.
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.
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.
50 #define _COMPONENT ACPI_NAMESPACE
51 ACPI_MODULE_NAME ("nsutils")
53 /* Local prototypes */
55 #ifdef ACPI_OBSOLETE_FUNCTIONS
57 AcpiNsFindParentName (
58 ACPI_NAMESPACE_NODE *NodeToSearch);
62 /*******************************************************************************
64 * FUNCTION: AcpiNsPrintNodePathname
66 * PARAMETERS: Node - Object
67 * Message - Prefix message
69 * DESCRIPTION: Print an object's full namespace pathname
70 * Manages allocation/freeing of a pathname buffer
72 ******************************************************************************/
75 AcpiNsPrintNodePathname (
76 ACPI_NAMESPACE_NODE *Node,
85 AcpiOsPrintf ("[NULL NAME]");
89 /* Convert handle to full pathname and print it (with supplied message) */
91 Buffer.Length = ACPI_ALLOCATE_LOCAL_BUFFER;
93 Status = AcpiNsHandleToPathname (Node, &Buffer);
94 if (ACPI_SUCCESS (Status))
98 AcpiOsPrintf ("%s ", Message);
101 AcpiOsPrintf ("[%s] (Node %p)", (char *) Buffer.Pointer, Node);
102 ACPI_FREE (Buffer.Pointer);
107 /*******************************************************************************
109 * FUNCTION: AcpiNsGetType
111 * PARAMETERS: Node - Parent Node to be examined
113 * RETURN: Type field from Node whose handle is passed
115 * DESCRIPTION: Return the type of a Namespace node
117 ******************************************************************************/
121 ACPI_NAMESPACE_NODE *Node)
123 ACPI_FUNCTION_TRACE (NsGetType);
128 ACPI_WARNING ((AE_INFO, "Null Node parameter"));
129 return_UINT8 (ACPI_TYPE_ANY);
132 return_UINT8 (Node->Type);
136 /*******************************************************************************
138 * FUNCTION: AcpiNsLocal
140 * PARAMETERS: Type - A namespace object type
142 * RETURN: LOCAL if names must be found locally in objects of the
143 * passed type, 0 if enclosing scopes should be searched
145 * DESCRIPTION: Returns scope rule for the given object type.
147 ******************************************************************************/
151 ACPI_OBJECT_TYPE Type)
153 ACPI_FUNCTION_TRACE (NsLocal);
156 if (!AcpiUtValidObjectType (Type))
158 /* Type code out of range */
160 ACPI_WARNING ((AE_INFO, "Invalid Object Type 0x%X", Type));
161 return_UINT32 (ACPI_NS_NORMAL);
164 return_UINT32 (AcpiGbl_NsProperties[Type] & ACPI_NS_LOCAL);
168 /*******************************************************************************
170 * FUNCTION: AcpiNsGetInternalNameLength
172 * PARAMETERS: Info - Info struct initialized with the
173 * external name pointer.
177 * DESCRIPTION: Calculate the length of the internal (AML) namestring
178 * corresponding to the external (ASL) namestring.
180 ******************************************************************************/
183 AcpiNsGetInternalNameLength (
184 ACPI_NAMESTRING_INFO *Info)
186 const char *NextExternalChar;
190 ACPI_FUNCTION_ENTRY ();
193 NextExternalChar = Info->ExternalName;
195 Info->NumSegments = 0;
196 Info->FullyQualified = FALSE;
199 * For the internal name, the required length is 4 bytes per segment, plus
200 * 1 each for RootPrefix, MultiNamePrefixOp, segment count, trailing null
201 * (which is not really needed, but no there's harm in putting it there)
203 * strlen() + 1 covers the first NameSeg, which has no path separator
205 if (ACPI_IS_ROOT_PREFIX (*NextExternalChar))
207 Info->FullyQualified = TRUE;
210 /* Skip redundant RootPrefix, like \\_SB.PCI0.SBRG.EC0 */
212 while (ACPI_IS_ROOT_PREFIX (*NextExternalChar))
219 /* Handle Carat prefixes */
221 while (ACPI_IS_PARENT_PREFIX (*NextExternalChar))
229 * Determine the number of ACPI name "segments" by counting the number of
230 * path separators within the string. Start with one segment since the
231 * segment count is [(# separators) + 1], and zero separators is ok.
233 if (*NextExternalChar)
235 Info->NumSegments = 1;
236 for (i = 0; NextExternalChar[i]; i++)
238 if (ACPI_IS_PATH_SEPARATOR (NextExternalChar[i]))
245 Info->Length = (ACPI_NAME_SIZE * Info->NumSegments) +
248 Info->NextExternalChar = NextExternalChar;
252 /*******************************************************************************
254 * FUNCTION: AcpiNsBuildInternalName
256 * PARAMETERS: Info - Info struct fully initialized
260 * DESCRIPTION: Construct the internal (AML) namestring
261 * corresponding to the external (ASL) namestring.
263 ******************************************************************************/
266 AcpiNsBuildInternalName (
267 ACPI_NAMESTRING_INFO *Info)
269 UINT32 NumSegments = Info->NumSegments;
270 char *InternalName = Info->InternalName;
271 const char *ExternalName = Info->NextExternalChar;
276 ACPI_FUNCTION_TRACE (NsBuildInternalName);
279 /* Setup the correct prefixes, counts, and pointers */
281 if (Info->FullyQualified)
283 InternalName[0] = AML_ROOT_PREFIX;
285 if (NumSegments <= 1)
287 Result = &InternalName[1];
289 else if (NumSegments == 2)
291 InternalName[1] = AML_DUAL_NAME_PREFIX;
292 Result = &InternalName[2];
296 InternalName[1] = AML_MULTI_NAME_PREFIX_OP;
297 InternalName[2] = (char) NumSegments;
298 Result = &InternalName[3];
304 * Not fully qualified.
305 * Handle Carats first, then append the name segments
310 for (i = 0; i < Info->NumCarats; i++)
312 InternalName[i] = AML_PARENT_PREFIX;
316 if (NumSegments <= 1)
318 Result = &InternalName[i];
320 else if (NumSegments == 2)
322 InternalName[i] = AML_DUAL_NAME_PREFIX;
323 Result = &InternalName[(ACPI_SIZE) i+1];
327 InternalName[i] = AML_MULTI_NAME_PREFIX_OP;
328 InternalName[(ACPI_SIZE) i+1] = (char) NumSegments;
329 Result = &InternalName[(ACPI_SIZE) i+2];
333 /* Build the name (minus path separators) */
335 for (; NumSegments; NumSegments--)
337 for (i = 0; i < ACPI_NAME_SIZE; i++)
339 if (ACPI_IS_PATH_SEPARATOR (*ExternalName) ||
340 (*ExternalName == 0))
342 /* Pad the segment with underscore(s) if segment is short */
348 /* Convert the character to uppercase and save it */
350 Result[i] = (char) ACPI_TOUPPER ((int) *ExternalName);
355 /* Now we must have a path separator, or the pathname is bad */
357 if (!ACPI_IS_PATH_SEPARATOR (*ExternalName) &&
358 (*ExternalName != 0))
360 return_ACPI_STATUS (AE_BAD_PATHNAME);
363 /* Move on the next segment */
366 Result += ACPI_NAME_SIZE;
369 /* Terminate the string */
373 if (Info->FullyQualified)
375 ACPI_DEBUG_PRINT ((ACPI_DB_EXEC, "Returning [%p] (abs) \"\\%s\"\n",
376 InternalName, InternalName));
380 ACPI_DEBUG_PRINT ((ACPI_DB_EXEC, "Returning [%p] (rel) \"%s\"\n",
381 InternalName, InternalName));
384 return_ACPI_STATUS (AE_OK);
388 /*******************************************************************************
390 * FUNCTION: AcpiNsInternalizeName
392 * PARAMETERS: *ExternalName - External representation of name
393 * **Converted Name - Where to return the resulting
394 * internal represention of the name
398 * DESCRIPTION: Convert an external representation (e.g. "\_PR_.CPU0")
399 * to internal form (e.g. 5c 2f 02 5f 50 52 5f 43 50 55 30)
401 *******************************************************************************/
404 AcpiNsInternalizeName (
405 const char *ExternalName,
406 char **ConvertedName)
409 ACPI_NAMESTRING_INFO Info;
413 ACPI_FUNCTION_TRACE (NsInternalizeName);
416 if ((!ExternalName) ||
417 (*ExternalName == 0) ||
420 return_ACPI_STATUS (AE_BAD_PARAMETER);
423 /* Get the length of the new internal name */
425 Info.ExternalName = ExternalName;
426 AcpiNsGetInternalNameLength (&Info);
428 /* We need a segment to store the internal name */
430 InternalName = ACPI_ALLOCATE_ZEROED (Info.Length);
433 return_ACPI_STATUS (AE_NO_MEMORY);
438 Info.InternalName = InternalName;
439 Status = AcpiNsBuildInternalName (&Info);
440 if (ACPI_FAILURE (Status))
442 ACPI_FREE (InternalName);
443 return_ACPI_STATUS (Status);
446 *ConvertedName = InternalName;
447 return_ACPI_STATUS (AE_OK);
451 /*******************************************************************************
453 * FUNCTION: AcpiNsExternalizeName
455 * PARAMETERS: InternalNameLength - Lenth of the internal name below
456 * InternalName - Internal representation of name
457 * ConvertedNameLength - Where the length is returned
458 * ConvertedName - Where the resulting external name
463 * DESCRIPTION: Convert internal name (e.g. 5c 2f 02 5f 50 52 5f 43 50 55 30)
464 * to its external (printable) form (e.g. "\_PR_.CPU0")
466 ******************************************************************************/
469 AcpiNsExternalizeName (
470 UINT32 InternalNameLength,
471 const char *InternalName,
472 UINT32 *ConvertedNameLength,
473 char **ConvertedName)
475 UINT32 NamesIndex = 0;
476 UINT32 NumSegments = 0;
477 UINT32 RequiredLength;
478 UINT32 PrefixLength = 0;
483 ACPI_FUNCTION_TRACE (NsExternalizeName);
486 if (!InternalNameLength ||
490 return_ACPI_STATUS (AE_BAD_PARAMETER);
493 /* Check for a prefix (one '\' | one or more '^') */
495 switch (InternalName[0])
497 case AML_ROOT_PREFIX:
502 case AML_PARENT_PREFIX:
504 for (i = 0; i < InternalNameLength; i++)
506 if (ACPI_IS_PARENT_PREFIX (InternalName[i]))
508 PrefixLength = i + 1;
516 if (i == InternalNameLength)
529 * Check for object names. Note that there could be 0-255 of these
532 if (PrefixLength < InternalNameLength)
534 switch (InternalName[PrefixLength])
536 case AML_MULTI_NAME_PREFIX_OP:
538 /* <count> 4-byte names */
540 NamesIndex = PrefixLength + 2;
541 NumSegments = (UINT8)
542 InternalName[(ACPI_SIZE) PrefixLength + 1];
545 case AML_DUAL_NAME_PREFIX:
547 /* Two 4-byte names */
549 NamesIndex = PrefixLength + 1;
563 /* one 4-byte name */
565 NamesIndex = PrefixLength;
572 * Calculate the length of ConvertedName, which equals the length
573 * of the prefix, length of all object names, length of any required
574 * punctuation ('.') between object names, plus the NULL terminator.
576 RequiredLength = PrefixLength + (4 * NumSegments) +
577 ((NumSegments > 0) ? (NumSegments - 1) : 0) + 1;
580 * Check to see if we're still in bounds. If not, there's a problem
581 * with InternalName (invalid format).
583 if (RequiredLength > InternalNameLength)
585 ACPI_ERROR ((AE_INFO, "Invalid internal name"));
586 return_ACPI_STATUS (AE_BAD_PATHNAME);
589 /* Build the ConvertedName */
591 *ConvertedName = ACPI_ALLOCATE_ZEROED (RequiredLength);
592 if (!(*ConvertedName))
594 return_ACPI_STATUS (AE_NO_MEMORY);
599 for (i = 0; i < PrefixLength; i++)
601 (*ConvertedName)[j++] = InternalName[i];
606 for (i = 0; i < NumSegments; i++)
610 (*ConvertedName)[j++] = '.';
613 /* Copy and validate the 4-char name segment */
615 ACPI_MOVE_NAME (&(*ConvertedName)[j], &InternalName[NamesIndex]);
616 AcpiUtRepairName (&(*ConvertedName)[j]);
619 NamesIndex += ACPI_NAME_SIZE;
623 if (ConvertedNameLength)
625 *ConvertedNameLength = (UINT32) RequiredLength;
628 return_ACPI_STATUS (AE_OK);
632 /*******************************************************************************
634 * FUNCTION: AcpiNsValidateHandle
636 * PARAMETERS: Handle - Handle to be validated and typecast to a
639 * RETURN: A pointer to a namespace node
641 * DESCRIPTION: Convert a namespace handle to a namespace node. Handles special
642 * cases for the root node.
644 * NOTE: Real integer handles would allow for more verification
645 * and keep all pointers within this subsystem - however this introduces
646 * more overhead and has not been necessary to this point. Drivers
647 * holding handles are typically notified before a node becomes invalid
648 * due to a table unload.
650 ******************************************************************************/
652 ACPI_NAMESPACE_NODE *
653 AcpiNsValidateHandle (
657 ACPI_FUNCTION_ENTRY ();
660 /* Parameter validation */
662 if ((!Handle) || (Handle == ACPI_ROOT_OBJECT))
664 return (AcpiGbl_RootNode);
667 /* We can at least attempt to verify the handle */
669 if (ACPI_GET_DESCRIPTOR_TYPE (Handle) != ACPI_DESC_TYPE_NAMED)
674 return (ACPI_CAST_PTR (ACPI_NAMESPACE_NODE, Handle));
678 /*******************************************************************************
680 * FUNCTION: AcpiNsTerminate
686 * DESCRIPTION: free memory allocated for namespace and ACPI table storage.
688 ******************************************************************************/
697 ACPI_FUNCTION_TRACE (NsTerminate);
701 * Free the entire namespace -- all nodes and all objects
702 * attached to the nodes
704 AcpiNsDeleteNamespaceSubtree (AcpiGbl_RootNode);
706 /* Delete any objects attached to the root node */
708 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
709 if (ACPI_FAILURE (Status))
714 AcpiNsDeleteNode (AcpiGbl_RootNode);
715 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
717 ACPI_DEBUG_PRINT ((ACPI_DB_INFO, "Namespace freed\n"));
722 /*******************************************************************************
724 * FUNCTION: AcpiNsOpensScope
726 * PARAMETERS: Type - A valid namespace type
728 * RETURN: NEWSCOPE if the passed type "opens a name scope" according
729 * to the ACPI specification, else 0
731 ******************************************************************************/
735 ACPI_OBJECT_TYPE Type)
737 ACPI_FUNCTION_ENTRY ();
740 if (Type > ACPI_TYPE_LOCAL_MAX)
742 /* type code out of range */
744 ACPI_WARNING ((AE_INFO, "Invalid Object Type 0x%X", Type));
745 return (ACPI_NS_NORMAL);
748 return (((UINT32) AcpiGbl_NsProperties[Type]) & ACPI_NS_NEWSCOPE);
752 /*******************************************************************************
754 * FUNCTION: AcpiNsGetNode
756 * PARAMETERS: *Pathname - Name to be found, in external (ASL) format. The
757 * \ (backslash) and ^ (carat) prefixes, and the
758 * . (period) to separate segments are supported.
759 * PrefixNode - Root of subtree to be searched, or NS_ALL for the
760 * root of the name space. If Name is fully
761 * qualified (first INT8 is '\'), the passed value
762 * of Scope will not be accessed.
763 * Flags - Used to indicate whether to perform upsearch or
765 * ReturnNode - Where the Node is returned
767 * DESCRIPTION: Look up a name relative to a given scope and return the
768 * corresponding Node. NOTE: Scope can be null.
770 * MUTEX: Locks namespace
772 ******************************************************************************/
776 ACPI_NAMESPACE_NODE *PrefixNode,
777 const char *Pathname,
779 ACPI_NAMESPACE_NODE **ReturnNode)
781 ACPI_GENERIC_STATE ScopeInfo;
786 ACPI_FUNCTION_TRACE_PTR (NsGetNode, ACPI_CAST_PTR (char, Pathname));
789 /* Simplest case is a null pathname */
793 *ReturnNode = PrefixNode;
796 *ReturnNode = AcpiGbl_RootNode;
798 return_ACPI_STATUS (AE_OK);
801 /* Quick check for a reference to the root */
803 if (ACPI_IS_ROOT_PREFIX (Pathname[0]) && (!Pathname[1]))
805 *ReturnNode = AcpiGbl_RootNode;
806 return_ACPI_STATUS (AE_OK);
809 /* Convert path to internal representation */
811 Status = AcpiNsInternalizeName (Pathname, &InternalPath);
812 if (ACPI_FAILURE (Status))
814 return_ACPI_STATUS (Status);
817 /* Must lock namespace during lookup */
819 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
820 if (ACPI_FAILURE (Status))
825 /* Setup lookup scope (search starting point) */
827 ScopeInfo.Scope.Node = PrefixNode;
829 /* Lookup the name in the namespace */
831 Status = AcpiNsLookup (&ScopeInfo, InternalPath, ACPI_TYPE_ANY,
832 ACPI_IMODE_EXECUTE, (Flags | ACPI_NS_DONT_OPEN_SCOPE),
834 if (ACPI_FAILURE (Status))
836 ACPI_DEBUG_PRINT ((ACPI_DB_EXEC, "%s, %s\n",
837 Pathname, AcpiFormatException (Status)));
840 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
843 ACPI_FREE (InternalPath);
844 return_ACPI_STATUS (Status);