Otherware/Otherware_1_SB_Development.iso/amiga/os/sim.lha/sim.doc

Text File | 1989-06-21 | 90.7 KB | 2,723 lines

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

        *******      ****         ******        *     *          *******
         * * *      **  **          **          **   **           * * *
          *****     ***             **          *** ***          *****
           * *       ***            **          *******           * *
            ***        ***          **          ** * **          ***
             *      **  **   **     **     **   **   **   **      *
              *      ****    **   ******   **   **   **   **     *


                           System-Independent Monitor
               Copyright ⌐ by Stefan Walter, ALL RIGHTS RESERVED

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



              The User Manual, refering to version 1.51 of S.I.M.
                      Released on the 27th of January 1991




                                 --------------
                                 READ IT OR DIE
                                 --------------






                                    CONTENTS
                                    ========


 1. Introduction
         1.1  Welcome to SIM
         1.2  About this Documentation

 2. Getting aquainted with SIM
         2.1  What is SIM?
         2.2  Qualifications, Requirements and Limitations
         2.3  The SIM Program

 3. Some words about...
         3.1  The Display
         3.2  Breakpoints
         3.3  Trace
         3.4  The Keyboard
         3.5  Disk Access
         3.6  Files
         3.7  Breaking
         3.8  The Actual Address
         3.9  The Matchbuffer
         3.10 Command History
         3.11 Traps
         3.12 Functionkeys
         3.13 SIM and the Hardware

 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 Debuger Window
         4.5  Debugger Window Shortcuts

 5. Additional Information
         5.1  Assembler and Calculator Syntax
         5.2  Line Forms
         5.3  The Debug Server Entrance
         5.4  The SIM Base
         5.5  Errors

 6. Greetings, Thanks, Support and about Future Releases
         6.1  Thanks
         6.2  Greetings
         6.3  Support
         6.4  About Future Releases





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



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


  Congratulations dear user. You have just become owner of the second release
  of 'S.I.M.', the high performance monitor and debugger for the Commodore
  Amiga, probably the best, the mightiest and the only of its kind.

  Version 0.50 of 'S.I.M.' was freeware. This version of 'S.I.M.' is now a
  shareware program. 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 don't respect these three rules I wish you all the bad things you'd
  wish somebody that steals, adds to or misuses something created by yourself
  in hours of hard work. So be fair! Only happy programers are good
  programers.

  If you copied this version from somebody else and you like it and keep using
  it, you should send me (if you did not yet) 20 SFr or 20DM or 15$ (well, 1g
  gold or half a barrel of oil will also be accepted) shareware fee. This has
  for you the advantage that I will send you the final version on another disk
  as soon as it's finished.


  Note: The entire risk of using SIM is to the user himself. In NO event
        will the author be liable for direct or indirect damage or loss
        resulting from the use of this program.



 1.2 About this Documentation
 ============================


  There exist two very good reasons why you must at least have a look at
  this text:

  1. I do not question your qualifications and your knowledge of the Amigas
     hardware. But SIM bases on a new concept that offers an universe of
     possibilities but also demands a lot of the user. There are a lot of
     details that will get important at a certain moment, details you'll never
     find out about on your own. It is in your own interest if you read this
     manual. You will then be able to use 90% of the possibilities this
     program offers (sorry, the only one that knows everything about this
     tool, that's me).

  2. It was fun programming SIM, but it was HELL writing this damn manual.
     Writing it in german would have been hard enough, but writing it in
     a foreign language made it a torture. Good old Woodbird (my former english
     teacher) may forgive me all the bad mistakes I did in this text. So you
     may honour my sacrifice by reading this, since I do not like to do write
     manuals that no one reads.





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



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


  A good question, isn't it? Well, it's not as easy to give a straight answer
  then to ask the question. As you could read in the title, 'S.I.M.' stands
  for (S)ystem (I)ndependent (M)onitor. I presume that nearly every programer
  working on the AMIGA (intromakers excluded) knows what a 'monitor' is (I do
  not mean the device you stare at in this moment!).

  There have been several before, like good old C-Monitor, A-Mon, RomCrack and
  a lot more. During the developement of SIM they served as examples for how to
  do it and how not to do it and how to do it better. I hope that does not
  cause any trouble with copyrights and so on. The result of this compiling
  is an unmatched variety and complexity of commands. This is only a short
  selection of the more spectacular features of SIM:

        - comfortable command editing
        - integrated assembler, disassembler and calculator
        - very powerfull findmechanisms
        - superb breakpoint and trace possibilities
        - parallel printer support
        - freely defineable functionkeys
        - exception control
        - DOS-track and sector read/write operations
        - one-bitplane graphic searcher
        - diskformat
        - file LOAD, SAVE, DELETE and DIR operation
        - copperlist finder and disassembler

  Additionally to the monitor commands, this version disposes of what I call
  'Debugger Window'. People that are used to Monam2 will welcome it because
  it provides a similarly easy and effective way to overview a program.

  So far nothing new. What makes SIM so powerfull is the way it interacts
  with the AMIGAs hardware and system. SIM tries to be as discreete and as
  independent as it is possible.

  On one hand this means that SIM will run under all circumstances. It
  does not need anything, no exec, no DOS, no nothing. This capability leaves
  a wide field of usages. You could use SIM as last hope to salvage data from
  the memory before reset. Or for virus-secure diskoperations since SIM
  does it without DOS.

  On the other hand discreetion means that S.I.M. will do as less changes in
  the software environement (ram, custom registers etc.) as it can. It does
  neither use blitter nor copper. This 'invisibility' of SIM makes it
  possible to monitor and track a programs to unknown depthts. You can debug
  directly into graphic routines, interrupt handlers, diskroutines, task
  and memory handling routines without any difficulties and resulting problems.

  I have made some bonebreaking tests with SIM, but it passed them all.
  There is no absolute protection from SIM, it can only be made very hard
  to keep control of a program with SIM, but if you are clever enough, you
  will allways find a way around the problem.



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


  To use SIM efficiently, detailed knowledge of the AMIGAs hardware,
  the 68000 processor and assembler language is ABSOLUTELY neccessary.
  SIM is designed to be used by professionals.

  SIM will work on practically every normal machine, as long as its
  processor is a Motorola 68ooo/7.14 MHz. Other processors (68010/20/30/...)
  are not supported yet, I am sorry about that. These processors are much more
  comlicated in their assembler language and exception handling and I do not
  have one of them.

  Different memory configurations and Big/Fat Agnus do not bother SIM.
  Theoretically you'd not even need a kickstart ROM/WOM to run SIM.

  I recommend a fastmem memory expansion of at least half a megabyte at $200000
  or $c00000. This gets usefull when you want to debug a program that uses the
  entier chip ram. You can then put SIM in fastram which you have disabled
  with one of those resetting nofastmems.



 2.3 The SIM Program
 ===================


  SIM is not a conventional program (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.

  When you work with SIM you must change your way of thinking. The Amiga has
  multitasking. Most debuggers are 'taskoriented'. This means that they debug a
  certain task, and only that one. If another task crashes, they do not notice
  this. SIM is a monotasking debugger. In the eyes of SIM there is only one
  program running on your machine. This one program may splitt up into several
  seperated programs that are 'switched' (the tasks), but it is still one whole
  program. This concept enables you to debug different tasks at a time, and
  even newly generated ones i.e. by createproc().





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



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


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

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

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

  SIM does not have an memory manager that 'ghosts' the display. This means
  that when you have a display at $70000 and a backup at $c50000 and you want
  to change or view memory or find something at $71000, you either transfere
  the display to another location in the chipmem or you have to look or edit
  in the backup (at $c51000 in our example).

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

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



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


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

        - ILLEGAL breakpoints
        - JSR breakpoints
        - STACK breakpoints

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

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

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

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


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

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

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

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


    - condition term:

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

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


    - counter breakpoint:

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

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


    - button breakpoint:

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

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


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

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

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

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

    - do a tracestep to execute the instruction.

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

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


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

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

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

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

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

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

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


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


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

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

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

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

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



 3.3 Trace
 =========


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


    - condition term:

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

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


    - counter trace:

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

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


    - button trace:

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

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


    - trace breakpoint:

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

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


    - 68020 emulation:

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

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


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

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

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

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



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


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

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

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

  - release all other keys

  - type 'return'

  - release the keys you pressed for that operation

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

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



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


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

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

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

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

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



 3.6 Files
 =========


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

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

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



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


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

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

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

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



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


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



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


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


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

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

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

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

  This feature enables you to search for counters or changes.

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

  An example: you are searching for the livecounter in a game. You have five
  lives:

  1. define matchbuffer, i.e. 'k c00000 c10000'
  2. search for 5, i.e. 'f 0 20000 !n 05'
  3. exit and die once
  4. search for 4, i.e. 'f 0 20000 !m 04'
     If you are lucky, one address stays in the matchbuffer
  5. list addresse(s) in matchbuffer, i.e. 'k 0'
  6. if neccessary go to step 3 and search for one live less



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


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



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


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

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

  Additionally you can force SIM to set traps again if they are modified by
  toggeling 'Auto Unmodify Traps' on.



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


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

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

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



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


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

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


  - DMACON
  - INTENA
  - INTREQ *)

  - Level 2 interrupt
  - Level 3 interrupt

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

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

  - CIA-B: DDRA

  - CIA-A: SR write buffer

  - VPOS **)


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


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

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

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


  As I 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 it puts back when
  exiting. Those registers are:


  - DIWSTRT
  - DIWSTOP
  - DDFSTRT
  - DDFSTOP
  - BPLCON0
  - BPLCON1
  - BPLMOD1
  - COLOR00
  - COLOR01


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

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


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


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





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



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


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

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

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

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

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



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


  On the worktable, several basic features are provided:

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

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

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

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

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

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

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

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

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

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

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

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

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

   - <SHIFT+HELP> prints the second helppage.

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

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

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

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

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

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


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


 4.3 The Commands and Their Syntax
 =================================

  As mentioned earlier, SIM understands a vast number of commands.
  While working in SIM, you can get a little overview of them in the two
  helppages:

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

  and

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

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

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

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

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


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

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

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

     command (startaddress) (endaddress)

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

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

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

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

   Do not try to dump the customregisters area.

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


   EXAMPLES:

    m 0 100
    a 100
    d
    l 51236 !+60


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

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

   You can modify the memory with these two commands.
   The edit command can write data at a location in the memory (see chapter
   'line forms' for details)

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

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

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

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


   EXAMPLES:

    e 70000
    e>00070000: 0121
    n 100 nop


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

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

   Transfer:

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

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


   Occpuy:

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

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


   EXAMPLES:

   t 0 10000 c00000
   o 12564 !+60 nnop


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

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

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

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

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

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

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


   Find data:

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

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

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

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

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

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

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


   Find disassembly:

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

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

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

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

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

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

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

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

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

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

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


   Compare:

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

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

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

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

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

   - c : Continues to compare after last address reported.


   Matchbuffer:

   You can read out or define the matchbuffer:

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

   - k * : Clears matchbuffer.

   - k ? : Shows you where the matchbuffer is.

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

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

   - k : Lists or shows next entrie(s)


   EXAMPLES:

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


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

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

   Registers:

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

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


   Trapsetting:

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

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

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


   Trapcreating:

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

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

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

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

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

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

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

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


   EXAMPLES:

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


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

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

   Breakpoints:

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

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

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

   - b [s] : Sets a simple breakpoint

   - b : Lists all breakpoints

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

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

   - bk : Kills all breakpoints

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


   Trace:

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

   - z [j] : Does trace until:

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

   - z : Does one tracestep


   Nextstep:

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

   - u : Do one nextstep


   Leave Out:

   This simply leaves instructions away:

   - i [n] : Leaves out n instructions

   - i : Leaves out one instruction


   EXAMPLES:

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


   Flow
   ----

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

   Exit:

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

   - x : Exits, but asks for confirmation first

   - X : Exits directly


   Quit:

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

   - q : Quits, but asks for confirmation first

   - Q : Quits directly


   Gosub:

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

   - g [s]  : goes to subroutine at s

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

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

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


   History:

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

   - h [n] : Print nth last history

   - h : Print all five histories

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


   EXAMPLES:

   h 3
   X
   q
   g 100
   gw 200


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

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


   Set Drive:

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

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

   - D : Shows actual drive

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

   - D? : finds position of head of actual drive

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


   Read Track:

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

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

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

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


   Write Track:

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

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

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


   Read Sector:

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

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

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


   Write Sector:

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

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

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

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


   Format Disk:

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

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

   - >f : Formats disk in actual drive

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

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


   EXAMPLES:

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


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

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


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


   Load File:

   This command loads a file directly into memory:

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

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


   Save file:

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

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

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

   List Directory:

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

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

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

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


   EXAMPLES:

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


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

   ? [n]{,}(n) : Calculate
   F (n)(c){@} : Define functionkeys
   P (s)(m)    : Start graphic searcher
   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


   Calculator:

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

   - ? [n] : calculate result of n

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


   Functionkeys:

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

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

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

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


   Graphic Searcher:

   The 'p' command starts the graphic searcher:

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

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

   Cursor up:         Scrolls plane one line down

   Cursor down:       Scrolls plane one line up

   Cursor left:       Scrolls plane one line right

   Cursor right:      Scrolls plane one line left

   Shift+Cursor up:   Scrolls plane one screen down

   Shift+Cursor down: Scrolls plane one screen up

   Help:              Modulo=modulo+2

   Del:               Modulo=modulo-2

   Shift+Help:        Modulo=modulo+16

   Shift+Del:         Modulo=modulo-16

   Backspace:         Modulo=0

   Return:            Switches between hires and lores

   Control:           Ends graphic searcher

   The graphic searcher should recognize additional chipmem at $80000


   SIM Addresses:

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

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

   The 's command will mostly be used to transfere the display at another
   location when you want to look at the memory where the display is.

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


   Copperlist:

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

   - l*        : Shows the active copperlist

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

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

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

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

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

   When you search quickly, the copperlist you are looking for will be
   activated. If this one is not the running one, search again for the other to
   set the other copperlist again.


   EXAMPLES:

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


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

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


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


  Startaddress:

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

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


  Linkterm:

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

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

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

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


  EXAMPLES:

  A a0+56
  T a0+d0
  T pc @



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


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

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

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



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


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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

  <a>            Selects asciidump for the active view.

  <m>            Selects hexdump for the active view.

  <l>            Selects copperdump for the active view.

  <m>            Selects disassembly for the active view.


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

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

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

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


  Flow
  ----

  <z>            Does a tracestep.

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

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

  <x>            Exits SIM.

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

  <g>            Leaves a subroutine. Therefore SIM puts a STACK-breakpoint at
                 the actual stackpointer and exits. Do not use this when the
                 subroutine has allready put more data on the stack.

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


  Edit
  ----

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

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

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


  Indirects
  ---------

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

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

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

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


  Find
  ----

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

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


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

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

  <h>            Makes a hardcopy of the actual display by printing it as
                 text.

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

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

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

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

  <F1-F10>       Toggles availability of funktionkeys.

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

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


  Most of these shortcuts are only functioning when the debugger window is
  activated. Only  <h>,<p>,<!>,<?>,<F1-F10>,<k>,<z>,<u>,<i>,<q> and <x>
  are allways functioning.





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



 Assembler and Calculator Syntax
 ===============================


  The assembler used in SIM is entierly home-made and is fully
  motorola compatible. Anyway, some special features have been added
  to increase userfriendlyness:

  - You can use 'add' instead of 'addi', 'adda' and 'addx -(ax),-(ay)'
    This is also valuable for 'sub'.

  - 'cmpm', 'cmpi' and 'cmpa' can be replaced by 'cmp'

  - You can use 'eor' instead of 'eori'. This also works with 'and' and 'or'

  - Bcc xxxx, DBcc Dx,xxxx, xxxx(PC) and xx(PC,Rx) use absoulute addresses.
    This means that when you want to have a code like

            60010: bra $60000

   you can enter 'bra $60000'. If you want to give the offset directly,
   you have to put a '+' or a '-' in front of it:

            60010: bra -$12

    But remember: The Offset has allways to be:

            (targetaddress-instructionaddress+2)

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

  - If no size given, direct addresses are word if possible.

  - DC.W or DC.L can be used, but only one value is allowed.

  - If you do not give an instruction size, the default size is
    taken, which in most cases is WORD.

  - The interpreter is very tollerant, even a line like

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

    will be accepted and assembled correctly.



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



  The calculator used in SIM is also entierly home-made. It disposes
  of several very useful operations and value forms. The calculator is used
  when you have to enter a number. Just have an overview of the operations
  supported, sorted by their priority:

   -   - Prefix change: Changes a positive value to a negative and vice
         versa.

   ~   - Logical NOT: Changes the state of all 32 bits of the value.
         For example: ~5 is -6.

   .s  - Size a value: Any value will be extended to LONG from the size you
         define. For example: $89.b will then be made to $ffffff89.

         The size given is also important for the assembler when using direct
         long or short address.

   []  - A value in these brackets will be used as an address and the
         content of the memory at that address will be taken.

         A size directly after the closing bracket will define if
         the value will be taken as a BYTE, WORD or LONG and extended
         to LONG. For example: [4].l gets the execbase ($676 or $c00276)
         [$dff002].w reads out the actual DMACON as a WORD.

   *,/ - Multiply or divide long, considering if the values are positiv
         or negativ. For example: -$56*5 is fffffe52.

   \   - Gets the modulo of a long division. For example: 11\4 is 3.

   +,- - Addition or Subtraction, allways long.

   <<  - Shift value left: this corresponds to a multiplication with 2
         to the nth power, whereas n is the numer of bits to be shifted.
         For example: $20<<8 is $2000.

   >>  - Shift value right: this corresponds to a division by 2
         to the nth power, whereas n is the numer of bits to be shifted.
         For example: $2000>>8 is $20.

   &   - Logical AND.

   !   - Logical Exlusive OR

   |   - Logical OR

   <>  - Not equal: If the two values are not equal, this returns true
         (=$ffffffff), otherwise false (=0).

   =   - Equal: If two vales are equal, this returns true.

   <=  - Less or equal: Returns true, if the first value is less than
         the other or at least equal.

   =>  - Higher or equal: Returns true, if the first value is higher than
         the other or at least equal.

   >   - Higher: Returns true, if the first value is higher than the other.

   <   - Less: Returns true, if the first value is less than the other.


   As for the forms of values, SIM understands these:


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

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

   %x  - Binary number: A number in binary form
                        consisting of max. 32 digits 0 and 1.

   "/' - ASCII chars: A number consisting of max. 4 ASCII chars.
         f.e.: "SIM!" or '!MIS'

   !   - Stands for the last result. This enables you to do things
         like: m 61f35 !+39dc = "Show memory from $61f35 to $61f35
         plus 39dc".

   @   - Stands for the actual address. This is the address, SIM uses as
         standart workaddress for dump commands.

   SIM - The program and base address of SIM

   D0-D7,A0-A7,PC,SP,SSP,USP,SR,CCR and M0-M7 - The registers. The calculator
         can directly use the content of these registers. SSP is the supervisor
         stack pointer, USP the userstack pointer SP and A7 the actual stack
         pointer. I.E. when you are tracing a program, and you want to know,
         what is at the address  56(a0,d7.w), you can use 'm 56+a0+d7.w'.


  The end of a term is usualy set by a space, a komma, a semikolon, a
  doubble point or a <CR>. Actually, when 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.

  Not to forget: some 120 brackets are allowed, more than you will ever use.

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

  Hexadecimal mode is usually used to get addresses (s,e,t,b,p)
  or hexnumbers (x). For all other cases decimal mode is used, also for
  assembler.



 5.2 Line Forms
 ==============


  There are two types of lines you have to differe: the command line
  and the data line.

  - The command line is the one that contains the different commands
    you want to execute. This line has usualy that form:

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

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


  - The data line is of another kind. Whenever you have to enter datas
    directly, for edit, find, occupy etc., you enter a data line. This
    dataline can consist of this four elements, allways seperated by a komma:

   - Hexnumbers: Are introduced with or without '$'. They can be as long as
     you want. The hexnumber is ended by a char that is no number and
     not 'A','B','C','D','E' or 'F' (lower case letters also included)
     If you enter an odd number of digits, the last digit will be taken as
     byte, its higher nibble zeroed. Spaces are allowed between digits.

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

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

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


     Now an example, using all the elements from above. You enter:

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

     And the result are these 14 bytes:

       45  42 44 48  4e f9 00 06 00 00  11 11        66 66
       |-  |-------  |----------------  |----        |----
       |   |         |                  |            |
       45  "BDH"     jmp $60000         [$fc0000].w  6666


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



 5.3 The Debug Server Entrance
 =============================


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

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

  Now, when you are in SIM and want to give control back to the debug
  server, you can use the 'q' command (or 'Q' or AMIGA-q). SIM does then
  copy the workregisters back into the base area and takes the reentry PC, SR
  USP and SSP 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.4 The SIM Base
 ================


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


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

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

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


;--- Display ------

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


;--- Entrances ----

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

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


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

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


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

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


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

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

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

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

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

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

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

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

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

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

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

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

 long  0               ;+136 Register d0
 long  0               ;+140 Register d1
 long  0               ;+144 Register d2
 long  0               ;+148 Register d3
 long  0               ;+152 Register d4
 long  0               ;+156 Register d5
 long  0               ;+160 Register d6
 long  0               ;+164 Register d7
 long  0               ;+168 Register a0
 long  0               ;+172 Register a1
 long  0               ;+176 Register a2
 long  0               ;+180 Register a3
 long  0               ;+184 Register a4
 long  0               ;+188 Register a5
 long  0               ;+192 Register a6
 long  0               ;+196 User stack pointer
 long  0               ;+200 Supervisor stack pointer
 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
 long  0               ;+222 Reentry sr of server

;--- Extension ----

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

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

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



 5.5 Errors
 ==========


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


 Assembler errors:

   illegal instruction:
     The assembler does not know this instruction.

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

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

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

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

   line malformed:
     Something is undefinably wrong.

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

   illegal sea:
     An illegal effective address as source.

   illegal tea:
     An illegal effective address as destination.

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

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

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


 Calculator errors:

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

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

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

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

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


 SIM errors:

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

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


 Diskaccess errors:

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

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

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

  disk full:
    That error should not occure.

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

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





*******************************************************************************
 6. Greetings, Thanks, Support and about Future Releases
*******************************************************************************



 6.1 Thanks
 ==========


  Big thanks must go to my friend Daniel Weber for continuous testing of all
  new features I inserted, some good and some bad ideas and severe criticism
  of all the work I did.

  Thanks must also go to all the other people who reported me their ideas
  and gave bugreports:  Christian Schneider, AndrΘ Dietisheim, Oliver Fehrlin,
  Stefan Strasser.

  Also to Yello, Depeche Mode, Kitaro, Star Inc., Mike Oldfield, Guru Josh,
  Enigma, New Order, Vangelis, J.M. Jarre, Harold Faltermeyer, Art of Noise,
  Alan Parson Project, Die Toten Hosen and Megatron for cool background music.



 6.2 Greetings
 =============


  Greetings go to all members of my crew, to my few contacts, to the makers of
  Amiga Action Replay (especially Lord Olaf), to SCA (for the RomCrack),
  to Graftgold for converting Rainbow Islands and to all Beerbrewers (for
  beeing).



 6.3 Support
 ===========


  The following is a short list of products supporting SIM.

        - FlyMon (assembler monitor)

        - NOG2   (trap- and exceptionhandler)

        - ProAsm (integrated editor/assembler/debugger)

        - SIMBUG (SIM loader)

  You are welcome to contact me if you want detailed information about how to
  support SIM correctly in your own programs. If you code a program that will
  support SIM, you are also welcome to tell me so, not only because the list
  would become longer, but also because the tools that may dispose of SIM
  support are surely of a kind I like and will use.



 6.4 About Future Releases
 =========================


  Version 1.51 is definitely not the ultimate release of SIM, there is a lot
  of room for improvements and new features. My intention is to make a version
  2.00, a realy final one that will be PERFECT. Unfortunately, I will not have
  much time for that until July 1991, it may take quite some time for it to be
  released. The People who send me the money for this version, and only those,
  will get it as soon as its finished.

  If you have questions, bugreports, ideas for new features or complaints or
  if you simply want to contact me, write to:

                               Stefan Walter
                            Finsterruetistr. 57
                               8135 Langnau
                                SWITZERLAND

  Or dial Switzerland/01/713 01 46, from 18.oo to 20.oo.


                                               Enjoy!

                                                 Stefan Walter      27.Jan.1991