1.\" $NetBSD: amldb.8,v 1.4 2009/11/02 00:35:32 joerg 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.Bl -tag -width "Value" -compact -offset indent 123.It Sy Value 124.Sy Region type 125.It 0 126SystemMemory 127.It 1 128SystemIO 129.It 2 130PCI_Config 131.It 3 132EmbeddedControl 133.It 4 134SMBus 135.El 136.Pp 137Interactive commands are described below: 138.Bl -tag -width indent 139.It Cm s 140.Em Single step : 141Performs single-step execution of the current Control Method. 142If the next instruction is an invocation of another Control Method, 143the step execution will continue in the following Control Method. 144.It Cm n 145.Em Step program : 146Performs single-step execution of the current Control Method. 147Even if the next instruction is an invocation of another Control 148Method, the step execution will not continue. 149.It Cm c 150.Em Continue program being debugged : 151Resumes execution of the AML interpreter. 152Because the current 153.Nm 154has no way of breakpoint, this command might not so much useful. 155.It Cm q 156.Em Quit method execution : 157Terminates execution of the current Control Method. 158If 159.Nm 160is not in execution, this command causes to input the next 161DSDT data file. 162If there are no next DSDT data files, it terminates 163.Nm 164itself. 165.It Cm t 166.Em Show local name space tree and variables : 167Displays the structure of the ACPI namespace tree. 168If 169.Nm 170is in execution, this command displays the structure that relates 171to the objects, arguments, and local variables below the scope of the 172current Control Method. 173.It Cm i 174.Em Toggle region input prompt : 175Switches whether the prompt for modifying the value read from the 176.Em region contents 177be showed or not. 178Default is On. 179.It Cm o 180.Em Toggle region output prompt : 181Switches whether the prompt for modifying the value to be written 182to the region contents will be shown or not. 183The default is Off. 184.It Cm m 185.Em Show memory management statistics : 186Displays the current statistics of the memory management system 187on the AML interpreter. 188.It Cm r Ar method 189.Em Run specified method : 190Executes the specified Control Method. 191If it requires one or 192more arguments, a prompt such as the following appears; 193.Bd -literal 194Method: Arg 1 From 0x280626ce To 0x28062775 195 Enter argument values (ex. number 1 / string foo). 'q' to quit. 196 Arg0 ? 197.Ed 198.Pp 199For each argument, a pair of type string and value delimited by 200one or more spaces can be entered. 201Now only 202.Ic number 203and 204.Ic string 205can be specified as the type string. 206In the current implementation, only the first character of the type 207string, such as 208.Ic n 209or 210.Ic s , 211is identified. 212For example, we can enter as follows: 213.Bd -literal 214 Arg0 ? n 1 215.Ed 216.Pp 217.It Cm f Ar string 218.Em Find named objects from namespace : 219Lists the named objects that includes the specified string as the 220terminate elements searching from the ACPI namespace. 221For the namespace is expressed as the sequence of four-character 222elements, appropriate number of additional underscore 223.Pq Ql _ 224characters are necessary for specifying objects which have less than four 225character string. 226Unless additional underscores specified, matching 227occurs as the beginning of word with the specified number of characters. 228.It Cm h 229.Em Show help messsage : 230Displays the command summary of 231.Nm . 232.El 233.Sh OPTIONS 234Exactly one of the following options must be specified. 235Otherwise, 236.Nm 237shows its usage and terminates. 238.Bl -tag -width indent 239.It Fl d 240Dump the final status of all of the 241.Em region contents 242in the ACPI Virtual Machine to the file 243.Pa region.dmp . 244.It Fl h 245Terminate with the usage of this command. 246.It Fl s 247Display the statistics of the memory management system on the 248AML interpreter when 249.Nm 250terminates. 251.It Fl t 252Display the tree structure of ACPI namespace after the 253DSDT data file is read. 254.El 255.Sh FILES 256.Bl -tag -width region.ini -compact 257.It Pa region.ini 258.It Pa region.dmp 259.El 260.Sh EXAMPLES 261The following is an example including, invoking the 262.Nm , 263searching 264.Li _PRS 265(Possible Resource Settings) 266objects, and executing the 267.Li _PTS 268(Prepare To Sleep) 269Control Method by the AML interpreter. 270.Bd -literal -offset indent 271% amldb p2b.dsdt.dat 272Loading p2b.dsdt.dat...done 273AML\*[Gt]f _PRS 274\\_SB_.PCI0.ISA_.PS2M._PRS. 275\\_SB_.PCI0.ISA_.IRDA._PRS. 276\\_SB_.PCI0.ISA_.UAR2._PRS. 277\\_SB_.PCI0.ISA_.UAR1._PRS. 278\\_SB_.PCI0.ISA_.ECP_._PRS. 279\\_SB_.PCI0.ISA_.LPT_._PRS. 280\\_SB_.PCI0.ISA_.FDC0._PRS. 281\\_SB_.LNKD._PRS. 282\\_SB_.LNKC._PRS. 283\\_SB_.LNKB._PRS. 284\\_SB_.LNKA._PRS. 285AML\*[Gt]r _PTS 286Method: Arg 1 From 0x2805f0a3 To 0x2805f0db 287 Enter argument values (ex. number 1 / string foo). 'q' to quit. 288 Arg0 ? n 5 289==== Running _PTS. ==== 290AML\*[Gt]s 291[\\_PTS. START] 292If(LNot(LEqual(Arg0, 0x5))) 293AML\*[Gt] 294If(LEqual(Arg0, 0x1)) 295AML\*[Gt] 296If(LEqual(Arg0, 0x2)) 297AML\*[Gt] 298Store(One, TO12) 299[aml_region_write(1, 1, 0x1, 0xe42c, 0x18, 0x1)] 300amldb: region.ini: No such file or directory 301 [1:0x00@0xe42f]-\*[Gt][1:0x01@0xe42f] 302[write(1, 0x1, 0xe42f)] 303[aml_region_read(1, 1, 0xe42c, 0x18, 0x1)] 304 [1:0x01@0xe42f] 305DEBUG[read(1, 0xe42f)\*[Am]mask:0x1](default: 0x1 / 1) \*[Gt]\*[Gt] 306[read(1, 0xe42f)-\*[Gt]0x1] 307AML\*[Gt] 308Or(Arg0, 0xf0, Local2)[Copy number 0xf5] 309AML\*[Gt]t 310_PTS Method: Arg 1 From 0x2805f0a3 To 0x2805f0db 311 Arg0 Num:0x5 312 Local2 Num:0xf5 313AML\*[Gt]s 314Store(Local2, DBG1) 315[aml_region_write(1, 1, 0xf5, 0x80, 0x0, 0x8)] 316 [1:0x00@0x80]-\*[Gt][1:0xf5@0x80] 317[write(1, 0xf5, 0x80)] 318[aml_region_read(1, 1, 0x80, 0x0, 0x8)] 319 [1:0xf5@0x80] 320DEBUG[read(1, 0x80)\*[Am]mask:0xf5](default: 0xf5 / 245) \*[Gt]\*[Gt] 321[read(1, 0x80)-\*[Gt]0xf5] 322AML\*[Gt] 323[\\_PTS. END] 324_PTS Method: Arg 1 From 0x2805f0a3 To 0x2805f0db 325NO object 326==== _PTS finished. ==== 327AML\*[Gt]q 328% 329.Ed 330.Sh SEE ALSO 331.Xr acpi 4 , 332.\" .Xr acpiconf 8 , 333.Xr acpidump 8 334.Sh HISTORY 335The 336.Nm 337utility appeared in 338.Fx 5.0 . 339.Sh AUTHORS 340.An Takanori Watanabe Aq takawata@FreeBSD.org 341.An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org 342.An Yasuo YOKOYAMA Aq yokoyama@jp.FreeBSD.org 343.Pp 344Some contributions made by 345.An Chitoshi Ohsawa Aq ohsawa@catv1.ccn-net.ne.jp , 346.An Takayasu IWANASHI Aq takayasu@wendy.a.perfect-liberty.or.jp , 347.An Norihiro KUMAGAI Aq kumagai@home.com , 348.An Kenneth Ingham Aq ingham@I-pi.com , 349and 350.An Michael Lucas Aq mwlucas@blackhelicopters.org . 351.Sh BUGS 352The ACPI virtual machine does not completely simulate the behavior 353of a machine with an ACPI BIOS. 354In the current implementation, the 355ACPI virtual machine only reads or writes the stored values by 356emulating access to regions such as SystemMemory. 357.Pp 358Because the AML interpreter interprets and disassembles 359simultaneously, it is impossible to implement such features as setting 360breakpoints with the specified line number in ASL. 361Setting breakpoints 362at certain Control Methods, which is not very difficult, has not 363yet implemented because nobody has ever needed it. 364