From eeb8c4c74cd2c6f98cd03d79f7bdcf2b44043ca4 Mon Sep 17 00:00:00 2001 From: Ray Lau Date: Wed, 11 Nov 2026 10:01:10 +0000 Subject: [PATCH] [doc] Add wrapper feature documentation Signed-off-by: Ray Lau --- README.md | 5 ++++- hw/ip/uart16550/README.md | 36 ++++++++++++++++++++++++++++++++ hw/ip/uart16550/doc/registers.md | 24 +++++++++++++++++++++ 3 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 hw/ip/uart16550/README.md create mode 100644 hw/ip/uart16550/doc/registers.md diff --git a/README.md b/README.md index 82e71b4..8eb77ce 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/hw/ip/uart16550/README.md b/hw/ip/uart16550/README.md new file mode 100644 index 0000000..76a8434 --- /dev/null +++ b/hw/ip/uart16550/README.md @@ -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 + +- 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 diff --git a/hw/ip/uart16550/doc/registers.md b/hw/ip/uart16550/doc/registers.md new file mode 100644 index 0000000..dc4b4c2 --- /dev/null +++ b/hw/ip/uart16550/doc/registers.md @@ -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