APDL Public Domain 1/APDL_PD1A.iso/utilities/arctools/!ARCTOOLS/Manual

Text File | 1992-10-28 | 146.5 KB | 4,054 lines

   AAAAAAAA  RRRRRRR  CCCCCCC TTTTTTTTTT  OOOOOO    OOOOOO  LL      SSSSS
   AA    AA  R     R  CC   CC T   TT   T OO    OO  OO    OO LL     SS   S
   AAAAAAAA  RRRRRRR  CC          TT     OO    OO  OO    OO LL     SS
   AA    AA  R  RR    CC          TT     OO    OO  OO    OO LL      SSSS
   AA    AA  R  RR    CC          TT     OO    OO  OO    OO LL         SS
   AA    AA  R   RR   CC   CC     TT     OO    OO  OO    OO LL     S   SS
   AA    AA  R    RR  CCCCCCC    TTTT     OOOOOO    OOOOOO  LLLLLL SSSSS




                              Version  0.72


                Written by:  Mohsen Alshayef  27 Oct 1992

                  Copyright (C)  Mohsen Alshayef 1992




            *************************************************
            *   This version of ARCTOOLS is Public Domain   *
            *************************************************




 ARCTOOLS is a complex program which is under continuous development and,
 while every effort is made to ensure it functions as detailed in this
 manual, I cannot accept any liability for any loss or damage resulting
 from the use of ARCTOOLS or the information in this manual.



                *****************************************
                *   For further information contact:    *
                *                                       *
                *     Mohsen Alshayef,                  *
                *     PO BOX 50217,                     *
                *     AL-Hidd,                          *
                *     Bahrain,                          *
                *****************************************




Manual contents
===============
  Introduction:
      Important Notice
      System Requirements
      Starting ARCTOOLS

  The *Commands:
      Commands summary
      Disc and file commands
      Memory commands
      General commands

  The memory editors

  The disc editors:
      Using the disc editors with non-standard discs.
      Recovering deleted files using the disc editors.

  The Commands Menu

  Keys used in the editors:
      Keys summary
      Keys discription

  The dis-assembler

  The single-line assembler

  Calling the assembler from BASIC

  Using the dis-assembler to recover lost ARM code source files

  ARM 3 instructions assembly and disassembly


                     *****************************
                     *       Introduction        *
                     *****************************

ARCTOOLS is a utility module which adds many *Commands that most of you
will find very valuable.Some are seldom used, but they are there when you
need them. ARCTOOLS tries to add commands that are valuable to users
(beginners and experienced) as well as facilities that many advanced
ARM code programmers need.

ARCTOOLS differs from other utility modules in that most of its commands
are accessible from within the various memory and disc editors. An area
of memory or disc can be marked and then various operations can be
performed on it using a simple and efficient menu system.
ARCTOOLS also provides many facilities built into its editors with the
promise of more in future vesrions.

ARCTOOLS is not a multi-tasking application. Speed and ease of use is
what all matters to real users of ARCTOOLS. Fast scrolling colourful
text in the mnemonic or dis-assembler with automatic search for defined
labels every time an instruction is decoded out of memory has to be
done with no delays. This, however, does not mean that I am not thinking
of a Desktop version. ARCTOOLS has a built in 'Commands' menu, accessible
from any disc or memory editor. With few simple key strokes you can achieve
what takes ages with the mouse. Experienced users always use keyboard
shortcuts in any application.

The number of *Commands provided will be extended in the future.
Please feel free to contact me on the address given above if you need a
customized version with say certain *Commands added or others removed or
you want different keys to be used in the different editors.
Also, if you have any suggestions, comments, bugs discovered etc., I will
be pleased to here from you.
If you have a utility that YOU have written or an idea of a utility, please
contact me, I'll be happy to add your code to your customized ARCTOOLS.

ARCTOOLS is in a continuous development. New versions are coming up in every
two to three weeks, so please send suggestions and comments.

                      ****************************
                      *    Important Notice      *
                      ****************************

It is the user's responsibility to ensure that ARCTOOLS is used lawfully
and you are not permitted to use it in violation of Copyright Law.

You may NOT change ARCTOOLS utility or use ANY part of it in other products
without my approval. You may spread it freely with ALL files included,
but not for any profit. This software is provided 'as is'. Using it is
entirely at your own risk.

You are not allowed to distribute ARCTOOLS as an 'extra' in any commercial
product.
This version of ARCTOOLS is public domain. Future versions will remain
public domain until I decide otherwise.
If you are interested in ARCTOOLS as a commercial product, you are kindly
invited to contact me to discuss financial details.

                       *************************
                       *  System Requirements  *
                       *************************

ARCTOOLS has been assembled using the BBC BASIC assembler and the ARM
BASIC EDITOR on an A5000 with 4 M bytes of memory and 120 M bytes Hard
Disc under RISC OS 3.10.

ARCTOOLS requires RISC OS 3 or higher to run. You may find that some
of ARCTOOLS commands will work on RISC OS 2 systems, but the memory
and disc editors will not. ARCTOOLS uses some of the new RISC OS 3
SWIs.




                        ***********************
                        *  Starting ARCTOOLS  *
                        ***********************

ARCTOOLS can be loaded into your system (as a module):

 1. From the Desktop: Click twice on the ARCTOOLS icon.
 2. From the line command: type  *ARCTOOLS

ARCTOOLS will take 63 K bytes from the RMA for its code and 39 K bytes
for its workspace. Additionally it will claim 32 Kbytes for the labels
buffers.

Future versions of ARCTOOLS will allow the user to specify the size of
the different ARCTOOLS buffers.




                           ARCTOOLS *Commands
                           ==================

Using the *Commands:
====================

ARCTOOLS provides three categories of *command:
- Disc and file commands.
- Memory commands.
- General commands.

To issue *Commands from wihin the desktop: press F12 and then type the
required command.

To enter any of the disc or memory editors from within the desktop you
should use the command line by pressing F12. Do not use the task window.
The memory and disc editors use direct screen access and will mess up the
desktop windows if entered from the task window.


*Commands summary:
==================

 1: *BList <filename> [<line number>][,[<line number>]] [<LISTO number>]
 2: *Clear <start> <end>|+<length>
 3: *Dedit <drive> [<address>] [<format>]
 4: *Dget <drive> <disc addrs> <end>|+<length> <memory addrs>
 5: *DLock [<ON|OFF>]
 6: *DMap [<drive>]
 7: *Dput <drive> <memory addrs> <end>|+<length> <disc addrs>
 8: *Event [<event number> <ON|OFF>]
 9: *Fcompare <1st file> <2nd file> [<max diff>]
10: *Fcount <filename> <string> [C]
11: *Fdump <filename> <format> [<offset>]
12: *Files
13: *FillH <start> <end>|+<length> <Hex list>
14: *FillT <start> <end>|+<length> <string>
15: *FillW <start> <end>|+<length> <words list>
16: *FindB <start> <binary number> [Q|N|E|F]
17: *FindC <start> <word|%binary|mnemonic string>
18: *FindH <start> <Hex list> [Q|N|E|F]
19: *FindM <start> <Mnemonic string> [Q|N|E|F]
20: *FindN <start> <32-bit number> [Q|N|E|F]
21: *FindT <start> <string> [[C] [Q|N|E|F]]
22: *FindW <start> <word> [Q|N|E|F]
23: *Fjoin <1st file> <2nd file> [<target file>]
24: *FMcompare <filename> <addrs> [<max diff>]
25: *Freplace <srs filename> <srs string> <trgt filename> <trgt string> [C]
26: *Heap [<address>]
27: *Index
28: *Labels
29: *LoadLabels <filename>
30: *Mcommands [<relocatable module name>]
31: *Mcompare <start> <end>|+<length> <with> [<max diff>]
32: *Mdump <f/rmat> <start> [<end>|+<length> [<offset>]]
33: *Medit [[<address>] [<format>]] | [<label>]
34: *Mmap
35: *Move <start> <end>|+<length> <to>
36: *MPage [<page number>]
37: *Reverse <start> <end>|+<length>
38: *SaveArc <filename>
39: *SaveLabels <filename>
40: *Slow [<value>]
41: *Swap <start> <end>|+<length> <with>
42: *SwiC [<SWI chunck>]
43: *SwiM <relocatable module name>
44: *SwiN <SWI name>
45: *SwiS <SWI number>
46: *System
47: *Timing <start> [<end>|+<length> [<offset>]]
48: *Tools [G|D|M]
49: *Vector [<vector number>]
50: *Where <address>


              *****************************************
              *       Disc and file commands          *
              *****************************************


 General Notes:

  -   Where <drive number> is given, this identifies the drive number
      as 0 to 7 or A to H, not a disc name.
  -   <format> means the editor format (B,H,W,T,M,N or Y) not the disc
      format.
  -   The *Dput and *Dget commands allow unrestricted length of data
      to be specified, they are not limited to a sector aligned lengths
      or addresses.
  -   All disc and memory addresses are assumed to be hexadecimal values
      unless the address is proceeded with base number.
  -   It is best to use the commands menu built into the memory and disc
      editors to perform the equivalent *Dget and *Dput operations. This
      makes it easier and safer because you can see where data is copied
      from or copied to.

  WARNING: You should know what you are doing when using any of the
           disc commands.

    =======================================================================
 1: *Dedit <drive number> [<address>] [<format>]
    =======================================================================

    Enters any one of the 7 disc editors at the given address.
    If no address or format is given then the last visited address
    will be seeked and the last remembered disc editor is entered.
    The drive number must be given. This must be a drive number, not
    a disc name.
    The disc editors can edit any disc recognized by the Operating
    System including all ADFS formats, RAM disc, DOS and ATARI discs.
    As well as custom known disc formats. See the section on the
    Disc Editor.

    Parameters:
    ===========

    <Drive number>    can be any of the values 0 to 7 or A to H.

    <address>         optional disc address.

    <format>          optional editor format.


    Examples:
    =========

             *Dedit  0  0  T      Enter the disc Text editor at
                                  address 0 reading from drive 0.

             *Dedit  4  H         Enter the disc Hex editor at the
                                  last visited disc address on drive
                                  number 4 (Hard Disc 1).

    Possible errors: Bad drive
    ================ Bad number
                     Unknown ARCTOOLS editor

    Related commands: *Dput, *Dget.
    =================



    =======================================================================
 2: *Dget <drive number> <disc adrs> <end>|+<length> <memory adrs>
    =======================================================================

    Purpose: Copy a block of data from disc to memory.
    ========

    *DGET CAN GET DATA FROM ANY ADDRESS AND OF ANY LENGTH.

    Note: The memory area that the disc data will be copied to must
          lie in logical Ram.

    Parameters:
    ===========

    <drive>             :drive number 0-7 or A-H
    <disc adrs>         :start address of data on disc
    <end>|+<length>     :marker of data on disc. This can be given
                         as the end address or the length of data.
    <memory adrs>       :start address of memory to copy data to.

    Examples:
    =========

    *Dget 0 0 [phone]        Copy 1024 bytes starting at disc address
                                0 to memory starting at 60000

    *Dget 0 1A +10 60005        Copy 10 bytes starting at disc address
                                1A to memory starting at 60005.
                                This actually copies the disc name to RAM!

    Possible error: Bad drive
    =============== Bad memory
                    Non writable memory

    Related commands: *Dput, *Dedit.
    ================

    =======================================================================
 3: *Dlock [<ON|OFF>]
    =======================================================================

    Purpose: To software write-protect ALL drives.
    ========

    Examples:
    =========
    *Dlock         Reports the status of the Dlock command, This
                   will show either:
                   'All drives are write-enabled', or
                   'All drives are write-protected'.

    *Dlock ON      Write protects all drives.

    *Dlock OFF     Removes the *Dlock protection.

    When Dlock is ON, an attempt to write to a drive will produce the
    error message: 'Protected drive'


    Possible errors: Bad parameter
    ================

    Related commands:  None.
    =================


    =======================================================================
 4: *Dmap [<drive>]
    =======================================================================

    Purpose: Display the free disc space map.
    ======== This command provides a neat way of display the free
             space map on disc by intercepting the OS *MAP command.

    This command shows the map number, its start address and its size
    together with the total free space map on the specified disc.

    Example:  *Dmap 4     Displays the free space map on the Hard disc.
    =======

    Possible errors: Bad drive
    ================

    Related commands: None.
    ================

    =======================================================================
 5: *Dput <drive> <memory adrs> <end>|+<length> <disc adrs>
    =======================================================================

    Purpose: Copy data from memory to disc directly.
    ========

    *DPUT CAN COPY DATA TO ANY ADDRESS AND ANY LENGTH OF DISC.

    The memory block must lie in a logical Ram area.

    Parameters:
    ===========

    <drive>             :drive number 0-7 or A-H
    <memory adrs>       :start adrs of data in memory
    <end>|+<length>     :marker of memory data. This can be given
                         as an end address or data length.
    <disc adrs>         :start address on disc to copy data to.

    Examples:
    =========

    *Dput 0 8F00 900 2800       Copies 256 bytes from memory address
                                8F00 to disc starting at address 2800.

    *Dput 0 60000 +10 1A        Copies 10 bytes starting at memory
                                address 60000 to disc starting at
                                address 1A

    Possible Errors: Bad drive
    ================ Bad memory

    Related commands: *Dget, *Dedit.
    =================


    =======================================================================
 6: *Fcompare <first file> <second file> [<max difference>]
    =======================================================================

    Purpose: Perform byte comparison of two files.
    ========

    This command compares two files byte for byte.
    If the <max difference> is ommited, the comparison will stop
    after 10 differences.
    To display all difference: give a max difference value of 0.
    Any difference will be shown as:

    Different at <address>: 1st file = <Byte> / 2nd file = <Byte>

    The 'different at address' is the offset within the files.

    If the two files compare okay, then the message "Comparion OK"
    will be shown.

    MOTE: This command performs a byte for byte comparison. It does
          not check to see if the two files have identical lengths.
          The comparison stops when either file end is reached.

    Examples:
    =========

    *Fcompare Document  Manual 0    Lists all differences between
                                       the two files.

    *Fcompare File1 File2   5       Compare 'File1' with 'File2', stopping
                                    after 5 differences.


    Possible errors: File not found.
    ================

    Related commands:  *FMcompare, *Mcompare.
    =================

    =======================================================================
 7: *Fcount <filename> <string> [C]
    =======================================================================

    Purpose: Counts the number of occurences of a string in the given
    ======== filename.
             String containing a number of spaces must be enclosed in
             quotes.
             The number of occurences is echoed on the screen dynamically.

    Parameters:
    ===========

    <filename>       The name of file to search in.
    <string>         The string to count.
    [C]              Optional switch which when included allows the
                     counting of strings to be case insensitive.

    Examples:
    =========

    *Fcount TextFile  "The"        Counts the number of occurences of the
                                   string 'The' in the file 'TextFile'

    *Fcount MyFile |M              Counts the number of occurences of the
                                   string |M (i.e. character ASCII code 13)
                                   in the file 'MyFile'

    *Fcount Prog ". This is" C     Counts the number of occurrences of the
                                   string '. This is' in the file 'Prog'.
                                   The search is case insensitive.

    The message 'No match found' will be reported if command can not find
    the requested string.

    Related errors: Bad parameter
    ===============

    Related commands: *Freplace
    =================


    =======================================================================
 8: *Fdump <filename> <format> [<offset>]
    =======================================================================

    Purpose: Dump a file to screen using any of the 7 dump formats.
    ========

    This command allows a file stored on disc to be dummped into the
    screen, or printer if VDU 2 or CTRL+B has been issued.
    Using the optional <offset> address you can dump a file as though
    it was stored in a particular address. In the Mnemonics dump
    format, any reference to offset addresses in instructions will
    be taken care of.

    Parameters:
    ===========

    <filename>             A valid filename.
    <format>               Editor format: B, H, M, N, T, W or Y.
    <offset>               Optional offset address to be used in place
                           of the zero offset address.

    Examples:
    =========

    *Fdump myfile M 3800000   Dump 'myfile' using the dis-assembler
                              showing addresses as though the file was
                              in the system ROM address space.

    *Fdump Doc T              Dump the file 'Doc' using the Text dump
                              format.


    Possible errors: Unknown ARCTOOLS editor
    ================ Bad number

    Related commands: *Mdump
    =================

    =======================================================================
 9: *Files
    =======================================================================

    Purpose: List details of all currently open files.
    ========

    The command takes no parameters and prints out the following
    information on each currently open file:

    1. The handle number. The OS assigns a handle number for each
       file at time of opening which programs use to access the
       data in the file or to write data to the file.
    2. The read/write status. The read/read status indicates the type
       of access method used when the file was opened as follows:
       a) Read Only :  OPENIN used.
       b) Read/Write:  OPENOUT or OPENUP used.
    3. The file extent. This is the size of the file.
    4. The current pointer position in the file. The pointer position
       is controlled by the OS or by the user and is used as a mark
       to indicate where the data is read from or written to in the
       file.

    If there are no open files. The message 'No open files' is displayed.


    Possible errors: None.
    ===============

    Related commands: None.
    ================

    =======================================================================
10: *Fjoin <first file> <second file> [<target file>]
    =======================================================================

    Purspoe: To join two files.
    ========

    This command may be used to append one file to another, or
    make a new file out of two different files by appending
    them two each other.
    Note: Different filenames should be given to the three files.

    Parameters:
    ===========

    <first file>            Name of the first file.
    <second file>           Name of the second file.
    <target file>           Optional target file.


    Examples:
    =========

    *Fjoin Doc1 Doc2  New     Makes a new file called 'New' out of
                              the two files; 'Doc1' and 'Doc2'.
                              The new file will be stamped with the
                              file type 'Data'.

    *Fjoin File1 File2        Appends File2 to File1. In this case File1
                              will have File2 added to it. File1 will
                              maintain its old File Type.


    Possible errors: File open
    ================

    Related commands: None.
    =================


    =======================================================================
11: *FMcompare <filename> <address> [<max difference>]
    =======================================================================

    Purpose: Compares the content of a file with that of the given
    ======== memory area.

    This command compares a file with the content of memory.
    If the <max difference> is ommited, the comparison will stop
    after 10 differences.
    To display all difference: give a max difference value of 0.
    Any difference will be shown as:

    Different at <address>: file = <Byte> / memory = <Byte>

    The 'different at address' is the offset within the file, not
    the memory address, and always starts at zero. Bytes values
    are shown in hexadecimal.

    Parameters:
    ===========

    <filename>                 Valid filename.
    <address>                  Start of memory to compare with.
    <maximum difference>       Optional max difference allowed.

    Examples:
    =========

    *FMcompare MyProg  8f00      Compares the content of the file
                                 'MyProg' with the content of memory
                                 starting at address &8F00.

    *FMcompare Text 8F00 0       Compare the content of file 'Text'
                                 with memory starting at &8F00, listing
                                 all differences.


    Possible errors: Bad number
    ================ Bad memory
                     None logical ram address


    Related commands: *Fcompare, *Mcompare.
    =================

    =======================================================================
12: *Freplace <srs filename> <srs string> <trgt filename> <trgt string> [C]
    =======================================================================

    Purpose: To replace or delete a string in a file.
    ========

    This command replaces the given <srs string> with the given
    <trgt string>. Any reference to the <srs string> in the <srs filename>
    is replaced by the <trgt string> and placed in the new file
    <trgt filename>.
    If the <srs string> is to be deleted, then the use '-d' for the
    <trgt string>.
    When the 'C' switch is included, the search for the string becomes
    case insensitive.

    Parameters:
    ===========

    <srs filename>     Filename to search for string inside.
    <srs string>       String to search for in the <srs filename>.
    <trgt filename>    New file to be created.
    <trgt string>      String which will replace the <srs string>.
    [C]                When included the search becomes case insensitive.

    Examples:
    =========

    *Freplace Documnt1 "Roger" Documnt2 "Mike"
                           Replaces all references to the string 'Roger'
                           in the file Documnt1 by the string "Mike", and
                           places the result in Cocumnt2.

    *Freplace ReadMe |M  ReadMe2  |M|J
                           Replaces all references to <CR> in the file
                           'ReadMe' by the ASCII code <CR><LF>, creating
                           a new file called 'ReadMe2'.
                           This example shows how a text file under RISC
                           OS system can be converted to a file readable
                           under MS DOS.

    *Freplace MyProg |J  NewFile -d
                           Creates a file called 'NewFile' identical to
                           file 'MyProg' but removing any ASCII codes 12
                           (Line feed).

    Possible errors: File not found
    ================ Bad parameter

    Related commands: *Fcount
    =================




                  +++++++++++++++++++++++++++++++++
                  +       Memory Commands         +
                  +++++++++++++++++++++++++++++++++

    General Notes:
    ==============

    - Extreme caution should be exercised when using the memory commands
      as most of them have a destructive effect on data in memory.

    - To be able to write into an area of memory, the memory block must
      exist in logical or physical Ram. No write operation is allowed
      into the the ROM address space (above &3400000).

    - The memory commands have been optimized for speed and efficiency.




    =======================================================================
 1: *Clear <start> <end>|+<length>
    =======================================================================

    Purpose: Wipe clean a block of memory.
    ========

    Parameters:
    ===========

    <start>               The start address of memory area
    <end>                 The end address of memory area
    +<length>             The length of memory area

    Examples:
    =========

    *Clear 9000 +100      Clears 256 bytes starting at address &9000
    *Clear 9000 9100      same as above command

    Note: The memory area to be cleared must be writable.
          If the end address of the area to be cleared lies in
          a memory area different than that of the start address,
          ARCTOOLS will clear up to the end of the current memory
          area.

    Possible errors:
    ================

    Related commands: *FillH, *FillT, *FillW.
    =================


    =======================================================================
 2: *FillH <start> <end>|+<length> <hex list>
    =======================================================================

    Purpose:  Fill memory area with a sequence of bytes.
    ========

    This command allows a region of memory to be filled with
    specified data.
    The given sequence of bytes is repeatedly written to bytes in the
    given memory area until the entire block has been filled.

    Parameters:
    ===========

    <start>           Start address of the memory block.
    <end>             End address of the memory block.
    +<length>         Length of the memory block.
    <hex list>        List of space separated hexadecimal bytes
                      to fill the requested memory area with.

    Examples:
    =========

    *FillH 10000 +200 FF          Fills &200 bytes of memory area starting
                                  at address &10000 with the hex byte &FF.

    *FillH 20000 +100 "0 0 1 1"   Fill &100 bytes of memory area starting
                                  at address &20000 with the bytes
                                  0 0 1 1.


    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory
                      Bad number

    Related commands: *FillT, *FillW
    =================

    =======================================================================
 3: *FillT <start> <end>|+<length> <string>
    =======================================================================

    Purpose: Fill memory area with a string.
    ========

    The given string is repeatedly written to bytes in the given
    memory range until the entire block has been filled.

    Parameters:
    ===========

    <start>           Start address of the memory block.
    <end>             End address of the memory block.
    +<length>         Length of the memory block.
    <string>          String to fill memory with. The Operating System
                      GSTranslate convention for specifying control
                      characters may be used within the string.

    Examples:
    =========

    *FillT  45000 +1000 "Risc"   This would fill the memory range &45000
                                 to &46000 with the string "Risc"

    *FillT  45000 46000 "Risc"   Similar to the above.

    *FillT  20000 +100 "|M"      Fill the memory area with the ASCII code
                                 given by CTRL+M, i.e. character with
                                 ASCII code 13.


    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory

    Related commands: *FillH, *FillW
    =================


    =======================================================================
 4: *FillW <start> <end>|+<length> <words list>
    =======================================================================

    Purpose: Fill memory area with 32-bit numbers.
    ========

    The memory block must be word aligned.

    Parameters:
    ===========

    <start>           Start address of the memory block.
    <end>             End address of the memory block.
    +<length>         Length of the memory block.
    <word list>       List of 32-bit numbers space separated.

    Examples:
    =========

    *FillW 19000 21000 "10203040 1234 1 2"

                       Fill memory area &19000 to &21000 with the 32-bit
                       numbers:
                       10203040, 00001234, 00000001, 00000002

    *FillW 21400 +200 "1 2 3 4"

                       Fill memory area &21400 to &21600 with the 32-bit
                       numbers:
                       00000001, 00000002, 00000003, 00000004



    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory
                      Non aligned address
                      Bad number

    Related commands: *FillH, *FillT
    =================



              ===========================================
              General notes on the memory search commands
              ===========================================

   The memory search commands are: *FindB, *FindC, *FindH, *Find, *FindM
   *FindN and *FindT.

   These commands search all memory starting at the given address for
   the given data.
   All of the search commands except *FindC, have optional switches
   which are Q, N, E or F. The meaning of each switch is:
   Q : Quit after first match.
   N : Go for Next match. This gives a list of all matching addresses.
   E : Enter the appropriate editor at the first match.
   F : Full search. This is a count option which will give the number
       of matches found.
   If no Q, N, E or F switch is given then, the message:
   "Found at address &xxxxxxxx (Quit/Next/Edit) (Q/N/E)?" will
   be shown. Press Q to quit, N for next match or E to enter the
   memory editor at the shown address. At any time pressing Escape
   key stops the search. Once in the memory editors, use the key
   combination CTRL+Back Space to search for the next match. The
   Back Space key is the key to the right of the Pound key. You can switch
   to another editor and continue the search.

   At any time, the Escape key can be used to abandon the search.


   NOTE: It is possible that the search commands will report matches
         found in memory locations, that upon entering the editors,
         the contents of these locations have changed.
         The search routines will report that a 32-bit number or a
         mnemonic string is found at say &1C00010, but the content of
         that location is different!!!. The reason behind this is that
         this area (starting at &1C00000) is used as the OS heap and
         Supervisor stack were registers are stored when pushed on the
         stack. The same applies to area starting at &1F00000 which is
         used for the cursor, OS space and the sound DMA.
         ARCTOOLS stores the numbers to search for in registers
         which are pushed into the stack when sub-routines are called.
         The search routine will find the register content pushed into
         the stack, but as soon as the search routine exits to report to
         you that a match is found, the registers would have been pulled
         out of the stack and the stack has been replaced by other values.
         This is the reason behind this strange behaviour. This is considered
         normal and is not a bug.


    =======================================================================
 5: *FindB <start> <binary number> [<Q|N|E|F>]
    =======================================================================

    Purpose: Memory search for a binary number.
    ========

    This command is used to search all the machine memory starting
    at the given address for a binary number.
    Characters allowed in the binary number are 0, 1 and #. The
    entered number is considered a 32-bit binary number.
    If the entered binary number is 11, then this will translate into:
    00000000000000000000000000000011

    The command will list all memory addresses that have the same
    number.

    Parameters:
    ===========

    <start>                 Memory start address.
    <binary number>         A binary number. Single wildcards
                            allowed.
    <Q>                     Quit after first found match.
    <N>                     Show Next address. This causes all
                            all matching memory addresses to be
                            listed into the screen.
    <E>                     Enter the editor at first match address.
    <F>                     Full. This performs a count of the
                            number of matches found.

    Examples:
    =========

    *FindB  0   11          Lists all addresses that contain the binary
                            number %11.

    *FindB  0  ####1111000000000000000000000000  F
                            Count all matches of the given binary number.
                            This actually counts all SWI instructions
                            in the machine.


    Possible errors: Bad memory
    ================ Bad parameter
                     Bad number

    Related commands: *FinH, *FindM, *FindT, *FindC, *FindN, *FindW
    =================


    =======================================================================
 6: *FindC <start> <word|%binary|Mnemonic string>
    =======================================================================

    Purpose: Provide a mnemonic screen dump of all occurrences of
    ======== the given match code.

    This command will dump to the screen in the current dis-assembler
    display format all occurrences of the given code.
    The code to search for can be given as a 32-bit number (Word),
    a 32-bit binary number or as a mnemonic string.
    If the code is enclosed in quotes then it is assumed to be a
    mnemonic string, if it is proceeded by the % sign then it is
    assumed to be a binary number, otherwise it is a 32-bit hex
    number.
    Single wildcards are only allowed in the word or binary number
    code.

    Parameters:
    ===========

    <word>                   A 32-bit hex number. Single wild cards
                             allowed
    <%cinary>                A 32-bit binary number, proceeded by the
                             % sign. Single wildcards allowed.
    <Mnemonic string>        A string of assembly code.

    Examples:
    =========

    *FindC 3800000 "SWI OS_WriteS"    Dump to screen all references to the
                                      SWI OS_Find instruction starting at
                                      address &3800000 (System ROM area).

    *FindC 1800000 #F######      Dump to screen all reference of SWI
                                 instructions starting at address &1800000.

    *FindC 0 %####00010###########00001001###
                                 Dump to screen all references to the
                                 ARM3 SWP instruction.

    *FindC 3800000 %####1110000#########111100010000
                                 Dump to screen all reference to the
                                 ARM3 cache control register operations in
                                 the system ROM.


    Possible errors: Bad memory
    ================ Bad parameter
                     Bad number

    Related commands: *FinH, *FindM, *FindT, *FindW, *FindN, *FindB
    =================


    =======================================================================
 7: *FindH <start> <hex list> [<Q|N|E|F>]
    =======================================================================

    Purpose: Search memory for a list of hex bytes.
    ========

    Parameters:
    ===========

    <start>                 Memory start address
    <hex list>              A list of hexadecimal byte numbers
                            Single wildcards allowed.
    <Q>                     Quit after first found match.
    <N>                     Show Next address. This causes all
                            all matching memory addresses to be
                            listed into the screen.
    <E>                     Enter the editor at first match address.
    <F>                     Full. This performs a count of the
                            number of matches found.

    Examples:
    =========

    *FindH &8F00 "0D FF"    Search memory for the bytes &0D followed by
                            by &FF starting at address &8F00. This finds
                            the end address of a BASIC program in
                            memory.

    *FindH 0 "FF ## FF 00"  Search for the bytes sequence which has the
                            first byte &FF, third byte &FF, fourth byte
                            &00, don't care about second byte.

    *FindH 3800000 "1#F"    Similar to search for "1# 0F", starting at
                            address &3800000.

    *FindH 0 "#A 20 F# ## 34"  Search for the bytes sequence with the
                               following criteria:
                               1st byte: low nibble = &A
                               2nd byte: &20
                               3rd byte: high nibble = &F
                               4th byte: don't care
                               5th byte: &34

    Possible errors: Bad memory
    ================ Bad parameter
                     Bad number

    Related commands: *FinB, *FindM, *FindT, *FindC, *FindN, *FindW
    =================

    =======================================================================
 8: *FindM <start> <Mnemonic string> [<Q|N|E|F>]
    =======================================================================

    Purpose: Search memory starting at the given address for
    ======== mnemonics.

    This command allows the search of a line of assembly code
    to be performed. The mnemonic must be enclosed in quotes.
    Any string which ARCTOOLS can assemble can be searched for.
    The current version of ARCTOOLS does not allow wildcards in
    the given mnemonic string.

    Parameters:
    ===========

    <Start>                 Memory start address.
    <Mnemonic string>       Valid mnemonic string.
    <Q>                     Quit after first found match.
    <N>                     Show Next address. This causes all
                            all matching memory addresses to be
                            listed into the screen.
    <E>                     Enter the editor at first match address.
    <F>                     Full. This performs a count of the
                            number of matches found.

    Examples:
    =========

    *FindM   0  "STMFD R13!,{R14}"    Search memory starting at address
                                      &0000 for the mnemonic string
                                      "STMFD R13!,{R14}"

    *FindM 3800000 "SWI OS_ReadC"     Searches the ROM for the all
                                      occurrences of SWI "OS_ReadC".

    *FindM 3800000 "SWI OS_ReadC" F   Counts the number of occurrences
                                      of the SWI "OS_ReadC"

    *FindM 3800000 "LDRB R0,[R1]" E   Search for the given assembly
                                      code in the system ROM, entering
                                      the Mnemonics editor at the first
                                      Match found. Use CTRL+Back Space
                                      for next match search.

    Possible errors: Bad memory
    ================ Bad parameter

    Related commands: *FinH, *FindB, *FindT, *FindC, *FindN
    =================

    =======================================================================
 9: *FindN <stirt> <32-bit number> [<Q|N|E|F>]
    =======================================================================

    Purpose: Search for a 32-bit number in memory.
    ========

    This command searches for a 32-bit decimal number. The sign
    can be given. Wildcards are not allowed.

    Parameters:
    ===========

    <start>                 Memory start address
    <32-bit number>         A 32-bit decimal number.
    <Q>                     Quit after first found match.
    <N>                     Show Next address. This causes all
                            all matching memory addresses to be
                            listed into the screen.
    <E>                     Enter the editor at first match address.
    <F>                     Full. This performs a count of the
                            number of matches found.

    Examples:
    =========

    *FindN  0  -1 N         List all occurrences of the decimal number
                            -1

    *FindN  3800000 -1 F    Count all occurrences of the number -1 in
                            the system ROM area.

    *FindN  3800000 123 E   Search for the number 123 in the system
                            ROM, entering the Numbers editor at the
                            first match found. Use CTRL+Back Space for
                            the next match.


    Possible errors: Bad memory
    ================ Bad parameter
                     Bad number

    Related commands: *FinH, *FindM, *FindT, *FindC, *FindB, *FindW
    =================

    =======================================================================
10: *FindT <start> <string> [<Q|N|E|F>]
    =======================================================================

    Purpose: Search for a string in memory
    ========

    The operating system GSTranslate convention for specifying control
    characters may be used within the search string.

    Parameters:
    ===========

    <start>                 Memory start address
    <string>                A valid string which is GSTranslated.
                            Single wildcards allowed.
    <Q>                     Quit after first found match.
    <N>                     Show Next address. This causes all
                            all matching memory addresses to be
                            listed into the screen.
    <E>                     Enter the editor at first match address.
    <F>                     Full. This performs a count of the
                            number of matches found.

    Examples:
    =========

    *FindT 3800000 "Acorn"        Search the OS ROM for the string "Acorn".

    *FindT 3800000 "System" F     Count the number of occurrences of the
                                  string "System" in the OS ROM.

    *FindT 3800000 "System" C F   Similar to the above but the search is
                                  now case insensitive.

    *FindT 0 "|M|J" N             List all addresses that contain the
                                  control codes 13 followed by 10. These
                                  are the control codes for a carriage return
                                  and a line feed.


    Possible errors: Bad memory
    ================ Bad parameter

    Related commands: *FinH, *FindM, *FindW, *FindC, *FindN, *FindB
    =================


    =======================================================================
11: *FindW <start> <word> [<Q|N|E|F>]
    =======================================================================

    Purpose: Search memory for a given 32-bit hexadecimal number.
    ========

    Parameters:
    ===========

    <start>                 Memory start address
    <word>                  A 32-bit hexadecimal number. Single
                            wildcards allowed.
    <Q>                     Quit after first found match.
    <N>                     Show Next address. This causes all
                            all matching memory addresses to be
                            listed into the screen.
    <E>                     Enter the editor at first match address.
    <F>                     Full. This performs a count of the
                            number of matches found.

    Examples:
    =========

    *FindW  0 "######12"      Search memory starting at address &00000 for
                              the hex 32-bit number which has the LSB byte
                              of &12.

    *Find 1800000 "6A######"  Search memory starting at address &1800000 for
                              any 32-bit number with the msb byte equal to
                              &6A. This actually searches for all Branch
                              instructions with 'V' condition code set.
                              If you select to enter the editor, then you
                              are placed in the WORDs editors, however, you
                              can continue the search for the next match
                              from within any editor.


    Possible errors: Bad memory
    ================ Bad parameter
                     Bad number

    Related commands: *FinH, *FindM, *FindT, *FindC, *FindN, *FindB
    =================

    =======================================================================
12: *Heap [<address>]
    =======================================================================

    Purpose: Examine the structure of a heap memory.
    ========

    Parameters:
    ===========

    [<address>]            Heap start address.
                           If no address is given the RMA area is examined.

    This command provides the following information:

    - Heap memory start address
    - Heap size
    - Total number of blocks
    - Total area used in the heap
    - Total free area in the heap
    - Largest free block

    The command also provides the following information on each block in
    the heap:

    - Block position
    - Start address in heap area
    - Size
    - Status (Claimed or free)

    If the Heap address is &1800000 (i.e. the RMA area), then this command
    provides more information on whether the heap block is a module code
    or a module buffer.

    Examples:
    =========

    *Heap          Displays the structure of the RMA heap

    *Heap 10000    Displays the structure of heap area starting at memory
                   address &10000

    Related error: 'Bad or corrupted heap'
    ==============

    Related commands: None.
    =================



    The block size shown is the one setup by the OS Heap Manager and not
    necessarily the one requested by the program. ie. the size includes
    the 4 bytes allocated at the start of each block which contains the
    block size. Additionally the Heap manager forces the block size to
    be a multiple of eight. Therefore, the minimum size of a block is 8
    bytes including the 4 bytes allocated to the size.
    Example: if a block size of 1022 was requested then the Heap Manager
             aligns the length to a word boundary becoming 1024 bytes, then
             adds 4 bytes to it making it 1028 bytes, then forces it to
             a multiple of eight making the length 1032 bytes.
    Using the above example it can be seen that although the user requested
    1022 bytes, the Heap Manager allocated 1032 bytes for the block.
    ARCTOOLS displays the Heap Manager's block size, not the user's requested
    size.
    Released blocks are highlighted by the word 'free'. The last block if any
    is the unused area in the heap.
    The *Heap command is very useful when developing programs that make use
    of the heap system as it is important for the program to release any
    memory area not being used and to be written in such a way as not to
    cause many holes to appear in the heap memory.
    RISC OS makes extensive use of a number of different heaps, the re-
    locatable module area (RMA) is used by the OS as one large heap. Other
    heap areas known to the author is the one starting at address &1C02000
    which is used to store system variables.



    =======================================================================
13: *Mcompare <start> <end>|+<length> <with> [<max diff>]
    =======================================================================

    Purpose: Compares the content of two memory blocks byte for
    ======== byte.

    This command compares the content of two memory areas byte for
    for byte listing any differences on the screen.
    If the <max difference> is ommited, the comparison will stop
    after 10 differences.
    To display all difference: give a max difference value of 0.
    Any difference will be shown as:

    Different at <address> = <Byte> / <address> = <Byte>

    If the two memory blocks contain the same data, the message
    'Comparion OK' will be shown.

    Parameters:
    ===========

    <start>            Start address of the first memory block.
    <end>              End address of the first memory block.
    +<length>          Length of the first memory block.
    <with>             Start address of the second memory block.
    <max diff>         Optional maximum difference.

    Examples:
    =========

    *Mcompare 8F00 [phone]      Compare memory 8F00 to 9F00 with
                                    memory starting at 10000.

    *Mcompare 20000 [phone]    Compare &200 bytes of memory starting
                                    at address &20000 with that starting
                                    at address &30000. List all possible
                                    differences.


    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory

    Related commands: *FMcompare.
    =================

    =======================================================================
14: *Mdump <format> <start> [<end>|+<length> [<offset>]]
    =======================================================================

    Purpose: Dump memory content in the specified dump format.
    ========

    When the memory is dumped into the screen, the memory addresses
    shown are those where the data comes from. However, using the
    <offset> address you can cause the result to show the dump of
    an area of memory as though it has come from another address.
    NOTE: To give the <offset> address, you should specify the <end> or
          +<length> parameter.
    If no <end> or +<length> parameter is given then a full screen dump
    is given. This depends on the current screen mode.

    Parameters:
    ===========

    <format>               Editor format: B, H, M, N, T, W or Y.
    <start>                Start address of the memory block.
    <end>                  Optional memory block end address.
    +<length>              Optional length of the memory block.
    <offset>               Optional offset address to be used in place
                           of the actual memory address.

    Examples:
    =========

    *Mdump M 3800000 +100 0    Dump &100 bytes starting at &3800000 using
                               the Mnemonic format. Show as though code
                               was at address &0000

    *Mdump T 8f00 20000        Dump memory area &8F00 to &20000 using the
                               Text format.



    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory
                      Unknown editor format

    Related commands: *Fdump, *medit, *Dedit.
    =================

    =======================================================================
15: *Medit [[<address> [<format>]] | [<label>]
    =======================================================================

    Purpose: Enter one of the 7 memory editors.
    ========

    This is the heart of ARCTOOLS commands. Any of the 7 memory
    editors can be accessed using this command.
    The address given is aligned to the next word-aligned address in
    the Mnemonic, Word, Numbers and Binary editors.

    Parameters:
    ===========

    *Medit                     Enter the last visited editor at the last
                               visited address.
    *Medit <address>           Enter the last visited editor at the given
                               memory address.
    *Medit <address> <format>  Enter the given editor at the given address.
    *medit <format>            Enter the given editor at the last visited
                               memory address.
    *medit <label>             Enter the Mnemonics editor at the given
                               label address.

    Examples:
    =========

    *medit 3800000 m           Enter the Mnemonics editor at the start of
                               system ROM space.

    *medit my_code             Enter the Mnemonics editor at the label
                               my_code. If the label is not defined, then
                               the error message 'Bad number' is given.

    *medit T                   Enter the text editor at the last visited
                               address.


    Possible errors: Bad number
    ================ Unknown editor format

    Related commands: *Mdump, *Fdump, *Dedit.
    =================


    =======================================================================
16: *Mmap
    =======================================================================

    Purpose: Display the memory map of the machine.
    ========

    This command gives useful information on the logical memory
    mapping of the machine. The command shows the memory area
    name, its start address, its end address and its current
    size. The command also shows the total physical ram in the
    machine.
    The sizes of the IOC devices, the Low ROM and the High ROM areas
    are the maximum size available.

    On ARM 3 machines, the cache state of each memory area is displayed.
    Memory areas can be cacheable, uncacheable, cacheable and updateable,
    or cacheable and disruptive.


    Possible errors: None.
    ================

    Related commands: None.
    =================


    =======================================================================
17: *Move <start> <end>|+<length> <to>
    =======================================================================

    Purpose: Copy a block of memory from one location to another.
    ========

    This command performs a copy of an area of memory to another
    location leaving the original area intact.

    Parameters:
    ===========

    <start>             Start address of memory to be copied.
    <end>               End address of the memory to be copied.
    +<length>           Length of the memory block to be copied.
    <to>                Target address.

    Examples:
    =========

    *Move  3800000 [phone]    Copies the first &2000 bytes from
                                   the memory area starting at address
                                   &3800000 to the area starting at
                                   address &20000.

    *Move 2004000  [phone]     Copies &1000 bytes from physical ram
                                   starting at &2004000 to address &20000.



    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory

    Related commands: *Swap, *Reverse.
    =================

    =======================================================================
18: *Mpage [<page number>]
    =======================================================================

    Purpose:  Displays the logical to physical memory mapping used by
    ========  the MEMC.

    Parameters:
    ===========

    [<page number>]         MEMC page number 0-255
                            If no page is given all pages are shown

    Information provided are:

    - Total pages in machines
    - Page size
    - Total mapped out pages (see below)
    - Page number, with its corresponding physical and logical memory
      addresses, its protection level number, its accessibility level and
      the memory area allocated to.

    The ARM can address 64 Mbytes of memory. This 64 Mbytes is divided
    into three areas. 16 Mbytes for physical RAM, 16 Mbytes for I/O and ROM,
    and 32 Mbytes for logical RAM. Address &0000000 to  &1FFFFFF is assigned
    to logical RAM and addresses &2000000 to &2FFFFFF are assigned to
    physical RAM. The I/O and ROM addresses start from &3000000 to &3FFFFFF.
    RISC OS uses the MEMC to map the 16 Mbytes of physical memory into
    16 Mbytes of logical memory. Using the current ARM-MEMC interface, the
    maximum RAM an ARM machine can support is 16 Mbytes.
    The mapping performed by the MEMC is achieved through a so called paging
    structure. The available physical memory is divided into pages. The
    max number of pages the current MEMC can support is 128. In a 1 Mbytes
    machine, each MEMC page is 8 Kbytes in size (1 Mbytes divided by 128).
    In a 4 Mbytes machines, the page size is 32 Kbytes. Each page has its
    own descriptor entry held in a so called CAM (Content-Addressable Memory)
    area in the MEMC. This MEMC structure allows fast logical to physical
    address translation without increase in memory access time.
    Each MEMC page can have its own protection level; 0, 1 or 2.

    The protection levels are defined as follows:
    Level 0 : The least privileged mode. This level allows read and
              write operation by everybody.
    Level 1 : This is read only in User mode. You must enter a Supervisor
              mode (SVC, IRQ or FIQ) to write into such page.
    Level 2 : This is not accessible in User Mode. You must switch into
              a Supervisor mode to read or write into such page.

    RISC OS provides two SWIs to enable reading and/or setting the MEMC
    memory map entry parameters together with protection levels.
    Using these SWIs, one can perform the following operation on memory
    pages:
           1. Un-map a page
           2. Map a page onto one page of logical memory
           3. Map a page onto several pages of logical memory

    The last operation (mapping one page into several pages of logical
    memory) is very unique in the sense that once several pages of
    logical Ram are mapped from one physical page, RISC OS will not
    be able to read or write from such pages. RISC OS can only read
    and write from pages that have a one-to-one mapping. The program
    that performed such map translation is the only one which could
    read and write those pages as it the one that has the old mapping
    parameters before being re-mapped.
    The Desktop uses this technique (one-to-many mapping) to hide
    pages of applications away when several applications are being
    multi-tasked and are sharing the same address (&8000).
    Such pages are referred to as mapped-out or hidden pages.

    In ARCTOOLS *Mpage command, mapped out pages are annotated 'Mapped out'
    and have the minimum accessibility. These pages are mapped to address
    &1F08000 which is part of the Cursor, OS space and Sound DMA area.
    All mapped out pages are mapped into this address, hence ARCTOOLS can not
    display the contents of such pages, however, if the machine contains
    mapped out pages, ARCTOOLS memory editors will allow display and editing
    of the memory page at address &1F08000 which will be one of the mapped
    out pages. Remember that ARCTOOLS memory editor allow editing of physical
    RAM and hence all pages of the machine are accessible.
    The mapping out technique is used extensively by the Desktop to hide
    programs and memory areas in a multi-tasking environment.
    Using *Mpage from within the Desktop will show all mapped out pages
    available.
    Memory pages may be hidden or mapped out by using the OS SWI call
    'OS_SetMemMapEntries' setting the page address to a value above
    32 Mbytes (&2000000).


    =======================================================================
19: *Reverse <start> <end>|+<length>
    =======================================================================

    Purpose: Reverse the data in a block of memory.
    ========

    Parameters:
    ===========

    <start>             Start address of first memory block.
    <end>               End address of the first memory block
    +<length>           Length of the first memory block.


    Examples:
    =========

    *Reverse   8000 +100      Reverses 256 bytes of data starting
                              at memory address &8000

    *Reverse 10000 11000      Reverses the given memory block.


    Possible errors:  None logical ram address
    ================  Non-writable memory
                      Bad memory

    Related commands: *Swap, *Move.
    =================


    =======================================================================
20: *Swap <start> <end>|+<length> <with>
    =======================================================================

    Purpose: Swaps to blocks of memory.
    ========

    Parameters:
    ===========

    <start>             Start address o& first memory block.
    <end>               End address of the first memory block
    +<length>           Length of the first memory block
    <with>              Start address of the second memory block

    Examples:
    =========

    *Swap  8000 [phone]    Swaps 4096 bytes (&1000) from the
                              memory area starting at &8000 with that
                              starting at &9000

    *Swap 8000 9000 9000      Similar to the above, using an end address
                              example of &9000.

    Possible errors:  Memory overlaps.
    ===============   None logical ram address
                      Non-writable memory
                      Bad memory


    Related commands: *Move, *Reverse.
    ================


    Note: The two memory blocks should not overlap, as this will
          generate an error. Swapping overlapped memory blocks causes
          the data in both blocks to be corrupted.

    =======================================================================
21: *Timing <start> [<end>|+<length> [<offset>]]
    =======================================================================

     This command is similar to *Mdump with an 'M' format, however, the dump
     also includes the ARM instruction timing.
     It is informative to know how quickly you can expect instructions to
     execute. This command gives the timing of all ARM instructions.
     As different ARM machines have different clock frequencies, the timing
     is not given in actual nano- or micro-seconds, instead it is given in
     terms of 'instruction cycles'. The 'clock cycle' is one tick of the
     crystal oscillator which drives the ARM.
     There are 3 types of instruction cycles used in an ARM machine:

     1. Sequential (s) cycles:
        Used when the ARM fetches instructions in a sequential order.
        For example, when the ARM is executing instructions with no
        interruption from branches and load/store operation.
        These cycles are one clock cycle per instruction cycle for RAM
        and two clock cycles for ROM.
     2. Non-sequential (n) cycles:
        Used when the ARM fetches instructions in a non-sequential order.
        For example, the first instruction fetched after a branch
        instruction.
        These cycles need two clocks cycles per instruction cycle for RAM
        and ROM.
     3. Internal (i) cycles:
        Used when the ARM is performing an internal operation and not
        accessing memory to fetch an instruction.
        These instruction cycles always take one clock cycle.

     The actual time for each instruction to execute depends on the type
     of instruction and on the machine clock speed.

     The clock cycles timings are as follows:

      8 MHz machine: one clock cycle is 125 nano-seconds
     12 MHz machine: one clock cycle is 83.3 nano-seconds
     24 MHz machine: one clock cycle is 41.7 nano-seconds
     32 MHz machine: one clock cycle is 32.75 nano-seconds

     One nano-second equals one thousands of a micro-second.

     On an 8 MHz machine one 's' instruction cycle takes 125 nano-seconds,
     one 'n' cycle takes 250 nano-seconds.
     On a 16 MHz machine one 's' instruction cycle takes 65.5 nano-seconds.
     On 25 MHz and above machines the 's' and 'n' instruction cycle timing
   0 will be affected by the memory access time as the processor will be
     using wait states when accessing the slow memory. However, the 'i'
     cycles are not affected by memory access time.


    =======================================================================
22: *Where <address>
    =======================================================================

    Purpose: Display the area of memory to which the given address
    ======== belongs.


    Examples:
    =========

    *where 0            The command output will be 'OS workspace'

    *where 3400000      The command output will be 'Low ROM/VIDC'



   Possible errors: 'Bad number'
   ================ 'Bad memory'

   Related commands: *Mpage
   =================



                  ++++++++++++++++++++++++++++++++
                  +     General Commands          +
                  ++++++++++++++++++++++++++++++++


    =======================================================================
 1: *BList <filename> [<1st line>][,[<2nd line>]] [<LISTO number>]
    =======================================================================

    Purpose: Lists a tokenised BASIC file. Output is sent to the
    ======== screen but if VDU2 was issued output will also be sent to
             the printer.

    Parameters:
    ===========

    <filename>          the name of a BASIC tokenised file
    [<LISTO number>]    this is a number from 0-31. This is similar
                        to BASIC's LISTO option number except that
                        bit 1 (i.e. ident structure) is not used.
                        The default number is zero.

    LISTO option bits mean:
    bit 0: Space after line
    bit 1: Not used
    bit 2: Split lines at :
    bit 3: Don't list line numbers
    bit 4: List tokens in lower case

    Examples:
    ========

    *BList Prog          Lists file 'Prog' in default LISTO option.

    *BList Prog 1000     Lists line 1000 of file 'Prog'

    *Blist Prog 5000,    Lists file 'Prog' starting at line 5000.
                         Note: There should be no space between the
                         number and the comma.

    *Blist Prog 10,1000  Lists lines 10 through 1000 of file 'Prog'.
                         Note: There should be no space between the
                         the two numbers and the comma.

    *Blist Prog ,1000    Lists file 'Prog' from start up to line 1000.

    *Blist Prog ,1000 8  Lists file 'Prog' from start up to line 1000
                         without line numbers.

    NOTE: To specify the LISTO option, the 2nd line number must also be
          given otherwise the LISTO number is interpreted as the 1st line
          number.


    Possible errors: 'Not a BASIC file'
    ===============  'Bad BASIC file'
                     'Bad parameters'

    Related commands: None.
    ================


    =======================================================================
 2: *Event [<event number> <ON|OFF>]
    =======================================================================

    Purpose: Allow control and display of events status.
    ========

    Parameters:
    ===========

    <event number>         Decimal number 0 to 17

    <ON|OFF>               Enable or disable.

    Examples:
    =========

    *Event                Lists all events numbers, names and
                          status.

    *event 0 ON           Enable the output buffer empty event.

    *event 0 OFF          Disable the output buffer empty event.


    Possible errors: Bad parameter
    ================ Number too big

    Related commands: None.
    =================

    Generating events all the time uses a lot of processor time. To
    avoid this, events are disabled by default.
    In RISC OS 3, event number 11 (A key has been pressed or released
    event) is normally enabled. This is enabled by the Screen blanker
    module.



    =======================================================================
 3: *Index
    =======================================================================

    Purpose: Show the speed index of the machine.
    ====½===

    This command measures the speed index of the machine relative
    to an Archimedes A310 computer fitted with ARM 2 processor and
    a normal MEMC chip (i.e. not MEMC1a) operating in screen mode 0.
    In other words; this index gives a relative measure of how fast
    your computer is compared to a very early module of the
    Archimedes (in fact the first produced type 1987).

    NOTE:  This test will be extended in the future to cover other
    =====  aspects of the machine.





    =======================================================================
 4: *Labels
    =======================================================================

    Purpose: List all defined labels in memory.
    ========

    This command will list all currently defined labels in memory.
    This command will not list any defined remarks.

    The list shows the label address and name.


    Possible errors: No defined labels
    ================

    Related commands: *SaveLabels, *LoadLabels
    =================

    =======================================================================
 5: *LoadLabels <filename>
    =======================================================================

    Purpose: Loads a previously saved Labels file.
    ========

    This command is a complement to the *SaveLabels command, and
    allows you load any saved labels into ARCTOOLS buffer.
    If the file is larger than the current size of the Labels
    buffer, ARCTOOLS will try to extend the buffer area by claiming
    the adjacent free slot in the RMA. If this fails the file will
    not be loaded and an error message will be generated.

    Warning: Loading a Labels file will delete any currently
             defined labels in memory.


    Possible errors: Not a labels' file
    ================ Unable to extend due no room in RMA

    Related commands: *SaveLabels, *Labels.
    =================


    =======================================================================
 6: *Mcommands [<relocatable module name>]
    =======================================================================

    Purpose: List a given module *Command entry addresses.
    ========

    This command is used to list all commands in a given module
    together with their entry addresses.
    If no module name is given then all commands in the machine
    are listed.


    Parameters:
    ===========

    [<relocatable module name>]      Optional module name.

    Examples:
    =========

    *Mcommands ARCTOOLS          Lists all entry addresses of ARCTOOLS
                                 commands.

    *Mcommands Utility.          Lists all entry addresses of the Utility
                                 Module commands.

    *Mcommands                   Lists all entry addresses of all commands
                                 in the machine.

    Possible errors: Module not found
    ================

    Related commands: None.
    =================


    =======================================================================
 7: *SaveArc <filename>
    =======================================================================

    Purpose: Save ARCTOOLS module together with current
    ======== configurations.

    This command is used to save ARCTOOLS module to disc together
    with any configurations that you have made. Once loaded, the
    new ARCTOOLS module will remember the last disc and memory editors,
    the last memory address, the last disc address, the last flags
    setup in any editor.
    This is the easiest way of configuring your ARCTOOLS to suit your
    requirement. No fiddling with *Configure commands.


    Possible errors: None.
    ================

    Related commands: None.
    =================

    =======================================================================
 8: *SaveLabels <filename>
    =======================================================================

    Purpose: Save all defined labels in memory as a Data file.
    ========

    Once you have defined any labels in the memory editors, you
    can save them to disc as a Data file so that you will not
    have to write them all over again.
    It is also advisable to save any defined labels you have
    created before issuing any of the destructive modules
    *commands such as *Tidy, *Rmkill or *Rmclear.

    The saved labels can be loaded into ARCTOOLS buffer using the
    *LoadLabels command.

    Note: This command will also save any defined line comments.


    Possible errors: No defined labels
    ================

    Related commands: *LoadLabels, *Labels.
    =================



    =======================================================================
 9: *Slow [<value>]
    =======================================================================

    Purpose: Slow down program execution speed.
    ========

    This command slows down the machine by a given delay. Although
    this might seem strange thing you want your computer to do,
    you may need this command when you want to see things that are
    too quick for the eye to catch. Examples are, slowing down games
    so that you can play them at your own pace, watching the desktop
    window drawing order, debugging a program which outputs to the
    screen.
    Routines or programs that disable interrupts will not be slowed
    down, for example, you will not be able to actually see in slowmotion
    how a character is drawn on the screen pixel-by-pixel.

    Parameters:
    ===========

    [<value>]          This is the only parameter, which gives the
                       delay value in decimal numbers.
                       Acceptable values are 0 to 5120.
                       A value of 0 restores the machine to its own
                       speed.
    Examples:
    =========

    *Slow 200          Slow down the machine by a value of 200.

    *Slow 3000         Slow down by 3000. Very sluggish.


    Possible errors:  'Bad number'
    ================  'Number too big'

    Related commands:  None.
    =================


    =======================================================================
10: *SwiC [<SWI chunck>]
    =======================================================================

    Purpose:  List all Software Interrupts in a given SWI Chunck
    ========  Identification number.

    The Operating System provides a total of 16 million different
    Software Interrupts or SWI. A SWI Chunck Identification
    number identifies a block of 64 consecutive SWIs. Acorn
    assigns a Chunck Identification number to each module or
    application on  request.
    The *SwiC command will list all SWIs in the given chunck
    identification number.
    If the number given is not a SWI chunck ID number it will be
    rounded to the related Chunck ID number.
    Because not every number in a SWI chunck is utilized, this
    command will only list used SWIs that have a SWI name.

    Examples:
    =========

    *SWIC 0            Lists all SWI numbers from 0 to 63

    *SWIC 40080        Lists all Font SWIs.

    *SWIC 43040        Lists all Territory SWIs.

    *SWIC 44B00        Lists all DOS filing system SWIs.

    Possible errors: Bad number
    ================

    Related commands: *SwiM, *SwiN, *SwiS
    =================

    =======================================================================
11: *SwiM <relocatable module name>
    =======================================================================

    Purpose: List all Software Interrupts in a given module.
    ========

    Parameters:
    ===========

    <relocatable module name>    The module name, abbreviated if
                                 required.

    Examples:
    =========

    *SwiM  ADFS           Lists all SWIs in the ADFS module.

    *SwiM  Hour.          Lists all SWIs in the Hourglass module.

    *SwiM  Squash         Lists all SWIs in the Squash module.

    *SwiM  UtilityModule  Lists all the Operating System SWIs.

    If the module does not have any SWIs then the 'No SWIs in module'
    message will be shown.

    Although the UtilityModule does not have SWIs, this commands will
    show all the Operating System SWIs (i.e SWIs with bits 18 and 19
    clear).

    Possible errors: Module not found
    ================

    Related commands: *SwiC, *SwiN, *SwiS.
    =================


    =======================================================================
12: *SwiN <SWI name>
    =======================================================================

    Purpose: Convert a SWI name into a SWI number.
    ========

    Parameters:
    ===========

    <SWI name>         A valid SWI name.

    Examples:
    =========

    *SwiN   OS_Write0

    *SWIN   XOS_ReadC


    Note: The SWI name is case sensitive, and must be entered correctly.


    Possible errors: SWI name not known.
    ================

    Related commands: *SwiC, *SwiM, *SwiS
    =================

    =======================================================================
13: *SwiS <SWI number>
    =======================================================================

    Purpose: Convert a SWI number into a SWI name.
    ========

    Parameters:
    ===========

    <SWI number>         Hexadecimal SWI number.

    Examples:
    =========

    *SWIS  0

    *SWIS  40

    *SWIS  80682


    Possible errors: Bad number
    ================

    Related commands: *SwiC, *SwiM, *SwiN
    =================


    =======================================================================
14: *System
    =======================================================================

    Purpose: Display information on the current system and
    ======== program environment.

    The command displays information on the current system and the current
    environment, such as the processor type, memory used, memory limits, and
    all environment handlers codes addresses and buffers.
    The command also displays the application start time and the
    keyboard handler address. If an ARM3 or higher is fitted, then the
    current content of the cache control registers is shown.
    the *System command provides information on the following:

    - Processor type
    - Cache state (ON or OFF)
    - Cache ID register content
    - Cache Control register content
    - Cache Cacheable register content
    - Cache Updateable register content
    - Cache Disruptive register content
    - Memory limit address
    - Undefined instructions handler address
    - Prefetch abort handler address
    - Data abort handler address
    - Address exception handler address
    - Error handler address
    - Error buffer address
    - CallBack handler address
    - CallBack register save area address
    - BreakPoint handler address
    - BreakPoint register save area address
    - Escape handler address
    - Event handler address
    - Exit handler address
    - Unused SWI handler address
    - Exception registers buffer address
    - Application space
    - Currently active object address
    - UpCall handler address
    - Current MEMC state
    - *Command string address
    - Keyboard handler address
    - Application start time

    =======================================================================
15: *Tools [G|D|M]
    =======================================================================

    Purpose: Display a summary of all ARCTOOLS *Commands names
    ======== and their correct syntax.

    Examples:
    =========

    *Tools        Lists all ARCTOOLS commands.

    *Tools D      Lists all ARCTOOLS disc and file commands.

    *Tools G      Lists all ARCTOOLS general commands.

    *Tools M      Lists all ARCTOOLS memory commands.

    Possible errors: None
    ===============

    Related commands: None
    ================


    =======================================================================
16: *Vector [<vector number>]
    =======================================================================

    Purpose: Display information on the routines claiming the Software
    ======== Vectors.

    The information displayed are address of the routines, routine
    workspace start address (R12) and where the routine is located
    i.e. OS kernel, ADFS, etc. The display also gives the vector name.

    The allowed vectors numbers are 0 to 47.

    The Operating System keeps track of the vector chains in its workspace
    (the first 32 Kbytes of memory). The chain structure contains pointers
    to the vector claimants code and workspace.

    *Vector with no parameter will list all the vectors available.

    Examples:
    =========

    *Vector 1                 gives information on the errorV

    *Vector                   gives information on all vectors



    Possible errors: 'Number too big'
    ===============

    Related Commands: None
    ================





                      ===========================
                           The Memory Editors
                      ===========================

 A total of 7 different memory editors are provided in ARCTOOLS allowing
 limitless possibilities or editing different memory areas. The most power-
 ful of these is the Mnemonics editor or dis-assembler, see the sections
 on the assembler and disassembler for more details.

  There are two methods to enter the memory editors:

  1. from the line command using the *Medit command.
  2. from the disc editors using the CTRL-E key combination.

 The cursor keys are used for navigate around memory. Facilities are provided
 to navigate really quickly using the 'Memory Area' jump. 'Memory Area' jumps
 can be achieved using the Up and Down cursor keys while holding the CTRL
 and SHIFT keys.

 The information bar (the top line of the screen) provides information on
 the current area and the current system as well as the current editor.
 The different information provided by the information bar can be viewed
 using the CTRL-Copy keys.

 Data can be entered in different formats depending on the editor type.
 The 'Text Editor' allows any character to be entered. In the 'Numbers'
 editor, only numbers are allowed. In the 'Hex', 'Bytes', 'Binary' and
 'Words' editors, you have the option of entering data using Hex, Binary,
 Decimal or Text formats, the different formats are selectable using the
 CTRL-Insert key.

 Two memory areas can not be edited; the ROM and the IO space. Other areas
 including the physical ram area can be edited.







                      ===========================
                            The DISC Editors
                      ===========================

  ARCTOOLS provides a number of powerful tools to manipulate data stored
  on discs directly. The *Dget and *Dput commands are one example of
  an improved method of moving data between disc and memory which removes
  the Operating System limitations of having to work with sector aligned
  start addresses and sizes. The most powerful tool provided by ARCTOOLS
  is the disc editor. The disc editor manipulates data stored on discs
  directly using disc addresses rather than sector and track numbers.
  Seven different display formats are provided, similar to those in the
  memory editors, this gives a total of seven disc editors. The disc editors
  provide additional information on the currently editted disc which is
  displayed at the top line of the screen using the CTRL-Copy key
  combination.

  There are two methods to enter the disc editors:

  1. from the line command using the *Dedit command.
  2. from the memory editor using the CTRL-E key combination.

  The disc editors work with any disc format known to the Operating System.
  Under RISC OS this includes:
  - ADFS disc formats L, D, E and F.
  - DOS 1.44M, 720M, 1.2M and 360K discs.
  - Atari 720K and 360K discs.
  - RAM discs.
  - IDE hard discs.
  - ST506 hard discs.
  - SCSI hard discs.

  The disc editors will automatically support any new filing systems added
  to the FileCore modules.

  WARNING:     Extreme care must be observed when using the disc editors.
  ========     The entire disc can be accessed and any data can be changed
               without restriction. Changing data on the disc particularly
               directory or map data can render large number of files and
               or the entire disc inaccessible.


  Using the Disc Editors with non-standard discs:
  ===============================================

  The disc editors also support non-standard or protected format discs. The
  format of these discs must be described to ARCTOOLS disc editors. To
  achieve this a simple method is used.

  When any of the disc editors is entered, ARCTOOLS asks the Operating
  System to identify the disc format. If the Operating System or its
  extension modules fail to identify the disc and error message will be
  produced which prevents you from using the disc editors.
  To allow non-standard discs to be edited, ARCTOOLS must first be told
  that the format is non-standard. Do this proceed as follows:

  1. Insert a known format disc in the required drive.
  2. Enter the disc editor.
  3. Remove the known format disc and insert the non-standard disc.
     At this time the sector content shown on the screen is still
     that of the previous known format disc.
  4. Press CTRL-SHIFT-I (Hold down CTRL and SHIFT keys and press I).
     A simple menu on the bottom of the screen is shown. This menu
     shows the previous disc format total tracks, sectors per track,
     sector size, total heads and disc density.
     Use the right and left cursor keys to move through the different
     parameters, and the Up and down keys to modify these parameters.
  5. Once you have setup the new format press the RETURN key. The disc
     will now be accessed using the format that you have just setup.


  Recovering deleted files using the Disc Editors:
  ================================================

  Unlike other filing system, the ADFS is one of the most difficult when
  it comes to recovering deleted files. Accidently deleting files is
  a common mistake many users do. On some filing system, for example,
  the DOS filing system it is much much easier to recover these files.
  The reason behind this is in the way the ADFS deletes the files.
  When you request a file to be deleted using the *Delete or *Wipe command,
  the ADFS removes the file name and its information from the directory
  space on the disc, then it returns the space allocated to it to the
  disc free space map so that this free space can be used for storing
  other files. The data in the free space is not destroyed as long as
  it is not overwritten by another file. What makes recovering deleted
  files difficult on the ADFS is that the file name and its information
  are wiped out. The DOS filing system, for example, does not wipe out
  the filename or its information data. It simply replaces the first
  character of the filename with a control code &E5.
  Given the above information it is impossible to write programms that
  provide facilites such as the 'UnErase' Norton Utility on DOS systems.

  Recovering deleted files on the ADFS is unfortunately a manual method.
  Geared with information on the lost file, the user has to search the
  disc to locate the start and end addresses of the file. On a disc with
  an E or F format, the file could be fragmented and its content is
  scattered all over the disc surface.

  ARCTOOLS provides the following manual methods:

  - You can search for a given string in the lost file. This speeds up the
    search process.
  - You can use the 'Nex Free Map' option. Using the CTRL-SHIFT-UP cursor
    or Down cursor, you can search for the deleted file in the free sectors.
    This is the place where your deleted file resides.
  - Once identified you can use the disc marks to mark the start and end
    addresses of the file, then copy this data to memory using the
    'Command menu'.
  - Once in memory the data can be saved to file using the 'Commands Menu'.

  With fragmented files, each fragment has to be saved seperately and then
  using the *Fjoin command the files can joined together (in the correct
  order).


  Writing back edited data:
  =========================

  When editing sector data, the data is written into a copy of the sector
  in memory and not immediately stored on disc. After a sector's data has
  been changed, moving onto another sector or track or exiting the editor
  will cause the message 'Save Sector [Y/N] ?' to appear. Pressing the
  'Y' key will cause the sector data to be written back to disc. Any other
  key will skip the sector saving routine.

  Errors when reading a disc:
  ===========================

  If errors are encountered when ARCTOOLS is reading data from a disc,
  an error message will be generated. The sector content displayed on the
  screen will be shown as a text message 'Bad'.



                     ============================
                          The commands Menu
                     ============================

The commands menu is built into all memory and disc editors. The menu
can be called by pressing the key combination CTRL+C providing both
memory marks (in the memory editors) or disc marks (in the disc editors)
have been set.
The commands menu shows a list of itmes which can be selected using the
UP and Down cursor keys.
The two memory marks are used for various operations. Some operations
require a third address, for example, the MOVE MEMORY command. The 3rd
address will be the current memory address before the commands menu
is entered. The 3rd address can be changed.
Some commands will execute when you simply hit the return key, for example,
the 'Wipe memory' option. Other options require a string or numbers to
be entered. In this case you should enter the required parameter and hit
return.
At any time while entering a value, you can use the UP and DOWN cursors
to ignore the current command and go to the next command or option.
The commands menu will be exited if you hit the Escape key, or after a
command is executed.

Commands menu options:
======================

 1. Move Memory:  Move address1 address2 to [address3]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    address3 is the current memory address. This can be changed.
    This will move the marked area to the address given in address3.

 2. Swap Memory:  Swap address1 address2 with [address3]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    address3 is the current memory address. This can be changed.
    This will swap the marked area with the area starting at address3.


 3. Wipe      : Wipe address1 address2 ? <Return to execute>
                Wipe current sector? <Return to execute>

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    Hitting the Return key will cause the area to be wiped clean.
    In the disc editors this menu option will wipe the current sector.

 4. Memory ---> File : Save address1 address2 filename: [_              ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    Enter the filename to save under, then press Return. This will save
    the content of the memory area as a 'Data' file.


 5. File ---> Memory : Load to address1 address2 filename: [_           ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command will load a file into the given memory area. If the file
    size is larger then the size of the memory area, then the following
    message will be shown:
    File too large by xxxx bytes. <Load/Insert> (L/I)?
    You are offered the option whether to Insert the file or to Load the
    complete file. Inserting the file into the given memory area will
    load only the part which will fit into the given area.



 6. Fill Bytes : Fill address1 address2 with bytes [_                   ]
                 Fill current sector with bytes [_                    ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command is similar to the *FillH command. You can enter the
    sequence of bytes (hex) to fill memory with.
    In the disc editors, this option will fill the current sector with
    a sequence of bytes.


 7. Fill Words : Fill address1 address2 with words [_                   ]
                 Fill current sector with words [_                    ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command is similar to the *FillW command. You can enter the
    sequence of words to fill memory with.
    In the disc editors, this option will fill the current sector with
    a sequence of words.

 8. Fill String : Fill address1 address2 with string [_                 ]
                  Fill current sector with string [_                   ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command is similar to the *FillT command. You can enter the
    string to fill memory with.
    In the disc editors, this option will fill the current sector with
    the given string.

 9. Fill Mnemonic: Fill address1 address2 with mnem. [_                  ]
                   Fill current sector with mnem. [_                    ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command will fill the given memory with the entered Mnemonic
    string.
    In the disc editors, this option will fill the current sector with
    the given mnemonic string.

10. Disc ---> Memory: Get disc address1 address2 to memory [address3]

    address1 and address2 are the start and end addresses of the Disc
    area set using mark1 and mark2 when in the disc editors.
    If the commands menu was called from a disc editor then address3
    will be the start of the memory area. If it was called from within
    the memory editors, then address3 will be the current memory address.
    This command will copy the disc area marked by address1 and address2
    to the memory area starting at address3.

11. Memory ---> Disc: Put memory address1 address2 to disc [address3]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    If the commands menu was called from a disc editor then address3
    will be the current disc address. If it was called from within the
    memory editors, then address3 will be the start of the disc area.
    This command will copy the memory area marked by address1 and address2
    to the disc area starting at address3.


12. Invert Memory: Invert address1 address2 ? <Return to execute>

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command will reverse the memory area when Return key is pressed.
    It is similar to the *Reverse command.

13. Label Area: Label area address1 address2 with [Label            ]

    address1 and address2 are the start and end addresses of the memory
    area set using mark1 and mark2.
    This command will auto label the area given in address1 and address2.
    Label names will start with the string 'Label', however this can
    be changed to any string. All labels will be counted from 0 and
    attached to label names. For example, Lable_0, Label_1, Label_2...
    If ARCTOOLS can not find any labels in the given area, the message:
    'No labels in this area' will be generated.


                         ====================
                         Keys used in Editors
                         ====================

ARCTOOLS EDITOR KEYS Summarys:
==============================

Escape                :Abandon current operation, return to last activity.
CTRL+Escape           :Exit the editor, dumping the current line to screen.
CTRL+B                :Enter BINARY editor
CTRL+H                :Enter HEX editor
CTRL+W                :Enter WORDS editor
CTRL+N                :Enter NUMBERS editor
CTRL+M                :Enter MNEMONIC editor
CTRL+T                :Enter TEXT editor
CTRL+Y                :Enter BYTEs editor

CTRL+J                :JUMP to branch-to address (MNEMONIC editor only)
CTRL+SHIFT+J          :JUMP to address in current memory address
                       or to address in current memory address plus offset
                       in Mark1 if Mark1 is set
CTRL+R                :Return to previous address
CTRL+G                :Goto address

CTRL+F                :Find data. Search for data in memory.
CTRL+Back space       :Continue search from current address
CTRL+SHIFT+Back space :Continue search from last found address
CTRL+TAB              :Toggle text search case sensitivity

CTRL+L                :Label the current memory address
CTRL+SHIFT+L          :Comment on the current memory address


CTRL+X                :Toggle top bit of ASCII codes
CTRL+P                :Dump screen to PRINTER
CTRL+D                :Toggle between Active and Passive screen DISPLAY

CTRL+S                :In BINARY editor: Toggle between 8 or 32 bit
                                         position count
                      :In NUMBERS editor:Change SIGN of number
CTRL+COPY             :Change Screen Information Bar.
CTRL+INSERT           :Change Data entry format
                      :In NUMBERS editor:Change number padding ASCII code

CTRL+keypad 1         :Set Mark No.1
CTRL+keypad 2         :Set Mark No.2
CTRL+HOME             :Goto Mark
CTRL+Delete           :Delete all marks

CTRL+C                :Enter Commands menu
CTRL+E                :Toggle between Memory and Disc EDITORS
CTRL+I                :Install new disc (DISC editors only)
CTRL+SHIFT+I          :Install user defined disc
CTRL+keypad *         :Enter *Command line

Right Cursor          :Move cursor one place right
Left Cursor           :Move cursor one place left
Up Cursor             :Move cursor up one line
Down Cursor           :Move cursor down one line

SHIFT+Right Cursor    :Move cursor to rightmost position.
SHIFT+Left Cursor     :Move cursor to leftmost position.
SHIFT+Up Cursor       :Move cursor Up 29 lines (one full screen).
SHIFT+DOWN Cursor     :Move cursor DOWN 29 lines (one full screen).

CTRL+Right Cursor     :In Memory Editors: Move cursor to rightmost position.
                       In Disc Editors  : Increment address by One SECTOR.
CTRL+Left Cursor      :In Memory Editors: Move cursor to leftmost position.
                       In DISC Editors  : Decrement address by One SECTOR.
CTRL+Up Cursor        :In Memory Editors: Go to start of previous memory
                                          page.
                       In Disc Editors  : Decrement address by One TRACK.
CTRL+DOWN Cursor      :In Memory Editors: Go to start of next memory page.
                       In Disc Editors  : Increment address by One TRACK.

CTRL+SHIFT+Up Cursor  :In Memory Editors:Go to start of previous memory area.
                       In Disc Editors  :Go to start of previous free disc
                                         space map area.

CTRL+SHIFT+DOWN Cursor:In Memory Editors:Go to start of next memory area.
                       In Disc Editors  :Go to start of next free disc space
                                         map area.


                   ARCTOOLS EDITORS KEYS description:
                   ==================================

Escape key:
-----------
The Escape key is used to abandon the current operation and return to the
last operation. Use Escape to:
 - exit the memory or disc editors, or
 - exit the commands menu, or
 - abandom any current operation.


CTRL+Escape (Exit the editor showing current address data on screen)
--------------------------------------------------------------------
Somtimes you may want to exit the editor after you have searched for
certain data. May be, you wanted to use this data in your BASIC program,
to do so, press CTRL+Escape keys, this will exit the current editor but
your data will be on the screen. Now you can copy it into a BASIC program
line or do some mathematical calculations on it using the BASIC
keywords.


CTRL+J  (Jump to address)
-------------------------
In the mnemonics editor, this key combination allows the user to perform
a "jump to address" which can be used to follow the structure of a
program. The address that the editor jumps to is the one at the current
cursor position and only when one of the following instructions is being
highlighted:

 B     {Address/Label}
 BL    {Address/Label}
 ADR   Rx,{Address/Label}
 ADRL  Rx,{Address/Label}
 STR   Rx,{Address/Label}
 LDR   Rx,{Address/Label}
 STF   Fx,{Address/Label}
 LDF   Fx,{Address/Label}
 STC   Cp#x,Cx,{Address/Label}
 LDC   Cp#x,Cx,{Address/Label}

Example of CTRL+J use:
----------------------
The following example allows you to examine the Operating System
Software Interrupt routine.

1. Enter the mnemonic editor at location &00000008 which is the SWI
   hardware vector by typing: *MEDIT 8 M
2. The instruction at memory location &8 is a branch instruction to
   the SWI decode routine. Press CTRL+J to go to the start of that
   routine.

Pressing CTRL+R will return you to the previous memory location where the
jump was made from. Jumps to addresses can be nested up to 255 jumps.
CTRL+J is only valid in the mnemonic editor. If you try to use it in any
other editor it will be ignored.

CTRL+R    (Return to last jumped from address)
----------------------------------------------
This key combination allows you to return to the last jumped from address.
A beep is emitted if their are no more return addresses.


CTRL+SHIFT+J  (Jump to word address)
------------------------------------
This key combination is only valid in the mnemonic editor.
This key combination allows the user to jump to a memory location which
is stored in the current highlighted memory location.
example: if the cursor is at the following location,

 01F033FC  .1..  03803104  ORREQ    R3,R0,#1

then pressing CTRL+SHIFT+J will cause the editor to jump to the memory
address at location store at &01F033FC which is in this case &03803104.

Another example:
The following example allows you to examine the Operating System SWIs
routines.
1. Enter the mnemonic editor at location &00000008 which is the SWI
   hardware vector by typing: *MEDIT 8 M
2. The instruction at memory location &8 is a branch instruction to
   the SWI decode routine. Press CTRL+J to go to the start of that
   routine.
3. Move the cursor down 15 lines to move to the start of the Operating
   System Software Instructions Jump Table.
   The table contains jump addresses for all SWI routines used by the
   OS Kernel, i.e. SWI 0 through &1FF
   Memory address &1F033FC contains the value &3803104 which is the
   address for the "OS_WriteC".
4. To jump to the "OS_WriteC" code which starts at &3803104, position
   the cursor to address &1F033FC, then ensure that Mark 1 is clear by
   pressing CTRL+Delete (See Offset Jumps). Once Mark 1 is cleared, press
   CTRL+SHIFT+J to jump to address &3803104. This is the 'OS_WriteC'
   Code.

Offset Jumps:
-------------
An additional feature of CTRL+SHIFT+J key combination is OFFSET jump.
The offset jump is automatically selected if MARK 1 is set. In this case,
before jumping to the address at current memory location, the editor will
add the address of MARK 1 to it.
This offset jump can be very helpful when examining module tables.
Example of offset jump:
The following example will take you the SWI handler code used in the
'PDriver' module.

type the following:

*medit 391773C M
This will enter Mnemonic Editor at start of 'PDriver' module.

Note: The 'PDriver' module start address can be obtained by using the
      OS command '*Modules'

Press CTRL+ Keypad 1  to set mark no. 1. Mark 1 would be set to 391773C.
Move the cursor down until address 391775C is reached. This address
contains the value &1B0 which is the offset from the start of the module
to the module SWI handler code.
To jump to the SWI handler code simply press CTRL+SHIFT+J. The editor
will add the offset value (&1B0) contained at current memory location to
the address value stored in Mark 1 and jump to the result address.


NOTE: The above example of CTRL+J and CTRL+SHIFT+J assume a RISC OS 3
      operating system is fitted on an A5000.


CTRL+G    (Go to address or label)
----------------------------------
This key combination allows you to move to another memory area very
quickly by giving the address or the label name. The given address
is assumed to be a hexadecimal number, any number base can be given.
ARCTOOLS remembers the memory address you have left, so to return to the
previous address after this command, press CTRL+R.


CTRL+F  (Find or Data Search)
-----------------------------
This key combination is used to locate data in memory or on disc.
The data type depends on the type of editor in use.
1. In the TEXT editor:
   Searches for a string. single wildcards are allowed
2. In the Binary editor:
   Searches for a binary number. single wildcards are allowed
3. In the Hex editor:
   Searches for hex numbers. single wildcards are allowed
4. In the Word editor:
   Searches for a word. single wildcards are allowed
5. In the Numbers editor:
   Searches for a decimal number. No wildcards allowed
6. In the Mnemonic editor:
   Searches for an ARM, FPU or CO-PRO instruction. No wildcards allowed

The search starts at the current memory address. Once data is found,
use CTRL+Back Space for the next match.
You can switch to a different editor and continue the search.


CTRL+Back Space (Continue search from current address)
------------------------------------------------------
Continues the search for the data from the current memory address.
The 'Back Space' key is located to the right of the Pound sign key.


CTRL+SHIFT+Back Space (Continue search from last found address)
---------------------------------------------------------------
Continues the search for the data from the last found address.


CTRL+TAB  (Toggle string search CASE)
-------------------------------------
Toggle between Case sensitive and case insensitive string search.
The CASE status can be viewed using the information title at the top
display screen using CTRL+Copy.
CASE: OFF  means case insensitive
CASE: ON  means case sensitive


CTRL+L (Label address)
----------------------
This function is only available in the Mnemonic memory editor.
Used to label an address of memory. The current memory address is labelled.
If the current address already has a defined label, then, when this function
is entered, the label name will be displayed at the cursor position so
that this can be changed or deleted.
Maximum label string length is 23 characters.

To delete a previously defined label you should press CTRL+L at the
current label address, then use CTRL+U or the delete key to remove the
label name, then press enter.

NOTE: Ensure that the assembler 'labels and remarks' flag is ON, so
      that the assembler can display any defined labels or remarks.

NOTE: If your enter a label name which is already defined, then that
      label name is removed and the current address is assigned to it.

NOTE: See the section on the Line Editor.


CTRL+SHIFT+L (Place a remark at an address)
-------------------------------------------
This function is only available in the Mnemonic memory editor.
The message 'Enter comment' will be shown at the current memory address.
Enter the remark or comment and press return.
A remark can be deleted by using CTRL+SHIFT+L on the remark address,
deleting the whole line, then pressing enter.


NOTE: See the section on the Line Editor.


CTRL+X    (Toggle ASCII top-bit)
--------------------------------
This key combinations is used to toggle the top-bit of ASCII characters
displayed on screen. With top bit clear, text strings are easy to read.


CTRL+P    (Print screen)
------------------------
Sends the contents of the screen to printer. All Ascii characters are
sent to the printer with their top-bit clear.
You should have your printer on-line before pressing CTRL+P.

NOTE: ARCTOOLS (current version) does not check to see if your printer
      is on-line. The program will hang if your printer is not on line.
      This is to be corrected in the next version.


CTRL+D    (Toggle Display type)
-------------------------------
Toggles between active and passive display. When the display status is
ON, the locations of memory are constantly read and updated on the screen.
This type of active display allows the user to examine memory locations
which are constantly changing.
The status of display is displayed at the top of the screen using CTRL+Copy.
For example, try to examine memory area starting at &9A8 with active
display switched ON.


CTRL+S
------
This key combination is only used in the Binary and the Numbers Editors.
In the Numbers editor: It is used to modify the memory content from a
                       a signed into unsigned number.
In the Binary editor : This is used to toggle between 32-bit or 8-bit
                       position count. The bit position count is
                       shown on the top right corner of the screen, so
                       that you can move the cursor to the required bit
                       position without having to count using your fingure!
                       This is normally 32-bit count (from 0 to 31), but
                       can be 8-bit count considering the 32-bit number
                       is split into four 8-bit bytes.


CTRL+Copy  (Information Bar display)
------------------------
Cycles through the information bar which is shown at the top of the screen.

In the memory editors the following information is provided:

1. ARCTOOLS Version number and author name
2. Current memory area name and its size
3. Current memory page information
4. Machine total RAM size, total pages and page size
5. Memory and Disc marks
6. Display status, case status, Top bit status and current editor type

In the disc editors the following information is provided:

1. ARCTOOLS Version number and author name
2. Drive information:
   -Current drive number and type (Floppy or Hard),
   -Current head number,
   -Current sector number,
   -Current track number,
3. Sectors information:
   -Total sectors per track,
   -Current sector number,
   -Sector size,
   -Sector start address
4. Tracks information:
   -Total tracks per head,
   -Current track number,
   -Track size,
   -Track start address
5. Drive information:
   -Total heads,
   -Total sectors per track,
   -Total tracks per head,
   -Density,
   -Root directory address
6. Drive information:
   -Disc name,
   -Disc ID,
   -Disc size
7. Memory and disc marks
8. Display status, case status, Top bit status and current editor type.


The Memory and Disc marks are automatically displayed if any marks is
set or the Commands menu is entered.


CTRL+Insert  (Data Input)
-------------------------
Selects the type of data input format used when editing memory or disc.
The Data Input depends on the editor type as follows:

Binary Editor  : Binary, Hex, Decimal, Text.        Default: Binary
Hex Editor     : Binary, Hex, Decimal, Text.        Default: Hex
Text Editor    : Text only
Words Editor   : Binary, Hex, Decimal, Text.        Default: Hex
Mnemonic Editor: Set or unset the current shown display format flag.
Numbers Editor : Numbers only
Byte Editor    : Binary, Hex, Decimal, Text.        Default: Decimal

In the Numbers editor CTRL+Insert is used to change the leading padding
character from zeros to spaces.


CTRL+Keypad 1 (Set Mark 1)
--------------------------
Sets Mark no.1 to the current memory address if in memory editors or
to to current disc address if in disc editors.
Mark 1 address is displayed on the top of the screen as "Memory: {address}"
or "Disc: {address}"

CTRL+Keypad 2 (Set Mark 2)
--------------------------
Sets Mark no.2 to the current memory address if in memory editors or
to to current disc address if in disc editors.
Mark 2 address is displayed on the top of the screen as "To: {address}"
or "To: {address}"


CTRL+Home (Go to set mark)
--------------------------
Pressing CTRL+Home keys will allow you to go to the address in the
set marks. First press takes you to mark1 address, the second press,
to mark2 address.


CTRL+Delete
-----------
Removes memory Mark1 and Mark2 if in memory editors.
Removes discs Mark1 and Mark2 if in disc editors.


CTRL+C   (Commands menu)
------------------------
Enters the commands menu.
The commands menu can be entered from any memory or disc editor providing
both memory marks are set. See the Section on the Commands Menu for more
details.


CTRL+E   (Toggle between Memory and Disc editors)
-------------------------------------------------
This key combination is used to toggle between memory and disc editors.
In any memory editor, pressing CTRL+E will enter the Disc editor on
the last disc address viewed. Pressing CTRL+E in any disc editor will
take you back to the last visited memory address. This provides a quick
method of switching between the different editors without having to
revert to the *Medit and *Dedit commands.


CTRL+I (Install disc)
---------------------
This key combination is only available in the disc editors.
This causes a new disc to be read by the editor. This allows the user
to examine a new disc without leaving the disc editor.
The editor will read information from the currently selected drive.


CTRL+SHIFT+I (Install user defined disc)
----------------------------------------
This key combination is only available in the disc editors. This allows
the user to install a disc with a format that he only knows. When
the key combination is used, the format menu is entered which contains
information on the previous disc format. The user can change this data
using the cursor keys. Pressing return will install the new disc using
the new defined format.


CTRL+Keypad * (Line command)
----------------------------
Enters the supervisor mode, so that you can issue *Commands.
Press Escape to return to the editor.
NOTE: You should not issue *Commands such as *Dedit or *Medit that cause
      the editors to entred. This re-entry will cause ARCTOOLS to
      loose track of data.


Right Cursor:
-------------
In the BINARY editor  : Move cursor right by one bit position.
In the HEX editor     : Move cursor right by one byte position.
In the WORD editor    : Move cursor right by one word (4 bytes).
In the NUMBER editor  : Inactive.
In the MNEMONIC editor: Show next display format flag status.
In the TEXT editor    : Move cursor right by one byte position.
In the BYTES editor   : Move cursor right by one byte position.


Left Cursor:
------------
In the BINARY editor  : Move cursor left by one bit position.
In the HEX editor     : Move cursor left by one byte position.
In the WORD editor    : Move cursor left by one word (4 bytes).
In the NUMBER editor  : Inactive.
In the MNEMONIC editor: Show previous display format flag status.
In the TEXT editor    : Move cursor left by one byte position.
In the BYTES editor   : Move cursor left by one byte position.


Up Cursor:
----------
This key is used to scroll the screen down. This decrements the current
highlighted address by:

In the BINARY editor  : 4 bytes.
In the HEX editor     : 16 bytes.
In the WORD editor    : 16 bytes.
In the NUMBER editor  : 4 bytes.
In the MNEMONIC editor: 4 bytes.
In the TEXT editor    : 64 bytes.
In the BYTES editor   : 8 bytes.


Down Cursor:
------------
This key is used to scroll the screen up. This increments the current
highlighted address by:

In the BINARY editor  : 4 bytes.
In the HEX editor     : 16 bytes.
In the WORD editor    : 16 bytes.
In the NUMBER editor  : 4 bytes.
In the MNEMONIC editor: 4 bytes.
In the TEXT editor    : 64 bytes.
In the BYTES editor   : 8 bytes.


SHIFT+<Right Cursor> (Move cursor to rightmost position)
--------------------------------------------------------
This key commbination is used to move the cursor to the right most position
on the screen. However, in the Binary editor its used to move the cursor
to the right by one byte (8 bits).


SHIFT+<Left Cursor> (Move cursor to leftmost position)
------------------------------------------------------
Move the cursor to the left most position on the screen. In the Binary
editor, this key combination is used to move the cursor to the left by
one byte (8 bits).


SHIFT+<Up Cursor> (Scroll down to previous screen)
--------------------------------------------------
This key combination is used to decrement the currently highlight address
by a value which depends on the type of editor;

In the BINARY editor  : 116 bytes.
In the HEX editor     : 464 bytes.
In the WORD editor    : 464 bytes.
In the NUMBER editor  : 116 bytes.
In the MNEMONIC editor: 116 bytes.
In the TEXT editor    : 1856 bytes.
In the BYTES editor   : 232 bytes.


SHIFT+<Down Cursor> (Scroll up to next screen)
----------------------------------------------
This key combination is used to increment the currently highlight address
by a value which depends on the type of editor;

In the BINARY editor  : 116 bytes.
In the HEX editor     : 464 bytes.
In the WORD editor    : 464 bytes.
In the NUMBER editor  : 116 bytes.
In the MNEMONIC editor: 116 bytes.
In the TEXT editor    : 1856 bytes.
In the BYTES editor   : 232 bytes.

This key combination together with CTRL+<Up Cursor> provide a quick way of
scrolling through memory.


CTRL+<Right Cursor>
-------------------
In the Memory Editors: (Advance cursor to most right position)

This provides similar results to the SHIFT+<Right Cursor), except that in
the BINARY Editor, it advances the cursor to the most right position on the
screen.

In the Disc Editors: (Next sector)

Provide sector increment facility. If the sector has been modified, you
are offered to save the sector back to disc before you go to the next
sector.

CTRL+<Left Cursor>
------------------
In the Memory Editors: (Advance cursor to most left position)

This provides similar results to the SHIFT+<Left Cursor), except that in
the BINARY Editor, it advances the cursor to the most left position on the
screen.

In the Disc Editors: (Previous sector)

Provide sector decrement facility. If the sector has been modified, you
are offered to save the sector back to disc before you go to the previous
sector.


CTRL+<Up Cursor>
----------------
In the Memory Editors: (Go to memory page start address)

This provides a jump to the current memory page start address. If you are
already at the memory page start address, then the previous memory start
address is jumped to. The page size depends on the total ram in the
machine. In a 1 Mbytes machine, this is 8 Kbytes. In a 4 Mbytes machine
or higher, this is 32 Kbytes.

In the Disc Editor: (Go to previous disc track)

This provides a track decrement facility.


CTRL+<Down Cursor>
------------------
In the Memory Editors: (Go to next memory page start address)

This provides a jump to the next memory page start address.
The page size depends on the total ram in the machine.

In the Disc Editor: (Go to next disc track)

This provides a track increment facility.


CTRL+SHIFT+<Up Cursor>
----------------------
In the Memory Editors: (Go to current memory area start address)

This key combination provides a quick and easy method of moving from one
memory area to another. In addition if you are in the Relocatable Module
Area (RMA) or in the ROM area, then this key allows you to move to the
start of the module code. If you are already at the start of a memory area
or the start of a module code, this key will take you to the start address
of the previous memory area or module code.

In The Disc Editor: (Go to start of previous free disc map area)

Provide a facility to quickly identify non used area of the disc. This
where deleted files can be found!


CTRL+SHIFT+<Down Cursor>
------------------------
In the Memory Editors: (Go to next memory area start address)

This key combination will take you to the start of the next memory area.
If the area contains modules, then it will take you to the start of the
next module. Using this key combination you can quickly browse through
all module without having to remember their start addresses.

In The Disc Editor: (Go to start of nex free disc map area)

Provide a facility to quickly identify non used area of the disc. This
where deleted files can be found!


                The dis-assembler (Mnemonics Editor)
                ====================================

This is the most powerfull memory editor provided by ARCTOOLS. It is an
essential tool when writing assembly code. The dis-assembler allows ARM,
FPU and co-processor instructions held in memory to be converted back into
the mnemonic form used by common ARM assemblers. The dis-assembler tends
to closely follow the BASIC assembler conventions.
ARCTOOLS does not use the built-in debugger dis-assembler SWI instruction
provided by RISC OS as this SWI has many limitations. ARCTOOLS provides
its own routines to disassemble ARM code.


The disassembler can be entered by typing:

*Medit <address> M     Enter the disassembler at <address>
*Medit <Label> M       Enter the disassembler at <Label>
*Medit M               Enter the disassembler at last visited address
*Medit                 Enter the disassembler at last visited address
                       if the disassembler was the last visited editor

or if already in any other editor pressing CTRL+M

Once entered, the disassembler screen contains one line per disassembled
instruction. Each display line contains five fields. The first field is
the memory address where the instruction is stored. This memory address
is always word aligned. The second field is the content of the memory
address in ASCII format. This is very useful, since some codes contain
text embedded between ARM instructions, an example is the OS SWI instruction
"OS_WriteS" which is always followed by a zero terminated, word aligned
text string. The third field is the memory word content displayed in
hexadecimal numbers. Not all assembly code is ARM or FPU instructions,
certain areas of memory contain data used as constants, data tables of
colour definitions, jump addresses as so on. In this case the third field
is the one of interest. The fourth and fifth fields are the data
interpreted as an ARM, FPU or co-processor instruction.
An instruction consists of two parts an OPCODE and an OPERAND. These
are fields four and five respectively.


The dis-assembler provides a large number of display formats which are
controlled by the user. The display formats are instant in effect.

How to change the dis-assembler display format?
===============================================

When in the dis-assembler, the display format flags are shown at the
bottom of the screen, only one flag will be shown at any time, to
display the rest of the options flags, use the right and left cursor
keys. This will cycle through the whole set of flags, showing the
option number, its purpose and its status, for example:

 0:[SWI numbers              ]:[OFF]

This shows flag no. zero, which is the SWI numbers flag. The [OFF]
indicates that its currently OFF. To switch to ON, press CTRL + Insert
key combinations. This will cause the 'SWI numbers' flag to become
active causing all SWI instruction names to be replaced by numbers.
The effect is instant re-disassembly of all the code on the screen to
reflect the new flags status.

There are currently a total of 18 flags (0-17), these are as follows:

 0: SWI numbers.
    ON : All SWI instructions are shown as SWI numbers.
    OFF: All SWI instructions are shown as SWI names. [Default]

 1: Shifted immediate numbers.
    ON : Immediate numbers are shown as number<<shift. [Default]
    OFF: Immediate numbers shown the normal way.

    This flag allows easy interpretation of instructions that try to
    set or clear certain bits in a number, for example, it is much
    easier when you see the difference between these two instructions:

    BICNE   R0,R0,#&8000000

    BICNE   R0,R0,#1<<27

    It is very clear in the second line that the instruction is trying
    to clear bit 27 of R0.
    This conversion is carried out only for numbers that are shifted by
    more than 3 places and are higher than 255.

 2: Immediate number ---> ASCII chars.
    ON : Immediate numbers shown as ASCII characters when possible.
    OFF: No ASCII character display. [Default]

    When set to on, this flag allows immediate numbers in the ASCII
    character set to be shown as ASCII characters. For example:

    MOV  R1,#65   becomes   MOV  R1,#ASC"A"


 3: FEDA stack type.
    ON : Use the Full/Empty, Ascending/Descending stack type. [Default]
    OFF: Use the Increment/Decrement, Before/After stack type.

    This flag is used to select between the two types of stack notations.
    This notation is used with the LDM/STM type instructions.

    The most common stack type notation used by programmers is the
    FEDA type, for example:

    STMFD  R13!,{R14}
    LDMFD  R13!,{PC}^

    Using the IDBA notation, the above two instructions will be shown
    as:

    STMDB  R13!,{R14}
    LDMIA  R13!,{PC}^

 4: PC relative Load/Store.
    ON : PC relative addressing notation is shown. [Default]
    OFF: PC relative addressing display switched off.

    When this flag is on, the following instruction:

    LDR  R0,[PC,#12], becomes   LDR R0,address

 5: SWI names quotes.
    ON : All SWI names are enclosed in quotation marks.
    OFF: All SWI names are displayed without quotation marks. [Default]

 6: HS/LO condition codes.
    ON : The CC and CS condition codes are replaced by HS and LO. [Default]
    OFF: The condition codes CC and CS are used.

 7: ADR directive.
    ON : The ADR directive is used. [Default]
    OFF: The ADR directive is not used.

    When this flag is on, any instructions which use reference to the
    PC with ADD and SUB opcodes together with immediate numbers are
    replaced by the ADR directive.

 8: LSL/LSR ---> */DIV.
    ON : LSL and LSR shifts are converted into * and DIV keywords.
    OFF: Shifts using LSL and LSR are displayed as normal. [Default]

    When on, this flag allows the display of instructions using the
    LSL and LSR to be shown as * (multiply) and DIV (divide)
    instructions. Examples:

    MOV  R0,R1,LSL #2     becomes    MOV  R0,R1*4
    ADD  R1,R2,R3,LSR #3  becomes    ADD  R1,R2,R3 DIV 8

    Remember that the single-line dis-assembler accepts these new
    keywords.

 9: Decimal numbers only.
    ON : All immediate numbers are shown as decimal numbers.
    OFF: All immediate numbers are shown in the default format. [Default]

    When on, this flag causes all immediate numbers to be shown as
    decimal numbers. This does not affect the the display of addresses
    used in instructions such as B and BL, as these are always shown
    as hexadecimal numbers.

10: Signed decimal numbers.
    ON : All decimal numbers are shown as signed numbers.
    OFF: All decimal numbers are shown as unsigned numbers. [Default]

    For this flag to be effective, flag no. 9 (Decimal numbers only) must
    also be on.

11: MVN/CMN/CNF ---> MOV/CMP/CMF.
    ON : Allow conversion of above instruction.
    OFF: Switch off conversion. [Default]

    When on, this flag allows the MVN instruction to be shown as MOV,
    CMN as CMP, and CNF as CMF. For example:

    MVN  R0,#1  becomes  MOV  R0,#-2
    CMN  R0,#1  becomes  CMP  R0,#-1

    Do not format to turn the 'Decimal numbers only' and the 'Signed
    decimal numbers' flags on to see the result in signed decimal numbers.

12: Co-processor instructions.
    ON : All co-processor instructions disassembled. [Default]
   !OFF: no co-processor instructions shown.

    This flag must be on to allow both the co-processor and FPU instructions
    to be disassembled.
    When set to OFF, all co-processor instructions are replaced by the
    message: "Co-processor instruction", including all FPU instructions.

13: FPU instructions.
    ON : All Floating Point co-processor instructions shown. [Default]
    OFF: No FPU instruction disassembled.

    To disassemble FPU instructions both the 'FPU instructions' and the
    'Co-processor instructions' flags must set to ON. If the 'FPU
    instructions' flag is set to OFF, then all FPU instructions will be
    disassembled as co-processor instructions.

14: Power multiply.
    ON : Use the 'power multiply' notation.
    OFF: Use normal display. [Default]

    When on, this flag allows the following conversion to take place:

    MOV R0,R1,LSL #1     becomes   MOV  R0,R1*2
    ADD R0,R1,R1,LSL #2  becomes   MOV  R0,R1*3
    RSB R0,R1,R1,LSL #3  becomes   MOV  R0,R1*7
    SUB R0,R1,R1,LSL #2  becomes   MOV  R0,R1*-3

15: Labels and remarks.
    ON : Allows any defined labels and remarks to be shown. [Default]
    OFF: Disables labels and remarks display.

16: Long ADR directive.
    ON : Disassembles the ADRL directive. [Default]
    OFF: Disables ADRL directive disassembly.

17: Show bad instructions.
    ON : Bad instructions are flagged. [Default]
    OFF: Bad instruction flagging disabled.

    Bad instructions are those which are (normally) not created by
    assemblers. They are normal instructions which the CPU will in
    many ways accept but have certain bit set or clear. ARCTOOLS
    defines the following as Bad instructions:

    1. Bad MUL: Bits set.

       This is a MUL or MLA instruction with either or both bits 5 and 6 set.

    2. Bad MUL: Rd=PC.

       This is a MUL or MLA instruction with the destination register equal
       to the PC (R15).

    3. Bad MUL: Rd=Rm

       This is a MUL or MLA instruction with the Destination Register set
       to the same number as the Rm register.

    4. Bad MUL: Rn set.

       This is a MUL instruction with bits 12 to 15, used only in the MLA
       instruction as the accumulate instruction number, not clear.

    5. Bad Comparison.

       This is a comparison instruction (CMP, CMN, TST or TEQ) with the
       S-bit (bit 20) clear. All comparison instructions must have the
       set condition code bit set to function as expected.

    6. Bad MOV/MVN.

       This is a MOV or MVN instruction, with any of bits 16 to 19 set.
       The MOV and MVN instructions do not have <Rn> register. The
       <Rn> register field must be zero.

    7. Bad shift.

       This is a shift operation of LSR or ASR with the shift number
       equal to zero.



Colours used in the dis-assembler:
==================================

The dis-assembler uses colors to provide an easy way of identifying
pieces of code or sub-routines.

The colors used are:

 - Orange :  Branch instructions and addresses.
 - Red    :  Undefined and Bad instructions.
 - Magenta:  Co-processor instructions.
 - Cyan   :  FPU instructions and ARM3 co-processor instructions.
 - Brown  :  STM and LDM instructions.
 - Yellow :  SWI instructions, labels and remarks.





                       The Single Line Assembler
                       =========================

The single line assembler is built into both memory and disc Mnemonic
editors or dis-assemblers.
To enter the single line assembler simply press CTRL+M when in any
of the other editors. This automatically selects the Mnemonic editor.
The editor in this mode will try its best to interpret the contents
of memory or disc and produce the corresponding instruction.
The Mnemonic editor or disassembler can disassemble all instructions.

There are 3 types of instructions:
1. ARM Instructions
2. Floating Point Instructions
3. Co-processor Instructions

The dis-assembler will disassemble all of the above types of instructions.
The Single-Line_Assembler will assemble all of the above instructions, and
hence it covers all possible instructions.

There are some Undefined instructions, and are at the moment of two types:

1. Undefined ARM Instructions
2. Undefined FPU Instructions

These are referred to by Acorn as Reserved or Undefined instructions.

There are no illegal Co-processor instructions. All 16 possible co-
processor instructions will be assembled and disassembled!!!

Co-processors are numbered 0-15. Number 1 being the Floating point
co-processor. Therefore, you can assemble FPU instructions using
co-processor instruction with the co-processor number set to 1 or
simply use the best and logical way: using FPU instructions.

This manual will not teach how to write assembly code. And the following
information assumes that you are familiar with both the ARM and FPU
instruction sets.

How to enter the Single-Line-Assembler?
======================================

In the Mnemonic editor by pressing the first character of your new line.
This causes the message "Enter Instruction:" to be displayed followed
by the character typed. You can now continue typing the instruction.
Pressing Return, Cursor Up or Cursor Down causes ARCTOOLS to assemble
the new line of code. If the line of code is acceptable the assembled
opcode is put into memory and the memory cursor advanced in a direction
determined by the terminating key.
If the terminating key was Cursor Up the memory cursor moves up. Return,
Enter or Cursor Down keys causes it to move down to the next memory address.


Small changes to existing code:
===============================

You may sometimes want to change only a small part of the Instruction
already displayed, possibly the condition code part or the "S" suffix.
To do so, press CTRL+Return. This will enter the Single-Line-Assembler
with the cursor position on the first character of the line. You can
now move the cursor left or right and modify the line.

Example:
Instruction at Cursor is:  MOVS PC,R14
Target Instruction is: MOV PC,R14
Action: Press CTRL+Return, move cursor right to the letter "S", press
the space key, Press return.

If the assembler could not assemble the code for any reason, an error
message is displayed for a short time (time delay can be overridden by pressing
the ESCAPE key). After this time delay, you are put back on the same
line of text you have typed with the cursor at the character which
causes the error. This makes it easy for you to identify the part that
caused the error. You can now correct the error or press Escape to exit
the Single-Line Assembler.

At any time, pressing the Escape key exits the assembler without assembling
the new line of code.

The single line assembler will ignore any irrelevant text or data after
the instruction. The exception is when assembling immediate numbers or
reference to addresses. This is because in these two cases the Operating
System 'EVAL' function is used which tries to evaluate the whole string
of text.




HOW TO USE THE SINGLE-LINE ASSEMBLER
====================================

The single-line assembler is compatible with the BBC BASIC's assembler.
There are however exceptions. Being only a single line assembler, you
can not use variables, except labels if already defined, as in a fully
blown assembler.
It can be generally said that any instruction that the dis-assembler
can display, the assembler will accept.
If you are familiar with any ARM assembler then you will find no problems
with this assembler.
The use of the FPU instructions is described in the Programmers Reference
Manual. The co-processors instructions set is describes in the excellent
book " ARM Assembly Language programming" by Peter Cockerell.


                   The Single-Line-Assembler Features:
                   ===================================
 1. Assemble all ARM instructions.

 2. Assemble all FPU instructions.

 3. Assemble all co-processor instructions.

 4. Text entered is case insensitive. (except SWI name).

 5. Automatic use of complement instructions:
    MOV  R0,#-1    will be assembled as  MVN  R0,#0
    ADD  R0,R1,#-2 will be assembled as  SUB  R0,R1,#2
    The complement instruction conversion will be carried out with the
    following instructions:
    MOV-MVN, BIC-AND, ADD-SUB, ADC-SBC, CMP/CMN
    The assembler will try to convert into a complement instruction if
    the immediate number can not be encoded into the instruction. If it
    fails the second time it will generate an error.

 6. Accepts PC-relative addressing.
    example:  LDR   R0,&20000
              STRB  R1,&21000
              STFS  F0,&10000
    The offset of the address given in the instruction should not be more
    than 4095 bytes from the current memory address for ARM instructions,
    and 1020 for FPU instructions. The FPU offset address must be word-
    aligned.

 7. Accepts the BBC BASIC's ADR directive.
    Limits imposed by the use of the ADR directive are the same as those
    in ARM BBC BASIC.

 8. Accepts the ADRL (long ADR) directive. Creating two instructions to
    cover an offset of 64 Kbytes.
    Note: An error message will be generated if you try to assemble the
          ADRL directive at the end of a memory boundary.

 9. Accepts the BBC BASIC's ASC keyword.
    example:SUB   R0,R0,#ASC"0"   equivalent to SUB  R0,R0,#48
            CMP   R2,#ASC" "      equivalent to CMP  R0,#32

            An alternative method is to omit the "ASC" word.

    Example: MOV   R0," "    equivalent to MOV  R0,#ASC" "
             MOV   R0,""     same as above
             MOV   R0,"""    equivalent to MOV  R0,#34

10. Accepts many forms of Software Instructions.
    Example: SWINE   "OS_WriteC"
             SWI     XOS_Write0
             SWI     0
             SWIPL   256+7
             SWI     "OS_WriteI"+7
             SWI     256+ASC"0"
             SWI     256+"0"
             SWI     2+1      equivalent to SWI  3
             SWI     OS_WriteI+ASC"a"
             SWI     256+""

  Note: There are Software Instructions that can not be assembled.
        They are:
        "User", "OS_Undefined"
        This is because, these two SWIs cover a wide range of SWI
        instruction numbers, and hence The Operating System can
        not tell which number you want.

11. Ignores irrelevant spaces in entered instruction.
    Example: MOVR0,R1           = MOV R0,R1
             ADDR2,R5,R3        = ADD R2,R5,R3
             andR3,R4,R2LSL#2   = and R3,R4,R2,LSL #2
    The exception is with the 'SWI' opcode as a space between the opcode
    and operand is necessary

12. Understands the following for register numbers:
    ARM Instructions         : (0-14,15|PC) or (R0-R14,R15|PC)
    FPU Instructions         : (0-7) or (F0-F7)
    Co-processor Instructions: (0-15) or (C0-C15)
    ARM3 co-processor        : (0-5) or (C0-C5) or register name:
                               ID, Flush, Control, Cacheable,
                               Updateable, Disruptive.

13. Uses the OS 'EVAL' function to evaluate integers, so any mathematical
    expression is allowed in immediate numbers.
    Examples:AND     R2,R3,#-2
             BICS    PC,R14,#1<<29
             ORREQ   R1,R2,#-1<<20
             MOV     R0,#NOT 1
             ADD     R3,R2,#30+4*25
             SUB     R0,R0,#1 OR (1<<5)
             SUBNE   R1,R2,#ASC"0"
             ADDPL   R2,R2,"a"

14. Understands power multiply instructions.
    Example: MOV  R0,R1*2    becomes   MOV  R0,R1,LSL #1
             MOV  R0,R1*3    becomes   ADD  R0,R1,R1,LSL #2
             MOV  R0,R1*7    becomes   RSB  R0,R1,R1,LSL #3
             MOV  R0,R1*-3   becomes   SUB  R0,R1,R1,LSL #2

15. Understands '*' and 'DIV' as alternatives for 'LSL' and 'LSR'.
    Example: MOV  R0,R1*4     becomes   MOV  R0,R1,LSL #2
             ADD  R0,R1,R2*32 becomes   ADD  R0,R1,R2 LSL #5
             MOV  R0,R1 DIV 8 becomes   MOV  R0,R1,LSR #3

16. Accepts labels previously defined in place of any reference to
    a memory address.


17. Assembles the new ARM3 SWP instruction.

18. Assembles the ARM3 cache control instructions.

The Single-Line Assembler conventions:
======================================

1. The instruction  STR  R0,[R1] is assembled into STR R0,[R1,#0]
2. The instruction  STR  R0,[R1]! is assembled into STR R0,[R1,#0]!
3. The instruction  STRT  R0,[R1] is assembled into STRT R0,[R1],#0


The single-line assembler errors:
=================================

 1. Unknown opcode
 2. Bad shift
 3. Bad multiply, <Rd>=PC
 4. Bad multiply, <Rn>=<Rd>
 5. Bad register
 6. Bad ASCII
 7. Missing ' '    : This is produced when an expected char is missing.
 8. Bad number
 9. Bad address/label
10. Can't encode number
11. Non aligned address
12. Bad operation
13. Bad immediate operand
14. No 'T' with pre-indexed or PC-relative addressing
15. Bad offset
16. Bad Co-processor operation
17. Precision needed



                    Calling the assembler from BASIC
                    ================================

 ARCTOOLS provides a single SWI which can be used from your own BASIC
 assembly code. This allows assembly of all FPU instructions, all
 co-processor instructions, the new ARM3 SWP instruction and all Cache
 control instructions, from within the BASIC assembler.

 To allow this you need to add a simple function in your BASIC program
 which will be called from within the assembly lines.

 Here is an example of the BASIC function:
 =========================================

 DEF FNass(A$)
 SYS "ARCTOOLS_Assemble",A$,P% TO !P% : P%+=4 : =TRUE


 The following is an example of the use of the cache control instruction
 assembly. Two routines are provided, one to switch ON the cache, and the
 other to switch it OFF.
 NOTE: The example given will only work on ARM 3 processors.

 DIM code 1000
 FOR pass= 0 TO 2 STEP 2
 P%=code
 [OPT pass

 .CacheON
 STMFD  R13!,{R0,R14}           ;Push regs on the stack
 MOV    R0,#3                   ;Value to write into cache control reg
 B      Do_It
 .CacheOFF
 STMFD  R13!,{R0,R14}           ;Push regs on the stack
 MOV    R0,#2                   ;Value to write into cache control reg
 .Do_It
 SWI    "XOS_EnterOS"           ;Enter SPV mode, so we can write to cache
 FNass(" CHSW  R0,Control")     ;Write R0 into cache 'Control' register
 TEQP   PC,#0                   ;Return to user mode
 LDMFD  R13!,{R0,PC}^           ;Pull regs and preserve flags
 ]
 NEXT
 END

 The above example demonstrates the use of ARCTOOLS single-line assembler
 from a BASIC program. Of course, any valid instruction that ARCTOOLS
 understands can be assembled. See above for full assembler syntax.
 There are however some limitations:

 1. You should not use variables when ARCTOOLS_Assemble SWI.
 2. You should not call the ARCTOOLS ADR directive with a label or variable.
 3. You should not call ARCTOOLS ADRL directive.



         Using the dis-assembler to recover lost source code files
         =========================================================

   This section will be given in detail in the next version of ARCTOOLS.
   If your are an experienced ARM programmer, you will have no problem
   using the dis-assembler together with the automatic labelling feature
   and the *Mdump command to get back your lost files.

   Next versions of ARCTOOLS will make the conversion process as
   intelligent as possible. This will include automatic Modules
   conversions. A simple of way of marking memory areas as Data items
   or strings, so that these will be converted into DCB, DCD or EQUS
   equivalents.

   The current version of ARCTOOLS allows the instruction "SWI OS_WriteS",
   when dumped to the screen to be followed by the string which would be
   printed. The string is shown in EQUS and DCB keywords, followed by the
   keyword 'ALIGN'.

                 ARM 3 instructions assembly and disassembly
                 ===========================================

 The SWP instruction:
 ====================

 The SWP instruction is used to swap a byte or word between register
 and memory. It is used as a form of LDR/STR in multi-processor installation.
 During the execution of this instruction, the bus interface LOCK signal
 is asserted so that other processors will not gain access to the bus.

 The instruction syntax is:

 SWP<cond><B>  Rd,Rm,[Rn]

 The SWP instruction performs the following operations:
 1. Copy the content of <Rn> address into <Rd>,
 2. Store <Rm> into <Rn> address.

 The SWP instruction is only executed in a supervisor mode.

 ARCTOOLS will assemble and disassemble the SWP instruction. Examples are:

   SWPNE   R0,R3,[R10]
   SWPB    R1,R0,[R2]
   SWPPLB  R0,R1,[R7]



 The cache control register operations:
 ======================================
 ARM 3 processors contain within them a cache memory. The cache caches
 virtually addressed data. For efficiency the cache does not cache
 everything. To control the various operations of the cache, 6 control
 registers are provided. These are:

 0 : ID register
 1 : Flush register
 2 : Control register
 3 : Cacheable register
 4 : Updateable register
 5 : Disruptive register

 The cache control instructions use the co-processor register transfer
 instructions (MRC and MCR instructions) with the co-processor number set
 to 15.
 Two instructions are provided to communicate with the cache registers;
 the MRC instruction which copies the content of the ARM register to the
 cache control register and the MCR which copies the content of the cache
 control register to the ARM register.

 ARCTOOLS can assemble and disassemble all co-processor instructions and
 hence communication with the cache can be performed using the MCR and MRC
 instructions. The MCR and MRC instructions syntax is very complex and
 difficult to remember, example:

 To read the cache ID register into R4:

 MCR  Cp#15,Op#0,R4,C0,C0,0

 this can be abbreviated into:

 MCR  15,0,R4,0,0,0

 However, ARCTOOLS provides a new instrcution syntax to handle these
 instrcutions.

 Instruction sysntax:  CSHR<cond>  Rd,Cx
 ====================  CSHW<cond>  Rd,Cx

 where:
       CSHR : opcode to read the cache register into ARM register.
       CSHW : opcode to write the ARM register into the cache register.
       Rd   : ARM register R0 - R15
       Cx   : cache control register C0 to C5.

 ARCTOOLS also understands cache register name so that:

 C0 = ID
 C1 = Flush
 C2 = Control
 C3 = Cacheable
 C4 = Updateable
 C5 = Disruptive

 Examples:
 =========

 CSHREQ  R4,C0                 ;Read cache ID register into R4.
 CSHR    R0,Cacheable          ;Read cacheable register into R0.
 CSHW    R7,Control            ;Write R7 into cache control register.

 Note: The cache control insructions are only executed in supervisor mode.
       In other processor modes, these instructions will fail as 'Undefined
       instructions'!!