1 /*******************************************************************************
3 * Module Name: nsxfeval - Public interfaces to the ACPI subsystem
4 * ACPI Object evaluation interfaces
6 ******************************************************************************/
8 /******************************************************************************
12 * Some or all of this work - Copyright (c) 1999 - 2017, Intel Corp.
13 * All rights reserved.
17 * 2.1. This is your license from Intel Corp. under its intellectual property
18 * rights. You may have additional license terms from the party that provided
19 * you this software, covering your right to use that party's intellectual
22 * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
23 * copy of the source code appearing in this file ("Covered Code") an
24 * irrevocable, perpetual, worldwide license under Intel's copyrights in the
25 * base code distributed originally by Intel ("Original Intel Code") to copy,
26 * make derivatives, distribute, use and display any portion of the Covered
27 * Code in any form, with the right to sublicense such rights; and
29 * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
30 * license (with the right to sublicense), under only those claims of Intel
31 * patents that are infringed by the Original Intel Code, to make, use, sell,
32 * offer to sell, and import the Covered Code and derivative works thereof
33 * solely to the minimum extent necessary to exercise the above copyright
34 * license, and in no event shall the patent license extend to any additions
35 * to or modifications of the Original Intel Code. No other license or right
36 * is granted directly or by implication, estoppel or otherwise;
38 * The above copyright and patent license is granted only if the following
43 * 3.1. Redistribution of Source with Rights to Further Distribute Source.
44 * Redistribution of source code of any substantial portion of the Covered
45 * Code or modification with rights to further distribute source must include
46 * the above Copyright Notice, the above License, this list of Conditions,
47 * and the following Disclaimer and Export Compliance provision. In addition,
48 * Licensee must cause all Covered Code to which Licensee contributes to
49 * contain a file documenting the changes Licensee made to create that Covered
50 * Code and the date of any change. Licensee must include in that file the
51 * documentation of any changes made by any predecessor Licensee. Licensee
52 * must include a prominent statement that the modification is derived,
53 * directly or indirectly, from Original Intel Code.
55 * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
56 * Redistribution of source code of any substantial portion of the Covered
57 * Code or modification without rights to further distribute source must
58 * include the following Disclaimer and Export Compliance provision in the
59 * documentation and/or other materials provided with distribution. In
60 * addition, Licensee may not authorize further sublicense of source of any
61 * portion of the Covered Code, and must include terms to the effect that the
62 * license from Licensee to its licensee is limited to the intellectual
63 * property embodied in the software Licensee provides to its licensee, and
64 * not to intellectual property embodied in modifications its licensee may
67 * 3.3. Redistribution of Executable. Redistribution in executable form of any
68 * substantial portion of the Covered Code or modification must reproduce the
69 * above Copyright Notice, and the following Disclaimer and Export Compliance
70 * provision in the documentation and/or other materials provided with the
73 * 3.4. Intel retains all right, title, and interest in and to the Original
76 * 3.5. Neither the name Intel nor any other trademark owned or controlled by
77 * Intel shall be used in advertising or otherwise to promote the sale, use or
78 * other dealings in products derived from or relating to the Covered Code
79 * without prior written authorization from Intel.
81 * 4. Disclaimer and Export Compliance
83 * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
84 * HERE. ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
85 * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT, ASSISTANCE,
86 * INSTALLATION, TRAINING OR OTHER SERVICES. INTEL WILL NOT PROVIDE ANY
87 * UPDATES, ENHANCEMENTS OR EXTENSIONS. INTEL SPECIFICALLY DISCLAIMS ANY
88 * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
91 * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
92 * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
93 * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
94 * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
95 * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
96 * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES. THESE LIMITATIONS
97 * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
100 * 4.3. Licensee shall not export, either directly or indirectly, any of this
101 * software or system incorporating such software without first obtaining any
102 * required license or other approval from the U. S. Department of Commerce or
103 * any other agency or department of the United States Government. In the
104 * event Licensee exports any such software from the United States or
105 * re-exports any such software from a foreign destination, Licensee shall
106 * ensure that the distribution and export/re-export of the software is in
107 * compliance with all laws, regulations, orders, or other restrictions of the
108 * U.S. Export Administration Regulations. Licensee agrees that neither it nor
109 * any of its subsidiaries will export/re-export any technical data, process,
110 * software, or service, directly or indirectly, to any country for which the
111 * United States government or any agency thereof requires an export license,
112 * other governmental approval, or letter of assurance, without first obtaining
113 * such license, approval or letter.
115 *****************************************************************************
117 * Alternatively, you may choose to be licensed under the terms of the
120 * Redistribution and use in source and binary forms, with or without
121 * modification, are permitted provided that the following conditions
123 * 1. Redistributions of source code must retain the above copyright
124 * notice, this list of conditions, and the following disclaimer,
125 * without modification.
126 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
127 * substantially similar to the "NO WARRANTY" disclaimer below
128 * ("Disclaimer") and any redistribution must be conditioned upon
129 * including a substantially similar Disclaimer requirement for further
130 * binary redistribution.
131 * 3. Neither the names of the above-listed copyright holders nor the names
132 * of any contributors may be used to endorse or promote products derived
133 * from this software without specific prior written permission.
135 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
136 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
137 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
138 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
139 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
140 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
141 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
142 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
143 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
144 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
145 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
147 * Alternatively, you may choose to be licensed under the terms of the
148 * GNU General Public License ("GPL") version 2 as published by the Free
149 * Software Foundation.
151 *****************************************************************************/
153 #define EXPORT_ACPI_INTERFACES
155 #include <contrib/dev/acpica/include/acpi.h>
156 #include <contrib/dev/acpica/include/accommon.h>
157 #include <contrib/dev/acpica/include/acnamesp.h>
158 #include <contrib/dev/acpica/include/acinterp.h>
161 #define _COMPONENT ACPI_NAMESPACE
162 ACPI_MODULE_NAME ("nsxfeval")
164 /* Local prototypes */
167 AcpiNsResolveReferences (
168 ACPI_EVALUATE_INFO *Info);
171 /*******************************************************************************
173 * FUNCTION: AcpiEvaluateObjectTyped
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 * ReturnType - Expected type of return object
186 * DESCRIPTION: Find and evaluate the given object, passing the given
187 * parameters if necessary. One of "Handle" or "Pathname" must
188 * be valid (non-null)
190 ******************************************************************************/
193 AcpiEvaluateObjectTyped (
195 ACPI_STRING Pathname,
196 ACPI_OBJECT_LIST *ExternalParams,
197 ACPI_BUFFER *ReturnBuffer,
198 ACPI_OBJECT_TYPE ReturnType)
201 BOOLEAN FreeBufferOnError = FALSE;
204 ACPI_FUNCTION_TRACE (AcpiEvaluateObjectTyped);
207 /* Return buffer must be valid */
211 return_ACPI_STATUS (AE_BAD_PARAMETER);
214 if (ReturnBuffer->Length == ACPI_ALLOCATE_BUFFER)
216 FreeBufferOnError = TRUE;
219 /* Evaluate the object */
221 Status = AcpiEvaluateObject (Handle, Pathname,
222 ExternalParams, ReturnBuffer);
223 if (ACPI_FAILURE (Status))
225 return_ACPI_STATUS (Status);
228 /* Type ANY means "don't care" */
230 if (ReturnType == ACPI_TYPE_ANY)
232 return_ACPI_STATUS (AE_OK);
235 if (ReturnBuffer->Length == 0)
237 /* Error because caller specifically asked for a return value */
239 ACPI_ERROR ((AE_INFO, "No return value"));
240 return_ACPI_STATUS (AE_NULL_OBJECT);
243 /* Examine the object type returned from EvaluateObject */
245 if (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type == ReturnType)
247 return_ACPI_STATUS (AE_OK);
250 /* Return object type does not match requested type */
252 ACPI_ERROR ((AE_INFO,
253 "Incorrect return type [%s] requested [%s]",
254 AcpiUtGetTypeName (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type),
255 AcpiUtGetTypeName (ReturnType)));
257 if (FreeBufferOnError)
260 * Free a buffer created via ACPI_ALLOCATE_BUFFER.
261 * Note: We use AcpiOsFree here because AcpiOsAllocate was used
262 * to allocate the buffer. This purposefully bypasses the
263 * (optionally enabled) allocation tracking mechanism since we
264 * only want to track internal allocations.
266 AcpiOsFree (ReturnBuffer->Pointer);
267 ReturnBuffer->Pointer = NULL;
270 ReturnBuffer->Length = 0;
271 return_ACPI_STATUS (AE_TYPE);
274 ACPI_EXPORT_SYMBOL (AcpiEvaluateObjectTyped)
277 /*******************************************************************************
279 * FUNCTION: AcpiEvaluateObject
281 * PARAMETERS: Handle - Object handle (optional)
282 * Pathname - Object pathname (optional)
283 * ExternalParams - List of parameters to pass to method,
284 * terminated by NULL. May be NULL
285 * if no parameters are being passed.
286 * ReturnBuffer - Where to put method's return value (if
287 * any). If NULL, no value is returned.
291 * DESCRIPTION: Find and evaluate the given object, passing the given
292 * parameters if necessary. One of "Handle" or "Pathname" must
293 * be valid (non-null)
295 ******************************************************************************/
300 ACPI_STRING Pathname,
301 ACPI_OBJECT_LIST *ExternalParams,
302 ACPI_BUFFER *ReturnBuffer)
305 ACPI_EVALUATE_INFO *Info;
306 ACPI_SIZE BufferSpaceNeeded;
310 ACPI_FUNCTION_TRACE (AcpiEvaluateObject);
313 /* Allocate and initialize the evaluation information block */
315 Info = ACPI_ALLOCATE_ZEROED (sizeof (ACPI_EVALUATE_INFO));
318 return_ACPI_STATUS (AE_NO_MEMORY);
321 /* Convert and validate the device handle */
323 Info->PrefixNode = AcpiNsValidateHandle (Handle);
324 if (!Info->PrefixNode)
326 Status = AE_BAD_PARAMETER;
331 * Get the actual namespace node for the target object.
332 * Handles these cases:
334 * 1) Null node, valid pathname from root (absolute path)
335 * 2) Node and valid pathname (path relative to Node)
336 * 3) Node, Null pathname
339 (ACPI_IS_ROOT_PREFIX (Pathname[0])))
341 /* The path is fully qualified, just evaluate by name */
343 Info->PrefixNode = NULL;
348 * A handle is optional iff a fully qualified pathname is specified.
349 * Since we've already handled fully qualified names above, this is
354 ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
355 "Both Handle and Pathname are NULL"));
359 ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
360 "Null Handle with relative pathname [%s]", Pathname));
363 Status = AE_BAD_PARAMETER;
367 Info->RelativePathname = Pathname;
370 * Convert all external objects passed as arguments to the
371 * internal version(s).
373 if (ExternalParams && ExternalParams->Count)
375 Info->ParamCount = (UINT16) ExternalParams->Count;
377 /* Warn on impossible argument count */
379 if (Info->ParamCount > ACPI_METHOD_NUM_ARGS)
381 ACPI_WARN_PREDEFINED ((AE_INFO, Pathname, ACPI_WARN_ALWAYS,
382 "Excess arguments (%u) - using only %u",
383 Info->ParamCount, ACPI_METHOD_NUM_ARGS));
385 Info->ParamCount = ACPI_METHOD_NUM_ARGS;
389 * Allocate a new parameter block for the internal objects
390 * Add 1 to count to allow for null terminated internal list
392 Info->Parameters = ACPI_ALLOCATE_ZEROED (
393 ((ACPI_SIZE) Info->ParamCount + 1) * sizeof (void *));
394 if (!Info->Parameters)
396 Status = AE_NO_MEMORY;
400 /* Convert each external object in the list to an internal object */
402 for (i = 0; i < Info->ParamCount; i++)
404 Status = AcpiUtCopyEobjectToIobject (
405 &ExternalParams->Pointer[i], &Info->Parameters[i]);
406 if (ACPI_FAILURE (Status))
412 Info->Parameters[Info->ParamCount] = NULL;
416 #ifdef _FUTURE_FEATURE
419 * Begin incoming argument count analysis. Check for too few args
422 switch (AcpiNsGetType (Info->Node))
424 case ACPI_TYPE_METHOD:
426 /* Check incoming argument count against the method definition */
428 if (Info->ObjDesc->Method.ParamCount > Info->ParamCount)
430 ACPI_ERROR ((AE_INFO,
431 "Insufficient arguments (%u) - %u are required",
433 Info->ObjDesc->Method.ParamCount));
435 Status = AE_MISSING_ARGUMENTS;
439 else if (Info->ObjDesc->Method.ParamCount < Info->ParamCount)
441 ACPI_WARNING ((AE_INFO,
442 "Excess arguments (%u) - only %u are required",
444 Info->ObjDesc->Method.ParamCount));
446 /* Just pass the required number of arguments */
448 Info->ParamCount = Info->ObjDesc->Method.ParamCount;
452 * Any incoming external objects to be passed as arguments to the
453 * method must be converted to internal objects
455 if (Info->ParamCount)
458 * Allocate a new parameter block for the internal objects
459 * Add 1 to count to allow for null terminated internal list
461 Info->Parameters = ACPI_ALLOCATE_ZEROED (
462 ((ACPI_SIZE) Info->ParamCount + 1) * sizeof (void *));
463 if (!Info->Parameters)
465 Status = AE_NO_MEMORY;
469 /* Convert each external object in the list to an internal object */
471 for (i = 0; i < Info->ParamCount; i++)
473 Status = AcpiUtCopyEobjectToIobject (
474 &ExternalParams->Pointer[i], &Info->Parameters[i]);
475 if (ACPI_FAILURE (Status))
481 Info->Parameters[Info->ParamCount] = NULL;
487 /* Warn if arguments passed to an object that is not a method */
489 if (Info->ParamCount)
491 ACPI_WARNING ((AE_INFO,
492 "%u arguments were passed to a non-method ACPI object",
501 /* Now we can evaluate the object */
503 Status = AcpiNsEvaluate (Info);
506 * If we are expecting a return value, and all went well above,
507 * copy the return value to an external object.
511 goto CleanupReturnObject;
514 if (!Info->ReturnObject)
516 ReturnBuffer->Length = 0;
520 if (ACPI_GET_DESCRIPTOR_TYPE (Info->ReturnObject) ==
521 ACPI_DESC_TYPE_NAMED)
524 * If we received a NS Node as a return object, this means that
525 * the object we are evaluating has nothing interesting to
526 * return (such as a mutex, etc.) We return an error because
527 * these types are essentially unsupported by this interface.
528 * We don't check up front because this makes it easier to add
529 * support for various types at a later date if necessary.
532 Info->ReturnObject = NULL; /* No need to delete a NS Node */
533 ReturnBuffer->Length = 0;
536 if (ACPI_FAILURE (Status))
538 goto CleanupReturnObject;
541 /* Dereference Index and RefOf references */
543 AcpiNsResolveReferences (Info);
545 /* Get the size of the returned object */
547 Status = AcpiUtGetObjectSize (Info->ReturnObject,
549 if (ACPI_SUCCESS (Status))
551 /* Validate/Allocate/Clear caller buffer */
553 Status = AcpiUtInitializeBuffer (ReturnBuffer,
555 if (ACPI_FAILURE (Status))
558 * Caller's buffer is too small or a new one can't
561 ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
562 "Needed buffer size %X, %s\n",
563 (UINT32) BufferSpaceNeeded,
564 AcpiFormatException (Status)));
568 /* We have enough space for the object, build it */
570 Status = AcpiUtCopyIobjectToEobject (
571 Info->ReturnObject, ReturnBuffer);
577 if (Info->ReturnObject)
580 * Delete the internal return object. NOTE: Interpreter must be
581 * locked to avoid race condition.
583 AcpiExEnterInterpreter ();
585 /* Remove one reference on the return object (should delete it) */
587 AcpiUtRemoveReference (Info->ReturnObject);
588 AcpiExExitInterpreter ();
594 /* Free the input parameter list (if we created one) */
596 if (Info->Parameters)
598 /* Free the allocated parameter block */
600 AcpiUtDeleteInternalObjectList (Info->Parameters);
604 return_ACPI_STATUS (Status);
607 ACPI_EXPORT_SYMBOL (AcpiEvaluateObject)
610 /*******************************************************************************
612 * FUNCTION: AcpiNsResolveReferences
614 * PARAMETERS: Info - Evaluation info block
616 * RETURN: Info->ReturnObject is replaced with the dereferenced object
618 * DESCRIPTION: Dereference certain reference objects. Called before an
619 * internal return object is converted to an external ACPI_OBJECT.
621 * Performs an automatic dereference of Index and RefOf reference objects.
622 * These reference objects are not supported by the ACPI_OBJECT, so this is a
623 * last resort effort to return something useful. Also, provides compatibility
624 * with other ACPI implementations.
626 * NOTE: does not handle references within returned package objects or nested
627 * references, but this support could be added later if found to be necessary.
629 ******************************************************************************/
632 AcpiNsResolveReferences (
633 ACPI_EVALUATE_INFO *Info)
635 ACPI_OPERAND_OBJECT *ObjDesc = NULL;
636 ACPI_NAMESPACE_NODE *Node;
639 /* We are interested in reference objects only */
641 if ((Info->ReturnObject)->Common.Type != ACPI_TYPE_LOCAL_REFERENCE)
647 * Two types of references are supported - those created by Index and
648 * RefOf operators. A name reference (AML_NAMEPATH_OP) can be converted
649 * to an ACPI_OBJECT, so it is not dereferenced here. A DdbHandle
650 * (AML_LOAD_OP) cannot be dereferenced, nor can it be converted to
653 switch (Info->ReturnObject->Reference.Class)
655 case ACPI_REFCLASS_INDEX:
657 ObjDesc = *(Info->ReturnObject->Reference.Where);
660 case ACPI_REFCLASS_REFOF:
662 Node = Info->ReturnObject->Reference.Object;
665 ObjDesc = Node->Object;
674 /* Replace the existing reference object */
678 AcpiUtAddReference (ObjDesc);
679 AcpiUtRemoveReference (Info->ReturnObject);
680 Info->ReturnObject = ObjDesc;
687 /*******************************************************************************
689 * FUNCTION: AcpiWalkNamespace
691 * PARAMETERS: Type - ACPI_OBJECT_TYPE to search for
692 * StartObject - Handle in namespace where search begins
693 * MaxDepth - Depth to which search is to reach
694 * DescendingCallback - Called during tree descent
695 * when an object of "Type" is found
696 * AscendingCallback - Called during tree ascent
697 * when an object of "Type" is found
698 * Context - Passed to user function(s) above
699 * ReturnValue - Location where return value of
700 * UserFunction is put if terminated early
702 * RETURNS Return value from the UserFunction if terminated early.
703 * Otherwise, returns NULL.
705 * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
706 * starting (and ending) at the object specified by StartHandle.
707 * The callback function is called whenever an object that matches
708 * the type parameter is found. If the callback function returns
709 * a non-zero value, the search is terminated immediately and this
710 * value is returned to the caller.
712 * The point of this procedure is to provide a generic namespace
713 * walk routine that can be called from multiple places to
714 * provide multiple services; the callback function(s) can be
715 * tailored to each task, whether it is a print function,
716 * a compare function, etc.
718 ******************************************************************************/
722 ACPI_OBJECT_TYPE Type,
723 ACPI_HANDLE StartObject,
725 ACPI_WALK_CALLBACK DescendingCallback,
726 ACPI_WALK_CALLBACK AscendingCallback,
733 ACPI_FUNCTION_TRACE (AcpiWalkNamespace);
736 /* Parameter validation */
738 if ((Type > ACPI_TYPE_LOCAL_MAX) ||
740 (!DescendingCallback && !AscendingCallback))
742 return_ACPI_STATUS (AE_BAD_PARAMETER);
746 * Need to acquire the namespace reader lock to prevent interference
747 * with any concurrent table unloads (which causes the deletion of
748 * namespace objects). We cannot allow the deletion of a namespace node
749 * while the user function is using it. The exception to this are the
750 * nodes created and deleted during control method execution -- these
751 * nodes are marked as temporary nodes and are ignored by the namespace
752 * walk. Thus, control methods can be executed while holding the
753 * namespace deletion lock (and the user function can execute control
756 Status = AcpiUtAcquireReadLock (&AcpiGbl_NamespaceRwLock);
757 if (ACPI_FAILURE (Status))
759 return_ACPI_STATUS (Status);
763 * Lock the namespace around the walk. The namespace will be
764 * unlocked/locked around each call to the user function - since the user
765 * function must be allowed to make ACPICA calls itself (for example, it
766 * will typically execute control methods during device enumeration.)
768 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
769 if (ACPI_FAILURE (Status))
774 /* Now we can validate the starting node */
776 if (!AcpiNsValidateHandle (StartObject))
778 Status = AE_BAD_PARAMETER;
782 Status = AcpiNsWalkNamespace (Type, StartObject, MaxDepth,
783 ACPI_NS_WALK_UNLOCK, DescendingCallback,
784 AscendingCallback, Context, ReturnValue);
787 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
790 (void) AcpiUtReleaseReadLock (&AcpiGbl_NamespaceRwLock);
791 return_ACPI_STATUS (Status);
794 ACPI_EXPORT_SYMBOL (AcpiWalkNamespace)
797 /*******************************************************************************
799 * FUNCTION: AcpiNsGetDeviceCallback
801 * PARAMETERS: Callback from AcpiGetDevice
805 * DESCRIPTION: Takes callbacks from WalkNamespace and filters out all non-
806 * present devices, or if they specified a HID, it filters based
809 ******************************************************************************/
812 AcpiNsGetDeviceCallback (
813 ACPI_HANDLE ObjHandle,
818 ACPI_GET_DEVICES_INFO *Info = Context;
820 ACPI_NAMESPACE_NODE *Node;
822 ACPI_PNP_DEVICE_ID *Hid;
823 ACPI_PNP_DEVICE_ID_LIST *Cid;
829 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
830 if (ACPI_FAILURE (Status))
835 Node = AcpiNsValidateHandle (ObjHandle);
836 Status = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
837 if (ACPI_FAILURE (Status))
844 return (AE_BAD_PARAMETER);
848 * First, filter based on the device HID and CID.
850 * 01/2010: For this case where a specific HID is requested, we don't
851 * want to run _STA until we have an actual HID match. Thus, we will
852 * not unnecessarily execute _STA on devices for which the caller
853 * doesn't care about. Previously, _STA was executed unconditionally
854 * on all devices found here.
856 * A side-effect of this change is that now we will continue to search
857 * for a matching HID even under device trees where the parent device
858 * would have returned a _STA that indicates it is not present or
859 * not functioning (thus aborting the search on that branch).
861 if (Info->Hid != NULL)
863 Status = AcpiUtExecute_HID (Node, &Hid);
864 if (Status == AE_NOT_FOUND)
868 else if (ACPI_FAILURE (Status))
870 return (AE_CTRL_DEPTH);
873 NoMatch = strcmp (Hid->String, Info->Hid);
879 * HID does not match, attempt match within the
880 * list of Compatible IDs (CIDs)
882 Status = AcpiUtExecute_CID (Node, &Cid);
883 if (Status == AE_NOT_FOUND)
887 else if (ACPI_FAILURE (Status))
889 return (AE_CTRL_DEPTH);
892 /* Walk the CID list */
895 for (i = 0; i < Cid->Count; i++)
897 if (strcmp (Cid->Ids[i].String, Info->Hid) == 0)
899 /* Found a matching CID */
914 /* Run _STA to determine if device is present */
916 Status = AcpiUtExecute_STA (Node, &Flags);
917 if (ACPI_FAILURE (Status))
919 return (AE_CTRL_DEPTH);
922 if (!(Flags & ACPI_STA_DEVICE_PRESENT) &&
923 !(Flags & ACPI_STA_DEVICE_FUNCTIONING))
926 * Don't examine the children of the device only when the
927 * device is neither present nor functional. See ACPI spec,
928 * description of _STA for more information.
930 return (AE_CTRL_DEPTH);
933 /* We have a valid device, invoke the user function */
935 Status = Info->UserFunction (ObjHandle, NestingLevel,
936 Info->Context, ReturnValue);
941 /*******************************************************************************
943 * FUNCTION: AcpiGetDevices
945 * PARAMETERS: HID - HID to search for. Can be NULL.
946 * UserFunction - Called when a matching object is found
947 * Context - Passed to user function
948 * ReturnValue - Location where return value of
949 * UserFunction is put if terminated early
951 * RETURNS Return value from the UserFunction if terminated early.
952 * Otherwise, returns NULL.
954 * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
955 * starting (and ending) at the object specified by StartHandle.
956 * The UserFunction is called whenever an object of type
957 * Device is found. If the user function returns
958 * a non-zero value, the search is terminated immediately and this
959 * value is returned to the caller.
961 * This is a wrapper for WalkNamespace, but the callback performs
962 * additional filtering. Please see AcpiNsGetDeviceCallback.
964 ******************************************************************************/
969 ACPI_WALK_CALLBACK UserFunction,
974 ACPI_GET_DEVICES_INFO Info;
977 ACPI_FUNCTION_TRACE (AcpiGetDevices);
980 /* Parameter validation */
984 return_ACPI_STATUS (AE_BAD_PARAMETER);
988 * We're going to call their callback from OUR callback, so we need
989 * to know what it is, and their context parameter.
992 Info.Context = Context;
993 Info.UserFunction = UserFunction;
996 * Lock the namespace around the walk.
997 * The namespace will be unlocked/locked around each call
998 * to the user function - since this function
999 * must be allowed to make Acpi calls itself.
1001 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
1002 if (ACPI_FAILURE (Status))
1004 return_ACPI_STATUS (Status);
1007 Status = AcpiNsWalkNamespace (ACPI_TYPE_DEVICE, ACPI_ROOT_OBJECT,
1008 ACPI_UINT32_MAX, ACPI_NS_WALK_UNLOCK,
1009 AcpiNsGetDeviceCallback, NULL, &Info, ReturnValue);
1011 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
1012 return_ACPI_STATUS (Status);
1015 ACPI_EXPORT_SYMBOL (AcpiGetDevices)
1018 /*******************************************************************************
1020 * FUNCTION: AcpiAttachData
1022 * PARAMETERS: ObjHandle - Namespace node
1023 * Handler - Handler for this attachment
1024 * Data - Pointer to data to be attached
1028 * DESCRIPTION: Attach arbitrary data and handler to a namespace node.
1030 ******************************************************************************/
1034 ACPI_HANDLE ObjHandle,
1035 ACPI_OBJECT_HANDLER Handler,
1038 ACPI_NAMESPACE_NODE *Node;
1042 /* Parameter validation */
1048 return (AE_BAD_PARAMETER);
1051 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
1052 if (ACPI_FAILURE (Status))
1057 /* Convert and validate the handle */
1059 Node = AcpiNsValidateHandle (ObjHandle);
1062 Status = AE_BAD_PARAMETER;
1066 Status = AcpiNsAttachData (Node, Handler, Data);
1069 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
1073 ACPI_EXPORT_SYMBOL (AcpiAttachData)
1076 /*******************************************************************************
1078 * FUNCTION: AcpiDetachData
1080 * PARAMETERS: ObjHandle - Namespace node handle
1081 * Handler - Handler used in call to AcpiAttachData
1085 * DESCRIPTION: Remove data that was previously attached to a node.
1087 ******************************************************************************/
1091 ACPI_HANDLE ObjHandle,
1092 ACPI_OBJECT_HANDLER Handler)
1094 ACPI_NAMESPACE_NODE *Node;
1098 /* Parameter validation */
1103 return (AE_BAD_PARAMETER);
1106 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
1107 if (ACPI_FAILURE (Status))
1112 /* Convert and validate the handle */
1114 Node = AcpiNsValidateHandle (ObjHandle);
1117 Status = AE_BAD_PARAMETER;
1121 Status = AcpiNsDetachData (Node, Handler);
1124 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
1128 ACPI_EXPORT_SYMBOL (AcpiDetachData)
1131 /*******************************************************************************
1133 * FUNCTION: AcpiGetData
1135 * PARAMETERS: ObjHandle - Namespace node
1136 * Handler - Handler used in call to AttachData
1137 * Data - Where the data is returned
1141 * DESCRIPTION: Retrieve data that was previously attached to a namespace node.
1143 ******************************************************************************/
1147 ACPI_HANDLE ObjHandle,
1148 ACPI_OBJECT_HANDLER Handler,
1151 ACPI_NAMESPACE_NODE *Node;
1155 /* Parameter validation */
1161 return (AE_BAD_PARAMETER);
1164 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
1165 if (ACPI_FAILURE (Status))
1170 /* Convert and validate the handle */
1172 Node = AcpiNsValidateHandle (ObjHandle);
1175 Status = AE_BAD_PARAMETER;
1179 Status = AcpiNsGetAttachedData (Node, Handler, Data);
1182 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
1186 ACPI_EXPORT_SYMBOL (AcpiGetData)