plan9fox/sys/man/2/aml

.TH AML 2
.SH NAME
amltag, amlval, amlint, amllen, amlnew, amlinit, amlexit, amlload, amlwalk, amleval, amlenum, amltake, amldrop - ACPI machine language interpreter
.SH SYNOPSIS
.\" .ta 0.75i 1.5i 2.25i 3i 3.75i 4.5i
.ta 0.7i +0.7i +0.7i +0.7i +0.7i +0.7i +0.7i
.EX
#include <u.h>
#include <libc.h>
#include <aml.h>

int	amltag(void *);
void*	amlval(void *);
uvlong	amlint(void *);
int	amllen(void *);

void*	amlnew(char tag, int len);

void	amlinit(void);
void	amlexit(void);

int	amlload(uchar *data, int len);
void*	amlwalk(void *dot, char *name);
int	amleval(void *dot, char *fmt, ...);
void	amlenum(void *dot, char *seg, int (*proc)(void *, void *), void *arg);

void	amltake(void *);
void	amldrop(void *);

void*	amlroot;
int	amldebug;
.EE
.SH DESCRIPTION
The aml library implements a interpreter for the ACPI machine language
byte code.
.PP
The interpreter runtime state is initialized by calling
.I amlinit
and frees all the resources when
.I amlexit
is called.
The runtime state consists of objects organized in a global
namespace. The name object refered by
.I amlroot
is the root of that namespace.
.PP
.I Amlload
populates the namespace with objects parsed from the
definition block of 
.I len
byte size read from
.IR data .
.PP
Objects are dynamically allocated and typed and are passed as
.B void*
pointers. The type tag of an object can be determined with the
.I amltag
function. The following table shows the defined tags and ther
underlying type:
.EX
/*
 *	b	uchar*	buffer		amllen() returns number of bytes
 *	s	char*	string		amllen() is strlen()
 *	n	char*	undefined name	amllen() is strlen()
 *	i	uvlong*	integer
 *	p	void**	package		amllen() is # of elements
 *	r	void*	region
 *	f	void*	field
 *	u	void*	bufferfield
 *	N	void*	name
 *	R	void*	reference
 */
.EE
.PP
Name objects (like
.IR amlroot )
can be traversed with
.I amlenum
and
.I amlwalk
functions. The
.I amlwalk
function
takes a path string (relative or absolute)
and returns the final name object of the walk; or
.B nil
if not found.
.I Amlenum
recursively enumerates all child name objects of
.I dot
that have
.I seg
as name; or any name if
.I seg
is
.BR nil ;
calling
.I proc
for each one passing
.IR dot .
When
.I proc
returns zero, enumeration will continue recursively down
for the current dot.
.PP
.I Amlval
returns the value of a name, reference or field object.
Calling
.I amlval
on any other object yiedls the same object.
.PP
.I Amllen
is defined for variable length objects like buffers, strings and packages.
For strings, the number of characters (not including terminating null byte)
is returned. For buffers, the size of the buffer in bytes is returned.
For packages (arrays), the number of elements is returned. For any other
object types, the return value is undefined.
.PP
.I Amlint
returns the integer value of an object. For strings, the string is interpreted
as hexadecimal number. For buffers and buffer fields, the binary value is returned.
Integers just return ther value. Any other object types yield zero.
.PP
Integer, buffer, string and package objects can be created with the
.I amlnew
function. The 
.I tag
specific definition of the
.I len
parameter is the same as in
.I amllen
(see above).
.PP
.I Amleval
evaluates the name object
.IR dot .
For method evaluation, the
.I fmt
string parameter describes the arguments passed to the evaluated
method. Each character in
.I fmt
represents a tag for an method argument taken from the
variable argument list of
.I amleval
and passed to the method.
The fmt tags
.BR I ,
.B i
and
.B s
take
.BR uvlong ,
.B int
and
.B char*
from the variable argument list and create object copies to
be passed.
The tags
.BR b ,
.B p
and
.B *
take
.B void*
from the variable argument list and pass them as objects
by reference (without conversion or copies).
The last variable argument is a pointer to the result
object location. When the last parameter is
.B nil
the result is discarded.
.PP
Objects returned by
.IR amlval ,
.I amleval
and
.I amlnew
are subject to garbage collection during method evaluation
unless previously maked to be excluded from collection with
.IR amltake .
To remark an object for collection,
.I amldrop
needs be called.
Objects stay valid as long as they are reachable from
.IR amlroot .
.PP
.EX
extern void*	amlalloc(int);
extern void	amlfree(void*);
.EE
.PP
.I Amlalloc
and
.I amlfree
can be optionaly defined to control dynamic memory allocation 
providing a way to limit or pool the memory allocated by acpi.
If not provided, the library will use the functions
defined in
.IR malloc (2)
for dynamic allocation.
.PP
The aml library can be linked into userspace programs and
and the kernel which have different means of hardware access.
.PP
.EX
extern void	amldelay(int);
.EE
.PP
.I Amldelay
is called by the interpreter with the number of microseconds it
needs to wait.
.PP
.EX
extern int	amlmapio(Amlio *io);
extern void	amlunmapio(Amlio *io);
.EE
.PP
The interpreter calls
.I amlmapio
with a
.I Amlio
data structure that needs be filled out.
.PP
.EX
typedef struct Amlio Amlio;
struct Amlio
{
	int	space;
	uvlong	off;
	uvlong	len;
	void	*name;
	uchar	*va;

	void	*aux;
	int	(*read)(Amlio *io, void *data, int len, int off);
	int	(*write)(Amlio *io, void *data, int len, int off);
};
.EE
.PP
The
members
.IR space ,
.IR off ,
.I len
and
.I name
are initialized by the interpreter and describe the I/O region
it needs access to. For memory regions,
.I va
can to be set to the virtual address mapping base by the
mapping function.
The interpreter will call the
.I read
and
.I write
function pointers with a relative offset to the regions
base offset.
The
.I aux
pointer can be used freely by the map function to attach its own
resources to the I/O region and allows it to free these resources
on
.IR amlunmapio .
.PP
The following region types are defined by ACPI:
.EX
enum {
	MemSpace	= 0x00,
	IoSpace		= 0x01,
	PcicfgSpace	= 0x02,
	EbctlSpace	= 0x03,
	SmbusSpace	= 0x04,
	CmosSpace	= 0x05,
	PcibarSpace	= 0x06,
	IpmiSpace	= 0x07,
};
.EE
.SH SOURCE
.B /sys/src/libaml