Add manpages acpi userland tools.

Obtained from:	ACPI for FreeBSD project

4 files changed, 516 insertions, 4 deletions

diff --git a/usr.sbin/acpi/acpidump/Makefile b/usr.sbin/acpi/acpidump/Makefile
index 346dcf2..c135529 100644
--- a/usr.sbin/acpi/acpidump/Makefile
+++ b/usr.sbin/acpi/acpidump/Makefile
@@ -3,8 +3,7 @@
 
 PROG=	acpidump
 SRCS=	acpi.c acpi_user.c asl_dump.c aml_dump.c acpidump.c
-NOMAN=	yes
-#MAN8=	acpidump.8
+MAN8=	acpidump.8
 #DEBUG_FLAGS= -g
 
 .include <bsd.prog.mk>
diff --git a/usr.sbin/acpi/acpidump/acpidump.8 b/usr.sbin/acpi/acpidump/acpidump.8
new file mode 100644
index 0000000..a9919bd
--- /dev/null
+++ b/usr.sbin/acpi/acpidump/acpidump.8
@@ -0,0 +1,174 @@
+.\" ACPI (ACPI Package)
+.\"
+.\" Copyright (c) 1999 Doug Rabson <dfr@FreeBSD.org>
+.\" Copyright (c) 2000 Mitsuru IWASAKI <iwasaki@FreeBSD.org>
+.\" Copyright (c) 2000 Yasuo YOKOYAMA <yokoyama@jp.FreeBSD.org>
+.\" Copyright (c) 2000 Hiroki Sato <hrs@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\" 
+.\" $FreeBSD$
+.\" 
+.Dd August 31, 2000
+.Dt ACPIDUMP 8
+.Os FreeBSD 5.0
+.Sh NAME
+.Nm acpidump
+.Nd dump ACPI tables
+.Sh SYNOPSIS
+.Nm acpidump
+.Nm acpidump
+.Op Fl o Ar dsdt_file_for_output
+.Nm acpidump
+.Op Fl f Ar dsdt_file_for_input
+.Sh DESCRIPTION
+The
+.Nm
+command analyzes ACPI tables in physical memory and dumps them to standard output.
+In addition,
+.Nm
+can disassemble some contents of the tables in AML
+.Pq ACPI Machine Language
+and dump them in ASL
+.Pq ACPI Source Language .
+.Pp
+ACPI tables have an notably essential data block called DSDT
+.Pq Differentiated System Description Table ,
+that includes information used on the kernel side such as
+detail information about PnP hardware, procedures for controlling
+a power management support and so on.
+.Nm
+can extract a DSDT data block from physical memory and store it into
+a DSDT data file, and also can generate an output in ASL
+from a given DSDT data file.
+.Pp
+When
+.Nm
+is invoked with no option, it will search ACPI tables from physical
+memory via a special file
+.Pa /dev/mem
+and dump them.  First, it searches Root System Description Pointer,
+that has a signature
+.Qq RSD PTR\ \& ,
+and then gets RSDT
+.Pq Root System Description Table ,
+which includes a list of pointers to physical memory addresses
+for other tables.
+RSDT itself and all other tables linked from RSDT are generically
+called SDT
+.Pq System Description Table
+and their header has the common format which consists of items
+such as Signature, Length, Revision, Checksum, OEMID, OEM Table ID,
+OEM Revision, Creator ID and Creator Revision.
+.Nm
+dumps contents of these SDTs.
+For further information about formats of each table,
+see chapter 5: ACPI Software Programming Model, 
+.Dq Advanced Configuration and Power Interface Specification Revision 1.0b
+from Intel/Microsoft/Toshiba.
+.Pp
+There is always a pointer to a physical memory address in RSDT for FACP
+.Pq Fixed ACPI Description Table .
+.Ns \ FACP defines static system information about power management support
+.Pq ACPI Hardware Register Implementation
+such as interrupt mode
+.Pq INT_MODEL ,
+SCI interrupt number, SMI command port
+.Pq SMI_CMD
+and location of ACPI registers.  
+FACP also has a pointer to a physical memory address for DSDT,
+which includes information used on the kernel side such as
+PnP, power management support and so on.
+While the other tables are described in fixed format,
+DSDT consists of AML data which compiled from sources
+written in free formated ASL, description language for ACPI.
+When
+.Nm
+outputs DSDT, it disassembles the AML data and
+translates them into ASL.
+.Sh OPTIONS
+The following options are supported by
+.Nm Ns :
+.Bl -tag -width indent
+.It Fl o Ar dsdt_file_for_output
+Stores DSDT data block from physical memory into a file specified in
+.Ar dsdt_file_for_output
+in addition to behavior with no option.
+.It Fl f Ar dsdt_file_for_input
+Interprets AML data in DSDT from a file specified in
+.Ar dsdt_file_for_input
+and dumps them in ASL to standard output.
+.It Fl h
+Displays usage and exit.
+.El
+.Sh EXAMPLES
+This is an example to get a dump of SDTs and a DSDT data file
+simultaneously on a machine that supports ACPI BIOS.
+.Bd -literal -offset indent
+# acpidump -o foo.dsdt > foo.asl
+.Ed
+.Sh BUGS
+In the current implementation,
+.Nm
+doesn't dump any information of Firmware ACPI Control Structure
+.Pq FACS
+specified by a pointer in FACP.
+Some parts of output in ASL are incomplete.  To obtain a complete
+output, it would need to change the implementation into another one
+that analyzes a whole DSDT and builds an ACPI namespace as preprocess,
+and then interprets the DSDT again referring to namespace.
+.Sh FILES
+.Bl -tag -width /dev/mem
+.It Pa /dev/mem
+.El
+.Sh SEE ALSO
+.Xr mem 4 ,
+.Xr acpi 4 ,
+.Xr acpiconf 8 ,
+.Xr amldb 8
+.Pp
+.Dq Advanced Configuration and Power Interfce Specification
+.Bd -literal -offset indent -compact 
+Intel
+Microsoft
+Toshiba
+Revision 1.0b
+.Ed
+<URL:http://www.teleport.com/~acpi/>
+.Sh AUTHORS
+.An Doug Rabson Aq dfr@FreeBSD.org
+.An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org
+.An Yasuo YOKOYAMA Aq yokoyama@jp.FreeBSD.org
+.Pp
+Some contributions made by
+.An Chitoshi Ohsawa Aq ohsawa@catv1.ccn-net.ne.jp ,
+.An Takayasu IWANASHI Aq takayasu@wendy.a.perfect-liberty.or.jp ,
+.An Yoshihiko SARUMARU Aq mistral@imasy.or.jp ,
+.An Hiroki Sato Aq hrs@FreeBSD.org ,
+and
+.An Michael Lucas Aq mwlucas@blackhelicopters.org .
+.Sh HISTORY
+The
+.Nm
+command appeared in
+.Fx 5.0 .
diff --git a/usr.sbin/acpi/amldb/Makefile b/usr.sbin/acpi/amldb/Makefile
index e683e1c..e0f92a5 100644
--- a/usr.sbin/acpi/amldb/Makefile
+++ b/usr.sbin/acpi/amldb/Makefile
@@ -4,8 +4,7 @@
 PROG=	amldb
 SRCS=	amldb.c debug.c region.c
 SRCS+=	aml_parse.c aml_name.c aml_amlmem.c aml_memman.c aml_store.c aml_obj.c aml_evalobj.c aml_common.c
-NOMAN=	yes
-#MAN8=	amldb.8
+MAN8=	amldb.8
 #DEBUG_FLAGS= -g
 CFLAGS+= -I${.CURDIR}/../../../sys -I${.CURDIR}
 
diff --git a/usr.sbin/acpi/amldb/amldb.8 b/usr.sbin/acpi/amldb/amldb.8
new file mode 100644
index 0000000..bcfa01c
--- /dev/null
+++ b/usr.sbin/acpi/amldb/amldb.8
@@ -0,0 +1,340 @@
+.\" ACPI (ACPI Package)
+.\" 
+.\" Copyright (c) 2000 Takanori Watanabe <takawata@FreeBSD.org>
+.\" Copyright (c) 2000 Mitsuru IWASAKI <iwasaki@FreeBSD.org>
+.\" Copyright (c) 2000 Yasuo YOKOYAMA <yokoyama@jp.FreeBSD.org>
+.\" Copyright (c) 2000 Norihiro KUMAGAI <kumagai@home.com>
+.\" 
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd August 31, 2000
+.Dt AMLDB 8
+.Os FreeBSD 5.0
+.Sh NAME
+.Nm amldb
+.Nd executing and debugging AML interpreter
+.Pq with DSDT files
+.Sh SYNOPSIS
+.Nm amldb
+.Op Fl dhst
+.Ar dsdt_file ...
+.Sh DESCRIPTION
+.Nm Amldb
+parses the DSDT
+.Pq Differentiated System Description Table
+files, which usually are acquired from ACPI BIOS, and executes
+the sequence of ACPI Control Methods described in AML
+.Pq ACPI Machine Language
+with its AML interpreter.
+.Nm Amldb
+also has a simple ACPI virtual machine.  During execution of the
+Control Methods each access to the region, such as
+SystemMemory, SystemIO, PCI_Config, does not affect the real
+hardware but only the virtual machine.
+Because the sequence of virtual accesses is maintained in user space,
+AML interpreter developers need not worry about any effect on hardware
+when they analyze DSDT data files.  They can develop and debug the
+interpreter, even if the machine has no ACPI BIOS.
+.Pp
+The developer will need to acquire a DSDT data file from any machine
+with ACPI BIOS through
+.Xr acpidump 8 .
+The DSDT is a table, a part of the whole ACPI memory table
+located in somewhere in the BIOS area
+.Pq 0xa0000 \- 0x100000 .
+It includes such information as the detailed hardware information
+for PnP, and the set of procedures which perform power management from
+the OS.  The information is stored in AML format.
+.Pp
+The AML interpreter can execute any of the Control Methods specified
+by users.  When executed, it interprets the byte sequence in the
+Control Method of DSDT, and disassembles the opecodes that it
+recognizes into ASL
+.Pq ACPI Source Language
+format to be displayed.
+.Pp
+If it encounters one of more accesses to the region such as
+SystemMemory in executing the Control Methods, its ACPI Virtual
+Machine simulates the input/output operations to the resources in the
+region.  In writing to a certain region, the ACPI Virtual Machine
+prepares a piece of memory corresponding to its address,
+if necessary, and holds the specified value in the memory as the
+.Em region contents .
+In reading from a certain region, it fetches the value in the memory
+.Pq Em region contents ,
+prompts with it as the following:
+.Bd -literal -offset indent
+DEBUG[read(0, 0x100b6813)&mask:0x1](default: 0x1 / 1) >>
+.Ed
+.Pp
+for users to have the opportunity to modify it, and hands it to
+the AML interpreter.  In case that there is no corresponding region
+in the AML Virtual Machine, the value zero is handed.
+.Pp
+The interpreter continues to maintain all of the
+.Em region contents
+until
+.Nm
+terminates.  You can specify their initial values with the file
+.Pa region.ini
+in the current directory.  If it is executed with
+.Fl d
+option, it dumps the final status of all of its
+.Em region contents
+to the file
+.Pa region.dmp
+when it terminates.  Each line of there files consists of the following
+fields, separated by tabs; region type, address, and value.
+Region types are specified as follows;
+.TS H
+box;
+c | l.
+value	region type
+=
+0	SystemMemory	
+1	SystemIO
+2	PCI_Concig
+3	EmbeddedControl
+4	SMBus
+.TE
+.Pp
+Interactive commands are described below:
+.Bl -tag -width indent
+.It Cm s
+.Em Single step: 
+Performs single-step execution of the current Control Method.  If
+the next instruction is an invocation of another Control Method,
+the step execution will continue in the following Control Method.
+.It Cm n
+.Em Step program:
+Performs single-step execution of the current Control Method.
+Even if the next instruction is an invocation of another Control
+Method, the step execution will not continue.
+.It Cm c
+.Em Continue program being debugged:
+Resumes execution of the AML interpreter.  Because the current
+.Nm
+has no way of breakpoint, this command might not so much useful.
+.It Cm q
+.Em Quit method execution:
+Terminates execution of the current Control Method.  If
+.Nm
+is not in execution, this command causes to input the next
+DSDT data file.  If there are no next DSDT data files, it
+terminates
+.Nm
+itself.
+.It Cm t
+.Em Show local name space tree and variables:
+Displays the structure of the ACPI namespace tree.  If
+.Nm
+is in execution, this command displays the structure that relates
+to the objects, arguments, and local variables below the scope of the
+current Control Method.
+.It Cm i
+.Em Toggle region input prompt:
+Switches whether the prompt for modifying the value read from the
+.Em region contents
+be showed or not.  Default is On.
+.It Cm o
+.Em Toggle region output prompt:
+Switches whether the prompt for modifying the value to be written
+to the region contents will be shown or not.  The default is Off.
+.It Cm m
+.Em Show memory management statistics:
+Displays the current statistics of the memory management system
+on the AML interpreter.
+.It Cm r Ar method
+.Em Run specified method:
+Executes the specified Control Method.  If it requires one or
+more arguments, a prompt such as the following appears;
+.Bd -literal
+Method: Arg 1 From 0x280626ce To 0x28062775
+  Enter argument values (ex. number 1 / string foo). 'q' to quit.
+  Arg0 ? 
+.Ed
+.Pp
+For each argument, a pair of type string and value delimited by
+one or more spaces can be entered.  Now only
+.Ic number
+and
+.Ic string
+can be specified as the type string.
+In the current implementation, only the first character of the type
+string, such as
+.Ic n
+or
+.Ic s ,
+is identified.  For example, we can enter as follows:
+.Bd -literal
+  Arg0 ? n 1
+.Ed
+.Pp
+.It Cm f Ar string
+.Em Find named objects from namespace:
+Lists the named objects that includes the specified string as the
+terminate elements searching from the ACPI namespace.  For the
+namespace is expressed as the sequence of four-character elements,
+appropriate number of additional underscore
+.Pq Sq _
+characters are necessary for specifying objects which have less than four
+character string.  Unless additional underscores specified, matching
+occurs as the beginning of word with the specified number of characters.
+.It Cm h
+.Em Show help messsage:
+Displays the command summary of
+.Nm amldb .
+.El
+.Pp
+.Sh OPTIONS
+Exactly one of the following options must be specified.  Otherwise,
+.Nm amldb
+shows its usage and terminates.
+.Bl -tag -width indent
+.It Fl d
+Dump the final status of all of the
+.Em region contents
+in the ACPI Virtual Machine to the file
+.Pa region.dmp .
+.It Fl h
+Terminate with the usage of this command.
+.It Fl s
+Display the statistics of the memory management system on the
+AML interpreter when
+.Nm
+terminates.
+.It Fl t
+Display the tree structure of ACPI namespace after the
+DSDT data file is read.
+.El
+.Sh EXAMPLES
+The following is an example including, invoking the
+.Nm amldb ,
+searching
+.Li _PRS
+.Pq Possible Resource Settings
+objects, and executing the
+.Li _PTS
+.Pq Prepare To Sleep
+Control Method by the AML interpreter.
+.Bd -literal -offset indent
+% amldb p2b.dsdt.dat
+Loading p2b.dsdt.dat...done
+AML>f _PRS
+\\_SB_.PCI0.ISA_.PS2M._PRS.
+\\_SB_.PCI0.ISA_.IRDA._PRS.
+\\_SB_.PCI0.ISA_.UAR2._PRS.
+\\_SB_.PCI0.ISA_.UAR1._PRS.
+\\_SB_.PCI0.ISA_.ECP_._PRS.
+\\_SB_.PCI0.ISA_.LPT_._PRS.
+\\_SB_.PCI0.ISA_.FDC0._PRS.
+\\_SB_.LNKD._PRS.
+\\_SB_.LNKC._PRS.
+\\_SB_.LNKB._PRS.
+\\_SB_.LNKA._PRS.
+AML>r _PTS
+Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
+  Enter argument values (ex. number 1 / string foo). 'q' to quit.
+  Arg0 ? n 5
+==== Running _PTS. ====
+AML>s
+[\_PTS. START]
+If(LNot(LEqual(Arg0, 0x5)))
+AML>
+If(LEqual(Arg0, 0x1))
+AML>
+If(LEqual(Arg0, 0x2))
+AML>
+Store(One, TO12)
+[aml_region_write(1, 1, 0x1, 0xe42c, 0x18, 0x1)]
+amldb: region.ini: No such file or directory
+        [1:0x00@0xe42f]->[1:0x01@0xe42f]
+[write(1, 0x1, 0xe42f)]
+[aml_region_read(1, 1, 0xe42c, 0x18, 0x1)]
+        [1:0x01@0xe42f]
+DEBUG[read(1, 0xe42f)&mask:0x1](default: 0x1 / 1) >>
+[read(1, 0xe42f)->0x1]
+AML>
+Or(Arg0, 0xf0, Local2)[Copy number 0xf5]
+AML>t
+_PTS  Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
+  Arg0    Num:0x5
+  Local2  Num:0xf5
+AML>s
+Store(Local2, DBG1)
+[aml_region_write(1, 1, 0xf5, 0x80, 0x0, 0x8)]
+        [1:0x00@0x80]->[1:0xf5@0x80]
+[write(1, 0xf5, 0x80)]
+[aml_region_read(1, 1, 0x80, 0x0, 0x8)]
+        [1:0xf5@0x80]
+DEBUG[read(1, 0x80)&mask:0xf5](default: 0xf5 / 245) >>
+[read(1, 0x80)->0xf5]
+AML>
+[\_PTS. END]
+_PTS  Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
+NO object
+==== _PTS finished. ====
+AML>q
+%
+.Ed
+.Pp
+.Sh BUGS
+The ACPI virtual machine does not completely simulate the behavior
+of a machine with an ACPI BIOS.  In the current implementation, the
+ACPI virtual machine only reads or writes the stored values by
+emulating access to regions such as SystemMemory.
+.Pp
+Because the AML interpreter interprets and disassembles
+simultaneously, it is impossible to implement such features as setting
+breakpoints with the specified line number in ASL.  Setting breakpoints
+at certain Control Methods, which is not very difficult, has not
+yet implemented because nobody has ever needed it.
+.Sh FILES
+.Bl -tag -width region.ini -compact
+.It Pa region.ini
+.br
+.It Pa region.dmp
+.El
+.Sh SEE ALSO
+.Xr acpi 4 ,
+.Xr acpiconf 8 ,
+.Xr acpidump 8
+.Pp
+.Sh AUTHORS
+.An Takanori Watanabe Aq takawata@FreeBSD.org
+.An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org
+.An Yasuo YOKOYAMA Aq yokoyama@jp.FreeBSD.org
+.Pp
+Some contributions made by
+.An Chitoshi Ohsawa Aq ohsawa@catv1.ccn-net.ne.jp ,
+.An Takayasu IWANASHI Aq takayasu@wendy.a.perfect-liberty.or.jp ,
+.An Norihiro KUMAGAI Aq kumagai@home.com ,
+.An Kenneth Ingham Aq ingham@I-pi.com ,
+and
+.An Michael Lucas Aq mwlucas@blackhelicopters.org .
+.Sh HISTORY
+The
+.Nm
+command appeared in
+.Fx 5.0 .