sys/contrib/dev/acpica/nsxfeval.c

   1 /*******************************************************************************
   2  *
   3  * Module Name: nsxfeval - Public interfaces to the ACPI subsystem
   4  *                         ACPI Object evaluation interfaces
   5  *              $Revision: 7 $
   6  *
   7  ******************************************************************************/
   8
   9 /******************************************************************************
  10  *
  11  * 1. Copyright Notice
  12  *
  13  * Some or all of this work - Copyright (c) 1999 - 2003, Intel Corp.
  14  * All rights reserved.
  15  *
  16  * 2. License
  17  *
  18  * 2.1. This is your license from Intel Corp. under its intellectual property
  19  * rights.  You may have additional license terms from the party that provided
  20  * you this software, covering your right to use that party's intellectual
  21  * property rights.
  22  *
  23  * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
  24  * copy of the source code appearing in this file ("Covered Code") an
  25  * irrevocable, perpetual, worldwide license under Intel's copyrights in the
  26  * base code distributed originally by Intel ("Original Intel Code") to copy,
  27  * make derivatives, distribute, use and display any portion of the Covered
  28  * Code in any form, with the right to sublicense such rights; and
  29  *
  30  * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
  31  * license (with the right to sublicense), under only those claims of Intel
  32  * patents that are infringed by the Original Intel Code, to make, use, sell,
  33  * offer to sell, and import the Covered Code and derivative works thereof
  34  * solely to the minimum extent necessary to exercise the above copyright
  35  * license, and in no event shall the patent license extend to any additions
  36  * to or modifications of the Original Intel Code.  No other license or right
  37  * is granted directly or by implication, estoppel or otherwise;
  38  *
  39  * The above copyright and patent license is granted only if the following
  40  * conditions are met:
  41  *
  42  * 3. Conditions
  43  *
  44  * 3.1. Redistribution of Source with Rights to Further Distribute Source.
  45  * Redistribution of source code of any substantial portion of the Covered
  46  * Code or modification with rights to further distribute source must include
  47  * the above Copyright Notice, the above License, this list of Conditions,
  48  * and the following Disclaimer and Export Compliance provision.  In addition,
  49  * Licensee must cause all Covered Code to which Licensee contributes to
  50  * contain a file documenting the changes Licensee made to create that Covered
  51  * Code and the date of any change.  Licensee must include in that file the
  52  * documentation of any changes made by any predecessor Licensee.  Licensee
  53  * must include a prominent statement that the modification is derived,
  54  * directly or indirectly, from Original Intel Code.
  55  *
  56  * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
  57  * Redistribution of source code of any substantial portion of the Covered
  58  * Code or modification without rights to further distribute source must
  59  * include the following Disclaimer and Export Compliance provision in the
  60  * documentation and/or other materials provided with distribution.  In
  61  * addition, Licensee may not authorize further sublicense of source of any
  62  * portion of the Covered Code, and must include terms to the effect that the
  63  * license from Licensee to its licensee is limited to the intellectual
  64  * property embodied in the software Licensee provides to its licensee, and
  65  * not to intellectual property embodied in modifications its licensee may
  66  * make.
  67  *
  68  * 3.3. Redistribution of Executable. Redistribution in executable form of any
  69  * substantial portion of the Covered Code or modification must reproduce the
  70  * above Copyright Notice, and the following Disclaimer and Export Compliance
  71  * provision in the documentation and/or other materials provided with the
  72  * distribution.
  73  *
  74  * 3.4. Intel retains all right, title, and interest in and to the Original
  75  * Intel Code.
  76  *
  77  * 3.5. Neither the name Intel nor any other trademark owned or controlled by
  78  * Intel shall be used in advertising or otherwise to promote the sale, use or
  79  * other dealings in products derived from or relating to the Covered Code
  80  * without prior written authorization from Intel.
  81  *
  82  * 4. Disclaimer and Export Compliance
  83  *
  84  * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
  85  * HERE.  ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
  86  * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT,  ASSISTANCE,
  87  * INSTALLATION, TRAINING OR OTHER SERVICES.  INTEL WILL NOT PROVIDE ANY
  88  * UPDATES, ENHANCEMENTS OR EXTENSIONS.  INTEL SPECIFICALLY DISCLAIMS ANY
  89  * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
  90  * PARTICULAR PURPOSE.
  91  *
  92  * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
  93  * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
  94  * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
  95  * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
  96  * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
  97  * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS
  98  * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
  99  * LIMITED REMEDY.
 100  *
 101  * 4.3. Licensee shall not export, either directly or indirectly, any of this
 102  * software or system incorporating such software without first obtaining any
 103  * required license or other approval from the U. S. Department of Commerce or
 104  * any other agency or department of the United States Government.  In the
 105  * event Licensee exports any such software from the United States or
 106  * re-exports any such software from a foreign destination, Licensee shall
 107  * ensure that the distribution and export/re-export of the software is in
 108  * compliance with all laws, regulations, orders, or other restrictions of the
 109  * U.S. Export Administration Regulations. Licensee agrees that neither it nor
 110  * any of its subsidiaries will export/re-export any technical data, process,
 111  * software, or service, directly or indirectly, to any country for which the
 112  * United States government or any agency thereof requires an export license,
 113  * other governmental approval, or letter of assurance, without first obtaining
 114  * such license, approval or letter.
 115  *
 116  *****************************************************************************/
 117 /* $DragonFly: src/sys/contrib/dev/acpica/Attic/nsxfeval.c,v 1.1 2003/09/24 03:32:16 drhodus Exp $                                                               */
 118
 119
 120 #define __NSXFEVAL_C__
 121
 122 #include "acpi.h"
 123 #include "acnamesp.h"
 124
 125
 126 #define _COMPONENT          ACPI_NAMESPACE
 127         ACPI_MODULE_NAME    ("nsxfeval")
 128
 129
 130 /*******************************************************************************
 131  *
 132  * FUNCTION:    AcpiEvaluateObjectTyped
 133  *
 134  * PARAMETERS:  Handle              - Object handle (optional)
 135  *              *Pathname           - Object pathname (optional)
 136  *              **ExternalParams    - List of parameters to pass to method,
 137  *                                    terminated by NULL.  May be NULL
 138  *                                    if no parameters are being passed.
 139  *              *ReturnBuffer       - Where to put method's return value (if
 140  *                                    any).  If NULL, no value is returned.
 141  *              ReturnType          - Expected type of return object
 142  *
 143  * RETURN:      Status
 144  *
 145  * DESCRIPTION: Find and evaluate the given object, passing the given
 146  *              parameters if necessary.  One of "Handle" or "Pathname" must
 147  *              be valid (non-null)
 148  *
 149  ******************************************************************************/
 150
 151 ACPI_STATUS
 152 AcpiEvaluateObjectTyped (
 153     ACPI_HANDLE             Handle,
 154     ACPI_STRING             Pathname,
 155     ACPI_OBJECT_LIST        *ExternalParams,
 156     ACPI_BUFFER             *ReturnBuffer,
 157     ACPI_OBJECT_TYPE        ReturnType)
 158 {
 159     ACPI_STATUS             Status;
 160     BOOLEAN                 MustFree = FALSE;
 161
 162
 163     ACPI_FUNCTION_TRACE ("AcpiEvaluateObjectTyped");
 164
 165
 166     /* Return buffer must be valid */
 167
 168     if (!ReturnBuffer)
 169     {
 170         return_ACPI_STATUS (AE_BAD_PARAMETER);
 171     }
 172
 173     if (ReturnBuffer->Length == ACPI_ALLOCATE_BUFFER)
 174     {
 175         MustFree = TRUE;
 176     }
 177
 178     /* Evaluate the object */
 179
 180     Status = AcpiEvaluateObject (Handle, Pathname, ExternalParams, ReturnBuffer);
 181     if (ACPI_FAILURE (Status))
 182     {
 183         return_ACPI_STATUS (Status);
 184     }
 185
 186     /* Type ANY means "don't care" */
 187
 188     if (ReturnType == ACPI_TYPE_ANY)
 189     {
 190         return_ACPI_STATUS (AE_OK);
 191     }
 192
 193     if (ReturnBuffer->Length == 0)
 194     {
 195         /* Error because caller specifically asked for a return value */
 196
 197         ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 198             "No return value\n"));
 199
 200         return_ACPI_STATUS (AE_NULL_OBJECT);
 201     }
 202
 203     /* Examine the object type returned from EvaluateObject */
 204
 205     if (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type == ReturnType)
 206     {
 207         return_ACPI_STATUS (AE_OK);
 208     }
 209
 210     /* Return object type does not match requested type */
 211
 212     ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 213         "Incorrect return type [%s] requested [%s]\n",
 214         AcpiUtGetTypeName (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type),
 215         AcpiUtGetTypeName (ReturnType)));
 216
 217     if (MustFree)
 218     {
 219         /* Caller used ACPI_ALLOCATE_BUFFER, free the return buffer */
 220
 221         AcpiOsFree (ReturnBuffer->Pointer);
 222         ReturnBuffer->Pointer = NULL;
 223     }
 224
 225     ReturnBuffer->Length = 0;
 226     return_ACPI_STATUS (AE_TYPE);
 227 }
 228
 229
 230 /*******************************************************************************
 231  *
 232  * FUNCTION:    AcpiEvaluateObject
 233  *
 234  * PARAMETERS:  Handle              - Object handle (optional)
 235  *              *Pathname           - Object pathname (optional)
 236  *              **ExternalParams    - List of parameters to pass to method,
 237  *                                    terminated by NULL.  May be NULL
 238  *                                    if no parameters are being passed.
 239  *              *ReturnBuffer       - Where to put method's return value (if
 240  *                                    any).  If NULL, no value is returned.
 241  *
 242  * RETURN:      Status
 243  *
 244  * DESCRIPTION: Find and evaluate the given object, passing the given
 245  *              parameters if necessary.  One of "Handle" or "Pathname" must
 246  *              be valid (non-null)
 247  *
 248  ******************************************************************************/
 249
 250 ACPI_STATUS
 251 AcpiEvaluateObject (
 252     ACPI_HANDLE             Handle,
 253     ACPI_STRING             Pathname,
 254     ACPI_OBJECT_LIST        *ExternalParams,
 255     ACPI_BUFFER             *ReturnBuffer)
 256 {
 257     ACPI_STATUS             Status;
 258     ACPI_OPERAND_OBJECT     **InternalParams = NULL;
 259     ACPI_OPERAND_OBJECT     *InternalReturnObj = NULL;
 260     ACPI_SIZE               BufferSpaceNeeded;
 261     UINT32                  i;
 262
 263
 264     ACPI_FUNCTION_TRACE ("AcpiEvaluateObject");
 265
 266
 267     /*
 268      * If there are parameters to be passed to the object
 269      * (which must be a control method), the external objects
 270      * must be converted to internal objects
 271      */
 272     if (ExternalParams && ExternalParams->Count)
 273     {
 274         /*
 275          * Allocate a new parameter block for the internal objects
 276          * Add 1 to count to allow for null terminated internal list
 277          */
 278         InternalParams = ACPI_MEM_CALLOCATE (((ACPI_SIZE) ExternalParams->Count + 1) *
 279                                                 sizeof (void *));
 280         if (!InternalParams)
 281         {
 282             return_ACPI_STATUS (AE_NO_MEMORY);
 283         }
 284
 285         /*
 286          * Convert each external object in the list to an
 287          * internal object
 288          */
 289         for (i = 0; i < ExternalParams->Count; i++)
 290         {
 291             Status = AcpiUtCopyEobjectToIobject (&ExternalParams->Pointer[i],
 292                                                 &InternalParams[i]);
 293             if (ACPI_FAILURE (Status))
 294             {
 295                 AcpiUtDeleteInternalObjectList (InternalParams);
 296                 return_ACPI_STATUS (Status);
 297             }
 298         }
 299         InternalParams[ExternalParams->Count] = NULL;
 300     }
 301
 302     /*
 303      * Three major cases:
 304      * 1) Fully qualified pathname
 305      * 2) No handle, not fully qualified pathname (error)
 306      * 3) Valid handle
 307      */
 308     if ((Pathname) &&
 309         (AcpiNsValidRootPrefix (Pathname[0])))
 310     {
 311         /*
 312          *  The path is fully qualified, just evaluate by name
 313          */
 314         Status = AcpiNsEvaluateByName (Pathname, InternalParams,
 315                     &InternalReturnObj);
 316     }
 317     else if (!Handle)
 318     {
 319         /*
 320          * A handle is optional iff a fully qualified pathname
 321          * is specified.  Since we've already handled fully
 322          * qualified names above, this is an error
 323          */
 324         if (!Pathname)
 325         {
 326             ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 327                 "Both Handle and Pathname are NULL\n"));
 328         }
 329         else
 330         {
 331             ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 332                 "Handle is NULL and Pathname is relative\n"));
 333         }
 334
 335         Status = AE_BAD_PARAMETER;
 336     }
 337     else
 338     {
 339         /*
 340          * We get here if we have a handle -- and if we have a
 341          * pathname it is relative.  The handle will be validated
 342          * in the lower procedures
 343          */
 344         if (!Pathname)
 345         {
 346             /*
 347              * The null pathname case means the handle is for
 348              * the actual object to be evaluated
 349              */
 350             Status = AcpiNsEvaluateByHandle (Handle, InternalParams,
 351                             &InternalReturnObj);
 352         }
 353         else
 354         {
 355            /*
 356             * Both a Handle and a relative Pathname
 357             */
 358             Status = AcpiNsEvaluateRelative (Handle, Pathname, InternalParams,
 359                             &InternalReturnObj);
 360         }
 361     }
 362
 363
 364     /*
 365      * If we are expecting a return value, and all went well above,
 366      * copy the return value to an external object.
 367      */
 368     if (ReturnBuffer)
 369     {
 370         if (!InternalReturnObj)
 371         {
 372             ReturnBuffer->Length = 0;
 373         }
 374         else
 375         {
 376             if (ACPI_GET_DESCRIPTOR_TYPE (InternalReturnObj) == ACPI_DESC_TYPE_NAMED)
 377             {
 378                 /*
 379                  * If we received a NS Node as a return object, this means that
 380                  * the object we are evaluating has nothing interesting to
 381                  * return (such as a mutex, etc.)  We return an error because
 382                  * these types are essentially unsupported by this interface.
 383                  * We don't check up front because this makes it easier to add
 384                  * support for various types at a later date if necessary.
 385                  */
 386                 Status = AE_TYPE;
 387                 InternalReturnObj = NULL;   /* No need to delete a NS Node */
 388                 ReturnBuffer->Length = 0;
 389             }
 390
 391             if (ACPI_SUCCESS (Status))
 392             {
 393                 /*
 394                  * Find out how large a buffer is needed
 395                  * to contain the returned object
 396                  */
 397                 Status = AcpiUtGetObjectSize (InternalReturnObj,
 398                                                 &BufferSpaceNeeded);
 399                 if (ACPI_SUCCESS (Status))
 400                 {
 401                     /* Validate/Allocate/Clear caller buffer */
 402
 403                     Status = AcpiUtInitializeBuffer (ReturnBuffer, BufferSpaceNeeded);
 404                     if (ACPI_FAILURE (Status))
 405                     {
 406                         /*
 407                          * Caller's buffer is too small or a new one can't be allocated
 408                          */
 409                         ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 410                             "Needed buffer size %X, %s\n",
 411                             (UINT32) BufferSpaceNeeded, AcpiFormatException (Status)));
 412                     }
 413                     else
 414                     {
 415                         /*
 416                          *  We have enough space for the object, build it
 417                          */
 418                         Status = AcpiUtCopyIobjectToEobject (InternalReturnObj,
 419                                         ReturnBuffer);
 420                     }
 421                 }
 422             }
 423         }
 424     }
 425
 426     /* Delete the return and parameter objects */
 427
 428     if (InternalReturnObj)
 429     {
 430         /*
 431          * Delete the internal return object. (Or at least
 432          * decrement the reference count by one)
 433          */
 434         AcpiUtRemoveReference (InternalReturnObj);
 435     }
 436
 437     /*
 438      * Free the input parameter list (if we created one),
 439      */
 440     if (InternalParams)
 441     {
 442         /* Free the allocated parameter block */
 443
 444         AcpiUtDeleteInternalObjectList (InternalParams);
 445     }
 446
 447     return_ACPI_STATUS (Status);
 448 }
 449
 450
 451 /*******************************************************************************
 452  *
 453  * FUNCTION:    AcpiWalkNamespace
 454  *
 455  * PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
 456  *              StartObject         - Handle in namespace where search begins
 457  *              MaxDepth            - Depth to which search is to reach
 458  *              UserFunction        - Called when an object of "Type" is found
 459  *              Context             - Passed to user function
 460  *              ReturnValue         - Location where return value of
 461  *                                    UserFunction is put if terminated early
 462  *
 463  * RETURNS      Return value from the UserFunction if terminated early.
 464  *              Otherwise, returns NULL.
 465  *
 466  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 467  *              starting (and ending) at the object specified by StartHandle.
 468  *              The UserFunction is called whenever an object that matches
 469  *              the type parameter is found.  If the user function returns
 470  *              a non-zero value, the search is terminated immediately and this
 471  *              value is returned to the caller.
 472  *
 473  *              The point of this procedure is to provide a generic namespace
 474  *              walk routine that can be called from multiple places to
 475  *              provide multiple services;  the User Function can be tailored
 476  *              to each task, whether it is a print function, a compare
 477  *              function, etc.
 478  *
 479  ******************************************************************************/
 480
 481 ACPI_STATUS
 482 AcpiWalkNamespace (
 483     ACPI_OBJECT_TYPE        Type,
 484     ACPI_HANDLE             StartObject,
 485     UINT32                  MaxDepth,
 486     ACPI_WALK_CALLBACK      UserFunction,
 487     void                    *Context,
 488     void                    **ReturnValue)
 489 {
 490     ACPI_STATUS             Status;
 491
 492
 493     ACPI_FUNCTION_TRACE ("AcpiWalkNamespace");
 494
 495
 496     /* Parameter validation */
 497
 498     if ((Type > ACPI_TYPE_EXTERNAL_MAX) ||
 499         (!MaxDepth)                     ||
 500         (!UserFunction))
 501     {
 502         return_ACPI_STATUS (AE_BAD_PARAMETER);
 503     }
 504
 505     /*
 506      * Lock the namespace around the walk.
 507      * The namespace will be unlocked/locked around each call
 508      * to the user function - since this function
 509      * must be allowed to make Acpi calls itself.
 510      */
 511     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 512     if (ACPI_FAILURE (Status))
 513     {
 514         return_ACPI_STATUS (Status);
 515     }
 516
 517     Status = AcpiNsWalkNamespace (Type, StartObject, MaxDepth, ACPI_NS_WALK_UNLOCK,
 518                     UserFunction, Context, ReturnValue);
 519
 520     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 521     return_ACPI_STATUS (Status);
 522 }
 523
 524
 525 /*******************************************************************************
 526  *
 527  * FUNCTION:    AcpiNsGetDeviceCallback
 528  *
 529  * PARAMETERS:  Callback from AcpiGetDevice
 530  *
 531  * RETURN:      Status
 532  *
 533  * DESCRIPTION: Takes callbacks from WalkNamespace and filters out all non-
 534  *              present devices, or if they specified a HID, it filters based
 535  *              on that.
 536  *
 537  ******************************************************************************/
 538
 539 static ACPI_STATUS
 540 AcpiNsGetDeviceCallback (
 541     ACPI_HANDLE             ObjHandle,
 542     UINT32                  NestingLevel,
 543     void                    *Context,
 544     void                    **ReturnValue)
 545 {
 546     ACPI_STATUS             Status;
 547     ACPI_NAMESPACE_NODE     *Node;
 548     UINT32                  Flags;
 549     ACPI_DEVICE_ID          Hid;
 550     ACPI_DEVICE_ID          Cid;
 551     ACPI_GET_DEVICES_INFO   *Info;
 552
 553
 554     Info = Context;
 555
 556     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 557     if (ACPI_FAILURE (Status))
 558     {
 559         return (Status);
 560     }
 561
 562     Node = AcpiNsMapHandleToNode (ObjHandle);
 563     Status = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 564     if (ACPI_FAILURE (Status))
 565     {
 566         return (Status);
 567     }
 568
 569     if (!Node)
 570     {
 571         return (AE_BAD_PARAMETER);
 572     }
 573
 574     /*
 575      * Run _STA to determine if device is present
 576      */
 577     Status = AcpiUtExecute_STA (Node, &Flags);
 578     if (ACPI_FAILURE (Status))
 579     {
 580         return (AE_CTRL_DEPTH);
 581     }
 582
 583     if (!(Flags & 0x01))
 584     {
 585         /* Don't return at the device or children of the device if not there */
 586         return (AE_CTRL_DEPTH);
 587     }
 588
 589     /*
 590      * Filter based on device HID & CID
 591      */
 592     if (Info->Hid != NULL)
 593     {
 594         Status = AcpiUtExecute_HID (Node, &Hid);
 595         if (Status == AE_NOT_FOUND)
 596         {
 597             return (AE_OK);
 598         }
 599         else if (ACPI_FAILURE (Status))
 600         {
 601             return (AE_CTRL_DEPTH);
 602         }
 603
 604         if (ACPI_STRNCMP (Hid.Buffer, Info->Hid, sizeof (Hid.Buffer)) != 0)
 605         {
 606             Status = AcpiUtExecute_CID (Node, &Cid);
 607             if (Status == AE_NOT_FOUND)
 608             {
 609                 return (AE_OK);
 610             }
 611             else if (ACPI_FAILURE (Status))
 612             {
 613                 return (AE_CTRL_DEPTH);
 614             }
 615
 616             /* TBD: Handle CID packages */
 617
 618             if (ACPI_STRNCMP (Cid.Buffer, Info->Hid, sizeof (Cid.Buffer)) != 0)
 619             {
 620                 return (AE_OK);
 621             }
 622         }
 623     }
 624
 625     Status = Info->UserFunction (ObjHandle, NestingLevel, Info->Context, ReturnValue);
 626     return (Status);
 627 }
 628
 629
 630 /*******************************************************************************
 631  *
 632  * FUNCTION:    AcpiGetDevices
 633  *
 634  * PARAMETERS:  HID                 - HID to search for. Can be NULL.
 635  *              UserFunction        - Called when a matching object is found
 636  *              Context             - Passed to user function
 637  *              ReturnValue         - Location where return value of
 638  *                                    UserFunction is put if terminated early
 639  *
 640  * RETURNS      Return value from the UserFunction if terminated early.
 641  *              Otherwise, returns NULL.
 642  *
 643  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 644  *              starting (and ending) at the object specified by StartHandle.
 645  *              The UserFunction is called whenever an object that matches
 646  *              the type parameter is found.  If the user function returns
 647  *              a non-zero value, the search is terminated immediately and this
 648  *              value is returned to the caller.
 649  *
 650  *              This is a wrapper for WalkNamespace, but the callback performs
 651  *              additional filtering. Please see AcpiGetDeviceCallback.
 652  *
 653  ******************************************************************************/
 654
 655 ACPI_STATUS
 656 AcpiGetDevices (
 657     char                    *HID,
 658     ACPI_WALK_CALLBACK      UserFunction,
 659     void                    *Context,
 660     void                    **ReturnValue)
 661 {
 662     ACPI_STATUS             Status;
 663     ACPI_GET_DEVICES_INFO   Info;
 664
 665
 666     ACPI_FUNCTION_TRACE ("AcpiGetDevices");
 667
 668
 669     /* Parameter validation */
 670
 671     if (!UserFunction)
 672     {
 673         return_ACPI_STATUS (AE_BAD_PARAMETER);
 674     }
 675
 676     /*
 677      * We're going to call their callback from OUR callback, so we need
 678      * to know what it is, and their context parameter.
 679      */
 680     Info.Context      = Context;
 681     Info.UserFunction = UserFunction;
 682     Info.Hid          = HID;
 683
 684     /*
 685      * Lock the namespace around the walk.
 686      * The namespace will be unlocked/locked around each call
 687      * to the user function - since this function
 688      * must be allowed to make Acpi calls itself.
 689      */
 690     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 691     if (ACPI_FAILURE (Status))
 692     {
 693         return_ACPI_STATUS (Status);
 694     }
 695
 696     Status = AcpiNsWalkNamespace (ACPI_TYPE_DEVICE,
 697                                     ACPI_ROOT_OBJECT, ACPI_UINT32_MAX,
 698                                     ACPI_NS_WALK_UNLOCK,
 699                                     AcpiNsGetDeviceCallback, &Info,
 700                                     ReturnValue);
 701
 702     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 703     return_ACPI_STATUS (Status);
 704 }
 705
 706
 707 /*******************************************************************************
 708  *
 709  * FUNCTION:    AcpiAttachData
 710  *
 711  * PARAMETERS:  ObjHandle           - Namespace node
 712  *              Handler             - Handler for this attachment
 713  *              Data                - Pointer to data to be attached
 714  *
 715  * RETURN:      Status
 716  *
 717  * DESCRIPTION: Attach arbitrary data and handler to a namespace node.
 718  *
 719  ******************************************************************************/
 720
 721 ACPI_STATUS
 722 AcpiAttachData (
 723     ACPI_HANDLE             ObjHandle,
 724     ACPI_OBJECT_HANDLER     Handler,
 725     void                    *Data)
 726 {
 727     ACPI_NAMESPACE_NODE     *Node;
 728     ACPI_STATUS             Status;
 729
 730
 731     /* Parameter validation */
 732
 733     if (!ObjHandle  ||
 734         !Handler    ||
 735         !Data)
 736     {
 737         return (AE_BAD_PARAMETER);
 738     }
 739
 740     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 741     if (ACPI_FAILURE (Status))
 742     {
 743         return (Status);
 744     }
 745
 746     /* Convert and validate the handle */
 747
 748     Node = AcpiNsMapHandleToNode (ObjHandle);
 749     if (!Node)
 750     {
 751         Status = AE_BAD_PARAMETER;
 752         goto UnlockAndExit;
 753     }
 754
 755     Status = AcpiNsAttachData (Node, Handler, Data);
 756
 757 UnlockAndExit:
 758     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 759     return (Status);
 760 }
 761
 762
 763 /*******************************************************************************
 764  *
 765  * FUNCTION:    AcpiDetachData
 766  *
 767  * PARAMETERS:  ObjHandle           - Namespace node handle
 768  *              Handler             - Handler used in call to AcpiAttachData
 769  *
 770  * RETURN:      Status
 771  *
 772  * DESCRIPTION: Remove data that was previously attached to a node.
 773  *
 774  ******************************************************************************/
 775
 776 ACPI_STATUS
 777 AcpiDetachData (
 778     ACPI_HANDLE             ObjHandle,
 779     ACPI_OBJECT_HANDLER     Handler)
 780 {
 781     ACPI_NAMESPACE_NODE     *Node;
 782     ACPI_STATUS             Status;
 783
 784
 785     /* Parameter validation */
 786
 787     if (!ObjHandle  ||
 788         !Handler)
 789     {
 790         return (AE_BAD_PARAMETER);
 791     }
 792
 793     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 794     if (ACPI_FAILURE (Status))
 795     {
 796         return (Status);
 797     }
 798
 799     /* Convert and validate the handle */
 800
 801     Node = AcpiNsMapHandleToNode (ObjHandle);
 802     if (!Node)
 803     {
 804         Status = AE_BAD_PARAMETER;
 805         goto UnlockAndExit;
 806     }
 807
 808     Status = AcpiNsDetachData (Node, Handler);
 809
 810 UnlockAndExit:
 811     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 812     return (Status);
 813 }
 814
 815
 816 /*******************************************************************************
 817  *
 818  * FUNCTION:    AcpiGetData
 819  *
 820  * PARAMETERS:  ObjHandle           - Namespace node
 821  *              Handler             - Handler used in call to AttachData
 822  *              Data                - Where the data is returned
 823  *
 824  * RETURN:      Status
 825  *
 826  * DESCRIPTION: Retrieve data that was previously attached to a namespace node.
 827  *
 828  ******************************************************************************/
 829
 830 ACPI_STATUS
 831 AcpiGetData (
 832     ACPI_HANDLE             ObjHandle,
 833     ACPI_OBJECT_HANDLER     Handler,
 834     void                    **Data)
 835 {
 836     ACPI_NAMESPACE_NODE     *Node;
 837     ACPI_STATUS             Status;
 838
 839
 840     /* Parameter validation */
 841
 842     if (!ObjHandle  ||
 843         !Handler    ||
 844         !Data)
 845     {
 846         return (AE_BAD_PARAMETER);
 847     }
 848
 849     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 850     if (ACPI_FAILURE (Status))
 851     {
 852         return (Status);
 853     }
 854
 855     /* Convert and validate the handle */
 856
 857     Node = AcpiNsMapHandleToNode (ObjHandle);
 858     if (!Node)
 859     {
 860         Status = AE_BAD_PARAMETER;
 861         goto UnlockAndExit;
 862     }
 863
 864     Status = AcpiNsGetAttachedData (Node, Handler, Data);
 865
 866 UnlockAndExit:
 867     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 868     return (Status);
 869 }
 870
 871