Amiga ISO Collection/AmigaUtilCD2.iso/Misc/MAXONNOG2NOGURU.DMS/in.adf/sim.doc

Text File | 1992-12-28 | 103.6 KB | 3,084 lines

-------------------------------------------------------------------------------

                                  S.I.M.

                        System-Independent Monitor
                               Version 1.68

                Copyright © 1990/1991/1992 by Stefan Walter
                            ALL RIGHTS RESERVED

-------------------------------------------------------------------------------



            The User Manual, refering to version 1.68 of S.I.M.,
                          distributed with NOG2.






                                 CONTENTS
                                 ========


1.      Introduction
--------------------

        1.1     Welcome to SIM
        1.3     Disclaimer
        1.2     About this Documentation

2.      Getting aquainted with SIM
----------------------------------

        2.1     What is SIM?
        2.2     Qualifications, Requirements and Limitations
        2.3     The 68020+ Version
        2.4     Configuring SIM
        2.5     The SIM Program

3.      Some words about...
---------------------------

        3.1     The Display
        3.2     Breakpoints
        3.3     Trace
        3.4     The Keyboard
        3.5     Disk Access
        3.6     Files
        3.7     Breaking
        3.8     The Actual Address
        3.9     The Matchbuffer
        3.10    Command History
        3.11    Traps
        3.12    Functionkeys
        3.13    SIM and the Hardware
        3.14    The Colors Red and Yellow
        3.15    Printer Support
        3.16    Memory Managing
        3.17    Screen Blanker
        3.18    Effective Address Calculation
        3.19    Symbols
        3.20    PAL/NTSC

4.      Communication between YOU and SIM
-----------------------------------------

         4.1    The SIM Environement
         4.2    The Monitor
         4.3    The Commands and their Syntax
         4.4    The Debugger Window
         4.5    Debugger Window Shortcuts

5.      Additional Information
------------------------------

         5.1    Assembler Usage
         5.2    Calculator Usage
         5.3    Data Line
         5.4    The Debug Server Entrance
         5.5    The SIM Base
         5.6    Errors
         5.7    Footer Messages

6.      Appendix
----------------

        6.1     Acknowledgements
        6.2     Registered Users
        6.3     My Address




*******************************************************************************
        1.      Introduction
*******************************************************************************




1.1     Welcome to SIM
======================


  Congratulations dear user. You have just obtained the third release
  of 'S.I.M.', a high performance monitor and debugger for the Commodore
  Amiga.

  This version of SIM is distributed along with NOG2. Buyers of NOG2
  automatically obtain the status of a registered user and gain the
  right to use SIM.

  'S.I.M.' is a shareware product. This means that it can be used, copied
  and distributed freely, provided that:

    1)   No fee is charged for copying and distribution.
    2)   It is distributed ONLY in its original, unmodified state.
    3)   This document is copied along with the program.

  If you copied this version from somebody else and you like it and keep using
  it, you are asked to send a little contribution of 20 SFr or 15 US$ to the
  author in order to get registered and to obtain support and the final
  version when it's finished.



1.2     Disclaimer
==================


  This program is provided "as is" without warranty of any kind. The entier
  risk of using it is to the user himself. In no event I (the author) will
  be liable for direct or indirect damage, loss of data or criminal actions
  done due to the use of this program. If you do not agree with this, you
  may not use SIM.



1.3     About this Documentation
================================


  You should carefully skim this documentation if you are not used to SIM
  yet. SIM bases on a concept that especially programers lacking detailed
  knowledge of assembly language or C will first need to get aquainted
  with.




*******************************************************************************
        2.      Getting aquainted with SIM
*******************************************************************************




2.1     What is SIM?
====================


  SIM is a very powerful debugger and monitor. It was designed to work under
  all circumstances and especially to supervise rather unconventional programs
  which do not make much use of the operating system or do completely disable
  it for more or less long time. It is intended for people who need to debug
  games, demonstration programs and even other operating systems on the Amiga.

  SIM works below the operating system and does not interact with any of its
  facilities or routines. It disposes of ways to enable you relatively
  comfortable debugging of any piece of machine language. Be it a task list
  manipulating routine, an interrupt or direct access on hardware like disk
  drives or the blitter, routines you can't monitor with an ordinary system
  based debugger. There are practically no limits. You can invoke SIM at any
  moment and it will pop up and work properly.

  SIM will do as less changes to the software and hardware (ram, custom/cia
  registers) as it can. When you exit SIM, it will try to leave everything the
  way it was when SIM was started. SIM does neiter use blitter nor copper,
  so any 'interrupted' program can continue to run with no defects due to
  a call to SIM.

  SIM will be very useful for you if you need to debug programs belonging in
  the cathegories described above. If you only need to debug 'ordinary'
  programs with no critical or nonmultitasking routines, you are better served
  with a full system debugger. There are plenty of good debuggers of that
  kind available, also in the Public Domain.



2.2     Qualifications, Requirements and Limitations
====================================================


  To use SIM efficiently, detailed knowledge of the AMIGAs hardware,
  the 680x0 processors and assembly language is ABSOLUTELY neccessary.
  If you lack this knowledge, get Commodores 'Amiga Technical Reference
  Series' and Motorolas documentations of the 68000 family.

  SIM is completely independent of the OS the Amiga uses. There is a certain
  support for the normal OS, but no dependancy.

  SIM does several things by directly accessing the hardware. This however
  is no longer allowed by Commodore and will probably cause SIM not to work
  on Amigas of the next generation(s). If an incompatibility occurs, an
  update will be released.

  You should not invoke SIM while doing any kind of timed access to hardware,
  i.e. serial transfer. Because SIM shuts down everything, data transfer
  will be interrupted. SIM may get in troubble if your Amiga is connected
  to a harddisk which is accessed by an interrupt polled driver, damage
  however should not be inflicted.




2.3     The 68020+ Version
==========================

  The 68020+ version is only an 68000 version with the neccessary changes
  to get it working on better CPUs. Special features of these processors
  (additional exception vectors, instructions, registers, etc.) are not
  supported if not absolutely neccessary.

  The 68020+ version however works only with some limitations:

        - VBR must be at a known position. Default location $0,
          if vectorbase is not at 0, the real location must be
          stored in the base of SIM (offset 264).

        - The 'v' command can only push stackframes back, not
          generate artificial ones.

        - The disassembler and assembler do not support any instructions
          added in the 68010+ processors, except Bcc.B/W/L and EXT.B.

        - MMU activities are not dealt with yet. SIM deactivates the MMU by
          default. If an active MMU tree i.e. only remaps the Kickstart image,
          you can switch the MMU on while SIM is active, if some sort of
          virtual memory or enforce MMU tree is active, you should keep the
          MMU shut while SIM is active.



2.4     Configuring SIM
=======================


  You can't use SIM right away, you need to configure a copy to your
  Amiga first. Therefore you have to use 'SIMConfig'. This program
  configurates SIM for your machine and your personal needs.

  The program is selfexplaining except when it comes to define the
  memory pages. Here you shall make no mistake or the copy generated will
  not work properly. First think about what must be viewable. That is:

        - graphic memory
        - all fastmem expansions
        - Kickstart image

  Get all start and endaddresses and sort them from lowest to highest.
  If you can merge pages then do so for same memory types. Do not define
  overlapping pages. Pages must also start and end at even addresses. The
  program  'SIMConfig' does not check for correctness of what you enter.
  If you define incorrect pages, SIM may crash later. In case you do not
  want any memory managing enter $1000000 as first page endaddress for
  the 68000 version, $80000000 for the 68020+ version.

  You can exit this program anytime by entering 'exit'.



2.5     The SIM Program
=======================


  SIM is not an executable (it has no hunkstructure, so you cannot
  simply start it from the CLI or workbench) but a simple PC-relative file
  that can be loaded somewhere into the memory or included in one of your
  own programs.

  SIM is a nonmultitasking debugger. When it is activated, Multitasking
  is immediately stopped, much like by Disable().




*******************************************************************************
        3.      Some words about...
*******************************************************************************




3.1     The Display
===================


  The display creates some of the more tricky problems for SIM and you.
  As you know, you need 20480/$5000 bytes of chipmem for a medres bitplane
  you want to display. SIM uses a 640*256 bitplane for it's display. But at a
  certain moment, there may be no 20480 bytes chipmem available.

  The solution is the backup. When you have an area of $5000 free chipmem
  that will stay free for sure (that means it is allocated with allocmem or
  will never be used), you simply set the display address to the start
  of that area and the backup address to zero (this means no backup). SIM will
  then concider these $5000 bytes its own and use it as display. When you enter
  SIM, the data in this area are then destroyed.

  In case there is not enough free chipmem or the chipmem will be used entierly
  in near future and you have enough (that means $5000 bytes) unused fastmem
  that won't be used for sure (disable fastmem...), you set the backup address
  to the start of a free $5000 block of fastmem and the display address just to
  somewhere in the chipmem. When SIM is activated, It copies the content of the
  $5000 bytes display- to the backupmem and uses the displaymem. When you leave
  SIM again, it copies the $5000 bytes back from the backup- to the displaymem.
  That way, the chip ram is unchanged.

  The memory manager claimed to be missing in earlier versions
  is now integrated in several functions. If you have defined a backup area
  the memory manager automatically fades it in at the location of the display.

  Because the interrupt vectors are used, you may not specify a display below
  $70 or above $7b000 when you have the normal amount of chipmem (the chipmem
  is reflected at $80000, except if you have fastmem there).

  Both the display- and the backupaddress are entered in the SIM-basearea
  before starting SIM or set by the 's' command while working.

  NTSC users please note that although a 640*200 plane only uses 16000 bytes,
  you too need $5000 display memory because it is also used as MFM buffer
  for all disk operations.



3.2     Breakpoints
===================


  A breakpoint is basically a change in the program that is monitored that
  stops it and gives control to the debugger that set it. In other terms, you
  can run the program at full speed until it arrives at a certain instruction.
  This is a very important feature when you have to control the flow of a
  program. Therefore the breakpoint system of SIM is very sophisticated. SIM
  can handle three kinds of breakpoints:

        - ILLEGAL breakpoints
        - JSR breakpoints
        - STACK breakpoints

  Each kind is used for different problems and has its advantages and
  disadvantages.

  SIM is able to handle 16 different breakpoints at a time. When you enter
  SIM, it removes the breakpoints from the memory, so the memory looks like it
  would look with no breakpoints set. That enables you to change instructions
  that are at a breakpoint without first removing the breakpoint before
  changeing and putting it back afterwards.

  A critical situation occurs when the breakpoint is overwritten by a
  program (i.e. by a copyroutine). Such a breakpoint is in 'modified' state
  When SIM removes the breakpoints at entry, it checks if they are still there.
  Modified breakpoints are not removed and not restored, when you leave SIM
  again. If you want to have the modified breakpoint set again, you must first
  'forget' it (this means that SIM simply frees the place in the breakpoint
  list but does not put the original opcode or words back). Then you can set
  it again.

  You cannot set breakpoints everywhere. SIM tests if there is ram at the
  location where you want to set a breakpoint. If there is none, this causes
  an error. SIM also prohibits to set breakpoints in the SIM codesegment.


  1. ILLEGAL breakpoints
  ----------------------

  Illegal breakpoints are normally the most used ones and offer the most
  possibilities. When you set an ILLEGAL breakpoint at a certain instruction,
  SIM replaces the opcode word of that instruction by the ILLEGAL opcode $4afc.
  When the ILLEGAL instruction is executed instead of the original instruction,
  an ILLEGAL INSTRUCTION exception happens.

  Therefore it is neccessary that the ILLEGAL INSTRUCTION vector somehow jumps
  to SIM, either directly, set by the 'w' command, or indirectly by the task
  traphandle, set by 'SIM-BUG' or another SIM-loader. If this is not so, your
  machine crashes.

  Illegal breakpoints have the advantage that they can be 'conditioned'.
  This means that this breakpoint only forces entry when one or one of several
  conditions are fullfilled. The following criterias can decide whether or
  not the breakpoint forces entry:


    - condition term:

      You can specify a formula that is calculated each time when the program
      arrives at the breakpoint. When the result of the term is zero, the
      program continues, if it is nonzero, SIM is entered.

      You can use that feature to i.e. break a program at a certain point if
      a register contains a certain value.


    - counter breakpoint:

      A counter breakpoint will enter SIM if the program has passed the
      breakpoint a certain number of times.

      This way you can i.e. break a subroutine after it was called a certain
      number of times.


    - button breakpoint:

      When the program arrives at a button breakpoint, SIM will look if the
      left or right mousebutton or the firebutton of a joystick in port 1 is
      pressed and enter SIM if one is pressed. You can specify what buttons
      are concidered.

      Button breakpoints can i.e. be set in a vertical blanking interrupt.
      every fiftieth/sixtieth of a second, SIM can check if you want to enter
      or not.


  Additionally you can make resident Illegal breakpoints. A nonresident
  breakpoint will be removed after it caused entry. A resident breakpoint
  will stay active until you remove it. A resident breakpoint can be used
  in situations when you want to stop a program several times at the same
  address.

  SIMs breakpoint system enables to combine all these elements, to make
  resident breakpoinst that break at SEVERAL conditions. You can set a resident
  breakpoint at $70000 that either breaks when d3 is 3245 or the left or right
  mousebutton is pressed and that is limited to 1000 passes. The command line
  to set that breakpoint would look like that: 'b 70000 * ?d3=3245 lr 1000'.

  You may ask the question how to go over a breakpoint. SIM does this in three
  steps:

    - remove the Illegal opcode and put back the original one.

    - do a tracestep to execute the instruction.

    - remember the (possibly new) opcode and set the $4afc again.

  As you see, SIM uses the TRACE vector to ignore a breakpoint. This means
  that you must not only set the ILLEGAL INSTRUCTION vector but also the
  TRACE vector. This is neccessary as soon as you have set a conditioned or
  a resident breakpoint.


  2. JSR breakpoints
  ------------------

  The second type of breakpoint is a rather a 'heavy duty' one. When you
  set a JSR breakpoint, SIM remembers the 6 bytes at the breakpoint address
  and puts a JSR instruction there that jumps absolutely into SIM (i.e.
  'JSR $c50726'). When the breakpoint is reached, the program jumps
  directly into SIM which then puts back the 6 bytes.

  This breakpoint has two advantages. The first is that you do not need any
  vectors to be set. The second is that a JSR breakpoint can be transfered.
  When you have an Illegal breakpoint in a routine and that routine is
  transfered to another location and the breakpoint is reached in the
  copied routine, SIM will not know that that illegal is a breakpoint
  because it is not at any of the addresses at which a breakpoint was set,
  so it will not be replaced by the original opcode.

  JSR breakpoints are recognized at their entrance, because each of the 16
  possible JSR breakpoints has another entrance. That way, SIM can recognize
  that breakpoint whereever it is. But be carefull, never enter SIM by
  these entrances on your own. You must also see to it that after the
  transfered breakpoint forced entry and was removed, the original one is
  NOT reached too.

  Because of these two advantages, you can use JSR breakpoints in delicate
  situations, where you are not sure if the vectors are not changed.

  A disadvantage of JSR breakpoints is that they use not one but three
  words. The minimum size for an instruction is a word, an Illegal
  breakpoint can be set at any instruction because the instruction ILLEGAL
  uses one word. A JSR breakpoint may replace three instructions. Therefore
  you have to set the JSR breakpoint in a 'linearly' executed part of the
  program. Here are two examples where the JSR breakpoint is not set
  correctly. The breakpoint is always set at the label 'bkpt':

  1. .
     .
     .
     bsr.s label      ;this bsr would jump in the middle of the breakpoint!
    bkpt:
     bra.s label2     ;JSR opcode
    label:
     nop              ;HIword of entrance
     nop              ;LO word of entrance
     .
     .
     .


  2. .
     .
     .
    bkpt:
     moveq #1,d0      ;JSR opcode
    label:
     moveq #0,d1      ;HI word of entrance
     rts              ;LO word of entrance
     .
     .
     .
     moveq #-1,d0
     bra.s label      ;again in the middle...


  3. Stack breakpoints
  --------------------

  Contrarily to the Illegal and JSR breakpoint, the Stack breakpoint is
  not a change in the program but a change on the Stack. When SIM sets a
  Stack breakpoint, it replaces a returnaddress on the stack by the address
  of an entrance of SIM. When the appropriate rts, rtr or rte that would
  return to that address is reached, it returns to SIM instead. SIM sets the
  pc to the returnaddress and replaces the SIM entrance address on the stack
  (should now be at a7-4!) by the original address for security.

  For SIM, it does not differe, if the Stack breakpoint is set in the
  supervisor or userstack (in earlier versions it did, this is no longer
  so).

  Use this feature wisely! SIM cannot test if the Stack breakpoint you set
  is put in a stack and is taken off stack by a rts. Its upon you to set Stack
  breakpoints at the right position.

  Stack breakpoints are also used by for the nextstep and the leave
  subroutine command.



3.3     Trace
=============


  Tracing is the second way of keeping a program under control. SIM can
  singlestep a program. Therefore you must see that the TRACE exception caused
  by that somehow ends up in SIM, either set it directly or set the
  tasktraphandle. It can also let a program run step by step and stop when
  one or several conditions are fullfilled, much like the illegal breakpoints:


    - condition term:

      You can specify a formula that is calculated after each step. When the
      result of the term is zero, the trace continues, if it is nonzero,
      SIM is entered.

      You can use that feature to i.e. break a program as soon as a certain
      register is changed.


    - counter trace:

      You can specify a maximum number of steps to do. When that amount of steps
      is done, SIM is entered.

      Counter trace is mostly use to just get back after a routine is done.


    - button trace:

      After each step, SIM will look if the left or right mousebutton or the
      firebutton of a joystick in port 1 is pressed and enter SIM if one is
      pressed. You can specify what buttons are concidered.

      Button trace can i.e. be used for stoping a program by hand at any moment.


    - trace breakpoint:

      You can define an address that is compared to the PC after each step.
      If the program has arrived at that address, SIM is entered.

      This feature is used when you cannot use breakpoints for some reasons.


    - 68020 emulation:

      This is also a condition. SIM is only entered when a change in the flow
      would happen, this means that the pc points on a BRA, JMP etc.

      I do not know what this is for, but people like it.


  SIM uses the trace flag to do single steps. What some people do not know is
  that you can trace over some instructions that may clear that flag. These are

   RTE
   MOVE to SR
   ORI #x,SR
   EORI #x,SR
   ANDI #x,SR

  Additionally you can enter the TRAP #x exception routines with the trace.

  Tracing has one weak spot: if you are tracing and an interrupt happens that
  somehow causes entry in SIM (i.e. by a breakpoint), SIM loses the control
  over the trace. When you exit SIM again and the interrupt ends, a TRACE
  exception happens. You must then start to trace again or clear the trace flag
  by hand.

  Some words about the speed: It is clear that the more conditions you allow,
  the slower the program runs. Additionally some conditions cause longer delays
  than others. Condition trace is slower than button trace because it has to
  call the calculator which is relatively complex and slow.



3.4     The Keyboard
====================


  The most difficult problems are imposed by the keyboard. The Amigas keyboard
  hardware cannot tell you which keys are pressed at a certain moment, it
  reports only key changes. This makes it difficult for systemindependent
  programs. When you press a key under system and release it in a program
  that has its own keyboardhandler, the system will never know that you
  released that key, it will report repeats of that key all the time until you
  press another key. To prevent this, SIM will look that all keys are in the
  same state when you leave SIM as they were in when you entered SIM. When you
  leave SIM and a key is not in the same state, SIM will ask you to either
  press that key or to release it. Therefore, in the headline you will find the
  keys rawkey number and if in the keymap there is a printable char, that char
  too. You can only exit SIM if you press or release all keys that it wants
  you to.

  If you leave SIM by accident (hit wrong key?) and you are requested to
  press/release a key, you can do the following operation to return to the
  monitor:

  - press another key that is not a qualifier (shift etc.), not 'r', 'e', 't',
    'u', 'n' or one that you must press to exit (esc is a good choice).

  - release all other keys

  - type 'return'

  - release the keys you pressed for that operation

  If you are tired to press keys again and again to exit, you can use the
  flush keystatefield shortcut. SIM will then clear the internal list of
  keys that were pressed when SIM was activated.

  As you know, the keyboard can store upto ten rawkeys on its own if
  the CPU has no time or need to get keyboard events. It is possible
  that several key hits are waiting to be replied. When SIM is activated
  then, it would recieve all those old keys that may invoke shortcuts or
  commands that are not desired. Similar problems occur when you link SIM
  in the CIA-A interrupt and it is invoked before the key is replied. The
  keyboardbuffer killer is used to reply to all possibly waiting keys and
  to flush the keyboard buffer. This feature can be toggled on or off.



3.5     Disk Access
===================


  Because ram is a too transitory datacarier, SIM can read and write
  DOS-tracks and sectors. It does this by directly accessing the hardware.
  Unfortunately, I know only one way to find out if a drive is running or
  not: To activate the drive and look if its on full speed with no delay.
  This system is only working when the running drives have a disk inserted.
  If no disk is in a running drive and you access disk, it will be stoped
  after disk access.

  When SIM is writing or reading, the display is used as buffer. You still
  see it, but it contains chaos. The top line is used to give you status
  information about the track that is operated or errors occured.

  When an error occures, you can either break with CTRL, retry with SHIFT
  or ignore the error with ALT (when file operation, ALT=CTRL).

  When a track is not correct, SIM tries to read it three times. Then it
  reports the error but displays also which sectors were okay. It is
  possible that only one sector is damaged, press SHIFT several times, SIM
  may find some sectors more that are okay and simply were after the damaged
  sector last time.

  SIM is tollerant concerning the integrity of the sectors. Checksums are
  calculated and SIM reports an error if one is wrong, but it decodes the
  sector anyway. This enables SIM to reapair partially destroyed tracks.

  HD disks as used in the A4000 are not supported yet.



3.6     Files
=============


  The capabilitys of SIM to read, list and write files are some of its newest
  and most usefull features. You can load any files of a DOS disk, also
  from user directories to memory. You can list the files and their length
  contained in any directory. And you can save any area of memory as a file
  on a disk.

  The file save system is quite sophisticated. It writes files in a way
  that they can be loaded and listed fast. Info- and extension blocks are
  located on track 79 and higher, data blocks from 79 down to 0 and from 159
  to 79. Additionally, SIM will first look if a file fits the disk before
  it begins to save. The bad sideeffect of this is that saving takes some time.

  One thing you must remember is to be carefull with saving files when you
  work with the normal operating system afterwards. When you save a file,
  the bitmap on the disk is changed. The system keeps its own copy of the
  bitmap of a disk in memory. When it accesses that disk again, it possibly
  discovers a totally different bitmap. When it comes to the worst, the DOS
  crashes with the guru 07000007 (bitmap corrupt). To prevent this, you
  simply remove that disk from its drive and put it back again. The DOS
  then rereads the bitmap and everything's okay.



3.7     Breaking
================


  In certain situations, it may be neccessary to break an operation or to
  pause it. SIM can both. You can break the dump commands, find and compare
  by shortly hitting CTRL. If you press it longer, SIM only pauses and
  continues when you release CTRL. When you press SHIFT-CTRL or additionaly
  hit the SHIFT key when you pause, SIM locks until you release, press and
  relese CTRL again. This enables you i.e. to make notes without holding
  CTRL all the time.

  While locked or paused, you can press the ALT key. When you release CTRL
  (if locked, press it first), SIM breaks also. This is used when you have
  paused and want to stop immediately.

  ALT-CTRL is used to break command execution in general. Before SIM looks
  for a new command in a command line, it tests for ALT-CTRL. If that's so,
  it breaks. This enables you to break a commandline like 'P0:X' since you
  cannot break the 'P' and 'X' commands.

  An exception to this rules are the disk operation and the list directory
  command. These commands can only be broken. Therefore simply keep the CTRL
  key pressed until SIM gets it.



3.8     The Actual Address
==========================


  The dump and edit commands share a default address variable that is used
  each time, you do not give a startaddress. This address has the name '@'
  for the calculator. It contains the endaddress of the last dump or edit
  command or it is set by find and compare.



3.9     The Matchbuffer
=======================


  The matchbuffer is used to collect addresses. You can force the find and
  compare commands to put the addresses they report into this buffer. Well,
  this is nothing special. But you can also say under what conditions an
  address is put in the buffer or one that is already in buffer stays there.
  There are three possible conditions:


  - old:     If an address that was already in buffer did not match with any
             reported by the find or compare command, it only stays in the
             buffer when you enable oldies.

  - match:   If an address that is reported is already somewhere in the buffer,
             it stays only when you enable matches.

  - new:     If an address is new, it is only put in the buffer when you enable
             new ones.

  You can combine the three conditions in any way (there are eight possible),
  some may make not much sence.

  This feature enables you to search for counters or changes. It is implented
  for people using SIM to cheat in games.

  To show the addresses in the buffer, the 'k' command is used.

  An example: you are searching for the address of a counter. You know that
  the counter is on 10 now:

  1. define matchbuffer, i.e. 'k c00000 c10000'
  2. search for 10, i.e. 'f 0 20000 !n 0a'
  3. exit, perform any neccessary operation to change the counter to another
     known value, i.e. 15
  4. search for 15, i.e. 'f 0 20000 !m 0f'
  5. list addresse(s) in matchbuffer, i.e. 'k 0'
  6. if more than one address stays in the buffer, go to step 3 and
     search again until one address stays.



3.10    Command History
=======================


  SIM remembers the last commands executed in the monitor. 128 bytes are
  reserved for that. These 128 bytes contain the last packed command lines
  that fit. If you get an old command line back by the command history
  shortcuts and execute it, it is not remembered as the newest executed
  command.



3.11    Traps
=============


  The traps are one of the major connections of sim to the outer world. They are
  used for breakpoints and to handle crashes. You can set the ten basic
  exception vectors directly. When you enter SIM, it puts back the original
  vectors, so you can edit them. When exited, SIM sets the set traps again.

  Problems occure when the program that is debugged sets the traps itself.
  When the program changes a vector previously set by SIM, this is handled the
  same way as it is done with changed breakpoints.

  Additionally you can force SIM to set traps again if they are modified by
  toggeling 'Auto Unmodify Traps' on. If traps set by SIM are changed, the
  display color of SIM turns yellow in order to inform you of this.

  While working under operating system, it is not recomended to set the
  exception vectors directly to SIM, except if it becomes neccessary.



3.12    Functionkeys
====================


  You can define all ten functionkeys with a text or command line. If you define
  a text, it is copied at the location of the cursor. If you define a command
  line, it is executed directly.

  The system used bases much on the one used by the Sharp PC-1500, thanks to
  Sharp for that.

  The functionkeys share 300 bytes of 'intelligent' textbuffer with the
  condition breakpoints and linkterms.

  The ten functionkeys are partially allready defined in the original
  SIM version. These are the definitions:

  F1:  z@        ;for easy tracing
  F2:  u@        ;also for easy tracing
  F3:  i@        ;dito
  F4:  f@        ;for repeated finding
  F5:  c@        ;for repeated comparing
  F8:  v:X@      ;when exceptionvectors are set and an exception happens
                  and has to be handled by the original vector
  F9:  dm0 m0@   ;for finding disassembly without debugger window. Initially
                  deselected
  F10: r:dpc pc@ ;for tracing without debugger window. Initially deselected



3.13    SIM and the Hardware
============================


  SIM does only use a very limited part of the hardware registers, the ones
  that are indispensable or must be set on fix values to provide security.
  Some of these registers can be read, some not. The values of the readable
  ones are remembered in a special part of SIM called 'SIM base' when SIM is
  activated. The SIM base is located, as its name says, at the start of SIM.
  In chapter 6.1 you find the structure of the base.

  These are the registers that are read out and stored in the base at entry.
  When you exit SIM, it copies the remembered values back:


  - DMACON
  - INTENA
  - INTREQ *)

  - Level 2 interrupt
  - Level 3 interrupt

  - CIA-A: CRA
  - CIA-A: CRB
  - CIA-B: CRA
  - CIA-B: CRB

  - CIA-A: PRA write buffer
  - CIA-A: PRB write buffer
  - CIA-A: DDRA
  - CIA-A: DDRB

  - CIA-B: DDRA

  - CIA-A: SR write buffer

  - VPOS **)


  All these registers are used by SIM when working. If you have to know
  what vaule was in one of those, you have to look in the SIM base where SIM
  remembered them.


  *) This register is handled in a special way. While SIM is active, it leaves
  the disk-DMA switched on. If it wouldn't, this would possibly destroy your
  disks. Now since the disk-DMA is left on, remember that when the disk-DMA is
  terminated, bit 1 in the INTREQ is set. But this may happen during SIM is
  active because the DMA was still transfering when the INTREQ was read. Therefore
  you will find only the interrupt requests in the backup that were waiting
  when SIM was activated. If you want to know abaout the actual ones, you must
  read out INTREQR using the calculator command '?[$dff09c].w'.

  When you exit and didn't edit the INTREQ backup, SIM does not restore
  the bits EXTER, DSKSYN, RBF, AUDX, DSKBLK and TBE from the backup. If you
  edited the backup, the bits that are changed are restored , even if they
  contain some of the bits named above.

  **) This value is not written back. SIM rather waits for the rasterbeam
  to be aproximately at that position that it was on when the register was
  read. The register is read at a late point of time when SIM is activated,
  quite some instructions have been executed then, so it is not very precise.
  hopefully this can be improved.

  As quoted, some of the custom register contain information that is lost
  because SIM cannot read from these registers. For the more important
  ones, SIM disposes of an editable list of 'reentry' values which it puts
  back when exiting. Those registers are:


  - DIWSTRT
  - DIWSTOP
  - DDFSTRT
  - DDFSTOP
  - BPLCON0
  - BPLCON1
  - BPLMOD1
  - COLOR00
  - COLOR01
  - BEAMCON0*)

  *) The BEAMCON0 register is only accessed under ECS or AGA. Unter OS,
  this register however is only updated at calls to LoadView(), not in
  the copperlist. You may need to concider that if you are using an
  advanced resolution (i.e. VGA) on your Workbench screen and don't
  access SIM via SIMBug or PostSIM which both update the BEAMCON0 reentry
  value to the value used by the OS.

  As you see, these registers all concern the display. In most cases, they
  are reset anyway by a copperlist. If not, you have to look in the program
  where it sets them for the initial value and enter it in the base or decide
  on your own what value to use.

  Some of the registers are modified but do not have a reentry value,
  because they are either too temporary (DSKPTX for example) or compleetely
  unimportant (BPL1PTX). If it becomes neccessary, you can edit some with
  the 'e' command:


  - CLXDAT
  - DSKBTR *)
  - DSKPTX *)
  - DSKLEN *)
  - DSKSYNC *)
  - BPL1PTX
  - BPL1DAT
  - SPRXDATA/B
  - CIAA: ICR state and mask


  *) These registers are only used and changed when you read or write from or
  to disk.



3.14    The Colors Red and Yellow
=================================


  When you start to use SIM quite often and in critical situations, it may
  happen that the text color of SIM, which normally is green, turns red.
  This means that the SIM code has been partially changed. SIM calculates
  a checksum over its main code segment and looks if it is the same each time.
  If not, it changes the color to red.

  When the color is red you must be rather carefull. SIM seems to run well but
  it may crash when you execute a certain command or do something else. If
  you can, load a new copy and don't keep using the destroyed one.

  A yellow text color means that one or more of the traps set has been
  overwritten.



3.15    Printer Support
=======================


  SIM allows you to send all output on the monitor to the printer. Therefore
  it simply sends the text as ASCII codes to the parallel port. This should
  allow you to use practically any parallel printer. If you want to send ESC
  codes (to select NLQ, reset etc.) you can do this by entering CTRL-[ and
  the rest of the ESC code as a command and press return. Remember to use
  the printer specific codes and not the AMIGA specific ones.

  Printer support does not work quite right with laser printers and certain
  other non-matrix printers which need a FF before printing or which
  demand both LF and CR.



3.16    Memory Managing
=======================


  SIM now disposes of the memory manager that was missing in v1.51. It does
  this:

      - It fades in the backup of the display at the location of the display.
        If there is no backup it zeroes the display.

      - At VBR+$68 and VBR+$6c it inserts the level 2 and level 3 vectors.

      - It handles five pages of memory that can be read and written to.
        Other areas are zeroed.

  The memory manager is currently not supported by all functions. Only the
  'm', 'a', 'd', 'p' and 'l' commands (and the corresponding debugger window
  output forms), 'c', 't', 'o', 'P', 'H', 'L', 'S', 'e', 'n' and 'q' commands
  use it, the rest still doesn't.



3.17    Screen Blanker
======================


  When you do not press any key during 10 minutes and SIM is not doing any
  operation, it automatically darkens the monitor.



3.18    Effective Address Calculation
=====================================


  SIM can now calculate effective addresses. The source EA of the command at
  the PC is displayed below A6 of the registerlist, the destination EA below
  A7. Further use of this new capability has not yet been made, but it sure
  leaves a wide field of powerfull features to be made.



3.19    Symbols
===============


  SIM now supports a symbol list generated by an external program. The symbols
  can't be edited yet or new ones added. Symbols are used in the calculator
  and the disassembler.



3.20    PAL/NTSC
================

  When SIM is invoked on any PAL/NTSC machine for the first time, it adapts
  its display to the machine type. If ECS (or AGA) chipset is available,
  you are allowed to toggle between PAL/NTSC. NTSC users also can use an
  NTSC overscan display with 28 lines.




*******************************************************************************
 4. Communication between YOU and SIM
*******************************************************************************



4.1     The SIM Environement
============================


  As quoted in the chapter about the display, SIM provides its own. It is
  basically used for all output SIM produces (leave alone the printer and
  disk).

  You have a display of 200/224/256*640 pixels or 25/28/32 lines and 80 rows.
  The screens colors are green and dark blue but may be set by you to any
  colors you like. The screen is devided in header, worktable/debugger window
  and footer, all seperated by a line of '­'.

  The header normally contains the title and copyrights but serves also as
  statusline when accessing disk and keyboard cleanup.

  The worktable and the debugger window share 28 lines.
   - In the worktable, actually the monitor, you can move the cursor around
     and enter commands and get output.
   - The debugger window shows you one or two views of the memory in different
     forms at different addresses, read more about that feature in the
     appropriate chapter.

  The footer contains the cause of SIM's entry, a status and result field
  and the addresses of SIM itself, the display- and backupaddresses.



4.2     The Monitor
===================


  On the worktable, several basic features are provided:

   - What you see on the monitor (the text) is stored in SIM, when you leave
     and enter again, the display will be the same.

   - SIM has two entier keymaps for not qualified,
     shifted, alternated and shifted+alternated keys, one USA and one custom.
     In the original version, the custom one is Swiss.

   - Ctrl+chars with ascii values from $40-$60 will cause a char from
     $0-$20 (i.e. 'J' (=$4a) => <CR> (=$a))

   - Ctrl+chars with ascii values from $60-$80 will cause a char from
     $80-$a0

   - The cursor can be moved around one char by pressing the cursor keys.

   - The cursor can be moved to the extreme positions by pressing
     <SHIFT>+cursor keys (i.e. <SHIFT>+cursor right => cursor in row 79)

   - <DEL> will delete the char above the cursor and shift all chars right
     of the cursor one row left, inserting a space at row 79

   - <BACKSPACE> will clear the char left of the cursor and shift all chars
     above and right of the cursor one row left.

   - <SHIFT>+<DEL> will insert a space at the cursor position and shift all
     chars above and right of the cursor one row right.

   - <SHIFT>+<BACKSPACE> will clear the char above the cursor move the
     cursor one row left

   - <ALT>+<DEL> will clear the monitor part and put the cursor in the left
     upper corner next to a point.

   - <ALT>+<BACKSPACE> will clear the line in which the cursor is, put a '.' in
     row 1 and the cursor in row 2.

   - <HELP> prints the first helppage, starting in the line below the line the
     cursor is in actually.

   - <SHIFT+HELP> prints the second helppage.

   - <F1-F10>: you can freely define the ten function keys.

   - <SHIFT>+<ESC> copies the last executed command in the line of the
     cursor.

   - <ALT>+<ESC> copies the line of the cursor in the command
     buffer. It can then be inserted anywhere by <SHIFT>+<ESC>.

   - <CR> will execute the commands in the actual line (the one in which
     the cursor is).

   - <ALT+CURSOR UP> goes one step back in command history and fill the actual
     line with the actuall command in history.

   - <ALT+CURSOR DOWN> goes one step forth in command history.


   You can execute commands by entering them in one line and pressing
   return. When all commands are executed, SIM looks if a point '.' is in
   row 0 of the actual line. If so, the cursor is set left of it and the
   line is not cleared. If no point is found there, SIM puts one there
   and clears the rest of the line. That way, the point signals wheather or
   not a line is a previous command line. That enables to use again the
   commands that  have been entered earlier and are still visible on the
   screen.


4.3     The Commands and their Syntax
=====================================

  The command line contains the different commands to be executed.
  It has this form:

              .<command> <options> (: <command> <options> ...)

  You can enter several commands in one line, seperated by a
  doubble point. The doubble point is needed, except if the next char
  is the same as of the last executed command (i.e. 'mmmm' is allowed
  and shows $200 bytes at once, starting at the actual address).

  While working in SIM, you can get a little overview of them in the two
  helppages:

   n (s)(i) :assemble    | t [s][e][t] :transfer mem | A (s) :set viewstart
   e (s)(d) :edit mem    | o [s][e][d] :occupy mem   | w (x) :CPU traps
   d (s)(e) :disassemble | c (s)(e)(t) :compare mem  | v (x) :create trap
   a (s)(e) :show ascii  | f (sejd)(m) :find data    | h (n) :history
   m (s)(e) :show hex    | f (sej'i'i) :find disasm  | g [s] :go sub
   l (s)(e) :show copper | s (p)(b)(c) :set SIM-adrs | i (n) :leave out
   p (s)(e) :show text   | F (n)(c){@} :edit F-keys  | u     :next step
   k (s)(e) :matchbuffer | z (n*n?cb)  :trace steps  | r (rs):edit regs
   P (s)(m) :show plane  | b (s)(*n?b) :breakpoints  | q/Q   :quit prog
   ? (expr) :calculate   | T (expr){@} :set linkterm | x/X   :exit and go

  and

   >f(n)    :format disk | <s [s][b](n) :read secs
   D (n)    :set drive   | >s [s][b](n) :write secs
   D?(n)    :find head   | <t [s][t](n) :read tracks
   B [s]    :bootchksum  | >t [s][t](n) :write tracks
   K [s]    :blockchksum | L  [fs](n)(s):load file
   V (path) :directory   | S  [f][s][e] :save file
   R [s]    :set range   | H  [s][e](p) :hear memory

  In the helppage and the explanations, the following shortenings are used for
  options:

   s: (start)address/seek     e: endaddress         t: targetaddress/track
   i: assembler instructions  d: dataline           c: a text or SIM commands
   n: decimal number          x: hexadecimal number m: mask/modulo
   r: register                p: plane              b: backup/breakmode/block
   ?: condition term          f: file               j: jokers

  Options in '[]' are neccessary.
  Options in '()' are optional.
  Chars in '{}' serve as sign or flag.

  Because space in SIM is limited, these helppages tell only the basic
  syntax of a command. Here comes a short but detailed list of all commands
  and what they do:


 Dump Commands
 -------------

    m (s)(e) : print memory as hexdump
    a (s)(e) : print memory as asciidump
    d (s)(e) : disassemble memory
    l (s)(e) : interprete memory as copperlist
    p (s)(e) : print memory as text

   Dump commands have all the same options, only the output changes:

     command (startaddress) (endaddress)

   If you give both addresses, SIM starts to dump from the startaddress and
   stops when the endaddress is reached or passed over.

   If you give only the startaddress, SIM starts to dump from that address
   and calculates an endaddress. That endaddress will be:

    for 'm': start+128
    for 'a': start+512
    for 'd': start+32
    for 'l': start+32
    for 'p': start+eight lines

   If you do not give any address, SIM takes the actual address as
   startaddress.

   Do not try to dump the customregisters area.

   In the disassembly, the instructions BSR,JSR and TRAP #x are indented
   and after the instructions JMP, BRA, ILLEGAL, RTS, RTE, RTR and RESET a
   line of '-' is printed for seperation. Additionally, breakpoints are
   marked by an asterix.


   EXAMPLES:

    m 0 100
    a 100
    d
    l 51236 !+60
    p $25364


 Edit Commands
 -------------

    e (s)(d) : edit memory
    n (s)(n) : assemle

   You can modify the memory with these two commands. They both ignore the
   memory manager and write diectly to memory.

   The edit command can write data at a location in the memory (see chapter
   'line forms' for details)

   The assemle command can assemble one or more instructions seperated by a
   ',' at a location in memory (see chapter 'Assembler and Calculator' for
   info)

   If you give both startaddress and data/instructions, SIM simply edits
   the memory.

   If you only give the startaddress, SIM will start to assemble or edit in
   a continuous mode where it always prepares the next line for further data
   or instructions. To stop this simply give no instruction or data. The
   system is as clever as it recognices if in the line it prepares for a new
   data or assemble line, there is already a data or assemble line that was
   prepared for continuous mode. If that is so, it only updates the address
   but does not clear the line. That enables you to i.e. correct a program
   assembled in continuous mode and to insert instructions.

   If you do not give any option, SIM starts to edit/assemble in continuous
   mode at the actual address.


   EXAMPLES:

    e 70000
    e>00070000: 0121
    n 100 nop


 Transfer and Occupy
 -------------------

   t (s)(e)(t) : Transfer memory
   o (s)(e)(d) : Occupy memory

   Transfer:

   This command simply copies a part of the memory to another location smartly.
   This means that SIM uses as- or descending mode for copying, not to destroy
   the memory:

   - t [s][e][t] : Transfers memory from s to e at new address t


   Occpuy:

   Occupy is generaly used to clear the memory or to fill it with repeated data:

   - o [s][e][d] : Occupy memory from s to e with data d


   EXAMPLES:

   t 0 10000 c00000
   o 12564 !+60 nnop


 Find and Compare
 ----------------

   f (s)(e)(j)(d)(m) - find data
   f (s)(e)(j) i (i) - find disassembly
   c (s)(e)(t)(j)    - compare memory
   k {@}(s)(e)       - show/set matchbuffer

   SIM disposes of a sophisticated find and compare system. For any of the
   three you can specify some jokers:

   - +/-n : Sets a step, only at every nth address is searched or compared.

   - '*'  : To say that all addresses where nothing was found or two bytes
            are the same are reported.

   - '@'  : When you do not want a list of addresses but to have them reported
            one by one, set this joker. SIM will then execute F9 each time
            something is reported and put the active view of the debugger
            window at that address.

   - '!'  : If you want to collect and filter addresses with the matchbuffer,
            set this flag. After the '!' you can enter an 'o' to say that old
            ones stay, a 'm' to say that same addresses stay, or a 'n' to say
            that new ones stay. Combinations are allowed.


   Find data:

   You can search in a defined area in the memory for a certain bytecombination
   with this command. Depending of how many options you enter, the command does
   different things:

   - f [s][e](j)[d][m] : Starts to find from s to e with the jokers j for
     the bytes d that are masked by the mask m. Only the bits that are set in m
     are concidered when comparing. If the mask is shorter than the data, the
     rest of the mask will be set to $ff

   - f [s][e](j)[d] :Starts to search for data with all bits set in the mask.

   - f [s][e](j) : Starts to find for the same data with the same mask as last
     time in the area from s to e with new jokers j.

   - f [s][e] : Searches again in the area from s to e.

   - f [s] : Starts to search from s to the last e.

   - f : Continues to find after the last address reported.


   Find disassembly:

   You can find an instruction or a fragment of it in a defined are in the
   memory. Like find data, find disassembly does not need all options:

   - f [s][e](j) i [i] : Starts to find from s to e with jokers j for the
     instruction i.

   - f [s][e](j) : Starts to find for the same instruction in the area
     from s to e with new jokers j.

   - f [s][e] : Searches again in the area from s to e.

   - f [s] : Starts to search from s to the last e.

   - f : Continues to find after the last address reported.

   The instruction i can be only a fragment like '4(a6)' or an entier
   instruction like 'moveq #3,d0'. Several things must be made right:

   - When you have entered a space, SIM will concider what is before the
     space to be the mnemonic. Because the disassembler leaves an eight
     chars large field for the mnemonic where the rest is filled with
     spaces, SIM does tabulate your entries. 'clr.l d0' will internally
     made to 'clr.l   d0'.

   - The char '*' is used as joker. It says that this char is not compared.
     I.e. '(a*)' searches for all indirect accesses with any address register.

   - The char '_' is replaced by a space. I.e. '_d0' searches for
     all accesses on d0 as source ea.

   - The char '@' at the start or the end of your fragment limits the
     search on the start or end of the fragment. I.e. '@st' finds only
     'st.b d0' but not 'tst.l d3'.


   Compare:

   You can compare two areas in the memory. Different amount of options for
   different results:

   - c [s][e][t](j) : Compares area from s to e with area t to (t+(e-s)) with
     jokers j.

   - c [s][e][t] : Compares with no jokers.

   - c [s][t] : Continues to compare from s with t.

   - c [s] : Compares from s to last e with last t

   - c : Continues to compare after last address reported.


   Matchbuffer:

   You can read out or define the matchbuffer:

   - k [s][e] : Defines a new matchbuffer from s to e and clears it.

   - k * : Clears matchbuffer.

   - k ? : Shows you where the matchbuffer is.

   - k @ [s] : Shows all matchbuffer entries larger than s by reporting
     them one by one over F9.

   - k [s] : Lists all entries higher than s

   - k : Lists or shows next entrie(s)


   EXAMPLES:

    f 0 100 00
    f 10000 20000 !nm 05
    f 0 20000 @ imoveq #*,d*
    c 0 100 200 *
    k 100
    k@ 0


 Processor Commands
 ------------------

   r (r)(x) : set/view registers
   w (x)    : set/view traps
   v (x)    : create trap

   Registers:

   The 'r' command is used to either set a register d0-d7, a0-a7, ssp, usp, pc,
   sr, m0-m7 or to view them:

   - r [r][x] : Sets register r vith new value x
   - r        : Views registers
   - r?       : Views memories m0-m7


   Trapsetting:

   The 'w' command is used to either set or clear the ten basic CPU exception
   vectors or to view their status:

   - w [x] : Sets or clears Vector x
   - w     : Lists status of vectors
   - wk    : Clears all traps

   You can set or clear several vectors at a time by seperating the vector
   numbers by kommas. The vector numbers correspond to the exception numbers, 2
   for bus error upto $b for linef.


   Trapcreating:

   The 'v' command is used to simulate the occurence of an exception or to
   remove one from the stack:

   - v [x]  : Simulates exception x
   - v [-x] : Removes exception x from stack
   - v      : Simulates occurence of same exception that forced entry
   - v?     : Gives information about trap that forced entry

   SIM can simulate exceptions 2 upto $40. When you simulate an address or bus
   error, SIM takes either the ssw, ir and aa from the last bus or address
   error or zero for all when none happened yet.

   When you simulate an exception 2 upto $b, which is set by the 'w' command,
   SIM takes the old vector as new pc.

   When you simulate an interrupt, the sr will also contain the interrupt
   level.

   The 'v' command without options is used to put an exception back on the
   stack when i.e. you want the old vector to handle the problem. This works
   only if SIM was entered by one of the exceptions.

   You can only remove traps from the stack when you are in supervisor mode.
   The vector number is only used to know how much has to be taken from the
   stack (14 bytes when 2 or 3, 6 for the rest).

   The 'v?' command is used to know more about the exception, especially
   address and bus errors.

   In the 68020+ version, the 'v' command can only be called without options.


   EXAMPLES:

   r pc pc+20
   r m7 d0
   r?
   w 4,9
   wk
   v 3
   v -3
   v?


 Breakpoints and Trace
 ---------------------

   b (s)(j)  : set/clear breakpoints
   u         : nextstep
   z (j)     : tracestep
   i (n)     : leave out instructions

   Breakpoints:

   The 'b' command is used to handle breakpoints. Different options are
   available:

   - b [s][j] : Sets a breakpoint at address s with the options:

     - 'l' or 'r' or 'f' : button breakpoint
     - [n]               : counter breakpoint
     - '?' [n]           : condition breakpoint
     - '*'               : resident breakpoint

   - b [s] : Sets a simple breakpoint

   - b : Lists all breakpoints

   - bj [s] : Sets a JSR breakpoint at s

   - bs [s] : Sets a STACK breakpoint at s

   - bk : Kills all breakpoints

   You can seperate several breakpoints at a time by seperating the next
   address from the previous address or options by a komma.


   Trace:

   The 'z' command executes tracesteps. It either stops after one step or when
   a certain condition is fullfilled:

   - z [j] : Does trace until:

     - 'l' or 'r' or 'f' : trace until button pressed
     - [n]               : trace n steps
     - '?' [n]           : trace until n not zero
     - '*' [s]           : trace until pc=s
     - 'c'               : emulate 68020 trace

   - z : Does one tracestep


   Nextstep:

   The 'u' command does either one tracestep or when it is done at a JSR, BSR
   or TRAP #x, it does also a tracestep and sets a stack breakpoint at a7
   (or a7+2 when TRAP) and exits:

   - u : Do one nextstep


   Leave Out:

   This simply leaves instructions away:

   - i [n] : Leaves out n instructions

   - i : Leaves out one instruction


   EXAMPLES:

    b 100 *j100 ?[4]<>$c00276
    bj 100,200
    bssp
    z *pc
    z j
    n
    i 2


   Flow
   ----

   x     : Exit
   X     : Exit directly
   q     : Quit
   Q     : Quit directly
   g [s] : go to subroutine
   h (n) : history

   Exit:

   The 'x' or 'X' commands are used to simply continue the program at full
   speed. 'x' asks first if you are sure, 'X' simply exits:

   - x : Exits, but asks for confirmation first

   - X : Exits directly


   Quit:

   The 'q' or 'Q' commands are used to return control to the debug server.
   'q' asks first if you are sure, 'Q' simply returs directly:

   - q : Quits, but asks for confirmation first

   - Q : Quits directly


   Gosub:

   The 'g' command is used to execute a little program from SIM:

   - g [s]  : goes to subroutine at s

   - gw [s] : goes to subroutine at s but does not exit yet

   When SIM goes to subroutine, it first pushes the old pc on the stack and then
   the return address for the rts.

   The 'gw' command does only prepare the stack for the operation but does not
   exit yet. This is i.e. used to trace a subroutine.


   History:

   SIM remembers the last five sets of registers as they were when SIM was left
   for the last five times. The list is also updated after each step when doing
   conditioned trace:

   - h [n] : Print nth last history

   - h : Print all five histories

   SIM does not only remember the registers d0-a6, usp, ssp, sr and pc but
   also the instruction at the pc because of selfmodifying code.


   EXAMPLES:

   h 3
   X
   q
   g 100
   gw 200


   Diskoperations
   --------------

   D  (n)       : set drive
   <t (s)(s)(n) : read track
   >t (s)(s)(n) : write track
   <s (s)(s)(n) : read sector
   >s (s)(s)(n) : write sector
   >f (n)       : format disk
   B  (s)       : bootchecksum
   K  (s)       : blockchecksum

   Set Drive:

   The 'D' command is used to set the drive number that is used for further
   diskoperations (tracks, sectors or format, but not fot file operations!)
   or to ask for the actually used drive or to ask for the position of the
   head of a drive:

   - D [n] : Takes drive n (0-3) as actual drive

   - D : Shows actual drive

   - D? [n] : finds position of head of drive n

   - D? : finds position of head of actual drive

   The headposition is reported as logical track, the sideselect bit will be
   concidered when calculating the position. In most cases (DOS included)
   the sideselect bit will be set directly before DMA access and put to an
   undefined state afterwards. If that is so when you use this command, you
   must find the side that is used on your own, analyze the diskroutines.


   Read Track:

   The '<t' command simply reads entier logical tracks (0-159) somewhere into
   memory:

   - <t [s][t][n] : Reads n tracks starting with t to s

   - <t [s][t] : Reads one track t to s

   Well, SIM does not test where the data is read, you simply should not
   'overread' the display or SIM.


   Write Track:

   The '>t' command writes an area of the memory as logical tracks on disk:

   - >t [s][t][n] : Writes n tracks starting with t, data start at s

   - >t [s][t] : Writes one track t, data start at s


   Read Sector:

   With the '<s' command you can now read single sectors from disk to memory:

   - <s [s][b][n] : reads n sectors starting with b to s

   - <s [s][b] : reads one sector b to s


   Write Sector:

   With the '>s' command you can write single sectors from disk to memory:

   - <s [s][b][n] : writes n sectors starting with b, data start at s

   - <s [s][b] : writes one sector b, data start at s

   The sector writeroutine is clever enough. If you only write some
   sectors of a track, it reads the rest of them from disk to complete the
   track and writes the track afterwards.


   Format Disk:

   Because you can now save files, you may have to make a datadisk first.
   The '>f' command is used to format and initialize a disk:

   - >f [n] : Formats disk in drive n

   - >f : Formats disk in actual drive

   You can't yet enter a name for the disk, it will automatically be
   'DATA-DISK'. The creation date is zeroed too. But the DOS cannot seperate
   disks with the same name and same date. So never keep two datadisks
   in two drives simultaneously, your machine would crash if you do so.

   If you format a disk that was previously in a drive and you return to DOS,
   remove and reinsert that disk for the DOS must know the new name and new
   bitmap.


   Bootchecksum:

   When you want to save a bootblock on a disk, you may have to update the
   checksum with this command:

   - B [s] : Sets new checksum of bootblock that starts at s


   Blockchecksum:

   When you want to save an edited datablock on a disk, you may have to update
   the checksum with this command:

   - K [s] : Sets new checksum of block that starts at s



   EXAMPLES:

    <t c00000 0 80
    >t c00000 0 80
    >s 70000 0 2
    <s 60000 880
    D1
    D? 2
    >f 0
    B 60000
    K 70000


   Fileoperations
   --------------

   L [f][s](n)(s) : Load file
   S [f][s][e]    : Save file
   V (path)       : List directory


   Paths and filenames can either be given plainly or between ' or ".
   The only devices known are DF0:, DF1:, DF2: and DF3:, disknames
   are not supported.


   Load File:

   This command loads a file directly into memory:

   - L [f][s] : Loads file f to s

   - L [f][s](n) : Loads n bytes from file f to s

   - L [f][s](n)(s) : Loads n bytes from file f to s, s bytes from the
                      start of the file

   Just make sure that you don't load files over SIM or the display.


   Save file:

   With this command you can save an area of the memory as file:

   - S [f][s][e] : Saves memory from s to e as file f

   This command is also used to delete files. To do so simply save a file
   with the name of the file you want to delete and the same start- and
   endaddress (filelength=0).


   List Directory:

   This command is used to list the directory of a disk or a user directory.

   - V [path] : Lists directory of directory specified by path.

   - V : Lists directory of last drive used for fileoperations.

   SIM reads the directory page by page because the display is used as buffer.
   If a page is full or the directory is read, it displays it. If there stays
   stuff to be displayed, SIM writes 'more' in the footer. You can then continue
   by pressing <SPACE>.


   EXAMPLES:

    L 'df0:c/dir' 60000
    S df1:data 0 100
    V df0:c


   Miscellaneous
   -------------

   ? [n]{,}(n) : Calculate
   F (n)(c){@} : Define functionkeys
   P (s)(m)    : Start graphic searcher
   H [s][e](p) : Hear sound
   s (p)(b)(c) : Set display, backup and program addresses
   l*          : Show copperlist
   l? (s)(e)   : Find active copperlist
   l= [n]      : Find copperlist one or two
   R [s]       : Set range for access scan


   Calculator:

   If you need to calculate something, you can do it with the '?' command.
   SIM will calculate the result of one or several terms and return the
   result(s) as hexadecimal, signed hexadecimal, decimal and binary number
   and as ascii chars:

   - ? [n] : calculate result of n

   You can calculate the result of several terms at the same time by seperating
   the terms by a komma.


   Functionkeys:

   The 'F' command is used to set and view the functionkeys functions:

   - F [n][c] @ : Occupies Fkey n with commandline c that is executed directly
   - F [n][c]   : Occupies Fkey n with text c
   - F [n]      : Clears Fkey n
   - F          : Lists Fkeys

   When you set a functionkey, the entier rest of the commandline will be
   taken for the command or text.

   When you list the functionkeys, the ones that are locked by Amiga-Fx are
   marked by an asterix, the directly executable have an '@' at the end.


   Graphic Searcher:

   The 'P' command starts the graphic searcher:

   - P [s][m] : Starts at address s with modulo m
   - P [s]    : Starts at address s with last modulo
   - P        : Starts at last address with last modulo

   When you have activated the graphic searcher, several keys are used for
   display modifications:

   Cursor up:         Scrolls plane one line down

   Cursor down:       Scrolls plane one line up

   Cursor left:       Scrolls plane one line right

   Cursor right:      Scrolls plane one line left

   Shift+Cursor up:   Scrolls plane one screen down

   Shift+Cursor down: Scrolls plane one screen up

   Help:              Modulo=modulo+2

   Del:               Modulo=modulo-2

   Shift+Help:        Modulo=modulo+16

   Shift+Del:         Modulo=modulo-16

   Backspace:         Modulo=0

   Return:            Switches between hires and lores

   Control:           Ends graphic searcher


   Since the graphic searcher also supports the memory manager a further
   improvement has been made. It is now possible not only to look at the
   chipmem but at the entier space of addressable memory including fastmem
   and rom.

   Because of technical reasons the status bar is now located at the bottom.
   It has also become neccessary to limit the modulo. It can now range from
   $ffb2 to $3ffe for a hires and from $ffda to $3ffe for a lores plane.


   Hear Sound:

   The 'H' command makes you listen to parts of the memory.

   H [s][e](p) : Hear memory from s to e with period p
   H [s][e]    : Hear memory from s to e with last period

   Memory manager is supported.


   SIM Addresses:

   The 's' command is used to transfer the display and backup and the SIM
   code itself:

   s [p][b][c] : New display at p, new backup at b and SIM copied to c
   s [p][b]    : New display at p, new backup at b and SIM stays where it is
   s [p]       : New display at p, backup and program stay where they are
   s           : Repaints the display

   Be carefull when you transfer the SIM code. SIM does adjust breakpoint and
   traps to the new address. But a possible debug server will only know
   about the new location when you quit. The old copy of SIM will still work,
   but its breakpoint and trap system will be confused. The same problem
   occurs when the tasktraphandle is set to SIM. Use this command only when
   the system is dead. Also do not copy SIM below $70!


   Copperlist:

   The 'l' command is basically used to disassemble a copperlist. The
   following variations are used for different actions:

   - l*        : Shows the active copperlist

   - l? [s][e] : Starts to search for the copperlist from s to e

   - l? [s]    : Starts to search for the copperlist from s to $80000

   - l?        : Starts to search for the copperlist from $70 to $80000

   - l= [n]    : Starts to search quickly for copperlist 1 or 2

   To end copperlist display or searching, press <CTRL>.

   When you search quickly, the copperlist you are looking for will be
   activated. If this one is not the running one, search again for the other to
   set the other copperlist again. This kind of searching has the risk that you
   may search for a copperlist that does not exist.

   This function does not work properly on MC68020+ due to some timing
   problems. Calling it on any MC68020+ may not find a copperlist.


   Set range:

   The 'R' command is used to define the range in which the access scan
   shortcuts will search for accesses. Default is $10000.

   - R [s]     : Sets range to s


   EXAMPLES:

   ? 256*5,52*56
   F10 r:dpc pc@
   F
   P 12356 52
   s 70000 c50000 c40000
   l*
   l=1
   l? 20000
   R $80000


 Debugger Window Support
 -----------------------

  A [s]    : Set new startaddress
  T [s]{@} : Set linkterm


  These two commands are used to set new startaddresses for the views of
  the debugger window.


  Startaddress:

  With this command you can directly set the startaddress of the active view:

  - A [s] : Set new startaddress of view to s


  Linkterm:

  To set a linkterm for a view, you use the 'T' command. SIM will calculate
  the result of this formula and use it as new startaddress each time it is
  entered:

  - T [s] @ : Set smart linkterm for active view

  - T [s] : Set simple linkterm for active view

  When SIM calculates a simple linkterm, it takes the result as new
  startaddress. The result of a smart linkterm is only used as new startaddress
  if it is not in the frame of the view. Normally this is only used to link
  a view to the PC.


  EXAMPLES:

  A a0+56
  T a0+d0
  T pc @



4.4     The Debugger Window
===========================


  You can switch it on or off by pressing <esc>. When you do so, a part
  of the worktable is locked for the cursor and used to print out the
  registers and one or two different views of the memory in different
  forms (hex, ascii etc.). The window is updated as soon as you execute
  a command that may change the memory and at entry of SIM.

  The two views have two startaddresses that are stored in m0 and m1.
  m1 is unused when you did not splitt the window and use only one view.

  You can link the two views to two terms, the socalled 'linkterms'.



 4.5 Debugger Window Shortcuts
 =============================


  If you have to deal with the window, you do this by use of shortcuts that
  are qualified by either left or right Amiga. If you splitted the window,
  you can select the view that recieves the command by pressing <TAB>.


 Window Handling
 ---------------

  <cursor up>     Decreases the views startaddress and scrolls the
                  content one line down. How much the startaddress is decreased
                  depends on what the window output form is:

                   - disassembly: the length of the instruction above the
                     startaddress.
                   - hexdump:     16 bytes.
                   - asciidump:   64 bytes.
                   - copperdump:  4 bytes.
                   - text:        one line.

  <cursor down>   Increases the views startaddress and scrolls the
                  content one line up. How much the startaddress is decreased
                  depends on what the window output form is:

                   - disassembly: the length of the instruction at the
                     actual startaddress.
                   - hexdump:     16 bytes.
                   - asciidump:   64 bytes.
                   - copperdump:  4 bytes.
                   - text:        one line.

  <cursor left>  Decreases the views startaddress one or two bytes:

                   - disassembly: two bytes.
                   - hexdump:     one byte.
                   - asciidump:   one byte.
                   - copperdump:  two bytes.
                   - text:        one byte.

  <cursor right> Increases the views startaddress one or two bytes:

                   - disassembly: two bytes.
                   - hexdump:     one byte.
                   - asciidump:   one byte.
                   - copperdump:  two bytes.
                   - text:        one byte.

  <shift cu>     Decreases the views startaddress and moves back to last
                 page, depending on the output form:

                   - disassembly: the sum of instruction lengths of the number
                     of instructions fitting the window back from the actual
                     startaddress.
                   - hexdump:     <number of lines>*16 bytes.
                   - asciidump:   <number of lines>*64 bytes.
                   - copperdump:  <number of lines>*4 bytes.
                   - text:        one page.

  <shift cd>     Increases the views startaddress and moves to next
                 page, depending on the output form:

                   - disassembly: sets startaddress to the address of the
                     instruction following the last one visible.
                   - hexdump:     <number of lines>*16 bytes.
                   - asciidump:   <number of lines>*64 bytes.
                   - copperdump:  <number of lines>*4 bytes.
                   - text:        one page.

  <alt cu>       Decreases the size of the debugger window by one line.
                 The minimum size is one line. The space that becomes free
                 for the monitor is cleared with spaces.

  <alt cd>       Increases the size of the debugger window by one line.
                 The maximum size is as large as there stays one line for the
                 monitor. If the cursor was in the line now belonging to the
                 debugger window, it is moved to the line below which is then
                 initialized.

  <shift alt cu> Works only when you splitted the window. This moves the bar
                 seperating the two views one line up, which decreases the
                 upper view and increases the lower view one line.

  <shift alt cu> Works only when you splitted the window. This moves the bar
                 seperating the two views one line down, which increases the
                 upper view and decreases the lower view one line.

  <s>            Splitts or unsplitts the window into two views. When you
                 unsplitt, the startaddress and linkterm of the active view
                 are taken as the one of the now single view, the ones of the
                 inactive view are stored and taken as the ones for the second
                 view when you splitt again.

  <r>            This recalculates the linkterm(s) and sets the
                 views startaddresses again.


  Output Form Selection
  ---------------------

  <a>            Selects asciidump for the active view.

  <m>            Selects hexdump for the active view.

  <l>            Selects copperdump for the active view.

  <m>            Selects disassembly for the active view.

  <p>            Selects text for the active view.

  <D>            Dis-/enables symbols in general.

  <S>            Allows symbols also for $xxxx(An) either only at the PC
                 or always.


  Breakpoints
  -----------

  <b>            Sets a simple Illegal breakpoint at the startaddress of
                 the active view.

  <v>            Sets a resident Illegal breakpoint at the startaddress of
                 the active view.

  <B>            Sets a JSR-breakpoint at the startaddress of the active view.


  Flow
  ----

  <z>            Does a tracestep.

  <u>            Does a nextstep that does not follow into subroutines.

  <i>            Leaves out one instruction/puts pc to next instruction.

  <x>            Exits SIM.

  <q>            Exits SIM and goes back to debug server.

  <g>            Leaves a subroutine. Therefore SIM puts a STACK-breakpoint at
                 the actual stackpointer and exits. Do not use this when the
                 subroutine has already put more data on the stack. This
                 corresponds to the command 'bssp:X'.

  <G>            Performs an RTS. Basically does 'rpc[sp]:rspsp+4'.

  <j>            Sets the pc to the startaddress of the active view.


  Edit
  ----

  <e>            Starts to edit in loopmode at the startaddress of the
                 active view.

  <n>            Starts to assemble in loopmode at the startaddress of the
                 active view.

  <N>            Replaces the Instruction at the startaddress of the active
                 view by NOPs.


  Indirects
  ---------

  <[>            Goes to next higher indirectlevel and takes the longword
                 at the startaddress of the active view as the new
                 startaddress and stores the old one.

  <]>            Goes to last indirectlevel and takes the stored
                 startaddress as the new one.

  <{>            Same as <[> but the longword will be taken as BCPL and
                 multiplied by four.

  <}>            Goes to next higher indirectlevel and takes the stored
                 address of that one as the new startaddress.

  <alt shift right>    If the instruction at the PC is a branch
                 of any kind, An indirection to the address of the branch
                 is done.

  <alt right>    If the instruction at the start of the view is a branch
                 of any kind, An indirection to the address of the branch
                 is done.

  <alt left>     Exdirects too.

  <shift alt left> Exdirects too.


  Find
  ----

  <f>            Continues to search at the startaddress of the active
                 view.

  <c>            Continues to compare. The source address will be the
                 startaddress of the first view , the destination address
                 the  startaddress of the second view.

  <>>            Initiates scan for accesses on start address of current
                 view. The range can be set with the 'R' command, default
                 is $10000. SIM will search both upwards and downwards for
                 accesses, the range specifies the maximum distance to test.

  <<>            Continues scan.


  Miscellaneous
  -------------

  <P>            Toggles the printer on/off. The printer can only be
                 activated if there is an active one connected to the parallel
                 port.

  <H>            Makes a hardcopy of the actual display by printing it as
                 text. You do not have to activate the printer first.

  <k>            Toggles between US keymap and custom keymap (originally CH)

  <!>            Flushes keystatefield, see chapter 'the keyboard'.

  <?>            Toggles keyboardbuffer killer, see chapter 'the keyboard'

  <+>            Toggles fully printable charset. When switched on (full), the
                 chars $0-$1f and $80-$9f are not replaced by a point in
                 asciidump, hexdump etc. Switch it off (semi) when using the
                 printer because else these chars would trouble it.

  <\>            Toggles Auto-Unmodify Traps. When this feature is switched
                 on, all modified traps are set again when you leave SIM.

  <F1-F10>       Toggles availability of funktionkeys.

  <0-9>          Takes one of the ten position memories as the startaddress
                 of the active view.

  <shift 0-9>    Works only with the keypad! Stores the startaddress of the
                 active view in one of the ten position memories.

  <M>            Toggles the MMU on or off (68020+ only).

  <L>            Switches between PAL, NTSC and NTSC overscan if ECS is
                 available. If not, NTSC users can switch between NTSC
                 and NTSC overscan only.

  <R>            Toggles register display mode: Either display MSP or
                 SR flags (68020+ only).


  Most of these shortcuts are only functioning when the debugger window is
  activated. Only <h>,<p>,<!>,<?>,<F1-F10>,<k>,<z>,<u>,<i>,<q>, <L>, <S>,
  <D>, <\>, <+>, <M>, <R> and <x> are always functioning.




*******************************************************************************
        5.      Additional Information
*******************************************************************************


5.1     Assembler Usage
=======================


  SIM contains a full 68000 assembler which allows you to make changes to
  programs while debugging. It supports the standard optimisations and
  aliases used by most other assemblers:


        - ADDI and ADDA can be replaced by ADD. ADDX can also be replaced
          by ADD if the effective addresses are address register indirect
          with predecrement.

        - SUBI and SUBA can be replaced by SUB. SUBX can also be replaced
          by SUB if the effective addresses are address register indirect
          with predecrement.

        - CMP can be used instead of CMPA, CMPI and CMPM.

        - EOR, OR and AND can be used instead of EORI, ORI and ANDI.

        - Bcc and DBcc instructions and PC-relative effective addresses
          use absolute addresses. It is possible to specify the offset
          directly by puting a '+' or '-' sign in front (but note that
          the offset is counted from start of instruction plus 2):

                00060010:       bra     $60000
            or  00060010:       bra     -$12

        - If no size is given, Bcc will be optimised to short if possible.

        - If no size given, memory direct effective addresses are optimised
          to WORD if possible.

        - If no size given for an instruction, the default size is used
          which in most cases is WORD.

        - The interpreter is very tollerant concerning spaces, a line like

                move.l    (  $75 ) (   PC  , D7.l  )  , ( $4 ).w

          will be accepted and assembled correctly.



5.2     Calculator Usage
========================


  The calculator is one of the central functions of SIM, all numeric input
  is handled by it. It disposes of several very useful operations and value
  forms. The following operators are supported, sorted after priority:


        ()      Brackets: Correspond to normal brackets. Number of opening
                and closing brackets must be the same. Maximum nesting
                is 127.

        []      Memory indirection: The result of the term in these brackets
                an address and the content of the memory at that address will
                be read.

                A size directly after the closing bracket will define if
                the value will be read as a BYTE, WORD or LONG and extended
                to LONG. I.e.: [4].l reads out AbsExecBase, [$dff002].w reads
                out the actual DMACON as a WORD.

        -       Prefix change: Changes a positive value to a negative and vice
                versa. I.e.: -5 is -5, -0 is 0, --6 is 6.

        ~       Logical NOT: Inverts all 32 bits of the value. I.e.: ~5 is -6.

        .s      Sizing: Any value will be extended to LONG from the size
                specified. I.e.: $89.b is $ffffff89.

                The size of the result is used both for the assembler when
                using memory direct effective addresses and for data input
                for the memory edit command etc. If multiple sizing operations
                occure, the last sizing operation in the lowest bracket level
                defines the finial size of the result.

        *,/     Multiply and divide: Signed LONG multiplication and division.
                I.e.: -$56*5 is fffffe52, 9/-3 is -3.

        \       Modulo: Signed LONG modulo. I.e.: 11\4 is 3.

        +,-     Addition and subtraction: LONG addition and subtraction.
                I.e.:   1000-9 is 991.

        <<      Shift left: Correspond to a multiplication with 2 to the nth
                power, whereas n is the numer of bits to be shifted.
                I.e.: $20<<8 is $2000.

        >>      Shift right: Corresponds to a division by 2 to the nth power,
                whereas n is the numer of bits to be shifted.
                I.e.: $2000>>8 is $20.

        &       Logical AND: LONG AND operation. I.e.: $1234&$ff00 is $1200.

        !       Logical EOR: LONG EOR operation. I.e.: $c1!$54 is $a5.

        |       Logical OR: LONG OR operation. I.e.: $1200|$34 is $1234.

        <>      Not equal: Result of this operation is -1 if values not equal,
                else 0. I.e.: 5<>6 is -1, 3<>3 is 0.

        =       Equal:  Result of this operation is -1 if values are equal,
                else 0. I.e.: 5=6 is 0, 3=3 is -1.

        <=,=<   Lower or same: Signed comparison, result is -1 if value left
                of operator is lower or the same than the right value.
                I.e.: 1<=1 is -1, 6<=5 is 0.

        =>,>=   Greater or equal: Signed comparison, result is -1 if value left
                of operator is greater or equal than the right value.
                I.e.: 2=>1 is -1, 0=>5 is 0.

        <       Less: Signed comparison, result is -1 if value left
                of operator is less than the right value.
                I.e.: 1<1 is 0, 0<5 is -1.

        >       Greater: Signed comparison, result is -1 if value left
                of operator is greater than the right value.
                I.e.: 2>1 is -1, 0>5 is 0.


  As for the form of values, the following are supported:


        $x      Hexadecimal number: A number in hexadecimal form, consisting
                of max. 8 digits 0-9 and a-f. I.e.: $badcode1

        #x      Decimal number: A number in decimal form, consisting of
                digits 0-9. I.e.: #1992.

        %x      Binary number: A number in binary form, consisting of
                max. 32 digits 0 and 1. I.e.: %1010001011.

        ',"     ASCII chars: A number consisting of max. 4 ASCII chars.
                The string must be introduced and ended with the same
                sign. If a ' must appear in a string introduced with
                ', two ' following each other mark one '. The same is valid
                for the ". I.e.: "SIM!", 'DATA', 'it''s','''' , '"MC"'.

        !       Last result: Stands for the result of the last term
                calculated. I.e.: To display 16 bytes at $50000 one can
                enter the command 'm $50000 !+$10'.

        @       Actual address. Stands for the actual address used by dump
                commands and edit/assembly commands. I.e.: @-100.

        SIM     SIM start: The program and base address of SIM.

        D0-D7 ,A0-A7 ,PC ,SP ,SSP ,USP ,SR ,CCR and M0-M7
        (MSP/ISP instead of SSP for 68020+)

                CPU registers: The calculator can directly use the content
                of these registers. SSP is the supervisor stack pointer,
                USP the userstack pointer SP and A7 the actual stack pointer.
                MSP and ISP are iaster and interrupt stack pointers.
                M0-M7 are variables, M0 and M1 are used as view start
                registers. I.e.: pc+10-d0.

        SEA, TEA, SX, TX

                The effective address of the source and destination EA of
                the instruction at the PC. The SX and TX registers are 1
                if the instruction has an source/destination EA, otherwise
                0 and the corresponding EA register is undefined. You shall
                not use any of these registers in a condition expression
                for trace or breakpoints. I.e.: sea*sx

        x,\x    Symbols: Uses the symbol specified after the '\'. I.e. \start.



  A calculator term normally ends at a space, a doubble point, a semikolon,
  a komma or a carriage return. If you have opened a bracket, you can have
  spaces between operators and values, but ONLY then. Otherwise, the end of
  the term will not be there where you wanted.

  The calculator can work in decimal or hexadecimal mode. In decimal mode you
  do not have to write the '#' before a decimal number, but for hexadecimal
  numbers, the '$' is neccessary. In hexadecimal mode you do not have to write
  the '$' before a hexadecimal number, but for decimal numbers, the '#' is
  neccessary.

  Hexadecimal mode is usually used to get addresses and hexadecimal numbers.
  For the other cases decimal mode is used, also for the assembler.



5.3     Data Line
=================


  The data line is used to specify data for different commands like
  find, edit, occupy. The dataline consists of four elements:

        -       Hexadecimaly numbers are introduced with or without '$'.
                They can be as long as neccessary. The number is ended by a
                char that is no digit. If you enter an odd number of digits,
                the last digit will be taken as byte, its higher nibble
                zeroed. Spaces are allowed between digits.

        -       Assembler instructions are initiated by a 'n', then the
                instruction follows.

        -       Calculator terms are initiated by a '?', then the term
                follows. The size of the result will be considered
                (LONG=4 bytes,WORD=2 bytes and BYTE=1 byte).

        -       Ascii chars are either initiated by ' or " and closed with
                the same or a <CR>.


  An example, using all the elements from above. The line:

        45,"ABC",njmp $60000,?[$fc0000].w,6666

  is interpreted as:

        45  41 42 43  4e f9 00 06 00 00  11 11        66 66
        |-  |-------  |----------------  |----        |----
        |   |         |                  |            |
        45  "ABC"     jmp $60000         [$fc0000].w  6666


   A dataline ends at a space or an illegal char. Between the komma that
   seperates two datatypes and the next datatype there can be spaces. also
   between digits (only for the edit command, not find and occupy).



5.4     The Debug Server Entrance
=================================


  The debug server entrance is specially concieved for the cooperation
  between SIM and another debugger or loader, i.e. SIM-BUG. It enables
  the debug server to give control over a program to SIM and SIM to return
  control to the debug server.

  In a part of the SIM base, there is space to store the registers d0-a6,
  USP and SSP (ISP/MSP), SR and PC of the program that is monitored. The
  debug server can fill in this table. Additionally, It can specify a
  reentry PC, SR, USP and SSP (ISP/MSP). When it enters SIM by the debug
  server entrance, SIM takes the registers out of the table and copies them
  into the workregister buffer. SIM has now the control over the program.

  If you want to give control back to the debug server, i.e. to unload the
  program, you can use the 'q' command (or 'Q' or AMIGA-q). SIM does then
  copy the workregisters back into the base area and takes the reentry PC, SR
  USP and SSP (ISP/MSP) as the actual ones. To be sure that the debug server
  is still there, SIM looks at the address <reentrypc-4> if the longword
  $4f4b4159 ("OKAY") is there. If the longword is there, it exits. That way,
  it returns to the address specified by the reentry PC with reentry stacks
  and a reentry SR. The registers do not contain sencefull information, appart
  a6 which contains the base/codeaddress of SIM. In case you transfered SIM,
  the debug server knows where you put it.

  The debug server can now read out the table with the registers and use
  them for itself.



5.5     The SIM Base
====================


  At the start of the SIM program, the different entrances are located,
  the backups and reentry values and the debug server datastructure. The
  structure of this base is documented here. The offsets described won't
  be changed in higher versions, I hope, but I feel free to extend it at
  the upper end.

  You may cut this list out and print it in order to have it ready when
  you need to edit a value in the base.


-------------------------------------------------------------------------------
 The S.I.M. Base Structure
-------------------------------------------------------------------------------

;--- Base ---------

 struct toolbase       ;+0  The startadress of S.I.M. in memory


;--- Display ------

 aptr  plane           ;+0  The startaddress of the $5000 bytes display ram
                            (must be chipmem!)
 aptr  backup          ;+4  The startaddress of the backup of the display.
                            When not zero, S.I.M. will copy what is in the
                            memory of the future display to this part of memory
                            when entered and copy it back when left.


;--- Entrances ----

 jmp   entrance1       ;+8  Entrance for JSR. Here you can simply enter S.I.M.
                            by a 'JSR' to this address.
 jmp   entrance2       ;+12 Entrance for Exec's traphandle. When you want to
                            use S.I.M. as traphandler of your task, write this
                            address to <taskstruct+50>.
 jmp   entrance3       ;+16 Debug server entrance.

 long  0               ;+20 *** RESERVED FOR EXPANSION ***


;--- Our Traps ----    ;When a trap is set directly, its vector is set to
                        the corresponding entrance in here.

 jmp   entrance22      ;+24 Bus error
 jmp   entrance23      ;+28 Address error
 jmp   entrance24      ;+32 Illegal instruction
 jmp   entrance25      ;+36 Divide-by-zero
 jmp   entrance26      ;+40 CHK instruction
 jmp   entrance27      ;+44 TRAPV instruction
 jmp   entrance28      ;+48 Privilege violation
 jmp   entrance29      ;+52 Trace
 jmp   entrance2a      ;+56 Op Code 1010
 jmp   entrance2b      ;+60 Op Code 1111


;--- Signal -------

 long  "SIM!"          ;+64 This Long signals that this is S.I.M.
 long  version         ;+68 Version of S.I.M. as 4 ASCII chars


;--- Backups ------    ;when S.I.M. is entered it backups some customregisters
                        and vectors here.

 word  dmacon          ;+72 $DFF096/002
 word  intena          ;+74 $DFF09A/01C
 word  intreq          ;+76 $DFF09C/01E
 long  level2          ;+78 $68
 long  level3          ;+82 $6C

 byte  ciaacra         ;+86 $BFEE01
 byte  ciaacrb         ;+87 $BFEF01
 byte  ciabcra         ;+88 $BFDE00
 byte  ciabcrb         ;+89 $BFDF00
 byte  ciaapra         ;+90 $BFE001
 byte  ciaaprb         ;+91 $BFE101
 byte  ciaaddra        ;+92 $BFE201
 byte  ciaaddrb        ;+93 $BFE301
 byte  ciabddra        ;+94 $BFD200
 byte  ciaasp          ;+95 $BFEC01
 long  vpos            ;+96 $DFF004

;--- Reentry ------    ;Reentry values of things that can't be saved.
                        When S.I.M. is left, it inits the registers named
                        with the values in this list.

 word  $2981           ;+100 DIWSTRT
 word  $29c1           ;+102 DIWSTOP
 word  $0038           ;+104 DDFSTRT
 word  $00d0           ;+106 DDFSTOP
 word  $5200           ;+108 BPLCON0
 word  $0000           ;+110 BPLCON1
 word  $0000           ;+112 BPLMOD1
 word  $0000           ;+114 COLOR00
 word  $0000           ;+116 COLOR01

;--- ICR Special --    ;The ICR data and mask.

 byte  lasticr         ;+118 $BFED00 read
 byte  reentryicrmask  ;+119 $BFED00 write

;--- Distances ----    ;Distances to internal structures.

 long  disasscalc-base ;+120 Distance to disasscalc module
 long  preferences-base;+124 Distance to preference structure

;--- Debug --------    ;Debug server structure for entrance 3.

 long  0               ;+128 Offset from base to end of inited part
 long  "????"          ;+132 Sign of server

;--- Program ------    ;The registers of the program that is debugged.

 long  0               ;+136 Register d0
 long  0               ;+140 Register d1
 long  0               ;+144 Register d2
 long  0               ;+148 Register d3
 long  0               ;+152 Register d4
 long  0               ;+156 Register d5
 long  0               ;+160 Register d6
 long  0               ;+164 Register d7
 long  0               ;+168 Register a0
 long  0               ;+172 Register a1
 long  0               ;+176 Register a2
 long  0               ;+180 Register a3
 long  0               ;+184 Register a4
 long  0               ;+188 Register a5
 long  0               ;+192 Register a6
 long  0               ;+196 User stack pointer
 long  0               ;+200 Supervisor stack pointer/ISP
 long  0               ;+204 PC of program
 word  0               ;+208 SR of program

;--- Server data --

 long  0               ;+210 Reentry routine of server
 long  0               ;+214 Reentry usp of server
 long  0               ;+218 Reentry ssp of server/ISP
 long  0               ;+222 Reentry sr of server

;--- Extension ----

 aptr  0               ;+224 Pointer to zero ended list of aptrs that point
                             to zero ended texts. The texts in this list are
                             printed and the pointer is cleared
 aptr  0               ;+228 Pointer to task structure, currently unused
 aptr  0               ;+232 Segmentlist, currently unused
 aptr  0               ;+236 Symbollist with labels, currently unused

 long  0               ;+240 MSP (68020+ only)
 long  0               ;+244 Reentry MSP (68020+ only)

 long  0,0,0,0         ; RESERVED

 long  sim_size        ;+256 Size of SIM
 byte  0               ;+260 CPU information
 byte  0               ;+261 MMU information
 word  0               ;+262 BEAMCON0 reentry value
 long  0               ;+264 VBR

;--- End ----------    ;+240 This is the end of the actual structure

--------------------------------------------------------------------------------



5.6     Errors
==============


 SIM is a flexible tool. Therefore the user can do many mistakes.
 In this chapter, all errors are explained. When an error occurs that
 bases on an error in the command line (which in fact is in most cases so)
 SIM prints the error text in the line of the cursor and copies the command
 line in the next line. The cursor is in the line of the copied command line
 below the char or the word that probably caused the error.


 Assembler errors:

   illegal instruction:
     The assembler does not know this instruction.

   illegal value:
     An number is higher or less than it should be.

   illegal ea:
     This 'effective address' is not allowed. In fact it has not always
     to be an effective address for the assembler uses the same routine for
     all source- and destinationterms.

   illegal size:
     An instruction has either no size at all or does not support the
     one you have given.

   illegal operator:
     An operator is not just as it should be.

   line malformed:
     Something is undefinably wrong.

   too few info:
     Some part of this instruction is missing.

   illegal sea:
     An illegal effective address as source.

   illegal tea:
     An illegal effective address as destination.

   illegal char:
     The assembler is suprised to find that char.

   illegal condition:
     The condition of a Bcc, DBcc or Scc is inexistent.

   illegal direction:
     The direction for bitshifting is neither left nor right.


 Calculator errors:

   bracketerror:
     You have opened more brackets than you closed or vice versa.

   overflow:
     The result is larger than $ffffffff or ±$8000000, or you
     have divided by zero or you do more than 30 operations.

   illegal value:
     The calculator cannot interprete that as a number.

   illegal operator:
     This is no operator for mathematical operations supported by the
     calculator.

   no value given:
     You have forgotten to give a term, or the very first value of an
     expected term is of an unknown type.


 SIM errors:

   too much:
     The startaddres given for a command is higher than the endaddress.

   breakpointerror:
     SIM has no more breakpoints free or it could not set a breakpoint there,
     either because ROM is read only or it is not possible to put breakpoints
     in the memory presently occupied by the SIM code.


 Diskaccess errors:

  disk error:
    Something went wrong with the diskaccess, either the track that is read
    is damaged or the disk was writeprotected. In most cases you will get a
    warning in the statusline of the diskaccess display.

  file not found:
    SIM could not locate the file you want to load or a directory in its path.

  not enough space:
    When you want to save a file, SIM first checks if the file would fit.
    If it wouldn't, this error is returned.

  disk full:
    That error should not occure.

  directory error:
    If something goes wrong in the line of the listing of the directory,
    i.e. bad hashes or disk damaged, this error is returned.

  illegal path:
    SIM cannot locate the directory you want to list.



5.7     Footer Messages
=======================


  As mentioned earlier, there is a status field in the footer line. This
  space is used to transmit messages to the user that are not as important as
  to be printed in the monitor or serve as additional information.
  Currently the following texts can appear there:


   - busy        : As soon as SIM is doing something this text is printed.
                   This shows you If SIM is working or not.

   - break       : When you break the execution of a command SIM replys with
                   this message.

   - pause       : When you pause.

   - lock        : When you press SHIFT-CTRL to stop all output for some time.

   - Fx on/off   : When you toggle function keys SIM returns the new state
                   to you this way.

   - flushed     : When you flush the keystatefield.

   - prt err     : When the printer has troubble (paper out/select...)

   - cnd err     : When an error occurs while calculating the condition terms
                   of breakpoints or trace, SIM is entered and this text
                   appears

   - prt on/off  : When you toggle the printer and it is available.

   - AUT on/off  : When you toggle Auto Unmodify Traps

   - US kmap     : When you select the secondary (US) keymap

   - xx kmap     : When you select the primary (custom) keymap

   - indir x     : When you use indirects the current indirect level
                   is told you so.

   - return      : When you return from the keyboard restoring routine
                   by entering 'return'.

   - KBF on/off  : When you toggle the Keyboard Buffer Killer.

   - more        : When the directory of a disk does not fit in the monitor
                   part SIM writes that message to tell you that there is more.

   - MMU on/off  : The status of the MMU tree (68020+ version only).




*******************************************************************************
        6.      Appendix
*******************************************************************************



6.1     Acknowledgements
========================


  Big thanks must go to all the people who helped me in this project and
  many others:


        Daniel Weber for continuous testing of all new features I
        inserted, some good and some bad ideas and his mighty ProAsm.
        Not to forget, for all the cool movies each saturday too.

        René Eberhard for more tips, betatesting, exchange of KS 2.0
        knowhow and loads of fun at MicroSpot and Feller and everywhere
        else.

        Bryan Ford for many good ideas, betatesting, tons of hints,
        proofreading my documentations and all the cool e-mail chat
        and much more.

        André Dietisheim, Oliver Ferlin, Stefan Strasser, Kay Temirel,
        Christian Schneider and Niel Ericson for bugreports and ideas.

        Michael Hitch for MC68040 testing.

        To all the registered users.



6.2     Registered Users
========================


  Thanks go to the following users who registered and persuaded me that some
  people use this tool:


        Daniel Weber            (Switzerland)
        René Eberhard           (Switzerland)
        Kay Temirel             (Germany)
        Niel Ericson            (Canada)
        Roby Leemann            (Switzerland)
        Steve Anderson          (Canada)
        Jörn Körner             (Germany)
        Bryan Ford              (USA)
        Dan Babcock             (USA)
        Gerd Hesina             (Austria)
        Jandl Mario             (Austria)



6.3     My Address
==================


  If you want to register, if you have bugreports, question, ideas or
  complaints (constructive criticism is always welcome), or if you just want
  to contact me, write or send a letter to:

        Stefan Walter
        Finsterruetistr. 57
        8135 Langnau a./A.
        SWITZERLAND

  Because snail mail is slow, you can also contact me by phone or by sending
  a message to the electronic mail address below (if you call by phone,
  please concider any possible time differences and don't wake me up in the
  night :).

        Phone:          Switzerland/(0)1/713-01-46
        Internet:       avalon.physik.unizh.ch!swalter




-------------------------------------------------------------------------------
                                                     Stefan Walter, 15.Nov.1992