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