Core

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.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015