1 /*******************************************************************************
3 * Module Name: dsutils - Dispatcher utilities
5 ******************************************************************************/
8 * Copyright (C) 2000 - 2006, R. Byron Moore
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions, and the following disclaimer,
16 * without modification.
17 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
18 * substantially similar to the "NO WARRANTY" disclaimer below
19 * ("Disclaimer") and any redistribution must be conditioned upon
20 * including a substantially similar Disclaimer requirement for further
21 * binary redistribution.
22 * 3. Neither the names of the above-listed copyright holders nor the names
23 * of any contributors may be used to endorse or promote products derived
24 * from this software without specific prior written permission.
26 * Alternatively, this software may be distributed under the terms of the
27 * GNU General Public License ("GPL") version 2 as published by the Free
28 * Software Foundation.
31 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
34 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
37 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
38 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
40 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
41 * POSSIBILITY OF SUCH DAMAGES.
44 #include <acpi/acpi.h>
45 #include <acpi/acparser.h>
46 #include <acpi/amlcode.h>
47 #include <acpi/acdispat.h>
48 #include <acpi/acinterp.h>
49 #include <acpi/acnamesp.h>
50 #include <acpi/acdebug.h>
52 #define _COMPONENT ACPI_DISPATCHER
53 ACPI_MODULE_NAME("dsutils")
55 /*******************************************************************************
57 * FUNCTION: acpi_ds_clear_implicit_return
59 * PARAMETERS: walk_state - Current State
63 * DESCRIPTION: Clear and remove a reference on an implicit return value. Used
64 * to delete "stale" return values (if enabled, the return value
65 * from every operator is saved at least momentarily, in case the
66 * parent method exits.)
68 ******************************************************************************/
69 void acpi_ds_clear_implicit_return(struct acpi_walk_state *walk_state)
71 ACPI_FUNCTION_NAME("ds_clear_implicit_return");
74 * Slack must be enabled for this feature
76 if (!acpi_gbl_enable_interpreter_slack) {
80 if (walk_state->implicit_return_obj) {
82 * Delete any "stale" implicit return. However, in
83 * complex statements, the implicit return value can be
84 * bubbled up several levels.
86 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
87 "Removing reference on stale implicit return obj %p\n",
88 walk_state->implicit_return_obj));
90 acpi_ut_remove_reference(walk_state->implicit_return_obj);
91 walk_state->implicit_return_obj = NULL;
95 #ifndef ACPI_NO_METHOD_EXECUTION
96 /*******************************************************************************
98 * FUNCTION: acpi_ds_do_implicit_return
100 * PARAMETERS: return_desc - The return value
101 * walk_state - Current State
102 * add_reference - True if a reference should be added to the
105 * RETURN: TRUE if implicit return enabled, FALSE otherwise
107 * DESCRIPTION: Implements the optional "implicit return". We save the result
108 * of every ASL operator and control method invocation in case the
109 * parent method exit. Before storing a new return value, we
110 * delete the previous return value.
112 ******************************************************************************/
115 acpi_ds_do_implicit_return(union acpi_operand_object *return_desc,
116 struct acpi_walk_state *walk_state, u8 add_reference)
118 ACPI_FUNCTION_NAME("ds_do_implicit_return");
121 * Slack must be enabled for this feature, and we must
122 * have a valid return object
124 if ((!acpi_gbl_enable_interpreter_slack) || (!return_desc)) {
128 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
129 "Result %p will be implicitly returned; Prev=%p\n",
130 return_desc, walk_state->implicit_return_obj));
133 * Delete any "stale" implicit return value first. However, in
134 * complex statements, the implicit return value can be
135 * bubbled up several levels, so we don't clear the value if it
136 * is the same as the return_desc.
138 if (walk_state->implicit_return_obj) {
139 if (walk_state->implicit_return_obj == return_desc) {
142 acpi_ds_clear_implicit_return(walk_state);
145 /* Save the implicit return value, add a reference if requested */
147 walk_state->implicit_return_obj = return_desc;
149 acpi_ut_add_reference(return_desc);
155 /*******************************************************************************
157 * FUNCTION: acpi_ds_is_result_used
159 * PARAMETERS: Op - Current Op
160 * walk_state - Current State
162 * RETURN: TRUE if result is used, FALSE otherwise
164 * DESCRIPTION: Check if a result object will be used by the parent
166 ******************************************************************************/
169 acpi_ds_is_result_used(union acpi_parse_object * op,
170 struct acpi_walk_state * walk_state)
172 const struct acpi_opcode_info *parent_info;
174 ACPI_FUNCTION_TRACE_PTR("ds_is_result_used", op);
176 /* Must have both an Op and a Result Object */
179 ACPI_ERROR((AE_INFO, "Null Op"));
184 * We know that this operator is not a
185 * Return() operator (would not come here.) The following code is the
186 * optional support for a so-called "implicit return". Some AML code
187 * assumes that the last value of the method is "implicitly" returned
188 * to the caller. Just save the last result as the return value.
189 * NOTE: this is optional because the ASL language does not actually
190 * support this behavior.
192 (void)acpi_ds_do_implicit_return(walk_state->result_obj, walk_state,
196 * Now determine if the parent will use the result
198 * If there is no parent, or the parent is a scope_op, we are executing
199 * at the method level. An executing method typically has no parent,
200 * since each method is parsed separately. A method invoked externally
201 * via execute_control_method has a scope_op as the parent.
203 if ((!op->common.parent) ||
204 (op->common.parent->common.aml_opcode == AML_SCOPE_OP)) {
205 /* No parent, the return value cannot possibly be used */
207 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
208 "At Method level, result of [%s] not used\n",
209 acpi_ps_get_opcode_name(op->common.
214 /* Get info on the parent. The root_op is AML_SCOPE */
217 acpi_ps_get_opcode_info(op->common.parent->common.aml_opcode);
218 if (parent_info->class == AML_CLASS_UNKNOWN) {
219 ACPI_ERROR((AE_INFO, "Unknown parent opcode Op=%p", op));
224 * Decide what to do with the result based on the parent. If
225 * the parent opcode will not use the result, delete the object.
226 * Otherwise leave it as is, it will be deleted when it is used
227 * as an operand later.
229 switch (parent_info->class) {
230 case AML_CLASS_CONTROL:
232 switch (op->common.parent->common.aml_opcode) {
235 /* Never delete the return value associated with a return opcode */
243 * If we are executing the predicate AND this is the predicate op,
244 * we will use the return value
246 if ((walk_state->control_state->common.state ==
247 ACPI_CONTROL_PREDICATE_EXECUTING)
248 && (walk_state->control_state->control.
249 predicate_op == op)) {
255 /* Ignore other control opcodes */
259 /* The general control opcode returns no result */
261 goto result_not_used;
263 case AML_CLASS_CREATE:
266 * These opcodes allow term_arg(s) as operands and therefore
267 * the operands can be method calls. The result is used.
271 case AML_CLASS_NAMED_OBJECT:
273 if ((op->common.parent->common.aml_opcode == AML_REGION_OP) ||
274 (op->common.parent->common.aml_opcode == AML_DATA_REGION_OP)
275 || (op->common.parent->common.aml_opcode == AML_PACKAGE_OP)
276 || (op->common.parent->common.aml_opcode ==
278 || (op->common.parent->common.aml_opcode == AML_BUFFER_OP)
279 || (op->common.parent->common.aml_opcode ==
280 AML_INT_EVAL_SUBTREE_OP)) {
282 * These opcodes allow term_arg(s) as operands and therefore
283 * the operands can be method calls. The result is used.
288 goto result_not_used;
293 * In all other cases. the parent will actually use the return
294 * object, so keep it.
300 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
301 "Result of [%s] used by Parent [%s] Op=%p\n",
302 acpi_ps_get_opcode_name(op->common.aml_opcode),
303 acpi_ps_get_opcode_name(op->common.parent->common.
309 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
310 "Result of [%s] not used by Parent [%s] Op=%p\n",
311 acpi_ps_get_opcode_name(op->common.aml_opcode),
312 acpi_ps_get_opcode_name(op->common.parent->common.
318 /*******************************************************************************
320 * FUNCTION: acpi_ds_delete_result_if_not_used
322 * PARAMETERS: Op - Current parse Op
323 * result_obj - Result of the operation
324 * walk_state - Current state
328 * DESCRIPTION: Used after interpretation of an opcode. If there is an internal
329 * result descriptor, check if the parent opcode will actually use
330 * this result. If not, delete the result now so that it will
331 * not become orphaned.
333 ******************************************************************************/
336 acpi_ds_delete_result_if_not_used(union acpi_parse_object *op,
337 union acpi_operand_object *result_obj,
338 struct acpi_walk_state *walk_state)
340 union acpi_operand_object *obj_desc;
343 ACPI_FUNCTION_TRACE_PTR("ds_delete_result_if_not_used", result_obj);
346 ACPI_ERROR((AE_INFO, "Null Op"));
354 if (!acpi_ds_is_result_used(op, walk_state)) {
355 /* Must pop the result stack (obj_desc should be equal to result_obj) */
357 status = acpi_ds_result_pop(&obj_desc, walk_state);
358 if (ACPI_SUCCESS(status)) {
359 acpi_ut_remove_reference(result_obj);
366 /*******************************************************************************
368 * FUNCTION: acpi_ds_resolve_operands
370 * PARAMETERS: walk_state - Current walk state with operands on stack
374 * DESCRIPTION: Resolve all operands to their values. Used to prepare
375 * arguments to a control method invocation (a call from one
376 * method to another.)
378 ******************************************************************************/
380 acpi_status acpi_ds_resolve_operands(struct acpi_walk_state *walk_state)
383 acpi_status status = AE_OK;
385 ACPI_FUNCTION_TRACE_PTR("ds_resolve_operands", walk_state);
388 * Attempt to resolve each of the valid operands
389 * Method arguments are passed by reference, not by value. This means
390 * that the actual objects are passed, not copies of the objects.
392 for (i = 0; i < walk_state->num_operands; i++) {
394 acpi_ex_resolve_to_value(&walk_state->operands[i],
396 if (ACPI_FAILURE(status)) {
401 return_ACPI_STATUS(status);
404 /*******************************************************************************
406 * FUNCTION: acpi_ds_clear_operands
408 * PARAMETERS: walk_state - Current walk state with operands on stack
412 * DESCRIPTION: Clear all operands on the current walk state operand stack.
414 ******************************************************************************/
416 void acpi_ds_clear_operands(struct acpi_walk_state *walk_state)
420 ACPI_FUNCTION_TRACE_PTR("ds_clear_operands", walk_state);
422 /* Remove a reference on each operand on the stack */
424 for (i = 0; i < walk_state->num_operands; i++) {
426 * Remove a reference to all operands, including both
427 * "Arguments" and "Targets".
429 acpi_ut_remove_reference(walk_state->operands[i]);
430 walk_state->operands[i] = NULL;
433 walk_state->num_operands = 0;
438 /*******************************************************************************
440 * FUNCTION: acpi_ds_create_operand
442 * PARAMETERS: walk_state - Current walk state
443 * Arg - Parse object for the argument
444 * arg_index - Which argument (zero based)
448 * DESCRIPTION: Translate a parse tree object that is an argument to an AML
449 * opcode to the equivalent interpreter object. This may include
450 * looking up a name or entering a new name into the internal
453 ******************************************************************************/
456 acpi_ds_create_operand(struct acpi_walk_state *walk_state,
457 union acpi_parse_object *arg, u32 arg_index)
459 acpi_status status = AE_OK;
462 union acpi_operand_object *obj_desc;
463 union acpi_parse_object *parent_op;
465 acpi_interpreter_mode interpreter_mode;
466 const struct acpi_opcode_info *op_info;
468 ACPI_FUNCTION_TRACE_PTR("ds_create_operand", arg);
470 /* A valid name must be looked up in the namespace */
472 if ((arg->common.aml_opcode == AML_INT_NAMEPATH_OP) &&
473 (arg->common.value.string)) {
474 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH, "Getting a name: Arg=%p\n",
477 /* Get the entire name string from the AML stream */
480 acpi_ex_get_name_string(ACPI_TYPE_ANY,
481 arg->common.value.buffer,
482 &name_string, &name_length);
484 if (ACPI_FAILURE(status)) {
485 return_ACPI_STATUS(status);
488 /* All prefixes have been handled, and the name is in name_string */
491 * Special handling for buffer_field declarations. This is a deferred
492 * opcode that unfortunately defines the field name as the last
493 * parameter instead of the first. We get here when we are performing
494 * the deferred execution, so the actual name of the field is already
495 * in the namespace. We don't want to attempt to look it up again
496 * because we may be executing in a different scope than where the
497 * actual opcode exists.
499 if ((walk_state->deferred_node) &&
500 (walk_state->deferred_node->type == ACPI_TYPE_BUFFER_FIELD)
501 && (arg_index != 0)) {
503 ACPI_CAST_PTR(union acpi_operand_object,
504 walk_state->deferred_node);
506 } else { /* All other opcodes */
509 * Differentiate between a namespace "create" operation
510 * versus a "lookup" operation (IMODE_LOAD_PASS2 vs.
511 * IMODE_EXECUTE) in order to support the creation of
512 * namespace objects during the execution of control methods.
514 parent_op = arg->common.parent;
516 acpi_ps_get_opcode_info(parent_op->common.
518 if ((op_info->flags & AML_NSNODE)
519 && (parent_op->common.aml_opcode !=
520 AML_INT_METHODCALL_OP)
521 && (parent_op->common.aml_opcode != AML_REGION_OP)
522 && (parent_op->common.aml_opcode !=
523 AML_INT_NAMEPATH_OP)) {
524 /* Enter name into namespace if not found */
526 interpreter_mode = ACPI_IMODE_LOAD_PASS2;
528 /* Return a failure if name not found */
530 interpreter_mode = ACPI_IMODE_EXECUTE;
534 acpi_ns_lookup(walk_state->scope_info, name_string,
535 ACPI_TYPE_ANY, interpreter_mode,
536 ACPI_NS_SEARCH_PARENT |
537 ACPI_NS_DONT_OPEN_SCOPE, walk_state,
538 ACPI_CAST_INDIRECT_PTR(struct
542 * The only case where we pass through (ignore) a NOT_FOUND
543 * error is for the cond_ref_of opcode.
545 if (status == AE_NOT_FOUND) {
546 if (parent_op->common.aml_opcode ==
547 AML_COND_REF_OF_OP) {
549 * For the Conditional Reference op, it's OK if
550 * the name is not found; We just need a way to
551 * indicate this to the interpreter, set the
561 * We just plain didn't find it -- which is a
562 * very serious error at this point
564 status = AE_AML_NAME_NOT_FOUND;
568 if (ACPI_FAILURE(status)) {
569 ACPI_ERROR_NAMESPACE(name_string, status);
573 /* Free the namestring created above */
575 ACPI_MEM_FREE(name_string);
577 /* Check status from the lookup */
579 if (ACPI_FAILURE(status)) {
580 return_ACPI_STATUS(status);
583 /* Put the resulting object onto the current object stack */
585 status = acpi_ds_obj_stack_push(obj_desc, walk_state);
586 if (ACPI_FAILURE(status)) {
587 return_ACPI_STATUS(status);
589 ACPI_DEBUGGER_EXEC(acpi_db_display_argument_object
590 (obj_desc, walk_state));
592 /* Check for null name case */
594 if (arg->common.aml_opcode == AML_INT_NAMEPATH_OP) {
596 * If the name is null, this means that this is an
597 * optional result parameter that was not specified
598 * in the original ASL. Create a Zero Constant for a
599 * placeholder. (Store to a constant is a Noop.)
601 opcode = AML_ZERO_OP; /* Has no arguments! */
603 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
604 "Null namepath: Arg=%p\n", arg));
606 opcode = arg->common.aml_opcode;
609 /* Get the object type of the argument */
611 op_info = acpi_ps_get_opcode_info(opcode);
612 if (op_info->object_type == ACPI_TYPE_INVALID) {
613 return_ACPI_STATUS(AE_NOT_IMPLEMENTED);
616 if (op_info->flags & AML_HAS_RETVAL) {
617 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
618 "Argument previously created, already stacked\n"));
620 ACPI_DEBUGGER_EXEC(acpi_db_display_argument_object
622 operands[walk_state->num_operands -
626 * Use value that was already previously returned
627 * by the evaluation of this argument
630 acpi_ds_result_pop_from_bottom(&obj_desc,
632 if (ACPI_FAILURE(status)) {
634 * Only error is underflow, and this indicates
635 * a missing or null operand!
637 ACPI_EXCEPTION((AE_INFO, status,
638 "Missing or null operand"));
639 return_ACPI_STATUS(status);
642 /* Create an ACPI_INTERNAL_OBJECT for the argument */
645 acpi_ut_create_internal_object(op_info->
648 return_ACPI_STATUS(AE_NO_MEMORY);
651 /* Initialize the new object */
654 acpi_ds_init_object_from_op(walk_state, arg, opcode,
656 if (ACPI_FAILURE(status)) {
657 acpi_ut_delete_object_desc(obj_desc);
658 return_ACPI_STATUS(status);
662 /* Put the operand object on the object stack */
664 status = acpi_ds_obj_stack_push(obj_desc, walk_state);
665 if (ACPI_FAILURE(status)) {
666 return_ACPI_STATUS(status);
669 ACPI_DEBUGGER_EXEC(acpi_db_display_argument_object
670 (obj_desc, walk_state));
673 return_ACPI_STATUS(AE_OK);
676 /*******************************************************************************
678 * FUNCTION: acpi_ds_create_operands
680 * PARAMETERS: walk_state - Current state
681 * first_arg - First argument of a parser argument tree
685 * DESCRIPTION: Convert an operator's arguments from a parse tree format to
686 * namespace objects and place those argument object on the object
687 * stack in preparation for evaluation by the interpreter.
689 ******************************************************************************/
692 acpi_ds_create_operands(struct acpi_walk_state *walk_state,
693 union acpi_parse_object *first_arg)
695 acpi_status status = AE_OK;
696 union acpi_parse_object *arg;
699 ACPI_FUNCTION_TRACE_PTR("ds_create_operands", first_arg);
701 /* For all arguments in the list... */
705 status = acpi_ds_create_operand(walk_state, arg, arg_count);
706 if (ACPI_FAILURE(status)) {
710 ACPI_DEBUG_PRINT((ACPI_DB_DISPATCH,
711 "Arg #%d (%p) done, Arg1=%p\n", arg_count,
714 /* Move on to next argument, if any */
716 arg = arg->common.next;
720 return_ACPI_STATUS(status);
724 * We must undo everything done above; meaning that we must
725 * pop everything off of the operand stack and delete those
728 (void)acpi_ds_obj_stack_pop_and_delete(arg_count, walk_state);
730 ACPI_EXCEPTION((AE_INFO, status, "While creating Arg %d",
732 return_ACPI_STATUS(status);