The interrupt system on a RISC OS computer makes extensive use of buffers. These act as temporary holding areas for data after you (or a device) generate it, and before a device (or you) consume it. For example, whenever you type a character on the keyboard, that character is stored in the keyboard input buffer by the keyboard interrupt handler, and it remains there until your program is ready to use it.
The buffer manager is a global buffer managing system used by DeviceFS to provide buffers for the various devices that can be accessed. It provides a set of calls for setting up a buffer, inserting and removing data from a buffer, and removing a buffer. For more details about the buffer manager see the chapter entitled The Buffer Manager.
We are not concerned with filing system buffers in this section. However, these are areas where RISC OS holds whole areas of files in memory to increase the efficiency of file access. The use of file buffers is generally invisible to you; there is no direct way of accessing their contents.
The buffers we are looking at are known as first-in first-out, or FIFO, buffers. This is because the characters are removed from the buffer in the same order in which they were inserted. Many operations on buffers are implicit. For example, when you send a character to the printer or RS423 port, a character is inserted into a buffer. When you read from the keyboard or RS423 port using OS_ReadC, a character is removed from the buffer.
Additionally, there are several explicit buffer operations available. These include:
All these operations are implemented as OS_Bytes - see below.
The buffer is also purged implicitly when the escape condition is cleared - see the chapter entitled Character Input.
There are ten buffers, numbered 0 - 9. Their uses are as follows:
| Number | Use | Size |
|---|---|---|
| 0 | Keyboard | 255 |
| 1 | RS423 (input) | 255 |
| 2 | RS423 (output) | 191 |
| 3 | Printer | 1023 From RISC OS 3 onwards, the size of the printer buffer is configurable using *Configure PrinterBufferSize. |
| 4 | Sound channel 0 | 3 |
| 5 | Sound channel 1 | 3 |
| 6 | Sound channel 2 | 3 |
| 7 | Sound channel 3 | 3 |
| 8 | Speech | 3 |
| 9 | Mouse | 63 |
Buffers 2 to 8 are output buffers. They hold data you generate until a device is ready to consume it. The others are input buffers. These store bytes generated by the keyboard, RS423 and mouse respectively until you are ready to read them.
Currently, buffers 4 to 8 are not used by RISC OS. They are provided for compatibility with BBC Micro software. Sound buffering and speech are implemented differently on RISC OS hardware than they were on BBC hardware. These buffers are not considered further.
The format of data in all buffers in current use, except for the mouse buffer, is byte-oriented ASCII data, although top-bit-set characters are treated specially in the keyboard buffer (and optionally in the serial input buffer). See the chapter entitled Character Input for a description of buffer values for the keyboard buffer. The mouse buffer contents refer to buffered button clicks. The format is as follows:
| Offset | Contents |
|---|---|
| +0 | Mouse x coordinate low |
| +1 | Mouse x coordinate high |
| +2 | Mouse y coordinate low |
| +3 | Mouse y coordinate high |
| +4 | Button state |
| +5 | Time of button change, byte 0 |
| +6 | Time of button change, byte 1 |
| +7 | Time of button change, byte 2 |
| +8 | Time of button change, byte 3 |
The bytes are listed in the order in which they would be removed using OS_Byte 145 - see OS_Byte 145.
Usually OS_Mouse reads data from the mouse buffer. If none is available, it returns the current state instead. The mouse buffer is 63 bytes long, so 7 entries may be held at once.
The OS_Bytes used to control buffers are described below.
They are, in fact, just an interface to the vectored buffer routines described on InsV onwards of the Software vectors. Usually, the OS_Bytes are easier to use. However, there are times when it is preferable, or necessary (for example to read the number of bytes free in an input buffer) to use the vectors. They can be called directly using OS_CallAVector.
To use different sized system buffers under RISC OS 2, you must provide handlers for all of InsV, RemV and CnpV. You could do so in a module that replaces, say, the printer buffer with a much larger one. You would claim the memory for this from the relocatable module area. The module could have its own configuration byte held in CMOS RAM to specify the size of the buffer, which it would claim on initialisation.
Under later versions of RISC OS you can alter the size of the printer buffer using *Configure PrinterBufferSize. To alter the size of other system buffers, rather than claiming InsV, RemV and CnpV, you must instead use the buffer manager SWIs Buffer_Create or Buffer_Register.
| R0 | = | 15 | ||||||
| R1 | = | reason code :
|
| R0 | preserved | |
| R1 | corrupted | |
| R2 | corrupted | |
This call flushes either all the buffers, or only the current input buffer determined by R0.
The contents of the buffer(s) are discarded. Individual buffers may be flushed using OS_Byte 21.
| R0 | = | 21 |
| R1 | = | buffer number |
| R0 | preserved | |
| R1 | preserved | |
| R2 | corrupted | |
This call flushes the specified buffer.
| R0 | = | 128 | ||||||||||||||||
| R1 | = | reason code :
|
| R0 | preserved | |
| R1 | = | bits 0 - 7 = low 8 bits of answer |
| R2 | = | bits 0 - 23 = high 24 bits of answer |
The action of this call depends upon the reason code in R1. It returns either the current x or y position of the mouse, or the number of bytes in a particular input buffer, or how many bytes there are free in a particular output buffer.
Obviously we are more concerned with the calls where R1 >= 246 here. Note that R1 = (255 - buffer number) in these cases. If you want, you can also calculate this as { (- (buffer number + 1)) AND &FF }.
The calls to read the mouse position are considered obsolete, and are unreliable because they read the buffered position rather than the actual position. You should use OS_Mouse instead.
| R0 | = | 138 |
| R1 | = | buffer number |
| R2 | = | byte to insert |
| R0 | preserved | |
| R1 | preserved | |
| R2 | preserved | |
| C | set if the buffer was full | |
| C | clear if the character was inserted | |
This call inserts the byte specified in R2 into the buffer identified by R1. If C=1 on exit, the byte was not inserted as there was no room.
Inserting bytes into the mouse buffer isn't recommended, but if you must, you should be careful to insert all nine bytes with interrupts disabled, to prevent a real mouse transition from entering data into the middle of your data. You must do so as quickly as possible to reduce latency in the interrupt system.
| R0 | = | 145 |
| R1 | = | buffer number |
| R0 | preserved | |
| R1 | preserved | |
| R2 | = | byte extracted |
| C | set if the buffer was empty | |
| C | clear if the character was read | |
This call extracts the next byte from a specified buffer. If the buffer was empty then the C flag is set, and R2 will be invalid.
This call assumes the buffer number is correct; it does not generate an error if passed a bad buffer number, and its behaviour is undefined.
| R0 | = | 152 |
| R1 | = | buffer number |
| R0 | preserved | |
| R1 | preserved | |
| R2 | = | next byte in buffer, or corrupted if buffer was empty |
| C | set if the buffer was empty | |
| C | clear if the character was read | |
This call returns the status of a specified buffer; the carry flag is set if the buffer is empty. If a byte is available, it is returned in R2 but is not removed from the buffer.
This call assumes the buffer number is correct; it does not generate an error if passed a bad buffer number, and its behaviour is undefined.
| R0 | = | 153 | ||||||
| R1 | = | buffer number :
| ||||||
| R2 | = | byte to insert |
| R0 | preserved | |
| R1 | corrupted | |
| R2 | corrupted | |
| C | set if the buffer was full | |
| C | clear if the character was inserted | |
This call enables bytes to be inserted into one of the two input buffers.
If the buffer was full and a byte could not be inserted, then the C flag is set on return.
If the current escape character (usually ASCII 27) is inserted, then appropriate action is taken; see the chapter entitled Character Input.
| Maintainer(s): | RISCOS Ltd <developer@riscos.com> | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| History: |
| ||||||||
| Disclaimer: |
Copyright © Pace Micro Technolgy plc, 2002. |