GitLab

The poor documentation of OS_Exit in the PRMs means there could be many
pieces of software which are using it in a dangerous way. E.g. the
famous issue of "OS_Exit generates a garbage error if the return code is
out of range" that's documented in the OS StrongHelp manuals - where
people (quite rightly) assumed that the OS would generate the "return
code out of range" error, when in reality the OS has only ever used the
error pointer that was supplied by the caller.

Try and improve on things slightly by having OS_Exit sanity check the
supplied error pointer before it tries to use it. This doesn't alter the
cases where OS_Exit decides to silently ignore the supplied error
pointer / return code (if R0 isn't word aligned, or historically, if R0
wasn't word aligned and wasn't in the low 64MB of address space), it
just alters the logic for what error pointer gets sent to
OS_GenerateError when it does decide to raise an error.

If the error pointer looks bad (it's below &4000 or not pointing to at
least 8 bytes of readable memory) then it will get swapped out for one
of the "return code out of range" errors which get used when you *Set
Sys$ReturnCode.

Version 6.70. Tagged as 'Kernel-6_70'

Although it's never been officially documented, RISC OS has historically
used the following values for R0-R2 when calling the exit environment
handler:

R0 = 0 (or some other "safe" value)
R1 = R1 from OS_Exit
R2 = Return code

Some exit handlers were relying on this (e.g. Shared C Library /
ANSILib). Changing OS_Exit to use TaskControl_ResetStacks was causing R1
& R2 to be corrupt, with the result that non-zero, non-error-generating
return codes from C programs were being lost and reset to zero.

Document things more clearly and ensure R0-R2 have acceptable values so
that software which relies on the old behaviour will work again.

OSExitArgs checks how OS_Exit handles its arguments, whether it passes
the call on to the error or exit handler, and the register state on
entry to those handlers.

It will currently fail on this version of the kernel due to a register
corruption bug introduced when OS_Exit was changed to use
TaskControl_ResetStacks (the state of R0-R2 on entry to exit handlers
has never been documented, and some handlers rely on R0-R2 being in a
valid state to pass into another OS_Exit call, but TaskControl was
corrupting R1-R2, preventing the return code from being passed on)