sys/contrib/dev/acpica/source/components/namespace/nsxfeval.c

   1 /*******************************************************************************
   2  *
   3  * Module Name: nsxfeval - Public interfaces to the ACPI subsystem
   4  *                         ACPI Object evaluation interfaces
   5  *
   6  ******************************************************************************/
   7
   8 /*
   9  * Copyright (C) 2000 - 2014, Intel Corp.
  10  * All rights reserved.
  11  *
  12  * Redistribution and use in source and binary forms, with or without
  13  * modification, are permitted provided that the following conditions
  14  * are met:
  15  * 1. Redistributions of source code must retain the above copyright
  16  *    notice, this list of conditions, and the following disclaimer,
  17  *    without modification.
  18  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
  19  *    substantially similar to the "NO WARRANTY" disclaimer below
  20  *    ("Disclaimer") and any redistribution must be conditioned upon
  21  *    including a substantially similar Disclaimer requirement for further
  22  *    binary redistribution.
  23  * 3. Neither the names of the above-listed copyright holders nor the names
  24  *    of any contributors may be used to endorse or promote products derived
  25  *    from this software without specific prior written permission.
  26  *
  27  * Alternatively, this software may be distributed under the terms of the
  28  * GNU General Public License ("GPL") version 2 as published by the Free
  29  * Software Foundation.
  30  *
  31  * NO WARRANTY
  32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  33  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  34  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  35  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  36  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  37  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  38  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  40  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  41  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  42  * POSSIBILITY OF SUCH DAMAGES.
  43  */
  44
  45 #define __NSXFEVAL_C__
  46 #define EXPORT_ACPI_INTERFACES
  47
  48 #include "acpi.h"
  49 #include "accommon.h"
  50 #include "acnamesp.h"
  51 #include "acinterp.h"
  52
  53
  54 #define _COMPONENT          ACPI_NAMESPACE
  55         ACPI_MODULE_NAME    ("nsxfeval")
  56
  57 /* Local prototypes */
  58
  59 static void
  60 AcpiNsResolveReferences (
  61     ACPI_EVALUATE_INFO      *Info);
  62
  63
  64 /*******************************************************************************
  65  *
  66  * FUNCTION:    AcpiEvaluateObjectTyped
  67  *
  68  * PARAMETERS:  Handle              - Object handle (optional)
  69  *              Pathname            - Object pathname (optional)
  70  *              ExternalParams      - List of parameters to pass to method,
  71  *                                    terminated by NULL. May be NULL
  72  *                                    if no parameters are being passed.
  73  *              ReturnBuffer        - Where to put method's return value (if
  74  *                                    any). If NULL, no value is returned.
  75  *              ReturnType          - Expected type of return object
  76  *
  77  * RETURN:      Status
  78  *
  79  * DESCRIPTION: Find and evaluate the given object, passing the given
  80  *              parameters if necessary. One of "Handle" or "Pathname" must
  81  *              be valid (non-null)
  82  *
  83  ******************************************************************************/
  84
  85 ACPI_STATUS
  86 AcpiEvaluateObjectTyped (
  87     ACPI_HANDLE             Handle,
  88     ACPI_STRING             Pathname,
  89     ACPI_OBJECT_LIST        *ExternalParams,
  90     ACPI_BUFFER             *ReturnBuffer,
  91     ACPI_OBJECT_TYPE        ReturnType)
  92 {
  93     ACPI_STATUS             Status;
  94     BOOLEAN                 FreeBufferOnError = FALSE;
  95
  96
  97     ACPI_FUNCTION_TRACE (AcpiEvaluateObjectTyped);
  98
  99
 100     /* Return buffer must be valid */
 101
 102     if (!ReturnBuffer)
 103     {
 104         return_ACPI_STATUS (AE_BAD_PARAMETER);
 105     }
 106
 107     if (ReturnBuffer->Length == ACPI_ALLOCATE_BUFFER)
 108     {
 109         FreeBufferOnError = TRUE;
 110     }
 111
 112     /* Evaluate the object */
 113
 114     Status = AcpiEvaluateObject (Handle, Pathname,
 115         ExternalParams, ReturnBuffer);
 116     if (ACPI_FAILURE (Status))
 117     {
 118         return_ACPI_STATUS (Status);
 119     }
 120
 121     /* Type ANY means "don't care" */
 122
 123     if (ReturnType == ACPI_TYPE_ANY)
 124     {
 125         return_ACPI_STATUS (AE_OK);
 126     }
 127
 128     if (ReturnBuffer->Length == 0)
 129     {
 130         /* Error because caller specifically asked for a return value */
 131
 132         ACPI_ERROR ((AE_INFO, "No return value"));
 133         return_ACPI_STATUS (AE_NULL_OBJECT);
 134     }
 135
 136     /* Examine the object type returned from EvaluateObject */
 137
 138     if (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type == ReturnType)
 139     {
 140         return_ACPI_STATUS (AE_OK);
 141     }
 142
 143     /* Return object type does not match requested type */
 144
 145     ACPI_ERROR ((AE_INFO,
 146         "Incorrect return type [%s] requested [%s]",
 147         AcpiUtGetTypeName (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type),
 148         AcpiUtGetTypeName (ReturnType)));
 149
 150     if (FreeBufferOnError)
 151     {
 152         /*
 153          * Free a buffer created via ACPI_ALLOCATE_BUFFER.
 154          * Note: We use AcpiOsFree here because AcpiOsAllocate was used
 155          * to allocate the buffer. This purposefully bypasses the
 156          * (optionally enabled) allocation tracking mechanism since we
 157          * only want to track internal allocations.
 158          */
 159         AcpiOsFree (ReturnBuffer->Pointer);
 160         ReturnBuffer->Pointer = NULL;
 161     }
 162
 163     ReturnBuffer->Length = 0;
 164     return_ACPI_STATUS (AE_TYPE);
 165 }
 166
 167 ACPI_EXPORT_SYMBOL (AcpiEvaluateObjectTyped)
 168
 169
 170 /*******************************************************************************
 171  *
 172  * FUNCTION:    AcpiEvaluateObject
 173  *
 174  * PARAMETERS:  Handle              - Object handle (optional)
 175  *              Pathname            - Object pathname (optional)
 176  *              ExternalParams      - List of parameters to pass to method,
 177  *                                    terminated by NULL. May be NULL
 178  *                                    if no parameters are being passed.
 179  *              ReturnBuffer        - Where to put method's return value (if
 180  *                                    any). If NULL, no value is returned.
 181  *
 182  * RETURN:      Status
 183  *
 184  * DESCRIPTION: Find and evaluate the given object, passing the given
 185  *              parameters if necessary. One of "Handle" or "Pathname" must
 186  *              be valid (non-null)
 187  *
 188  ******************************************************************************/
 189
 190 ACPI_STATUS
 191 AcpiEvaluateObject (
 192     ACPI_HANDLE             Handle,
 193     ACPI_STRING             Pathname,
 194     ACPI_OBJECT_LIST        *ExternalParams,
 195     ACPI_BUFFER             *ReturnBuffer)
 196 {
 197     ACPI_STATUS             Status;
 198     ACPI_EVALUATE_INFO      *Info;
 199     ACPI_SIZE               BufferSpaceNeeded;
 200     UINT32                  i;
 201
 202
 203     ACPI_FUNCTION_TRACE (AcpiEvaluateObject);
 204
 205
 206     /* Allocate and initialize the evaluation information block */
 207
 208     Info = ACPI_ALLOCATE_ZEROED (sizeof (ACPI_EVALUATE_INFO));
 209     if (!Info)
 210     {
 211         return_ACPI_STATUS (AE_NO_MEMORY);
 212     }
 213
 214     /* Convert and validate the device handle */
 215
 216     Info->PrefixNode = AcpiNsValidateHandle (Handle);
 217     if (!Info->PrefixNode)
 218     {
 219         Status = AE_BAD_PARAMETER;
 220         goto Cleanup;
 221     }
 222
 223     /*
 224      * Get the actual namespace node for the target object.
 225      * Handles these cases:
 226      *
 227      * 1) Null node, valid pathname from root (absolute path)
 228      * 2) Node and valid pathname (path relative to Node)
 229      * 3) Node, Null pathname
 230      */
 231     if ((Pathname) &&
 232         (ACPI_IS_ROOT_PREFIX (Pathname[0])))
 233     {
 234         /* The path is fully qualified, just evaluate by name */
 235
 236         Info->PrefixNode = NULL;
 237     }
 238     else if (!Handle)
 239     {
 240         /*
 241          * A handle is optional iff a fully qualified pathname is specified.
 242          * Since we've already handled fully qualified names above, this is
 243          * an error.
 244          */
 245         if (!Pathname)
 246         {
 247             ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 248                 "Both Handle and Pathname are NULL"));
 249         }
 250         else
 251         {
 252             ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 253                 "Null Handle with relative pathname [%s]", Pathname));
 254         }
 255
 256         Status = AE_BAD_PARAMETER;
 257         goto Cleanup;
 258     }
 259
 260     Info->RelativePathname = Pathname;
 261
 262     /*
 263      * Convert all external objects passed as arguments to the
 264      * internal version(s).
 265      */
 266     if (ExternalParams && ExternalParams->Count)
 267     {
 268         Info->ParamCount = (UINT16) ExternalParams->Count;
 269
 270         /* Warn on impossible argument count */
 271
 272         if (Info->ParamCount > ACPI_METHOD_NUM_ARGS)
 273         {
 274             ACPI_WARN_PREDEFINED ((AE_INFO, Pathname, ACPI_WARN_ALWAYS,
 275                 "Excess arguments (%u) - using only %u",
 276                 Info->ParamCount, ACPI_METHOD_NUM_ARGS));
 277
 278             Info->ParamCount = ACPI_METHOD_NUM_ARGS;
 279         }
 280
 281         /*
 282          * Allocate a new parameter block for the internal objects
 283          * Add 1 to count to allow for null terminated internal list
 284          */
 285         Info->Parameters = ACPI_ALLOCATE_ZEROED (
 286             ((ACPI_SIZE) Info->ParamCount + 1) * sizeof (void *));
 287         if (!Info->Parameters)
 288         {
 289             Status = AE_NO_MEMORY;
 290             goto Cleanup;
 291         }
 292
 293         /* Convert each external object in the list to an internal object */
 294
 295         for (i = 0; i < Info->ParamCount; i++)
 296         {
 297             Status = AcpiUtCopyEobjectToIobject (
 298                 &ExternalParams->Pointer[i], &Info->Parameters[i]);
 299             if (ACPI_FAILURE (Status))
 300             {
 301                 goto Cleanup;
 302             }
 303         }
 304
 305         Info->Parameters[Info->ParamCount] = NULL;
 306     }
 307
 308
 309 #if 0
 310
 311     /*
 312      * Begin incoming argument count analysis. Check for too few args
 313      * and too many args.
 314      */
 315
 316     switch (AcpiNsGetType (Info->Node))
 317     {
 318     case ACPI_TYPE_METHOD:
 319
 320         /* Check incoming argument count against the method definition */
 321
 322         if (Info->ObjDesc->Method.ParamCount > Info->ParamCount)
 323         {
 324             ACPI_ERROR ((AE_INFO,
 325                 "Insufficient arguments (%u) - %u are required",
 326                 Info->ParamCount,
 327                 Info->ObjDesc->Method.ParamCount));
 328
 329             Status = AE_MISSING_ARGUMENTS;
 330             goto Cleanup;
 331         }
 332
 333         else if (Info->ObjDesc->Method.ParamCount < Info->ParamCount)
 334         {
 335             ACPI_WARNING ((AE_INFO,
 336                 "Excess arguments (%u) - only %u are required",
 337                 Info->ParamCount,
 338                 Info->ObjDesc->Method.ParamCount));
 339
 340             /* Just pass the required number of arguments */
 341
 342             Info->ParamCount = Info->ObjDesc->Method.ParamCount;
 343         }
 344
 345         /*
 346          * Any incoming external objects to be passed as arguments to the
 347          * method must be converted to internal objects
 348          */
 349         if (Info->ParamCount)
 350         {
 351             /*
 352              * Allocate a new parameter block for the internal objects
 353              * Add 1 to count to allow for null terminated internal list
 354              */
 355             Info->Parameters = ACPI_ALLOCATE_ZEROED (
 356                 ((ACPI_SIZE) Info->ParamCount + 1) * sizeof (void *));
 357             if (!Info->Parameters)
 358             {
 359                 Status = AE_NO_MEMORY;
 360                 goto Cleanup;
 361             }
 362
 363             /* Convert each external object in the list to an internal object */
 364
 365             for (i = 0; i < Info->ParamCount; i++)
 366             {
 367                 Status = AcpiUtCopyEobjectToIobject (
 368                     &ExternalParams->Pointer[i], &Info->Parameters[i]);
 369                 if (ACPI_FAILURE (Status))
 370                 {
 371                     goto Cleanup;
 372                 }
 373             }
 374
 375             Info->Parameters[Info->ParamCount] = NULL;
 376         }
 377         break;
 378
 379     default:
 380
 381         /* Warn if arguments passed to an object that is not a method */
 382
 383         if (Info->ParamCount)
 384         {
 385             ACPI_WARNING ((AE_INFO,
 386                 "%u arguments were passed to a non-method ACPI object",
 387                 Info->ParamCount));
 388         }
 389         break;
 390     }
 391
 392 #endif
 393
 394
 395     /* Now we can evaluate the object */
 396
 397     Status = AcpiNsEvaluate (Info);
 398
 399     /*
 400      * If we are expecting a return value, and all went well above,
 401      * copy the return value to an external object.
 402      */
 403     if (ReturnBuffer)
 404     {
 405         if (!Info->ReturnObject)
 406         {
 407             ReturnBuffer->Length = 0;
 408         }
 409         else
 410         {
 411             if (ACPI_GET_DESCRIPTOR_TYPE (Info->ReturnObject) ==
 412                 ACPI_DESC_TYPE_NAMED)
 413             {
 414                 /*
 415                  * If we received a NS Node as a return object, this means that
 416                  * the object we are evaluating has nothing interesting to
 417                  * return (such as a mutex, etc.)  We return an error because
 418                  * these types are essentially unsupported by this interface.
 419                  * We don't check up front because this makes it easier to add
 420                  * support for various types at a later date if necessary.
 421                  */
 422                 Status = AE_TYPE;
 423                 Info->ReturnObject = NULL;   /* No need to delete a NS Node */
 424                 ReturnBuffer->Length = 0;
 425             }
 426
 427             if (ACPI_SUCCESS (Status))
 428             {
 429                 /* Dereference Index and RefOf references */
 430
 431                 AcpiNsResolveReferences (Info);
 432
 433                 /* Get the size of the returned object */
 434
 435                 Status = AcpiUtGetObjectSize (Info->ReturnObject,
 436                             &BufferSpaceNeeded);
 437                 if (ACPI_SUCCESS (Status))
 438                 {
 439                     /* Validate/Allocate/Clear caller buffer */
 440
 441                     Status = AcpiUtInitializeBuffer (ReturnBuffer,
 442                                 BufferSpaceNeeded);
 443                     if (ACPI_FAILURE (Status))
 444                     {
 445                         /*
 446                          * Caller's buffer is too small or a new one can't
 447                          * be allocated
 448                          */
 449                         ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 450                             "Needed buffer size %X, %s\n",
 451                             (UINT32) BufferSpaceNeeded,
 452                             AcpiFormatException (Status)));
 453                     }
 454                     else
 455                     {
 456                         /* We have enough space for the object, build it */
 457
 458                         Status = AcpiUtCopyIobjectToEobject (Info->ReturnObject,
 459                                     ReturnBuffer);
 460                     }
 461                 }
 462             }
 463         }
 464     }
 465
 466     if (Info->ReturnObject)
 467     {
 468         /*
 469          * Delete the internal return object. NOTE: Interpreter must be
 470          * locked to avoid race condition.
 471          */
 472         AcpiExEnterInterpreter ();
 473
 474         /* Remove one reference on the return object (should delete it) */
 475
 476         AcpiUtRemoveReference (Info->ReturnObject);
 477         AcpiExExitInterpreter ();
 478     }
 479
 480
 481 Cleanup:
 482
 483     /* Free the input parameter list (if we created one) */
 484
 485     if (Info->Parameters)
 486     {
 487         /* Free the allocated parameter block */
 488
 489         AcpiUtDeleteInternalObjectList (Info->Parameters);
 490     }
 491
 492     ACPI_FREE (Info);
 493     return_ACPI_STATUS (Status);
 494 }
 495
 496 ACPI_EXPORT_SYMBOL (AcpiEvaluateObject)
 497
 498
 499 /*******************************************************************************
 500  *
 501  * FUNCTION:    AcpiNsResolveReferences
 502  *
 503  * PARAMETERS:  Info                    - Evaluation info block
 504  *
 505  * RETURN:      Info->ReturnObject is replaced with the dereferenced object
 506  *
 507  * DESCRIPTION: Dereference certain reference objects. Called before an
 508  *              internal return object is converted to an external ACPI_OBJECT.
 509  *
 510  * Performs an automatic dereference of Index and RefOf reference objects.
 511  * These reference objects are not supported by the ACPI_OBJECT, so this is a
 512  * last resort effort to return something useful. Also, provides compatibility
 513  * with other ACPI implementations.
 514  *
 515  * NOTE: does not handle references within returned package objects or nested
 516  * references, but this support could be added later if found to be necessary.
 517  *
 518  ******************************************************************************/
 519
 520 static void
 521 AcpiNsResolveReferences (
 522     ACPI_EVALUATE_INFO      *Info)
 523 {
 524     ACPI_OPERAND_OBJECT     *ObjDesc = NULL;
 525     ACPI_NAMESPACE_NODE     *Node;
 526
 527
 528     /* We are interested in reference objects only */
 529
 530     if ((Info->ReturnObject)->Common.Type != ACPI_TYPE_LOCAL_REFERENCE)
 531     {
 532         return;
 533     }
 534
 535     /*
 536      * Two types of references are supported - those created by Index and
 537      * RefOf operators. A name reference (AML_NAMEPATH_OP) can be converted
 538      * to an ACPI_OBJECT, so it is not dereferenced here. A DdbHandle
 539      * (AML_LOAD_OP) cannot be dereferenced, nor can it be converted to
 540      * an ACPI_OBJECT.
 541      */
 542     switch (Info->ReturnObject->Reference.Class)
 543     {
 544     case ACPI_REFCLASS_INDEX:
 545
 546         ObjDesc = *(Info->ReturnObject->Reference.Where);
 547         break;
 548
 549     case ACPI_REFCLASS_REFOF:
 550
 551         Node = Info->ReturnObject->Reference.Object;
 552         if (Node)
 553         {
 554             ObjDesc = Node->Object;
 555         }
 556         break;
 557
 558     default:
 559
 560         return;
 561     }
 562
 563     /* Replace the existing reference object */
 564
 565     if (ObjDesc)
 566     {
 567         AcpiUtAddReference (ObjDesc);
 568         AcpiUtRemoveReference (Info->ReturnObject);
 569         Info->ReturnObject = ObjDesc;
 570     }
 571
 572     return;
 573 }
 574
 575
 576 /*******************************************************************************
 577  *
 578  * FUNCTION:    AcpiWalkNamespace
 579  *
 580  * PARAMETERS:  Type                - ACPI_OBJECT_TYPE to search for
 581  *              StartObject         - Handle in namespace where search begins
 582  *              MaxDepth            - Depth to which search is to reach
 583  *              DescendingCallback  - Called during tree descent
 584  *                                    when an object of "Type" is found
 585  *              AscendingCallback   - Called during tree ascent
 586  *                                    when an object of "Type" is found
 587  *              Context             - Passed to user function(s) above
 588  *              ReturnValue         - Location where return value of
 589  *                                    UserFunction is put if terminated early
 590  *
 591  * RETURNS      Return value from the UserFunction if terminated early.
 592  *              Otherwise, returns NULL.
 593  *
 594  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 595  *              starting (and ending) at the object specified by StartHandle.
 596  *              The callback function is called whenever an object that matches
 597  *              the type parameter is found. If the callback function returns
 598  *              a non-zero value, the search is terminated immediately and this
 599  *              value is returned to the caller.
 600  *
 601  *              The point of this procedure is to provide a generic namespace
 602  *              walk routine that can be called from multiple places to
 603  *              provide multiple services; the callback function(s) can be
 604  *              tailored to each task, whether it is a print function,
 605  *              a compare function, etc.
 606  *
 607  ******************************************************************************/
 608
 609 ACPI_STATUS
 610 AcpiWalkNamespace (
 611     ACPI_OBJECT_TYPE        Type,
 612     ACPI_HANDLE             StartObject,
 613     UINT32                  MaxDepth,
 614     ACPI_WALK_CALLBACK      DescendingCallback,
 615     ACPI_WALK_CALLBACK      AscendingCallback,
 616     void                    *Context,
 617     void                    **ReturnValue)
 618 {
 619     ACPI_STATUS             Status;
 620
 621
 622     ACPI_FUNCTION_TRACE (AcpiWalkNamespace);
 623
 624
 625     /* Parameter validation */
 626
 627     if ((Type > ACPI_TYPE_LOCAL_MAX) ||
 628         (!MaxDepth)                  ||
 629         (!DescendingCallback && !AscendingCallback))
 630     {
 631         return_ACPI_STATUS (AE_BAD_PARAMETER);
 632     }
 633
 634     /*
 635      * Need to acquire the namespace reader lock to prevent interference
 636      * with any concurrent table unloads (which causes the deletion of
 637      * namespace objects). We cannot allow the deletion of a namespace node
 638      * while the user function is using it. The exception to this are the
 639      * nodes created and deleted during control method execution -- these
 640      * nodes are marked as temporary nodes and are ignored by the namespace
 641      * walk. Thus, control methods can be executed while holding the
 642      * namespace deletion lock (and the user function can execute control
 643      * methods.)
 644      */
 645     Status = AcpiUtAcquireReadLock (&AcpiGbl_NamespaceRwLock);
 646     if (ACPI_FAILURE (Status))
 647     {
 648         return_ACPI_STATUS (Status);
 649     }
 650
 651     /*
 652      * Lock the namespace around the walk. The namespace will be
 653      * unlocked/locked around each call to the user function - since the user
 654      * function must be allowed to make ACPICA calls itself (for example, it
 655      * will typically execute control methods during device enumeration.)
 656      */
 657     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 658     if (ACPI_FAILURE (Status))
 659     {
 660         goto UnlockAndExit;
 661     }
 662
 663     /* Now we can validate the starting node */
 664
 665     if (!AcpiNsValidateHandle (StartObject))
 666     {
 667         Status = AE_BAD_PARAMETER;
 668         goto UnlockAndExit2;
 669     }
 670
 671     Status = AcpiNsWalkNamespace (Type, StartObject, MaxDepth,
 672                 ACPI_NS_WALK_UNLOCK, DescendingCallback,
 673                 AscendingCallback, Context, ReturnValue);
 674
 675 UnlockAndExit2:
 676     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 677
 678 UnlockAndExit:
 679     (void) AcpiUtReleaseReadLock (&AcpiGbl_NamespaceRwLock);
 680     return_ACPI_STATUS (Status);
 681 }
 682
 683 ACPI_EXPORT_SYMBOL (AcpiWalkNamespace)
 684
 685
 686 /*******************************************************************************
 687  *
 688  * FUNCTION:    AcpiNsGetDeviceCallback
 689  *
 690  * PARAMETERS:  Callback from AcpiGetDevice
 691  *
 692  * RETURN:      Status
 693  *
 694  * DESCRIPTION: Takes callbacks from WalkNamespace and filters out all non-
 695  *              present devices, or if they specified a HID, it filters based
 696  *              on that.
 697  *
 698  ******************************************************************************/
 699
 700 static ACPI_STATUS
 701 AcpiNsGetDeviceCallback (
 702     ACPI_HANDLE             ObjHandle,
 703     UINT32                  NestingLevel,
 704     void                    *Context,
 705     void                    **ReturnValue)
 706 {
 707     ACPI_GET_DEVICES_INFO   *Info = Context;
 708     ACPI_STATUS             Status;
 709     ACPI_NAMESPACE_NODE     *Node;
 710     UINT32                  Flags;
 711     ACPI_PNP_DEVICE_ID      *Hid;
 712     ACPI_PNP_DEVICE_ID_LIST *Cid;
 713     UINT32                  i;
 714     BOOLEAN                 Found;
 715     int                     NoMatch;
 716
 717
 718     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 719     if (ACPI_FAILURE (Status))
 720     {
 721         return (Status);
 722     }
 723
 724     Node = AcpiNsValidateHandle (ObjHandle);
 725     Status = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 726     if (ACPI_FAILURE (Status))
 727     {
 728         return (Status);
 729     }
 730
 731     if (!Node)
 732     {
 733         return (AE_BAD_PARAMETER);
 734     }
 735
 736     /*
 737      * First, filter based on the device HID and CID.
 738      *
 739      * 01/2010: For this case where a specific HID is requested, we don't
 740      * want to run _STA until we have an actual HID match. Thus, we will
 741      * not unnecessarily execute _STA on devices for which the caller
 742      * doesn't care about. Previously, _STA was executed unconditionally
 743      * on all devices found here.
 744      *
 745      * A side-effect of this change is that now we will continue to search
 746      * for a matching HID even under device trees where the parent device
 747      * would have returned a _STA that indicates it is not present or
 748      * not functioning (thus aborting the search on that branch).
 749      */
 750     if (Info->Hid != NULL)
 751     {
 752         Status = AcpiUtExecute_HID (Node, &Hid);
 753         if (Status == AE_NOT_FOUND)
 754         {
 755             return (AE_OK);
 756         }
 757         else if (ACPI_FAILURE (Status))
 758         {
 759             return (AE_CTRL_DEPTH);
 760         }
 761
 762         NoMatch = ACPI_STRCMP (Hid->String, Info->Hid);
 763         ACPI_FREE (Hid);
 764
 765         if (NoMatch)
 766         {
 767             /*
 768              * HID does not match, attempt match within the
 769              * list of Compatible IDs (CIDs)
 770              */
 771             Status = AcpiUtExecute_CID (Node, &Cid);
 772             if (Status == AE_NOT_FOUND)
 773             {
 774                 return (AE_OK);
 775             }
 776             else if (ACPI_FAILURE (Status))
 777             {
 778                 return (AE_CTRL_DEPTH);
 779             }
 780
 781             /* Walk the CID list */
 782
 783             Found = FALSE;
 784             for (i = 0; i < Cid->Count; i++)
 785             {
 786                 if (ACPI_STRCMP (Cid->Ids[i].String, Info->Hid) == 0)
 787                 {
 788                     /* Found a matching CID */
 789
 790                     Found = TRUE;
 791                     break;
 792                 }
 793             }
 794
 795             ACPI_FREE (Cid);
 796             if (!Found)
 797             {
 798                 return (AE_OK);
 799             }
 800         }
 801     }
 802
 803     /* Run _STA to determine if device is present */
 804
 805     Status = AcpiUtExecute_STA (Node, &Flags);
 806     if (ACPI_FAILURE (Status))
 807     {
 808         return (AE_CTRL_DEPTH);
 809     }
 810
 811     if (!(Flags & ACPI_STA_DEVICE_PRESENT) &&
 812         !(Flags & ACPI_STA_DEVICE_FUNCTIONING))
 813     {
 814         /*
 815          * Don't examine the children of the device only when the
 816          * device is neither present nor functional. See ACPI spec,
 817          * description of _STA for more information.
 818          */
 819         return (AE_CTRL_DEPTH);
 820     }
 821
 822     /* We have a valid device, invoke the user function */
 823
 824     Status = Info->UserFunction (ObjHandle, NestingLevel, Info->Context,
 825                 ReturnValue);
 826     return (Status);
 827 }
 828
 829
 830 /*******************************************************************************
 831  *
 832  * FUNCTION:    AcpiGetDevices
 833  *
 834  * PARAMETERS:  HID                 - HID to search for. Can be NULL.
 835  *              UserFunction        - Called when a matching object is found
 836  *              Context             - Passed to user function
 837  *              ReturnValue         - Location where return value of
 838  *                                    UserFunction is put if terminated early
 839  *
 840  * RETURNS      Return value from the UserFunction if terminated early.
 841  *              Otherwise, returns NULL.
 842  *
 843  * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
 844  *              starting (and ending) at the object specified by StartHandle.
 845  *              The UserFunction is called whenever an object of type
 846  *              Device is found. If the user function returns
 847  *              a non-zero value, the search is terminated immediately and this
 848  *              value is returned to the caller.
 849  *
 850  *              This is a wrapper for WalkNamespace, but the callback performs
 851  *              additional filtering. Please see AcpiNsGetDeviceCallback.
 852  *
 853  ******************************************************************************/
 854
 855 ACPI_STATUS
 856 AcpiGetDevices (
 857     char                    *HID,
 858     ACPI_WALK_CALLBACK      UserFunction,
 859     void                    *Context,
 860     void                    **ReturnValue)
 861 {
 862     ACPI_STATUS             Status;
 863     ACPI_GET_DEVICES_INFO   Info;
 864
 865
 866     ACPI_FUNCTION_TRACE (AcpiGetDevices);
 867
 868
 869     /* Parameter validation */
 870
 871     if (!UserFunction)
 872     {
 873         return_ACPI_STATUS (AE_BAD_PARAMETER);
 874     }
 875
 876     /*
 877      * We're going to call their callback from OUR callback, so we need
 878      * to know what it is, and their context parameter.
 879      */
 880     Info.Hid          = HID;
 881     Info.Context      = Context;
 882     Info.UserFunction = UserFunction;
 883
 884     /*
 885      * Lock the namespace around the walk.
 886      * The namespace will be unlocked/locked around each call
 887      * to the user function - since this function
 888      * must be allowed to make Acpi calls itself.
 889      */
 890     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 891     if (ACPI_FAILURE (Status))
 892     {
 893         return_ACPI_STATUS (Status);
 894     }
 895
 896     Status = AcpiNsWalkNamespace (ACPI_TYPE_DEVICE, ACPI_ROOT_OBJECT,
 897                 ACPI_UINT32_MAX, ACPI_NS_WALK_UNLOCK,
 898                 AcpiNsGetDeviceCallback, NULL, &Info, ReturnValue);
 899
 900     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 901     return_ACPI_STATUS (Status);
 902 }
 903
 904 ACPI_EXPORT_SYMBOL (AcpiGetDevices)
 905
 906
 907 /*******************************************************************************
 908  *
 909  * FUNCTION:    AcpiAttachData
 910  *
 911  * PARAMETERS:  ObjHandle           - Namespace node
 912  *              Handler             - Handler for this attachment
 913  *              Data                - Pointer to data to be attached
 914  *
 915  * RETURN:      Status
 916  *
 917  * DESCRIPTION: Attach arbitrary data and handler to a namespace node.
 918  *
 919  ******************************************************************************/
 920
 921 ACPI_STATUS
 922 AcpiAttachData (
 923     ACPI_HANDLE             ObjHandle,
 924     ACPI_OBJECT_HANDLER     Handler,
 925     void                    *Data)
 926 {
 927     ACPI_NAMESPACE_NODE     *Node;
 928     ACPI_STATUS             Status;
 929
 930
 931     /* Parameter validation */
 932
 933     if (!ObjHandle  ||
 934         !Handler    ||
 935         !Data)
 936     {
 937         return (AE_BAD_PARAMETER);
 938     }
 939
 940     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 941     if (ACPI_FAILURE (Status))
 942     {
 943         return (Status);
 944     }
 945
 946     /* Convert and validate the handle */
 947
 948     Node = AcpiNsValidateHandle (ObjHandle);
 949     if (!Node)
 950     {
 951         Status = AE_BAD_PARAMETER;
 952         goto UnlockAndExit;
 953     }
 954
 955     Status = AcpiNsAttachData (Node, Handler, Data);
 956
 957 UnlockAndExit:
 958     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
 959     return (Status);
 960 }
 961
 962 ACPI_EXPORT_SYMBOL (AcpiAttachData)
 963
 964
 965 /*******************************************************************************
 966  *
 967  * FUNCTION:    AcpiDetachData
 968  *
 969  * PARAMETERS:  ObjHandle           - Namespace node handle
 970  *              Handler             - Handler used in call to AcpiAttachData
 971  *
 972  * RETURN:      Status
 973  *
 974  * DESCRIPTION: Remove data that was previously attached to a node.
 975  *
 976  ******************************************************************************/
 977
 978 ACPI_STATUS
 979 AcpiDetachData (
 980     ACPI_HANDLE             ObjHandle,
 981     ACPI_OBJECT_HANDLER     Handler)
 982 {
 983     ACPI_NAMESPACE_NODE     *Node;
 984     ACPI_STATUS             Status;
 985
 986
 987     /* Parameter validation */
 988
 989     if (!ObjHandle  ||
 990         !Handler)
 991     {
 992         return (AE_BAD_PARAMETER);
 993     }
 994
 995     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
 996     if (ACPI_FAILURE (Status))
 997     {
 998         return (Status);
 999     }
1000
1001     /* Convert and validate the handle */
1002
1003     Node = AcpiNsValidateHandle (ObjHandle);
1004     if (!Node)
1005     {
1006         Status = AE_BAD_PARAMETER;
1007         goto UnlockAndExit;
1008     }
1009
1010     Status = AcpiNsDetachData (Node, Handler);
1011
1012 UnlockAndExit:
1013     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
1014     return (Status);
1015 }
1016
1017 ACPI_EXPORT_SYMBOL (AcpiDetachData)
1018
1019
1020 /*******************************************************************************
1021  *
1022  * FUNCTION:    AcpiGetData
1023  *
1024  * PARAMETERS:  ObjHandle           - Namespace node
1025  *              Handler             - Handler used in call to AttachData
1026  *              Data                - Where the data is returned
1027  *
1028  * RETURN:      Status
1029  *
1030  * DESCRIPTION: Retrieve data that was previously attached to a namespace node.
1031  *
1032  ******************************************************************************/
1033
1034 ACPI_STATUS
1035 AcpiGetData (
1036     ACPI_HANDLE             ObjHandle,
1037     ACPI_OBJECT_HANDLER     Handler,
1038     void                    **Data)
1039 {
1040     ACPI_NAMESPACE_NODE     *Node;
1041     ACPI_STATUS             Status;
1042
1043
1044     /* Parameter validation */
1045
1046     if (!ObjHandle  ||
1047         !Handler    ||
1048         !Data)
1049     {
1050         return (AE_BAD_PARAMETER);
1051     }
1052
1053     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
1054     if (ACPI_FAILURE (Status))
1055     {
1056         return (Status);
1057     }
1058
1059     /* Convert and validate the handle */
1060
1061     Node = AcpiNsValidateHandle (ObjHandle);
1062     if (!Node)
1063     {
1064         Status = AE_BAD_PARAMETER;
1065         goto UnlockAndExit;
1066     }
1067
1068     Status = AcpiNsGetAttachedData (Node, Handler, Data);
1069
1070 UnlockAndExit:
1071     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
1072     return (Status);
1073 }
1074
1075 ACPI_EXPORT_SYMBOL (AcpiGetData)