xref: /freebsd/sys/contrib/dev/acpica/components/namespace/nsxfeval.c (revision 8d20be1e22095c27faf8fe8b2f0d089739cc742e)
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)
1070