sys/man/2/aml

   1 .TH AML 2
   2 .SH NAME
   3 amltag, amlval, amlint, amllen, amlnew, amlinit, amlexit, amlload, amlwalk, amleval, amlenum, amltake, amldrop - ACPI machine language interpreter
   4 .SH SYNOPSIS
   5 .\" .ta 0.75i 1.5i 2.25i 3i 3.75i 4.5i
   6 .ta 0.7i +0.7i +0.7i +0.7i +0.7i +0.7i +0.7i
   7 .EX
   8 #include <u.h>
   9 #include <libc.h>
  10 #include <aml.h>
  11
  12 int     amltag(void *);
  13 void*   amlval(void *);
  14 uvlong  amlint(void *);
  15 int     amllen(void *);
  16
  17 void*   amlnew(char tag, int len);
  18
  19 void    amlinit(void);
  20 void    amlexit(void);
  21
  22 int     amlload(uchar *data, int len);
  23 void*   amlwalk(void *dot, char *name);
  24 int     amleval(void *dot, char *fmt, ...);
  25 void    amlenum(void *dot, char *seg, int (*proc)(void *, void *), void *arg);
  26
  27 void    amltake(void *);
  28 void    amldrop(void *);
  29
  30 void*   amlroot;
  31 int     amldebug;
  32 .EE
  33 .SH DESCRIPTION
  34 The aml library implements a interpreter for the ACPI machine language
  35 byte code.
  36 .PP
  37 The interpreter runtime state is initialized by calling
  38 .I amlinit
  39 and frees all the resources when
  40 .I amlexit
  41 is called.
  42 The runtime state consists of objects organized in a global
  43 namespace. The name object refered by
  44 .I amlroot
  45 is the root of that namespace.
  46 .PP
  47 .I Amlload
  48 populates the namespace with objects parsed from the
  49 definition block of
  50 .I len
  51 byte size read from
  52 .IR data .
  53 .PP
  54 Objects are dynamically allocated and typed and are passed as
  55 .B void*
  56 pointers. The type tag of an object can be determined with the
  57 .I amltag
  58 function. The following table shows the defined tags and ther
  59 underlying type:
  60 .EX
  61 /*
  62  *      b       uchar*  buffer          amllen() returns number of bytes
  63  *      s       char*   string          amllen() is strlen()
  64  *      n       char*   undefined name  amllen() is strlen()
  65  *      i       uvlong* integer
  66  *      p       void**  package         amllen() is # of elements
  67  *      r       void*   region
  68  *      f       void*   field
  69  *      u       void*   bufferfield
  70  *      N       void*   name
  71  *      R       void*   reference
  72  */
  73 .EE
  74 .PP
  75 Name objects (like
  76 .IR amlroot )
  77 can be traversed with
  78 .I amlenum
  79 and
  80 .I amlwalk
  81 functions. The
  82 .I amlwalk
  83 function
  84 takes a path string (relative or absolute)
  85 and returns the final name object of the walk; or
  86 .B nil
  87 if not found.
  88 .I Amlenum
  89 recursively enumerates all child name objects of
  90 .I dot
  91 that have
  92 .I seg
  93 as name; or any name if
  94 .I seg
  95 is
  96 .BR nil ;
  97 calling
  98 .I proc
  99 for each one passing
 100 .IR dot .
 101 When
 102 .I proc
 103 returns zero, enumeration will continue recursively down
 104 for the current dot.
 105 .PP
 106 .I Amlval
 107 returns the value of a name, reference or field object.
 108 Calling
 109 .I amlval
 110 on any other object yiedls the same object.
 111 .PP
 112 .I Amllen
 113 is defined for variable length objects like buffers, strings and packages.
 114 For strings, the number of characters (not including terminating null byte)
 115 is returned. For buffers, the size of the buffer in bytes is returned.
 116 For packages (arrays), the number of elements is returned. For any other
 117 object types, the return value is undefined.
 118 .PP
 119 .I Amlint
 120 returns the integer value of an object. For strings, the string is interpreted
 121 as hexadecimal number. For buffers and buffer fields, the binary value is returned.
 122 Integers just return ther value. Any other object types yield zero.
 123 .PP
 124 Integer, buffer, string and package objects can be created with the
 125 .I amlnew
 126 function. The
 127 .I tag
 128 specific definition of the
 129 .I len
 130 parameter is the same as in
 131 .I amllen
 132 (see above).
 133 .PP
 134 .I Amleval
 135 evaluates the name object
 136 .IR dot .
 137 For method evaluation, the
 138 .I fmt
 139 string parameter describes the arguments passed to the evaluated
 140 method. Each character in
 141 .I fmt
 142 represents a tag for an method argument taken from the
 143 variable argument list of
 144 .I amleval
 145 and passed to the method.
 146 The fmt tags
 147 .BR I ,
 148 .B i
 149 and
 150 .B s
 151 take
 152 .BR uvlong ,
 153 .B int
 154 and
 155 .B char*
 156 from the variable argument list and create object copies to
 157 be passed.
 158 The tags
 159 .BR b ,
 160 .B p
 161 and
 162 .B *
 163 take
 164 .B void*
 165 from the variable argument list and pass them as objects
 166 by reference (without conversion or copies).
 167 The last variable argument is a pointer to the result
 168 object location. When the last parameter is
 169 .B nil
 170 the result is discarded.
 171 .PP
 172 Objects returned by
 173 .IR amlval ,
 174 .I amleval
 175 and
 176 .I amlnew
 177 are subject to garbage collection during method evaluation
 178 unless previously maked to be excluded from collection with
 179 .IR amltake .
 180 To remark an object for collection,
 181 .I amldrop
 182 needs be called.
 183 Objects stay valid as long as they are reachable from
 184 .IR amlroot .
 185 .PP
 186 .EX
 187 extern void*    amlalloc(int);
 188 extern void     amlfree(void*);
 189 .EE
 190 .PP
 191 .I Amlalloc
 192 and
 193 .I amlfree
 194 can be optionaly defined to control dynamic memory allocation
 195 providing a way to limit or pool the memory allocated by acpi.
 196 If not provided, the library will use the functions
 197 defined in
 198 .IR malloc (2)
 199 for dynamic allocation.
 200 .PP
 201 The aml library can be linked into userspace programs and
 202 and the kernel which have different means of hardware access.
 203 .PP
 204 .EX
 205 extern void     amldelay(int);
 206 .EE
 207 .PP
 208 .I Amldelay
 209 is called by the interpreter with the number of milliseconds it
 210 needs to wait.
 211 .PP
 212 .EX
 213 extern int      amlmapio(Amlio *io);
 214 extern void     amlunmapio(Amlio *io);
 215 .EE
 216 .PP
 217 The interpreter calls
 218 .I amlmapio
 219 with a
 220 .I Amlio
 221 data structure that needs be filled out.
 222 .PP
 223 .EX
 224 typedef struct Amlio Amlio;
 225 struct Amlio
 226 {
 227         int     space;
 228         uvlong  off;
 229         uvlong  len;
 230         void    *name;
 231         uchar   *va;
 232
 233         void    *aux;
 234         int     (*read)(Amlio *io, void *data, int len, int off);
 235         int     (*write)(Amlio *io, void *data, int len, int off);
 236 };
 237 .EE
 238 .PP
 239 The
 240 members
 241 .IR space ,
 242 .IR off ,
 243 .I len
 244 and
 245 .I name
 246 are initialized by the interpreter and describe the I/O region
 247 it needs access to. For memory regions,
 248 .I va
 249 can to be set to the virtual address mapping base by the
 250 mapping function.
 251 The interpreter will call the
 252 .I read
 253 and
 254 .I write
 255 function pointers with a relative offset to the regions
 256 base offset.
 257 The
 258 .I aux
 259 pointer can be used freely by the map function to attach its own
 260 resources to the I/O region and allows it to free these resources
 261 on
 262 .IR amlunmapio .
 263 .PP
 264 The following region types are defined by ACPI:
 265 .EX
 266 enum {
 267         MemSpace        = 0x00,
 268         IoSpace         = 0x01,
 269         PcicfgSpace     = 0x02,
 270         EbctlSpace      = 0x03,
 271         SmbusSpace      = 0x04,
 272         CmosSpace       = 0x05,
 273         PcibarSpace     = 0x06,
 274         IpmiSpace       = 0x07,
 275 };
 276 .EE
 277 .SH SOURCE
 278 .B /sys/src/libaml