1 /*******************************************************************************
3 * Module Name: nseval - Object evaluation interfaces -- includes control
4 * method lookup and execution.
6 ******************************************************************************/
9 * Copyright (C) 2000 - 2005, R. Byron Moore
10 * All rights reserved.
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions
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.
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.
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.
46 #include <acpi/acpi.h>
47 #include <acpi/acparser.h>
48 #include <acpi/acinterp.h>
49 #include <acpi/acnamesp.h>
52 #define _COMPONENT ACPI_NAMESPACE
53 ACPI_MODULE_NAME ("nseval")
55 /* Local prototypes */
58 acpi_ns_execute_control_method (
59 struct acpi_parameter_info
*info
);
62 acpi_ns_get_object_value (
63 struct acpi_parameter_info
*info
);
66 /*******************************************************************************
68 * FUNCTION: acpi_ns_evaluate_relative
70 * PARAMETERS: Pathname - Name of method to execute, If NULL, the
71 * handle is the object to execute
72 * Info - Method info block, contains:
73 * return_object - Where to put method's return value (if
74 * any). If NULL, no value is returned.
75 * Params - List of parameters to pass to the method,
76 * terminated by NULL. Params itself may be
77 * NULL if no parameters are being passed.
81 * DESCRIPTION: Evaluate the object or find and execute the requested method
83 * MUTEX: Locks Namespace
85 ******************************************************************************/
88 acpi_ns_evaluate_relative (
90 struct acpi_parameter_info
*info
)
93 struct acpi_namespace_node
*node
= NULL
;
94 union acpi_generic_state
*scope_info
;
95 char *internal_path
= NULL
;
98 ACPI_FUNCTION_TRACE ("ns_evaluate_relative");
102 * Must have a valid object handle
104 if (!info
|| !info
->node
) {
105 return_ACPI_STATUS (AE_BAD_PARAMETER
);
108 /* Build an internal name string for the method */
110 status
= acpi_ns_internalize_name (pathname
, &internal_path
);
111 if (ACPI_FAILURE (status
)) {
112 return_ACPI_STATUS (status
);
115 scope_info
= acpi_ut_create_generic_state ();
120 /* Get the prefix handle and Node */
122 status
= acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE
);
123 if (ACPI_FAILURE (status
)) {
127 info
->node
= acpi_ns_map_handle_to_node (info
->node
);
129 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
130 status
= AE_BAD_PARAMETER
;
134 /* Lookup the name in the namespace */
136 scope_info
->scope
.node
= info
->node
;
137 status
= acpi_ns_lookup (scope_info
, internal_path
, ACPI_TYPE_ANY
,
138 ACPI_IMODE_EXECUTE
, ACPI_NS_NO_UPSEARCH
, NULL
,
141 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
143 if (ACPI_FAILURE (status
)) {
144 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
, "Object [%s] not found [%s]\n",
145 pathname
, acpi_format_exception (status
)));
150 * Now that we have a handle to the object, we can attempt to evaluate it.
152 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
, "%s [%p] Value %p\n",
153 pathname
, node
, acpi_ns_get_attached_object (node
)));
156 status
= acpi_ns_evaluate_by_handle (info
);
158 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
, "*** Completed eval of object %s ***\n",
162 acpi_ut_delete_generic_state (scope_info
);
165 ACPI_MEM_FREE (internal_path
);
166 return_ACPI_STATUS (status
);
170 /*******************************************************************************
172 * FUNCTION: acpi_ns_evaluate_by_name
174 * PARAMETERS: Pathname - Fully qualified pathname to the object
175 * Info - Method info block, contains:
176 * return_object - Where to put method's return value (if
177 * any). If NULL, no value is returned.
178 * Params - List of parameters to pass to the method,
179 * terminated by NULL. Params itself may be
180 * NULL if no parameters are being passed.
184 * DESCRIPTION: Evaluate the object or rind and execute the requested method
185 * passing the given parameters
187 * MUTEX: Locks Namespace
189 ******************************************************************************/
192 acpi_ns_evaluate_by_name (
194 struct acpi_parameter_info
*info
)
197 char *internal_path
= NULL
;
200 ACPI_FUNCTION_TRACE ("ns_evaluate_by_name");
203 /* Build an internal name string for the method */
205 status
= acpi_ns_internalize_name (pathname
, &internal_path
);
206 if (ACPI_FAILURE (status
)) {
207 return_ACPI_STATUS (status
);
210 status
= acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE
);
211 if (ACPI_FAILURE (status
)) {
215 /* Lookup the name in the namespace */
217 status
= acpi_ns_lookup (NULL
, internal_path
, ACPI_TYPE_ANY
,
218 ACPI_IMODE_EXECUTE
, ACPI_NS_NO_UPSEARCH
, NULL
,
221 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
223 if (ACPI_FAILURE (status
)) {
224 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
,
225 "Object at [%s] was not found, status=%.4X\n",
231 * Now that we have a handle to the object, we can attempt to evaluate it.
233 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
, "%s [%p] Value %p\n",
234 pathname
, info
->node
, acpi_ns_get_attached_object (info
->node
)));
236 status
= acpi_ns_evaluate_by_handle (info
);
238 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
, "*** Completed eval of object %s ***\n",
247 ACPI_MEM_FREE (internal_path
);
250 return_ACPI_STATUS (status
);
254 /*******************************************************************************
256 * FUNCTION: acpi_ns_evaluate_by_handle
258 * PARAMETERS: Info - Method info block, contains:
259 * Node - Method/Object Node to execute
260 * Parameters - List of parameters to pass to the method,
261 * terminated by NULL. Params itself may be
262 * NULL if no parameters are being passed.
263 * return_object - Where to put method's return value (if
264 * any). If NULL, no value is returned.
265 * parameter_type - Type of Parameter list
266 * return_object - Where to put method's return value (if
267 * any). If NULL, no value is returned.
271 * DESCRIPTION: Evaluate object or execute the requested method passing the
274 * MUTEX: Locks Namespace
276 ******************************************************************************/
279 acpi_ns_evaluate_by_handle (
280 struct acpi_parameter_info
*info
)
285 ACPI_FUNCTION_TRACE ("ns_evaluate_by_handle");
288 /* Check if namespace has been initialized */
290 if (!acpi_gbl_root_node
) {
291 return_ACPI_STATUS (AE_NO_NAMESPACE
);
294 /* Parameter Validation */
297 return_ACPI_STATUS (AE_BAD_PARAMETER
);
300 /* Initialize the return value to an invalid object */
302 info
->return_object
= NULL
;
304 /* Get the prefix handle and Node */
306 status
= acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE
);
307 if (ACPI_FAILURE (status
)) {
308 return_ACPI_STATUS (status
);
311 info
->node
= acpi_ns_map_handle_to_node (info
->node
);
313 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
314 return_ACPI_STATUS (AE_BAD_PARAMETER
);
318 * For a method alias, we must grab the actual method node so that proper
319 * scoping context will be established before execution.
321 if (acpi_ns_get_type (info
->node
) == ACPI_TYPE_LOCAL_METHOD_ALIAS
) {
322 info
->node
= ACPI_CAST_PTR (struct acpi_namespace_node
, info
->node
->object
);
326 * Two major cases here:
327 * 1) The object is an actual control method -- execute it.
328 * 2) The object is not a method -- just return it's current value
330 * In both cases, the namespace is unlocked by the acpi_ns* procedure
332 if (acpi_ns_get_type (info
->node
) == ACPI_TYPE_METHOD
) {
334 * Case 1) We have an actual control method to execute
336 status
= acpi_ns_execute_control_method (info
);
340 * Case 2) Object is NOT a method, just return its current value
342 status
= acpi_ns_get_object_value (info
);
346 * Check if there is a return value on the stack that must be dealt with
348 if (status
== AE_CTRL_RETURN_VALUE
) {
349 /* Map AE_CTRL_RETURN_VALUE to AE_OK, we are done with it */
355 * Namespace was unlocked by the handling acpi_ns* function, so we
358 return_ACPI_STATUS (status
);
362 /*******************************************************************************
364 * FUNCTION: acpi_ns_execute_control_method
366 * PARAMETERS: Info - Method info block, contains:
367 * Node - Method Node to execute
368 * Parameters - List of parameters to pass to the method,
369 * terminated by NULL. Params itself may be
370 * NULL if no parameters are being passed.
371 * return_object - Where to put method's return value (if
372 * any). If NULL, no value is returned.
373 * parameter_type - Type of Parameter list
374 * return_object - Where to put method's return value (if
375 * any). If NULL, no value is returned.
379 * DESCRIPTION: Execute the requested method passing the given parameters
381 * MUTEX: Assumes namespace is locked
383 ******************************************************************************/
386 acpi_ns_execute_control_method (
387 struct acpi_parameter_info
*info
)
390 union acpi_operand_object
*obj_desc
;
393 ACPI_FUNCTION_TRACE ("ns_execute_control_method");
396 /* Verify that there is a method associated with this object */
398 obj_desc
= acpi_ns_get_attached_object (info
->node
);
400 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR
, "No attached method object\n"));
402 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
403 return_ACPI_STATUS (AE_NULL_OBJECT
);
406 ACPI_DUMP_PATHNAME (info
->node
, "Execute Method:",
407 ACPI_LV_INFO
, _COMPONENT
);
409 ACPI_DEBUG_PRINT ((ACPI_DB_EXEC
, "Method at AML address %p Length %X\n",
410 obj_desc
->method
.aml_start
+ 1, obj_desc
->method
.aml_length
- 1));
413 * Unlock the namespace before execution. This allows namespace access
414 * via the external Acpi* interfaces while a method is being executed.
415 * However, any namespace deletion must acquire both the namespace and
416 * interpreter locks to ensure that no thread is using the portion of the
417 * namespace that is being deleted.
419 status
= acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
420 if (ACPI_FAILURE (status
)) {
421 return_ACPI_STATUS (status
);
425 * Execute the method via the interpreter. The interpreter is locked
426 * here before calling into the AML parser
428 status
= acpi_ex_enter_interpreter ();
429 if (ACPI_FAILURE (status
)) {
430 return_ACPI_STATUS (status
);
433 status
= acpi_psx_execute (info
);
434 acpi_ex_exit_interpreter ();
436 return_ACPI_STATUS (status
);
440 /*******************************************************************************
442 * FUNCTION: acpi_ns_get_object_value
444 * PARAMETERS: Info - Method info block, contains:
445 * Node - Object's NS node
446 * return_object - Where to put object value (if
447 * any). If NULL, no value is returned.
451 * DESCRIPTION: Return the current value of the object
453 * MUTEX: Assumes namespace is locked, leaves namespace unlocked
455 ******************************************************************************/
458 acpi_ns_get_object_value (
459 struct acpi_parameter_info
*info
)
461 acpi_status status
= AE_OK
;
462 struct acpi_namespace_node
*resolved_node
= info
->node
;
465 ACPI_FUNCTION_TRACE ("ns_get_object_value");
469 * Objects require additional resolution steps (e.g., the Node may be a
470 * field that must be read, etc.) -- we can't just grab the object out of
475 * Use resolve_node_to_value() to get the associated value. This call always
476 * deletes obj_desc (allocated above).
478 * NOTE: we can get away with passing in NULL for a walk state because
479 * obj_desc is guaranteed to not be a reference to either a method local or
480 * a method argument (because this interface can only be called from the
481 * acpi_evaluate external interface, never called from a running method.)
483 * Even though we do not directly invoke the interpreter for this, we must
484 * enter it because we could access an opregion. The opregion access code
485 * assumes that the interpreter is locked.
487 * We must release the namespace lock before entering the intepreter.
489 status
= acpi_ut_release_mutex (ACPI_MTX_NAMESPACE
);
490 if (ACPI_FAILURE (status
)) {
491 return_ACPI_STATUS (status
);
494 status
= acpi_ex_enter_interpreter ();
495 if (ACPI_SUCCESS (status
)) {
496 status
= acpi_ex_resolve_node_to_value (&resolved_node
, NULL
);
498 * If acpi_ex_resolve_node_to_value() succeeded, the return value was placed
501 acpi_ex_exit_interpreter ();
503 if (ACPI_SUCCESS (status
)) {
504 status
= AE_CTRL_RETURN_VALUE
;
505 info
->return_object
= ACPI_CAST_PTR
506 (union acpi_operand_object
, resolved_node
);
507 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES
, "Returning object %p [%s]\n",
509 acpi_ut_get_object_type_name (info
->return_object
)));
513 /* Namespace is unlocked */
515 return_ACPI_STATUS (status
);