

                  ARCTOOLS version 0.72 (Public Domain)
                  =====================================

                 Written by Mohsen Alshayef, 27 Oct 1992

                          Mohsen Alshayef 1992

     ***************************************************************
     *                                                             *
     *            You need RISC-OS 3 to run ARCTOOLS               *
     *                                                             *
     ***************************************************************



The following files should be in the !ARCTOOLS application directory:

1. ARCTOOLS     : ARCTOOLS module code.
2. Manual       : ARCTOOLS user manual. (Text file)
3. ReadMe       : ReadMe file (this one). (Text file)
4. Licence      : User licence

Quick familiarization:
======================

Double clicking on the !ARCTOOLS icon will load ARCTOOLS module into the
RMA. ARCTOOLS is then active until killed.

For a quick summary of all commands provided, type:

 *Tools            for a list of all ARCTOOLS commands.
 *Tools G          for a list of all ARCTOOLS general commands.
 *Tools M          for a list of all ARCTOOLS memory commands.
 *Tools D          for a list of all ARCTOOLS disc and files commands.

The memory and disc editors in ARCTOOLS outperform those in any utility
ever written for the ACORN machines. You only have to use them for half
an hour, and I guarantee you that you will throw your old memory and
disc editor utilities away.

If you are familiar with memory or disc editors then press F12 and type
*Medit. You will be surprised for what you get!!!! But you will only
appreciate the power of ARCTOOLS once you have read the 'Manual' text
file. There are so many facilities provided that it is best to print
the file 'Manual' provided in the !ARCTOOLS directory for easier cross
reference.

Read the file 'Manual' for a complete (I hope) coverage of all the commands
and facilities.

I hope you find ARCTOOLS most useful for your needs. Please send me any
comments or suggestions. Address is in the file 'Manual'.


ARCTOOLS requires RISC OS 3 or higher to operate properly. This is due to
the use of some of the new SWIs provided in RISC-OS 3.



                   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                   !                               !
                   !           H E L P             !
                   !                               !
                   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


 -  Although I have tried my best to make ARCTOOLS compatible with
    RISC OS 3, I still havn't exploited the full features of RICS OS 3
    due to the lack of the new Programmers Reference Manuals. Some of
    the new RISC OS SWIs and their parameter passings were discovered
    using ARCTOOLS itself.

 -  I have allowed the user of ARCTOOLS to get access to the I/O memory
    space. This used to cause problems on my A310 with RISC OS 2. It
    does not seem to do so on my A5000 RISC OS 3. I don't know if this
    is due to the new Operating System, the ARM processor difference, or
    the hardware difference.
    I can not test this with different hardware. Please send me the result
    of scanning that area on different machines, with say podules fitted.
    If there are serious problems, I will have the access to that area of
    memory made optional in next versions of ARCTOOLS.

 -  ARCTOOLS have not been tested on a machine with 8 Mbytes and higher
    of ram. I would like to know, how it behaves. How many Mega bytes does
    the *Mmap command report? How many pages are reported by the *Mpage
    command? Do the memory editors work properly?

 -  ARCTOOLS has been tested on an A5000 machine with 4 Mbytes of ram,
    one floppy drive, one 120 Mbytes IDE hard disc, and without any
    extension modules attached. If you have a machine with different
    specifications and you are experiencing difficulties, please contact
    me so that I'll be able to update ARCTOOLS coding.

 -  I was hoping to include ARM 6xx assembly and dis-assembly in ARCTOOLS,
    but because of the lack of information I am unable to do this at the
    moment. If you can provide such information, you will have a copy
    delivered to your door of every new ARCTOOLS version.



Current known Problems with ARCTOOLS (To be removed in next versions)
=====================================


 1. When using any output re-direction with ARCTOOLS commands, for example,
    *mdump, *system, *event, *vector or *fdump, you will find that the
    text output is oddly formatted. This also occurs if any of the above
    ARCTOOLS commands is issued from within the desktop Task Window. The
    reason for this is that these commands use the OS OS_Byte 134 to read the
    current text cursor position. OS_Byte 134 returns a value of 0 for the
    current X position of the text cursor if the output is re-directed. This
    seems to be a bug of the Operating System, not ARCTOOLS.

 2. The current version of the disc editor can only remember one disc
    drive. When switching between the memory and disc editors using the
    CTRL+"E" key combination, the drive accessed is drive 0. This is because
    ARCTOOLS remembers the last drive it used in the disc editors. Use
    *Dedit 4, to access the hard disc, sbusequent editors switching will
    automatically access drive 4.

 3. When in the disc editor, if the disc is changed, ARCTOOLS knows about
    this whenever you use any of the disc operation. ARCTOOLS will give
    the error message 'Disc changed' then it will read the new disc
    sector data at the current address. A bug exists which causes subsequent
    operation to give 'Disc changed' error message although the disc has
    already been identified.
    To prevent this, any time you change a disc while in the disc editors,
    you should use CTRL-I to install the new disc so that ARCTOOLS forgets
    about the previous disc.

 4. The CTRL-P key combination used to send the screen output to
    printer does not check to see if the printer is on-line. This can
    cause the machine to hang.

 5. The FPU CMN and CMNE instructions will not automatically do complement
    translation. This is a very minor limitation which I will be looking
    into in the next versions.

 6. The 'search Mnemonic' in the mnemonics editor (dis-assembler) can not
    properly find any of the following instructions:
     1. LDR|STR  Rx,<address>
     2. LDM|STM  Rx,<address>
     3. LDF|STF  Fx,<address>
     4. LDC|STC  Cx,<address>
     5. ADR      Rx,<address>
     6. ADRL     Rx,<address>
    This is due to the offset address calculation required. This requires
    a different search routine. The routine is already included for the
    search of  Branch instructions, future versions will extend this
    routine to include all the above instructions.

 7. The search routine does not search physical RAM area if it was
    started in a logical RAM area. To search in physical RAM you simply
    start the search in the physical ram area. This is not really a bug,
    it is just how I wanted it to be. If you started the search in logical
    memory then there is no need to search in physical ram as they both
    contain the same data. However some logical ram pages can be hidden
    by other applications which you will not be able to access. Using
    the search in physical ram will then allow you to find what you are
    looking for.



Future features to be incorporated in ARCTOOLS:
===============================================

 1. Full support of all operating system disc and drive types in the
    disc editors.

 2. The disc editors will support automatic switching between drives,
    so that you can switch between drives with the press of a key.

 3. Full support of RISC OS 3 features.

 4. Automatic labeling of modules with suitable names and adding comments
    to modules entry addresses.

 5. Adding a *History command, and an improved line editor. Part of the
    line editor code is already used in ARCTOOLS.

 6. *Dlock command will have options to lock only specified drives.

 7. Many additional options will be added to the Commands Menu.

 8. Improved machine index computation to cover memory, processor and
    drives tests.

 9. Neat ways of entering and exiting ARCTOOLS editors from desktop.

10. Add a new *command to append labels files to existing labels in
    memory.

11. Add a printer on-line check.

12. Add a facility to allow entering hex numbers in the WORD editors
    using a normal input routine.

13. Allow the size of ARCTOOLS buffers used for storing tables to be
    specified by the user.

14. Multiple wildcards will be allowed in the memory and disc string
    search routines.

15. The *System command will be extended to show other system related
    parameters.

16. Assembly and disassembly of ARM 6xx processors instructions.





 Good Luck and Happy Programming.



                  ARCTOOLS is   Mohsen Alshayef 1992

                  This version, 0.72 is public-domain

