Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# UART 16550 Hardware IP Block
# UART 16550 Hardware IP Repository

This repository contains a wrapper around [OpenTitan's well-verified UART hardware IP block][opentitan-uart] in order to support the common [16550 specification][16550-spec].

> [!IMPORTANT]
> The design for this IP is incomplete and the RTL will change significantly. This IP is also not well verified.

## Initial build

To do a test build you can use the following command:
Expand Down
36 changes: 36 additions & 0 deletions hw/ip/uart16550/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# UART 16550 Hardware IP Block

The UART 16550 IP block is a wrapper around the [OpenTitan UART IP][opentitan-uart], which allows it to be used with the standard 16550 register map.

> [!IMPORTANT]
> The design for this IP is incomplete and the RTL will change significantly. This IP is also not well verified.

## Register functionality

As the OpenTitan UART IP and the [16550 specification][16550-spec] have different feature sets, this wrapper only provides features supported by both implementations. The differences in register functionality are further described in the [register documentation](doc/registers.md).

## Functional differences

Additional functional differences from the [16550 specification][16550-spec] are listed below:

- Receive FIFO size is 64 bytes
- Transmit FIFO size is 32 bytes
- Received characters with framing error or parity error are not pushed into the RCVR FIFO.

## Interrupts

This wrapper provides the same set of interrupt outputs as the OpenTitan UART IP. The following interrupt outputs will however always be inactive as they are never enabled by the wrapper:

- tx_watermark
- tx_done
- rx_timeout

## Features not yet implemented
Comment thread
raylau1 marked this conversation as resolved.
Resolved

- TL-UL host request integrity check, integrity errors will be ignored
- TL-UL host `PutPartialData` opcode, which will behave as `PutFullData`
- TL-UL host request size other than 2, which will be treated as 2
- RACL, all registers will always be accessible

[opentitan-uart]: https://github.com/lowRISC/opentitan/tree/master/hw/ip/uart
[16550-spec]: https://web.archive.org/web/20180826215135/http://www.ti.com/lit/ds/symlink/pc16550d.pdf
24 changes: 24 additions & 0 deletions hw/ip/uart16550/doc/registers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# UART 16550 registers

All standard 16550 registers are implemented and accessible at the least significant byte of consecutive 4-byte words. Writes to the more significant 3 bytes are ignored and reads from these 3 bytes return 0.
The register map has a size of 32 bytes and wraps every 32 bytes.
Accesses with a non-zero `a_address[1:0]` return an error.

The difference in functionality between the [16550 specification][16550-spec] and the UART 16550 wrapper is provided in the table below.

| Register | Address offset (bytes) | Access | Difference from the specification |
|-|-|-|-|
| RBR | 0x0 (DLAB=0) | RO | Reads from an empty RCVR FIFO returns 0. |
| THR | 0x0 (DLAB=0) | WO | Writes to a full XMIT FIFO are dropped. |
| IER | 0x4 (DLAB=0) | RW | Values written to EDSSI are kept, but will have no other effect as MODEM status interrupts are never raised. |
| IIR | 0x8 | RO | Bit 3 is set when FIFO is enabled and there is an RCVR FIFO overflow interrupt. FIFO mode timeout interrupts are aliased to received data available interrupts, and are raised immediately when the trigger level is reached without a timeout. Software must set a RCVR FIFO trigger level of 1 byte. THRE interrupt will not be cleared by reading IIR. A fix for bit 3 and FIFO mode timeout interrupt are tracked in [#9](https://github.com/lowRISC/uart-16550/issues/9). |
| FCR | 0x8 | WO | 16450 mode is not supported. Values written to FIFO enable are kept, but will have no other effect as the OpenTitan UART always uses a FIFO. Changing FIFO enable does not clear the FIFOs. All bits of FCR are writable regardless of the value of FIFO enable. Writes to bits 3-5 have no effect. Writing `0b11` to the RCVR FIFO trigger level will set a trigger level of 16 bytes. |
| LCR | 0xC | RW | WLS writes are ignored and reads return `0b11` to indicate 8-bit word length. STB writes are ignored and reads return `0b0` to indicate 1 stop bit. EPS resets to `0b1` to indicate it is enabled by default. Writes to stick parity are ignored and reads return `0b0` to indicate that stick parity is always disabled. |
| MCR | 0x10 | RW | Values written to DTR, RTS and OUT are kept but have no effect on external pins. |
| LSR | 0x14 | RO | Break interrupt is indicated when the Rx pin has been continuously low for 1 bit time less than 2 character times. The first all-zero character of a break sets FE. PE, FE and BI are indicated on reception, with `LSR[7]` being the or reduction of these bits. Writes are ignored and do not return an error. |
| MSR | 0x18 | RO | Reads to DCTS, DDSR, TERI and DDCD always return 0. Reads to CTS, DSR, RI and DCD return 0 when loopback is disabled. Writes are ignored and do not return an error. |
| SCR | 0x1C | RW | - |
| DLL | 0x0 (DLAB=1) | RW | Values written are kept, but will always set CTRL.NCO to 20972, corresponding to 1 Mbaud at 50 MHz clock. One write to DLL/DLM is needed to enable Tx and Rx. |
| DLM | 0x4 (DLAB=1) | RW | Same as DLL. |

[16550-spec]: https://web.archive.org/web/20180826215135/http://www.ti.com/lit/ds/symlink/pc16550d.pdf