OS_ReadLine
OS_ReadLine is an interface used to read a line from the current input stream. It was originally designed for Arthur, based on the OS_Word 0 system call provided by the BBC series of machines. This, and the initial 26bit limitations of the architecture, meant that the vector itself reused parts of address space which have subsequently (with ARM 6 and later, with RISC OS 3.5) been made available to users through dynamic areas.
The buffer pointer in R0 is restricted by using the top two bits for flags. These two bits mean that any dynamic area in the top three quarters of memory could not be used for line buffers. Prior to Select, the top 6 bits are actually unavailable even though the lower 4 of these are unused.
With Select 4 and later, it is possible to use the OS_ReadLine call to address the full range of memory through an extended interface. By setting bit 31 of R1 (the length of the line), the 'Full address range interface' will be used. Clients should use this interface if they know they are to run on Select 4 or later. Specifically, this interface is available where the ReadLine module version 0.05 is present.
On both 26bit and 32bit OSs, the interface functions identically.
OS_ReadLine32
OS_ReadLine32 will always use the 'Full address range interface', and bit 31 of r1 need not be set to indicate this.
Full address range interface
On entry
R0 = pointer to buffer
R1 = maximum length of line
26bit - bit 31 should be set to indicate the full address range is used.
32bit - bit 31 will be ignored
R2 = lowest character to put into buffer
R3 = highest character to put into buffer
R4 = b0-7 : echo character (if bit 30 set)
bits 8-29 - reserved
bit 30 = use character in b0-7 to hide characters (for passwords)
bit 31 = don't reflect characters not entering the buffer
On exit
R0 = Preserved
R1 = length of line input
C clear if line terminated normally
C set if line terminated by escape
V set if an error occurred other than escape
Old-style interface
On entry
R0 = pointer to buffer + flags
bits 26-29: ignored
bit 30 - use character in R4 b0-7 to hide characters (for passwords)
bit31 - don't reflect characters not entering the buffer
R1 = maximum length of line
bit31 - must be clear, would cause buffer overflow if set on old systems
R2 = lowest character to put into buffer
R3 = highest character to put into buffer
R4 = b0-7 : echo character (if R0 bit 30 set)
On exit
R1 = length of line input
C clear if line terminated normally
C set if line terminated by escape
V set if an error occurred other than escape
ReadLine Vector
Because the OS_ReadLine interface has been updated, it has been necessary to update the ReadLine vector to reflect this.
On 32bit systems:
The 'Full address range interface' will always be used for ReadLineV. On 26bit systems. Bit 31 of R1 indicates whether the 'Full address range interface' or the 'Old-style interface' is present.
A handler on this vector could use code similar to the following to allow it to function whatever type of system is used :
ReadLineV_Code
STMFD sp!, {r0 , r4, r14} ; must preserve r0 and r4
TST r1, #1<<31 ; check for new style interface
BICNE r1, r1, #1<<31 ; if so, clear the flag
BNE full_interface_in_use
TEQ pc, pc ; are we 32bit ?
ANDNE r4, r4, #255 ; 26bit: leave just character
ANDNE r14,r0, #63<<26 ; 26bit: get flag bits (top 6 bits)
ORRNE r4, r4, r14 ; 26bit: update flags in r4
BICNE r0, r0, #63<<26 ; 26bit: leave just the address
full_interface_in_use
; registers now set up as described in 'Full address range interface'
; with r1 bit 31 clear.
Caveats
This documented interface differs from that developed by Pace Microtechnology PLC. These differences are mostly compatible, but are required to ensure that applications running on 26bit systems can benefit from the expanded interface. In particular :
- OS_ReadLine functions identically, whether invoked in 26bit or 32bit processor mode.
- OS_ReadLine can be used to access the full address range by setting bit 31.
- ReadLineV may be entered with R1 bit 31 set to indicate that the extended interface can be used.
ReadLine module
The ReadLine module provides the implementation of the OS_ReadLine and OS_ReadLine32 SWIs. It dispatches these to vector handlers appropriately for the processor upon which it is running. Where possible, the 'Full address range interface' will be degraded to the 'old-style' interface on 26bit systems.
|