AML_EVALNODE(9) | Kernel Developer's Manual | AML_EVALNODE(9)

# NAME

`aml_evalnode`, `aml_evalname`, `aml_find_node`, `aml_freevalue`, `aml_val2int` — AML API

# SYNOPSIS

`#include <dev/acpi/acpireg.h>`
`#include <dev/acpi/acpivar.h>`
`#include <dev/acpi/acpidev.h>`
`#include <dev/acpi/amltypes.h>`
`#include <dev/acpi/dsdt.h>`

int
`aml_evalnode`(struct acpi_softc *sc, struct aml_node *node, int argc, struct aml_value *argv, struct aml_value *res);

int
`aml_evalname`(struct acpi_softc *sc, struct aml_node *parent, const char *name, int argc, struct aml_value *argv, struct aml_value *res);

int
`aml_find_node`(struct aml_node *node, const char *name, int (*cbproc)(struct aml_node *, void *arg), void *arg);

void
`aml_freevalue`(struct aml_value *val);

int64_t
`aml_val2int`(struct aml_value *rval);

# DESCRIPTION

The AML API handles decoding and evaluation of the AML code embedded in a machine's ACPI tables. This code is used to implement configuration and control mechanisms for machines.

`aml_evalnode`() evaluates the AML node node located in the ACPI table specified by sc. Parameters may be passed using the argv parameters with the parameter argc specifying the number of parameters passed. If there are no arguments, a value of 0 is used for argc and argv should be `NULL`. If evaluating the node produces any result, for example a string with a device name reference, this result is stored in the res parameter unless it is `NULL`. res is cleared before storing the result. If node does not exist, `aml_evalnode`() returns `ACPI_E_BADVALUE`, otherwise it returns 0.

`aml_evalname`() is similar to `aml_evalnode`() but differs in that it searches for a subnode of parent with the name name. If such a node is found, it is evaluated using `aml_evalnode`(), passing whatever parameters were passed to itself. `aml_evalname`() returns the return value of `aml_evalnode`().

`aml_find_node`() is used to find all subnodes of parent with a name of name. For each node found, the function specified as the cbproc parameter is called with the node and arg as the first and second parameters, respectively. The function specified as the cbproc parameter returns a value that specifies if the tree walk should be terminated (!0) or continued (0) with the children. `aml_find_node`() always returns 0.

`aml_freevalue`() is used to free up the result returned from `aml_evalnode`() or the other AML evaluation functions. Note that no attempt is made to free the struct aml_value itself so it is safe to allocate this on the stack. Also, calling `aml_freevalue`() with a parameter of `NULL` is not an error.

`aml_val2int`() is used to convert the struct aml_value pointed to by the rval parameter to a signed 64-bit integer value. Multiple types exist for struct aml_value, and the conversion value depends on the type of the value object as follows. For objects of type `AML_OBJTYPE_INTEGER` and `AML_OBJTYPE_STATICINT`, the return value is simply the integer value stored in the object. For objects of type `AML_OBJTYPE_BUFFER`, the return value is the integer interpretation of the buffer contents. For objects of type `AML_OBJTYPE_STRING`, the return value is the integer value represented as a string in base 10 or, if prefixed by “0x”, in base 16. If rval is `NULL` or not of one of the types mentioned above, `aml_val2int`() returns 0.

# EXAMPLES

Using `aml_evalname`() to invoke the “_STA” method on a node node should be done like the following:

    struct acpi_softc	*sc
    struct aml_node		*node;
    struct aml_value	res;

    if (aml_evalname(sc->sc_acpi, node, "_STA", 0, NULL, &res) != 0) {
    	dnprintf(10, "%s: no _STA\n", DEVNAME(sc));
    	return;
    }

Using the struct aml_value obtained from the “_STA” call to determine if the device is a battery is done as follows:

    if ((aml_val2int(&res) & STA_BATTERY) == 0) {
    	dnprintf(10, %s: no battery present\n", DEVNAME(sc));
    	return;

Finally, when the result stored in res is no longer needed, free it using `aml_freevalue`():

    aml_freevalue(&res);

# SEE ALSO

acpi(4), acpidump(8)

# HISTORY

The AML API was written by Jordan Hargrave <jordan@openbsd.org>.

September 14, 2015 | Debian