Architecture
============

The :sv:mod:`uart` wrapper connects the UART to TileLink, alert, RACL, chip-I/O,
and interrupt interfaces. Register accesses are decoded by
:sv:mod:`uart_reg_top`; the resulting :sv:type:`uart_reg_pkg::uart_reg2hw_t`
and :sv:type:`uart_reg_pkg::uart_hw2reg_t` structures connect the register block
to :sv:mod:`uart_core`.

The core separates the two serial directions into :sv:mod:`uart_tx` and
:sv:mod:`uart_rx`.

RTL responsibilities
--------------------

.. list-table::
   :header-rows: 1
   :widths: 23 37 40

   * - Object
     - Responsibility
     - Selected API
   * - :sv:mod:`uart`
     - Integration wrapper
     - :sv:port:`uart.tl_i`, :sv:port:`uart.cio_rx_i`,
       :sv:port:`uart.cio_tx_o`, and the interrupt outputs
   * - :sv:mod:`uart_reg_top`
     - Generated bus-facing register block
     - :sv:port:`uart_reg_top.reg2hw` and
       :sv:port:`uart_reg_top.hw2reg`
   * - :sv:mod:`uart_core`
     - FIFOs, baud generation, loopback, status, and interrupts
     - :sv:port:`uart_core.rx`, :sv:port:`uart_core.tx`, and the two register
       structures
   * - :sv:mod:`uart_tx`
     - Parallel-to-serial datapath
     - :sv:port:`uart_tx.wr_data`, :sv:port:`uart_tx.wr`, and
       :sv:port:`uart_tx.tx`
   * - :sv:mod:`uart_rx`
     - Oversampled serial-to-parallel datapath
     - :sv:port:`uart_rx.rx`, :sv:port:`uart_rx.rx_data`, and
       :sv:port:`uart_rx.rx_valid`

FIFO sizing
-----------

The package constants :sv:param:`uart_reg_pkg::RxFifoDepth` and
:sv:param:`uart_reg_pkg::TxFifoDepth` configure 64 receive entries and 32
transmit entries respectively. :sv:mod:`uart_core` uses those values to size
the FIFO depth counters and instantiate the two synchronous FIFOs.

Data flow
---------

On transmit, software writes a byte through the register block. The core queues
it, then presents it on :sv:port:`uart_tx.wr_data` while pulsing
:sv:port:`uart_tx.wr`. The transmitter shifts the frame out through
:sv:port:`uart_tx.tx`.

On receive, :sv:mod:`uart_core` synchronizes and optionally majority-filters
the external input before forwarding it to :sv:port:`uart_rx.rx`. A valid frame
produces :sv:port:`uart_rx.rx_data` and :sv:port:`uart_rx.rx_valid`; the core
accepts the byte only when neither :sv:port:`uart_rx.frame_err` nor
:sv:port:`uart_rx.rx_parity_err` is asserted.

The upstream `theory of operation`_ covers register programming, loopback,
interrupt behavior, break detection, and baud-rate calculations in detail.

.. _theory of operation: https://opentitan.org/book/hw/ip/uart/doc/theory_of_operation.html