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