Monitor release version 1.00 ___________

        *** Monitor 1.00 30-Nov-1992  Steven Kramer ***
        At the time of writing I was in rather a hurry (and cold), so
        minimal documentation is provided here. More to follow later.
        
        I can be reached for anything relating to this package (and more)
        by (e)mailing me: 

        Steven Kramer
        Hoogte Kadijk 21-BII
        1018 BE Amsterdam
        (Netherlands)

        e-mail: kramer@ohm.phys.uva.nl
        

Copyright notice________________________
(Well everybody has one, and I want one too)

        The Monitor program consists of this file, and all the files in
        this directory.
        This program, and everything in it, is  Steven Kramer. However,
        copies of the program may be made freely on these conditions:
        1) The files in the program may never be distributed seperately.
        2) This program may never be copied or distributed if it has been
           modified in any way.
        3) This program may not be part of a commercial or promotional
           package without the written consent of the author.

Please note I do not object to modifications, but the modified program may not
be distributed anymore. If you think your modification is useful please send
me the updated files.



Money matters___________________________

Yes, I would very much appreciate it if I would get any money from users of
this program. Why would you do THAT?

- I started this program about one year ago. I wrote it entirely from scratch
(and all in BASIC and assembler, so no easy C libraries). This brings me to the
following point. The program is decidedly illegal in trapping errors, because
at the time of writing I had no documentation at all except lots of magazines,
so two Acorn User articles on the window manager was about it. Why is everything
from Acorn (like the Programmer's Reference Manuals) so expensive? Then again,
to Acorn's credit, I think the flexibility and user friendliness of RISC OS are
proven by the existence of this program (remember the 'without documentation'?)

- I think this program is useful for any programmer, from beginners to experts.
So think about this, when you all are using it: How long would it take you to
come up with something similar?

- I would like to think that some people actually appreciate this program, so I
did not spend all the time (which was a lot) on it just for my own little
utility. This will, of course, also give me some motivation to keep updating
the program.

- You. A point about you. First of all, this program is NOT shareware. What I
mean by that is that I don't make registration compulsory in any way. If you
do not use this program more than once every aeon, why would you spend any money
on it? But if you use it a lot, it might actually be fair to send me some money
for doing all your work...

So register yourself! This means sending me a small amount of money (it's up to
you how much a small amount is, but do not make it too small) which entitles you
to the new versions (i.e bugfree) and better documentation when they appear.
This will also give you a slightly cleaner conscience (needed to advance in the
evolution of your cosmic being).

And if you think that I must think a lot of this program to have the nerve to
ask for money... you are right, I do.



About the program_______________________

        Monitor allows you to disassemble/assemble/search/execute
        machine code programs. Two modes are provided for a program,
        internal and external. In external mode the unpaged memory
        can be examined (e.g. RMA, ROM), in internal mode a file is
        loaded in a Wimp memory slot. Monitor allows you to open
        windows on this program containing either a hex-dump or the
        disassembled listing. The file can be edited by entering new
        instructions or typing new data. By setting the environment values
        a program can be 'soft' relocated, i.e. ADR instructions and
        relative STR/LDR's will be relocated. This also affects the
        assembler.


Disassembler____________________________

        Not too much to say about this. Shows the program listing,
        allows you to open new windows by double clicking on B[L] or ADR
        instructions.
        
Options Word value - show instruction's word value.
        Address offset - Off:all relative addressing replaced by ADR
        Caps on - display in capital letters

Notes   Doesn't allow for coprocessor instructions.
        Does a whole lot of other things I can't remember.


Assembler_______________________________

        Allows you to edit programs. All 'standard' keypresses have the
        usual effects. Also allows you to automatically relocate the
        program when inserting a new instruction. Escape restores the
        original text.

Options Insert - Toggles insert/overwrite mode for text
        Auto relocate - relocates the program after pressing Return
        Clear new line - clears the instruction text after Return

Notes   Doesn't allow for coprocessor instructions at all.
        Automaticallly swaps registers in illegal multiplies.
        Recognises 'PC' for R15, and ADR pseudo-instruction.
        Lots more uninteresting things. (like SWI names or numbers)


Find____________________________________

        Allows you to search for certain (combinations of certain)
        instructions. Use by setting the search mask in the instruction 
        windows -accessed from the Find menu (press F1)- and pressing the
        Find button. Now the find window will be opened showing all 
        occurrences of the Find instruction. Open the find options window,
        by setting the region value you can specify how much instructions
        'above' and 'below' the found instruction will be displayed. Now
        enter a new Find pattern and press the XRef button. The region will
        be searched for the new pattern.

Options Word value, address offset, Caps on - see Disassemble
        Blank line - insert a blank line between regions
        Region up, down - see above

Notes   Double clicks open code windows on the instruction.
        Searches for ADR's and PC relative STR/LDR's can be done by
        entering a numeric value in the LHS register list.
        No more than 256 occurrences.
        Weird things will happen when you change the environment.
        And yes, you are right about the coprocessor. It's not.


Execution_______________________________

        This is the most inconsistent part of the program. It is utterly
        unreliable, so be warned! It allows you to execute (parts of) the
        program, in normal or step mode. What happpens is this:
        
        Normal:
        All the registers will be filled with the values from the register
        list window whose buttons are set. The program branches to the
        address in R15, with all processor flags set according to the
        switches. Control is returned when one of the hardware vectors is
        called (i.e. branch through zero, address exceptions) or directly
        by jumping to the return address. If a button is not set for a
        register it will not be updated, and not be filled on entry. For
        three registers defaults will then be used:
        R13 --> points to a 1024 byte full down stack
        R14 --> points to the return address
        R15 --> points to the first instruction
        
        Step:
        Essentially the same procedure as above, except each instruction
        will be executed by the program, and not the ARM. This allows you
        to execute a limited number of steps (0 means continous run), to
        run programs that are not relocatable and to stop the execution at
        a certain point (see the breaklist) or in a certain area. Execution
        can be stopped by pressing Escape. Everything that has been said
        about normal execution also holds for step execution.
        
        Execution output can be saved in two ways, the first (grab vdu)
        intercepts all OS_WriteC calls and buffers them. The second tries
        to grab the end result (i.e. when the program retakes control) as
        a sprite. The buffer is grabbed from the Wimp pool.

Options Lots...

Notes   You are not allowed to set r13_Sup, r13_IRQ or r13_FIQ from the
        register list.
        Step mode is always executed in USR mode...
        ...so no register banking
        One exception is made in step mode (see also 'special hacks'), in
          that SWI instructions are carried out literally for speed. This has
          its consequences though!


Things that don't fit___________________

-->     Save from code window --> Code saves the code as a memory block
                              --> Text saves the code as a source file

-->     The data window allows --> F4 (or select from menu) text search
                               --> Higlight + inverse video display of
                                   control characters only in <256 colours.


Special hacks___________________________

        For all the incredibly intelligent programmers out there...
        Because SWI's are executed as pure instructions there is a problem
        with relocatability. For instance, what happens with OS_Write0, which
        gets passed a relative address in R0? The answer is simple, it fails.
        I have tried to solve this by allowing any or all of the registers to
        have its value transformed to the absolute value. See the file SWIlist
        for examples, but note that registers are modified again on exit!
        There is however one more problem with SWIs... Yes, it is the elusive
        OS_WriteS. There is no way this could be implemented except for writing
        your own routine, which is exactly what has to be done. See the file
        GenSWI for information on how this is done. Note that any changes to
        SWIList and GenSWI have to be made permanent (in the file SWITable) by
        running GenSWI.



Copyright notice________________________
(Well everybody has one, and I want one too)

This program, and everything in it, is  Steven Kramer. However, copies of the
program may be made freely on these conditions:
1) This program, and all the files in it, may never be distributed seperately.
2) This program, and all the files in it, may never be copied or distributed
   if they have been modified
3) This program, and all the files in it, may not be part of a commercial
   or promotional package without the consent of the author.




Things that don't even have the slightest bit to do with the actual program

Things done since ...
     v0.00 Basically written the entire program
     

Things to do (maybe, order of likeliness)
     Get rid of loading so many windows
     ---> At present you can't have more than two Monitors running, the window
          count is about twentyish. This will happen when I get the Interface
          thingy.
     Allow non-relocatable code to run
     ---> Either by creating a new shell, and moving the program to the new
     environment or maybe simpler just by paging memory with the MEMC.
     
     Implement register banking in step mode
     ---> Not hard, but a lot of work and little reward
     
     Step SWIs
     --> Simple actually, especially when the register banking is done.
         A lot of SWI's still will give a lot of trouble I am sure.

     Multiple files in memory

     Receive some money

Recommended cd : The Geto Boys - The Geto Boys
     And remember, the Dutch invented the CD, so I should know!
