World of A1200/World_Of_A1200.iso/programs/develop/here/simbug/docs/sim.doc

Text File | 1995-02-27 | 115KB | 3,565 lines

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

                                   S.I.M.

                         System-Independent Monitor
                                Version 1.72

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

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



             The User Manual, refering to version 1.72 of S.I.M.




                                   WARNING
                                   =======


          This  version  of  SIM  is  not really official.  It was
          released  because  some  developers  and programers have
          requested   it  and  because  it  currently  serves  for
          debugging  Amiga  Mach.   It  is  beta test ware and not
          complete  by  any means.  A completely rewritten version
          is halveway finished and will be out soon.

          SIM  will  now  work on all existing Amigas running with
          MC60000   or   MC68020/30/40,   on   later   with   some
          limitations.  It works now on both PAL and NTSC machines
          with OCS/ECS/AGA.

          This   program  is  still  shareware,  only  Amiga  Mach
          developers  and  owners  of  NOG2  automatically  become
          registered  users.   No  warranty  for  functionality is
          given.








                                 CONTENTS
                                 ========


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

        1.1     Welcome to SIM
        1.3     Disclaimer
        1.2     About this Documentation


2.      Getting used to SIM
---------------------------

        2.1     What Is SIM?
        2.2     Who Can Use It
        2.3     Qualifications, Requirements and Limitations
        2.4     The 68020+ Version
        2.5     Configuring SIM
        2.6     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    Function Keys
        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
        3.21    Interrupt Lockup


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     Contacting Me




*****************************************************************************
        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.

'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 program from somebody else and you like it and keep using
it,  you  are  asked to send a little contribution of 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 used to.




*****************************************************************************
        2.      Getting used to 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.

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, no matter when it was stopped.



2.2     Who Can Use It
======================


SIM  was  written  to  be  used  by both serious programers of nice and clean
applications,  who  follow  the  guide  lines of Commodore, as well as by the
socalled  'democoders' who write programms which directly access the hardware
and  disable  multitasking  (and  who lately have become deprived to do so by
Commodore  :).   It  was originally mainly intended for the later, but it has
proven to be very useful for debugging applications too.

It  is  distributed  with the neccessary utilities to apply it on any kind of
program  that  need  to  be  debugged  at  a  given  time.   They are not too
comfortable yet, intuition based 'V36+ only' versions are planned.

SIM  will  be  very  useful  for  you  if  you  need  to debug programs which
temporarily  disable  multitasking.   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.3     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, especially the
part  that  deals  with  the  display.   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.   You  should  also  not  invoke  SIM  from within a level 2
interrupt  before  it  has  dealt  with keyboard events or keystrokes will be
lost.



2.4     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 yet if not absolutely neccessary.

There  is  currently  no  version  working  on 68010 Amigas because I have no
access  on  any  machine to try out any adaption to this CPU.  If anybody out
there feels she/he needs a version of SIM for 68010 and is willing to do some
beta testing, I will write a 68010 version.

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 tools supplied with SIM do this before they invoke
        SIM.

      - 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.   You  can  activate  the MMU again, SIM will then install a
        primitive  bus error handler which prevents craches in case of a tree
        containing illegal descriptors.



2.5     Configuring SIM
=======================


You  can't  use  SIM  right  away, you need to configure a copy to your Amiga
first,  that  is for the CPU and the memory configuration it uses.  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:

      - All memory
      - Kickstart image

Get  all  start-  and end addresses and sort them from lowest to highest.  If
neccessary  use  some  system  information  tool  to  get  the  start and end
addresses of all your memory blocks.

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  end address for the 68000
version, $80000000 for the 68020+ version.

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



2.6     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.
20480/$5000  bytes  of graphic memory are needed for a 640*256 bitplane.  But
at a certain moment, there may be no 20480 bytes graphic memory available.

The  solution  is  the  backup.   When you have an area of $5000 free graphic
memory  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 graphic memory or it will be used entierly
in  near future and you have enough (that is $5000 bytes) unused other memory
that  won't  be  used  for sure, you set the backup address to the start of a
free  $5000  bytes  block  of  other  memory  and the display address just to
somewhere  in  the  graphic  memory.   When  SIM  is activated, It copies the
content of the $5000 bytes display- to the backup memory and uses the display
memory.   When  you  leave SIM again, it copies the $5000 bytes back from the
backup- to the display memory.  That way, the graphic memory 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 the end of the graphics memory minus $5000.

Both  the  display-  and  the  backup address 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 which
stops  it and gives control to the debugger that set it.  In other terms, you
can  run  the  program at full speed until it executes 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
remove it (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 via the task
traphandle,  set  by 'SIMBug' 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 term 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.

        The use of SEA, TEA, SX and TX is allowed,  but you must first toggle
        on EA calculation using the AMIGA-Z shortcut.


      - 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  it  is  removed.   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'.

SIM  uses the TRACE vector to skip a resident or conditioned breakpoint if it
has  not  caused  entry  into SIM.  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, i.e.  in
routines  accessed  by  multiple  tasks or places where the illegal vector or
task traphandle is 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 will cause problems!
        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 for rts!) 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 'Return From ...' instruction.
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 term 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.

        The use of SEA, TEA, SX and TX is allowed,  but you must first toggle
        on EA calculation using the AMIGA-Z shortcut.


      - 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.


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 character,
that  character  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.

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 and is off by default.



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.  If you are
using  disk  commands, make sure a disk is always inserted or the drive motor
will  be  stoped after the command has completed although it was on.  This is
because  SIM  needs a disk to be inserted in a drive to find out if its motor
is turning.

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 repair partially destroyed tracks.

5 1/4" and HD drives as used in the A4000 are not supported yet.



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


You  can load any files of an OFS DOS disk 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 a command or to pause
it.   SIM  can do 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 th command execution 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 command line 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.



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 start address.  This address has the name '@' for the
calculator.   It contains the end address 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 send addresses to this buffer.  You can also also specify
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 old ones.

      - 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 is mainly integrated to search for counters.

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 currently 10:


        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' 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 command lines.  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 between 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 occur 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 due to
breakpoints in library vectors or other places where multiple tasks access.



3.12    Function Keys
=====================


The  ten  function  keys  can  be loaded with a text or command line.  If you
define  a text, it is copied at the location of the cursor when you press the
function key.  If you define a command line, it is executed directly.

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


        F1:  z@         For easy tracing.

        F2:  u@          " "

        F3:  i@          " "

        F4:  f@         For repeated finding.

        F5:  c@         For repeated comparing.

        F8:  v:X@       When an  exception vector is set  and an exception of
                        that kind  happens  and has  to be dealt with  by the
                        original vector.

        F9:  dm0 m0@    For finding  disassembly  without using  the debugger
                        window.  Initially deselected:

        F10: r:dpc pc@  For  tracing   without  using  the  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 *)

        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 **)


*) 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.   Since  the  disk-DMA  is left on, remember that when the disk-DMA is
terminated, bit 1 in the INTREQ is set.  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 about the actual contents, you
must read out INTREQ 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.


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.   If  you  need  to change one of them, you must change the
value stored in the base.

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 are put back when
SIM exits.  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  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.


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 completely 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.

If AGA is present, SIM also writes directly to some undocumented registers to
build up its display:


        $DFF106:        $0c40
        $DFF1E4:        $0000
        $DFF1FC:        $0000



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 have been
modified  and  overwritten.  In that case you should either reset the vectors
that have been changed or remove then.



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
controls  memory  access  by  certain  commands  and  forbids  read and write
accesses to addresses where no memory is located:


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

      - At  VBR+$68  and VBR+$6c it inserts the level 2 and level 3 interrupt
        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.  To continue to work, press
any key, best would be a qualifier.



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


SIM  can  calculate effective addresses.  The source EA of the command at the
PC is displayed below A6 of the small register list, the destination EA below
A7.   In  the large register list, the last line contains a 6 byte hexdump of
both the asource and destination EA.

EAs  can  be  used  in  calculator  terms.  The source EA is named 'SEA', the
destination EA is 'TEA'.  For both exists also a register 'SX' and 'TX' which
is  0 if the corresponding EA is not used by the instruction at the PC, and 1
if it is used.



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.  The shortcut AMIGA-SHIFT-d toggles use of the symbols.



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.  The shortcuts used to toggle is is AMIGA-L.



3.21    Interrupt Lockup
========================


SIM  uses  the  VB interrupt for its display setup and the PORTS interrupt to
handle  the  keyboard.   The  concept  of  the  Amiga allows external devices
connected  to  the  expansion  port  or the Zorro bus to generate interrupts.
Most  harddisk  controlers  use  this  feature  and  generate  Level  2 and 3
interrupts.   The basic problem for SIM is that if such a device generates an
interrupt,  it  does  not neccessarily clear the request by clearing a bit in
the INTREQ register.  Many devices have their own interrupt request register,
located  somewhere  in  the  Zorro address space.  Only the interrupt handler
that  is installed when the device is mounted knows about the address of that
register.  Therefore SIM cannot cancel such an interrupt and the result would
be that the machine either locks up or that the device fails.

To prevent this, SIM will detect if a level 2 or 3 interrupt was generated by
an  external  device.   If  it  is,  SIM will automatically exit, execute the
interrupt  routine  for  the  pending  interrupt  and  return through the JSR
entrance.




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



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


SIM  provides  a  display  of 200|224|256*640 pixels or 25|28|32 lines and 80
rows,  depending on the resolution you use.  The screens colors are green and
dark  blue.   The  screen is devided in header, worktable/debugger window and
footer, all separated by a bar of '­' chars.

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

The  worktable  and  the  debugger  window  share  21|24|28  lines.   In  the
worktable,  actually  the  monitor,  you can move the cursor around and enter
commands.   Output  of commands is also displayed in this part.  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  contents  of the part of the worktable covered by the debugger window is
remembered and restored if the window is removed.

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



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.   it  is  available  again if you enter SIM again, the display
        will be the same.

      - SIM has two entier keymaps for not qualified, shifted, alternated and
        shifted+alternated keys, one one custom and one USA.

      - CTRL-keys  with  assigned  chars  with ascii values from $40-$5f will
        result  in  a  char  with  the  ascii value from $0-$1f (i.e.  CTRL-J
        (=$4a) => <CR> (=$a))

      - CTRL-keys  with  assigned  chars  with ascii values from $60-$7f will
        result  in  a  char  with  the  ascii value from $0-$1f.

      - Cursor keys move the cursor by one step.

      - SHIFT-Cursors key moves the cursor in the extreme positions.

      - 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 visible worktable and put the cursor in the
        left upper corner next to a period.

      - 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 help page, starting in the line below the line
        the cursor is in actually.

      - SHIFT-HELP prints the second help page.

      - F1  to  F10  either execute the command line stored or print the text
        stored.

      - 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 with SHIFT-ESC.

      - CR will execute the commands in the line where the cursor is.

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

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



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


The command line contains the different commands to be executed.  Its form is
as follows:


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


You  can enter several commands in one line, separated by a colon.  The colon
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  with  SIM, you can get a little list of all commands with the
two help pages by pressing HELP or SHIFT-HELP:


     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     :recreate 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


     >f(n)    :format disk | <s [s][s](n) :read secs
     D (n)    :set drive   | >s [s][s](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 help page and the explanations, the following shortenings are used for
options:


        s: start address|seek value             e: end address
        i: assembly instructions                d: data line
        n: decimal number                       x: hexadecimal number
        r: register                             p: plane address
        ?: condition term                       f: file name
        t: destination address|track number     c: text|command line
        m: mask|modulo                          b: backup/breakmode/block
        j: options|flags


        Options in '[]' are neccessary.
        Options in '()' are optional.
        Chars in '{}' are optional flags.


Because  space in SIM is limited, these help pages tell only the basic syntax
of  a  command.   In  the  rest  of  this chapter all commands with all their
possibilities and what you can do with them are listed.








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


        m (s)(e)        Print memory as hexdump
        a (s)(e)        Print memory as asciidump
        d (s)(e)        Disassemble memory
        l (s)(e)        Disassemble memory as copperlist
        p (s)(e)        Print memory as text


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

        command (start address) (end address)

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

If  you give only the start address, SIM starts to dump from that address and
displays eight lines.

If you do not give any address, SIM takes the actual address as start address
and displays eight lines.

Adress spaces which are not defined are read zero.

In  disassembly,  the instructions BSR,JSR and TRAP #x are indented and after
the instructions JMP, BRA, ILLEGAL, RTS, RTE, RTR and RESET a separating line
of  '-'  is  printed.   Additionally,  resident  breakpoints are marked by an
asterix, JSR breakpoints with a plus sign amd normal breakoints with a cross.



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 directly to memory.  The edit command can write data
to  memory  (see  chapter  'Data  Line'  for details) The assemle command can
assemble  one  or  several  instructions  separated  by  a ',' to memory (see
chapter 'Assembler Usage' for info)

If  you  give  both  start  address  and  data/instructions,  SIM  writes the
data/instructions to memory.

If  you  only give the start address, 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 assembly 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
        e>00070000:
        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.  Memory managing
is used, undefined memory is read zero and not written to.

        t [s][e][t]     Transfers memory from s to e to new address t.




Occupy:

The 'o' command will fill a defined area of memory with a byte pattern.

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




EXAMPLES:

        t 0 10000 00c00000
        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 sophisticated data search and compare commands.  For any of
the  find or compare commands you can specify the following options after the
end address:


      - +/-n    Sets  the  step  rate.  Only at every nth address is the data
                are compared.

      - '*'     Specifies that 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 options.  SIM will then execute
                F9  each  time something is reported and put the start of the
                active view of the debugger window to that address.

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




Find data:

You  can  search  in  a defined area in the memory for a certain byte pattern
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 options j
                        for  the byte pattern d that is 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 options
                        j.

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

        f [s]           Starts to search from s.

        f               Continues to search after the last address reported.




Find disassembly:

This command searches an instruction or a fragment of it in a defined area of
the  memory.   Like the 'find data' command, 'find disassembly' does not need
all options:

        f [s][e](j) i [i]       Starts to find from s to e with options 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 options j.

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

        f [s]           Starts to search from s.

        f               Continues to search after the last address reported.


The  instruction i can be only a fragment like '4(a6)' or '@su*' or an entier
instruction  like  'moveq  #3,d0'.   Because  the disassembler calculates the
addresses  of  PC relative addressing modes, this command can also be used to
track  down  accesses  to  addresses.   Several rules must be concidered when
designing the search text:


      - If  there  is  a space in your text, 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  wildcard.   It replaces one char.  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:

This  command  will  compare  two  areas of memory and report addresses where
bytes differe or are the same:


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

        c [s][e][t]     Compares with no options.

        c [s][t]        Continues to compare from s and t.

        c [s]           Compares from s.

        c :             Continues to compare after last address reported.




Matchbuffer:

This  command  allows  you to manipulate and view the matchbuffer.  Refere to
the chapter 'The Matchbuffer' for further information.

        k [s][e]        Locates the matchbuffer from s to e and clears it.

        k *             Clears matchbuffer.

        k ?             Shows the location and number of entries.

        k @ [s]         Shows  all  matchbuffer  entries  larger  than  s  by
                        reporting  them one  by one using F9 and the debugger
                        windows active view.

        k [s]           Lists all entries higher than s

        k               Lists or shows next entries.




EXAMPLES:

        f 0 100 00
        f 10000 20000 !nm 05
        f 0 20000 @ imoveq #*
        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 and isp/msp or vbr (68020+ only) or to view them:


        r [r][x]        Sets register r vith new value x.

        r               Views registers.

        r?              Views memories m0-m7.




Traps:

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 all ten vectors.

        wk              Clears all traps.


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

Refere to the chapter 'Traps' for further information.




Create Traps:

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 exception that forced entry.

        v?              Gives information about the 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 due to an exception.

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 and
puts the old stackframe back.




EXAMPLES:

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







Breakpoint and Trace
--------------------


        b (s)(j)        Set/clear and view breakpoints
        u               next step
        z (j)           trace step
        i (n)           leave out instructions


Breakpoints:

The  'b'  command  is  used  to  handle breakpoints.  When you set an illegal
breakpoint,  you  can  specify the trigger conditions after the address.  The
following conditions are accepted:


      - 'l', 'r', 'j'   Breaks when left, right or joystick button pressed.

      - [n]             Breaks after breakpoint is reached n times.

      - '?'[n]          Breaks when term n is true (<>0).

      - *               Breakpoint is resident.


Refere to the chapter 'Breakpoints' for more information.


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

        b [s]           Sets a simple breakpoint at s or clears one.

        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  set  or remove several breakpoints at a time by separating the next
address from the previous address or options by a komma.




Trace Step:

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

      - 'l', 'r' or 'j' Traces until button pressed.

      - [n]             Traces n steps.

      - '?' [n]         Traces until term n is true (<>0).

      - '*' [s]         Traces until pc=s.

      - 'c'             Emulates 68020 trace steps.


Refere to the chapter 'Trace' for more information.

        z [j]           Traces until a condition j is fullfilled.

        z               Does one trace step.




Next Step:

The  'u' command does either one trace step or when the instruction at the PC
is  a  JSR,  BSR  or  TRAP  #x,  it  does  a trace step and then sets a stack
breakpoint at a7 (or a7+2 when the instruction was TRAP #x) and exits:


        u               Do one step.


Leave Out Instruction:

This command simply sets the PC one or n instructions further:


        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, reply with 'y' or 'n'.  'X' simply
exits:

        x               Exits, but asks for confirmation first.

        X               Exits directly.




Quit:

The  'q'  or  'Q' commands are used to return control over the program 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.


Note  the difference between the exit and the quit command.  The exit command
lets  the program continue.  The quit command calls the debug server and lets
it  deal  with  the  situation.  The program is not continued.  Refere to the
chapter 'The Debug Server Entrance' for more information.




Go Subroutine:

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


        g [s]           Call subroutine at s.

        gw [s]          Prepare stack for subroutine call but do not exit.


When SIM calls a subroutine, it first pushes the old pc on the stack and then
the  return  address  for  the  rts.   If the subroutine completes with a RTS
instruction, SIM is invoked again.

The  'gw'  command  does only prepare the stack for the operation, that is it
pushes  the  return  address  and the old PC value on the stack, 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 and each time a conditioned breakpoint is reached:


        h [n]           Display nth last history.

        h               Display all five history entries.


SIM does not only remember the registers d0-a6, usp, ssp (isp/msp), 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 for disk operations
        <t (s)(s)(n)    Read tracks
        >t (s)(s)(n)    Write tracks
        <s (s)(s)(n)    Read sectors
        >s (s)(s)(n)    Write sector
        >f (n)          Format disk
        B  (s)          Calculate bootblock checksum
        K  (s)          Calculate block checksum


Set Drive:

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


        D [n]           Uses 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.




Read Track:

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


        <t [s][t][n]    Reads n tracks starting with t to s.

        <t [s][t]       Reads one track t to s.


SIM  does  not  test  where  the data is read to, you should not overread the
display or SIM.  Memory managing is not yet supported in this function.




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.


This command does not support memory managing yet.




Read Sector:

With the '<s' command you can 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.


This command does not support memory managing yet.




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.


This command does not support memory managing yet.




Format Disk:

The '>f' command is used to format and initialize a disk with OFS:


        >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.  AmigaDOS cannot separate
disks  with  the same name and same date.  So never keep two datadisks in two
drives simultaneously, or DOS will get into troubble.

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




Bootchecksum:

When  you  want  to  save  a  bootblock to 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.
Refere to chapter 'Files' for more information.


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)(o)  Loads n  bytes  from  file f to s,  o bytes from  the
                        start of the file.


Memory managing is supported.  You still should not load data over SIM.




Save File:

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


        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 end address
(filelength=0).

Memory managing is supported.




List Directory:

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


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

        V               Lists directory of drive used last.


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 is more
to  be displayed, SIM writes 'more' in the footer.  You can continue and view
the next part 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 function keys
        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


Calculate:

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 separating
the terms by a komma.




Function Keys:

The 'F' command is used to set and view the function key definitions:


        F [n][c] @      Defines key n  with command  line c that  is executed
                        directly.

        F [n][c]        Occupies key n with text c.

        F [n]           Clears key n.

        F               Lists key definitions.


When  you  set  a  function  key, the entier rest of the command line will be
taken for the command or text.

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




Graphic Searcher:

The 'P' command starts the one plane 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, the following keys are used for
display control:


        Cursor up        Scrolls plane one line down.

        Cursor dn        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 dn  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.

        CR               Switches between hires and lores.

        CTRL             Ends graphic searcher.


Since  the  graphic searcher also supports the memory manager, it is possible
not only to look at the graphic memory but at the entier space of addressable
memory including other memory and rom image.

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 sends an area of memory as a sample to the audio hardware:


        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, SIM copied to c.

        s [p][b]        New display at p, new backup at b.

        s [p]           New display at p.

        s               Redraws 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 SIM.  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.

SIM  does  not  check the values you enter, make sure that you do not specify
locations where i.e.  display and SIM would overlay.




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?              Searches 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.

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




Set Scanrange:

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 start address
        T [s]{@}        Set linkterm


Start Address:

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

        A [s]           Set new start address of view to s.




Linkterm:

To  set  a  linkterm for a view, you use the 'T' command.  SIM will calculate
the  result  of  this  term  and  use it as new start address each time it is
entered or the AMIGA-r shortcut is pressed:


        T [s] @         Set smart linkterm for active view.

        T [s]           Set simple linkterm for active view.

        T               Removes linkterm.


When  SIM  calculates  a  simple  linkterm,  it takes the result as new start
address.  The result of a smart linkterm is only used as new start address if
it  is  not  in  the space currently displayed in 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 (disassembly,
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 start addresses that are stored in m0 and m1.  m1 is
unused when you do 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
=============================


The  window  and its views are controled with shortcuts that are qualified by
either  left or right Amiga.  If you have splitted the window, you can select
the view that recieves the commands by pressing <TAB>.








View Address
------------


        Cursor up       Decreases  the  views  start  address and scrolls the
                        display one line down.

        Cursor dn       Increases  the  views  start  address and scrolls the
                        display one line up.

        Cursor left     Decreases  the  views  start address by one byte (two
                        bytes for disassembly and copper dump).

        Cursor right    Increases  the  views  start address by one byte (two
                        bytes for disassembly and copper dump).

        SHIFT-C up      Decreases  the  views  start  address and scrolls the
                        display one page up.

        SHIFT-C dn      Increases  the  views  start  address and scrolls the
                        display one page down.

        ALT-C up        Decreases  the  size of the current view by one line.
                        The minimum size is one line.

        ALT-C dn        Increases  the  size of the current view by one line.
                        The  maximum size is as large as there stays one line
                        for the monitor.  If the cursor was in a line used by
                        the  debugger  window, it is moved to the top line in
                        the worktable.

        SHIFT-Alt-C up  Moves  the  bar separating the two views one line up,
                        which  decreases  the  upper  view  and increases the
                        lower view one line.

        SHIFT-Alt-C dn  Moves the bar separating the two views one line down,
                        which  increases  the  upper  view  and decreases the
                        lower view one line.

        s               Splitts  the window into two views or unsplitts again
                        and removes the inactive view.

        r               Recalculates the linkterm(s) and sets the views start
                        addresses again.







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


        a               Selects asciidump for the active view.

        m               Selects hexdump for the active view.

        l               Selects copper disassembly 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 throughout the entier disassembly.







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


        b               Sets an unconditioned illegal breakpoint at the start
                        address of the active view.

        v               Sets  an unconditioned resident illegal breakpoint at
                        the start address of the active view.

        B               Sets  a  JSR-breakpoint  at  the start address of the
                        active view.








Flow
----


        z               Does one trace step.

        u               Does  one  trace  step  that  does  not  follow  into
                        subroutines.

        i               Puts PC to next instruction.

        x               Exits SIM.

        q               Quits SIM and returns control 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 line 'bssp:X'.

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

        j               Sets the pc to the start address of the active view.








Edit
----

        e               Starts  to  edit  in  continuous  mode  at  the start
                        address of the active view.

        n               Starts  to  assemble  in continuous mode at the start
                        address of the active view.

        N               Replaces  the instruction at the start address of the
                        active view with NOP instruction.







Indirection
-----------


        [               Goes  to  next higher indirection level and takes the
                        longword  at  the start address of the active view as
                        the new start address and stores the old one.

        ]               Goes  to  previous  indirection  level  and takes the
                        stored start address as the new one.

        {               Same as AMGIA-[ but the longword will be read as BCPL
                        and multiplied by four.

        }               Goes  to  next  higher indirection level and uses the
                        last address this level pointed at.

        SHIFT-ALT-C left  If  the  instruction  at  the PC is a branch of any
                        kind,  an indirection to the address of the branch is
                        done.

        ALT-C           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.

        SHIFT-ALT-C right Goes to previous indirection level.

        ALT-C right     Goes to previous indirection level.


The  indirection  commands  can  have  a maximum depth of 8 levels.  SIM does
never reset to the first level on its own, if you have reached the limit, you
must reset it by returning to level 1.









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


        f               Continues  to  search  at  the  start  address of the
                        active view.

        c               Continues to compare.  The source address will be the
                        start  address  of  the  first view , the destination
                        address the start address 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 one connected to the parallel
                        port and it is selected.

        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.

        !               Flushes keystatefield, see chapter 'The Keyboard'.

        ?               Toggles  keyboard  buffer  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 period in asciidump, hexdump etc.  Switch it off
                        (semi) when using the printer.

        \               Toggles  the  auto-unmodify traps feature.  When this
                        is switched on, all modified traps are set again when
                        you leave SIM.

        F1 to F10       Toggles availability of funktion keys.

        0 to 9          Takes  one  of the ten position memories as the start
                        address of the active view.

        SHIFT-0 to 9    Stores the start address of the active view in one of
                        the  ten  position  memories.   Works  only  with the
                        keypad!

        L               Switches  between  PAL, NTSC and NTSC overscan if ECS
                        or  AGA chipset is available.  If not, NTSC users can
                        switch between NTSC and NTSC overscan only.

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

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

        ®               Toggles register display mode:  Either small register
                        list or large.

        Z               Toggles  EA calculation for condition breakpoints and
                        trace  on/off.  If the SEA, TEA, SX or TX register is
                        used in an condition expression, switch this on.









*****************************************************************************
        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  occur,  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.
                I.e.:  "SIM!", 'DATA', '"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, VBR for 68020+)

                CPU  registers:  The calculator can directly use the contents
                of these registers.  SSP is the supervisor stack pointer, USP
                the  userstack  pointer,  SP  and A7 the actual stack pointer
                (68020+:  SSP is the actual supervisor stack pointer, MSP and
                ISP  the  master and interrupt stack pointers, VBR the vector
                base register).

                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 a source/destination EA, otherwise 0 and the
                corresponding EA register is undefined.  I.e.:  sea*sx

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


A  term normally ends at a space, a colon, a semicolon, 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 it to be.

The  calculator can work in decimal or hexadecimal mode.  In decimal mode you
do  not  have  to  write  the  '#'  in  front  of  a  decimal number, but for
hexadecimal  numbers,  the '$' is neccessary.  In hexadecimal mode you do not
have  to  write the '$' for hexadecimal numbers, 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
or occupy.  The data line 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' character, 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>.  The string length is only limited by the line length.


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  data  line  ends  at  a  space or an illegal char.  Between the komma that
separates  two  datatypes  and  the  next datatype there can be spaces.  also
between digits (only for the edit command, not for 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.  'SIMBug'.  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 register
buffer.   SIM  has  now  the  control  over  the  program.   The length field
indicates  how  far  you have initialised the list from the length field.  If
you do not fill in the entier structure, the rest will be zeroed.

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  registers  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  SIM, the different entrances are located, the backups and
reentry  values  and  the debug server data structure.  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:


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

 STRUCT toolbase       ;+0  The start address of SIM in memory


;--- Display ------

 APTR  plane           ;+0  The start address of the $5000 bytes display ram
                            (must be graphic memory!)

 APTR  backup          ;+4  The start address of the backup of the display.
                            When not zero, SIM will copy what is in the
                            memory of the future display to this address
                            when entered and copy it back when left.


;--- Entrances ----

 JMP   entrance1       ;+8  Entrance for JSR. Here you can simply enter SIM
                            by a 'JSR' to this address.

 JMP   entrance2       ;+12 Entrance for Exec's traphandle. When you want to
                            use SIM as traphandler of your task, write this
                            address to <taskstruct+50>.

 JMP   entrance3       ;+16 Debug server entrance.

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


;--- 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 SIM
 LONG  version         ;+68 Version of SIM as 4 ASCII chars


;--- Backups ------    ;When SIM 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 VBR+$68
 LONG  level3          ;+82 VBR+$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 SIM 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 preferences structure


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

 LONG  0               ;+128 Offset from here 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
 APTR  0               ;+232 Segmentlist
 APTR  0               ;+236 Symbollist with labels

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

 LONG  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 ----------    ;+268 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 addressing mode is not allowed.

        illegal size:

                An  instruction has either no size at all or does not support
                this size.

        illegal operator:

                An operator is not allowed here.

        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 character is not allowed here.

        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:

                The number of brackets opened and closed does not match.

        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.








Disk errors
-----------


        disk error:

                Something  went  wrong with the disk access, 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
                disk access display.

        file not found:

                SIM  could  not  locate the file you want to load or the path
                given was faulty.

        not enough space:

                The file to be saved won't fit on the disk.

        disk full:

                That error should not occur.

        directory error:

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

        illegal path:

                SIM cannot locate the directory you want to list.







Other errors
------------


        too much:

                The  start address given for a command is higher than the end
                address.

        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.






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 due to an event:


        <nothing>       SIM is awaiting commands.

        busy            As  soon  as  SIM  is executing commands this text is
                        printed.  This shows you If SIM is working or not.

        break           When you break the execution of a command SIM replies
                        with this message.

        pause           When you pause.

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

        error           When an error occurs.

        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 the auto unmodify traps feature.

        US/** kmap      When you select the keymap.

        indir x         When  you use indirects the current indirect level is
                        shown.

        returned        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
                        visible monitor part, SIM writes that message to tell
                        you that there is more to see.

        semi/full       Whether or not the full charset is printable.

        symbols/opcode  Symbols  are  available  and used or not (disassembly
                        with symbols or opcode field).

        $xxxx()         Display offset for d16(ax) EAs.

        label()         Display symbol for all d16(ax) EAs.

        >label()        Display  symbol  of d16(ax) EAs of instruction at PC.
                        Use offset for other instructions.

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

        MSP/SR flags    If  the register list shall either display the MSP or
                        the SR flags (68020+ version only).

        found           If the scan for an access address was successful.

        caln/no EA      If  or if not the calculation of EAs is allowed while
                        tracing.




*****************************************************************************
        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,
        profreading my documentations and all the cool e-mail chat
        and much, much more.

      - André Dietisheim, Oliver Ferlin, Stefan Strasser, Kay Temirel,
        Ch. Schneider, F. Buergel and Niel Ericson for bugreports and
        ideas.

      - Michael Hitch for MC68040 testing.

      - And 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     Contacting Me
=====================


If  you  want to register, if you have bugreports, question, ideas, flames 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 between your location and mine and
don't wake me up in the night :).


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




-----------------------------------------------------------------------------
                                                   Stefan Walter, 10.Mar.1993