Repository navigation
[doc] Add wrapper feature documentation #7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
|
|
||
| - 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.