add aml(2) manual page

1 files changed, 278 insertions, 0 deletions

diff --git a/sys/man/2/aml b/sys/man/2/aml
new file mode 100644
index 000000000..d3ce2b2a7
--- /dev/null
+++ b/sys/man/2/aml
@@ -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