Changes to APIs due to 32-bit addressing
========================================
A fully 32-bit OS opens up the possibility of more areas of memory being
above 64MB. Currently the application slot, module area and ROM are all
below 64MB, but it is likely that in the future the module area and ROM
will move higher to allow the application slot to be limited only by
physical RAM (reducing the need for normal programs to create their own
dynamic areas, and wasting logical address space).
When the ROM and RMA move higher (or in a program with a very large
application slot), a number of existing RISC OS APIs that place flags in
the top bits of addresses are liable to fail. This document summarises
API changes to cover this.
General notes
-------------
A number of APIs, particularly in the Window Manager, allow registers or
other values to be a either be a pointer or <= 0. These APIs are being
changed to only accept -1 or 0 as a non-pointer value.
Also, some APIs are documented as only accepting 0 as a non-pointer value,
such as the scaling factors in OS_SpriteOp 52, but actually treat any
negative value as a non-pointer; these are being tightened up to match
the documentation.
OS_ReadLine
-----------
In existing OSes, R0 is interpreted as a 26-bit address, with 6 flag bits, 4
currently unused.
In a 32-bit OS, OS_ReadLine now interprets R0 as a 32-bit address, and acts
as though the flags are both clear. This reflects the most common usage, and
allows applications not wanting to use the flags to remain unaltered.
A new SWI, OS_ReadLine32, takes its flags in R4. Bits 31 and 30 correspond to
the original flags. Bits 29-8 are reserved and must be zero. Bits 7-0 are
used as the echo byte (if bit 30 is set). As before, R4 is preserved by the
call.
ReadLineV, in a 32-bit OS, is called as though from OS_ReadLine32; ie on
entry R0 is the buffer address and R4 contains the flags (always valid,
regardless of which SWI was called).
A ReadLineV claimant may handle this at run-time by beginning their
handler:
ReadLineV_Handler
STMFD R13!, {R4, R14} ; must preserve R4
TEQ PC, PC ; 26 bit OS?
ANDNE R14, R0, #&FC000000 ; if so, extract flags
ANDNE R4, R4, #&FF ; and potential echo byte
ORRNE R4, R4, R14 ; combine into new form
BICNE R0, R0, #&FC000000 ; may corrupt R0
...
; R0 now address
; R4 now flags plus echo byte
Because of the way ReadLineV operates, any OS_ReadLine32 SWI on a 26-bit
OS will return an error if R0 > 64MB.
When using either SWI, applications for existing 26-bit OSes should ensure
that the buffer is in a low address - eg allocated in the RMA or application
space.
OS_SubstituteArgs
-----------------
In existing OSes, R0 is interpreted as a 31-bit address, with 1 flag bit.
In a 32-bit OS, OS_SubstituteArgs now interprets R0 as a 32-bit address, and
acts as though the flag is clear. This allows applications not wanting to use
the flags to remain unaltered.
The new SWI OS_SubstituteArgs32 interprets R0 as a 32-bit address, and takes
a flags word in R5. Bit 31 of R5 corresponds to the existing bit 31 of R0;
bits 30-0 are reserved. R5 is preserved across the call.
OS_HeapSort
-----------
In existing OSes, R1 is interpreted as a 29-bit address, with 3 flag bits.
Also, due to a long-standing bug, instead of inspecting bit 31, the call
inspects bit 30, meaning bit 30 causes the documented functions of both bits
30 and 31 to occur, while bit 31 is ineffective.
In a 32-bit OS, the SWI continues to work in the same way, with R1 being
interpreted as a 29-bit address plus flags, and with the flags bug preserved
for backwards compatibility.
The new SWI OS_HeapSort32 interprets R1 as a 32-bit address, and takes a
flags word in R7. Bits 31-29 of R7 correspond to bits 31-29 of R1, but with
the flags bug corrected, so each bit functions as documented on PRM page
1-939.
FileCore background scatter lists
---------------------------------
High (top-bit set) addresses are possible in a scatter list, thus only
negative numbers smaller or equal to than -64K (ie >= unsigned &FFFF0000)
should be interpreted as the end of list marker. This applies to any FileCore
module for RISC OS 3.5 or later.