linux/drivers/acpi/acpica/dsutils.c

// SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0
/*******************************************************************************
 *
 * Module Name: dsutils - Dispatcher utilities
 *
 ******************************************************************************/

#include <acpi/acpi.h>
#include "accommon.h"
#include "acparser.h"
#include "amlcode.h"
#include "acdispat.h"
#include "acinterp.h"
#include "acnamesp.h"
#include "acdebug.h"

#define _COMPONENT …
ACPI_MODULE_NAME("dsutils")

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_clear_implicit_return
 *
 * PARAMETERS:  walk_state          - Current State
 *
 * RETURN:      None.
 *
 * DESCRIPTION: Clear and remove a reference on an implicit return value. Used
 *              to delete "stale" return values (if enabled, the return value
 *              from every operator is saved at least momentarily, in case the
 *              parent method exits.)
 *
 ******************************************************************************/
void acpi_ds_clear_implicit_return(struct acpi_walk_state *walk_state)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_do_implicit_return
 *
 * PARAMETERS:  return_desc         - The return value
 *              walk_state          - Current State
 *              add_reference       - True if a reference should be added to the
 *                                    return object
 *
 * RETURN:      TRUE if implicit return enabled, FALSE otherwise
 *
 * DESCRIPTION: Implements the optional "implicit return".  We save the result
 *              of every ASL operator and control method invocation in case the
 *              parent method exit. Before storing a new return value, we
 *              delete the previous return value.
 *
 ******************************************************************************/

u8
acpi_ds_do_implicit_return(union acpi_operand_object *return_desc,
			   struct acpi_walk_state *walk_state, u8 add_reference)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_is_result_used
 *
 * PARAMETERS:  op                  - Current Op
 *              walk_state          - Current State
 *
 * RETURN:      TRUE if result is used, FALSE otherwise
 *
 * DESCRIPTION: Check if a result object will be used by the parent
 *
 ******************************************************************************/

u8
acpi_ds_is_result_used(union acpi_parse_object * op,
		       struct acpi_walk_state * walk_state)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_delete_result_if_not_used
 *
 * PARAMETERS:  op              - Current parse Op
 *              result_obj      - Result of the operation
 *              walk_state      - Current state
 *
 * RETURN:      Status
 *
 * DESCRIPTION: Used after interpretation of an opcode. If there is an internal
 *              result descriptor, check if the parent opcode will actually use
 *              this result. If not, delete the result now so that it will
 *              not become orphaned.
 *
 ******************************************************************************/

void
acpi_ds_delete_result_if_not_used(union acpi_parse_object *op,
				  union acpi_operand_object *result_obj,
				  struct acpi_walk_state *walk_state)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_resolve_operands
 *
 * PARAMETERS:  walk_state          - Current walk state with operands on stack
 *
 * RETURN:      Status
 *
 * DESCRIPTION: Resolve all operands to their values. Used to prepare
 *              arguments to a control method invocation (a call from one
 *              method to another.)
 *
 ******************************************************************************/

acpi_status acpi_ds_resolve_operands(struct acpi_walk_state *walk_state)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_clear_operands
 *
 * PARAMETERS:  walk_state          - Current walk state with operands on stack
 *
 * RETURN:      None
 *
 * DESCRIPTION: Clear all operands on the current walk state operand stack.
 *
 ******************************************************************************/

void acpi_ds_clear_operands(struct acpi_walk_state *walk_state)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_create_operand
 *
 * PARAMETERS:  walk_state      - Current walk state
 *              arg             - Parse object for the argument
 *              arg_index       - Which argument (zero based)
 *
 * RETURN:      Status
 *
 * DESCRIPTION: Translate a parse tree object that is an argument to an AML
 *              opcode to the equivalent interpreter object. This may include
 *              looking up a name or entering a new name into the internal
 *              namespace.
 *
 ******************************************************************************/

acpi_status
acpi_ds_create_operand(struct acpi_walk_state *walk_state,
		       union acpi_parse_object *arg, u32 arg_index)
{ … }

/*******************************************************************************
 *
 * FUNCTION:    acpi_ds_create_operands
 *
 * PARAMETERS:  walk_state          - Current state
 *              first_arg           - First argument of a parser argument tree
 *
 * RETURN:      Status
 *
 * DESCRIPTION: Convert an operator's arguments from a parse tree format to
 *              namespace objects and place those argument object on the object
 *              stack in preparation for evaluation by the interpreter.
 *
 ******************************************************************************/

acpi_status
acpi_ds_create_operands(struct acpi_walk_state *walk_state,
			union acpi_parse_object *first_arg)
{ … }

/*****************************************************************************
 *
 * FUNCTION:    acpi_ds_evaluate_name_path
 *
 * PARAMETERS:  walk_state      - Current state of the parse tree walk,
 *                                the opcode of current operation should be
 *                                AML_INT_NAMEPATH_OP
 *
 * RETURN:      Status
 *
 * DESCRIPTION: Translate the -name_path- parse tree object to the equivalent
 *              interpreter object, convert it to value, if needed, duplicate
 *              it, if needed, and push it onto the current result stack.
 *
 ****************************************************************************/

acpi_status acpi_ds_evaluate_name_path(struct acpi_walk_state *walk_state)
{ … }