usr.sbin/acpi/amldb/amldb.8

   1 .\" ACPI (ACPI Package)
   2 .\"
   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>
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  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.
  16 .\"
  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
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd August 31, 2000
  32 .Dt AMLDB 8
  33 .Os FreeBSD 5.0
  34 .Sh NAME
  35 .Nm amldb
  36 .Nd executing and debugging AML interpreter
  37 .Pq with DSDT files
  38 .Sh SYNOPSIS
  39 .Nm amldb
  40 .Op Fl dhst
  41 .Ar dsdt_file ...
  42 .Sh DESCRIPTION
  43 .Nm Amldb
  44 parses the DSDT
  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.
  50 .Nm Amldb
  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.
  59 .Pp
  60 The developer will need to acquire a DSDT data file from any machine
  61 with ACPI BIOS through
  62 .Xr acpidump 8 .
  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.
  69 .Pp
  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
  73 recognizes into ASL
  74 .Pq ACPI Source Language
  75 format to be displayed.
  76 .Pp
  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
  83 .Em region contents .
  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) >>
  89 .Ed
  90 .Pp
  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.
  94 .Pp
  95 The interpreter continues to maintain all of the
  96 .Em region contents
  97 until
  98 .Nm
  99 terminates.  You can specify their initial values with the file
 100 .Pa region.ini
 101 in the current directory.  If it is executed with
 102 .Fl d
 103 option, it dumps the final status of all of its
 104 .Em region contents
 105 to the file
 106 .Pa region.dmp
 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;
 110 .TS H
 111 box;
 112 c | l.
 113 value   region type
 114 =
 115 0       SystemMemory
 116 1       SystemIO
 117 2       PCI_Concig
 118 3       EmbeddedControl
 119 4       SMBus
 120 .TE
 121 .Pp
 122 Interactive commands are described below:
 123 .Bl -tag -width indent
 124 .It Cm s
 125 .Em Single step:
 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.
 129 .It Cm n
 130 .Em Step program:
 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.
 134 .It Cm c
 135 .Em Continue program being debugged:
 136 Resumes execution of the AML interpreter.  Because the current
 137 .Nm
 138 has no way of breakpoint, this command might not so much useful.
 139 .It Cm q
 140 .Em Quit method execution:
 141 Terminates execution of the current Control Method.  If
 142 .Nm
 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
 145 terminates
 146 .Nm
 147 itself.
 148 .It Cm t
 149 .Em Show local name space tree and variables:
 150 Displays the structure of the ACPI namespace tree.  If
 151 .Nm
 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.
 155 .It Cm i
 156 .Em Toggle region input prompt:
 157 Switches whether the prompt for modifying the value read from the
 158 .Em region contents
 159 be showed or not.  Default is On.
 160 .It Cm o
 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.
 164 .It Cm m
 165 .Em Show memory management statistics:
 166 Displays the current statistics of the memory management system
 167 on the AML interpreter.
 168 .It Cm r Ar method
 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;
 172 .Bd -literal
 173 Method: Arg 1 From 0x280626ce To 0x28062775
 174   Enter argument values (ex. number 1 / string foo). 'q' to quit.
 175   Arg0 ?
 176 .Ed
 177 .Pp
 178 For each argument, a pair of type string and value delimited by
 179 one or more spaces can be entered.  Now only
 180 .Ic number
 181 and
 182 .Ic string
 183 can be specified as the type string.
 184 In the current implementation, only the first character of the type
 185 string, such as
 186 .Ic n
 187 or
 188 .Ic s ,
 189 is identified.  For example, we can enter as follows:
 190 .Bd -literal
 191   Arg0 ? n 1
 192 .Ed
 193 .Pp
 194 .It Cm f Ar string
 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
 200 .Pq Sq _
 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.
 204 .It Cm h
 205 .Em Show help messsage:
 206 Displays the command summary of
 207 .Nm amldb .
 208 .El
 209 .Pp
 210 .Sh OPTIONS
 211 Exactly one of the following options must be specified.  Otherwise,
 212 .Nm amldb
 213 shows its usage and terminates.
 214 .Bl -tag -width indent
 215 .It Fl d
 216 Dump the final status of all of the
 217 .Em region contents
 218 in the ACPI Virtual Machine to the file
 219 .Pa region.dmp .
 220 .It Fl h
 221 Terminate with the usage of this command.
 222 .It Fl s
 223 Display the statistics of the memory management system on the
 224 AML interpreter when
 225 .Nm
 226 terminates.
 227 .It Fl t
 228 Display the tree structure of ACPI namespace after the
 229 DSDT data file is read.
 230 .El
 231 .Sh EXAMPLES
 232 The following is an example including, invoking the
 233 .Nm amldb ,
 234 searching
 235 .Li _PRS
 236 .Pq Possible Resource Settings
 237 objects, and executing the
 238 .Li _PTS
 239 .Pq Prepare To Sleep
 240 Control Method by the AML interpreter.
 241 .Bd -literal -offset indent
 242 % amldb p2b.dsdt.dat
 243 Loading p2b.dsdt.dat...done
 244 AML>f _PRS
 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.
 252 \\_SB_.LNKD._PRS.
 253 \\_SB_.LNKC._PRS.
 254 \\_SB_.LNKB._PRS.
 255 \\_SB_.LNKA._PRS.
 256 AML>r _PTS
 257 Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
 258   Enter argument values (ex. number 1 / string foo). 'q' to quit.
 259   Arg0 ? n 5
 260 ==== Running _PTS. ====
 261 AML>s
 262 [\_PTS. START]
 263 If(LNot(LEqual(Arg0, 0x5)))
 264 AML>
 265 If(LEqual(Arg0, 0x1))
 266 AML>
 267 If(LEqual(Arg0, 0x2))
 268 AML>
 269 Store(One, TO12)
 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)]
 275         [1:0x01@0xe42f]
 276 DEBUG[read(1, 0xe42f)&mask:0x1](default: 0x1 / 1) >>
 277 [read(1, 0xe42f)->0x1]
 278 AML>
 279 Or(Arg0, 0xf0, Local2)[Copy number 0xf5]
 280 AML>t
 281 _PTS  Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
 282   Arg0    Num:0x5
 283   Local2  Num:0xf5
 284 AML>s
 285 Store(Local2, DBG1)
 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)]
 290         [1:0xf5@0x80]
 291 DEBUG[read(1, 0x80)&mask:0xf5](default: 0xf5 / 245) >>
 292 [read(1, 0x80)->0xf5]
 293 AML>
 294 [\_PTS. END]
 295 _PTS  Method: Arg 1 From 0x2805f0a3 To 0x2805f0db
 296 NO object
 297 ==== _PTS finished. ====
 298 AML>q
 299 %
 300 .Ed
 301 .Pp
 302 .Sh BUGS
 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.
 307 .Pp
 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.
 313 .Sh FILES
 314 .Bl -tag -width region.ini -compact
 315 .It Pa region.ini
 316 .br
 317 .It Pa region.dmp
 318 .El
 319 .Sh SEE ALSO
 320 .Xr acpi 4 ,
 321 .Xr acpiconf 8 ,
 322 .Xr acpidump 8
 323 .Pp
 324 .Sh AUTHORS
 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
 328 .Pp
 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 ,
 334 and
 335 .An Michael Lucas Aq mwlucas@blackhelicopters.org .
 336 .Sh HISTORY
 337 The
 338 .Nm
 339 command appeared in
 340 .Fx 5.0 .