mon.guide

@database mon.guide
@node main
                 Amiga Monitor v1.65 instructions
                 ================================

  This is a machine code monitor/debugger program for the Amiga.
  The first version was created many years ago, and many of the
  features and commands of the monitor were made similar to those
  of the monitors available for the Commodore 64. However, because
  the Amiga is a quite different machine many new commands and
  features were needed. Later versions of the monitor add many more
  useful features, such as expressions and variables. This version
  is quite close to an actual symbolic debugger as it can read symbol
  table information from executable files and display them in disassembly
  listings. It also has a built-in @{"script language" link Scripts}.

  Topics:

  @{"Starting the monitor" link Starting}
  @{"List of useful things" link Useful}
  @{"List of monitor commands" link CommandList}
  @{"Copyright & author info" link Copyright}
@endnode

@node Starting "Starting the monitor"

  The monitor can be started both from CLI and from workbench. If you
  want to start the monitor from workbench, you must first make an icon
  for it. (starting the monitor from workbench is not recommended,
  because the  programs that are run under the control of the monitor
  may require the CLI environment or else they may wait for workbench
  startup message forever...but you can use IconX to start the monitor
  from workbench as a CLI process)

  The monitor is re-entrant (pure) code and can be made resident (for
  example using the Workbench 1.3/2.0/3.0 resident command or ARP 1.3 ares)

  The monitor works with 68000, 68020, 68030 and 68040 processors.
  However, the assembler/disassembler only understand 68000 instructions.
  Operating system version 2.04 or later is required for reliable operation
  with the 68040 CPU.


  Command Line Arguments:

  options:
   -w <window width>
   -h <window height>
   -o <options>				(see @{"Options Flags" link OptionFlags})
   -s <initial-script-filename>		(see @{"Scripts" link Scripts})

  An optional filename can also be given in the command line.  The monitor
  will try to load the named executable file immediately after starting.
  The filename must be in quotes if it contains spaces. If there is anything
  on the command line after the file name, that will be used as the command
  line for the program loaded to the monitor (a0/d0 registers, see {"@-command" link EnterCmdLine})

  If a `+' character is used before the filename, the monitor tries to load
  symbol information from the file (see also @{"`l'-command" link LoadSeg}).

  See also @{"Using the monitor from a serial terminal" link FromTerminal}.
@endnode

@node FromTerminal "Using the monitor from a serial terminal"

  The monitor can be used from a terminal connected to the Amiga serial
  port. If you want to do this, first set the correct baud rate and other
  serial settings using the preferences program. Then mount AUX:
  if necessary, and start a new CLI/Shell with the command NewShell AUX:
  (or NewCLI AUX:). You get the normal CLI/Shell prompt to the terminal.
  Now simply start the monitor by typing `mon' <cr> to the terminal
  (do not `run' the monitor from the terminal; if you do it, the
  monitor opens a window on the Amiga display). If the terminal is not
  vt100/ansi compatible, you may need to use the `Dumb Terminal'
  @{"option flag" link OptionFlags} (flag #3) to disable some features of the monitor 
  (such as command line editing and history, but you can still delete
  the last character with backspace/delete). Easies way to do that is
  to start the monitor with the command `mon -o4'.
@endnode

@node Useful "List of useful things"

  Some useful things to know:

  @{"Option Flags" link OptionFlags}
  @{"Line editing/Command history" link LineEditing}
  @{"Stopping/restarting output" link StoppingOutput}
  @{"Numbers" link Numbers}
  @{"Expressions" link Expressions}
  @{"Byte strings" link ByteStrings}
  @{"Address ranges" link AddressRanges}
  @{"Tracing trap instructions" link TracingTraps}
  @{"Stack usage" link StackUsage}
  @{"File/directory names" link FileNames}
  @{"Version history" link VersionHistory}
@endnode

@node OptionFlags "Option flags"

  Commands `opt +n' and `opt -n' where `n' is a number between 1 and 4
  can be used to set and reset monitor option flags. Currently five
  flags are implemented:

   - flag #1
      Switches on the narrow disassembly output mode
      (does not show the data as hex digits)

   - flag #2
      Causes characters $a0-$ff to be considered printable in
      @{"`m'" link MemDisplay} and @{"`i'" link AsciiDump} memory dump commands (and `?' command ascii display).

   - flag #3
      This is the `Dumb terminal' mode flag. When this is set on,
      the command line history and editing features of the monitor
      are disabled, and the monitor does not use any vt100/ansi-
      escape sequences. This may be useful when using the monitor
      from a @{"serial terminal" link FromTerminal}.

   - flag #4
      When this flag is set, the monitor echoes each command to its
      output window/file before actually executing the commands.
      This is mainly useful with scripts.

   - flag #5
      Normally the monitor automatically resets the stack pointer
      to point to the normal stack area if it originally was out
      of range in the j/g/w/e/q-commands. This automatic stack reset
      can be disabled with this option flag. This is useful when
      debugging programs that allocate their own stacks and change
      the stack pointer there. The stack pointer can be reset manually
      with the @{"sr-command" link Execute 45}.

  Command `opt' without parameters lists the current flag settins.
  This includes a hexadecimal `flag value' that can be used on
  the command line with the `-o' option to set initial flags when the
  monitor is started (That flag value is simply a bit map of the option
  flags, option #1 is bit #0).
@endnode

@node LineEditing "Input line editing and command line history"

  You can edit the input lines by using the left/right cursor keys to move
  left and right, backspace to delete the character before the cursor and
  del to delete the character under the cursor. You can use the up/down
  cursor keys to get the old command lines (the monitor remembers 10 last
  command lines). Shift-cursor-up gets the last command and enters it
  automatically (you don't need to press <CR>). In assembler mode you can
  press Ctrl-E to edit the assembler instruction currently stored in that
  address.

  These features are not available if the `Dumb terminal' mode is
  selected (see @{"Option flags" link OptionFlags}).  In that case the only editing function
  is deleting the last character with backspace or delete key.
@endnode

@node StoppingOutput "Stopping the output"

  In most cases the output of the monitor can be suspended by pressing SPACE
  or control-S and continued by pressing control-S or SPACE again.
  To permanently stop the output, press Ctrl-C.
@endnode

@node Numbers "Numbers"

  Default number base is hexadecimal but it can be changed with the @{"ba" link NumberBase}-
  command (the argument of the ba-command is always decimal).

  the prefixes used to identify number bases are:
   `$'   hexadecimal
   `@'   octal
   `%'   binary
   `_'   decimal

  Numbers can also be entered as ASCII strings in single quotes, for example:
   'FORM'  -->  hex 464f524d

  See also @{"Expressions" link Expressions}.

@endnode

@node Expressions "Expressions"

  The monitor accepts expressions in most places where you need a number.

  The @{"calculator" link Calculator} (`?') command allows you to directly display
  values of expressions.


  The following operators are available:

     ==  equality test
     !=  inequality test
     <   less than                these tests return 1 if true and 0 if false
     >   greater than             they are most useful in scripts
     <=  less or equal than
     >=  greater or equal than

     +   addition
     -   subtraction
     |   bitwise or
     ^   bitwise exclusive or (xor)
     &   bitwise and
     *   multiplication
     /   division (integer only, truncated)
     %   modulo
     <<  left shift
     >>  right shift

  parenthesis can be used to group the operations in the expressions.

    `*'           represents the `current address'.

    [reg_name]    represents the value of register `reg_name'.

  All calculations are done in 32-bit integer arithmetic. No overflow
  checking is done.

  See also @{"Functions" link Functions} and @{"Variables" link Variables} and @{"Numbers" link Numbers}.

@endnode

@node Functions "Functions"

  The expression parser currently accepts the following built-in functions:

   hunk(n)  --  start address of nth hunk of currently loaded seglist
   hlen(n)  --  length of nth hunk of currently loaded seglist
   hend(n)  --  end address of nth hunk of currently loaded seglist
   nhunks   --  number of hunks in the currently loaded seglist
   abs(x)   --  absolute value of a number  
   peek(a)  --  8-bit contents of a memory location
   peekw(a) --  16-bit contents of a memory location
   peekl(a) --  32-bit contents of a memory location
   avail(x) --  call AvailMem() with the argument x. for example
		avail(0) returns total available memory,
		avail(2) returns available chip memory
		avail($20000) return largest available block.

  The following functions can be used to examine exec library, device,
  resource, task and port lists. Note that the pointers returned by these
  functions may become invalid any time if the library/device/task/port
  is expunged/removed from the system.

  lib("libname.library")   --	returns base address of a named library.
				note that this does not try to load
				the library from disk, it only searches
				ExecBase->LibList.

  dev("devname.device")   --	returns base address of a named device.
				note that this does not try to load
				the device from disk, it only searches
				ExecBase->DeviceList.

  res("resname.resource") --	returns base address of a named resource.

  task("taskname")	  --	returns pointer to named task.

  task(number)		  --	returns pointer to CLI process with the
				given number.

  task(0)		  --	returns pointer to current task (the CLI
				process that runs the monitor)

  port("portname")	  --	returns pointer to the public message port
				names "portname".

  board(manufacturer,product)  --  returns base address of an autoconfig
				board with the specified manufacturer and
				product codes.

  lib, dev, res, task and port-functions fail with error if the requested
  library/device etc. is not found, unless option flag #6 is set. In that
  case they return zero in error situations.

  Function names are not case sensitive.

@endnode

@node Variables "Variables"

  In addition to numbers and functions, variables can be used in
  expressions if they have been previously defined (Symbols in symbol
  hunks of an executable file are automatically defined as monitor
  variables when a file is loaded with the '+' option @{"(see `l' command)" link LoadSeg}.
  Variables are defined with the set-command.  All variable values are
  32-bit integers. Variable names can contain alphanumeric characters and
  underscores (`_'), but they cannot begin with a number. Variable names are
  case sensitive in this version.

  (There are some problems using variables with the assembler.
  Especially variables with names starting with `a',`d' or `s' may
  not be accepted in the assembler because it tries to interpret them
  as register names. You can get around this by using expressions
  like `0+variable')
@endnode

@node ByteStrings "Byte strings"

  Strings are used in the fill command, the hunt command, the modify memory
  command and the assembler directive dc.b .

  Byte strings are series of bytes, represented by numbers or ASCII-
  characters in single quotes or both together separated by commas.

  Note: the single quote itself may be included in a quoted string if it
  is duplicated.
   examples:
    'this is a byte string'
    12,34,56
    ''''  -- this means one single quote
    'both',$0A,'text',10,'and','numbers'

@endnode

@node AddressRanges "Address Range syntax"

  The following forms can be used to specify an address range:

  <Address>..<EndAddress>
  <Address>:<Length>

  Address ranges can be used with the following commands: @{"disassemble" link Disassemble},
  @{"memory dump" link MemDisplay}, @{"ascii dump" link AsciiDump} and @{"memory save" link RWAbs}.

  Address Ranges are new in monitor version 1.65. The commands that use
  them also have older compatible syntax forms.

@endnode

@node TracingTraps "Note about tracing Trap-instructions"

  There is a problem with the walk (trace) command and several instructions
  that cause processor exceptions. These instructions are chk, trap #n,
  trapv and divu/divs (with divisions by zero). If you try to trace these
  instructions, a trace-exception occurs in supervisor-mode, out of the
  control of the monitor and you get a software failure alert with number
  00000009.

  Included with the monitor distribution is a program called patchtrace
  that changes directly the processor hardware trace-exception vector to
  point a new routine that removes the trap-trace problem.

  (The monitor does not support executing code in supervisor mode, so there
  is not normally any reason to trace any of the instructions that can
  cause problems. However, because you can accidentally cause the machine
  to crash by tracing these instructions, the patchtrace-program
  may be useful.)

@endnode

@node StackUsage "Stack usage"

  The monitor allocates 2K of stack for its own use and the rest of
  the stack can be used by the program being debugged. If you need
  a larger stack, you can use the CLI `stack' command before you
  start the monitor.

@endnode

@node FileNames "File/directory names"

  When the monitor requires a file or directory name or the device name
  for the `dev'-command, the name must be in double quotes if it contains
  spaces. Also, some escape processing is done to the filename strings
  and the arguments of the echo-command. See the entry for @{"echo-command" link Echo}
  for details.
@endnode

@node CommandList "List of all monitor commands"

  ??     -- Show a short list of commands.
  ver    -- Show monitor version
  help   -- (also h or the HELP key) Show a help screen.
  x      -- Exit the monitor.

  @{"?      -- Calculator" link Calculator}.

  @{"exec    -- Execute scripts" link Exec}.
  @{"quit    -- Quit a script" link ScriptControlCommands}.
  @{"goto    -- Jump to another position in a script" link ScriptControlCommands}.
  @{"if      -- Conditional execution in a script" link ScriptControlCommands}.

  @{"echo    -- Display text/numbers" link Echo}.

  @{"pokel   -- Write a longword to memory" link Poke}.
  @{"pokew   -- Write a word to memory" link Poke}.
  @{"poke    -- Write a byte to memory" link Poke}.

  @{"ba      -- Set/Show number base" link NumberBase}.

  \          -- @{" Shell command/New shell" link Shell}.
  cls        -- Clear display.
  dir [@{"name" link FileNames}] -- Display disk directory.
  del @{"<name>" link FileNames} -- Delete a file.
  cd  <dir>  -- Change current directory.

  @{"o      -- Redirect output" link Redirect}.

  @{"i      -- Display memory in ASCII" link AsciiDump}.
  @{"m      -- Display memory in hex/ASCII" link MemDisplay}.
  @{"mf     -- Formatted memory display" link FormattedM}.
  @{"mi     -- Information about a memory location" link MemInfo}.
  @{"f      -- Fill memory" link Fill}.
  @{"t      -- Transfer memory" link Transfer}.
  @{"c      -- Compare memory" link CompMem}.
  @{"h      -- Hunt (search) memory" link Hunt}.
  @{":      -- Write to memory" link ModifyMem}.

  @{"opt    -- Set/Show option flags" link OptionFlags}.

  @{"rb     -- Set/Show addr. reg. relative base" link RelBase}.

  @{"!      -- Play digisound" link Digisound}.

  @{"#      -- Correct bootblock checksum" link Checksums}.
  @{"=      -- Correct disk block checksum" link Checksums}.

  @{"<      -- Read disk sectors" link DiskRW}.
  @{">      -- Write disk sectors" link DiskRW}.
  @{"dev    -- Set disk device name" link DiskRW}.

  @{"[      -- Read from file to memory " link RWAbs}.
  @{"]      -- Write from memory to file" link RWAbs}.

  @{"&      -- Allocate memory at absolute address" link MemoryAlloc}.
  @{"(      -- Allocate memory" link MemoryAlloc}.
  @{")      -- Free memory" link MemoryAlloc}.
  @{"sm     -- Show allocated memory" link MemoryAlloc}.

  @{"l      -- Load AmigaDOS executable" link LoadSeg}.
  @{"u      -- Unload executable" link LoadSeg}.
  @{"sl     -- Display segment list" link LoadSeg}.

  @{"@       -- Enter a command line" link EnterCmdLine}.

  @{"r      -- Set/Show registers" link Registers}.

  @{"sr     -- Reset stack" link Execute}.
  @{"g      -- Go/Execute code" link Execute}.
  @{"j      -- Jump to subroutine" link Execute}.
  @{"w      -- Walk/Trace" link Execute}.
  @{"e      -- Extended trace" link Execute}.
  @{"q      -- Quicktrace" link Execute}.
  @{"z      -- Skip instruction" link Execute}.

  @{"b      -- Set breakpoint" link Breakpoints}.
  @{"br     -- Remove breakpoint" link Breakpoints}.
  @{"bl     -- List breakpoints" link Breakpoints}.

  @{"set    -- Set/Show variables" link Set}.
  @{"cv     -- Clear all variables" link Set}.

  @{"d      -- Disassemble" link Disassemble}.
  @{"a      -- Assemble" link Assemble}.

  @{"vt     -- Show tasks" link ListThings}.
  @{"vl     -- Show libraries" link ListThings}.
  @{"vd     -- Show devices" link ListThings}.
  @{"vr     -- Show resources" link ListThings}.
  @{"vp     -- Show public message ports" link ListThings}.
  @{"vs     -- Show public semaphores" link ListThings}.
  @{"vi     -- Show interrupts" link ListThings}.
  @{"ve     -- Show Autoconfig devices" link ListThings}.

@endnode

@node NumberBase

ba [num]  --  Set/show current number base

  ba without parameters displays the current number base. ba <num> sets
  the base to <num> which is always decimal. this is the default base
  used in number input if no base prefix is specified. initially it is 16
  (hexadecimal).
@endnode

@node FormattedM "Formatted Memory Display"

mf -- Formatted memory display

 Usage:
  mf "formatstring"
  mf <addr> "formatstring"
  mf <addr> <endaddr> "formatstring"

  This command displays memory in user-specified format. The format string
  can contain normal text that is printed directly and c-printf-style
  format specifiers. The following format specifiers are currently supported:
    %b  -- hex byte
    %w  -- hex word
    %l  -- hex longword
    %db -- decimal byte
    %dw -- decimal word
    %dl -- decimal longword
    %a  -- current address (in hex)
    %c  -- ASCII character (printable ones only, others show as `.')
    %s  -- string (longword pointer to a NUL-terminated string)
    %x  -- BCPL string (longword pointer to a string with length byte)
           (non-printable characters in strings are printed as `.'
            Strings longer than 100 characters are truncated)

  The escape sequences described in the @{"echo" link Echo}-command entry
  can also be used in the format string.

  Note1: words and longs that are displayed must be at even addresses. If
  the current address is odd when a word or longword value is going to be
  displayed, the address is incremented to the next even address and
  an asterisk is printed as a warning to the user.

  Note2: a space is required between this command and its arguments.

  Example:

  mf lib("foobar.library") "Succ=%l Pred=%l Type=%b Pri=%b Name=`%s'"

  This displays the contents of the node structure in the library
  structure of foobar.library.

@endnode

@node AsciiDump

i -- Display memory in ASCII
 Usage:
  i                   -- display a screenful from current address
  i <addr>            -- display a screenful from <addr>
  i <addr> <end-addr> -- display from <addr> to <end-addr>
  i <addr>..<end-addr> or m <addr>:<length> (see @{"address ranges" link AddressRanges})

 If the ASCII dump was started inside a hunk of currently loaded
 executable, it automatically stops at the end of that hunk.
@endnode

@node MemDisplay

m -- Display memory in hex and ASCII
 Usage:
  m                   -- display a screenful from current address
  m <addr>            -- display a screenful from <addr>
  m <addr> <end-addr> -- display from <addr> to <end-addr>
  m <addr>..<end-addr> or m <addr>:<length> (see @{"address ranges" link AddressRanges})

 If the memory display was started inside a hunk of currently loaded
 executable, it automatically stops at the end of that hunk.
@endnode

@node MemInfo

mi <addr> -- Display information about memory locations

  The mi-command tells you if the address `addr' is in the system memory
  list, is it allocated or not and is it inside any of the hunks
  of the currently loaded segment.
@endnode

@node ModifyMem

: -- Modify memory

 Usage:
  : <addr> <string>

  Puts the @{"<string>" link ByteStrings} in memory at <addr>
  This can also be done with the command `a <addr> dc.b <string>'
  (but then <addr> must be even)
@endnode

@node Transfer

t -- Transfer (move) memory

 Usage:
  t <start-addr> <end-addr> <destination-addr>

 The command works correctly even if the source and destination memory
 blocks overlap. (if destination is at a higher address than source,
  the block is moved backwards, starting at the end)
@endnode

@node Fill
f -- Fill memory with a byte or a string of bytes
 Usage:
  f <start-addr> <end-addr> <byte>   ;fills with <byte>
  f <start-addr> <end-addr> <string> ;fills with the string

 Example:
  f $60000 $601FF $4E,$71 fills from $60000 to $601FF with NOP-instruction
@endnode

@node Hunt

h -- Hunt (find) string in memory

 Usage:
  h <start-addr> <end-addr> <string>

  Displays all addresses in the range <start-addr>..<end-addr>
  where the @{"<string>" link ByteStrings} is found.
@endnode

@node CompMem

c -- Compare memory

 Usage:
  c <start-addr> <end-addr> <string>

  Displays all addresses in the range <start-addr>..<end-addr>
  where is corresponding byte in the destination block is different from
  the source.
@endnode

@node Calculator

? [expr]  --  Calculator

  Displays the value of the @{"expression" link Expressions} in hex, decimal, octal, binary
  and ASCII characters.  If the number is negative, displays it as signed
  and unsigned.
@endnode

@node Redirect

o -- Redirect output

 usage:
  o name -- redirects monitor output to file or device `name'
  o      -- returns to normal, output comes to the monitor window

 For example, to send the output to printer use `o PRT:'.
 If the file specified in the `o'-command already exists, the monitor
 output will be appended to the end of the file.
@endnode

@node Set

set [var[=expr]] -- Set/show variables

  The set-command without parameters displays the values of all currently
  defined variables. The form `set var=expr' sets the value of `var' to
  the value of the expression. `set var' removes the definition of `var'.

cv -- Clear all variables

  Asks if you really want to do it, answer `y' to clear them.
@endnode

@node Assemble

a -- Assemble

 usage:
  a         : assemble to the current address
  a <addr>  : assemble to <addr>
  a <addr> <instruction> : assemble <instruction> at <addr>

  After assembling an instruction the monitor prompts with the address of
  the location following the instruction just assembled and waits a new
  instruction to be entered. To exit this mode, simply press <CR> without
  entering an instruction. To edit an existing instruction, press Ctrl-E when
  the monitor is waiting an assembler instruction.

   The assembler understands all the normal 68000 instructions and also
  the `pseudo-instructions' dc.b, dc.w and dc.l, which can be used to
  directly put data in memory.
   See also @{"Some notes about the assembler" link AssemblerNotes}.
@endnode

@node AssemblerNotes "Some notes about using the assembler"

   When entering assembler instructions which have an implicit size, no
   size specifier is allowed in the monitor assembler. These instructions
   are for example btst, bchg, bclr, btst, lea, move to/from sr/ccr/usp,
   andi/ori/eori #data,sr/ccr Scc (set according to condition),
   abcd/sbcd/nbcd and shifts with memory operands.

   Instructions that can have different sizes must have the size specifier,
   there is no `default size' (normal assemblers use a default size of word.
   The omission of default size is intentional, because it is so easy to
   forget the size specifier when you really don't mean the size to be word).

   Branch instructions with no size specifier or the .l-specifier assemble
   to normal (16-bit offset) branches, if given the .s-size specifier they
   assemble to the short form (8-bit offset). The dbxx-(decrement and branch)
   -instructions allow no size specifier.

   The assembler converts add/sub/and/or/eor with immediate data source
   automatically to adda/addi/subi/andi/eori. It does not convert move or
   add/sub to the quick form nor does it convert branches automatically to
   the short form. You must specify those yourself (so you must use the
   moveq/addq/subq- instructions or specify the size .s to branches
   as noted above). Also cmp-memory instruction must be entered as cmpm,
   the assembler does not convert cmp (an)+,(an)+ to cmpm.

   The above conversion rules do not apply to andi/ori/eori with status
   register or condition code register. In these cases you must enter the
   instruction as andi/ori/eori (don't leave the `i' out). Also, you
   can't enter any size specifier in this case.

  (In fact I want to make the assembler more flexible than it currently is,
  but that is not an easy task...maybe in some future version...)
@endnode

@node Disassemble

d -- Disassemble

 Usage:
  d                   -- disassemble a screenful from current address
  d <addr>            -- disassemble a screenful from <addr>
  d <addr> <end-addr> -- disassemble from <addr> to <end-addr>
  d <addr>..<end-addr> or m <addr>:<length> (see @{"address ranges" link AddressRanges})

 The disassembles supports only 68000 opcodes (with one exeception, 68020+
 32-bit long branches are supported).

 If the address of a disassembled instruction is inside a hunk of currently
 loaded executable file, the hunk number and offset are shown as follows:

H0+$000 07A8D220 2648                   movea.l a0,a3
 ^   ^       ^    ^                       ^
 |   |       |    \- instruction bytes    \ instruction
 |   |       |
 |   |       \- address
 |   |
 |   \- offset
 |
 \- hunk number

 If the disassembly was started inside a hunk of currently loaded executable,
 it automatically stops at the end of that hunk.
@endnode

@node Registers "Show/Change registers"

r -- Show or change registers

 Usage:
  r        -- displays all registers
  r <reg>=<number> or
  r <reg> <number> -- puts the value <number> into <reg>

   examples:
    r D0=0
    r A5 $60000
@endnode

@node Breakpoints "Set/Remove/List Breakpoints"

b -- Set breakpoints

 Usage:
  b <addr> [count] -- sets a breakpoint to <addr> with optional count

   Breakpoints are implemented by putting an illegal opcode ($4AFC) in the
  breakpoint locations when a G or J command is given. After returning to
  the monitor the original contents of the breakpoints are restored. This
  means that you can not put breakpoints to ROM (but you can trace ROM code).

  If no count is specified, default count of one is used. That means that
  the execution of a program stops and control returns to the monitor
  immediately when the breakpoint is encountered. If the breakpoint has
  a count that is greater than one, then control returns to the monitor
  when the breakpoint has been `hit' as many times as the count is.

  Breakpoint counts do not work with the `q' (quicktrace) command.


br -- Remove breakpoints

 usage:
  br <addr> -- removes the breakpoint at <addr>
  br #<num> -- removes breakpoint number <num>
  br all    -- removes all breakpoints

bl -- List breakpoints

 Usage:
  bl -- display a list of all breakpoints.

The g, j, w, q and e-commands use the current program counter value
(displayed with the r-command) if you don't give them an address.
The stack pointer is reset and a return address to the monitor is
put in the stack if the stack pointer is out of range. This automatic
stack pointer reset can be disabled with @{"option flag" link OptionFlags} #5. The stack
pointer can be manually reset with the 'rs'-command.
@endnode

@node Execute "Go/Jump/Walk/ExtTrace/QuickTrace/Skip"
g [addr] -- Go (execute machine code)

j [addr] -- Jump to subroutine

 As g-command but pushes return address first. this return address will
 give control back to the monitor when rts-instructions is executed.

w [addr] -- Walk (single step trace)

 This single steps code using the 68000 processor built-in trace mode.
 It works even with ROM code (but the e-command doesn't).

 (This command does not activate breakpoints)

e [addr] -- Extended trace (execute with temporary breakpoint)

 This command allows you to execute subroutine calls in full speed
 when tracing and you don't need to manually place a breakpoint after
 the calls. when the e-command is executed, a temporary breakpoint is
 placed in the location after the instruction to be executed. this break-
 point is automatically removed after the control returns to the monitor.

 The e-command can be used instead of the w-command to trace most of the
 instructions, but it is recommended that you use the w-command for
 tracing and when tracing code until you get to a subroutine call
 instruction. then enter the e-command and the subroutine is executed
 normally, but after that the monitor interrupts execution to the
 invisible breakpoint.

 Note that if you use the e-command in an address that contains a flow-
 control instruction, the code flow may never come to the temporary
 breakpoint. Normally it is better to trace using the w-instruction,
 but for example, system calls cannot always be traced, and even if
 they can, you most probably don't want to do it.

q [addr] -- QuickTrace (execute until flow-control instruction)

 This command executes code one instruction at time (in the 68000 trace mode)
 until it encounters a program flow control instruction (jump, branch,
 subroutine call or return, trap).

z -- skip current instruction

 This command can be used to advance the PC register over one instruction.
 Note that this does not actually execute or trace code, it only changes
 the monitor internal register values. An address can also be given as
 a parameter to this command but it is normally not useful (the current
 PC value will normally be used).

sr -- reset stack pointer.

 This resets the stack pointer to the value it has when monitor
 has just been started.

Note: there is no easy way to run BCPL programs (CLI commands) or other
programs that use the internal BCPL library from the monitor.
@endnode

@node EnterCmdLine "Enter command line"

\@ -- Enter command line

 Usage:
  @ [command line].

  If you don't specify a command line (enter only @<cr>) then the monitor
  will prompt for command line. The command line will be put in a special
  memory area and the register a0 will contain pointer to the string and
  d0 will contain length of the string (with a linefeed appended to end).
  If you want an empty command line, enter the @-command without parameters
  and press return on the `Cmdline>'-prompt. The purpose of this command
  is to specify a command line for the program that you are running from
  the monitor. If you start the monitor with a filename, anything after
  the filename is automatically used as the command line.

  The dos.library 2.0+ ReadArgs()-routine reads arguments from the standard
  input filehandle buffer. Monitor versions 1.60+ set the command line
  so that it works with ReadArgs(). Older versions of the monitor didn't
  support ReadArgs().
@endnode

@node LoadSeg "Load/Unload AmigaDOS executable"

l -- Load AmigaDOS executable

 Usage:
  l [+] @{"<name>" link FileNames} -- loads the executable file @{"<name>" link FileNames} in memory and displays
    the starting address of the first hunk, also sets PC to this address.
   only one executable file be loaded at the same time. Before loading a
  new file you must unload the old file with the u-command.  To display
  the starting & ending addresses of all the hunks in the file, use the
  sl-command.

  Command `l + <name>' loads symbol table and hunk type information in
  addition to the actual file hunks. Those symbols are like the variables
  defined by `set' command, but they also have a hunk number associated with
  them (it shows in square brackets in the `set' listing). Also, the symbols
  are automatically removed when the file is unloaded with the `u'-command.

  The command line (see @{"@-command" link EnterCmdLine}) is initialized as empty when this
  command is executed.

  Overlays are not supported.

u -- Unload AmigaDOS executable
 Usage:
  u  -- unload the currently loaded executable file.
        symbol information loaded by `l +' is removed by this command.

sl -- Segment list

 Usage:
  sl -- displays the starting & ending addresses and length of each hunk
  of the currently loaded file. If the `l +' command has been used to
  load the file, also the type of each hunk is displayed (including chip/fast
  memory types and data/bss byte counts of split data/bss hunks).
@endnode

@node RelBase "Set base address of address register relative symbols"
rb -- set base address for address register relative symbols

 Usage:
  rb addr  --    sets base address of a4-relative addressing to addr.
		 typically this is in the beginning of the data hunk
		 of a program with programs compiled with Lattice/SAS C.
  rb addr reg -- as above but allows selection of address register
                 other than a4.
  rb 0     --    removes the base address setting.
  rb       --    displays current base address setting.

  When the base address setting is active, the disassembler will check all
  xx(a4) (or other addr reg, if selected) addressing modes and if
  baseaddr + offset equals a symbol, the symbol is displayed.
@endnode

@node MemoryAlloc "Allocate/Free memory"
( -- Allocate memory

 Usage:
  ( <length>        -- allocate <length> bytes any type of memory
  ( <length> C      -- allocate <length> bytes of chip memory

  Displays the start & end addresses of the allocated memory block.
  Sets current address ('*') to the address of the allocated memory
  block. This can be used to assign the block address to a variable
  (see @{"Expressions" link Expressions} and the @{"set-command" Link Set}).

& -- Allocate absolute memory location

 Usage:
  & <addr> <length> -- allocate <length> bytes at <addr>

) -- Free memory

 Usage:
  ) <addr> -- frees the memory block starting at <addr>
  ) #<num> -- frees memory block number <num>.
  ) all    -- frees all the memory allocated with the (- and &-commands

sm -- Show allocated memory

 Usage:
  sm -- display all memory blocks allocated with the (- and &-commands
@endnode

@node RWAbs "Read/Write files"
[  -- Read file to memory

 Usage:
  [ <addr> @{"<name>" link FileNames} -- reads the file <name> to memory starting at <addr>

]  -- Write memory to file

 Usage:
  ] <addr> <length> @{"<name>" link FileNames} -- creates a file named <name> and writes <length>
 bytes of memory starting at <addr> to the file.
@endnode

@node DiskRW "Read/Write disk sectors"
<  -- Read disk sectors

 Usage:
  < <addr> <unit> <start-sector> <number-of-sectors>

 Reads <number-of-sectors> sectors from the disk in unit <unit> to memory
 starting at <addr>. <unit> is the unit number to be used in OpenDevice().
 with the default device (trackdisk.device) units 0..3 correspond DOS
 devices DF0: -- DF3:

 the read destination address does not need to be in chip memory.

>  -- Write disk sectors

 Usage:
  > <addr> <unit> <start-sector> <number-of-sectors>

 Writes <number-of-sectors> sectors to the disk in unit <unit> from memory
 starting at <addr>. <unit> is the unit number to be used in OpenDevice().
 with the default device (trackdisk.device) units 0..3 correspond DOS
 devices DF0: -- DF3:

 The write source address does not need to be in chip memory, even when
 using 1.3 trackdisk.device.

dev -- set/show current disk device

 Usage:
  dev  --  show current disk device
  dev devname -- set current disk device

 devname is an exec device name, given without quotes and with the `.device'-
 suffix. for example, if you have a 2090 hd controller, you can
 set it as the default disk device with the command: dev hddisk.device
 Note that the disk read/write commands work in the exec device level and
 know nothing about hard disk partitions. Be careful if you use the monitor
 to edit hard disk sectors! Note also that actual disk IO buffers used by
 the monitor are always in chip memory.

 The current disk device is used by the disk read/write commands (`<' and `>').
@endnode

@node Checksums "Correct disk block/bootblock checksums"

=  -- Corrects an OFS disk block checksum

 Usage:
  = <addr> -- if there is a DOS-format disk block read into memory
 at <addr>, calculates the correct checksum for the block and stores
 it in the block. Displays old and new checksums. This command is useful
 if use use the monitor as a disk editor. <addr> must be even.

 Extended usage: = <addr> <len> <offs>
 where <len> is block length to be checksummed and <offs> is the offset
 of the checksum longword from the start of the block. The checksum is
 calculated to that the sum of the longwords in the block is zero.

 Checksum for hard disk RigidDiskBlocks can be calculated with:
 = <addr> $100 $08


#  -- Corrects bootblock checksum

 Usage:
  # <addr> -- If there is a disk bootblock (2 disk blocks, 1024 bytes)
 read into memory at <addr>, calculates a new checksum for the bootblock
 and stores it in the bootblock (in memory). Displays old and new
 checksums. <addr> must be even.

 Extended usage: # <addr> <len> <offs>
 where <len> is block length to be checksummed and <offs> is the offset
 of the checksum longword from the start of the block. The checksum is
 calculated to that the sum of the longwords with carry in the block
 is $ffffffff.

 Checksum for pre-2.0 kickstart images (256K) can be calculated with:
 # <addr> $40000 $3ffe8
 and for 2.0+ kickstart images (512K) with:
 # <addr> $80000 $7ffe8

@endnode

@node Digisound "Play digitized sound"

!  -- Play digisound

 Usage:
  ! <addr> <length> <period> [count]

 Plays sound <length> bytes starting at <addr> and using sampling period
 <period>. the sound repeats <count> times or until you stop it by
 pressing Ctrl-C. <addr> must be in CHIP memory!.
@endnode

@node Shell

\ -- Command/ New Shell
  Usage:
   \ shell_command  -- executes one shell command.
		       the command should be in quotes if
		       it contains spaces (see note about @{"file names" link FileNames}).
   \                -- starts new shell with `NewShell' or `NewCLI'

  This uses the AmigaDOS Execute() call on 1.3, so it requires the `Run'-
  command to be in the C:-directory in AmigaDOS versions before 1.3.2
  (on AmigaDOS 2.0 it uses the new System() call)
@endnode

@node ListThings "Show tasks/libraries/devices/etc."

vt -- show tasks

  Shows the addresses, types, states and priorities of all tasks currently
  in the system (on the exec TaskWait & TaskReady lists and the current task)

  Type: t - task, p - process, c - CLI process
  State: w - waiting, r - ready, c - current

vl -- show library list

  Shows the addresses, names, versions & revisions and open counts of
  all libraries on the exec library list.

vd -- show device list

  Shows the addresses, names, versions & revisions and open counts of
  all devices on the exec device list.

vr -- show resource list

  Shows the addresses and names of all resources on the exec resource list.

vp -- show port list

  Shows the addresses, SigBits, mp_Flags-fields and names of all public
  message ports currently in the system (Note: the flags-field is
  in hexadecimal, it was in decimal in some older versions)

vs -- show semaphore list

  Shows the addresses and names of all public SignalSemaphores currently
  in the system.

vi -- show interrupts

  Shows information about the interrupt handlers and servers in the system.

ve -- show autoconfig device list

  Lists information about the autoconfig boards/devices in the system.
  The ConfigDev structure address, board hardware address, manufacturer and
  product numbers, size of board in KBytes and cd_Flags/er_Flags values
  are shown. The ConfigDev and board addresses and the flags are in
  hexadecimal, the other numbers are in decimal.
@endnode

@node Echo "Echo -- display text and/or numbers"

echo -- display text and/or numbers
  Usage:
    echo string | [$][expr] [string | [$][expr] ...]

  Writes the string(s) given in the command to the monitor output
  window/file. Strings can be quoted with double quotes. Also,
  the `\'-character can be used as an escape character. The following
  escape sequences are available:

   \n -> newline/linefeed
   \r -> carriage return
   \t -> tabulator
   \e -> the ASCII Escape character (0x1b, 27 decimal)
   \\ -> `\'
   \xnn where nn are hex digits -> ascii code nn

  These escape sequences can also be used whenever file names are given
  to the monitor.

  Numbers/expressions can be output by putting them in square brackets.
  [expr]  -- displays expression in decimal
  $[expr] -- displays expression in hexadecimal

  The echo-command is most useful in script files.
@endnode

@node Exec
exec -- execute a script file
  Usage:
    exec filename

  Executes the given script file. for more information, see @{"Scripts" link Scripts}.
@endnode

@node Poke "poke/pokew/pokel -- write to memory"

poke, pokew, pokel  --  write to memory

  poke <addr> <byteval>
  pokew <addr> <wordval>
  pokel <addr> <longval>

  Similator to corresponding BASIC commands. These commands write data to
  a memory location. Poke writes a byte (8-bit), pokew writes a word (16-bit)
  and pokel writes a longword (32-bit). Note that there is no comma between
  the address and value parameters.
@endnode

@node Exit

x -- Exit
  Cleanup and exit the monitor. This frees all the memory allocated
  with ( and & commands and closes redirection file, if open.

@endnode

@node Scripts "Scripts"

  The Amiga monitor versions 1.52 and above have a built-in script language.
  All normal monitor commands can be executed from scripts, and the are
  additional commands for controlling script execution.
  Scripts are started with the @{"exec" link Exec} command that can also be used inside
  scripts, so scripts can be nested (and memory availability is the only
  limit of the nesting depth).

  All lines in a script file beginning with a semicolon (;) are treated as
  comments and ignored by the monitor.

  See also @{"Script control commands" link ScriptControlCommands}.

@endnode

@node ScriptControlCommands "Script Control Commands"

quit -- quit executing a script and return to the previous script or
        keyboard input.

goto label  --  go to a specified label in a script.
        Labels must be in the beginning of a line and begin with a period (.)
        An optional colon can be in the end of the label name. The period
        and colon are not actually parts of the label name, so they are
        not included in the goto-command.

 Example:

   goto foobar
   ... other script commands

.foobar:	echo "This is the label `foobar'"

if <expr> <command> -- conditional execution
        Executes the <command> only when expression <expr> is non-zero.
        More complex conditionals can be constructed by using if and goto
        together.

  Example:

set counter = 1
.loop
echo "counter is" [counter]
set counter=counter+1
if counter <= _10 goto loop

@endnode

@node VersionHistory "Version history:"

1.65 ->
  - loading symbols is a little faster (but not much, memory
    allocation limits the speed more than disk i/o)
  - current address is set to the starting address of
    '[' and '<' commands.
  - hunk number/offset is shown in disassembly output.
  - '&' (alloc-abs) doesn't allow odd addresses.
  - memory list shows block numbers, and they can be used in
    the mem-free (')' command.
  - added 'i'-command.
  - added AmigaGuide-format document.
  - address range syntax addr..endaddr and addr:length

1.64 ->
  - now works again on OS 1.3. there was
    a bug in version checking...

1.63 ->
  - now should properly count labels when displaying
    disassembly one screen at a time.

1.62 ->
  - fixed a problem with breakpoints on 68040 machines

1.61 ->
  - breakpoint list shows counts correctly.
  - better error messages with b and br commands.

1.60 ->
  - command line setting from monitor command line works again
    (was broken in 1.59)
  - lib/dev etc. now return zero on error only if option flag #6 is set,
    otherwise they fail.
  - added board()-function to the expression parser.
  - disassembler now displays short branches as '.b' and 68000 long
    branches as '.w'. It also understands 68020+ long branches (.l)
  - now supports ReadArgs() command line parsing.
  - rb-command now works properly

1.59 ->
 - added 've'-command (list autoconfig devices)
 - 'no auto stackreset'-option flag and 'rs'-command to reset
   the stack pointer
 - automatically initializes a0/d0 to point to an empty
   command line when 'l'-command is used to load a new executable file.

1.58 ->
 - changed window position/size logic. now monitor window should
   open to the visible part of a bigger-than-display screen.

1.57 ->
 - memory display displays only the requested memory block
   (the last line is not always full)

1.56 ->
 - memory display stops at end of hunk (disassembly already did that)
 - memory allocation error now stops script execution
 - added %s and %x formats to the mf-command

1.55 ->
 - uses TC_TrapData instead of TC_UserData again...
 - now the `(' command cannot allocate negative amounts of memory...
 - now the assembler understands `.b' as short branch specifier and
   `.w' as long branch specifier.
 - now frees memory properly in `u' command.

1.54 ->
 - added poke[w,l] commands

1.53 ->
 - better error reporting with scripts.

1.52 ->
 - scripts (exec/quit/if/goto/echo commands)
 - \-command can be used to execute any cli/shell command.

1.51 ->
 - no longer lists bss hunks as split in strange ways (one lsl.l #2,d0 was
   missing in version 1.50)

1.50 ->
 - now mf-command requires space after command, else -> m fxxxx
 - show seglist displays info about split data/bss hunks
 - internal source reorganization

1.49 ->
 - hunk type display also shows chip/fast
 - some changes in symbol handling
 - internal source reorganization
 - disassembly stops at hunk end

1.48 ->
 - address register relative symbol support (rb-command)

1.47 ->
 - symbol support
 - variables now case sensitive
 - hunk type display in `sl'-command

1.46 ->
 - added breakpoint counts.

1.45 ->
 - small change in help text.
1.44 ->
 - added task/library/device/resource/port/semaphore list viewing commands.

1.43 ->
 - added formatted memory dump command
 - now gives error message if cannot allocate audio channels in digisound
   play command.
 - display can be stopped/started with ctrl-s/ctrl-q
 - spaces can be used in `set register' command before the equal sign.

1.42 ->
 - better option handling
 - understands 2.0 shell window close gadget
 - redirection to file now appends if possible
 - modulo operator now `%'

1.41 ->
 - fixed a bug that prevented some assembler instructions working.

1.40 ->
 - cd works correctly again
   (in 1.37..1.39 it ignored first letter of dir name...)

1.39 ->
 - interrupting `c' or `h' commands no longer causes error conditions.
 - added option flag 2 to select whether characters $a0-$ff are printable
   in `m' command memory dump.

1.38 ->
 - return from `j' or `g' commands with rts now works
   (was a major bug in 1.37)
 - input routine no longer acts strangely if shift-cursor-down
   or ESC-cursor/function/help is pressed.
 - command line automatically set if file name given on the monitor command
   line.
 - many little changes in assembler. most of these not visible to the user.

1.37 -> lots of new features...
 - major source code reorganization
 - extended checksum commands
 - calculator `ascii' output
 - memoryinfo displays hunk offsets
 - breakpoint numbers
 - added `port()' to expression parser

1.34 ->
 - added `narrow disassembly' option.
 - digisound player now defaults to play the sample once.

1.32 ->
 - now opens own window only if started with `run' or window width and
   height are given on the command line. can be used from serial terminal
   with AUX: shell.

1.31 ->
 - it is now not possible to accidentally try to assemble code to
   an odd address.

1.30 ->
 - many internal changes: global variable base register changed, uses
   new library call macros...

1.29 ->
 - added lib(), dev(), res() and task() to expression parser.

1.28 ->
 - modified patchtrace to work also when vector base is relocated.
 - small changes in initial window placement and size

1.27 ->
 - disk block/bootblock checksum functions and jump/go/trace etc. now
   check properly for odd addresses.
 - `odd address'-error message
 - skip instruction-command
 - Exit() now returns control back to the monitor.

1.26 ->
 - added hend() and nhunks-functions to the expression parser.
 - added command line options for window width and height
 - a file name to LoadSeg() can be given in the command line
 - new filename parse routine, now names with spaces in
   them must be in quotes

1.25 ->
 - (internal change) now uses TC_Userdata instead of TC_TrapData because
   TC_TrapData is marked as private in some prerelease 1.4/2.0 includes.
 - `\'-command now first tries to start a shell, then a CLI.
 - disk read/write commands can be used with hard disks etc.
 - fixed condition code register setting with go and jump commands.

1.24 ->
 - corrected a small bug in the assembler/disassembler mnemonic tables
   (trap and tas-instructions were accidentally exchanged...)

1.23 ->
 - quicktrace-command
 - now reserves separate areas of stack for the monitor itself and
   the program being debugged.

1.22 ->
 - better handling of stack pointer with jump & go-commands
 - extended trace command
 - memory display can be used at odd addresses
 - generally cleaned up the source code
 - variables are now case-insensitive.

1.20 ->
 - added the `[register]'-syntax in the expression parser

1.19 ->
 - disassembler now uses new routines. this makes the monitor
   executable little smaller than 1.17

1.17 ->
 - monitor is now re-entrant and can be made resident
 - transfer no longer crashes if you transfer from location zero
 - default base is again hexadecimal

1.15 ->
 - some minor bug fixes in assembler
   (move sp,usp or exg Rx,sp did not work)
 - `memory info'-command
 - underscores are allowed in variable names
 - variable list is kept in alphabetical order

1.12 ->
 - expressions can now be used instead of numbers. also included
   calculator-command.
 - variables can be used in expressions.
 - user-defineable default number base, default is now decimal.
 - hunt-command no longer finds anything in the monitor code/data areas
 - show seglist now displays hunk numbers
 - chip memory allocation syntax has been changed.

1.08 ->
 - the monitor works ok with 68010/68020 processors. older versions
   left sometimes extra data in supervisor stack.

1.07 ->
 - The disassembler and assembler handle exg Dn,An correctly
   (previously the data and address register numbers were reversed)
 - The disassembler no more displays any invalid codes as valid
   instructions (On the 68000 processor, of course. The monitor does
   not currently support 68010/68020 extra instructions).
 - The pc-relative indexed addressing mode now works with the assembler.
 - Some little bugs were fixed in the assembler.
    + And/or-instructions work with a pc-relative source operand. 
    + cmpm works with all sizes
    + most(if not all...) of the bugs that caused the assembler to
      assemble invalid instructions have been fixed.
 - `sp' can be used instead of `a7' in the assembler and the disassmbler
   displays a7 as `sp'.
 - The assembler now unserstands blo/bhs, slo/shs and dblo/sbhs
   and assembles them as bcs/bcc, scs/scc and dbcs/dbcc
 - The disassembler displays address-register relative offsets and short
   absolute addresses as signed numbers.
 - The monitor works now better with 60-column default font (TOPAZ60).
 - Disk read/write commands can be used with non-chip memory
 - Play digisound command has an optional parameter to specify
   how many times the sample is played.
 - A new command has been added to specify a command line for programs
   executed under the control of the monitor.
 - Breakpoints work even if you jump into the code at to breakpoint.
   The breakpoint does not activate until the instruction at the break
   position is executed, so you don't get immediately interrupted.
   (internally the monitor uses the trace-exception to skip the breakpoint
   at the first time...)

1.06 and older...
 - prehistoric versions...

@endnode

@node Copyright "Copyright, distribution and Author info"

  Amiga Monitor v1.65 is Copyright © 1987-1994 by Timo Rossi. The monitor
can be freely distributed non-commercially. This document file and the
`patchtrace'-program should be included in the distribution. Distribution
on freeware CD-ROMs such as the Fred Fish CDROM series and the AmiNet CD-ROM
is also allowed.

Send suggestions, bug reports etc. to:

  Timo Rossi
  Mattilankatu 40 A 4                E-mail:
  40600 Jyväskylä                 trossi@jyu.fi
  FINLAND

@endnode