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