OpenTitan UART

This site is a working example of sphinx-svdomain applied to a real SystemVerilog design. It combines source-driven API documentation from the OpenTitan UART RTL with explanatory pages based on the UART hardware IP specification.

The UART is a full-duplex serial peripheral with an 8-bit data word, optional even or odd parity, one stop bit, programmable baud rate, receive and transmit FIFOs, loopback modes, and interrupt reporting. This example focuses on how those concepts map onto discoverable SystemVerilog objects rather than duplicating the complete upstream specification.

The RTL logic is pinned to OpenTitan commit 377160a7ea64bf6b187127db5f2bc6819b7ff196. Declaration-facing comments in the local copy use the doc-comment syntax consumed by autodoc, making the generated API both descriptive and reproducible.

UART documentation

• Architecture
  • RTL responsibilities
  • FIFO sizing
  • Data flow
• Serial protocol
  • Transmit path
  • Receive path
• RTL API reference
  • Register package
  • Integration wrapper
  • UART core
  • Transmit datapath
  • Receive datapath
  • Generated register block
• How the example uses sphinx-svdomain
  • Targeted autodoc
  • Cross-references
  • Syntax-only boundary