|
www.riscos.com Technical Support: |
The serial device is provided as a DeviceFS (Device Filing System) device. For full details, see the chapter entitled DeviceFS.
For your convenience, we've also documented the kernel's OS_SerialOp SWI here, even though it properly belongs in Part 2 - The kernel. This SWI provides routines to access the serial device driver directly. It is like OS_Byte in that it contains a number of operations, determined by the reason code passed in R0. The advantages of using this approach are the speed of not going through several routines in the stream system, and no possibility of confusion about where the data is going.
There are also a number of OS_Byte commands for controlling the serial port, that are in RISC OS mainly for compatibility with earlier Acorn operating systems. Again, we've documented them here rather than with the kernel documentation. We strongly recommended that you use the OS_SerialOp commands in preference to the OS_Bytes because they are more complete and consistent.
Note that the serial device's input and output sides may be controlled independently. For example, you can transmit at a different baud rate from the one which is being used to receive - although hardware restrictions mean that this is not possible on machines fitted with the 82C710 or 82C711 controller, such as the A5000.
The serial device driver provides facilities to send and receive a byte, control the handshake lines and alter the protocol of the data. RISC OS provides a number of SWIs that allow access to these facilities.
Here is a summary of the OS_SerialOp commands:
Below is a summary of the OS_Byte commands in this chapter:
Remember, where possible you should use OS_SerialOp calls in preference to OS_Byte calls.
RISC OS uses streams for character input, character output, and printer output. There are OS_Byte calls to set the source and destination(s) of these streams. As an innate part of the character input/output system, they are described in full in the chapters entitled Character Input and Character Output, but we summarise them below.
Of course, you can also use OS_SerialOp calls to independently send and receive characters via the serial port; generally this is preferable.
This call selects the device from which all subsequent input is taken by OS_ReadC. This is determined by the value of R1 passed as follows:
| Value of R1 | Source of input |
|---|---|
| 0 | Keyboard, with serial input buffer disabled |
| 1 | Serial port |
| 2 | Keyboard, with serial input buffer enabled |
The difference between the 0 and 2 values is that the latter allows characters to be received into the serial input buffer under interrupts at the same time as the keyboard is being used as the primary input. If the input stream is subsequently switched to the serial device, then those characters can then be read.
For full details of OS_Byte 2, see OS_Byte 2.
This call selects which output stream(s) are active, and will hence receive all subsequent output from OS_WriteC and its derivatives. A bit mask in R1 determines this:
| Bit | Effect if set |
|---|---|
| 0 | Enables serial driver |
| 1 | Disables VDU drivers |
| 2 | Disables VDU printer stream |
| 3 | Enables printer (independently of the VDU) |
| 4 | Disables spooled output |
| 5 | Calls VDUXV instead of VDU drivers (see the chapter on VDU) |
| 6 | Disables printer, apart from VDU 1,n |
| 7 | Not used |
Thus to start sending characters to the serial output stream, call OS_Byte 3 with bit 0 of R1 set. Such characters sent are inserted into the serial output buffer (buffer number 2), where they remain until removed by the interrupt routine dealing with serial transmission.
For full details of OS_Byte 3, see OS_Byte 3.
This call sets which printer driver type (and hence printer port) is used for subsequent printer output. The value of R1 on entry determines this. For RISC OS 2, this works as follows:
| Value of R1 | Printer driver type |
|---|---|
| 0 | Printer sink |
| 1 | Parallel (Centronics) printer driver |
| 2 | Serial output |
| 3 - 255 | Files in system variables PrinterType$n (eg the NetPrint |
| module sets up PrinterType$4 to NetPrint:) |
Whereas for later versions of RISC OS:
| Value of R1 | Printer driver type |
|---|---|
| 0 - 255 | Files in system variables PrinterType$n |
| Note that appropriate values are set up for backwards compatibility: eg the serial device driver sets PrinterType$2 to use the serial device. |
Thus to send printer output to the serial port, call OS_Byte 5 with R1 = 2.
For full details of OS_Byte 5, see OS_Byte 5.
The serial driver will attempt to stop the sender transmitting when the amount of free space in the serial input buffer falls below a set threshold. The idea is that this space gives enough time for the sender to recognise the command and stop without overflowing the buffer. OS_Byte 203 can change the setting of this level.
If the output buffer is already full and there is nothing communicating with the serial port, when you insert another character the machine temporarily halts while it waits for a character to be removed to make space for the new character. An escape condition abandons this wait.
When trying to get communications working with an external device using the serial device, there are several important factors to remember:
Note that the default setup of the serial protocol (configured in CMOS RAM) is different from some earlier Acorn machines. For example, the setup for RISC OS machines is the same as the Master series (8 data bits, no parity, 2 stop bits), but different from the original BBC series (8 data bits, no parity, 1 stop bit).
Coming out of the serial connector are many lines. This is a list of their names and common abbreviations:
Refer to the documentation accompanying your particular communications device for information on how to wire these lines correctly with the serial port. For further information, contact Acorn Customer Support.
R0 = 8
R1 = baud rate code
R0 preserved
R1, R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call sets the receive baud rate for the serial port. It is provided for compatibility with older operating systems, and you should use OS_SerialOp 5 instead; see OS_SerialOp 5.
(This call uses the same baud rate codes as OS_SerialOp 5.)
ByteV
Sets the transmit baud rate for the serial port
R0 = 8
R1 = baud rate code
R0 preserved
R1, R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call sets the transmit baud rate for the serial port. It is provided for compatibility with older operating systems, and you should use OS_SerialOp 6 instead; see OS_SerialOp 6.
(This call uses the same baud rate codes as OS_SerialOp 6.)
R0 = 156
R1 = 0 or new value
R2 = 255 or 0
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call accesses the control byte of the serial port. In addition to updating the status byte in RAM, it also updates the hardware register which controls the serial port characteristics.
The call enables the current settings of the transmitter, receiver, interrupts and the serial handshake line Request To Send (RTS) to be read or altered.
When writing, the effect depends on the bits in R1:
| Bit 1 | Bit 0 | Effect | |||
|---|---|---|---|---|---|
| 0 | 0 | No effect | |||
| 0 | 1 | No effect | |||
| 1 | 0 | No effect | |||
| 1 | 1 | Reset transmit, receive and control registers | |||
| Bit 4 | Bit 3 | Bit 2 | Word length | Parity | Stop bits |
| 0 | 0 | 0 | 7 | even | 2 |
| 0 | 0 | 1 | 7 | odd | 2 |
| 0 | 1 | 0 | 7 | even | 1 |
| 0 | 1 | 1 | 7 | odd | 1 |
| 1 | 0 | 0 | 8 | none | 2 |
| 1 | 0 | 1 | 8 | none | 1 |
| 1 | 1 | 0 | 8 | even | 1 |
| 1 | 1 | 1 | 8 | odd | 1 |
| Bit 6 | Bit 5 | Transmission control | |||
| 0 | 0 | RTS low, transmit interrupt disabled | |||
| 0 | 1 | RTS low, transmit interrupt enabled | |||
| 1 | 0 | RTS high, transmit interrupt disabled | |||
| 1 | 1 | RTS low, transmit break level on transmit data, transmit interrupt disabled | |||
The above bits should not be modified as they are controlled by the OS. Use the OS_SerialOp SWIs instead to control transmission.
| Bit 7 | Receive interrupt |
|---|---|
| 0 | Disabled |
| 1 | Enabled |
The default setting for bits 2 - 4 comes from the *Configure Data value, shifted left by two bits. The current value of this byte may be read (but not set) using OS_Byte 192.
OS_SerialOps 0 and 1 provide all of these facilities and more, with the exception of the interrupt control bit. The receive interrupt/control bit can be set/cleared via OS_Byte 2. You should not change the RTS/transmit IRQ bits; RISC OS handles this function.
This call is provided for compatibility only and should not be used. In all cases you should use OS_SerialOp to provide these functions.
ByteV
R0 = 181
R1 = 0 to read or new state to write
R2 = 255 to read or 0 to write
R0 preserved
R1 = state before being overwritten
R2 = NoIgnore state (see OS_Byte 182 on OS_Byte 182)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The state stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((state AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
Usually, top-bit-set characters read from the serial input buffer are not treated specially. For example, if the remote device sends the code &85, when this is read, using OS_ReadC for example, that ASCII code will be returned to the caller immediately. It is sometimes useful to be able to treat serial input characters in exactly the same way as keyboard characters. OS_Byte 181 allows this.
The state value passed to this call has two values:
None
ByteV
Read/write serial busy flag
R0 = 191
R1 = 0 or new value
R2 = 255 or 0
R0 preserved
R1 = state before being overwritten
R2 = value of serial port control byte (see OS_Byte 192 on OS_Byte 192)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call is provided for compatibility reasons only; the cassette interface and RS423 serial port shared the same hardware on the BBC/Master 128 machines. It performs no useful function under RISC OS.
None
ByteV
R0 = 192 (reason code)
R1 = 0
R2 = 255
R0 preserved
R1 = value of communications state
R2 = value of flash counter (see OS_Byte 193 on OS_Byte 193)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call reads the control byte of the serial port. It is equivalent to a read operation with OS_Byte 156.
This call should not be used to write the value back, as to do so would make the RISC OS copy of the register inconsistent with the actual register in the serial hardware.
ByteV
R0 = 203
R1 = 0 to read or new value to write
R2 = 255 to read or 0 to write
R0 preserved
R1 = value before being overwritten
R2 = serial ignore flag (see OS_Byte 204 on OS_Byte 204)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
The serial input routine attempts to halt input when the amount of free space left in the input buffer falls below a certain level. This call allows the value at which input is halted to be read or changed.
OS_SerialOp 0 can be used to examine or change the handshaking method.
The default value is 9 characters.
None
ByteV
R0 = 204
R1 = 0 to read or new flag to write
R2 = 255 to read or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The flag stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((flag AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call is used to read or change the flag which indicates whether serial input is to be buffered or not. Although this call can stop data being placed in the serial input buffer, data is still received by the serial driver. Errors will still generate events unless they have been disabled by OS_Byte 13.
If the flag is zero, then serial input buffering is enabled. Any non-zero value disables it.
ByteV
R0 = 242 (&F2) (reason code)
R1 = 0
R2 = 255
R0 preserved
R1 = baud rates
R2 = timer switch state (see OS_Byte 243 on OS_Byte 243)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
R1 returns an encoded value which gives the baud rate for serial receive and transmit. Originally, in the BBC/Master operating systems, only eight baud rates were available. These could be encoded in three bits each for receive and transmit. Under RISC OS, 15 are available, which require four bits to encode. For compatibility with this earlier format, the layout of this byte looks unusual:
| Bit | Meaning |
|---|---|
| 0 | Transmit bit 0 |
| 1 | Transmit bit 1 |
| 2 | Transmit bit 2 |
| 3 | Receive bit 0 |
| 4 | Receive bit 1 |
| 5 | Receive bit 2 |
| 6 | Receive bit 3 |
| 7 | Transmit bit 3 |
These four bit groups are encoded with baud rates. Note that this order is not the same as the order used by any other baud rate setting SWI. This order is based on the original hardware:
| Value | Baud Rate |
|---|---|
| 0 | 19200 |
| 1 | 1200 |
| 2 | 4800 |
| 3 | 150 |
| 4 | 9600 |
| 5 | 300 |
| 6 | 2400 |
| 7 | 75 |
| 8 | 7200 |
| 9 | 134.5 |
| 10 | 1800 |
| 11 | 50 |
| 12 | 3600 |
| 13 | 110 |
| 14 | 600 |
| 15 | undefined |
The value stored must not be changed by making R1 and R2 other than the values stated above.
This call is provided for backwards compatibility with the BBC and Master operating systems. You should in preference use OS_SerialOps 5 and 6 to read and write baud rates.
ByteV
Low level serial operations
R0 = reason code
other input registers as determined by reason code
R0 preserved
other registers may return values, as determined by the reason code passed.
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call is like OS_Byte in that it is a single call with many operations within it. The operation required, or reason code, is passed in R0. It can have the following meanings:
| R0 | Meaning | Page |
|---|---|---|
| 0 | Read/write serial states | OS_SerialOp 0 |
| 1 | Read/write data format | OS_SerialOp 1 |
| 2 | Send break | OS_SerialOp 2 |
| 3 | Send byte | OS_SerialOp 3 |
| 4 | Get byte | OS_SerialOp 4 |
| 5 | Read/write receive baud rate | OS_SerialOp 5 |
| 6 | Read/write transmit baud rate | OS_SerialOp 6 |
| 7 | For system use only | OS_SerialOp 7 |
| 8 | Read/write serial input buffer threshold value | OS_SerialOp 8 |
For a detailed explanation of each reason code, see the relevant page.
None
SerialV
R0 = 0 (reason code)
R1 = EOR mask
R2 = AND mask
R0 preserved
R1 = old value of state
R2 = new value of state
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The structure of this call is very similar to that of OS_Bytes between SWI &A6 and SWI &FF. The new state is determined by:
New state = (Old state AND R2) EOR R1
This call is used to read and write various states of the serial system. These states are presented as a 32-bit word. The bits in this word represent the following states:
Note that if XON/XOFF handshaking is used, then OS_Byte 2,1 or 2,2 must be called beforehand.
RISC OS 2 does not support bits 4-7 and 21-23 inclusive.
R0 = 1 (reason code)
R1 = -1 to read, or new format value
R0 preserved
R1 = old format value
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call sets the encoding of characters when sent and received on the serial line. The bits in this word represent the following formats:
| Bit | Read/Write or Read Only | Value | Meaning |
|---|---|---|---|
| 0,1 | R/W | 0 | 8 bit word. |
| 1 | 7 bit word. | ||
| 2 | 6 bit word. | ||
| 3 | 5 bit word. | ||
| 2 | R/W | 0 | 1 stop bit. |
| 1 | 2 stop bits in most cases. 1 stop bit if 8 bit word with parity. 1.5 stop bits if 5 bit word without parity. | ||
| 3 | R/W | 0 | parity disabled. |
| 1 | parity enabled. | ||
| 4,5 | R/W | 0 | odd parity. |
| 1 | even parity. | ||
| 2 | parity always 1 on TX and ignored on RX. | ||
| 3 | parity always 0 on TX and ignored on RX. | ||
| 6 - 31 | reserved - must be set to zero. |
R0 = 2 (reason code)
R1 = length of break in centiseconds
R0, R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call sets the ACIA to transmit a break, then waits R1 centiseconds before resetting it to normal. Any character being transmitted at the time the call is made may be garbled. After sending the break the transmit process is either awakened if the buffer is not empty, or made dormant if the buffer is empty.
None
SerialV
R0 = 3 (reason code)
R1 = character to be sent
R0, R1 preserved
C flag clear if character was sent, or set if character was not sent (ie the buffer was full)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call puts a character in the serial output buffer, and re-enables the transmit interrupt if it had been disabled by RISC OS.
If the serial output buffer is full, the call returns immediately with the C flag set.
None
SerialV
R0 = 4
R0 preserved
R1 = character received (if C flag clear), or preserved (if C flag set - ie no character available in buffer to read)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call removes a character from the serial input buffer if one is present. If removing a character leaves the input buffer with more free spaces than are specified by OS_Byte 203, then the transmitting device is re-enabled in the way specified by the serial port state (as set by OS_SerialOp 0).
Note that reception must have been enabled using OS_Byte 2 before this call will have any effect.
OS_Byte 2 (SWI &06), OS_Byte 203 (SWI &06)
SerialV
R0 = 5 (reason code)
R1 = -1 to read, or 0 - 15 to set to a value
R0 preserved
R1 = old receive baud rate
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The baud rate codes are as follows:
| Value of R1 | Baud rate |
|---|---|
| 0 | 9600 |
| 1 | 75 |
| 2 | 150 |
| 3 | 300 |
| 4 | 1200 |
| 5 | 2400 |
| 6 | 4800 |
| 7 | 9600 |
| 8 | 19200 |
| 9 | 50 |
| 10 | 110 |
| 11 | 134.5 |
| 12 | 600 |
| 13 | 1800 |
| 14 | 3600 |
| 15 | 7200 |
The settings from 0 to 8 are in an order compatible with earlier operating systems. The other speeds from 9 to 15 provide all the other standard baud rates.
The default rate is set by *Configure Baud.
This call has the same effect as an OS_Byte 7 for writing.
OS_Byte 7 (SWI &06)
SerialV
Read/write TX baud rate
R0 = 6 (reason code)
R1 = -1 to read, or 0 - 15 to set to a value
R0 preserved
R1 = old transmit baud rate
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The baud rate codes are as follows:
| Value of R1 | Baud rate |
|---|---|
| 0 | 9600 |
| 1 | 75 |
| 2 | 150 |
| 3 | 300 |
| 4 | 1200 |
| 5 | 2400 |
| 6 | 4800 |
| 7 | 9600 |
| 8 | 19200 |
| 9 | 50 |
| 10 | 110 |
| 11 | 134.5 |
| 12 | 600 |
| 13 | 1800 |
| 14 | 3600 |
| 15 | 7200 |
The settings from 0 to 8 are in an order compatible with earlier operating systems. The other speeds from 9 to 15 provide all the other standard baud rates.
The default rate is set by *Configure Baud.
This call has the same effect as an OS_Byte 8 for writing.
This reason code is for system use only; you must not use it in your own code.
R0 = 8 (reason code)
R1 = -1 to read or new value to write
R0 preserved
R1 = value before being overwritten
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The serial input routine attempts to halt input when the amount of free space left in the input buffer falls below a certain level. This call allows the value at which input is halted to be read or changed.
OS_SerialOp 0 can be used to examine or change the handshaking method.
The default value in RISC OS 3.5 is 17 characters, but this is subject to change and should not be relied upon.
SerialV
*Configure Baud n
n - 0 to 8
*Configure Baud sets the configured receive and transmit baud rates for the serial port. The values of n correspond to the following baud rates:
| n | Baud rate |
|---|---|
| 0 | 9600 |
| 1 | 75 |
| 2 | 150 |
| 3 | 300 |
| 4 | 1200 |
| 5 | 2400 |
| 6 | 4800 |
| 7 | 9600 |
| 8 | 19200 |
The default value is 4 (1200 baud).
The change takes effect on the next reset.
*Configure Baud 7 - sets the configured baud rate to 9600
None
None
*Configure Data n
n - 0 to 7
*Configure Data sets the configured data word format for the serial port. The values of n correspond to the following formats:
| n | Word length | Parity | Stop bits |
|---|---|---|---|
| 0 | 7 | even | 2 |
| 1 | 7 | odd | 2 |
| 2 | 7 | even | 1 |
| 3 | 7 | odd | 1 |
| 4 | 8 | none | 2 |
| 5 | 8 | none | 1 |
| 6 | 8 | even | 1 |
| 7 | 8 | odd | 1 |
The default value is 4 (8 bits, no parity, 2 stop bits).
The change takes effect on the next reset.
*Configure Data 0 - (7 bits, even parity, 2 stop bits)
None