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 n should be done like the following:

    struct acpi_softc	*sc
    struct aml_node		*n;
    struct aml_value	res;
    if (aml_evalname(sc->sc_acpi, n, "_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>.