From 5bb6e489c0ab09d343ec5ad57a5aa96d9974a6f6 Mon Sep 17 00:00:00 2001 From: iwasaki Date: Thu, 14 Sep 2000 22:48:39 +0000 Subject: Add manpages acpi userland tools. Obtained from: ACPI for FreeBSD project --- usr.sbin/acpi/acpidump/Makefile | 3 +- usr.sbin/acpi/acpidump/acpidump.8 | 174 +++++++++++++++++++ usr.sbin/acpi/amldb/Makefile | 3 +- usr.sbin/acpi/amldb/amldb.8 | 340 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 516 insertions(+), 4 deletions(-) create mode 100644 usr.sbin/acpi/acpidump/acpidump.8 create mode 100644 usr.sbin/acpi/amldb/amldb.8 (limited to 'usr.sbin/acpi') 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 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 +.\" Copyright (c) 2000 Mitsuru IWASAKI +.\" Copyright (c) 2000 Yasuo YOKOYAMA +.\" Copyright (c) 2000 Hiroki Sato +.\" 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 + +.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 +.\" Copyright (c) 2000 Mitsuru IWASAKI +.\" Copyright (c) 2000 Yasuo YOKOYAMA +.\" Copyright (c) 2000 Norihiro KUMAGAI +.\" +.\" 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 . -- cgit v1.1