Info Jul 2016

Is there a proper way of stopping a program – ie :

mov pc.#0

b 0

Swi OS_breakpt

And being able to look at the Regs?
Something like *showregs in a Task window.

How would the ‘High vector’ RO respond to the above?

Would it be possible – for RO to use ‘High vectors or low’ depending on a CMOS value?

Is there a module that accelerates the pointer across screen – that works with several versions of RO?

Can you be more specific? Do you want to stop it for good, or restart it, or what?

The normal way to exit is to call OS_Exit. You could also return to the return address on the stack (if R14 was stacked at startup), but if you want to bomb out without knowing the state of the stack, OS_Exit is the way to go. I suppose you could claim a bit of memory in the RMA and dump the registers there prior to exiting, something like LDR R14, addressofmemoryblock, then STMIA R14, {R0-R13} ?
Don’t forget and use the habitual STMFD, that’ll upset stuff. ;-)

Branching to zero is, well, that’s the reset vector on low vector ARM – probably not what you would want to have happen. On a high vector ARM, I would imagine it would abort (I’m sitting outside in a deck chair – officially on holiday now) which as a side effect should dump the registers so that ShowRegs will display them…assuming RISC OS recovers by killing the application and doesn’t just stiff up.

Do you have the DDE? If it is a regular task, DDT is awkward and annoying but it is quite good when it deems your project worthy enough that it will work.

No, RISC OS cannot use CMOS to determine high or low vectors. That choice is not low level, that choice is bare metal. One needs to know where the vectors are before one can even think about reading CMOS.

I do think, however, that the nightly builds ought to come in high and low vector flavours until we can be certain that bugs have been exorcised.

SWI OS_BreakPt will do what you require and if you want the breakpoint to call your own code, claim the Breakpoint Environment handler

Mmm, that’s simpler, yes. ;-)

DDT is more flexible though.

I’ve found a old module ‘BreakPt’ that does this and prints it to its own window.

Think I have made it to work with RO 5.23 (25 Jul 16) – seemed to want to poke in a strange place in org vsn :-(

Needs a little update to handle the flags properly.

I would like to know – what params of below – should be:-

r0=8

r1 = address of code

r2=r12

r3 ???

SWI  "XOS_ChangeEnvironment"

r3 ???

and what should come out.

Tks

R3 is a pointer to a word aligned, 16 word buffer for the register dump

Tks – that is now 17 word buffer – extra word for the flags.
Head scratching time – whats the pecking order?

swi OS_BreakPt is called.
Your code if called before or after -by adding OS_ChangeEnvironment.

What does swi OS_Claim ,&1E – come into the sequence?
It seems to want to Zero R1 and R2 – when is this put into effect?

Any simple examples – explaining RO vectors/events etc out there.

Head scratching time – whats the pecking order?

You mean the register order? I’d imagine R0-R15 then the CPSR.

swi OS_BreakPt is called.
Your code if called before or after -by adding OS_ChangeEnvironment.

Huh? If you use OS_BreakCtrl or OS_ChangeEnvironment, then your breakpoint handler will be called when OS_BreakPt happens. No before, no after, your handler is called in place of the default OS one.

What does swi OS_Claim ,&1E – come into the sequence?
It seems to want to Zero R1 and R2 – when is this put into effect?

Leave that alone. You can hook into the OS_ChangeEnvironment vector to modify behaviour (for example a debugger might want to trap your breakpoint handler and ensure its own is always in use). For using OS_BreakPt, you don’t need to touch this.

I threw together a really basic example.

[program code deleted, I’ve written something better]

I’ve removed all mention of “returning to the program” as it is NOT possible with that code as it stands. I went for a walk up the driveway and back (about a kilometre round trip) and I just couldn’t get around the fact that R14 is going to get trashed. The only way to avoid this is to run the entire breakpoint handler in SVC mode.
Let me think about this some more…

Okay, here’s code.

First up, a simple little “wrapper”. This represents your program and indicates:

1. You must call debug_init to set up the breakpoint handler
2. You must call debug_finish before exiting
3. Call OS_BreakPt when you want to examine the registers.

; TestCode
; ========
;
; Stupid test program to test custom OS_BreakPt handler
;
; Rick Murray, 2016/08/04
;

        AREA |My$Code|, CODE, A32bit

        IMPORT debug_init      ; in the other code file ;-)
        IMPORT debug_finish

        ENTRY

        SWI    &10             ; OS_GetEnv
        MOV    R13, R1         ; set stack pointer

        BL     debug_init      ; set up breakpoint handler code

        ; set some registers so they can be seen in the debug dump
        MOV    R0, #&00
        MOV    R1, #&11
        MOV    R2, #&22
        MOV    R3, #&33
        MOV    R4, #&44
        MOV    R5, #&55
        MOV    R6, #&66
        MOV    R7, #&77
        ; only bother with R0-R7

        ; Okay, let's blow it up
        SWI    &17             ; invoke breakpoint

        ; Do it again - to see that the registers are the same
        SWI    &17             ; invoke breakpoint

        ; Output something
        ADR    R0, my_message
        SWI    &2              ; OS_Write0
        SWI    &3              ; OS_NewLine

        BL     debug_finish    ; undo debug stuff

        SWI    &11             ; OS_Exit
        ; *** EXIT ***

my_message
        =      "Hasta la vista, BABY.", 0
        ALIGN

        END

Here is the debug code. This handles setting up and removing the breakpoint handler, plus the handler itself. The handler runs in SVC mode and does some fiddling with USR mode while in SVC mode (hence why the LDM ^ and MOVS that are normally “not to be used” in 32 bit code).

Edit: There’s a later better version on my website. Details further below…

; DebugTest
; =========
;
; Test using OS_BreakPt for debugging.
;
; Rick Murray, 2016/08/04
;
; Open Source software - this code has been released under the EUPL v1.1 (only).
; hxxps://joinup.ec.europa.eu/community/eupl/og_page/european-union-public-licence-eupl-v11
; [EDIT: The above (hxxps) edited because Textile is a piece of poo at knowing when it
;        should and should not screw around with URLs. "xx" should be "tt", but you knew that...]
;
; Special note: The EUPL licence applies ONLY to this specific code. It may therefore be
;               used in and with software under other licences[*] without requiring any
;               modification to the licence of these other parts.
;
;               * - EUPL code can be converted to GPL v2 to work around the lack of
;                   compatibility and openness of the GPL.
;                   It is not, however, compatible with the even-less-open GPL v3.
;

        AREA |My$Code|, CODE, A32bit

        EXPORT debug_init      ; our host program needs this
        EXPORT debug_finish

debug_init
        ; set up debug stuff
        MOV    R0, #0          ; use existing register save block
        ADR    R1, debug_break ; our handler
        SWI    &20018          ; XOS_BreakCtrl (deprecated! ;-) )
        ADR    R2, debug_saveblock
        STR    R0, [R2, #0]    ; remember where the save block is
        STR    R1, [R2, #4]    ; remember the previous control routine
        MOV    PC, R14

debug_finish
        ; revert to previous
        ADR    R2, debug_saveblock
        LDR    R0, [R2, #0]    ; retrieve original saveblock
        LDR    R1, [R2, #4]    ; retrieve original control routine
        SWI    &20018          ; XOS_BreakCtrl
        MOV    PC, R14

debug_saveblock
        DCD    0               ; to remember saveblock address
        DCD    0               ; to remember control routine

debug_wordbuffer
        DCD    0               ; space for 8 characters plus terminull
        DCD    0
        DCD    0

debug_break
        ; Called upon a breakpoint
        ; USER mode registers are saved at debug_saveblock address,
        ; and we are entered in SVC mode.

        ;   R0-R3 : Scratch
        ;   R4    : Register save pointer
        ;   R5    : Counter

        ; Pick up address of saved registers
        ADR    R4, debug_saveblock
        LDR    R4, [R4]

        ; First, report where the break point happened
        ADR    R0, brk_msg
        SWI    &2              ; OS_Write0
        LDR    R0, [R4, #(15*4)] ; R15 aka PC
        ADR    R1, debug_wordbuffer
        MOV    R2, #11
        SWI    &D4             ; OS_ConvertHex8
        SWI    &2              ; OS_Write0
        SWI    &3              ; OS_NewLine

        ; Now dump the registers
        MOV    R5, #0          ; Start from R0

debug_dumploop
        ; Output "Rxx = &"
        SWI    256 + 'R'       ; Output "R"
        ADD    R0, R5, #48     ; R0 is now a number
        CMP    R5, #10         ; Register >= 10?
        SUBGE  R0, R0, #10     ; ...bring it back to 0-9 range
        SWIGE  256 + '1'       ; ...and prefix a '1'
        SWI    &0              ; OS_WriteC
        CMP    R5, #10
        SWILT  256 + ' '       ; Add a space if register < 10
        ADR    R0, reg_msg     ; " = &"
        SWI    &2              ; OS_Write0

        ; Read the register and output it, in the form:
        ;   xxxxxxxx (yyyyyy)
        ;   [hex]     [denary]
        MOV    R1, R5, LSL#2   ; R1 = counter, shifted to word offset
        LDR    R3, [R4, R1]    ; R3 = savedregs + counter offset
        MOV    R0, R3
        ADR    R1, debug_wordbuffer
        MOV    R2, #11
        SWI    &D4             ; OS_ConvertHex8
        SWI    &2              ; OS_Write0
        SWI    256 + ' '
        SWI    256 + '('
        MOV    R0, R3          ; pick up the register value again
        ADR    R1, debug_wordbuffer
        MOV    R2, #11
        SWI    &D8             ; OS_ConvertCardinal4
        SWI    &2              ; OS_Write0
        SWI    256 + ')'
        SWI    &3              ; OS_NewLine

        ADD    R5, R5, #1      ; next register
        CMP    R5, #15         ; done beyond R14?
        BLT    debug_dumploop  ; if not, go around again

        ; If we're here, R0-R14 have been dumped. Ask the user what
        ; to do.
        ADR    R0, abort_retry_ignore
        SWI    &2              ; OS_Write0
        SWI    &3              ; OS_NewLine
        SWI    &4              ; OS_ReadC

        ; 'C' means continue, anything else means exit.
        CMP    R0, #'C'        ; Was it a 'C'?
        CMPNE  R0, #'c'        ; Or was it a 'c'?
        BNE    debug_exit      ; If not, EXIT.

        ; If we're here, the user wants to resume with the program
        LDR    R0, [R4, #(16*4)] ; pick up the CPSR
        MSR    SPSR_cxsf, R0   ; store it in SPSR_svc

        MOV    R14, R4         ; Set R14_svc to point to register save block
        LDMIA  R14, {R0-R14}^  ; Restore all USER MODE registers
        MOV    R0, R0          ; objasm whinges

        LDR    R14, [R14, #(15*4)] ; R14_svc is now USER MODE PC
        ADD    R14, R14, #4    ; Point to the *following* instruction!

        MOVS   PC, R14         ; MOVS here will copy SPSR to CPSR
        ; we're back to our program now...


debug_exit
        ; We come here to EXIT the program

        MSR    CPSR_c, #16     ; drop to USER32 mode (from SVC)

        BL     debug_finish    ; restore previous breakpoint handler

        SWI    &11             ; OS_Exit

        ; ** Done **

brk_msg
        =      "Breakpoint at &", 0
        ALIGN

reg_msg
        =      " = &", 0
        ALIGN

abort_retry_ignore
        =      "[C]ontinue or [Q]uit?", 0
        ALIGN

        END

Both programs use hardcoded SWI numbers so that they can be easily copied and built without need to special headers or anything. Just build the two files and link ’em together. ;-)

Here is an example of the output:

*BreakTest
Breakpoint at &000080AC
R0  = &00000000 (0)
R1  = &00000011 (17)
R2  = &00000022 (34)
R3  = &00000033 (51)
R4  = &00000044 (68)
R5  = &00000055 (85)
R6  = &00000066 (102)
R7  = &00000077 (119)
R8  = &0000000A (10)
R9  = &30048584 (805602692)
R10 = &FA208000 (4196433920)
R11 = &FA207FA0 (4196433824)
R12 = &80000000 (2147483648)
R13 = &00408000 (4227072)
R14 = &0000808C (32908)
[C]ontinue or [Q]uit?
Breakpoint at &000080B0
R0  = &00000000 (0)
R1  = &00000011 (17)
R2  = &00000022 (34)
R3  = &00000033 (51)
R4  = &00000044 (68)
R5  = &00000055 (85)
R6  = &00000066 (102)
R7  = &00000077 (119)
R8  = &0000000A (10)
R9  = &30048584 (805602692)
R10 = &FA208000 (4196433920)
R11 = &FA207FA0 (4196433824)
R12 = &80000000 (2147483648)
R13 = &00408000 (4227072)
R14 = &0000808C (32908)
[C]ontinue or [Q]uit?
Hasta la vista, BABY.
*

Have fun. (^_^)

Thanks for your input – OS_BreakCtrl looks interesting.

The placing of the Regs at a low value – &AE8 – where does this go in Hi vector RO?

Two progs -one to set the Regs to a value.
The other to read it and display them.

BASIC Progs
******
REM Print Regs
SYS"OS_BreakCtrl",0,0 TO R0,R1
PRINT " R0 “~R0,” R1 "~R1
FOR X%=0 TO 16*4 STEP 4
PRINT ~R0!X%
NEXT

END
******
REM SetRegs
DIM Space% 17*4
O%=Space%:P%=Space%
[OPT 0
.go
MOV R0,#0 :MOV R1,#1 :MOV R2,#2
MOV R3,#3 :MOV R4,#4 :MOV R5,#5
MOV R6,#6 :MOV R7,#7 :MOV R8,#8
MOV R9,#09 :MOV R10,#10 :MOV R11,#11
MOV R12,#12 :MOV R13,#13
MSR CPSR_F,#&10000000 ;set V flag
SWI “OS_BreakPt”
SWI “OS_Exit”
]

CALL go
END
***********

Something like *showregs in a Task window.

I may be missing the point, and Martin Avison may be away, but isn’t this just what Reporter does?

The simplest is just to include SWI "Report_Regs" in the code, but if you supply a buffer you can be more specific with "SWI "Report_Registers". There are other useful SWIs as well.

The placing of the Regs at a low value – &AE8 – where does this go in Hi vector RO?

Probably the same offset from whereever the high vector stuff begins.

That said, it does not matter. The SWI exists to provide the information so you don’t make assumptions about where things go. The OS is free to put the register dump in other arbitrary places (RMA, for instance).

Two progs -one to set the Regs to a value.
The other to read it and display them.

Hmm, not quite what OS_BreakPt is there for. ;-)

Steve – Tend to use Report_Regs – shifting the higher regs – to within range if it is safe to – also seems to work ok in SVC.
Also make use of DeskDebug – might use it on Ricks prog :-)
Also make use of !Arm_Debug 26bit at mo.
Big advantage is that it will spool pc addresses to HD.
Go away and let it do it’s thing – like running for 2hrs – with DA Picture to get a fault to appear.

With BreakPt module – it seems to be poking (plus)+4 to the pc address – &AE8 (plus) +xx – that isn’t allowed by my Zero page protecting prog.
all fun and games :-)
Thanks for your help.

On my blog is an annotated version of the code explaining what it does. It is a slightly later version so it can also report on the processor flags (NZCV), plus “for the lulz” there is a description of how to use breakpoints in BASIC, not that there’s much any point in doing so…

http://www.heyrick.co.uk/blog/index.php?diary=20160805

Thanks for the effort – not much ARM code info around.
Should work with the GCC assembler.

Does this work with 32bit RO :-
(Does the flag info get passed through the swi?)

tst xxxx
swieq xxxx
swine xxxx

Does this work with 32bit RO :-
(Does the flag info get passed through the swi?)

Very interesting question. It appears that the flags are not supposed to pass a SWI, though a number of artificial tests (like MOV R0, #0 and SUBS R0, R0, #1) showed the code working correctly.

It is a fairly simple fix though. Push the CPSR into R1, and then MOV the uppercase version of the letter to it. If the clause is EQ, add 32 (makes it lower case). Then OS_WriteC to output it.
The code on my website has been updated to reflect these changes, and to correct some errant tabs inserted by Notepad++ (how many times must I tell it to use SPACES? <sigh>).

Apart from kernel SWIs, which are a bit special, the official line is that NZCV is undefined on entry to a SWI handler. When the handler exits, the current NZCV flags will be passed back to the caller. So handlers can’t read the caller’s flags, and if they want to return a value in a flag they must explicitly set the flag to the right value since the input value might not match what the caller had.

https://www.riscosopen.org/viewer/view/castle/RiscOS/Sources/Kernel/Docs/32bit?rev=4.4;hideattic=0#l49

I supose this only effects ARM assembler writers.

But if the SWI’s don’t do teq/cmp etc – no flags are changed.
But it makes for nice code – pity there isn’t a list of SWI’s that don’t touch the flags.

Justin F. (wanted used) provided a ‘Function signatures’ macro – (I have made up a BASIC version).
Perhaps copies could be held on Ricks site.

Since the GCC assembler is open source – perhaps a few macro’s could be added as standard – like a list of common swi’s etc.
Date/Time command?

Would make examples – like Ricks – easier to write.

It would be nice – for ones starting out coding – to make coding as simple as possible – without piles of header files – and strange sounding errors from Assembler/C Compilers.

Above – did Rick mean movs r0,#0

Using swi 256+7 – seems to allow &E0000000 through – V flag – zeroed -using the debug module BreakPt.
Have to try on 26bit RO to see if the ‘V’ is passed through – or is it standard practice to zero it.
(swi Report_Regs) also zeros the V flag.)

But if the SWI’s don’t do teq/cmp etc – no flags are changed.

It is a pretty big IF, to have a SWI “do something” that doesn’t modify the flags. Consider something as simple as SWI 256+65 which outputs an ‘A’ to the screen. Bzzzt! Wrong. It sends an ‘A’ to the current VDU stream, which could be VDU4, VDU5, redirected to sprite, copied to serial port, etc etc. Even if it was just to the screen, RISC OS uses a bitmap display, so there is surely some flag-using logic in reading the character code from the system font buffer and plotting it pixel by pixel to the screen.
In short, I think a SWI that does no TEQ/CMP etc would probably not be able to do much of anything at all.

Since the GCC assembler is open source – perhaps a few macro’s could be added as standard – like a list of common swi’s etc.

I have my own set of macros, there is a very big set of them in the DDE, plus I have (and DDE has) a long list of SWI definitions.

The reason I didn’t include any of this with my program is that “useful” headers would, by necessity, be many times larger than the program code.

Would make examples – like Ricks – easier to write.

Marginally. It wasn’t hard to look up the SWIs I wanted in StrongHelp to get the numbers.
However, note that supplying a standardised header with snippets of example code would make it a lot more tedious to read.

It would be nice – for ones starting out coding – to make coding as simple as possible – without piles of header files – and strange sounding errors from Assembler/C Compilers.

Generally speaking those strange sounding errors (and fear-inducing panic from the C compiler should you miss a single ‘;’) tell you that you did something wrong. Use it as a lesson – because unfortunately while we may be human and forgetful and stuff, there is zero room for error in software. You mess up, things will go wrong. You mess up a lot, it’ll blow up in your face (all those error messages), but you mess up just a little, that’s the worst as those problems can be subtle and hard to track down. As you pointed out with my SWIEQ, SWINE, and the question of whether or not SWIs preserve flags. They used to. They pretty much don’t now. I forgot.

Using swi 256+7 – seems to allow &E0000000 through – V flag – zeroed -using the debug module BreakPt.
Have to try on 26bit RO to see if the ‘V’ is passed through – or is it standard practice to zero it.
(swi Report_Regs) also zeros the V flag.)

Technically the SWI protocol states that V is set on exit if there was an error, so I guess it is valid to assume that V will be zeroed on entry to a SWI so it is only set on exit if an error actually happened. This is important to know as usually the behaviour of the SWI is modified so that R0 is a pointer to an error block, and any of the other registers that might be returned will either be preserved or in an undefined state. All you’re supposed to know is R0=error message, if V is set.

I’ve managed to get the breakpoint handler to enter a C module, so I’m writing something that will be entered upon OS_BreakPt but will offer more facilities (such as changing registers or flags, examining memory, etc).

It isn’t designed to be a fully fledged debugger. There’s the Debugger module for those who like pain, and DDT for those who like pain with whipped cream on top. :-P

Just made a ‘empty module’ – that just returns with ‘mov pc,r14’.
It contains some swi’s -:
Maybe needs a fresh – chunk number that doen’t upset others.

swi Debug_0
swi Debug_1
etc

The idea is that with ‘DeskDebug’ that it would seem easier to just type in:-

Debug_0 – to set breakpoints.

If you include the swi in the source code – the debugger with stop.
(easier than finding out – where the code you want is at)

The point is – is by adding this swi to the code – liable to have any side effects -other than making the code longer – maybe adr problems?