1 .\" ACPI (ACPI Package)
3 .\" Copyright (c) 2000 Takanori Watanabe <takawata@FreeBSD.org>
4 .\" Copyright (c) 2000 Mitsuru IWASAKI <iwasaki@FreeBSD.org>
5 .\" Copyright (c) 2000 Yasuo YOKOYAMA <yokoyama@jp.FreeBSD.org>
6 .\" Copyright (c) 2000 Norihiro KUMAGAI <kumagai@home.com>
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nd executing and debugging AML interpreter
45 .Pq Differentiated System Description Table
46 files, which usually are acquired from ACPI BIOS, and executes
47 the sequence of ACPI Control Methods described in AML
48 .Pq ACPI Machine Language
49 with its AML interpreter.
51 also has a simple ACPI virtual machine. During execution of the
52 Control Methods each access to the region, such as
53 SystemMemory, SystemIO, PCI_Config, does not affect the real
54 hardware but only the virtual machine.
55 Because the sequence of virtual accesses is maintained in user space,
56 AML interpreter developers need not worry about any effect on hardware
57 when they analyze DSDT data files. They can develop and debug the
58 interpreter, even if the machine has no ACPI BIOS.
60 The developer will need to acquire a DSDT data file from any machine
61 with ACPI BIOS through
63 The DSDT is a table, a part of the whole ACPI memory table
64 located in somewhere in the BIOS area
65 .Pq 0xa0000 \- 0x100000 .
66 It includes such information as the detailed hardware information
67 for PnP, and the set of procedures which perform power management from
68 the OS. The information is stored in AML format.
70 The AML interpreter can execute any of the Control Methods specified
71 by users. When executed, it interprets the byte sequence in the
72 Control Method of DSDT, and disassembles the opecodes that it
74 .Pq ACPI Source Language
75 format to be displayed.
77 If it encounters one of more accesses to the region such as
78 SystemMemory in executing the Control Methods, its ACPI Virtual
79 Machine simulates the input/output operations to the resources in the
80 region. In writing to a certain region, the ACPI Virtual Machine
81 prepares a piece of memory corresponding to its address,
82 if necessary, and holds the specified value in the memory as the
84 In reading from a certain region, it fetches the value in the memory
85 .Pq Em region contents ,
86 prompts with it as the following:
87 .Bd -literal -offset indent
88 DEBUG[read(0, 0x100b6813)&mask:0x1](default: 0x1 / 1) >>
91 for users to have the opportunity to modify it, and hands it to
92 the AML interpreter. In case that there is no corresponding region
93 in the AML Virtual Machine, the value zero is handed.
95 The interpreter continues to maintain all of the
99 terminates. You can specify their initial values with the file
101 in the current directory. If it is executed with
103 option, it dumps the final status of all of its
107 when it terminates. Each line of there files consists of the following
108 fields, separated by tabs; region type, address, and value.
109 Region types are specified as follows;
122 Interactive commands are described below:
123 .Bl -tag -width indent
126 Performs single-step execution of the current Control Method. If
127 the next instruction is an invocation of another Control Method,
128 the step execution will continue in the following Control Method.
131 Performs single-step execution of the current Control Method.
132 Even if the next instruction is an invocation of another Control
133 Method, the step execution will not continue.
135 .Em Continue program being debugged:
136 Resumes execution of the AML interpreter. Because the current
138 has no way of breakpoint, this command might not so much useful.
140 .Em Quit method execution:
141 Terminates execution of the current Control Method. If
143 is not in execution, this command causes to input the next
144 DSDT data file. If there are no next DSDT data files, it
149 .Em Show local name space tree and variables:
150 Displays the structure of the ACPI namespace tree. If
152 is in execution, this command displays the structure that relates
153 to the objects, arguments, and local variables below the scope of the
154 current Control Method.
156 .Em Toggle region input prompt:
157 Switches whether the prompt for modifying the value read from the
159 be showed or not. Default is On.
161 .Em Toggle region output prompt:
162 Switches whether the prompt for modifying the value to be written
163 to the region contents will be shown or not. The default is Off.
165 .Em Show memory management statistics:
166 Displays the current statistics of the memory management system
167 on the AML interpreter.
169 .Em Run specified method:
170 Executes the specified Control Method. If it requires one or
171 more arguments, a prompt such as the following appears;
173 Method: Arg 1 From 0x280626ce To 0x28062775
174 Enter argument values (ex. number 1 / string foo). 'q' to quit.
178 For each argument, a pair of type string and value delimited by
179 one or more spaces can be entered. Now only
183 can be specified as the type string.
184 In the current implementation, only the first character of the type
189 is identified. For example, we can enter as follows:
195 .Em Find named objects from namespace:
196 Lists the named objects that includes the specified string as the
197 terminate elements searching from the ACPI namespace. For the
198 namespace is expressed as the sequence of four-character elements,
199 appropriate number of additional underscore
201 characters are necessary for specifying objects which have less than four
202 character string. Unless additional underscores specified, matching
203 occurs as the beginning of word with the specified number of characters.
205 .Em Show help messsage:
206 Displays the command summary of
211 Exactly one of the following options must be specified. Otherwise,
213 shows its usage and terminates.
214 .Bl -tag -width indent
216 Dump the final status of all of the
218 in the ACPI Virtual Machine to the file
221 Terminate with the usage of this command.
223 Display the statistics of the memory management system on the
228 Display the tree structure of ACPI namespace after the
229 DSDT data file is read.
232 The following is an example including, invoking the
236 .Pq Possible Resource Settings
237 objects, and executing the
240 Control Method by the AML interpreter.
241 .Bd -literal -offset indent
243 Loading p2b.dsdt.dat...done
245 \\_SB_.PCI0.ISA_.PS2M._PRS.
246 \\_SB_.PCI0.ISA_.IRDA._PRS.
247 \\_SB_.PCI0.ISA_.UAR2._PRS.
248 \\_SB_.PCI0.ISA_.UAR1._PRS.
249 \\_SB_.PCI0.ISA_.ECP_._PRS.
250 \\_SB_.PCI0.ISA_.LPT_._PRS.
251 \\_SB_.PCI0.ISA_.FDC0._PRS.
257 Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
258 Enter argument values (ex. number 1 / string foo). 'q' to quit.
260 ==== Running _PTS. ====
263 If(LNot(LEqual(Arg0, 0x5)))
265 If(LEqual(Arg0, 0x1))
267 If(LEqual(Arg0, 0x2))
270 [aml_region_write(1, 1, 0x1, 0xe42c, 0x18, 0x1)]
271 amldb: region.ini: No such file or directory
272 [1:0x00@0xe42f]->[1:0x01@0xe42f]
273 [write(1, 0x1, 0xe42f)]
274 [aml_region_read(1, 1, 0xe42c, 0x18, 0x1)]
276 DEBUG[read(1, 0xe42f)&mask:0x1](default: 0x1 / 1) >>
277 [read(1, 0xe42f)->0x1]
279 Or(Arg0, 0xf0, Local2)[Copy number 0xf5]
281 _PTS Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
286 [aml_region_write(1, 1, 0xf5, 0x80, 0x0, 0x8)]
287 [1:0x00@0x80]->[1:0xf5@0x80]
288 [write(1, 0xf5, 0x80)]
289 [aml_region_read(1, 1, 0x80, 0x0, 0x8)]
291 DEBUG[read(1, 0x80)&mask:0xf5](default: 0xf5 / 245) >>
292 [read(1, 0x80)->0xf5]
295 _PTS Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
297 ==== _PTS finished. ====
303 The ACPI virtual machine does not completely simulate the behavior
304 of a machine with an ACPI BIOS. In the current implementation, the
305 ACPI virtual machine only reads or writes the stored values by
306 emulating access to regions such as SystemMemory.
308 Because the AML interpreter interprets and disassembles
309 simultaneously, it is impossible to implement such features as setting
310 breakpoints with the specified line number in ASL. Setting breakpoints
311 at certain Control Methods, which is not very difficult, has not
312 yet implemented because nobody has ever needed it.
314 .Bl -tag -width region.ini -compact
325 .An Takanori Watanabe Aq takawata@FreeBSD.org
326 .An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org
327 .An Yasuo YOKOYAMA Aq yokoyama@jp.FreeBSD.org
329 Some contributions made by
330 .An Chitoshi Ohsawa Aq ohsawa@catv1.ccn-net.ne.jp ,
331 .An Takayasu IWANASHI Aq takayasu@wendy.a.perfect-liberty.or.jp ,
332 .An Norihiro KUMAGAI Aq kumagai@home.com ,
333 .An Kenneth Ingham Aq ingham@I-pi.com ,
335 .An Michael Lucas Aq mwlucas@blackhelicopters.org .