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