Serial Device¶
A memory-mapped serial device (UART) that exchanges bytes between the
core and an external I/O device. It has serial_in/serial_out
pins, a serial_int_out output pin to the Interrupt
Controller (IRL 12), and
communicates with the core over the shared address/data bus through
its own set of registers. See Peripheral
Devices for the connection diagram and the
full address map.
A single instance is modeled. A self-tuning variant, which auto-detects baud rate from an initial calibration byte, is not used here.
Registers¶
| Register | Width | Access |
|---|---|---|
| Control | 32-bit | word (ld/st) |
| Tx | 8-bit | byte store (stb), write only |
| Rx | 8-bit | byte load (ldub), read only |
| Baud limit / baud control | 32-bit | word |
| Baud frequency | 32-bit | word |
See Peripheral Devices for the address of each register.
Each register has its own address. Tx and Rx are byte registers: a byte store to Tx's address sends that byte, and a byte load from Rx's address returns the received byte.
Control register bit-fields¶
| Bit | Field | Description |
|---|---|---|
[0] |
Tx_en |
Transmit enable. |
[1] |
Rx_en |
Receive enable. |
[2] |
Rx_interrupt_enable |
If set, receiving a byte raises an interrupt. |
[3] |
Tx_full (read-only) |
Set once the CPU writes Tx, cleared once it is transmitted. |
[4] |
Rx_full (read-only) |
Set once a byte is received into Rx, cleared once the CPU reads it. |
[5] |
UART_reset |
Writing 1 resets both state machines to their reset state (a byte still being transmitted is dropped). Always reads 0. |
Baud rate¶
The baud-limit and baud-frequency registers are computed from a desired baud rate and clock frequency, from the GCD of 16 times the baud rate and the clock frequency:
gcd = GCD(16 x baud_rate, clock_frequency)
baud_frequency = (16 x baud_rate) / gcd
baud_limit = (clock_frequency / gcd) - baud_frequency
The model stores both registers and reads them back, but they do not
set its transmit timing. How long a byte takes to transmit is the
model's own txTicksPerByte setting (default 1 cycle, see Model
Configuration Settings).
Behavior¶
The device is modeled by two independent state machines, transmit and receive, sharing the one control register above.
Transmit¶
TX_DISABLED
The reset state. A write ofTx_en=1clearsTx_fulland moves toTX_ENABLED.TX_ENABLED
Waits for a Tx register write. On one,Tx_fullis set and the device moves toTX_TRANSMITTING.TX_TRANSMITTING
Once the byte finishes transmitting,Tx_fullis cleared and the device returns toTX_ENABLED. A Tx write while still transmitting is dropped.
A write of Tx_en=0 from any state returns to TX_DISABLED. If a byte
is still being transmitted, it is sent first.
To send a byte: enable the transmitter, write the byte to the Tx
register, then poll Tx_full until it clears before writing the next
one (or disable the transmitter).
Receive¶
RX_DISABLED
The reset state. A write ofRx_en=1clearsRx_fulland moves toRX_ENABLED.RX_ENABLED
Waits for a byte on theserial_inpin. On one,Rx_fullis set, an interrupt is raised ifRx_interrupt_enableis set, and the device moves toRX_DATA_RECEIVED.RX_DATA_RECEIVED
Once the CPU reads the Rx register,Rx_fulland the interrupt are cleared and the device returns toRX_ENABLED.
A write of Rx_en=0 from any state clears Rx_full and the
interrupt, and returns to RX_DISABLED. While the receiver is disabled
or still holds an unread byte, incoming bytes wait, they are not lost.
The receiver supports two usage modes, selected by Rx_interrupt_enable:
- Polling mode (
Rx_interrupt_enable=0): enable the receiver, pollRx_fulluntil it sets, then read the Rx register (and disable the receiver, or leave it enabled for the next byte). - Interrupt mode (
Rx_interrupt_enable=1): enable the receiver, wait for the interrupt, then read the Rx register (and disable the receiver, or leave it enabled for the next byte).
Where the bytes go in the simulator¶
The serial device exists so a program can show output and take input. By default every transmitted byte is written straight to the simulator's own standard output, as the program sends it. Received bytes come from an input file. Every configuration with devices accepts:
| Option | Effect |
|---|---|
--serial-in <file> |
Bytes received on serial_in come from this file, in order. |
--serial-out <file> |
Transmitted bytes go to this file instead of standard output. |
--serial-pty |
A pseudo-terminal carries both directions. The simulator prints its device name, attach any terminal program to it. |
Without --serial-in, a file next to the program's .hex with the
same name and the extension .serial_in is used, if it exists. That is
how a validation test carries its own input.