glenda.party
term% ls -F
term% pwd
$home/manuals/9front/2/aml
term% cat index.txt
AML(2)                        System Calls Manual                       AML(2)



NAME
       amltag, amlval, amlint, amllen, amlnew, amlinit, amlexit, amlload, aml‐
       walk, amleval, amlenum, amltake, amldrop - ACPI machine language inter‐
       preter

SYNOPSIS
       #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;

DESCRIPTION
       The aml library implements an interpreter for the ACPI machine language
       byte code.

       amlinit() amlexit()
              The interpreter runtime state is initialized by calling  amlinit
              and frees all the resources when amlexit is called.  The runtime
              state consists of objects organized in a global  namespace.  The
              name  object  referred  to  by amlroot is the root of that name‐
              space.

       amlload(data,len)
              Amlload populates the namespace with  objects  parsed  from  the
              definition block of len byte size read from data.  The pc kernel
              provides access to the ACPI  tables  through  the  /dev/acpitbls
              file (see arch(3) for further details).

       amltag(p)
              Objects  are  dynamically  allocated and typed and are passed as
              void* pointers. The type tag of an object can be determined with
              the  amltag function. The following table shows the defined tags
              and ther underlying type:
              /*
               *     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
               */

       amlwalk(dot,name)
              Amlwalk takes a path string (relative to dot) in  name  and  re‐
              turns the final name object of the walk; or nil if not found.

       amlenum(dot,seg,proc,arg)
              Amlenum  recursively  enumerates  all  child name objects of dot
              that have seg as name; or any name if seg is nil;  calling  proc
              for  each  one passing dot.  When proc returns zero, enumeration
              will continue recursively down for the current dot.

       amlval(p)
              Amlval returns the value of a name, reference or  field  object.
              Calling amlval on any other object yields the same object.

       amllen(p)
              Amllen  is  defined  for  variable  length objects like buffers,
              strings and packages.  For strings,  the  number  of  characters
              (not  including the terminating null byte) is returned. For buf‐
              fers, the size of the buffer in bytes is returned.  For packages
              (arrays),  the number of elements is returned. For any other ob‐
              ject types, the return value is undefined.

       amlint(p)
              Amlint returns the integer value of an object. For strings,  the
              string  is interpreted as an hexadecimal number. For buffers and
              buffer fields, the binary value is returned.  Integers just  re‐
              turn their value. Any other object types yield zero.

       amlnew(tag,len)
              Integer,  buffer, string and package objects can be created with
              the amlnew function. The tag specific definition of the len  pa‐
              rameter is the same as in amllen (see above).

       amleval(dot,fmt,...)
              Amleval  evaluates  the name object dot.  For method evaluation,
              the fmt string parameter describes the arguments passed  to  the
              evaluated  method. Each character in fmt represents a tag for an
              method argument taken from the variable argument list of amleval
              and  passed to the method.  The fmt tags I, i and s take uvlong,
              int and char* from the variable argument list and create  object
              copies  to  be  passed.  The tags b, p and * take 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 nil the result is discarded.

       amltake(p) amldrop(p)
              Objects  returned  by  amlval, amleval and amlnew are subject to
              garbage collection during method  evaluation  unless  previously
              maked to be excluded from collection with amltake.  To remark an
              object for collection, amldrop needs be  called.   Objects  stay
              valid as long as they are reachable from amlroot.

       The  aml  library  can be linked into userspace programs and the kernel
       which have different means of hardware access and memory constraints.

       The Amlio data structure defines access to a hardware space.

       enum {
              MemSpace      = 0x00,
              IoSpace              = 0x01,
              PcicfgSpace   = 0x02,
              EbctlSpace    = 0x03,
              SmbusSpace    = 0x04,
              CmosSpace     = 0x05,
              PcibarSpace   = 0x06,
              IpmiSpace     = 0x07,
       };

       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);
       };

       The members space, off, len and name are initialized by the interpreter
       and  describe the I/O region it needs access to. For memory regions, va
       can to be set to the virtual address mapping base by the mapping  func‐
       tion.   The  interpreter will call the read and write function pointers
       with a relative offset to the regions base offset.  The 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 amlunmapio.

       amlmapio(io) amlunmapio(io)
              The interpreter calls amlmapio with a Amlio data structure  that
              is to be filled out. When finished, the interpreter calls amlun‐
              mapio with the same data structure to allow freeing resources.

       amldelay(µs)
              Amldelay is called by the interpreter with  the  number  of  mi‐
              croseconds to sleep.

       amlalloc(n) amlfree(p)
              Amlalloc  and  amlfree  can be optionally defined to control dy‐
              namic 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 malloc(2) for dynamic allocation.

SOURCE
       /sys/src/libaml

SEE ALSO
       arch(3)



                                                                        AML(2)