1.\" $NetBSD: amldb.8,v 1.2 2007/01/14 12:30:24 wiz Exp $ 2.\" ACPI (ACPI Package) 3.\" 4.\" Copyright (c) 2000 Takanori Watanabe <takawata@FreeBSD.org> 5.\" Copyright (c) 2000 Mitsuru IWASAKI <iwasaki@FreeBSD.org> 6.\" Copyright (c) 2000 Yasuo YOKOYAMA <yokoyama@jp.FreeBSD.org> 7.\" Copyright (c) 2000 Norihiro KUMAGAI <kumagai@home.com> 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD: src/usr.sbin/acpi/amldb/amldb.8,v 1.10 2002/08/13 16:07:26 ru Exp $ 31.\" 32.Dd August 31, 2000 33.Dt AMLDB 8 34.Os 35.Sh NAME 36.Nm amldb 37.Nd executing and debugging AML interpreter 38(with DSDT files) 39.Sh SYNOPSIS 40.Nm 41.Op Fl dhst 42.Ar dsdt_file ... 43.Sh DESCRIPTION 44The 45.Nm 46utility parses the DSDT 47(Differentiated System Description Table) 48files, which usually are acquired from ACPI BIOS, and executes 49the sequence of ACPI Control Methods described in AML 50(ACPI Machine Language) 51with its AML interpreter. 52The 53.Nm 54utility also has a simple ACPI virtual machine. 55During execution of the 56Control Methods each access to the region, such as 57SystemMemory, SystemIO, PCI_Config, does not affect the real 58hardware but only the virtual machine. 59Because the sequence of virtual accesses is maintained in user space, 60AML interpreter developers need not worry about any effect on hardware 61when they analyze DSDT data files. 62They can develop and debug the 63interpreter, even if the machine has no ACPI BIOS. 64.Pp 65The developer will need to acquire a DSDT data file from any machine 66with ACPI BIOS through 67.Xr acpidump 8 . 68The DSDT is a table, a part of the whole ACPI memory table 69located in somewhere in the BIOS area 70.Pq Li 0xa0000 \- 0x100000 . 71It includes such information as the detailed hardware information 72for PnP, and the set of procedures which perform power management from 73the OS. 74The information is stored in AML format. 75.Pp 76The AML interpreter can execute any of the Control Methods specified 77by users. 78When executed, it interprets the byte sequence in the 79Control Method of DSDT, and disassembles the opcodes that it 80recognizes into ASL 81(ACPI Source Language) 82format to be displayed. 83.Pp 84If it encounters one of more accesses to the region such as 85SystemMemory in executing the Control Methods, its ACPI Virtual 86Machine simulates the input/output operations to the resources in the 87region. 88In writing to a certain region, the ACPI Virtual Machine 89prepares a piece of memory corresponding to its address, 90if necessary, and holds the specified value in the memory as the 91.Em region contents . 92In reading from a certain region, it fetches the value in the memory 93.Pq Em region contents , 94prompts with it as the following: 95.Bd -literal -offset indent 96DEBUG[read(0, 0x100b6813)\*[Am]mask:0x1](default: 0x1 / 1) \*[Gt]\*[Gt] 97.Ed 98.Pp 99for users to have the opportunity to modify it, and hands it to 100the AML interpreter. 101In case that there is no corresponding region 102in the AML Virtual Machine, the value zero is handed. 103.Pp 104The interpreter continues to maintain all of the 105.Em region contents 106until 107.Nm 108terminates. 109You can specify their initial values with the file 110.Pa region.ini 111in the current directory. 112If it is executed with 113.Fl d 114option, it dumps the final status of all of its 115.Em region contents 116to the file 117.Pa region.dmp 118when it terminates. 119Each line of there files consists of the following 120fields, separated by tabs; region type, address, and value. 121Region types are specified as follows; 122.TS H 123box; 124c | l. 125value region type 126= 1270 SystemMemory 1281 SystemIO 1292 PCI_Concig 1303 EmbeddedControl 1314 SMBus 132.TE 133.Pp 134Interactive commands are described below: 135.Bl -tag -width indent 136.It Cm s 137.Em Single step : 138Performs single-step execution of the current Control Method. 139If the next instruction is an invocation of another Control Method, 140the step execution will continue in the following Control Method. 141.It Cm n 142.Em Step program : 143Performs single-step execution of the current Control Method. 144Even if the next instruction is an invocation of another Control 145Method, the step execution will not continue. 146.It Cm c 147.Em Continue program being debugged : 148Resumes execution of the AML interpreter. 149Because the current 150.Nm 151has no way of breakpoint, this command might not so much useful. 152.It Cm q 153.Em Quit method execution : 154Terminates execution of the current Control Method. 155If 156.Nm 157is not in execution, this command causes to input the next 158DSDT data file. 159If there are no next DSDT data files, it terminates 160.Nm 161itself. 162.It Cm t 163.Em Show local name space tree and variables : 164Displays the structure of the ACPI namespace tree. 165If 166.Nm 167is in execution, this command displays the structure that relates 168to the objects, arguments, and local variables below the scope of the 169current Control Method. 170.It Cm i 171.Em Toggle region input prompt : 172Switches whether the prompt for modifying the value read from the 173.Em region contents 174be showed or not. 175Default is On. 176.It Cm o 177.Em Toggle region output prompt : 178Switches whether the prompt for modifying the value to be written 179to the region contents will be shown or not. 180The default is Off. 181.It Cm m 182.Em Show memory management statistics : 183Displays the current statistics of the memory management system 184on the AML interpreter. 185.It Cm r Ar method 186.Em Run specified method : 187Executes the specified Control Method. 188If it requires one or 189more arguments, a prompt such as the following appears; 190.Bd -literal 191Method: Arg 1 From 0x280626ce To 0x28062775 192 Enter argument values (ex. number 1 / string foo). 'q' to quit. 193 Arg0 ? 194.Ed 195.Pp 196For each argument, a pair of type string and value delimited by 197one or more spaces can be entered. 198Now only 199.Ic number 200and 201.Ic string 202can be specified as the type string. 203In the current implementation, only the first character of the type 204string, such as 205.Ic n 206or 207.Ic s , 208is identified. 209For example, we can enter as follows: 210.Bd -literal 211 Arg0 ? n 1 212.Ed 213.Pp 214.It Cm f Ar string 215.Em Find named objects from namespace : 216Lists the named objects that includes the specified string as the 217terminate elements searching from the ACPI namespace. 218For the namespace is expressed as the sequence of four-character 219elements, appropriate number of additional underscore 220.Pq Ql _ 221characters are necessary for specifying objects which have less than four 222character string. 223Unless additional underscores specified, matching 224occurs as the beginning of word with the specified number of characters. 225.It Cm h 226.Em Show help messsage : 227Displays the command summary of 228.Nm . 229.El 230.Sh OPTIONS 231Exactly one of the following options must be specified. 232Otherwise, 233.Nm 234shows its usage and terminates. 235.Bl -tag -width indent 236.It Fl d 237Dump the final status of all of the 238.Em region contents 239in the ACPI Virtual Machine to the file 240.Pa region.dmp . 241.It Fl h 242Terminate with the usage of this command. 243.It Fl s 244Display the statistics of the memory management system on the 245AML interpreter when 246.Nm 247terminates. 248.It Fl t 249Display the tree structure of ACPI namespace after the 250DSDT data file is read. 251.El 252.Sh FILES 253.Bl -tag -width region.ini -compact 254.It Pa region.ini 255.It Pa region.dmp 256.El 257.Sh EXAMPLES 258The following is an example including, invoking the 259.Nm , 260searching 261.Li _PRS 262(Possible Resource Settings) 263objects, and executing the 264.Li _PTS 265(Prepare To Sleep) 266Control Method by the AML interpreter. 267.Bd -literal -offset indent 268% amldb p2b.dsdt.dat 269Loading p2b.dsdt.dat...done 270AML\*[Gt]f _PRS 271\\_SB_.PCI0.ISA_.PS2M._PRS. 272\\_SB_.PCI0.ISA_.IRDA._PRS. 273\\_SB_.PCI0.ISA_.UAR2._PRS. 274\\_SB_.PCI0.ISA_.UAR1._PRS. 275\\_SB_.PCI0.ISA_.ECP_._PRS. 276\\_SB_.PCI0.ISA_.LPT_._PRS. 277\\_SB_.PCI0.ISA_.FDC0._PRS. 278\\_SB_.LNKD._PRS. 279\\_SB_.LNKC._PRS. 280\\_SB_.LNKB._PRS. 281\\_SB_.LNKA._PRS. 282AML\*[Gt]r _PTS 283Method: Arg 1 From 0x2805f0a3 To 0x2805f0db 284 Enter argument values (ex. number 1 / string foo). 'q' to quit. 285 Arg0 ? n 5 286==== Running _PTS. ==== 287AML\*[Gt]s 288[\_PTS. START] 289If(LNot(LEqual(Arg0, 0x5))) 290AML\*[Gt] 291If(LEqual(Arg0, 0x1)) 292AML\*[Gt] 293If(LEqual(Arg0, 0x2)) 294AML\*[Gt] 295Store(One, TO12) 296[aml_region_write(1, 1, 0x1, 0xe42c, 0x18, 0x1)] 297amldb: region.ini: No such file or directory 298 [1:0x00@0xe42f]-\*[Gt][1:0x01@0xe42f] 299[write(1, 0x1, 0xe42f)] 300[aml_region_read(1, 1, 0xe42c, 0x18, 0x1)] 301 [1:0x01@0xe42f] 302DEBUG[read(1, 0xe42f)\*[Am]mask:0x1](default: 0x1 / 1) \*[Gt]\*[Gt] 303[read(1, 0xe42f)-\*[Gt]0x1] 304AML\*[Gt] 305Or(Arg0, 0xf0, Local2)[Copy number 0xf5] 306AML\*[Gt]t 307_PTS Method: Arg 1 From 0x2805f0a3 To 0x2805f0db 308 Arg0 Num:0x5 309 Local2 Num:0xf5 310AML\*[Gt]s 311Store(Local2, DBG1) 312[aml_region_write(1, 1, 0xf5, 0x80, 0x0, 0x8)] 313 [1:0x00@0x80]-\*[Gt][1:0xf5@0x80] 314[write(1, 0xf5, 0x80)] 315[aml_region_read(1, 1, 0x80, 0x0, 0x8)] 316 [1:0xf5@0x80] 317DEBUG[read(1, 0x80)\*[Am]mask:0xf5](default: 0xf5 / 245) \*[Gt]\*[Gt] 318[read(1, 0x80)-\*[Gt]0xf5] 319AML\*[Gt] 320[\_PTS. END] 321_PTS Method: Arg 1 From 0x2805f0a3 To 0x2805f0db 322NO object 323==== _PTS finished. ==== 324AML\*[Gt]q 325% 326.Ed 327.Sh SEE ALSO 328.Xr acpi 4 , 329.\" .Xr acpiconf 8 , 330.Xr acpidump 8 331.Sh HISTORY 332The 333.Nm 334utility appeared in 335.Fx 5.0 . 336.Sh AUTHORS 337.An Takanori Watanabe Aq takawata@FreeBSD.org 338.An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org 339.An Yasuo YOKOYAMA Aq yokoyama@jp.FreeBSD.org 340.Pp 341Some contributions made by 342.An Chitoshi Ohsawa Aq ohsawa@catv1.ccn-net.ne.jp , 343.An Takayasu IWANASHI Aq takayasu@wendy.a.perfect-liberty.or.jp , 344.An Norihiro KUMAGAI Aq kumagai@home.com , 345.An Kenneth Ingham Aq ingham@I-pi.com , 346and 347.An Michael Lucas Aq mwlucas@blackhelicopters.org . 348.Sh BUGS 349The ACPI virtual machine does not completely simulate the behavior 350of a machine with an ACPI BIOS. 351In the current implementation, the 352ACPI virtual machine only reads or writes the stored values by 353emulating access to regions such as SystemMemory. 354.Pp 355Because the AML interpreter interprets and disassembles 356simultaneously, it is impossible to implement such features as setting 357breakpoints with the specified line number in ASL. 358Setting breakpoints 359at certain Control Methods, which is not very difficult, has not 360yet implemented because nobody has ever needed it. 361