home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / c / wack.doc < prev    next >
Text File  |  1995-02-27  |  59KB  |  1,802 lines
  1. Wack - The Extensible Amiga Local and Remote Debugger
  2.  
  3. (c) Copyright 1992-1993 Commodore-Amiga, Inc.  All rights reserved.
  4.  
  5. This software is provided as-is and is subject to change; no warranties
  6. are made.  All use is at your own risk.  No liability or responsibility
  7. is assumed.
  8.  
  9. Table of Contents
  10. -----------------
  11.  
  12. 1.  Introduction
  13. 2.  Glossary
  14. 3.  Starting Wack
  15. 4.  Basic Wack Commands
  16. 5.  Wack Command Documentation
  17. 5a. Miscellaneous Commands
  18. 5b. Memory Commands
  19. 5c. Exec and DOS Commands
  20. 5d. Intuition Commands
  21. 5e. Graphics and Layers Commands
  22. 6.  ARexx Commands
  23. 7.  External Wack Commands
  24. 8.  Remote Debugging Via Envoy
  25. 9.  Remote Debugging Via SAD
  26. 10. Description of Files
  27.  
  28. 1.  Introduction
  29.     ------------
  30.  
  31. Wack is a local and remote debugger for the Amiga.  Originally used
  32. internally at Commodore by the software engineering department, it has
  33. grown to be potentially useful to other developers as well.
  34.  
  35. Wack can be used to analyze the same machine it is run on, or it can
  36. be connected remotely via an Envoy networking link to another Amiga
  37. running a small Wack-server program, or via a serial cable to another
  38. Amiga which uses SAD.  SAD is a V39 and higher ROM feature which
  39. provides a low-level protocol for debuggers to connect serially to an
  40. Amiga.  When SAD is running, it takes over the target machine.  There
  41. are a number of ways to launch SAD mode, including a small program to
  42. trigger it from either of the mouse ports.
  43.  
  44. Wack allows the operator to read and write the memory of the target
  45. system, as well as disassemble code, and analyze a great many system
  46. structures.  Through its ARexx macro language and the ability to add
  47. additional functions written in any programming language, you can
  48. extend Wack to display, analyze, and control features private to
  49. projects you may be developing.
  50.  
  51.  
  52. 2.  Glossary
  53.     --------
  54.  
  55. Here are simple explanations for a few terms which should help
  56. understanding the rest of this documentation.
  57.  
  58.  
  59. HOST
  60.  
  61. The host is the computer on which the Wack command window is running.
  62. In the simplest case, Wack can be used to explore the same system
  63. on which the command window is running, but Wack can also connect
  64. to a second Amiga, allowing remote debugging.
  65.  
  66.  
  67. TARGET
  68.  
  69. The target is the computer being analyzed or explored by Wack.  In the
  70. simplest case, the target is the same machine as the host.  However,
  71. Wack supports remote debugging, in which the host talks to a target
  72. machine in one of two ways (Envoy or SAD).
  73.  
  74.  
  75. ENVOY
  76.  
  77. Envoy is Commodore's Amiga peer-to-peer networking system.  Wack
  78. supports remote debugging over Envoy, which is to say if you have two
  79. machines connected by an Envoy network, you may run the Wack command
  80. window on one machine (the host) in order to examine the behavior of
  81. another machine (the target).  When Wack is connected to a target
  82. machine via Envoy, the target machine continues to run normally.
  83.  
  84.  
  85. SAD
  86.  
  87. SAD is a low-level serial debugging link built into the ROM of every
  88. Amiga running V39 or higher (Amiga OS Release 3 or higher).  Wack
  89. knows how to use the SAD protocols in order to talk to a target
  90. machine connected via a serial cable.  In order for Wack to
  91. communicate via the SAD mechanism, the target machine must be
  92. "frozen".  There are a number of ways to freeze the target to allow
  93. debugging, and Wack has a command to allow the target machine to
  94. resume normal operation when debugging is done.
  95.  
  96.  
  97. FRAME
  98.  
  99. A frame is a small amount of memory on the target computer.  By
  100. default, a frame is sixteen bytes long, but this can be changed.  Wack
  101. dumps or disassembles memory one frame at a time.  A few other
  102. functions may operate on frame-sized units.
  103.  
  104.  
  105. CURRENT ADDRESS
  106.  
  107. Wack allows you to navigate and browse the memory of the target
  108. system.  It does this by maintaining a "current address", which
  109. is the last address you looked at or went to.  Many commands take
  110. an optional address parameter.  If you leave out that parameter,
  111. the current address is used, otherwise the address you specify
  112. will be used by that command.
  113.  
  114.  
  115. ENFORCER
  116.  
  117. Enforcer is a Commodore utility which uses the MMU (memory management
  118. unit) available on most 68020 and higher systems.  Enforcer traps and
  119. reports on accesses to memory regions that programs are not normally
  120. supposed to touch.  Naturally, when browsing through memory there is a
  121. risk that one might stumble on such a memory region, thus causing
  122. "enforcer hits" (reports of access violations).  Wack normally
  123. prevents access to those areas of memory it knows should not be
  124. touched, thereby preventing Enforcer hits due to casual or careless
  125. navigating.  (Wack does have an option to remove this feature,
  126. permitting access to any memory, but re-introducing the risk of
  127. causing an enforcer hit).
  128.  
  129.  
  130. SEGTRACKER
  131.  
  132. SegTracker is a Commodore utility which tracks where every program on
  133. a computer ended up getting loaded.  Wack can use SegTracker running
  134. on the target system in order to correlate symbols from an executable
  135. containing debugging information available on the host to the actual
  136. addresses at which that program was loaded on the target.
  137.  
  138.  
  139. 3.  Starting Wack
  140.     -------------
  141.  
  142. The command syntax for starting Wack is:
  143.  
  144.     Wack TARGET,PUBSCREEN/K,FROM/K
  145.  
  146. TARGET specifies the target machine to debug.  If this argument is
  147. omitted, then Wack will debug the machine is it run on.  To debug a
  148. machine running the WackServer Envoy server program, specify that
  149. machine's network name as the TARGET parameter.  To connect via serial
  150. link to a machine via the SAD link, specify the serial port unit
  151. number to use.
  152.  
  153. PUBSCREEN is the name of the public screen on which you wish the Wack
  154. window to open.  If omitted, Wack will open on the default public
  155. screen (normally the Workbench).
  156.  
  157. FROM specifies the startup file that Wack should execute.  When Wack
  158. starts, it normally reads and executes rexx:startup.wack, which can
  159. contain ARexx commands to configure Wack to your liking.  Normally,
  160. Wack's menu structure and any command bindings to ARexx scripts or to
  161. external Wack modules are made in the startup file.  You can use the
  162. FROM keyword to specify an alternate startup file, or you may specify
  163. "FROM nil:" to specify that no startup file should be read.
  164.  
  165.  
  166. 4.  Basic Wack Commands
  167.     -------------------
  168.  
  169. Here is a brief introduction to the commands you may wish to play with
  170. when first using Wack.
  171.  
  172. * help
  173.  
  174. Type help to display a list of topics for which help is available.
  175. You can then type "help memory", for example, to see help on the
  176. commands you can use to view and manipulate memory on the target
  177. system.
  178.  
  179. * quit
  180.  
  181. Type quit to exit from Wack, closing the Wack window and cleaning up
  182. everything.
  183.  
  184. * (go to address)
  185.  
  186. Type the hex address you wish to see, to go to that address and show a
  187. frame of memory (which is normally 16 bytes) at that address.
  188.  
  189. * (show next frame)
  190.  
  191. The "show next frame" command will display the next frame of memory.
  192. Type <.> <RETURN> (period,return) to show the next frame.
  193.  
  194. * (show previous frame)
  195.  
  196. The "show next frame" command will display the previous frame of
  197. memory.  Type <,> <RETURN> (comma,return) to show the previous frame.
  198.  
  199. * (disassemble frame)
  200.  
  201. This command disassembles the next frame of memory, showing 680x0
  202. code.  Type <;> <RETURN> (semicolon,return) to disassemble a frame's
  203. worth of memory.
  204.  
  205. * (show tasks)
  206.  
  207. To get an idea of the structure scanning abilities of Wack, type
  208. "tasks" to see a list of all the tasks on the target system.
  209.  
  210.  
  211. 5.  Wack Command Documentation
  212.     --------------------------
  213.  
  214. This section explains each Wack command.  Wack is in general not case
  215. sensitive, though some of the arguments that represent items on the
  216. target Amiga's system lists may be searched for in a case-sensitive
  217. manner.  Words shown in all capitals are keywords and must be typed
  218. exactly as shown.  Round brackets "()" enclose optional parameters or
  219. keywords.  Vertical bars separate exclusive keywords.
  220.  
  221. If an optional address argument shown as "(address)" is omitted, the
  222. current address is used.
  223.  
  224.  
  225. 5a. Miscellaneous Commands
  226.     ----------------------
  227.  
  228. HELP ( MISC | CONFIG | MEMORY | EXEC | INTUITION | GRAPHICS )
  229.  
  230. Provide help on Wack commands.  Help is available on six different
  231. categories of command.  "HELP" alone or with an unknown argument
  232. provides general help information, including a list of the help
  233. categories.
  234.  
  235.  
  236. ? ( MISC | CONFIG | MEMORY | EXEC | INTUITION | GRAPHICS )
  237.  
  238. The question mark symbol is a synonym for "HELP".
  239.  
  240.  
  241. QUIT
  242.  
  243. The "QUIT" command exits the Wack session.
  244.  
  245.  
  246. ABOUT
  247.  
  248. The "ABOUT" command shows version and author information for Wack.
  249.  
  250.  
  251. CLS
  252.  
  253. The "CLS" command clears the Wack window.
  254.  
  255.  
  256. PROTECT ( ON | OFF )
  257.  
  258. Normally, Wack prevents you from reading or writing to areas of memory
  259. that are considered invalid.  This helps ensure system stability and
  260. removes the risk of Wack or its remote server causing an Enforcer hit
  261. if Enforcer is running on the target system.  If you wish to be able
  262. to access these areas of memory, you can use "PROTECT OFF" to turn off
  263. this protection.  "PROTECT ON" restores protection against accessing
  264. invalid addresses.  "PROTECT" alone shows the current state of this
  265. feature.  You should not be running Enforcer on the target system
  266. if you wish to use the "PROTECT OFF" feature.
  267.  
  268.  
  269. CAPTURE ( filename ) ( OFF ) ( APPEND )
  270.  
  271. The "CAPTURE" command allows you to capture all Wack output to a file.
  272. This is convenient for keeping a record of your debugging session, or
  273. for subsequent review or searching.  Type "CAPTURE filename" to begin
  274. capturing to the specified file.  "CAPTURE filename APPEND" will begin
  275. capturing, but will append to the specified file's existing contents
  276. instead of replacing it.  "CAPTURE OFF" will end capturing to that
  277. file.
  278.  
  279.  
  280. CONTEXT
  281.  
  282. When connected to the target Amiga via SAD, the "CONTEXT" command will
  283. display the execution context of the target machine.  This information
  284. includes the way in which SAD was triggered (a call to Debug(), a
  285. crash, or an NMI), and a dump of the data, address, and control
  286. registers of the CPU.  The context command first sends a delete
  287. keystroke (ASCII 127) to the connected machine.  This can be used to
  288. force a machine which is in the process of crashing (flashing power
  289. LED) to drop into SAD and establish a link with Wack.  See the section
  290. on connecting via SAD for more details.  When running locally or
  291. connected via Envoy, this command does not work.  The "CONTEXT"
  292. command sets the spare address pointer to point to the remote system's
  293. program counter.
  294.  
  295.  
  296. GO
  297.  
  298. When connected to the target Amiga via SAD, the "GO" command instructs
  299. the target machine to resume execution.  This command is useful since
  300. when the target is operating under SAD, normal operation is halted.
  301. When running locally or connected via Envoy, this command does not
  302. work.
  303.  
  304.  
  305. CALL ( address )
  306.  
  307. This causes wack (or the remote SAD or Envoy server) to call a function
  308. at the specified address, or the current address if none is specified.
  309. No parameters are set up.  A0/A1/D0/A1 are scratch.  Any return value
  310. from the function is ignored.  This function should be used very
  311. carefully, as it can easily crash the machine being debugged.
  312.  
  313.  
  314. SYSTEM command
  315.  
  316. The "SYSTEM" command instructs Wack to execute the specified command
  317. as an Amiga shell command.  For example "SYSTEM dir" would display
  318. the current directory in the Wack window.
  319.  
  320.  
  321. RX script
  322.  
  323. The "RX" command instructs Wack to execute the specified script as an
  324. ARexx script.  For example "RX foo.rexx" would run the foo.rexx
  325. script.  Normal ARexx searching rules apply, and the default extension
  326. for Wack ARexx scripts is ".wack".
  327.  
  328.  
  329. RXS commands
  330.  
  331. The "RXS" command instructs Wack to execute the specified arguments as
  332. ARexx commands.  For example "RXS print 17*5" would display "85" in
  333. the Wack window.
  334.  
  335.  
  336. CONFIGURATION COMMANDS
  337.  
  338.  
  339. PROMPT string
  340.  
  341. The "PROMPT" command allows you to configure the Wack command prompt.
  342. The string is taken literally, with the following substitutions:
  343.  
  344.     *N or \N: newline
  345.     *T or \T: tab
  346.     *C or \C: current address (in hex)
  347.  
  348. The default prompt is "\n=> ".
  349.  
  350.  
  351. SETDUMP ( WORD | LONGWORD ) ( WIDE | NARROW ) ( ASCII | NOASCII )
  352.  
  353. The "SETDUMP" command allows to configure the way in which memory
  354. dumps are read and displayed, to best suit your needs and the window
  355. widths.  The "WORD" and "LONGWORD" options control whether memory is
  356. to be read by word or by long word.  The default setting is to read by
  357. long word.  Certain hardware areas must be read in appropriate-sized
  358. units.  Note that if your frame size is an odd number of words, the
  359. last two bytes will be read as a word, not a long word.  Thus, if you
  360. set the frame size to 2 by using the ":2" command, all the reads will
  361. be by word.  The "NARROW" option inserts a space after every eight hex
  362. digits, while the "WIDE" option inserts a space after every four hex
  363. digits.  The "ASCII" and "NOASCII" options control whether the ASCII
  364. version of the memory is displayed beside the hexadecimal output.
  365. "SETDUMP" alone shows the current state.  Note that "SETDUMP WIDE
  366. ASCII" produces output which is more than 80 columns wide.
  367.  
  368.  
  369. BINDCONSTANT label ( address )
  370.  
  371. The "BINDCONSTANT" command is used to create a new Wack command which
  372. evaluates to the specified (or current) address.  For example, if you
  373. type "BINDCONSTANT ROMstart F80000", you would create a symbol called
  374. "ROMstart", whose value was F80000".  Typing a symbol (in this case,
  375. typing "ROMstart") would set the current address to the value of the
  376. symbol.  Also, the "WHERE" and "WHEREIS" commands take advantage of
  377. defined symbols to tell you where you are with respect to the nearest
  378. defined symbol.  You may wish to use this command in your startup.wack
  379. file to set up commands for frequently-needed constants.
  380.  
  381.  
  382. SET label ( address )
  383.  
  384. The "SET" command is a convenient synonym for the "BINDCONSTANT" 
  385. command.
  386.  
  387.  
  388. BINDALIAS newcommand oldcommand
  389.  
  390. The "BINDALIAS" command allows you to create synonyms for existing
  391. Wack commands.  For example, if you use the "EXECBASE" command
  392. frequently to show the contents of the ExecBase structure, you could
  393. type "BINDALIAS EB EXECBASE" to create a new command, "EB", which
  394. performs the same function as "EXECBASE".  You may wish to use this
  395. command in your startup.wack file to set up aliases for
  396. frequently-used commands.
  397.  
  398.  
  399. BINDSYSTEM command shellprogram ( arguments )
  400.  
  401. The "BINDSYSTEM" command allows you to define a new Wack command which
  402. executes a shell program with the specified arguments.  For example,
  403. if you type "BINDSYSTEM freemem avail total", then typing "freemem"
  404. would display the total amount of memory on the host system (the
  405. output of the shell command "avail total").  You may wish to use this
  406. command in your startup.wack file to set up convenient names for
  407. frequently-used shell commands.
  408.  
  409.  
  410. BINDRX command rexxscript ( arguments )
  411.  
  412. The "BINDRX" command allows you to define a new Wack command which
  413. executes an ARexx script with the specified arguments.  For example,
  414. if you type "BINDRX lvo ShowLVO", then typing "lvo" would run the
  415. ShowLVO ARexx script.  You may wish to use this command in your
  416. startup.wack file to tie ARexx extensions to Wack into Wack itself.
  417.  
  418.  
  419. BINDXWACK command shellprogram ( arguments )
  420.  
  421. The "BINDXWACK" command allows you to define a new Wack command which
  422. executes a specially-written shell program designed to be an external
  423. extension to Wack.  That program will be invoked, passing an
  424. additional argument of "WACKPORT=Wack's ARexx port's name".  The
  425. program can use the Wack ARexx port to issue commands to Wack,
  426. allowing you to extend Wack with C or any other language of your
  427. choice.  See the section on External Wack Commands.  Any "BINDXWACK"
  428. commands would typically be placed in your startup.wack file, so Wack
  429. always comes up configured with your extensions.
  430.  
  431.  
  432. ADDMENU header
  433.  
  434. Along with the "ADDITEM" and "ADDSUBITEM" commands, the "ADDMENU"
  435. command allows you to customize the menus of the Wack window.  The
  436. "ADDMENU" command creates a menu panel whose title is as specified.
  437. For example, "ADDMENU Intuition" would create a menu header whose
  438. title was "Intuition".
  439.  
  440.  
  441. ADDITEM header item command ( key )
  442.  
  443. The ADDITEM command creates a menu item for the menu strip of Wack's
  444. window.  If a menu panel with the specified header is found, the item
  445. will be added to that panel, otherwise a new panel will be created
  446. first.  The specified item name will be used in the menu.  The command
  447. you supply is the command which will be executed when that menu item
  448. is chosen.  The optional key argument allows you to specify a menu
  449. command-key for this item.  For example,
  450.  
  451.     ADDITEM Intuition "Show IntuitionBase" ibase I
  452.  
  453. would create a menu item entitled "Show IntuitionBase" in the
  454. Intuition menu.  This item would issue the Wack "ibase" command, and
  455. would have a keyboard equivalent of right-Amiga-I.
  456.  
  457.  
  458. ADDSUBITEM header item subitem command ( key )
  459.  
  460. The "ADDSUBITEM" command is similar to the "ADDITEM" command, but is
  461. used to create a menu subitem of the specified menu item in the
  462. specified menu panel.
  463.  
  464.  
  465. 5b. Memory Commands
  466.     ---------------
  467.  
  468. <RETURN>
  469.  
  470. Typing <RETURN> when at the Wack prompt displays the current memory
  471. frame.
  472.  
  473.  
  474. address
  475.  
  476. Typing a hexadecimal address at the Wack prompt sets Wack's current
  477. address to that address, and shows a frame of memory there.  For
  478. example, typing "F80000" would show the first frame of the system ROM.
  479.  
  480.  
  481. .
  482.  
  483. The period key allows you to advance to the next frame of memory, and
  484. show that frame.  For example, assuming the default frame size of 16
  485. bytes, and assuming the current address is F80000, typing "." would
  486. show the frame of memory starting at address F80010.  You can type
  487. multiple periods to show multiple frames.  For instance, typing "..."
  488. would show the next three frames of memory.
  489.  
  490.  
  491. ,
  492.  
  493. The comma key allows you to back up to the previous frame of memory,
  494. and show that frame.  For example, assuming the default frame size of
  495. 16 bytes, and assuming the current address is F90000, typing "." would
  496. show the frame of memory starting at address F8FFF0.  You can type
  497. multiple commas to show multiple frames.  For instance, typing ",,,"
  498. would show the three previous frames of memory, in reverse order.
  499.  
  500.  
  501. >
  502.  
  503. The greater-than key allows you to advance to the next word of memory
  504. and show a frame of memory starting there.  For example, assuming the
  505. current address is F80000, typing ">" would show the frame of memory
  506. starting at address F80002.  You can type multiple greater-thans to
  507. skip multiple frames.  For instance, if the current address is F80000,
  508. typing ">>>" would show the frame of memory beginning at F80006.  Note
  509. that unlike the period key, typing multiple greater-thans will not
  510. show the intermediate frames, only the result.
  511.  
  512.  
  513. <
  514.  
  515. The less-than key allows you to back up to the previous word of memory
  516. and show a frame of memory starting there.  For example, assuming the
  517. current address is F90000, typing "<" would show the frame of memory
  518. starting at address F8FFFE.  You can type multiple less-thans to
  519. skip multiple frames.  For instance, if the current address is F90000,
  520. typing "<<<" would show the frame of memory beginning at F8FFFA.  Note
  521. that unlike the comma key, typing multiple less-thans will not show
  522. the intermediate frames, only the result.
  523.  
  524.  
  525. ;
  526.  
  527. The semicolon key allows you to disassemble a frame of memory at
  528. the current address.  Typing multiple semicolons will disassemble
  529. that many frames of memory.
  530.  
  531.  
  532. +offset
  533.  
  534. The plus key is used to increase the current address by a specified
  535. offset.  For example, typing "+100" will advance the current address
  536. by 100 hex bytes, and display a frame of memory starting there.
  537.  
  538.  
  539. -offset
  540.  
  541. The plus key is used to decrease the current address by a specified
  542. offset.  For example, typing "-100" will back up the current address
  543. by 100 hex bytes, and display a frame of memory starting there.
  544.  
  545.  
  546. =value
  547.  
  548. The equals key is used to set the byte, word, or long word at the
  549. current address to the specified hexadecimal value.  The size of the
  550. write is determined by the number of hexadecimal digits you supply.
  551. Here are some examples:
  552.  
  553.     "=FF" sets the current byte to hexadecimal FF.
  554.     "=00FF" sets the current word to hexadecimal FF.
  555.     "=000000FF" sets the current long word to hexadecimal FF.
  556.  
  557.  
  558. :framesize
  559.  
  560. The colon key is used to set the frame size.  Normally, the frame size
  561. is 10 hex bytes.  Typing ":40" would set the frame size to 40 hex
  562. bytes, which would take four lines per frame to display.  A frame size
  563. of zero (":0") means that no frame is displayed when at a particular
  564. address.  This is useful when writing to areas of the system that
  565. cannot be safely read from, such as custom chip write-registers.
  566.  
  567.  
  568. [
  569.  
  570. The open square-bracket key is the indirection function.  This
  571. instructs Wack to set the current address to the long word stored at
  572. the current address.  This is very useful in list or structure
  573. traversal.  Multiple open square-brackets can be typed to perform
  574. multiple consecutive indirections.  Wack keeps a large stack of the
  575. indirections performed, so they can be undone with the close
  576. square-bracket (undo-indirection) feature.
  577.  
  578. The open square-bracket key is special in that it may be followed
  579. by an additional command on the same line.  For instance, typing
  580. "[task" would perform an indirection and then show the task at
  581. the resulting address.
  582.  
  583.  
  584. ]
  585.  
  586. The close square-bracket key is the undo-indirection (exdirection)
  587. function.  This instructs Wack to set the current address to the
  588. address before the most recent indirection operation.  This is very
  589. useful in list or structure traversal.  Multiple close square-brackets
  590. can be typed to perform multiple consecutive exdirections.
  591.  
  592. The close square-bracket key is special in that it may be followed by
  593. an additional command on the same line.  For instance, typing "]task"
  594. would undo the last indirection and then show the task at the
  595. resulting address.
  596.  
  597.  
  598. {
  599.  
  600. The open brace-bracket key is the BCPL-indirection function.  It
  601. evaluates the value stored at the current address as a BCPL pointer
  602. (BPTR) and sets the current address to that value.  Multiple open
  603. brace-brackets can by typed to perform multiple consecutive
  604. BCPL-indirections.  BCPL-indirections share the same stack as regular
  605. indirections, and can be undone with the close square-bracket key.
  606.  
  607. The open brace-bracket key is special in that it may be followed by an
  608. additional command on the same line.  For instance, typing "{process"
  609. would perform a BCPL-indirection and then show the process at the
  610. resulting address.
  611.  
  612.  
  613. DEC hexvalue
  614.  
  615. The "DEC" command is used to convert the specified hexadecimal value
  616. to decimal.  For example, "DEC 4A" produces an answer of 74.
  617.  
  618.  
  619. HEX decvalue
  620.  
  621. The "HEX" command is used to convert the specified decimal value to
  622. hexadecimal.  For example, "HEX 74" produces an answer of 4A.
  623.  
  624.  
  625. BPTR bcplpointer
  626.  
  627. The "BPTR" command is used to evaluate a BCPL pointer, which basically
  628. consists of multiplying by four.
  629.  
  630.  
  631. FIND ( hexvalue )
  632.  
  633. The "FIND" command is used to locate the specified hexadecimal word or
  634. long word between the current address and the find-limit (see the
  635. "LIMIT" command).  If the limit is zero (the default), a range of 1K
  636. is searched.  If the limit address is less than the current address,
  637. the search proceeds backwards.
  638.  
  639. If a hexadecimal value is specified, the search begins at the current
  640. address.  If the hex value is omitted, the last value used will be
  641. reused, and the search will commence just past the current address,
  642. which means that consecutive "FIND" commands will find successive
  643. occurrences of the target pattern.
  644.  
  645. The "FIND" command determines whether to search by word or by long
  646. word based on the number of hexadecimal digits supplied.
  647.  
  648.  
  649. / ( hexvalue )
  650.  
  651. The slash key is a synonym for the "FIND" command.
  652.  
  653.  
  654. LIMIT ( address )
  655.  
  656. Sets the limit for the "FIND" operation to the specified address (or
  657. the current address, if none is specified).  If the limit is set
  658. to zero, then the search limit will be set to 1K after the start
  659. address of any search.
  660.  
  661.  
  662. STACKLIMIT ( address )
  663.  
  664. The "STACKLIMIT" command sets up search boundaries based on the stack
  665. of the task at the specified address (or the current address, if no
  666. address is given).  The current address will be set to the task's
  667. SPReg value, and the limit will be set to the task's SPUpper value.
  668.  
  669.  
  670. WHERE ( address )
  671.  
  672. The "WHERE" command can be used to identify the nearest symbol less
  673. than or equal to the current or the specified address.  This is useful
  674. in determining where in the target system's memory you are.  Symbol
  675. definitions come from several places.  The "BINDCONSTANT" and "SET"
  676. commands can be used to define symbols, and the "BINDHUNKS" and
  677. "BINDSYMBOLS" commands may also be used to define symbols.
  678.  
  679.  
  680. WHEREIS ( address )
  681.  
  682. The "WHEREIS" command is similar to the WHERE command, except that it
  683. performs an indirection on the current or specified address.  That is,
  684. it looks up the address stored at the current or specified address in
  685. the symbol table.
  686.  
  687.  
  688. !
  689.  
  690. Wack maintains a "spare address" pointer, which is set by certain
  691. functions which locate system structures.  Typing "!" swaps the
  692. current address with the spare address.  For example, typing "AWINDOW"
  693. displays the address of the active window and sets the spare address
  694. pointer to point at that window.  Subsequently typing "!" sets the
  695. current address to point to the active window.
  696.  
  697. The exclamation point is special in that it may be followed by an
  698. additional command on the same line.  For instance, typing "!window"
  699. after "awindow" in the above example would go to and show the active
  700. window.
  701.  
  702.  
  703. SHOWHUNKS ( module )
  704.  
  705. If SegTracker is running on the target machine, then the "SHOWHUNKS"
  706. command may be used to show the base addresses of all the hunks of the
  707. specified module, or of all modules if no specific module is supplied.
  708. Module names are compared using a tail-anchored case-insensitive
  709. comparison against the module names known to SegTracker (which are
  710. generally the CLI command names).  That is, "SHOWHUNKS myprog" would
  711. match "Work:Tools/MyProg" but not "Work:Tools/MyProg.command".
  712.  
  713.  
  714. BINDHUNKS ( module )
  715.  
  716. This command is similar to "SHOWHUNKS", except that instead of
  717. displaying the base addresses of the hunks, "BINDHUNKS" creates Wack
  718. symbols for the base addresses of all the hunks of the specified
  719. module, or of all modules if no specific module is supplied.
  720. Following this, the "WHERE" and "WHEREIS" commands may be used to
  721. obtain hunk and offset information for any interesting address.  This
  722. command requires that SegTracker be running on the target machine.
  723. As an example, "BINDHUNKS myprog" would create symbols for the
  724. hunk-offsets of "myprog".
  725.  
  726.  
  727. BINDSYMBOLS symbolfile ( module )
  728.  
  729. This command uses SegTracker on the target machine to locate the base
  730. addresses of the hunks of the specified module, then reads the
  731. specified symbol file (normally, a matching version of the executable
  732. having symbols compiled into it), and creates a Wack symbol equal to
  733. the resolved value of each symbol found in the symbolfile.  The result
  734. is that Wack can learn the full symbols of a module already running on
  735. the target machine.  This can be very useful for figuring out where
  736. one is with the "WHERE" and "WHEREIS" commands.  If the module name is
  737. omitted, the file-name part (up to the first period) of the symbolfile
  738. name is used to find the module on SegTracker's list.  The module
  739. parameter can be used to give a precise name when the symbolfile name
  740. is significantly different to use.  As an example, typing the command
  741. "BINDSYMBOLS Work:Sources/MyProg.debug myprog" would create Wack
  742. symbols for all symbols defined in Work:Sources/MyProg.debug based on
  743. the actual location of the "myprog" program on the target machine.
  744.  
  745.  
  746. 5c. Exec and DOS Commands
  747.     ---------------------
  748.  
  749. EXECBASE
  750.  
  751. This command shows selected fields from ExecBase.  This command sets
  752. the spare address pointer to ExecBase.
  753.  
  754.  
  755. NODES ( address )
  756.  
  757. This command shows the address, node type, priority, and name of every
  758. Exec Node on the same list as the specified (or current) address.  An
  759. asterisk denotes the current node.  The name pointer is validated
  760. before printing, so the command is somewhat usable on MinNodes as
  761. well.
  762.  
  763.  
  764. SEM ( address )
  765.  
  766. This command shows the Exec SignalSemaphore at the specified (or
  767. current) address.
  768.  
  769.  
  770. SEMS ( address )
  771.  
  772. This command shows all the Exec SignalSemaphores on the List at the
  773. specified (or current) address.
  774.  
  775.  
  776. TASKS
  777.  
  778. This command shows a one-line summary for every task in the system,
  779. including the task's address, priority, status, signals being waited
  780. on, and the task name and process CLI command name, if any.
  781.  
  782.  
  783. TASK ( address | name )
  784.  
  785. The "TASK" command displays a detailed dump of an Exec task.  If no
  786. argument is given, the task at the current address is displayed.
  787. Alternately, you may specify the address of the task you wish to
  788. display.  The final option is to specify part or all of the task's
  789. name.  The first task whose task name or process CLI command name
  790. partially matches the specified name will be shown.
  791.  
  792.  
  793. SP
  794.  
  795.  
  796. INTERRUPTS
  797.  
  798. The "INTERRUPTS" command shows the Exec interrupt vectors.
  799.  
  800.  
  801. INTS
  802.  
  803. The "INTS" command is a synonym for the "INTERRUPTS" command.
  804.  
  805.  
  806. PORTS
  807.  
  808. The "PORTS" command shows information on all Exec MsgPorts on the Exec
  809. port list, including address, name, SigTask, and signal bit.
  810.  
  811.  
  812. DEVICES
  813.  
  814. The "DEVICES" command shows a summary of every Exec device, including
  815. its address, priority, version/revision, and name.
  816.  
  817.  
  818. DEVS
  819.  
  820. The "DEVS" command is a synonym for the "DEVICES" command.
  821.  
  822.  
  823. LIBRARIES
  824.  
  825. The "LIBRARIES" command shows a summary of every Exec library,
  826. including its address, priority, version/revision, and name.
  827.  
  828.  
  829. LIBS
  830.  
  831. The "LIBS" command is a synonym for the "LIBRARIES" command.
  832.  
  833.  
  834. RESOURCES
  835.  
  836. The "RESOURCES" command shows a summary of every Exec resource.
  837.  
  838.  
  839. RES
  840.  
  841. The "RES" command is a synonym for the "RESOURCES" command.
  842.  
  843.  
  844. REGIONS
  845.  
  846. The "REGIONS" command shows information on each memory region known
  847. to Exec.
  848.  
  849.  
  850. MEMORY
  851.  
  852. The "MEMORY" command shows all memory headers in the system.  Note that
  853. this command can potentially produce a very large amount of output.
  854.  
  855.  
  856. MEM
  857.  
  858. The "MEM" command is a synonym for the "MEMORY" command.
  859.  
  860.  
  861. MODULES
  862.  
  863. The "MODULES" command shows a summary of every Exec resident module,
  864. including its address, priority, version, and name.
  865.  
  866.  
  867. MODS
  868.  
  869. The "MODS" command is a synonym for the "MODULES" command.
  870.  
  871.  
  872. DOSBASE
  873.  
  874. The "DOSBASE" command displays selected fields of the dos.library
  875. DOSBase structure.  This command sets the spare address pointer to
  876. DOSBase.
  877.  
  878.  
  879. DOSLIST
  880.  
  881. The "DOSLIST" command shows the dos.library device/volume/assign list.
  882.  
  883.  
  884. PROCESS ( address | name )
  885.  
  886. The "PROCESS" command displays a detailed dump of a DOS process.  If
  887. no argument is given, the process at the current address is displayed.
  888. Alternately, you may specify the address of the process you wish to
  889. display.  The final option is to specify part or all of the process's
  890. name.  The first process whose task name or process CLI command name
  891. partially matches the specified name will be shown.  If the specified
  892. process turns out to be only a task, then only the task-related fields
  893. will be displayed.
  894.  
  895.  
  896. PROC
  897.  
  898. The "PROC" command is a synonym for the "PROCESS" command.
  899.  
  900.  
  901. 5d. Intuition Commands
  902.     ------------------
  903.  
  904. IBASE
  905.  
  906. The "IBASE" command shows selected fields from the public part of the
  907. IntuitionBase structure.  This command sets the spare address pointer
  908. to IntuitionBase.
  909.  
  910.  
  911. ASCREEN
  912.  
  913. The "ASCREEN" command shows the address of Intuition's active screen.
  914. This command sets the spare address pointer to the active screen.
  915.  
  916.  
  917. AWINDOW
  918.  
  919. The "AWINDOW" command shows the address of Intuition's active window.
  920. This command sets the spare address pointer to the active window.
  921.  
  922.  
  923. SCREEN ( address )
  924.  
  925. The "SCREEN" command displays the most important fields of the screen
  926. at the current or specified address.
  927.  
  928.  
  929. WINDOW ( address )
  930.  
  931. The "WINDOW" command displays the most important fields of the window
  932. at the current or specified address.
  933.  
  934.  
  935. WFLAGS ( address )
  936.  
  937. The "WFLAGS" command displays the Window Flags, MoreFlags, and
  938. IDCMPFlags fields using descriptive labels for each bit set.  The
  939. window at the current or specified address is used.
  940.  
  941.  
  942. FIRSTGAD
  943.  
  944. The "FIRSTGAD" command displays the address of the first gadget of the
  945. window at the specified or current address.  This command sets the
  946. spare address pointer to the first gadget of the window.
  947.  
  948.  
  949.  
  950. GADGET ( address )
  951.  
  952. The "GADGET" command displays the gadget at the current or specified
  953. address.
  954.  
  955.  
  956. GADGETS ( address )
  957.  
  958. The "GADGETS" command displays the list of gadgets beginning with the
  959. gadget at the current or specified address.
  960.  
  961.  
  962. MENU ( address )
  963.  
  964. The "MENU" command displays the Menu header at the current or
  965. specified address.
  966.  
  967.  
  968. MENUS ( address )
  969.  
  970. The "MENUS" command displays the list of Menu headers beginning with
  971. the Menu header at the current or specified address.
  972.  
  973.  
  974. ITEM ( address )
  975.  
  976. The "ITEM" command displays the MenuItem or SubItem at the current or
  977. specified address.
  978.  
  979.  
  980. ITEMS ( address )
  981.  
  982. The "ITEMS" command displays the list of MenuItems or SubItems
  983. beginning with the one at the current or specified address.
  984.  
  985.  
  986. REQUESTER ( address )
  987.  
  988. The "REQUESTER" command displays the Intuition Requester at the
  989. current or specified address.
  990.  
  991.  
  992. REQ ( address )
  993.  
  994. The "REQ" command is a synonym for the "REQUESTER" command.
  995.  
  996.  
  997. PROPINFO ( address )
  998.  
  999. The "PROPINFO" command shows the PropInfo structure at the current or
  1000. specified address.
  1001.  
  1002.  
  1003. IMAGE ( address )
  1004.  
  1005. The "IMAGE" command shows the Image structure at the current or
  1006. specified address.
  1007.  
  1008.  
  1009. ITEXT ( address )
  1010.  
  1011. The "ITEXT" command shows the IntuiText structure at the current or
  1012. specified address.
  1013.  
  1014.  
  1015. CLASS ( address )
  1016.  
  1017. The "CLASS" command shows the Boopsi Class structure at the current or
  1018. specified address.
  1019.  
  1020.  
  1021. OBJECT ( address )
  1022.  
  1023. The "OBJECT" command shows the Boopsi object structure at the current
  1024. or specified address.
  1025.  
  1026.  
  1027. LISEMS
  1028.  
  1029. The "LISEMS" command shows the LayerInfo and Layer semaphores for
  1030. all screens and windows in the system.
  1031.  
  1032.  
  1033. 5e. Graphics and Layers Commands
  1034.     ----------------------------
  1035.  
  1036. GFXBASE
  1037.  
  1038. The "GFXBASE" command shows many of the interesting fields of the
  1039. GfxBase structure.  This command sets the spare address pointer to
  1040. GfxBase.
  1041.  
  1042.  
  1043. VIEW ( address )
  1044.  
  1045. The "VIEW" command shows the View structure at the current or
  1046. specified address.
  1047.  
  1048.  
  1049. VEXTRA ( address )
  1050.  
  1051. The "VEXTRA" command shows the ViewExtra structure at the current or
  1052. specified address.
  1053.  
  1054.  
  1055. VIEWPORT ( address )
  1056.  
  1057. The "VIEWPORT" command shows the ViewPort structure at the current or
  1058. specified address.
  1059.  
  1060.  
  1061. VP ( address )
  1062.  
  1063. The "VP" command is a synonym for the "VIEWPORT" command.
  1064.  
  1065.  
  1066. VIEWPORTS ( address )
  1067.  
  1068. The "VIEWPORTS" command shows a list of ViewPort structures beginning
  1069. with the one at the current or specified address.
  1070.  
  1071.  
  1072. COP
  1073.  
  1074. The "COP" command shows the current copper list, excluding the color
  1075. table.
  1076.  
  1077.  
  1078. COPPER
  1079.  
  1080. The "COPPER" command shows the current copper list, including the
  1081. color table.
  1082.  
  1083.  
  1084. COPINIT
  1085.  
  1086. The "COPINIT" command shows the graphics copinit copper list.
  1087.  
  1088.  
  1089. LINFO ( address )
  1090.  
  1091. The "LINFO" command shows the LayerInfo structure at the current or
  1092. specified address.
  1093.  
  1094.  
  1095. LAYER ( address )
  1096.  
  1097. The "LAYER" command shows the Layer structure at the current or
  1098. specified address.
  1099.  
  1100.  
  1101. 6.  ARexx Commands
  1102.     --------------
  1103.  
  1104. You can invoke ARexx scripts directly from within Wack (see the "RX"
  1105. and "RXS" commands).  As well, you can create new Wack command names
  1106. whose function is to invoke ARexx scripts (see the "BINDRX" command).
  1107. The "BINDRX" commands are typically placed in your startup.wack file
  1108. so that Wack always opens configured to your liking.
  1109.  
  1110. Wack is an ARexx command host which allows an ARexx program to issue
  1111. any valid Wack command, and also gives access to a family of Wack
  1112. primitives that can be used to browse the target system.  The ARexx
  1113. port name is of the form "wack.n", where "n" is the invocation number.
  1114.  
  1115. Summary of ARexx commands supported by Wack:
  1116.  
  1117. CURRENTADDR    - Return and optionally set current address
  1118. SPAREADDR    - Return and optionally set spare address
  1119. VERSION        - Return Wack version
  1120. PRINT        - Print string to Wack window
  1121. READBYTE    - Read byte at current or specified address.
  1122.           Result is in hex unless "decimal" is specified.
  1123. READWORD    - Read word at current or specified address.
  1124.           Result is in hex unless "decimal" is specified.
  1125. READLONG    - Read long at current or specified address.
  1126.           Result is in hex unless "decimal" is specified.
  1127. READBLOCK    - Read block of memory into supplied buffer
  1128. READSTRING    - Read string at current or specified address.
  1129. READBSTR    - Read BSTR at current or specified address.
  1130. WRITEBYTE    - Write a byte to current or specified address.
  1131.           Byte is taken to be hex unless "decimal" is specified.
  1132. WRITEWORD    - Write a word to current or specified address.
  1133.           Word is taken to be hex unless "decimal" is specified.
  1134. WRITELONG    - Write a long to current or specified address.
  1135.           Long is taken to be hex unless "decimal" is specified.
  1136. WRITEBLOCK    - Write buffer into memory
  1137. FINDLIBRARY    - Return address of specified library
  1138. CONNECTION    - Return type of connection to target
  1139. CONTEXTADDR    - Return context address
  1140. CALL        - Call a function
  1141.  
  1142.  
  1143. Error codes:
  1144.  
  1145. An ARexx error of 10 generally signifies a bad argument to a command.
  1146. An ARexx error of 5 generally signifies object not found, or similar.
  1147.  
  1148.  
  1149. CURRENTADDR ( address )
  1150.  
  1151. The "CURRENTADDR" ARexx command is used to retrieve and optionally
  1152. change the current address pointer, which is used by Wack for data
  1153. displays and as the default address for most commands that accept an
  1154. address.  The result string is set to the value of the current
  1155. address.  If the optional address argument is provided, the current
  1156. address is then set to this value.
  1157.  
  1158.  
  1159. SPAREADDR ( address )
  1160.  
  1161. The "SPAREADDR" ARexx command is used to retrieve and optionally
  1162. change the spare address pointer, which is set by certain Wack
  1163. commands as a convenient bookmark.  The result string is set to the
  1164. value of the spare address.  If the optional address argument is
  1165. provided, the spare address is then set to this value.
  1166.  
  1167.  
  1168. VERSION
  1169.  
  1170. The "VERSION" ARexx command is used to retrieve the Wack version
  1171. number string.  The result string will be of the form "Wack 40.123".
  1172.  
  1173.  
  1174. PRINT ( string )
  1175.  
  1176. The "PRINT" ARexx command is used to print a text-string into the
  1177. Wack window.
  1178.  
  1179.  
  1180. READBYTE ( address ) ( DECIMAL )
  1181.  
  1182. The "READBYTE" ARexx command is used to read a byte value on the
  1183. target machine.  The byte at the specified or current address will be
  1184. read.  Normally, the result string will be in hexadecimal, unless the
  1185. "DECIMAL" keyword is supplied, in which case the result string will be
  1186. the decimal value.
  1187.  
  1188.  
  1189. READWORD ( address ) ( DECIMAL )
  1190.  
  1191. The "READWORD" ARexx command is used to read a word value on the
  1192. target machine.  The word at the specified or current address will be
  1193. read.  Normally, the result string will be in hexadecimal, unless the
  1194. "DECIMAL" keyword is supplied, in which case the result string will be
  1195. the decimal value.
  1196.  
  1197.  
  1198. READLONG ( address ) ( DECIMAL )
  1199.  
  1200. The "READLONG" ARexx command is used to read a long word value on the
  1201. target machine.  The long word at the specified or current address
  1202. will be read.  Normally, the result string will be in hexadecimal,
  1203. unless the "DECIMAL" keyword is supplied, in which case the result
  1204. string will be the decimal value.
  1205.  
  1206.  
  1207. READBLOCK ( address ) buffer size
  1208.  
  1209. The "READBLOCK" ARexx command is used to read a block of memory from the
  1210. target machine into a supplied buffer.  The block will start at the specified
  1211. or current address, and will be 'size' bytes long.  'address', 'buffer' and
  1212. 'size' must be in hexadecimal.
  1213.  
  1214. READSTRING ( address )
  1215.  
  1216. The "READSTRING" ARexx command is used to read a string on the target
  1217. machine.  The string beginning at the specified or current address
  1218. will be returned as the result string.
  1219.  
  1220.  
  1221. READBSTR ( address )
  1222.  
  1223. The "READBSTR" ARexx command is used to read a BSTR-style string on
  1224. the target machine.  The string beginning at the specified or current
  1225. address will be returned as the result string.  Note that the address
  1226. to specify is an actual address, not a BPTR.
  1227.  
  1228.  
  1229. WRITEBYTE ( address ) value ( DECIMAL )
  1230.  
  1231. The "WRITEBYTE" ARexx command is used to write a byte value into the
  1232. target machine.  The supplied value will be written to the specified
  1233. or current address.  The value you specify is assumed to be a
  1234. hexadecimal value, unless the "DECIMAL" keyword is supplied, in which
  1235. case the value you specify is assumed to be in decimal.
  1236.  
  1237.  
  1238. WRITEWORD ( address ) value ( DECIMAL )
  1239.  
  1240. The "WRITEWORD" ARexx command is used to write a word value into the
  1241. target machine.  The supplied value will be written to the specified
  1242. or current address.  The value you specify is assumed to be a
  1243. hexadecimal value, unless the "DECIMAL" keyword is supplied, in which
  1244. case the value you specify is assumed to be in decimal.
  1245.  
  1246.  
  1247. WRITELONG ( address ) value ( DECIMAL )
  1248.  
  1249. The "WRITELONG" ARexx command is used to write a long word value into
  1250. the target machine.  The supplied value will be written to the
  1251. specified or current address.  The value you specify is assumed to be
  1252. a hexadecimal value, unless the "DECIMAL" keyword is supplied, in
  1253. which case the value you specify is assumed to be in decimal.
  1254.  
  1255.  
  1256. WRITEBLOCK ( address ) buffer size
  1257.  
  1258. The "WRITEBLOCK" ARexx command is used to write a buffer into the memory
  1259. of the target machine.  The block will start at the specified or current
  1260. address, and will be 'size' bytes long.  'address', 'buffer' and 'size'
  1261. must be in hexadecimal.
  1262.  
  1263. FINDLIBRARY ( libraryname )
  1264.  
  1265. The "FINDLIBRARY" ARexx command is used to find the address of the
  1266. specified library on Exec's library list.  The full name in correct
  1267. case must be given, for example "FINDLIBRARY intuition.library".  The
  1268. result string will be the address of the library, if found.
  1269.  
  1270.  
  1271. CONNECTION
  1272.  
  1273. The "CONNECTION" ARexx command is used to retrieve type of connection
  1274. established to the target machine.  The result string will be of the
  1275. form:
  1276.  
  1277. - "Local" (when Wack is running directly on the target machine.)
  1278. - "Envoy foo" (when Wack is connected via Envoy to a machine named foo.)
  1279. - "SAD 3" (when Wack is connected via SAD over the host's serial.device
  1280.   unit 3.)
  1281.  
  1282.  
  1283. CONTEXTADDR
  1284.  
  1285. The "CONTEXTADDR" ARexx command returns the address of the SAD context
  1286. structure.  The result string is the address of the context structure,
  1287. or zero if not found.  If the target machine is connected other than
  1288. through SAD, the result is zero as the context address is not
  1289. supported in that case.
  1290.  
  1291. CALL ( address )
  1292.  
  1293. The "CALL" ARexx command causes wack (or the remote SAD or Envoy server)
  1294. to call a function at the specified address, or the current address if
  1295. none is specified.  No parameters are set up.  A0/A1/D0/A1 are scratch.
  1296. Any return value from the function is ignored.  This function should be
  1297. used very carefully, as it can easily crash the machine being debugged.
  1298.  
  1299.  
  1300.  
  1301. 7.  External Wack Commands
  1302.     ----------------------
  1303.  
  1304. In addition to extensions via ARexx, Wack provides a method whereby
  1305. you can write additional Wack commands in languages such as C.  One
  1306. major advantage over ARexx is that you can easily write modules to
  1307. dump structures private to your particular project.  Handling
  1308. structure offsets in ARexx is awkward at best.
  1309.  
  1310. The basic principle is that you can create a shell program, and bind
  1311. one or more Wack commands to it.  When those Wack commands are issued,
  1312. your shell program is invoked, passing any fixed arguments you
  1313. established when the command was bound, any arguments that were typed
  1314. alongside the command, and the name of Wack's command port.  The
  1315. address of that command port can be used like a library base, and Wack
  1316. functions may be called LVO-style with the port as the base address.
  1317.  
  1318. The "BINDXWACK" command allows you specify the new command name you
  1319. would like to create, as well as a shell program to run, and any fixed
  1320. arguments you wish to pass to it.  For instance, the command
  1321. "BINDXWACK showdata work:WackShow data" states you would like to
  1322. create a Wack command "SHOWDATA" which invokes the shell program
  1323. called "work:WackShow" passing the argument "data".  If you invoke it
  1324. by typing, "showdata f80000", the actual command line will be:
  1325.  
  1326.     work:WackShow WACKPORT=wack.1 data f80000
  1327.  
  1328. The fact that "BINDXWACK" supports a fixed argument to be passed
  1329. allows you to combine the code to handle multiple commands into a
  1330. single module, and use the fixed argument to tell which one was
  1331. invoked.  The actual instance argument can then be operated on.
  1332. "BINDXWACK" commands are typically be placed in your startup.wack
  1333. file, so Wack always comes up configured with your extensions.
  1334.  
  1335. The program you supply to handle the command would typically use
  1336. ReadArgs() to parse the arguments, and perform FindPort() on the Wack
  1337. port, placing the result in a variable called WackBase.  Prototypes
  1338. and pragmas are supplied which allow the following Wack functions to
  1339. be invoked:
  1340.  
  1341. NAME
  1342.     Wack_VPrintf() - Printf-style command to print into Wack window.
  1343.     Wack_Printf() - Varargs stub for Wack_VPrintf().
  1344.  
  1345. SYNOPSIS
  1346.     void Wack_VPrintf( STRPTR fmt, ULONG *arglist );
  1347.     void Wack_Printf( STRPTR fmt, ... );
  1348.  
  1349. FUNCTION
  1350.     These functions display text, printf-style, into the Wack window.
  1351.  
  1352.  
  1353. NAME
  1354.     Wack_ReadCurrAddr() - Retrieve the Wack current address pointer.
  1355.  
  1356. SYNOPSIS
  1357.     APTR Wack_ReadCurrAddr( void );
  1358.  
  1359. FUNCTION
  1360.     This function returns the value of the Wack current address
  1361.     pointer.
  1362.  
  1363.  
  1364. NAME
  1365.     Wack_WriteCurrAddr() - Change the Wack current address pointer.
  1366.  
  1367. SYNOPSIS
  1368.     APTR Wack_WriteCurrAddr( APTR newaddr );
  1369.  
  1370. FUNCTION
  1371.     This function changes the Wack current address pointer to the
  1372.     specified value.
  1373.  
  1374.  
  1375. NAME
  1376.     Wack_ReadSpareAddr() - Retrieve the Wack spare address pointer.
  1377.  
  1378. SYNOPSIS
  1379.     APTR Wack_ReadSpareAddr( void );
  1380.  
  1381. FUNCTION
  1382.     This function returns the value of the Wack spare address
  1383.     pointer.
  1384.  
  1385.  
  1386. NAME
  1387.     Wack_WriteSpareAddr() - Change the Wack spare address pointer.
  1388.  
  1389. SYNOPSIS
  1390.     APTR Wack_WriteSpareAddr( APTR newaddr );
  1391.  
  1392. FUNCTION
  1393.     This function changes the Wack spare address pointer to the
  1394.     specified value.
  1395.  
  1396.  
  1397. NAME
  1398.     Wack_ReadByte() - Read a byte from the target machine's memory.
  1399.  
  1400. SYNOPSIS
  1401.     UBYTE Wack_ReadByte( APTR address );
  1402.  
  1403. FUNCTION
  1404.     This function reads and returns one byte at the specified address
  1405.     of the target machine's memory.
  1406.  
  1407.  
  1408. NAME
  1409.     Wack_ReadWord() - Read a word from the target machine's memory.
  1410.  
  1411. SYNOPSIS
  1412.     UWORD Wack_ReadWord( APTR address );
  1413.  
  1414. FUNCTION
  1415.     This function reads and returns one word at the specified address
  1416.     of the target machine's memory.
  1417.  
  1418.  
  1419. NAME
  1420.     Wack_ReadLong() - Read a long word from the target machine's memory.
  1421.  
  1422. SYNOPSIS
  1423.     ULONG Wack_ReadLong( APTR address );
  1424.  
  1425. FUNCTION
  1426.     This function reads and returns one long word at the specified
  1427.     address of the target machine's memory.
  1428.  
  1429.  
  1430. NAME
  1431.     Wack_ReadBlock() - Read a block from the target machine's memory.
  1432.  
  1433. SYNOPSIS
  1434.     Wack_ReadBlock( APTR address, APTR buffer, ULONG size );
  1435.  
  1436. FUNCTION
  1437.     This function reads a block of memory at the specified address of the
  1438.     target machine's memory, 'size' bytes long into 'buffer'.
  1439.  
  1440.  
  1441. NAME
  1442.     Wack_ReadPointer() - Read a pointer from the target machine's memory.
  1443.  
  1444. SYNOPSIS
  1445.     APTR Wack_ReadPointer( APTR address );
  1446.  
  1447. FUNCTION
  1448.     This function reads and returns the pointer at the specified
  1449.     address of the target machine's memory.  This function is actually
  1450.     the same function as Wack_ReadLong(), just prototyped suitably
  1451.     for pointer retrieval.
  1452.  
  1453.  
  1454. NAME
  1455.     Wack_ReadBlock() - Read a block of the target machine's memory.
  1456.  
  1457. SYNOPSIS
  1458.     void Wack_ReadBlock( APTR address, APTR buffer, unsigned long size );
  1459.  
  1460. FUNCTION
  1461.     This function reads a block of memory from the target machine's
  1462.     memory, at the specified address and of the supplied size.  The
  1463.     result is placed into the buffer you supply.
  1464.  
  1465.  
  1466. NAME
  1467.     Wack_WriteByte() - Write a byte to the target machine's memory.
  1468.  
  1469. SYNOPSIS
  1470.     void Wack_WriteByte( APTR address, unsigned long data );
  1471.  
  1472. FUNCTION
  1473.     This function writes the specified byte value into the specified
  1474.     address of the target machine's memory.
  1475.  
  1476.  
  1477. NAME
  1478.     Wack_WriteWord() - Write a word to the target machine's memory.
  1479.  
  1480. SYNOPSIS
  1481.     void Wack_WriteWord( APTR address, unsigned long data );
  1482.  
  1483. FUNCTION
  1484.     This function writes the specified word value into the specified
  1485.     address of the target machine's memory.
  1486.  
  1487.  
  1488. NAME
  1489.     Wack_WriteLong() - Write a long word to the target machine's memory.
  1490.  
  1491. SYNOPSIS
  1492.     void Wack_WriteLong( APTR address, unsigned long data );
  1493.  
  1494. FUNCTION
  1495.     This function writes the specified long word value into the
  1496.     specified address of the target machine's memory.
  1497.  
  1498.  
  1499. NAME
  1500.     Wack_WriteBlock() - Write a block into the target machine's memory.
  1501.  
  1502. SYNOPSIS
  1503.     Wack_WriteBlock( APTR address, APTR buffer, ULONG size );
  1504.  
  1505. FUNCTION
  1506.     This function writes a block of memory at the specified address of the
  1507.     target machine's memory, 'size' bytes long from 'buffer'.
  1508.  
  1509.  
  1510. NAME
  1511.     Wack_WritePointer() - Write a pointer to the target machine's memory.
  1512.  
  1513. SYNOPSIS
  1514.     void Wack_WritePointer( APTR address, APTR data );
  1515.  
  1516. FUNCTION
  1517.     This function writes the specified pointer value into the
  1518.     specified address of the target machine's memory.  This function
  1519.     is actually the same function as Wack_WriteLong(), just prototyped
  1520.     suitably for writing pointers.
  1521.  
  1522.  
  1523. NAME
  1524.     Wack_FindLibrary() - Locate a library on the target machine.
  1525.  
  1526. SYNOPSIS
  1527.     struct Library *Wack_FindLibrary( STRPTR library );
  1528.  
  1529. FUNCTION
  1530.     This function attempts to locate the named library on the target
  1531.     machine, returning its address if found, or zero if not found.
  1532.  
  1533.  
  1534. NAME
  1535.     Wack_ReadString() - Read a string from the target machine's memory.
  1536.  
  1537. SYNOPSIS
  1538.     ULONG Wack_ReadString( STRPTR address, APTR buffer, unsigned long maxlen );
  1539.  
  1540. FUNCTION
  1541.     This function reads a string from the target machine's memory, at
  1542.     the supplied address and whose length does not exceed the
  1543.     specified maximum.  The result is placed into the buffer you
  1544.     supply.
  1545.  
  1546.  
  1547. NAME
  1548.     Wack_ReadBSTR() - Read a BCPL string from the target machine's memory.
  1549.  
  1550. SYNOPSIS
  1551.     ULONG Wack_ReadBSTR( STRPTR address, APTR buffer, unsigned long maxlen );
  1552.  
  1553. FUNCTION
  1554.     This function reads a BCPL-style string from the target machine's
  1555.     memory, at the supplied address and whose length does not exceed
  1556.     the specified maximum.  The result is placed into the buffer you
  1557.     supply.  Note that the supplied address is a regular pointer, not
  1558.     a BPTR.
  1559.  
  1560.  
  1561. NAME
  1562.     Wack_ReadContextAddr() - Return the SAD context address.
  1563.  
  1564. SYNOPSIS
  1565.     APTR Wack_ReadContextAddr( void );
  1566.  
  1567. FUNCTION
  1568.     This function returns the address of the SAD context, if the
  1569.     target machine is connected via SAD.  If the target machine
  1570.     is connected in some other way, then this function will
  1571.     return zero.
  1572.  
  1573. NAME
  1574.     Wack_Call() - Call a function on the target machine
  1575.  
  1576. SYNOPSIS
  1577.     ULONG Wack_Call( APTR addr );
  1578.  
  1579. FUNCTION
  1580.     This function causes wack (or the remote SAD or Envoy server)
  1581.     to call a function at the specified address.  No parameters are
  1582.     set up.  A0/A1/D0/A1 are scratch.  Any return value from the
  1583.     function is ignored.  This function should be used very
  1584.     carefully, as it can easily crash the machine being debugged.
  1585.  
  1586.  
  1587. When writing external Wack commands, great care must be taken because
  1588. there are potentially two address spaces (that of the host and that of
  1589. the target), and this can be confusing.  The problem is made worse in
  1590. that many bugs may not appear when Wack is run locally.
  1591.  
  1592. Here are some examples to illustrate.
  1593.  
  1594.     struct Window *window;
  1595.  
  1596.     /* Assume window is the address of some window in the
  1597.      * target machine.  We want to read the IDCMPFlags.
  1598.      *
  1599.      * WRONG WAY:
  1600.      *
  1601.      * idcmpflags = window->IDCMPFlags;    /* WRONG */
  1602.      *
  1603.      * This yields the contents of the long word in the
  1604.      * host whose address matches the address of the actual
  1605.      * IDCMPFlags field on the target.
  1606.      *
  1607.      * RIGHT WAY:
  1608.      */
  1609.  
  1610.      idcmpflags = Wack_ReadLong( &window->IDCMPFlags );
  1611.  
  1612.     /* This time we've been careful to actually read the
  1613.      * value from the target.  Alternately, if you need
  1614.      * to peruse the window a lot, you could do:
  1615.      *
  1616.      * struct Window winbuffer;
  1617.      *
  1618.      * Wack_ReadBlock( window, &winbuffer, sizeof( struct Window ) );
  1619.      * idcmpflags = winbuffer.IDCMPFlags;
  1620.      */
  1621.  
  1622. Here is a list walker that correctly reads nodes from the target
  1623. machine.  Assume that MyThing is a custom structure beginning with
  1624. a Node.
  1625.  
  1626.     struct MyThing
  1627.     {
  1628.         struct Node mt_Node;
  1629.         /* other stuff here */
  1630.     }
  1631.  
  1632.     struct List *list;    /* points to list in target machine */
  1633.     struct MyThing *curr;
  1634.     struct MyThing *succ;
  1635.     struct MyThing buffer;
  1636.  
  1637.     for ( curr = Wack_ReadPointer( &list->lh_Head );
  1638.         succ = Wack_ReadPointer( &curr->mt_Node.ln_Succ );
  1639.         curr = succ )
  1640.     {
  1641.         Wack_ReadBlock( curr, &buffer, sizeof( struct MyThing ) );
  1642.         /* Do what you need to buffer.mt_fields */
  1643.     }
  1644.  
  1645. The basic idea should be apparent from these examples.  Unfortunately,
  1646. it does clutter up the coding somewhat, but in time you get the hang
  1647. of it.  Again, if you accidentally read stuff from the host machine's
  1648. memory, you may not notice if Wack is not running over a remote link.
  1649.  
  1650.  
  1651. 8.  Remote Debugging Via Envoy
  1652.     --------------------------
  1653.  
  1654. Envoy is Commodore's Amiga peer-to-peer networking solution.  If two
  1655. Amigas are connected via Envoy, then Wack can be used to remote debug
  1656. from one machine to the other.  First, on the target machine, the
  1657. WackServer program should be run.  This program sits in the background
  1658. awaiting network transactions from the Wack debugger, and services
  1659. those transactions on demand.  Its role is primarily to perform
  1660. low-level reads and writes into the target machine's memory and
  1661. communicate the results back to the host.
  1662.  
  1663. For example, say we wanted to debug a machine called "amy".  On amy,
  1664. you would first type:
  1665.  
  1666.     run WackServer
  1667.  
  1668. Later, from another machine, you would type:
  1669.  
  1670.     Wack amy
  1671.  
  1672. and Wack would be connected to amy via an Envoy link.
  1673.  
  1674. In order to successfully debug a remote machine via Envoy, that
  1675. machine needs to be substantially healthy.  That is to say, certain
  1676. kinds of crashes may preclude Envoy-based remote debugging if the
  1677. WackServer program or the Envoy software is taken out of commission.
  1678. Nevertheless, this form of remote link is very convenient and
  1679. powerful.
  1680.  
  1681.  
  1682. 9.  Remote Debugging Via SAD
  1683.     ------------------------
  1684.  
  1685. SAD is a low-level serial link supported by Exec in the Amiga V39 and
  1686. higher ROM, corresponding to Release 3 and higher of the Amiga OS.
  1687. SAD completely takes over the target machine, and because of that and
  1688. because it is low-level, SAD can be used to debug even a relatively
  1689. scrambled Amiga.  SAD can be invoked on the target machine in one
  1690. of three ways:
  1691.  
  1692. Calling Debug():  If a program on the target machine calls the
  1693. exec.library Debug() function, then the target machine will attempt to
  1694. establish a SAD link over the serial port.  If after about ten or
  1695. twenty seconds no SAD host responds, the call to Debug() will return.
  1696.  
  1697. Guru-in-progress:  At the beginning of a software failure on the
  1698. target computer, the power LED blinks for about three seconds.  If
  1699. during that interval the target computer receives a "delete" keystroke
  1700. (ASCII 127) via the serial port at 9600 baud, the target Amiga will
  1701. drop into SAD mode.  The Wack "CONTEXT" command sends this delete
  1702. keystroke, and thus can be used to "catch" a crashing Amiga.  If the
  1703. target Amiga is not otherwise consuming serial input, the delete
  1704. keystroke can be sent and is buffered on the target computer, which
  1705. means that computer will be caught if ever it crashes.
  1706.  
  1707. NMI:  An Amiga can be configured so that a level-7 interrupt (NMI)
  1708. triggers SAD.  This would permit the addition of a hardware "SAD
  1709. button" to drop the computer into SAD at the press of a button,
  1710. permitting debug-on-demand.  Normally, this feature is not enabled,
  1711. and the NMI-interrupt-handler does nothing (i.e., performs an RTE
  1712. instruction).  To enable the NMI-SAD routine, look at the level-7
  1713. interrupt vector.  If it points to an RTE instruction, increment it by
  1714. two bytes.  That is, the NMI-SAD handler immediately follows the
  1715. do-nothing RTE instruction.  Note that many Amigas (primarily A500 and
  1716. A2000s) get spurious NMI interrupts, in which case the NMI technique
  1717. may not work for you.
  1718.  
  1719. The key issue then is since SAD takes over the target Amiga, how does
  1720. one drop a running Amiga into SAD as needed.  Six executables are
  1721. provided, one for the left, middle, and right mouse buttons of mouse
  1722. ports zero and one.  Running the appropriate executable, then clicking
  1723. that mouse button will trigger SAD, freezing the target machine.  The
  1724. Wack "GO" command can be used to resume normal execution on the target
  1725. machine.
  1726.  
  1727. Alternately, when debugging your own code, you can insert calls to
  1728. exec.library/Debug() at appropriate points.
  1729.  
  1730. Note that using Wack in SAD mode hogs the serial port, which you may
  1731. also be using for debug-text output.  If you trigger SAD, you have ten
  1732. or twenty seconds to get Wack up and responding to it before the
  1733. target machine will give up waiting and resume.
  1734.  
  1735.  
  1736. 10. Description of Files
  1737.     --------------------
  1738.  
  1739. This is the directory structure of the Wack package:
  1740.  
  1741.      tools (dir)
  1742.        DoSAD.0L                         DoSAD.0M
  1743.        DoSAD.0R                         DoSAD.1L
  1744.        DoSAD.1M                         DoSAD.1R
  1745.      demos (dir)
  1746.        arexxdemo.wack                   ShowLVO.wack
  1747.        ShowMember.wack                  ShowStructure.wack
  1748.        StructureOffset.rexx             xwackdemo
  1749.        xwackdemo.c
  1750.   startup.wack                     Wack
  1751.   Wack.doc                         WackServer
  1752.   wack_pragmas.h                   wack_protos.h
  1753.  
  1754. Wack        The Wack debugger itself.
  1755. Wack.doc    This file.
  1756. startup.wack    Example ARexx startup configuration file.  Place in rexx:.
  1757. WackServer    Program to run on target machine for Envoy connection.
  1758. wack_protos.h    Prototypes for functions to be called by Wack extension
  1759.         programs.
  1760. wack_pragmas.h    Pragma definitions for functions to be called by Wack
  1761.         extension programs.
  1762.  
  1763. DoSAD.#?    Programs to trigger a call to Debug() and thus enter
  1764.         SAD mode in response to one mouse button or another.
  1765.  
  1766. arexxdemo.wack    Example Wack ARexx script which prints the name, version,
  1767.         and revision of a library at the current or specified
  1768.         address.
  1769.  
  1770. StructureOffset.rexx    Underlying script to parse the 3.1 Structure.offsets
  1771.         file to determine the offset of a given structure's member.
  1772.         Used by ShowMember.wack, Member.wack, and IsA.wack.
  1773.  
  1774. ShowMember.wack    This script considers the current or specified address
  1775.         to be a structure of the type you specify, and
  1776.         displays the specified member.  Uses the supplied
  1777.         StructureOffset.rexx script and the structure offsets
  1778.         file. 
  1779.  
  1780. ShowStructure.wack    This script shows all members of the specified
  1781.         structure type at the current or specified address.
  1782.         This script allows you to dump any public system
  1783.         structure, even if Wack does not actually know it.
  1784.         Uses the supplied StructureOffset.rexx script and the
  1785.         structure offsets file.
  1786.  
  1787. ShowLVO.wack    ARexx script to determine the actual address that
  1788.         a particular library LVO will jump to.  Uses the
  1789.         include:pragmas/#?_pragmas.h.
  1790.  
  1791. xwackdemo.c    Source code to an example Wack extension program.
  1792.  
  1793. xwackdemo    Example Wack extension program to print the name,
  1794.         version, and revision of a library at the current
  1795.         or specified address.
  1796.  
  1797. rwfile.c    source code to an example Wack extension program.
  1798.  
  1799. rwfile        Example Wack extension program to read a block of
  1800.         memory into a file, or write a file into memory.
  1801.  
  1802.