add aml(2) manual page
This commit is contained in:
cinap_lenrek
parent
c5a70cc23d
commit
65829e635c
1 changed files with 278 additions and 0 deletions
278
sys/man/2/aml
Normal file
278
sys/man/2/aml
Normal file
|
|
@ -0,0 +1,278 @@
|
|||
.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 milliseconds 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
|
||||
Loading…
Reference in a new issue