| blob | 8d1b754005158ff0d90329c80e908bebd473a142 |
1 // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0
2 /*******************************************************************************
3 *
4 * Module Name: dsutils - Dispatcher utilities
5 *
6 ******************************************************************************/
8 #include <acpi/acpi.h>
17 #define _COMPONENT ACPI_DISPATCHER
20 /*******************************************************************************
21 *
22 * FUNCTION: acpi_ds_clear_implicit_return
23 *
24 * PARAMETERS: walk_state - Current State
25 *
26 * RETURN: None.
27 *
28 * DESCRIPTION: Clear and remove a reference on an implicit return value. Used
29 * to delete "stale" return values (if enabled, the return value
30 * from every operator is saved at least momentarily, in case the
31 * parent method exits.)
32 *
33 ******************************************************************************/
35 {
38 /*
39 * Slack must be enabled for this feature
40 */
43 }
46 /*
47 * Delete any "stale" implicit return. However, in
48 * complex statements, the implicit return value can be
49 * bubbled up several levels.
50 */
57 }
58 }
60 #ifndef ACPI_NO_METHOD_EXECUTION
61 /*******************************************************************************
62 *
63 * FUNCTION: acpi_ds_do_implicit_return
64 *
65 * PARAMETERS: return_desc - The return value
66 * walk_state - Current State
67 * add_reference - True if a reference should be added to the
68 * return object
69 *
70 * RETURN: TRUE if implicit return enabled, FALSE otherwise
71 *
72 * DESCRIPTION: Implements the optional "implicit return". We save the result
73 * of every ASL operator and control method invocation in case the
74 * parent method exit. Before storing a new return value, we
75 * delete the previous return value.
76 *
77 ******************************************************************************/
79 u8
82 {
85 /*
86 * Slack must be enabled for this feature, and we must
87 * have a valid return object
88 */
91 }
97 /*
98 * Delete any "stale" implicit return value first. However, in
99 * complex statements, the implicit return value can be
100 * bubbled up several levels, so we don't clear the value if it
101 * is the same as the return_desc.
102 */
106 }
108 }
110 /* Save the implicit return value, add a reference if requested */
115 }
118 }
120 /*******************************************************************************
121 *
122 * FUNCTION: acpi_ds_is_result_used
123 *
124 * PARAMETERS: op - Current Op
125 * walk_state - Current State
126 *
127 * RETURN: TRUE if result is used, FALSE otherwise
128 *
129 * DESCRIPTION: Check if a result object will be used by the parent
130 *
131 ******************************************************************************/
133 u8
136 {
141 /* Must have both an Op and a Result Object */
146 }
148 /*
149 * We know that this operator is not a
150 * Return() operator (would not come here.) The following code is the
151 * optional support for a so-called "implicit return". Some AML code
152 * assumes that the last value of the method is "implicitly" returned
153 * to the caller. Just save the last result as the return value.
154 * NOTE: this is optional because the ASL language does not actually
155 * support this behavior.
156 */
158 TRUE);
160 /*
161 * Now determine if the parent will use the result
162 *
163 * If there is no parent, or the parent is a scope_op, we are executing
164 * at the method level. An executing method typically has no parent,
165 * since each method is parsed separately. A method invoked externally
166 * via execute_control_method has a scope_op as the parent.
167 */
171 /* No parent, the return value cannot possibly be used */
176 aml_opcode)));
178 }
180 /* Get info on the parent. The root_op is AML_SCOPE */
182 parent_info =
187 }
189 /*
190 * Decide what to do with the result based on the parent. If
191 * the parent opcode will not use the result, delete the object.
192 * Otherwise leave it as is, it will be deleted when it is used
193 * as an operand later.
194 */
201 /* Never delete the return value associated with a return opcode */
207 /*
208 * If we are executing the predicate AND this is the predicate op,
209 * we will use the return value
210 */
212 ACPI_CONTROL_PREDICATE_EXECUTING) &&
214 op)) {
216 }
221 /* Ignore other control opcodes */
224 }
226 /* The general control opcode returns no result */
231 /*
232 * These opcodes allow term_arg(s) as operands and therefore
233 * the operands can be method calls. The result is used.
234 */
244 AML_VARIABLE_PACKAGE_OP)
246 AML_INT_EVAL_SUBTREE_OP)
248 AML_BANK_FIELD_OP)) {
249 /*
250 * These opcodes allow term_arg(s) as operands and therefore
251 * the operands can be method calls. The result is used.
252 */
254 }
259 /*
260 * In all other cases. the parent will actually use the return
261 * object, so keep it.
262 */
264 }
266 result_used:
275 result_not_used:
283 }
285 /*******************************************************************************
286 *
287 * FUNCTION: acpi_ds_delete_result_if_not_used
288 *
289 * PARAMETERS: op - Current parse Op
290 * result_obj - Result of the operation
291 * walk_state - Current state
292 *
293 * RETURN: Status
294 *
295 * DESCRIPTION: Used after interpretation of an opcode. If there is an internal
296 * result descriptor, check if the parent opcode will actually use
297 * this result. If not, delete the result now so that it will
298 * not become orphaned.
299 *
300 ******************************************************************************/
302 void
306 {
308 acpi_status status;
314 return_VOID;
315 }
318 return_VOID;
319 }
323 /* Must pop the result stack (obj_desc should be equal to result_obj) */
328 }
329 }
331 return_VOID;
332 }
334 /*******************************************************************************
335 *
336 * FUNCTION: acpi_ds_resolve_operands
337 *
338 * PARAMETERS: walk_state - Current walk state with operands on stack
339 *
340 * RETURN: Status
341 *
342 * DESCRIPTION: Resolve all operands to their values. Used to prepare
343 * arguments to a control method invocation (a call from one
344 * method to another.)
345 *
346 ******************************************************************************/
349 {
350 u32 i;
355 /*
356 * Attempt to resolve each of the valid operands
357 * Method arguments are passed by reference, not by value. This means
358 * that the actual objects are passed, not copies of the objects.
359 */
361 status =
363 walk_state);
366 }
367 }
370 }
372 /*******************************************************************************
373 *
374 * FUNCTION: acpi_ds_clear_operands
375 *
376 * PARAMETERS: walk_state - Current walk state with operands on stack
377 *
378 * RETURN: None
379 *
380 * DESCRIPTION: Clear all operands on the current walk state operand stack.
381 *
382 ******************************************************************************/
385 {
386 u32 i;
390 /* Remove a reference on each operand on the stack */
393 /*
394 * Remove a reference to all operands, including both
395 * "Arguments" and "Targets".
396 */
399 }
402 return_VOID;
403 }
404 #endif
406 /*******************************************************************************
407 *
408 * FUNCTION: acpi_ds_create_operand
409 *
410 * PARAMETERS: walk_state - Current walk state
411 * arg - Parse object for the argument
412 * arg_index - Which argument (zero based)
413 *
414 * RETURN: Status
415 *
416 * DESCRIPTION: Translate a parse tree object that is an argument to an AML
417 * opcode to the equivalent interpreter object. This may include
418 * looking up a name or entering a new name into the internal
419 * namespace.
420 *
421 ******************************************************************************/
423 acpi_status
426 {
429 u32 name_length;
432 u16 opcode;
433 acpi_interpreter_mode interpreter_mode;
438 /* A valid name must be looked up in the namespace */
444 arg));
446 /* Get the entire name string from the AML stream */
454 }
456 /* All prefixes have been handled, and the name is in name_string */
458 /*
459 * Special handling for buffer_field declarations. This is a deferred
460 * opcode that unfortunately defines the field name as the last
461 * parameter instead of the first. We get here when we are performing
462 * the deferred execution, so the actual name of the field is already
463 * in the namespace. We don't want to attempt to look it up again
464 * because we may be executing in a different scope than where the
465 * actual opcode exists.
466 */
471 obj_desc =
477 /*
478 * Differentiate between a namespace "create" operation
479 * versus a "lookup" operation (IMODE_LOAD_PASS2 vs.
480 * IMODE_EXECUTE) in order to support the creation of
481 * namespace objects during the execution of control methods.
482 */
484 op_info =
486 aml_opcode);
490 AML_INT_METHODCALL_OP)
493 AML_INT_NAMEPATH_OP)) {
495 /* Enter name into namespace if not found */
499 /* Return a failure if name not found */
502 }
504 status =
507 ACPI_NS_SEARCH_PARENT |
510 acpi_namespace_node,
512 /*
513 * The only case where we pass through (ignore) a NOT_FOUND
514 * error is for the cond_ref_of opcode.
515 */
518 AML_CONDITIONAL_REF_OF_OP) {
519 /*
520 * For the Conditional Reference op, it's OK if
521 * the name is not found; We just need a way to
522 * indicate this to the interpreter, set the
523 * object to the root
524 */
525 obj_desc =
527 acpi_operand_object,
528 acpi_gbl_root_node);
531 AML_EXTERNAL_OP) {
532 /*
533 * This opcode should never appear here. It is used only
534 * by AML disassemblers and is surrounded by an If(0)
535 * by the ASL compiler.
536 *
537 * Therefore, if we see it here, it is a serious error.
538 */
541 /*
542 * We just plain didn't find it -- which is a
543 * very serious error at this point
544 */
546 }
547 }
552 }
553 }
555 /* Free the namestring created above */
559 /* Check status from the lookup */
563 }
565 /* Put the resulting object onto the current object stack */
570 }
574 /* Check for null name case */
578 /*
579 * If the name is null, this means that this is an
580 * optional result parameter that was not specified
581 * in the original ASL. Create a Zero Constant for a
582 * placeholder. (Store to a constant is a Noop.)
583 */
590 }
592 /* Get the object type of the argument */
597 }
601 /*
602 * Use value that was already previously returned
603 * by the evaluation of this argument
604 */
607 /*
608 * Only error is underflow, and this indicates
609 * a missing or null operand!
610 */
614 }
616 /* Create an ACPI_INTERNAL_OBJECT for the argument */
618 obj_desc =
620 object_type);
623 }
625 /* Initialize the new object */
627 status =
633 }
634 }
636 /* Put the operand object on the object stack */
641 }
644 }
647 }
649 /*******************************************************************************
650 *
651 * FUNCTION: acpi_ds_create_operands
652 *
653 * PARAMETERS: walk_state - Current state
654 * first_arg - First argument of a parser argument tree
655 *
656 * RETURN: Status
657 *
658 * DESCRIPTION: Convert an operator's arguments from a parse tree format to
659 * namespace objects and place those argument object on the object
660 * stack in preparation for evaluation by the interpreter.
661 *
662 ******************************************************************************/
664 acpi_status
667 {
673 u32 i;
677 /* Get all arguments in the list */
683 }
688 /* Move on to next argument, if any */
691 arg_count++;
692 index++;
693 }
699 /* Create the interpreter arguments, in reverse order */
701 index--;
709 }
714 index--;
715 }
719 cleanup:
720 /*
721 * We must undo everything done above; meaning that we must
722 * pop everything off of the operand stack and delete those
723 * objects
724 */
729 }
731 /*****************************************************************************
732 *
733 * FUNCTION: acpi_ds_evaluate_name_path
734 *
735 * PARAMETERS: walk_state - Current state of the parse tree walk,
736 * the opcode of current operation should be
737 * AML_INT_NAMEPATH_OP
738 *
739 * RETURN: Status
740 *
741 * DESCRIPTION: Translate the -name_path- parse tree object to the equivalent
742 * interpreter object, convert it to value, if needed, duplicate
743 * it, if needed, and push it onto the current result stack.
744 *
745 ****************************************************************************/
748 {
753 u8 type;
759 /* This happens after certain exception processing */
762 }
768 /* TBD: Should we specify this feature as a bit of op_info->Flags of these opcodes? */
771 }
776 }
781 }
788 }
792 /* It was incremented by acpi_ex_resolve_to_value */
796 status =
798 walk_state);
801 }
803 /*
804 * The object either was anew created or is
805 * a Namespace node - don't decrement it.
806 */
808 }
810 /* Cleanup for name-path operand */
816 }
818 push_result:
825 /* Force to take it from stack */
828 }
830 exit:
833 }