1.\" $OpenBSD: aml_evalnode.9,v 1.6 2007/09/13 03:44:21 weingart Exp $ 2.\" 3.\" Copyright (c) 2007 Michael Knudsen <mk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 13 2007 $ 18.Dt AML_EVALNODE 9 19.Os 20.Sh NAME 21.Nm aml_evalnode , 22.Nm aml_evalname , 23.Nm aml_find_node , 24.Nm aml_freevalue , 25.Nm aml_val2int 26.Nd AML API 27.Sh SYNOPSIS 28.Fd #include <dev/acpi/acpireg.h> 29.Fd #include <dev/acpi/acpivar.h> 30.Fd #include <dev/acpi/acpidev.h> 31.Fd #include <dev/acpi/amltypes.h> 32.Fd #include <dev/acpi/dsdt.h> 33.Ft int 34.Fn "aml_evalnode" "struct acpi_softc *sc" "struct aml_node *node" \ 35"int argc" "struct aml_value *argv" "struct aml_value *res" 36.Ft int 37.Fn "aml_evalname" "struct acpi_softc *sc" "struct aml_node *parent" \ 38"const char *name" "int argc" "struct aml_value *argv" \ 39"struct aml_value *res" 40.Ft int 41.Fn "aml_find_node" "struct aml_node *node" "const char *name" \ 42"int (*cbproc)(struct aml_node *, void *arg)" "void *arg" 43.Ft void 44.Fn "aml_freevalue" "struct aml_value *val" 45.Ft int64_t 46.Fn "aml_val2int" "struct aml_value *rval" 47.Sh DESCRIPTION 48The AML API handles decoding and evaluation of the AML 49code embedded in a machine's ACPI tables. 50This code is used to implement configuration and control mechanisms for 51machines. 52.Pp 53.Fn aml_evalnode 54evaluates the AML node 55.Fa node 56located in the ACPI table specified by 57.Fa sc . 58Parameters may be passed using the 59.Fa argv 60parameters with the parameter 61.Fa argc 62specifying the number of parameters passed. 63If there are no arguments, 64a value of 0 is used for 65.Fa argc 66and 67.Fa argv 68should be 69.Dv NULL . 70If evaluating the node produces any result, for example a string with a device 71name reference, this result is stored in the 72.Fa res 73parameter unless it is 74.Dv NULL . 75.Fa res 76is cleared before storing the result. 77If 78.Pa node 79does not exist, 80.Fn aml_evalnode 81returns 82.Dv ACPI_E_BADVALUE , 83otherwise it returns 0. 84.Pp 85.Fn aml_evalname 86is similar to 87.Fn aml_evalnode 88but differs in that it searches for a subnode of 89.Pa parent 90with the name 91.Pa name . 92If such a node is found, it is evaluated using 93.Fn aml_evalnode , 94passing whatever parameters were passed to itself. 95.Fn aml_evalname 96returns the return value of 97.Fn aml_evalnode . 98.Pp 99.Fn aml_find_node 100is used to find all subnodes of 101.Pa parent 102with a name of 103.Pa name . 104For each node found, the function specified as the 105.Pa cbproc 106parameter is called with the node and 107.Pa arg 108as the first and second parameters, respectively. 109The function specified as the 110.Pa cbproc 111parameter returns a value that specifies if the tree walk 112should be terminated (!0) or continued (0) with the children. 113.Fn aml_find_node 114always returns 0. 115.Pp 116.Fn aml_freevalue 117is used to free up the result returned from 118.Fn aml_evalnode 119or the other AML evaluation functions. 120Note that no attempt is made to free the 121.Pa "struct aml_value" 122itself so it is safe to allocate this on the stack. 123Also, calling 124.Fn aml_freevalue 125with a parameter of 126.Dv NULL 127is not an error. 128.Pp 129.Fn aml_val2int 130is used to convert the 131.Pa struct aml_value 132pointed to by the 133.Pa rval 134parameter to a signed 64-bit integer value. 135Multiple types exist for 136.Pa struct aml_value , 137and the conversion value depends on the type 138of the value object as follows. 139For objects of type 140.Dv AML_OBJTYPE_INTEGER 141and 142.Dv AML_OBJTYPE_STATICINT , 143the return value is simply the integer value stored in the object. 144For objects of type 145.Dv AML_OBJTYPE_BUFFER , 146the return value is the integer interpretation of the buffer contents. 147For objects of type 148.Dv AML_OBJTYPE_STRING , 149the return value is the integer value represented as a string in base 10 150or, if prefixed by 151.Dq 0x , 152in base 16. 153If 154.Pa rval 155is 156.Dv NULL 157or not of one of the types mentioned above, 158.Fn aml_val2int 159returns 0. 160.Sh EXAMPLES 161Using 162.Fn aml_evalname 163to invoke the 164.Dq _STA 165method on a node 166.Pa n 167should be done like the following: 168.Bd -literal -offset indent 169struct acpi_softc *sc 170struct aml_node *n; 171struct aml_value res; 172 173if (aml_evalname(sc->sc_acpi, n, "_STA", 0, NULL, &res) != 0) { 174 dnprintf(10, "%s: no _STA\\n", DEVNAME(sc)); 175 return; 176} 177.Ed 178.Pp 179Using the 180.Pa struct aml_value 181obtained from the 182.Dq _STA 183call to determine if the device is a battery is done as follows: 184.Bd -literal -offset indent 185if ((aml_val2int(&res) & STA_BATTERY) == 0) { 186 dnprintf(10, %s: no battery present\\n", DEVNAME(sc)); 187 return; 188.Ed 189.Pp 190Finally, when the result stored in 191.Pa res 192is no longer needed, free it using 193.Fn aml_freevalue : 194.Bd -literal -offset indent 195aml_freevalue(&res); 196.Ed 197.Sh SEE ALSO 198.Xr acpi 4 , 199.Xr acpidump 8 200.Sh HISTORY 201The AML API was written by 202.An Jordan Hargrave Aq jordan@openbsd.org . 203