sys/contrib/dev/acpica-unix-20061109/namespace/nsxfeval.c

   1 /*******************************************************************************
   2  *
   3  * Module Name: nsxfeval - Public interfaces to the ACPI subsystem
   4  *                         ACPI Object evaluation interfaces
   5  *              $Revision: 1.29 $
   6  *
   7  ******************************************************************************/
   8
   9 /******************************************************************************
  10  *
  11  * 1. Copyright Notice
  12  *
  13  * Some or all of this work - Copyright (c) 1999 - 2006, 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
 118
 119 #define __NSXFEVAL_C__
 120
 121 #include "acpi.h"
 122 #include "acnamesp.h"
 123 #include "acinterp.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_ERROR ((AE_INFO, "No return value"));
 198         return_ACPI_STATUS (AE_NULL_OBJECT);
 199     }
 200
 201     /* Examine the object type returned from EvaluateObject */
 202
 203     if (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type == ReturnType)
 204     {
 205         return_ACPI_STATUS (AE_OK);
 206     }
 207
 208     /* Return object type does not match requested type */
 209
 210     ACPI_ERROR ((AE_INFO,
 211         "Incorrect return type [%s] requested [%s]",
 212         AcpiUtGetTypeName (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type),
 213         AcpiUtGetTypeName (ReturnType)));
 214
 215     if (MustFree)
 216     {
 217         /* Caller used ACPI_ALLOCATE_BUFFER, free the return buffer */
 218
 219         AcpiOsFree (ReturnBuffer->Pointer);
 220         ReturnBuffer->Pointer = NULL;
 221     }
 222
 223     ReturnBuffer->Length = 0;
 224     return_ACPI_STATUS (AE_TYPE);
 225 }
 226
 227 ACPI_EXPORT_SYMBOL (AcpiEvaluateObjectTyped)
 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_EVALUATE_INFO      *Info;
 259     ACPI_SIZE               BufferSpaceNeeded;
 260     UINT32                  i;
 261
 262
 263     ACPI_FUNCTION_TRACE (AcpiEvaluateObject);
 264
 265
 266     /* Allocate and initialize the evaluation information block */
 267
 268     Info = ACPI_ALLOCATE_ZEROED (sizeof (ACPI_EVALUATE_INFO));
 269     if (!Info)
 270     {
 271         return_ACPI_STATUS (AE_NO_MEMORY);
 272     }
 273
 274     Info->Pathname = Pathname;
 275     Info->ParameterType = ACPI_PARAM_ARGS;
 276
 277     /* Convert and validate the device handle */
 278
 279     Info->PrefixNode = AcpiNsMapHandleToNode (Handle);
 280     if (!Info->PrefixNode)
 281     {
 282         Status = AE_BAD_PARAMETER;
 283         goto Cleanup;
 284     }
 285
 286     /*
 287      * If there are parameters to be passed to a control method, the external
 288      * objects must all be converted to internal objects
 289      */
 290     if (ExternalParams && ExternalParams->Count)
 291     {
 292         /*
 293          * Allocate a new parameter block for the internal objects
 294          * Add 1 to count to allow for null terminated internal list
 295          */
 296         Info->Parameters = ACPI_ALLOCATE_ZEROED (
 297             ((ACPI_SIZE) ExternalParams->Count + 1) * sizeof (void *));
 298         if (!Info->Parameters)
 299         {
 300             Status = AE_NO_MEMORY;
 301             goto Cleanup;
 302         }
 303
 304         /* Convert each external object in the list to an internal object */
 305
 306         for (i = 0; i < ExternalParams->Count; i++)
 307         {
 308             Status = AcpiUtCopyEobjectToIobject (
 309                         &ExternalParams->Pointer[i], &Info->Parameters[i]);
 310             if (ACPI_FAILURE (Status))
 311             {
 312                 goto Cleanup;
 313             }
 314         }
 315         Info->Parameters[ExternalParams->Count] = NULL;
 316     }
 317
 318     /*
 319      * Three major cases:
 320      * 1) Fully qualified pathname
 321      * 2) No handle, not fully qualified pathname (error)
 322      * 3) Valid handle
 323      */
 324     if ((Pathname) &&
 325         (AcpiNsValidRootPrefix (Pathname[0])))
 326     {
 327         /* The path is fully qualified, just evaluate by name */
 328
 329         Info->PrefixNode = NULL;
 330         Status = AcpiNsEvaluate (Info);
 331     }
 332     else if (!Handle)
 333     {
 334         /*
 335          * A handle is optional iff a fully qualified pathname is specified.
 336          * Since we've already handled fully qualified names above, this is
 337          * an error
 338          */
 339         if (!Pathname)
 340         {
 341             ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 342                 "Both Handle and Pathname are NULL"));
 343         }
 344         else
 345         {
 346             ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 347                 "Null Handle with relative pathname [%s]", Pathname));
 348         }
 349
 350         Status = AE_BAD_PARAMETER;
 351     }
 352     else
 353     {
 354         /* We have a namespace a node and a possible relative path */
 355
 356         Status = AcpiNsEvaluate (Info);
 357     }
 358
 359     /*
 360      * If we are expecting a return value, and all went well above,
 361      * copy the return value to an external object.
 362      */
 363     if (ReturnBuffer)
 364     {
 365         if (!Info->ReturnObject)
 366         {
 367             ReturnBuffer->Length = 0;
 368         }
 369         else
 370         {
 371             if (ACPI_GET_DESCRIPTOR_TYPE (Info->ReturnObject) ==
 372                 ACPI_DESC_TYPE_NAMED)
 373             {
 374                 /*
 375                  * If we received a NS Node as a return object, this means that
 376                  * the object we are evaluating has nothing interesting to
 377                  * return (such as a mutex, etc.)  We return an error because
 378                  * these types are essentially unsupported by this interface.
 379                  * We don't check up front because this makes it easier to add
 380                  * support for various types at a later date if necessary.
 381                  */
 382                 Status = AE_TYPE;
 383                 Info->ReturnObject = NULL;   /* No need to delete a NS Node */
 384                 ReturnBuffer->Length = 0;
 385             }
 386
 387             if (ACPI_SUCCESS (Status))
 388             {
 389                 /* Get the size of the returned object */
 390
 391                 Status = AcpiUtGetObjectSize (Info->ReturnObject,
 392                             &BufferSpaceNeeded);
 393                 if (ACPI_SUCCESS (Status))
 394                 {
 395                     /* Validate/Allocate/Clear caller buffer */
 396
 397                     Status = AcpiUtInitializeBuffer (ReturnBuffer,
 398                                 BufferSpaceNeeded);
 399                     if (ACPI_FAILURE (Status))
 400                     {
 401                         /*
 402                          * Caller's buffer is too small or a new one can't
 403                          * be allocated
 404                          */
 405                         ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 406                             "Needed buffer size %X, %s\n",
 407                             (UINT32) BufferSpaceNeeded,
 408                             AcpiFormatException (Status)));
 409                     }
 410                     else
 411                     {
 412                         /* We have enough space for the object, build it */
 413
 414                         Status = AcpiUtCopyIobjectToEobject (Info->ReturnObject,
 415                                     ReturnBuffer);
 416                     }
 417                 }
 418             }
 419         }
 420     }
 421
 422     if (Info->ReturnObject)
 423     {
 424         /*
 425          * Delete the internal return object. NOTE: Interpreter must be
 426          * locked to avoid race condition.
 427          */
 428         AcpiExEnterInterpreter ();
 429
 430         /* Remove one reference on the return object (should delete it) */
 431
 432         AcpiUtRemoveReference (Info->ReturnObject);
 433         AcpiExExitInterpreter ();
 434     }
 435
 436
 437 Cleanup:
 438
 439     /* Free the input parameter list (if we created one) */
 440
 441     if (Info->Parameters)
 442     {
 443         /* Free the allocated parameter block */
 444
 445         AcpiUtDeleteInternalObjectList (Info->Parameters);
 446     }
 447
 448     ACPI_FREE (Info);
 449     return_ACPI_STATUS (Status);
 450 }
 451
 452 ACPI_EXPORT_SYMBOL (AcpiEvaluateObject)
 453
 454
 455 /*******************************************************************************
 456  *
 457  * FUNCTION:    AcpiWalkNamespace
 458  *
 459  * PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
 460  *              StartObject         - Handle in namespace where search begins
 461  *              MaxDepth            - Depth to which search is to reach
 462  *              UserFunction        - Called when an object of "Type" is found
 463  *              Context             - Passed to user function
 464  *              ReturnValue         - Location where return value of
 465  *                                    UserFunction is put if terminated early
 466  *
 467  * RETURNS      Return value from the UserFunction if terminated early.
 468  *              Otherwise, returns NULL.
 469  *
 470  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 471  *              starting (and ending) at the object specified by StartHandle.
 472  *              The UserFunction is called whenever an object that matches
 473  *              the type parameter is found.  If the user function returns
 474  *              a non-zero value, the search is terminated immediately and this
 475  *              value is returned to the caller.
 476  *
 477  *              The point of this procedure is to provide a generic namespace
 478  *              walk routine that can be called from multiple places to
 479  *              provide multiple services;  the User Function can be tailored
 480  *              to each task, whether it is a print function, a compare
 481  *              function, etc.
 482  *
 483  ******************************************************************************/
 484
 485 ACPI_STATUS
 486 AcpiWalkNamespace (
 487     ACPI_OBJECT_TYPE        Type,
 488     ACPI_HANDLE             StartObject,
 489     UINT32                  MaxDepth,
 490     ACPI_WALK_CALLBACK      UserFunction,
 491     void                    *Context,
 492     void                    **ReturnValue)
 493 {
 494     ACPI_STATUS             Status;
 495
 496
 497     ACPI_FUNCTION_TRACE (AcpiWalkNamespace);
 498
 499
 500     /* Parameter validation */
 501
 502     if ((Type > ACPI_TYPE_LOCAL_MAX) ||
 503         (!MaxDepth)                  ||
 504         (!UserFunction))
 505     {
 506         return_ACPI_STATUS (AE_BAD_PARAMETER);
 507     }
 508
 509     /*
 510      * Lock the namespace around the walk.
 511      * The namespace will be unlocked/locked around each call
 512      * to the user function - since this function
 513      * must be allowed to make Acpi calls itself.
 514      */
 515     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 516     if (ACPI_FAILURE (Status))
 517     {
 518         return_ACPI_STATUS (Status);
 519     }
 520
 521     Status = AcpiNsWalkNamespace (Type, StartObject, MaxDepth,
 522                     ACPI_NS_WALK_UNLOCK,
 523                     UserFunction, Context, ReturnValue);
 524
 525     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 526     return_ACPI_STATUS (Status);
 527 }
 528
 529 ACPI_EXPORT_SYMBOL (AcpiWalkNamespace)
 530
 531
 532 /*******************************************************************************
 533  *
 534  * FUNCTION:    AcpiNsGetDeviceCallback
 535  *
 536  * PARAMETERS:  Callback from AcpiGetDevice
 537  *
 538  * RETURN:      Status
 539  *
 540  * DESCRIPTION: Takes callbacks from WalkNamespace and filters out all non-
 541  *              present devices, or if they specified a HID, it filters based
 542  *              on that.
 543  *
 544  ******************************************************************************/
 545
 546 static ACPI_STATUS
 547 AcpiNsGetDeviceCallback (
 548     ACPI_HANDLE             ObjHandle,
 549     UINT32                  NestingLevel,
 550     void                    *Context,
 551     void                    **ReturnValue)
 552 {
 553     ACPI_GET_DEVICES_INFO   *Info = Context;
 554     ACPI_STATUS             Status;
 555     ACPI_NAMESPACE_NODE     *Node;
 556     UINT32                  Flags;
 557     ACPI_DEVICE_ID          Hid;
 558     ACPI_COMPATIBLE_ID_LIST *Cid;
 559     ACPI_NATIVE_UINT        i;
 560
 561
 562     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 563     if (ACPI_FAILURE (Status))
 564     {
 565         return (Status);
 566     }
 567
 568     Node = AcpiNsMapHandleToNode (ObjHandle);
 569     Status = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 570     if (ACPI_FAILURE (Status))
 571     {
 572         return (Status);
 573     }
 574
 575     if (!Node)
 576     {
 577         return (AE_BAD_PARAMETER);
 578     }
 579
 580     /* Run _STA to determine if device is present */
 581
 582     Status = AcpiUtExecute_STA (Node, &Flags);
 583     if (ACPI_FAILURE (Status))
 584     {
 585         return (AE_CTRL_DEPTH);
 586     }
 587
 588     if (!(Flags & ACPI_STA_DEVICE_PRESENT))
 589     {
 590         /* Don't examine children of the device if not present */
 591
 592         return (AE_CTRL_DEPTH);
 593     }
 594
 595     /* Filter based on device HID & CID */
 596
 597     if (Info->Hid != NULL)
 598     {
 599         Status = AcpiUtExecute_HID (Node, &Hid);
 600         if (Status == AE_NOT_FOUND)
 601         {
 602             return (AE_OK);
 603         }
 604         else if (ACPI_FAILURE (Status))
 605         {
 606             return (AE_CTRL_DEPTH);
 607         }
 608
 609         if (ACPI_STRNCMP (Hid.Value, Info->Hid, sizeof (Hid.Value)) != 0)
 610         {
 611             /* Get the list of Compatible IDs */
 612
 613             Status = AcpiUtExecute_CID (Node, &Cid);
 614             if (Status == AE_NOT_FOUND)
 615             {
 616                 return (AE_OK);
 617             }
 618             else if (ACPI_FAILURE (Status))
 619             {
 620                 return (AE_CTRL_DEPTH);
 621             }
 622
 623             /* Walk the CID list */
 624
 625             for (i = 0; i < Cid->Count; i++)
 626             {
 627                 if (ACPI_STRNCMP (Cid->Id[i].Value, Info->Hid,
 628                                         sizeof (ACPI_COMPATIBLE_ID)) != 0)
 629                 {
 630                     ACPI_FREE (Cid);
 631                     return (AE_OK);
 632                 }
 633             }
 634             ACPI_FREE (Cid);
 635         }
 636     }
 637
 638     Status = Info->UserFunction (ObjHandle, NestingLevel, Info->Context,
 639                 ReturnValue);
 640     return (Status);
 641 }
 642
 643
 644 /*******************************************************************************
 645  *
 646  * FUNCTION:    AcpiGetDevices
 647  *
 648  * PARAMETERS:  HID                 - HID to search for. Can be NULL.
 649  *              UserFunction        - Called when a matching object is found
 650  *              Context             - Passed to user function
 651  *              ReturnValue         - Location where return value of
 652  *                                    UserFunction is put if terminated early
 653  *
 654  * RETURNS      Return value from the UserFunction if terminated early.
 655  *              Otherwise, returns NULL.
 656  *
 657  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 658  *              starting (and ending) at the object specified by StartHandle.
 659  *              The UserFunction is called whenever an object of type
 660  *              Device is found.  If the user function returns
 661  *              a non-zero value, the search is terminated immediately and this
 662  *              value is returned to the caller.
 663  *
 664  *              This is a wrapper for WalkNamespace, but the callback performs
 665  *              additional filtering. Please see AcpiGetDeviceCallback.
 666  *
 667  ******************************************************************************/
 668
 669 ACPI_STATUS
 670 AcpiGetDevices (
 671     char                    *HID,
 672     ACPI_WALK_CALLBACK      UserFunction,
 673     void                    *Context,
 674     void                    **ReturnValue)
 675 {
 676     ACPI_STATUS             Status;
 677     ACPI_GET_DEVICES_INFO   Info;
 678
 679
 680     ACPI_FUNCTION_TRACE (AcpiGetDevices);
 681
 682
 683     /* Parameter validation */
 684
 685     if (!UserFunction)
 686     {
 687         return_ACPI_STATUS (AE_BAD_PARAMETER);
 688     }
 689
 690     /*
 691      * We're going to call their callback from OUR callback, so we need
 692      * to know what it is, and their context parameter.
 693      */
 694     Info.Hid          = HID;
 695     Info.Context      = Context;
 696     Info.UserFunction = UserFunction;
 697
 698     /*
 699      * Lock the namespace around the walk.
 700      * The namespace will be unlocked/locked around each call
 701      * to the user function - since this function
 702      * must be allowed to make Acpi calls itself.
 703      */
 704     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 705     if (ACPI_FAILURE (Status))
 706     {
 707         return_ACPI_STATUS (Status);
 708     }
 709
 710     Status = AcpiNsWalkNamespace (ACPI_TYPE_DEVICE, ACPI_ROOT_OBJECT,
 711                 ACPI_UINT32_MAX, ACPI_NS_WALK_UNLOCK,
 712                 AcpiNsGetDeviceCallback, &Info, ReturnValue);
 713
 714     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 715     return_ACPI_STATUS (Status);
 716 }
 717
 718 ACPI_EXPORT_SYMBOL (AcpiGetDevices)
 719
 720
 721 /*******************************************************************************
 722  *
 723  * FUNCTION:    AcpiAttachData
 724  *
 725  * PARAMETERS:  ObjHandle           - Namespace node
 726  *              Handler             - Handler for this attachment
 727  *              Data                - Pointer to data to be attached
 728  *
 729  * RETURN:      Status
 730  *
 731  * DESCRIPTION: Attach arbitrary data and handler to a namespace node.
 732  *
 733  ******************************************************************************/
 734
 735 ACPI_STATUS
 736 AcpiAttachData (
 737     ACPI_HANDLE             ObjHandle,
 738     ACPI_OBJECT_HANDLER     Handler,
 739     void                    *Data)
 740 {
 741     ACPI_NAMESPACE_NODE     *Node;
 742     ACPI_STATUS             Status;
 743
 744
 745     /* Parameter validation */
 746
 747     if (!ObjHandle  ||
 748         !Handler    ||
 749         !Data)
 750     {
 751         return (AE_BAD_PARAMETER);
 752     }
 753
 754     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 755     if (ACPI_FAILURE (Status))
 756     {
 757         return (Status);
 758     }
 759
 760     /* Convert and validate the handle */
 761
 762     Node = AcpiNsMapHandleToNode (ObjHandle);
 763     if (!Node)
 764     {
 765         Status = AE_BAD_PARAMETER;
 766         goto UnlockAndExit;
 767     }
 768
 769     Status = AcpiNsAttachData (Node, Handler, Data);
 770
 771 UnlockAndExit:
 772     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 773     return (Status);
 774 }
 775
 776 ACPI_EXPORT_SYMBOL (AcpiAttachData)
 777
 778
 779 /*******************************************************************************
 780  *
 781  * FUNCTION:    AcpiDetachData
 782  *
 783  * PARAMETERS:  ObjHandle           - Namespace node handle
 784  *              Handler             - Handler used in call to AcpiAttachData
 785  *
 786  * RETURN:      Status
 787  *
 788  * DESCRIPTION: Remove data that was previously attached to a node.
 789  *
 790  ******************************************************************************/
 791
 792 ACPI_STATUS
 793 AcpiDetachData (
 794     ACPI_HANDLE             ObjHandle,
 795     ACPI_OBJECT_HANDLER     Handler)
 796 {
 797     ACPI_NAMESPACE_NODE     *Node;
 798     ACPI_STATUS             Status;
 799
 800
 801     /* Parameter validation */
 802
 803     if (!ObjHandle  ||
 804         !Handler)
 805     {
 806         return (AE_BAD_PARAMETER);
 807     }
 808
 809     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 810     if (ACPI_FAILURE (Status))
 811     {
 812         return (Status);
 813     }
 814
 815     /* Convert and validate the handle */
 816
 817     Node = AcpiNsMapHandleToNode (ObjHandle);
 818     if (!Node)
 819     {
 820         Status = AE_BAD_PARAMETER;
 821         goto UnlockAndExit;
 822     }
 823
 824     Status = AcpiNsDetachData (Node, Handler);
 825
 826 UnlockAndExit:
 827     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 828     return (Status);
 829 }
 830
 831 ACPI_EXPORT_SYMBOL (AcpiDetachData)
 832
 833
 834 /*******************************************************************************
 835  *
 836  * FUNCTION:    AcpiGetData
 837  *
 838  * PARAMETERS:  ObjHandle           - Namespace node
 839  *              Handler             - Handler used in call to AttachData
 840  *              Data                - Where the data is returned
 841  *
 842  * RETURN:      Status
 843  *
 844  * DESCRIPTION: Retrieve data that was previously attached to a namespace node.
 845  *
 846  ******************************************************************************/
 847
 848 ACPI_STATUS
 849 AcpiGetData (
 850     ACPI_HANDLE             ObjHandle,
 851     ACPI_OBJECT_HANDLER     Handler,
 852     void                    **Data)
 853 {
 854     ACPI_NAMESPACE_NODE     *Node;
 855     ACPI_STATUS             Status;
 856
 857
 858     /* Parameter validation */
 859
 860     if (!ObjHandle  ||
 861         !Handler    ||
 862         !Data)
 863     {
 864         return (AE_BAD_PARAMETER);
 865     }
 866
 867     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 868     if (ACPI_FAILURE (Status))
 869     {
 870         return (Status);
 871     }
 872
 873     /* Convert and validate the handle */
 874
 875     Node = AcpiNsMapHandleToNode (ObjHandle);
 876     if (!Node)
 877     {
 878         Status = AE_BAD_PARAMETER;
 879         goto UnlockAndExit;
 880     }
 881
 882     Status = AcpiNsGetAttachedData (Node, Handler, Data);
 883
 884 UnlockAndExit:
 885     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 886     return (Status);
 887 }
 888
 889 ACPI_EXPORT_SYMBOL (AcpiGetData)
 890
 891