Home | History | Annotate | Line # | Download | only in namespace
nswalk.c revision 1.1.1.4
      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.4  christos  * Copyright (C) 2000 - 2014, 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 #define __NSWALK_C__
     45      1.1    jruoho 
     46      1.1    jruoho #include "acpi.h"
     47      1.1    jruoho #include "accommon.h"
     48      1.1    jruoho #include "acnamesp.h"
     49      1.1    jruoho 
     50      1.1    jruoho 
     51      1.1    jruoho #define _COMPONENT          ACPI_NAMESPACE
     52      1.1    jruoho         ACPI_MODULE_NAME    ("nswalk")
     53      1.1    jruoho 
     54      1.1    jruoho 
     55      1.1    jruoho /*******************************************************************************
     56      1.1    jruoho  *
     57      1.1    jruoho  * FUNCTION:    AcpiNsGetNextNode
     58      1.1    jruoho  *
     59      1.1    jruoho  * PARAMETERS:  ParentNode          - Parent node whose children we are
     60      1.1    jruoho  *                                    getting
     61      1.1    jruoho  *              ChildNode           - Previous child that was found.
     62      1.1    jruoho  *                                    The NEXT child will be returned
     63      1.1    jruoho  *
     64      1.1    jruoho  * RETURN:      ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
     65      1.1    jruoho  *                                    none is found.
     66      1.1    jruoho  *
     67  1.1.1.3  christos  * DESCRIPTION: Return the next peer node within the namespace. If Handle
     68  1.1.1.3  christos  *              is valid, Scope is ignored. Otherwise, the first node
     69      1.1    jruoho  *              within Scope is returned.
     70      1.1    jruoho  *
     71      1.1    jruoho  ******************************************************************************/
     72      1.1    jruoho 
     73      1.1    jruoho ACPI_NAMESPACE_NODE *
     74      1.1    jruoho AcpiNsGetNextNode (
     75      1.1    jruoho     ACPI_NAMESPACE_NODE     *ParentNode,
     76      1.1    jruoho     ACPI_NAMESPACE_NODE     *ChildNode)
     77      1.1    jruoho {
     78      1.1    jruoho     ACPI_FUNCTION_ENTRY ();
     79      1.1    jruoho 
     80      1.1    jruoho 
     81      1.1    jruoho     if (!ChildNode)
     82      1.1    jruoho     {
     83      1.1    jruoho         /* It's really the parent's _scope_ that we want */
     84      1.1    jruoho 
     85      1.1    jruoho         return (ParentNode->Child);
     86      1.1    jruoho     }
     87      1.1    jruoho 
     88      1.1    jruoho     /* Otherwise just return the next peer */
     89      1.1    jruoho 
     90      1.1    jruoho     return (ChildNode->Peer);
     91      1.1    jruoho }
     92      1.1    jruoho 
     93      1.1    jruoho 
     94      1.1    jruoho /*******************************************************************************
     95      1.1    jruoho  *
     96      1.1    jruoho  * FUNCTION:    AcpiNsGetNextNodeTyped
     97      1.1    jruoho  *
     98      1.1    jruoho  * PARAMETERS:  Type                - Type of node to be searched for
     99      1.1    jruoho  *              ParentNode          - Parent node whose children we are
    100      1.1    jruoho  *                                    getting
    101      1.1    jruoho  *              ChildNode           - Previous child that was found.
    102      1.1    jruoho  *                                    The NEXT child will be returned
    103      1.1    jruoho  *
    104      1.1    jruoho  * RETURN:      ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
    105      1.1    jruoho  *                                    none is found.
    106      1.1    jruoho  *
    107  1.1.1.3  christos  * DESCRIPTION: Return the next peer node within the namespace. If Handle
    108  1.1.1.3  christos  *              is valid, Scope is ignored. Otherwise, the first node
    109      1.1    jruoho  *              within Scope is returned.
    110      1.1    jruoho  *
    111      1.1    jruoho  ******************************************************************************/
    112      1.1    jruoho 
    113      1.1    jruoho ACPI_NAMESPACE_NODE *
    114      1.1    jruoho AcpiNsGetNextNodeTyped (
    115      1.1    jruoho     ACPI_OBJECT_TYPE        Type,
    116      1.1    jruoho     ACPI_NAMESPACE_NODE     *ParentNode,
    117      1.1    jruoho     ACPI_NAMESPACE_NODE     *ChildNode)
    118      1.1    jruoho {
    119      1.1    jruoho     ACPI_NAMESPACE_NODE     *NextNode = NULL;
    120      1.1    jruoho 
    121      1.1    jruoho 
    122      1.1    jruoho     ACPI_FUNCTION_ENTRY ();
    123      1.1    jruoho 
    124      1.1    jruoho 
    125      1.1    jruoho     NextNode = AcpiNsGetNextNode (ParentNode, ChildNode);
    126      1.1    jruoho 
    127      1.1    jruoho     /* If any type is OK, we are done */
    128      1.1    jruoho 
    129      1.1    jruoho     if (Type == ACPI_TYPE_ANY)
    130      1.1    jruoho     {
    131      1.1    jruoho         /* NextNode is NULL if we are at the end-of-list */
    132      1.1    jruoho 
    133      1.1    jruoho         return (NextNode);
    134      1.1    jruoho     }
    135      1.1    jruoho 
    136      1.1    jruoho     /* Must search for the node -- but within this scope only */
    137      1.1    jruoho 
    138      1.1    jruoho     while (NextNode)
    139      1.1    jruoho     {
    140      1.1    jruoho         /* If type matches, we are done */
    141      1.1    jruoho 
    142      1.1    jruoho         if (NextNode->Type == Type)
    143      1.1    jruoho         {
    144      1.1    jruoho             return (NextNode);
    145      1.1    jruoho         }
    146      1.1    jruoho 
    147      1.1    jruoho         /* Otherwise, move on to the next peer node */
    148      1.1    jruoho 
    149      1.1    jruoho         NextNode = NextNode->Peer;
    150      1.1    jruoho     }
    151      1.1    jruoho 
    152      1.1    jruoho     /* Not found */
    153      1.1    jruoho 
    154      1.1    jruoho     return (NULL);
    155      1.1    jruoho }
    156      1.1    jruoho 
    157      1.1    jruoho 
    158      1.1    jruoho /*******************************************************************************
    159      1.1    jruoho  *
    160      1.1    jruoho  * FUNCTION:    AcpiNsWalkNamespace
    161      1.1    jruoho  *
    162      1.1    jruoho  * PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
    163      1.1    jruoho  *              StartNode           - Handle in namespace where search begins
    164      1.1    jruoho  *              MaxDepth            - Depth to which search is to reach
    165      1.1    jruoho  *              Flags               - Whether to unlock the NS before invoking
    166      1.1    jruoho  *                                    the callback routine
    167  1.1.1.3  christos  *              DescendingCallback  - Called during tree descent
    168      1.1    jruoho  *                                    when an object of "Type" is found
    169  1.1.1.3  christos  *              AscendingCallback   - Called during tree ascent
    170      1.1    jruoho  *                                    when an object of "Type" is found
    171      1.1    jruoho  *              Context             - Passed to user function(s) above
    172      1.1    jruoho  *              ReturnValue         - from the UserFunction if terminated
    173      1.1    jruoho  *                                    early. Otherwise, returns NULL.
    174      1.1    jruoho  * RETURNS:     Status
    175      1.1    jruoho  *
    176      1.1    jruoho  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
    177      1.1    jruoho  *              starting (and ending) at the node specified by StartHandle.
    178      1.1    jruoho  *              The callback function is called whenever a node that matches
    179      1.1    jruoho  *              the type parameter is found. If the callback function returns
    180      1.1    jruoho  *              a non-zero value, the search is terminated immediately and
    181      1.1    jruoho  *              this value is returned to the caller.
    182      1.1    jruoho  *
    183      1.1    jruoho  *              The point of this procedure is to provide a generic namespace
    184      1.1    jruoho  *              walk routine that can be called from multiple places to
    185      1.1    jruoho  *              provide multiple services; the callback function(s) can be
    186      1.1    jruoho  *              tailored to each task, whether it is a print function,
    187      1.1    jruoho  *              a compare function, etc.
    188      1.1    jruoho  *
    189      1.1    jruoho  ******************************************************************************/
    190      1.1    jruoho 
    191      1.1    jruoho ACPI_STATUS
    192      1.1    jruoho AcpiNsWalkNamespace (
    193      1.1    jruoho     ACPI_OBJECT_TYPE        Type,
    194      1.1    jruoho     ACPI_HANDLE             StartNode,
    195      1.1    jruoho     UINT32                  MaxDepth,
    196      1.1    jruoho     UINT32                  Flags,
    197  1.1.1.3  christos     ACPI_WALK_CALLBACK      DescendingCallback,
    198  1.1.1.3  christos     ACPI_WALK_CALLBACK      AscendingCallback,
    199      1.1    jruoho     void                    *Context,
    200      1.1    jruoho     void                    **ReturnValue)
    201      1.1    jruoho {
    202      1.1    jruoho     ACPI_STATUS             Status;
    203      1.1    jruoho     ACPI_STATUS             MutexStatus;
    204      1.1    jruoho     ACPI_NAMESPACE_NODE     *ChildNode;
    205      1.1    jruoho     ACPI_NAMESPACE_NODE     *ParentNode;
    206      1.1    jruoho     ACPI_OBJECT_TYPE        ChildType;
    207      1.1    jruoho     UINT32                  Level;
    208      1.1    jruoho     BOOLEAN                 NodePreviouslyVisited = FALSE;
    209      1.1    jruoho 
    210      1.1    jruoho 
    211      1.1    jruoho     ACPI_FUNCTION_TRACE (NsWalkNamespace);
    212      1.1    jruoho 
    213      1.1    jruoho 
    214      1.1    jruoho     /* Special case for the namespace Root Node */
    215      1.1    jruoho 
    216      1.1    jruoho     if (StartNode == ACPI_ROOT_OBJECT)
    217      1.1    jruoho     {
    218      1.1    jruoho         StartNode = AcpiGbl_RootNode;
    219      1.1    jruoho     }
    220      1.1    jruoho 
    221      1.1    jruoho     /* Null child means "get first node" */
    222      1.1    jruoho 
    223      1.1    jruoho     ParentNode  = StartNode;
    224      1.1    jruoho     ChildNode   = AcpiNsGetNextNode (ParentNode, NULL);
    225      1.1    jruoho     ChildType   = ACPI_TYPE_ANY;
    226      1.1    jruoho     Level       = 1;
    227      1.1    jruoho 
    228      1.1    jruoho     /*
    229      1.1    jruoho      * Traverse the tree of nodes until we bubble back up to where we
    230      1.1    jruoho      * started. When Level is zero, the loop is done because we have
    231      1.1    jruoho      * bubbled up to (and passed) the original parent handle (StartEntry)
    232      1.1    jruoho      */
    233      1.1    jruoho     while (Level > 0 && ChildNode)
    234      1.1    jruoho     {
    235      1.1    jruoho         Status = AE_OK;
    236      1.1    jruoho 
    237      1.1    jruoho         /* Found next child, get the type if we are not searching for ANY */
    238      1.1    jruoho 
    239      1.1    jruoho         if (Type != ACPI_TYPE_ANY)
    240      1.1    jruoho         {
    241      1.1    jruoho             ChildType = ChildNode->Type;
    242      1.1    jruoho         }
    243      1.1    jruoho 
    244      1.1    jruoho         /*
    245      1.1    jruoho          * Ignore all temporary namespace nodes (created during control
    246      1.1    jruoho          * method execution) unless told otherwise. These temporary nodes
    247      1.1    jruoho          * can cause a race condition because they can be deleted during
    248      1.1    jruoho          * the execution of the user function (if the namespace is
    249      1.1    jruoho          * unlocked before invocation of the user function.) Only the
    250      1.1    jruoho          * debugger namespace dump will examine the temporary nodes.
    251      1.1    jruoho          */
    252      1.1    jruoho         if ((ChildNode->Flags & ANOBJ_TEMPORARY) &&
    253      1.1    jruoho             !(Flags & ACPI_NS_WALK_TEMP_NODES))
    254      1.1    jruoho         {
    255      1.1    jruoho             Status = AE_CTRL_DEPTH;
    256      1.1    jruoho         }
    257      1.1    jruoho 
    258      1.1    jruoho         /* Type must match requested type */
    259      1.1    jruoho 
    260      1.1    jruoho         else if (ChildType == Type)
    261      1.1    jruoho         {
    262      1.1    jruoho             /*
    263      1.1    jruoho              * Found a matching node, invoke the user callback function.
    264      1.1    jruoho              * Unlock the namespace if flag is set.
    265      1.1    jruoho              */
    266      1.1    jruoho             if (Flags & ACPI_NS_WALK_UNLOCK)
    267      1.1    jruoho             {
    268      1.1    jruoho                 MutexStatus = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
    269      1.1    jruoho                 if (ACPI_FAILURE (MutexStatus))
    270      1.1    jruoho                 {
    271      1.1    jruoho                     return_ACPI_STATUS (MutexStatus);
    272      1.1    jruoho                 }
    273      1.1    jruoho             }
    274      1.1    jruoho 
    275      1.1    jruoho             /*
    276  1.1.1.3  christos              * Invoke the user function, either descending, ascending,
    277      1.1    jruoho              * or both.
    278      1.1    jruoho              */
    279      1.1    jruoho             if (!NodePreviouslyVisited)
    280      1.1    jruoho             {
    281  1.1.1.3  christos                 if (DescendingCallback)
    282      1.1    jruoho                 {
    283  1.1.1.3  christos                     Status = DescendingCallback (ChildNode, Level,
    284      1.1    jruoho                                 Context, ReturnValue);
    285      1.1    jruoho                 }
    286      1.1    jruoho             }
    287      1.1    jruoho             else
    288      1.1    jruoho             {
    289  1.1.1.3  christos                 if (AscendingCallback)
    290      1.1    jruoho                 {
    291  1.1.1.3  christos                     Status = AscendingCallback (ChildNode, Level,
    292      1.1    jruoho                                 Context, ReturnValue);
    293      1.1    jruoho                 }
    294      1.1    jruoho             }
    295      1.1    jruoho 
    296      1.1    jruoho             if (Flags & ACPI_NS_WALK_UNLOCK)
    297      1.1    jruoho             {
    298      1.1    jruoho                 MutexStatus = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
    299      1.1    jruoho                 if (ACPI_FAILURE (MutexStatus))
    300      1.1    jruoho                 {
    301      1.1    jruoho                     return_ACPI_STATUS (MutexStatus);
    302      1.1    jruoho                 }
    303      1.1    jruoho             }
    304      1.1    jruoho 
    305      1.1    jruoho             switch (Status)
    306      1.1    jruoho             {
    307      1.1    jruoho             case AE_OK:
    308      1.1    jruoho             case AE_CTRL_DEPTH:
    309      1.1    jruoho 
    310      1.1    jruoho                 /* Just keep going */
    311      1.1    jruoho                 break;
    312      1.1    jruoho 
    313      1.1    jruoho             case AE_CTRL_TERMINATE:
    314      1.1    jruoho 
    315      1.1    jruoho                 /* Exit now, with OK status */
    316      1.1    jruoho 
    317      1.1    jruoho                 return_ACPI_STATUS (AE_OK);
    318      1.1    jruoho 
    319      1.1    jruoho             default:
    320      1.1    jruoho 
    321      1.1    jruoho                 /* All others are valid exceptions */
    322      1.1    jruoho 
    323      1.1    jruoho                 return_ACPI_STATUS (Status);
    324      1.1    jruoho             }
    325      1.1    jruoho         }
    326      1.1    jruoho 
    327      1.1    jruoho         /*
    328      1.1    jruoho          * Depth first search: Attempt to go down another level in the
    329  1.1.1.3  christos          * namespace if we are allowed to. Don't go any further if we have
    330      1.1    jruoho          * reached the caller specified maximum depth or if the user
    331      1.1    jruoho          * function has specified that the maximum depth has been reached.
    332      1.1    jruoho          */
    333      1.1    jruoho         if (!NodePreviouslyVisited &&
    334      1.1    jruoho             (Level < MaxDepth) &&
    335      1.1    jruoho             (Status != AE_CTRL_DEPTH))
    336      1.1    jruoho         {
    337      1.1    jruoho             if (ChildNode->Child)
    338      1.1    jruoho             {
    339      1.1    jruoho                 /* There is at least one child of this node, visit it */
    340      1.1    jruoho 
    341      1.1    jruoho                 Level++;
    342      1.1    jruoho                 ParentNode = ChildNode;
    343      1.1    jruoho                 ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
    344      1.1    jruoho                 continue;
    345      1.1    jruoho             }
    346      1.1    jruoho         }
    347      1.1    jruoho 
    348      1.1    jruoho         /* No more children, re-visit this node */
    349      1.1    jruoho 
    350      1.1    jruoho         if (!NodePreviouslyVisited)
    351      1.1    jruoho         {
    352      1.1    jruoho             NodePreviouslyVisited = TRUE;
    353      1.1    jruoho             continue;
    354      1.1    jruoho         }
    355      1.1    jruoho 
    356      1.1    jruoho         /* No more children, visit peers */
    357      1.1    jruoho 
    358      1.1    jruoho         ChildNode = AcpiNsGetNextNode (ParentNode, ChildNode);
    359      1.1    jruoho         if (ChildNode)
    360      1.1    jruoho         {
    361      1.1    jruoho             NodePreviouslyVisited = FALSE;
    362      1.1    jruoho         }
    363      1.1    jruoho 
    364      1.1    jruoho         /* No peers, re-visit parent */
    365      1.1    jruoho 
    366      1.1    jruoho         else
    367      1.1    jruoho         {
    368      1.1    jruoho             /*
    369      1.1    jruoho              * No more children of this node (AcpiNsGetNextNode failed), go
    370      1.1    jruoho              * back upwards in the namespace tree to the node's parent.
    371      1.1    jruoho              */
    372      1.1    jruoho             Level--;
    373      1.1    jruoho             ChildNode = ParentNode;
    374      1.1    jruoho             ParentNode = ParentNode->Parent;
    375      1.1    jruoho 
    376      1.1    jruoho             NodePreviouslyVisited = TRUE;
    377      1.1    jruoho         }
    378      1.1    jruoho     }
    379      1.1    jruoho 
    380      1.1    jruoho     /* Complete walk, not terminated by user function */
    381      1.1    jruoho 
    382      1.1    jruoho     return_ACPI_STATUS (AE_OK);
    383      1.1    jruoho }
    384