Below is Theo's original !Help file for bit !ARM_Debug Risc OS application.

I have updated !ARM_Debug to run on 32-bit ARM processors (e.g. RPi4) and
Risc OS 5. My notes can be found in the ReadMe file. I have corrected some
formatting and some grammar in this !Help file, although the following is
largely as written by Theo around 2002.

Theo has granted permission to me to make !ARM_Debug available to RO5 users.                    

Note: my goal has been to use Theo's code wherever possible (Theo is a better
ARM coder than me! - so that's a given). I have not yet attempted to add
new Arch32 processor functionality apart from the MSR and MRS instructions.
This means that !ARM_Debug currently works best for porting old 26-bit Risc
OS 2,3,4,6 code to 32bit Risc OS 5. 

Some newer 32bit instructions should work, as !ARM_Debug is mostly running each
instruction one-at-a-time on the RPi ARM processor but at a different PC address,
effectively in a sandbox. Depends partly upon the !ARM_Debug instruction decode
logic.

Ralph Barrett 05Oct2025.

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

                            ARM_Debug v1.33 (PD)
                            --------------------
                        Author: Theo v/d Boogaert
                      -----------------------------

This program is freely distributable as long as you don`t make any money out
of it, and as long as you include all the files unaltered.  This program is
supplied "as is".  I take no responsibility for any damage or loss of data
caused by the use of this program.

What is !ARM_Debug ?
------------------

-Single/multistepper for ARM machine code.

-Debug/edit (directly) applications and RAM modules

-Debug/edit files and ROM modules

-Places breakpoints in applications and RAM modules (User and SVC mode).

-Trap SWI calls (before or after execution and in User and SVC mode).

-Trap OS commands.

-Interrupt code that lock up your machine: ctrl/shift and keypad -  

-After a break or a trap, you can single-step through the code and all the
 registers and flags will be updated after every step.

 The flags and registers can be changed.

 After you quit the single-stepper the machine code will continue from the last
 step, with the last flags and registers.

-You can place a swi call in your source file which, after execution,
 interrupt the program with the last flags and registers (User and SVC mode).
 And again after quitting the singlestepper, your program will go on from the
 last step. The swi call is: SWI "OS_BreakAddress"
      
-Record all the steps (inc. registers and flags), which you canexamine afterwards.
 
-There is also an *STEP <address> command

-AND... a lot more.

History
-------

I wrote this program because I missed EXMON (you know that program in the
early 80s for the Beeb) for my Archimedes 310.

Originally this program worked only on an ARM2 and ARM3 machine.

After I bought my StrongARM RiscPC, I updated !ARM_Debug and now it works
well in 26bit SVC and 26bit USER mode, which is in most programs the case.
Because I'm almost the only user, I decided to write a small help file and to
distribute !ARM_Debug

How to start
------------
Start !ARM_Debug in a similar way to other RISC OS applications, by
double-clicking on its application icon. When it has loaded, it
will install itself on the iconbar and a rom module will be loaded.
In this rom module you'll find the monitor programme (Singlestepper).

The Iconbar menu
----------------

Click with the menu button on the ARM_Debug iconbar icon.
This will open a menu with the following items:

Info               This shows information about the programme.
----
Extend File        Only accessible if a file or a ROM module is loaded,
-----------        If !ARM_Debug has loaded an application or a RAM module,
                   then it's not possible to add bytes to them. 
                 
Read               Applications, Modules and Memory
----               When you clicked on an application, the complete wimpslot or module becomes
                   visible in a window.
                   
                   It's possible to edit the data in this window or place a breakpoint in it.
                   All the data, that has been changed when there is an application or RAM
                   module loaded, is write back directly in the original wimpslot or RAM module.

New                Gives the memory back that has been claimed from RISC-OS
---
Options  Offset   With this option the startaddress, in the main window, can be changed from a
----------------   file, application, RAM or ROM module.
Options  Colours  Here the colours from the main window can be changed and saved.
-----------------  There are also two screen modes to choose, for the singlestepper to work in.

Trap  SWI Call    Trap SWI calls.
---------------    
                   The following writable icons can/must be filled in:

                  - SWI (Number):
                     Here you fill in the SWI call that has to be trapped, the next lines are
                     valid:
                     - SWI Wimp_Initialise
                     - SWI "Wimp_Initialise"
                     - Wimp_Initialise
                     - 400C0

                  - Break options
                     Here you can choose if an swi call will be trapped before or
                     after the execution

                  - Check Register(s):
                     Mark the first icon and fill in the register (R) and data (&)
                     ARM_Debug interrupt the SWI call only, if the register, data and SWI are
                     all equal at the moment a SWI call has (or will be) executed.
                     When the second icon has also been marked then there will be two registers
                     that will be checked.  (AND/OR)

                   Click on OK (or press RETURN) to confirm
                   Click on CLEAR to reset all the data
                           

Trap  Oscli       Any OS command can be filled in (without the "*") for example:
------------         - Help
                     - cat
                     - .
                     
                   Click on OK (or press RETURN) to confirm
                   Click on CLEAR to reset all the data
                   In this program it's not possible to trap a SWI call and OS command at the
                   same time. If a SWI call is set then the OS command will be reset.

Quit               Return to calling code (if you are very lucky - RGPB).
-----



The Main window menu
--------------------

Start !ARM_Debug and load a application, file or module.

A window will appear, the main window.

Click, in this window, on the middle mouse button an the next menu items will appear:

Edit  Word                        Find  Word
-----------                        -----------
Edit  Byte                        Find  Byte
-----------            AND         -----------              AND    GOTO
Edit  Mnemonic  Off              Find  Mnemonic                 ----
--------------------               ---------------
Edit  Binary                      Find  String
-------------                      -------------

The above menu items are all straight forward, they do nothing more then they seposed to do.

Swap               If you change any data in the main window then the ASCI field on the right
----               side from this window is changing to. With the swap option the caret goes
                   from the data field to the ASCI field, and back again.

Markers            It's possible to set a total of three markers.
-------            They mark the address that has the caret, with F9, F10 or F11
                   After you press F9, F10 or F11 you go back to the place the marker was set.

Save               Here the file or module can be saved. But when a application has been loaded
----               then this option is not available.

BreakPoint         When you've loaded a application or rammodule then, with this menu option,
----------         you can interrupt any machine code when the processor executed the address
                   where the breakpoint has been set.
                   
                   The next writable icons can/must be filled in:

                    -Address:
                     This is the address where the interrupt begins.
                     When the main window has the input focus, then the address that has the
                     caret is filled in.
                     Otherwise you must fill in this writable icon by hand.

                    -BreakPoint Info:
                     If there is a breakpoint set, then this icon shows the address and the
                     instruction that belongs to this address.

                    -Break always:
                     When the  processor has reached the break address and this option is on, 
                     ARM_Debug interrupts this program always.

                    -Break only if:
                     Click on this option and ARM_Debug interrupt only then, when at the moment                      that the break address will be executed, the register and his contents are                      equal to the values that are filled in.

                     e.g. Place a breakpoint right behind a Wimp_Poll instruction.
                     Fill the writable icon "R" with 0 and the icon "&" with 6.
                     Now the application stops only then, when at the time from executing the
                     instruction after the Wimp_Poll instruction, register R0 has the value 6.

                    -Clear:
                     Reset the break address.

Select (and Save)  With select, a selection from the data in the main window can be saved. Just 
------             fill in the begin and end address.

Addr Info          Gives some information about that address that has the caret.
---------

S/M Step           When you enter this option the following will happen:

--------           Arm_debug starts a new application from the same size as the wimpslot or file
                   length from the programme in the main window.
                   
                   It copies this program in the new application and starts up the
                   singlestepper.
                   
                   All the registers and flags starting at zero except R13. For this a small
                   stack is reserved.
                   
                   The singlestepper begins at the address that you filled in at the writeable
                   icon.
                   
                   All the data that you or the application has been changed during the
                   singlestep mode have no influence on the original file or application.


The Singlestepper  The singlestepper takes over the whole machine. The main reason for that is
-----------------  because when there is a break in a application or a ram module (from a
                   breakpoint or a OS_BreakAddress instruction) the singlestepper can not
                   handle instructions step by step in a multitasking environment.  

                   Start up the singlestepper and on top off the screen you'll see a part of
                   the code from the main program.
                   
                   On the left side the address, then the value from that address (in words)
                   and the mnemonic that belongs to it.
                   
                   Almost every option can be used with the mouse or with function keys.

Data actions       Dragging with MOUSE SELECT:
------------
                       From:         TO:                 -- RESULT:
                   1.  Address  to   register
                   2.  Address  to   green address field -- go to
                   3.  Address  to   R15 (PC)            -- change execution address
                   4.  Register to   green address field -- go to
                   5.  Register to   register            -- change value from destiny register
                   6.  Register to   R15 (PC)            -- change execution address
                   7.  Words    to   Registers  
                   8.  Words    to   R15 (PC)
                   9.  Words    to   green address field
                   10. Address  to   "Break" button      -- set a soft breakpoint
                   11. Register to   "Break" button

                   Clicking with MOUSE SELECT on:
                   1e: ADR, B/BL, LDR or STR instruction -- follow the destination address
                   2e: Flags                             -- Toggle flags on/off
                   3e: Arrows                            -- Yes.

                   Clicking with MOUSE ADJUST on:
                   1e: Green address field               -- go to
                   2e: Words                             -- edit the value from that word
                   3e: Registers                         -- edit the value from that register
                   4e: R15 (PC)                          -- change the execution address

                             ********** Tool Actions **********

Calc.              Behind this button you'll find a simple calculator.

-----              Insert a string (decimal, hexadecimal(&) or binary(%) to evaluate, the
                   result is given in hex. and decimal.
                   
                   When you insert a "@" sign before the expression, the result is shown in
                   binary.
 
Record             With this button the addresses, mnemonics and registers, that has been
------             executed, can be saved to a file.

                   The name of this file can be filled in to the writable icon.
                   Normally this file is created in the root from your current filing system,
                   but it can be changed by editting the Trace$Address in the !Run file.
                   
                   Click on the Options button and the option window appears
                   At first only the addresses are send to the file, but by clicking on the
                   Mnemonics and Registers buttons, the executed mnemonics and the registers
                   will be saved also to this file. Clicking on the "Text or data" button
                   affects the way the data is stored to disc. As text the stored data can be
                   loaded in any text editor, as data the file can be loaded in ARM_Debug by
                   dragging the special data file to the iconbar or by doubleclicking on it.
                   
                   Following no longer true. (Text output is now implemented for RO5 RGPB).
                   It's not possible to store the data as a textfile with all the three 
                   buttons activated. This is because the saved file will become very large
                    
                   The last icon is writable and handles the maximum file length.
                   Click on the icon and type in a new filelength, confirm with a RETURN.
                   Don't make this number to small, as the file will grow very fast and even
                   if you fill in a very large number from say 100 Megabytes, it's always
                   possible to show this special data formatfile with !ARM_Debug.

                   Confirm with the "OK" button and the "Record" button will become red and
                   all the data will be send to the named file. Use the "Cancel" button to
                   close the file. The file will also been closed when you quit the monitor
                   program.
                   
Find               With this button you can search for Mnemonics (or a part from mnemonics),
----               words or strings.

                   The searching starts from the address in the writable icon.
                   Doubleclick on this icon to reset the address to zero.
                   
                   Pressing the 'F' key then 'escape' also redaws the screen and reactivates
                   the mouse. Useful when the 'Quit' button has been obscured by other text.

Marker             With this function an address can be marked by editting the writable icons.
------             With the functionkeys F9, F10 or F11 the address in  the green field
                   will be marked.
                   
                   You can jump to a marked address with the functionkeys F9, F10 or F11. 

M_Step             With the button "M_Step" a window  appears with five options:
------
                   1. Until Break or escape (Trace off).
                   
                   Click on this line or enter "1" and the programm will be executed step by
                   step until a softbreakpoint has been reached or you pressed the escape key.
                   
                   Note: Because trace is off there is no update from the screen except what the
                   program itself is sending to the screen.
                   
                   2. Until break or escape (Trace on).
                   
                   The same as above only here after every execution the registers and flags
                   will be updated to the screen.
                   
                   3. Until R<.> = <..> (Trace off).
                   
                   With this third option a register and its contents must be given.
                   Then the program will be executed step by step until the register R<.> has
                   reached the same value as you filled in.
                   
                   The execution will also stop as a softbreakpoint has been reached or you
                   pressed the escape key.
                   
                   4. Until R<.> = <..> (Trace on).
                    
                   The same as the third option only here after every execution the registers
                   and flags will be updated to the screen.
                   
                   5. Until !<Address>=<..>
                   
                   Click on this option and you've been asked to give an address and a value
                   for this address.
                   
                   Press enter and the programm will be executed step by step, until the given
                   address has the same value as you filled in.    
                
S_Step             With the S_Step button or spacebar one instruction will be executed.
------             After every instruction the registers and flags will be updated.

Skip               Skips the next instruction.
----               Only the PC register (R15) is affected. (R15=R15+4)

Break              With the break option you can place a total off five softbreakpoints in
-----              any RAM or ROM location you want.

                   After every line that has been executed, ARM_Debug checks this address
                   against the breakpoints addresses you set. Are these equal the single-
                   stepper will be interrupted.
                   
                   The button gives a window with three options:
                   
                   1. Set breakpoint.
                   
                   Fill in the breakaddress.
                   
                   A breakpoint can also been set by dragging an address to the "break" button.
                   
                   2. Show breakpoints.
                   
                   Gives a list from the breakpoints you set.
                   
                   3. Clear breakpoint.
                   
                   This option gives you a list from all the breakpoints.
                   Every line starts with a number.
                   
                   When you enter this number the breakpoint after this number will be removed
                   from the list.
                   
                   An easier way is to click with select or adjust on the breakpoint you want
                   to remove.

Quit               With Quit you go back to the place where your programm was interrupted.
----               When the interrupt was caused bya breakpoint or a SWI "OS_BreakAddress"
                   call, the singlestepper jumps to the address held in R15 with all the
                   registers updated and in the right processor mode.
                   
                   When the singlestepper was started by a *STEP command or by the "S/M Step"
                   menu command it just returns to the desktop or the commandline with a
                   SWI "OS_Exit" call.

Refresh            Refreshes the values on the screen.
-------              