1 /*******************************************************************************
3 * Module Name: nsxfeval - Public interfaces to the ACPI subsystem
4 * ACPI Object evaluation interfaces
7 ******************************************************************************/
9 /******************************************************************************
13 * Some or all of this work - Copyright (c) 1999 - 2007, Intel Corp.
14 * All rights reserved.
18 * 2.1. This is your license from Intel Corp. under its intellectual property
19 * rights. You may have additional license terms from the party that provided
20 * you this software, covering your right to use that party's intellectual
23 * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
24 * copy of the source code appearing in this file ("Covered Code") an
25 * irrevocable, perpetual, worldwide license under Intel's copyrights in the
26 * base code distributed originally by Intel ("Original Intel Code") to copy,
27 * make derivatives, distribute, use and display any portion of the Covered
28 * Code in any form, with the right to sublicense such rights; and
30 * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
31 * license (with the right to sublicense), under only those claims of Intel
32 * patents that are infringed by the Original Intel Code, to make, use, sell,
33 * offer to sell, and import the Covered Code and derivative works thereof
34 * solely to the minimum extent necessary to exercise the above copyright
35 * license, and in no event shall the patent license extend to any additions
36 * to or modifications of the Original Intel Code. No other license or right
37 * is granted directly or by implication, estoppel or otherwise;
39 * The above copyright and patent license is granted only if the following
44 * 3.1. Redistribution of Source with Rights to Further Distribute Source.
45 * Redistribution of source code of any substantial portion of the Covered
46 * Code or modification with rights to further distribute source must include
47 * the above Copyright Notice, the above License, this list of Conditions,
48 * and the following Disclaimer and Export Compliance provision. In addition,
49 * Licensee must cause all Covered Code to which Licensee contributes to
50 * contain a file documenting the changes Licensee made to create that Covered
51 * Code and the date of any change. Licensee must include in that file the
52 * documentation of any changes made by any predecessor Licensee. Licensee
53 * must include a prominent statement that the modification is derived,
54 * directly or indirectly, from Original Intel Code.
56 * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
57 * Redistribution of source code of any substantial portion of the Covered
58 * Code or modification without rights to further distribute source must
59 * include the following Disclaimer and Export Compliance provision in the
60 * documentation and/or other materials provided with distribution. In
61 * addition, Licensee may not authorize further sublicense of source of any
62 * portion of the Covered Code, and must include terms to the effect that the
63 * license from Licensee to its licensee is limited to the intellectual
64 * property embodied in the software Licensee provides to its licensee, and
65 * not to intellectual property embodied in modifications its licensee may
68 * 3.3. Redistribution of Executable. Redistribution in executable form of any
69 * substantial portion of the Covered Code or modification must reproduce the
70 * above Copyright Notice, and the following Disclaimer and Export Compliance
71 * provision in the documentation and/or other materials provided with the
74 * 3.4. Intel retains all right, title, and interest in and to the Original
77 * 3.5. Neither the name Intel nor any other trademark owned or controlled by
78 * Intel shall be used in advertising or otherwise to promote the sale, use or
79 * other dealings in products derived from or relating to the Covered Code
80 * without prior written authorization from Intel.
82 * 4. Disclaimer and Export Compliance
84 * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
85 * HERE. ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
86 * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT, ASSISTANCE,
87 * INSTALLATION, TRAINING OR OTHER SERVICES. INTEL WILL NOT PROVIDE ANY
88 * UPDATES, ENHANCEMENTS OR EXTENSIONS. INTEL SPECIFICALLY DISCLAIMS ANY
89 * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
92 * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
93 * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
94 * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
95 * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
96 * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
97 * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES. THESE LIMITATIONS
98 * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
101 * 4.3. Licensee shall not export, either directly or indirectly, any of this
102 * software or system incorporating such software without first obtaining any
103 * required license or other approval from the U. S. Department of Commerce or
104 * any other agency or department of the United States Government. In the
105 * event Licensee exports any such software from the United States or
106 * re-exports any such software from a foreign destination, Licensee shall
107 * ensure that the distribution and export/re-export of the software is in
108 * compliance with all laws, regulations, orders, or other restrictions of the
109 * U.S. Export Administration Regulations. Licensee agrees that neither it nor
110 * any of its subsidiaries will export/re-export any technical data, process,
111 * software, or service, directly or indirectly, to any country for which the
112 * United States government or any agency thereof requires an export license,
113 * other governmental approval, or letter of assurance, without first obtaining
114 * such license, approval or letter.
116 *****************************************************************************/
119 #define __NSXFEVAL_C__
121 #include <contrib/dev/acpica/acpi.h>
122 #include <contrib/dev/acpica/acnamesp.h>
123 #include <contrib/dev/acpica/acinterp.h>
126 #define _COMPONENT ACPI_NAMESPACE
127 ACPI_MODULE_NAME ("nsxfeval")
130 /*******************************************************************************
132 * FUNCTION: AcpiEvaluateObjectTyped
134 * PARAMETERS: Handle - Object handle (optional)
135 * Pathname - Object pathname (optional)
136 * ExternalParams - List of parameters to pass to method,
137 * terminated by NULL. May be NULL
138 * if no parameters are being passed.
139 * ReturnBuffer - Where to put method's return value (if
140 * any). If NULL, no value is returned.
141 * ReturnType - Expected type of return object
145 * DESCRIPTION: Find and evaluate the given object, passing the given
146 * parameters if necessary. One of "Handle" or "Pathname" must
147 * be valid (non-null)
149 ******************************************************************************/
152 AcpiEvaluateObjectTyped (
154 ACPI_STRING Pathname,
155 ACPI_OBJECT_LIST *ExternalParams,
156 ACPI_BUFFER *ReturnBuffer,
157 ACPI_OBJECT_TYPE ReturnType)
160 BOOLEAN MustFree = FALSE;
163 ACPI_FUNCTION_TRACE (AcpiEvaluateObjectTyped);
166 /* Return buffer must be valid */
170 return_ACPI_STATUS (AE_BAD_PARAMETER);
173 if (ReturnBuffer->Length == ACPI_ALLOCATE_BUFFER)
178 /* Evaluate the object */
180 Status = AcpiEvaluateObject (Handle, Pathname, ExternalParams, ReturnBuffer);
181 if (ACPI_FAILURE (Status))
183 return_ACPI_STATUS (Status);
186 /* Type ANY means "don't care" */
188 if (ReturnType == ACPI_TYPE_ANY)
190 return_ACPI_STATUS (AE_OK);
193 if (ReturnBuffer->Length == 0)
195 /* Error because caller specifically asked for a return value */
197 ACPI_ERROR ((AE_INFO, "No return value"));
198 return_ACPI_STATUS (AE_NULL_OBJECT);
201 /* Examine the object type returned from EvaluateObject */
203 if (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type == ReturnType)
205 return_ACPI_STATUS (AE_OK);
208 /* Return object type does not match requested type */
210 ACPI_ERROR ((AE_INFO,
211 "Incorrect return type [%s] requested [%s]",
212 AcpiUtGetTypeName (((ACPI_OBJECT *) ReturnBuffer->Pointer)->Type),
213 AcpiUtGetTypeName (ReturnType)));
217 /* Caller used ACPI_ALLOCATE_BUFFER, free the return buffer */
219 AcpiOsFree (ReturnBuffer->Pointer);
220 ReturnBuffer->Pointer = NULL;
223 ReturnBuffer->Length = 0;
224 return_ACPI_STATUS (AE_TYPE);
227 ACPI_EXPORT_SYMBOL (AcpiEvaluateObjectTyped)
230 /*******************************************************************************
232 * FUNCTION: AcpiEvaluateObject
234 * PARAMETERS: Handle - Object handle (optional)
235 * Pathname - Object pathname (optional)
236 * ExternalParams - List of parameters to pass to method,
237 * terminated by NULL. May be NULL
238 * if no parameters are being passed.
239 * ReturnBuffer - Where to put method's return value (if
240 * any). If NULL, no value is returned.
244 * DESCRIPTION: Find and evaluate the given object, passing the given
245 * parameters if necessary. One of "Handle" or "Pathname" must
246 * be valid (non-null)
248 ******************************************************************************/
253 ACPI_STRING Pathname,
254 ACPI_OBJECT_LIST *ExternalParams,
255 ACPI_BUFFER *ReturnBuffer)
258 ACPI_EVALUATE_INFO *Info;
259 ACPI_SIZE BufferSpaceNeeded;
263 ACPI_FUNCTION_TRACE (AcpiEvaluateObject);
266 /* Allocate and initialize the evaluation information block */
268 Info = ACPI_ALLOCATE_ZEROED (sizeof (ACPI_EVALUATE_INFO));
271 return_ACPI_STATUS (AE_NO_MEMORY);
274 Info->Pathname = Pathname;
275 Info->ParameterType = ACPI_PARAM_ARGS;
277 /* Convert and validate the device handle */
279 Info->PrefixNode = AcpiNsMapHandleToNode (Handle);
280 if (!Info->PrefixNode)
282 Status = AE_BAD_PARAMETER;
287 * If there are parameters to be passed to a control method, the external
288 * objects must all be converted to internal objects
290 if (ExternalParams && ExternalParams->Count)
293 * Allocate a new parameter block for the internal objects
294 * Add 1 to count to allow for null terminated internal list
296 Info->Parameters = ACPI_ALLOCATE_ZEROED (
297 ((ACPI_SIZE) ExternalParams->Count + 1) * sizeof (void *));
298 if (!Info->Parameters)
300 Status = AE_NO_MEMORY;
304 /* Convert each external object in the list to an internal object */
306 for (i = 0; i < ExternalParams->Count; i++)
308 Status = AcpiUtCopyEobjectToIobject (
309 &ExternalParams->Pointer[i], &Info->Parameters[i]);
310 if (ACPI_FAILURE (Status))
315 Info->Parameters[ExternalParams->Count] = NULL;
320 * 1) Fully qualified pathname
321 * 2) No handle, not fully qualified pathname (error)
325 (AcpiNsValidRootPrefix (Pathname[0])))
327 /* The path is fully qualified, just evaluate by name */
329 Info->PrefixNode = NULL;
330 Status = AcpiNsEvaluate (Info);
335 * A handle is optional iff a fully qualified pathname is specified.
336 * Since we've already handled fully qualified names above, this is
341 ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
342 "Both Handle and Pathname are NULL"));
346 ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
347 "Null Handle with relative pathname [%s]", Pathname));
350 Status = AE_BAD_PARAMETER;
354 /* We have a namespace a node and a possible relative path */
356 Status = AcpiNsEvaluate (Info);
360 * If we are expecting a return value, and all went well above,
361 * copy the return value to an external object.
365 if (!Info->ReturnObject)
367 ReturnBuffer->Length = 0;
371 if (ACPI_GET_DESCRIPTOR_TYPE (Info->ReturnObject) ==
372 ACPI_DESC_TYPE_NAMED)
375 * If we received a NS Node as a return object, this means that
376 * the object we are evaluating has nothing interesting to
377 * return (such as a mutex, etc.) We return an error because
378 * these types are essentially unsupported by this interface.
379 * We don't check up front because this makes it easier to add
380 * support for various types at a later date if necessary.
383 Info->ReturnObject = NULL; /* No need to delete a NS Node */
384 ReturnBuffer->Length = 0;
387 if (ACPI_SUCCESS (Status))
389 /* Get the size of the returned object */
391 Status = AcpiUtGetObjectSize (Info->ReturnObject,
393 if (ACPI_SUCCESS (Status))
395 /* Validate/Allocate/Clear caller buffer */
397 Status = AcpiUtInitializeBuffer (ReturnBuffer,
399 if (ACPI_FAILURE (Status))
402 * Caller's buffer is too small or a new one can't
405 ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
406 "Needed buffer size %X, %s\n",
407 (UINT32) BufferSpaceNeeded,
408 AcpiFormatException (Status)));
412 /* We have enough space for the object, build it */
414 Status = AcpiUtCopyIobjectToEobject (Info->ReturnObject,
422 if (Info->ReturnObject)
425 * Delete the internal return object. NOTE: Interpreter must be
426 * locked to avoid race condition.
428 AcpiExEnterInterpreter ();
430 /* Remove one reference on the return object (should delete it) */
432 AcpiUtRemoveReference (Info->ReturnObject);
433 AcpiExExitInterpreter ();
439 /* Free the input parameter list (if we created one) */
441 if (Info->Parameters)
443 /* Free the allocated parameter block */
445 AcpiUtDeleteInternalObjectList (Info->Parameters);
449 return_ACPI_STATUS (Status);
452 ACPI_EXPORT_SYMBOL (AcpiEvaluateObject)
455 /*******************************************************************************
457 * FUNCTION: AcpiWalkNamespace
459 * PARAMETERS: Type - ACPI_OBJECT_TYPE to search for
460 * StartObject - Handle in namespace where search begins
461 * MaxDepth - Depth to which search is to reach
462 * UserFunction - Called when an object of "Type" is found
463 * Context - Passed to user function
464 * ReturnValue - Location where return value of
465 * UserFunction is put if terminated early
467 * RETURNS Return value from the UserFunction if terminated early.
468 * Otherwise, returns NULL.
470 * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
471 * starting (and ending) at the object specified by StartHandle.
472 * The UserFunction is called whenever an object that matches
473 * the type parameter is found. If the user function returns
474 * a non-zero value, the search is terminated immediately and this
475 * value is returned to the caller.
477 * The point of this procedure is to provide a generic namespace
478 * walk routine that can be called from multiple places to
479 * provide multiple services; the User Function can be tailored
480 * to each task, whether it is a print function, a compare
483 ******************************************************************************/
487 ACPI_OBJECT_TYPE Type,
488 ACPI_HANDLE StartObject,
490 ACPI_WALK_CALLBACK UserFunction,
497 ACPI_FUNCTION_TRACE (AcpiWalkNamespace);
500 /* Parameter validation */
502 if ((Type > ACPI_TYPE_LOCAL_MAX) ||
506 return_ACPI_STATUS (AE_BAD_PARAMETER);
510 * Lock the namespace around the walk.
511 * The namespace will be unlocked/locked around each call
512 * to the user function - since this function
513 * must be allowed to make Acpi calls itself.
515 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
516 if (ACPI_FAILURE (Status))
518 return_ACPI_STATUS (Status);
521 Status = AcpiNsWalkNamespace (Type, StartObject, MaxDepth,
523 UserFunction, Context, ReturnValue);
525 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
526 return_ACPI_STATUS (Status);
529 ACPI_EXPORT_SYMBOL (AcpiWalkNamespace)
532 /*******************************************************************************
534 * FUNCTION: AcpiNsGetDeviceCallback
536 * PARAMETERS: Callback from AcpiGetDevice
540 * DESCRIPTION: Takes callbacks from WalkNamespace and filters out all non-
541 * present devices, or if they specified a HID, it filters based
544 ******************************************************************************/
547 AcpiNsGetDeviceCallback (
548 ACPI_HANDLE ObjHandle,
553 ACPI_GET_DEVICES_INFO *Info = Context;
555 ACPI_NAMESPACE_NODE *Node;
558 ACPI_COMPATIBLE_ID_LIST *Cid;
562 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
563 if (ACPI_FAILURE (Status))
568 Node = AcpiNsMapHandleToNode (ObjHandle);
569 Status = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
570 if (ACPI_FAILURE (Status))
577 return (AE_BAD_PARAMETER);
580 /* Run _STA to determine if device is present */
582 Status = AcpiUtExecute_STA (Node, &Flags);
583 if (ACPI_FAILURE (Status))
585 return (AE_CTRL_DEPTH);
588 if (!(Flags & ACPI_STA_DEVICE_PRESENT))
590 /* Don't examine children of the device if not present */
592 return (AE_CTRL_DEPTH);
595 /* Filter based on device HID & CID */
597 if (Info->Hid != NULL)
599 Status = AcpiUtExecute_HID (Node, &Hid);
600 if (Status == AE_NOT_FOUND)
604 else if (ACPI_FAILURE (Status))
606 return (AE_CTRL_DEPTH);
609 if (ACPI_STRNCMP (Hid.Value, Info->Hid, sizeof (Hid.Value)) != 0)
611 /* Get the list of Compatible IDs */
613 Status = AcpiUtExecute_CID (Node, &Cid);
614 if (Status == AE_NOT_FOUND)
618 else if (ACPI_FAILURE (Status))
620 return (AE_CTRL_DEPTH);
623 /* Walk the CID list */
625 for (i = 0; i < Cid->Count; i++)
627 if (ACPI_STRNCMP (Cid->Id[i].Value, Info->Hid,
628 sizeof (ACPI_COMPATIBLE_ID)) != 0)
638 Status = Info->UserFunction (ObjHandle, NestingLevel, Info->Context,
644 /*******************************************************************************
646 * FUNCTION: AcpiGetDevices
648 * PARAMETERS: HID - HID to search for. Can be NULL.
649 * UserFunction - Called when a matching object is found
650 * Context - Passed to user function
651 * ReturnValue - Location where return value of
652 * UserFunction is put if terminated early
654 * RETURNS Return value from the UserFunction if terminated early.
655 * Otherwise, returns NULL.
657 * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
658 * starting (and ending) at the object specified by StartHandle.
659 * The UserFunction is called whenever an object of type
660 * Device is found. If the user function returns
661 * a non-zero value, the search is terminated immediately and this
662 * value is returned to the caller.
664 * This is a wrapper for WalkNamespace, but the callback performs
665 * additional filtering. Please see AcpiGetDeviceCallback.
667 ******************************************************************************/
672 ACPI_WALK_CALLBACK UserFunction,
677 ACPI_GET_DEVICES_INFO Info;
680 ACPI_FUNCTION_TRACE (AcpiGetDevices);
683 /* Parameter validation */
687 return_ACPI_STATUS (AE_BAD_PARAMETER);
691 * We're going to call their callback from OUR callback, so we need
692 * to know what it is, and their context parameter.
695 Info.Context = Context;
696 Info.UserFunction = UserFunction;
699 * Lock the namespace around the walk.
700 * The namespace will be unlocked/locked around each call
701 * to the user function - since this function
702 * must be allowed to make Acpi calls itself.
704 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
705 if (ACPI_FAILURE (Status))
707 return_ACPI_STATUS (Status);
710 Status = AcpiNsWalkNamespace (ACPI_TYPE_DEVICE, ACPI_ROOT_OBJECT,
711 ACPI_UINT32_MAX, ACPI_NS_WALK_UNLOCK,
712 AcpiNsGetDeviceCallback, &Info, ReturnValue);
714 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
715 return_ACPI_STATUS (Status);
718 ACPI_EXPORT_SYMBOL (AcpiGetDevices)
721 /*******************************************************************************
723 * FUNCTION: AcpiAttachData
725 * PARAMETERS: ObjHandle - Namespace node
726 * Handler - Handler for this attachment
727 * Data - Pointer to data to be attached
731 * DESCRIPTION: Attach arbitrary data and handler to a namespace node.
733 ******************************************************************************/
737 ACPI_HANDLE ObjHandle,
738 ACPI_OBJECT_HANDLER Handler,
741 ACPI_NAMESPACE_NODE *Node;
745 /* Parameter validation */
751 return (AE_BAD_PARAMETER);
754 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
755 if (ACPI_FAILURE (Status))
760 /* Convert and validate the handle */
762 Node = AcpiNsMapHandleToNode (ObjHandle);
765 Status = AE_BAD_PARAMETER;
769 Status = AcpiNsAttachData (Node, Handler, Data);
772 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
776 ACPI_EXPORT_SYMBOL (AcpiAttachData)
779 /*******************************************************************************
781 * FUNCTION: AcpiDetachData
783 * PARAMETERS: ObjHandle - Namespace node handle
784 * Handler - Handler used in call to AcpiAttachData
788 * DESCRIPTION: Remove data that was previously attached to a node.
790 ******************************************************************************/
794 ACPI_HANDLE ObjHandle,
795 ACPI_OBJECT_HANDLER Handler)
797 ACPI_NAMESPACE_NODE *Node;
801 /* Parameter validation */
806 return (AE_BAD_PARAMETER);
809 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
810 if (ACPI_FAILURE (Status))
815 /* Convert and validate the handle */
817 Node = AcpiNsMapHandleToNode (ObjHandle);
820 Status = AE_BAD_PARAMETER;
824 Status = AcpiNsDetachData (Node, Handler);
827 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
831 ACPI_EXPORT_SYMBOL (AcpiDetachData)
834 /*******************************************************************************
836 * FUNCTION: AcpiGetData
838 * PARAMETERS: ObjHandle - Namespace node
839 * Handler - Handler used in call to AttachData
840 * Data - Where the data is returned
844 * DESCRIPTION: Retrieve data that was previously attached to a namespace node.
846 ******************************************************************************/
850 ACPI_HANDLE ObjHandle,
851 ACPI_OBJECT_HANDLER Handler,
854 ACPI_NAMESPACE_NODE *Node;
858 /* Parameter validation */
864 return (AE_BAD_PARAMETER);
867 Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
868 if (ACPI_FAILURE (Status))
873 /* Convert and validate the handle */
875 Node = AcpiNsMapHandleToNode (ObjHandle);
878 Status = AE_BAD_PARAMETER;
882 Status = AcpiNsGetAttachedData (Node, Handler, Data);
885 (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
889 ACPI_EXPORT_SYMBOL (AcpiGetData)