zircon/third_party/lib/acpica/source/components/namespace/nsxfeval.c
/*******************************************************************************
 *
 * FUNCTION:    AcpiWalkNamespace
 *
 * PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
 *              StartObject         - Handle in namespace where search begins
 *              MaxDepth            - Depth to which search is to reach
 *              DescendingCallback  - Called during tree descent
 *                                    when an object of "Type" is found
 *              AscendingCallback   - Called during tree ascent
 *                                    when an object of "Type" is found
 *              Context             - Passed to user function(s) above
 *              ReturnValue         - Location where return value of
 *                                    UserFunction is put if terminated early
 *
 * RETURNS      Return value from the UserFunction if terminated early.
 *              Otherwise, returns NULL.
 *
 * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 *              starting (and ending) at the object specified by StartHandle.
 *              The callback function is called whenever an object that matches
 *              the type parameter is found. If the callback function returns
 *              a non-zero value, the search is terminated immediately and this
 *              value is returned to the caller.
 *
 *              The point of this procedure is to provide a generic namespace
 *              walk routine that can be called from multiple places to
 *              provide multiple services; the callback function(s) can be
 *              tailored to each task, whether it is a print function,
 *              a compare function, etc.
 *
 ******************************************************************************/


RETURNS      Return value from the UserFunction if terminated early.
Otherwise, returns NULL.

Performs a modified depth-first walk of the namespace tree,
starting (and ending) at the object specified by StartHandle.
The callback function is called whenever an object that matches
the type parameter is found. If the callback function returns
a non-zero value, the search is terminated immediately and this
value is returned to the caller.

The point of this procedure is to provide a generic namespace
walk routine that can be called from multiple places to
provide multiple services; the callback function(s) can be
tailored to each task, whether it is a print function,
a compare function, etc.
RETURNS Return value from the UserFunction if terminated early . Otherwise returns NULL . Performs a modified depth - first walk of the namespace tree starting ( and ending ) at the object specified by StartHandle . The callback function is called whenever an object that matches the type parameter is found . If the callback function returns a non - zero value the search is terminated immediately and this value is returned to the caller . The point of this procedure is to provide a generic namespace walk routine that can be called from multiple places to provide multiple services ; the callback function ( s ) can be tailored to each task whether it is a print function a compare function etc .
ACPI_STATUS
AcpiWalkNamespace (
    ACPI_OBJECT_TYPE        Type,
    ACPI_HANDLE             StartObject,
    UINT32                  MaxDepth,
    ACPI_WALK_CALLBACK      DescendingCallback,
    ACPI_WALK_CALLBACK      AscendingCallback,
    void                    *Context,
    void                    **ReturnValue)
{
    ACPI_STATUS             Status;
    ACPI_FUNCTION_TRACE (AcpiWalkNamespace);
    if ((Type > ACPI_TYPE_LOCAL_MAX) ||
        (!MaxDepth)                  ||
        (!DescendingCallback && !AscendingCallback))
    {
        return_ACPI_STATUS (AE_BAD_PARAMETER);
    }
    Status = AcpiUtAcquireReadLock (&AcpiGbl_NamespaceRwLock);
    if (ACPI_FAILURE (Status))
    {
        return_ACPI_STATUS (Status);
    }
    Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
    if (ACPI_FAILURE (Status))
    {
        goto UnlockAndExit;
    }
    if (!AcpiNsValidateHandle (StartObject))
    {
        Status = AE_BAD_PARAMETER;
        goto UnlockAndExit2;
    }
    Status = AcpiNsWalkNamespace (Type, StartObject, MaxDepth,
        ACPI_NS_WALK_UNLOCK, DescendingCallback,
        AscendingCallback, Context, ReturnValue);
UnlockAndExit2:
    (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
UnlockAndExit:
    (void) AcpiUtReleaseReadLock (&AcpiGbl_NamespaceRwLock);
    return_ACPI_STATUS (Status);
}
ACPI_STATUS AcpiWalkNamespace ( ACPI_OBJECT_TYPE Type , ACPI_HANDLE StartObject , UINT32 MaxDepth , ACPI_WALK_CALLBACK DescendingCallback , ACPI_WALK_CALLBACK AscendingCallback , void * Context , void * * ReturnValue ) { ACPI_STATUS Status ; ACPI_FUNCTION_TRACE ( AcpiWalkNamespace ) ; if ( ( Type > ACPI_TYPE_LOCAL_MAX ) || ( ! MaxDepth ) || ( ! DescendingCallback && ! AscendingCallback ) ) { return_ACPI_STATUS ( AE_BAD_PARAMETER ) ; } Status = AcpiUtAcquireReadLock ( & AcpiGbl_NamespaceRwLock ) ; if ( ACPI_FAILURE ( Status ) ) { return_ACPI_STATUS ( Status ) ; } Status = AcpiUtAcquireMutex ( ACPI_MTX_NAMESPACE ) ; if ( ACPI_FAILURE ( Status ) ) { goto UnlockAndExit ; } if ( ! AcpiNsValidateHandle ( StartObject ) ) { Status = AE_BAD_PARAMETER ; goto UnlockAndExit2 ; } Status = AcpiNsWalkNamespace ( Type , StartObject , MaxDepth , ACPI_NS_WALK_UNLOCK , DescendingCallback , AscendingCallback , Context , ReturnValue ) ; UnlockAndExit2 : ( void ) AcpiUtReleaseMutex ( ACPI_MTX_NAMESPACE ) ; UnlockAndExit : ( void ) AcpiUtReleaseReadLock ( & AcpiGbl_NamespaceRwLock ) ; return_ACPI_STATUS ( Status ) ; }
FUNCTION:    AcpiWalkNamespace
 PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
              StartObject         - Handle in namespace where search begins
              MaxDepth            - Depth to which search is to reach
              DescendingCallback  - Called during tree descent
                                    when an object of "Type" is found
              AscendingCallback   - Called during tree ascent
                                    when an object of "Type" is found
              Context             - Passed to user function(s) above
              ReturnValue         - Location where return value of
                                    UserFunction is put if terminated early
FUNCTION : AcpiWalkNamespace PARAMETERS : Type - ACPI_OBJECT_TYPE to search for StartObject - Handle in namespace where search begins MaxDepth - Depth to which search is to reach DescendingCallback - Called during tree descent when an object of " Type " is found AscendingCallback - Called during tree ascent when an object of " Type " is found Context - Passed to user function ( s ) above ReturnValue - Location where return value of UserFunction is put if terminated early
/* Parameter validation */ /*
     * Need to acquire the namespace reader lock to prevent interference
     * with any concurrent table unloads (which causes the deletion of
     * namespace objects). We cannot allow the deletion of a namespace node
     * while the user function is using it. The exception to this are the
     * nodes created and deleted during control method execution -- these
     * nodes are marked as temporary nodes and are ignored by the namespace
     * walk. Thus, control methods can be executed while holding the
     * namespace deletion lock (and the user function can execute control
     * methods.)
     */ /*
     * Lock the namespace around the walk. The namespace will be
     * unlocked/locked around each call to the user function - since the user
     * function must be allowed to make ACPICA calls itself (for example, it
     * will typically execute control methods during device enumeration.)
     */ /* Now we can validate the starting node */