Home | History | Annotate | Line # | Download | only in namespace
nswalk.c revision 1.1.1.9
      1      1.1    jruoho /******************************************************************************
      2      1.1    jruoho  *
      3      1.1    jruoho  * Module Name: nswalk - Functions for walking the ACPI namespace
      4      1.1    jruoho  *
      5      1.1    jruoho  *****************************************************************************/
      6      1.1    jruoho 
      7  1.1.1.2    jruoho /*
      8  1.1.1.9  christos  * Copyright (C) 2000 - 2019, Intel Corp.
      9      1.1    jruoho  * All rights reserved.
     10      1.1    jruoho  *
     11  1.1.1.2    jruoho  * Redistribution and use in source and binary forms, with or without
     12  1.1.1.2    jruoho  * modification, are permitted provided that the following conditions
     13  1.1.1.2    jruoho  * are met:
     14  1.1.1.2    jruoho  * 1. Redistributions of source code must retain the above copyright
     15  1.1.1.2    jruoho  *    notice, this list of conditions, and the following disclaimer,
     16  1.1.1.2    jruoho  *    without modification.
     17  1.1.1.2    jruoho  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
     18  1.1.1.2    jruoho  *    substantially similar to the "NO WARRANTY" disclaimer below
     19  1.1.1.2    jruoho  *    ("Disclaimer") and any redistribution must be conditioned upon
     20  1.1.1.2    jruoho  *    including a substantially similar Disclaimer requirement for further
     21  1.1.1.2    jruoho  *    binary redistribution.
     22  1.1.1.2    jruoho  * 3. Neither the names of the above-listed copyright holders nor the names
     23  1.1.1.2    jruoho  *    of any contributors may be used to endorse or promote products derived
     24  1.1.1.2    jruoho  *    from this software without specific prior written permission.
     25  1.1.1.2    jruoho  *
     26  1.1.1.2    jruoho  * Alternatively, this software may be distributed under the terms of the
     27  1.1.1.2    jruoho  * GNU General Public License ("GPL") version 2 as published by the Free
     28  1.1.1.2    jruoho  * Software Foundation.
     29  1.1.1.2    jruoho  *
     30  1.1.1.2    jruoho  * NO WARRANTY
     31  1.1.1.2    jruoho  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     32  1.1.1.2    jruoho  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     33  1.1.1.2    jruoho  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
     34  1.1.1.2    jruoho  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     35  1.1.1.2    jruoho  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
     36  1.1.1.2    jruoho  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
     37  1.1.1.2    jruoho  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     38  1.1.1.2    jruoho  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     39  1.1.1.2    jruoho  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
     40  1.1.1.2    jruoho  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     41  1.1.1.2    jruoho  * POSSIBILITY OF SUCH DAMAGES.
     42  1.1.1.2    jruoho  */
     43      1.1    jruoho 
     44      1.1    jruoho #include "acpi.h"
     45      1.1    jruoho #include "accommon.h"
     46      1.1    jruoho #include "acnamesp.h"
     47      1.1    jruoho 
     48      1.1    jruoho 
     49      1.1    jruoho #define _COMPONENT          ACPI_NAMESPACE
     50      1.1    jruoho         ACPI_MODULE_NAME    ("nswalk")
     51      1.1    jruoho 
     52      1.1    jruoho 
     53      1.1    jruoho /*******************************************************************************
     54      1.1    jruoho  *
     55      1.1    jruoho  * FUNCTION:    AcpiNsGetNextNode
     56      1.1    jruoho  *
     57      1.1    jruoho  * PARAMETERS:  ParentNode          - Parent node whose children we are
     58      1.1    jruoho  *                                    getting
     59      1.1    jruoho  *              ChildNode           - Previous child that was found.
     60      1.1    jruoho  *                                    The NEXT child will be returned
     61      1.1    jruoho  *
     62      1.1    jruoho  * RETURN:      ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
     63      1.1    jruoho  *                                    none is found.
     64      1.1    jruoho  *
     65  1.1.1.3  christos  * DESCRIPTION: Return the next peer node within the namespace. If Handle
     66  1.1.1.3  christos  *              is valid, Scope is ignored. Otherwise, the first node
     67      1.1    jruoho  *              within Scope is returned.
     68      1.1    jruoho  *
     69      1.1    jruoho  ******************************************************************************/
     70      1.1    jruoho 
     71      1.1    jruoho ACPI_NAMESPACE_NODE *
     72      1.1    jruoho AcpiNsGetNextNode (
     73      1.1    jruoho     ACPI_NAMESPACE_NODE     *ParentNode,
     74      1.1    jruoho     ACPI_NAMESPACE_NODE     *ChildNode)
     75      1.1    jruoho {
     76      1.1    jruoho     ACPI_FUNCTION_ENTRY ();
     77      1.1    jruoho 
     78      1.1    jruoho 
     79      1.1    jruoho     if (!ChildNode)
     80      1.1    jruoho     {
     81      1.1    jruoho         /* It's really the parent's _scope_ that we want */
     82      1.1    jruoho 
     83      1.1    jruoho         return (ParentNode->Child);
     84      1.1    jruoho     }
     85      1.1    jruoho 
     86      1.1    jruoho     /* Otherwise just return the next peer */
     87      1.1    jruoho 
     88      1.1    jruoho     return (ChildNode->Peer);
     89      1.1    jruoho }
     90      1.1    jruoho 
     91      1.1    jruoho 
     92      1.1    jruoho /*******************************************************************************
     93      1.1    jruoho  *
     94      1.1    jruoho  * FUNCTION:    AcpiNsGetNextNodeTyped
     95      1.1    jruoho  *
     96      1.1    jruoho  * PARAMETERS:  Type                - Type of node to be searched for
     97      1.1    jruoho  *              ParentNode          - Parent node whose children we are
     98      1.1    jruoho  *                                    getting
     99      1.1    jruoho  *              ChildNode           - Previous child that was found.
    100      1.1    jruoho  *                                    The NEXT child will be returned
    101      1.1    jruoho  *
    102      1.1    jruoho  * RETURN:      ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
    103      1.1    jruoho  *                                    none is found.
    104      1.1    jruoho  *
    105  1.1.1.3  christos  * DESCRIPTION: Return the next peer node within the namespace. If Handle
    106  1.1.1.3  christos  *              is valid, Scope is ignored. Otherwise, the first node
    107      1.1    jruoho  *              within Scope is returned.
    108      1.1    jruoho  *
    109      1.1    jruoho  ******************************************************************************/
    110      1.1    jruoho 
    111      1.1    jruoho ACPI_NAMESPACE_NODE *
    112      1.1    jruoho AcpiNsGetNextNodeTyped (
    113      1.1    jruoho     ACPI_OBJECT_TYPE        Type,
    114      1.1    jruoho     ACPI_NAMESPACE_NODE     *ParentNode,
    115      1.1    jruoho     ACPI_NAMESPACE_NODE     *ChildNode)
    116      1.1    jruoho {
    117      1.1    jruoho     ACPI_NAMESPACE_NODE     *NextNode = NULL;
    118      1.1    jruoho 
    119      1.1    jruoho 
    120      1.1    jruoho     ACPI_FUNCTION_ENTRY ();
    121      1.1    jruoho 
    122      1.1    jruoho 
    123      1.1    jruoho     NextNode = AcpiNsGetNextNode (ParentNode, ChildNode);
    124      1.1    jruoho 
    125      1.1    jruoho     /* If any type is OK, we are done */
    126      1.1    jruoho 
    127      1.1    jruoho     if (Type == ACPI_TYPE_ANY)
    128      1.1    jruoho     {
    129      1.1    jruoho         /* NextNode is NULL if we are at the end-of-list */
    130      1.1    jruoho 
    131      1.1    jruoho         return (NextNode);
    132      1.1    jruoho     }
    133      1.1    jruoho 
    134      1.1    jruoho     /* Must search for the node -- but within this scope only */
    135      1.1    jruoho 
    136      1.1    jruoho     while (NextNode)
    137      1.1    jruoho     {
    138      1.1    jruoho         /* If type matches, we are done */
    139      1.1    jruoho 
    140      1.1    jruoho         if (NextNode->Type == Type)
    141      1.1    jruoho         {
    142      1.1    jruoho             return (NextNode);
    143      1.1    jruoho         }
    144      1.1    jruoho 
    145      1.1    jruoho         /* Otherwise, move on to the next peer node */
    146      1.1    jruoho 
    147      1.1    jruoho         NextNode = NextNode->Peer;
    148      1.1    jruoho     }
    149      1.1    jruoho 
    150      1.1    jruoho     /* Not found */
    151      1.1    jruoho 
    152      1.1    jruoho     return (NULL);
    153      1.1    jruoho }
    154      1.1    jruoho 
    155      1.1    jruoho 
    156      1.1    jruoho /*******************************************************************************
    157      1.1    jruoho  *
    158      1.1    jruoho  * FUNCTION:    AcpiNsWalkNamespace
    159      1.1    jruoho  *
    160      1.1    jruoho  * PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
    161      1.1    jruoho  *              StartNode           - Handle in namespace where search begins
    162      1.1    jruoho  *              MaxDepth            - Depth to which search is to reach
    163      1.1    jruoho  *              Flags               - Whether to unlock the NS before invoking
    164      1.1    jruoho  *                                    the callback routine
    165  1.1.1.3  christos  *              DescendingCallback  - Called during tree descent
    166      1.1    jruoho  *                                    when an object of "Type" is found
    167  1.1.1.3  christos  *              AscendingCallback   - Called during tree ascent
    168      1.1    jruoho  *                                    when an object of "Type" is found
    169      1.1    jruoho  *              Context             - Passed to user function(s) above
    170      1.1    jruoho  *              ReturnValue         - from the UserFunction if terminated
    171      1.1    jruoho  *                                    early. Otherwise, returns NULL.
    172      1.1    jruoho  * RETURNS:     Status
    173      1.1    jruoho  *
    174      1.1    jruoho  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
    175      1.1    jruoho  *              starting (and ending) at the node specified by StartHandle.
    176      1.1    jruoho  *              The callback function is called whenever a node that matches
    177      1.1    jruoho  *              the type parameter is found. If the callback function returns
    178      1.1    jruoho  *              a non-zero value, the search is terminated immediately and
    179      1.1    jruoho  *              this value is returned to the caller.
    180      1.1    jruoho  *
    181      1.1    jruoho  *              The point of this procedure is to provide a generic namespace
    182      1.1    jruoho  *              walk routine that can be called from multiple places to
    183      1.1    jruoho  *              provide multiple services; the callback function(s) can be
    184      1.1    jruoho  *              tailored to each task, whether it is a print function,
    185      1.1    jruoho  *              a compare function, etc.
    186      1.1    jruoho  *
    187      1.1    jruoho  ******************************************************************************/
    188      1.1    jruoho 
    189      1.1    jruoho ACPI_STATUS
    190      1.1    jruoho AcpiNsWalkNamespace (
    191      1.1    jruoho     ACPI_OBJECT_TYPE        Type,
    192      1.1    jruoho     ACPI_HANDLE             StartNode,
    193      1.1    jruoho     UINT32                  MaxDepth,
    194      1.1    jruoho     UINT32                  Flags,
    195  1.1.1.3  christos     ACPI_WALK_CALLBACK      DescendingCallback,
    196  1.1.1.3  christos     ACPI_WALK_CALLBACK      AscendingCallback,
    197      1.1    jruoho     void                    *Context,
    198      1.1    jruoho     void                    **ReturnValue)
    199      1.1    jruoho {
    200      1.1    jruoho     ACPI_STATUS             Status;
    201      1.1    jruoho     ACPI_STATUS             MutexStatus;
    202      1.1    jruoho     ACPI_NAMESPACE_NODE     *ChildNode;
    203      1.1    jruoho     ACPI_NAMESPACE_NODE     *ParentNode;
    204      1.1    jruoho     ACPI_OBJECT_TYPE        ChildType;
    205      1.1    jruoho     UINT32                  Level;
    206      1.1    jruoho     BOOLEAN                 NodePreviouslyVisited = FALSE;
    207      1.1    jruoho 
    208      1.1    jruoho 
    209      1.1    jruoho     ACPI_FUNCTION_TRACE (NsWalkNamespace);
    210      1.1    jruoho 
    211      1.1    jruoho 
    212      1.1    jruoho     /* Special case for the namespace Root Node */
    213      1.1    jruoho 
    214      1.1    jruoho     if (StartNode == ACPI_ROOT_OBJECT)
    215      1.1    jruoho     {
    216      1.1    jruoho         StartNode = AcpiGbl_RootNode;
    217      1.1    jruoho     }
    218      1.1    jruoho 
    219      1.1    jruoho     /* Null child means "get first node" */
    220      1.1    jruoho 
    221  1.1.1.6  christos     ParentNode = StartNode;
    222  1.1.1.6  christos     ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
    223  1.1.1.6  christos     ChildType = ACPI_TYPE_ANY;
    224  1.1.1.6  christos     Level = 1;
    225      1.1    jruoho 
    226      1.1    jruoho     /*
    227      1.1    jruoho      * Traverse the tree of nodes until we bubble back up to where we
    228      1.1    jruoho      * started. When Level is zero, the loop is done because we have
    229      1.1    jruoho      * bubbled up to (and passed) the original parent handle (StartEntry)
    230      1.1    jruoho      */
    231      1.1    jruoho     while (Level > 0 && ChildNode)
    232      1.1    jruoho     {
    233      1.1    jruoho         Status = AE_OK;
    234      1.1    jruoho 
    235      1.1    jruoho         /* Found next child, get the type if we are not searching for ANY */
    236      1.1    jruoho 
    237      1.1    jruoho         if (Type != ACPI_TYPE_ANY)
    238      1.1    jruoho         {
    239      1.1    jruoho             ChildType = ChildNode->Type;
    240      1.1    jruoho         }
    241      1.1    jruoho 
    242      1.1    jruoho         /*
    243      1.1    jruoho          * Ignore all temporary namespace nodes (created during control
    244      1.1    jruoho          * method execution) unless told otherwise. These temporary nodes
    245      1.1    jruoho          * can cause a race condition because they can be deleted during
    246      1.1    jruoho          * the execution of the user function (if the namespace is
    247      1.1    jruoho          * unlocked before invocation of the user function.) Only the
    248      1.1    jruoho          * debugger namespace dump will examine the temporary nodes.
    249      1.1    jruoho          */
    250      1.1    jruoho         if ((ChildNode->Flags & ANOBJ_TEMPORARY) &&
    251      1.1    jruoho             !(Flags & ACPI_NS_WALK_TEMP_NODES))
    252      1.1    jruoho         {
    253      1.1    jruoho             Status = AE_CTRL_DEPTH;
    254      1.1    jruoho         }
    255      1.1    jruoho 
    256      1.1    jruoho         /* Type must match requested type */
    257      1.1    jruoho 
    258      1.1    jruoho         else if (ChildType == Type)
    259      1.1    jruoho         {
    260      1.1    jruoho             /*
    261      1.1    jruoho              * Found a matching node, invoke the user callback function.
    262      1.1    jruoho              * Unlock the namespace if flag is set.
    263      1.1    jruoho              */
    264      1.1    jruoho             if (Flags & ACPI_NS_WALK_UNLOCK)
    265      1.1    jruoho             {
    266      1.1    jruoho                 MutexStatus = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
    267      1.1    jruoho                 if (ACPI_FAILURE (MutexStatus))
    268      1.1    jruoho                 {
    269      1.1    jruoho                     return_ACPI_STATUS (MutexStatus);
    270      1.1    jruoho                 }
    271      1.1    jruoho             }
    272      1.1    jruoho 
    273      1.1    jruoho             /*
    274  1.1.1.3  christos              * Invoke the user function, either descending, ascending,
    275      1.1    jruoho              * or both.
    276      1.1    jruoho              */
    277      1.1    jruoho             if (!NodePreviouslyVisited)
    278      1.1    jruoho             {
    279  1.1.1.3  christos                 if (DescendingCallback)
    280      1.1    jruoho                 {
    281  1.1.1.3  christos                     Status = DescendingCallback (ChildNode, Level,
    282  1.1.1.6  christos                         Context, ReturnValue);
    283      1.1    jruoho                 }
    284      1.1    jruoho             }
    285      1.1    jruoho             else
    286      1.1    jruoho             {
    287  1.1.1.3  christos                 if (AscendingCallback)
    288      1.1    jruoho                 {
    289  1.1.1.3  christos                     Status = AscendingCallback (ChildNode, Level,
    290  1.1.1.6  christos                         Context, ReturnValue);
    291      1.1    jruoho                 }
    292      1.1    jruoho             }
    293      1.1    jruoho 
    294      1.1    jruoho             if (Flags & ACPI_NS_WALK_UNLOCK)
    295      1.1    jruoho             {
    296      1.1    jruoho                 MutexStatus = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
    297      1.1    jruoho                 if (ACPI_FAILURE (MutexStatus))
    298      1.1    jruoho                 {
    299      1.1    jruoho                     return_ACPI_STATUS (MutexStatus);
    300      1.1    jruoho                 }
    301      1.1    jruoho             }
    302      1.1    jruoho 
    303      1.1    jruoho             switch (Status)
    304      1.1    jruoho             {
    305      1.1    jruoho             case AE_OK:
    306      1.1    jruoho             case AE_CTRL_DEPTH:
    307      1.1    jruoho 
    308      1.1    jruoho                 /* Just keep going */
    309      1.1    jruoho                 break;
    310      1.1    jruoho 
    311      1.1    jruoho             case AE_CTRL_TERMINATE:
    312      1.1    jruoho 
    313      1.1    jruoho                 /* Exit now, with OK status */
    314      1.1    jruoho 
    315      1.1    jruoho                 return_ACPI_STATUS (AE_OK);
    316      1.1    jruoho 
    317      1.1    jruoho             default:
    318      1.1    jruoho 
    319      1.1    jruoho                 /* All others are valid exceptions */
    320      1.1    jruoho 
    321      1.1    jruoho                 return_ACPI_STATUS (Status);
    322      1.1    jruoho             }
    323      1.1    jruoho         }
    324      1.1    jruoho 
    325      1.1    jruoho         /*
    326      1.1    jruoho          * Depth first search: Attempt to go down another level in the
    327  1.1.1.3  christos          * namespace if we are allowed to. Don't go any further if we have
    328      1.1    jruoho          * reached the caller specified maximum depth or if the user
    329      1.1    jruoho          * function has specified that the maximum depth has been reached.
    330      1.1    jruoho          */
    331      1.1    jruoho         if (!NodePreviouslyVisited &&
    332      1.1    jruoho             (Level < MaxDepth) &&
    333      1.1    jruoho             (Status != AE_CTRL_DEPTH))
    334      1.1    jruoho         {
    335      1.1    jruoho             if (ChildNode->Child)
    336      1.1    jruoho             {
    337      1.1    jruoho                 /* There is at least one child of this node, visit it */
    338      1.1    jruoho 
    339      1.1    jruoho                 Level++;
    340      1.1    jruoho                 ParentNode = ChildNode;
    341      1.1    jruoho                 ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
    342      1.1    jruoho                 continue;
    343      1.1    jruoho             }
    344      1.1    jruoho         }
    345      1.1    jruoho 
    346      1.1    jruoho         /* No more children, re-visit this node */
    347      1.1    jruoho 
    348      1.1    jruoho         if (!NodePreviouslyVisited)
    349      1.1    jruoho         {
    350      1.1    jruoho             NodePreviouslyVisited = TRUE;
    351      1.1    jruoho             continue;
    352      1.1    jruoho         }
    353      1.1    jruoho 
    354      1.1    jruoho         /* No more children, visit peers */
    355      1.1    jruoho 
    356      1.1    jruoho         ChildNode = AcpiNsGetNextNode (ParentNode, ChildNode);
    357      1.1    jruoho         if (ChildNode)
    358      1.1    jruoho         {
    359      1.1    jruoho             NodePreviouslyVisited = FALSE;
    360      1.1    jruoho         }
    361      1.1    jruoho 
    362      1.1    jruoho         /* No peers, re-visit parent */
    363      1.1    jruoho 
    364      1.1    jruoho         else
    365      1.1    jruoho         {
    366      1.1    jruoho             /*
    367      1.1    jruoho              * No more children of this node (AcpiNsGetNextNode failed), go
    368      1.1    jruoho              * back upwards in the namespace tree to the node's parent.
    369      1.1    jruoho              */
    370      1.1    jruoho             Level--;
    371      1.1    jruoho             ChildNode = ParentNode;
    372      1.1    jruoho             ParentNode = ParentNode->Parent;
    373      1.1    jruoho 
    374      1.1    jruoho             NodePreviouslyVisited = TRUE;
    375      1.1    jruoho         }
    376      1.1    jruoho     }
    377      1.1    jruoho 
    378      1.1    jruoho     /* Complete walk, not terminated by user function */
    379      1.1    jruoho 
    380      1.1    jruoho     return_ACPI_STATUS (AE_OK);
    381      1.1    jruoho }
    382