RTL API reference

Every object below is extracted from the vendored SystemVerilog at build time. The package is emitted first so its types and parameters can be linked from later module signatures.

Register package

package uart_reg_pkg

Generated UART register constants and hardware-facing data types.

Contains FIFO sizing, register offsets and reset values, register indices, and the packed structures exchanged by the register block and UART core.

parameter int RxFifoDepth = 64: Number of entries in the receive FIFO.

parameter int TxFifoDepth = 32: Number of entries in the transmit FIFO.

parameter int NumAlerts = 1: Number of fatal alert channels.

parameter int BlockAw = 6: Width of a register-block byte address.

parameter int NumRegs = 13: Number of software-visible UART registers.

enum int uart_alert_idx_t

Indices of UART fatal alert channels.

enumerator AlertFatalFaultIdx = 0: Fatal bus-integrity or register fault.

struct packed uart_reg2hw_intr_state_reg_t

Software view of the interrupt-state register.

field struct packed { logic q; } tx_empty: Transmit FIFO empty interrupt state.

field struct packed { logic q; } rx_parity_err: Receive parity-error interrupt state.

field struct packed { logic q; } rx_timeout: Receive timeout interrupt state.

field struct packed { logic q; } rx_break_err: Receive break-error interrupt state.

field struct packed { logic q; } rx_frame_err: Receive framing-error interrupt state.

field struct packed { logic q; } rx_overflow: Receive FIFO overflow interrupt state.

field struct packed { logic q; } tx_done: Final-byte transmit completion interrupt state.

field struct packed { logic q; } rx_watermark: Receive FIFO watermark interrupt state.

field struct packed { logic q; } tx_watermark: Transmit FIFO watermark interrupt state.

struct packed uart_reg2hw_intr_enable_reg_t

Software view of the interrupt-enable register.

field struct packed { logic q; } tx_empty: Enables the transmit FIFO empty interrupt.

field struct packed { logic q; } rx_parity_err: Enables the receive parity-error interrupt.

field struct packed { logic q; } rx_timeout: Enables the receive timeout interrupt.

field struct packed { logic q; } rx_break_err: Enables the receive break-error interrupt.

field struct packed { logic q; } rx_frame_err: Enables the receive framing-error interrupt.

field struct packed { logic q; } rx_overflow: Enables the receive FIFO overflow interrupt.

field struct packed { logic q; } tx_done: Enables the final-byte transmit completion interrupt.

field struct packed { logic q; } rx_watermark: Enables the receive FIFO watermark interrupt.

field struct packed { logic q; } tx_watermark: Enables the transmit FIFO watermark interrupt.

struct packed uart_reg2hw_intr_test_reg_t

Software write and write-enable view of the interrupt-test register.

field struct packed { logic q; logic qe; } tx_empty: Forces a transmit FIFO empty interrupt.

field struct packed { logic q; logic qe; } rx_parity_err: Forces a receive parity-error interrupt.

field struct packed { logic q; logic qe; } rx_timeout: Forces a receive timeout interrupt.

field struct packed { logic q; logic qe; } rx_break_err: Forces a receive break-error interrupt.

field struct packed { logic q; logic qe; } rx_frame_err: Forces a receive framing-error interrupt.

field struct packed { logic q; logic qe; } rx_overflow: Forces a receive FIFO overflow interrupt.

field struct packed { logic q; logic qe; } tx_done: Forces a final-byte transmit completion interrupt.

field struct packed { logic q; logic qe; } rx_watermark: Forces a receive FIFO watermark interrupt.

field struct packed { logic q; logic qe; } tx_watermark: Forces a transmit FIFO watermark interrupt.

struct packed uart_reg2hw_alert_test_reg_t

Software write and write-enable view of the alert-test register.

field logic q: Value written to the fatal-fault alert test bit.

field logic qe: Pulses when software writes the alert test bit.

struct packed uart_reg2hw_ctrl_reg_t

Software-controlled UART configuration fields.

field struct packed { logic [15:0] q; } nco: Baud-rate numerically controlled oscillator value.

field struct packed { logic [1:0] q; } rxblvl: Receive break-detection length selection.

field struct packed { logic q; } parity_odd: Selects odd rather than even parity.

field struct packed { logic q; } parity_en: Enables parity in both serial directions.

field struct packed { logic q; } llpbk: Enables external line loopback.

field struct packed { logic q; } slpbk: Enables internal system loopback.

field struct packed { logic q; } nf: Enables the receive majority noise filter.

field struct packed { logic q; } rx: Enables the receive datapath.

field struct packed { logic q; } tx: Enables the transmit datapath.

struct packed uart_reg2hw_status_reg_t

Software read-enable view of the live UART status fields.

field struct packed { logic q; logic re; } rxempty: Receive FIFO empty status access.

field struct packed { logic q; logic re; } rxidle: Receive datapath idle status access.

field struct packed { logic q; logic re; } txidle: Transmit datapath idle status access.

field struct packed { logic q; logic re; } txempty: Transmit FIFO empty status access.

field struct packed { logic q; logic re; } rxfull: Receive FIFO full status access.

field struct packed { logic q; logic re; } txfull: Transmit FIFO full status access.

struct packed uart_reg2hw_rdata_reg_t

Software read-data register interface.

field logic [7:0] q: Current receive-data value.

field logic re: Pulses when software reads the receive-data register.

struct packed uart_reg2hw_wdata_reg_t

Software write-data register interface.

field logic [7:0] q: Transmit-data value written by software.

field logic qe: Pulses when software writes the transmit-data register.

struct packed uart_reg2hw_fifo_ctrl_reg_t

Software-controlled FIFO thresholds and reset strobes.

field struct packed { logic [2:0] q; logic qe; } txilvl: Transmit FIFO interrupt threshold selection.

field struct packed { logic [2:0] q; logic qe; } rxilvl: Receive FIFO interrupt threshold selection.

field struct packed { logic q; logic qe; } txrst: Transmit FIFO reset strobe.

field struct packed { logic q; logic qe; } rxrst: Receive FIFO reset strobe.

struct packed uart_reg2hw_ovrd_reg_t

Software-controlled transmit-pin override fields.

field struct packed { logic q; } txval: Transmit pin value used while override is enabled.

field struct packed { logic q; } txen: Enables software override of the transmit pin.

struct packed uart_reg2hw_timeout_ctrl_reg_t

Software-controlled receive timeout configuration.

field struct packed { logic q; } en: Enables receive FIFO timeout detection.

field struct packed { logic [23:0] q; } val: Timeout threshold in UART bit times.

struct packed uart_hw2reg_intr_state_reg_t

Hardware updates to interrupt-state fields.

field struct packed { logic d; logic de; } tx_empty: Transmit FIFO empty event and update enable.

field struct packed { logic d; logic de; } rx_parity_err: Receive parity-error event and update enable.

field struct packed { logic d; logic de; } rx_timeout: Receive timeout event and update enable.

field struct packed { logic d; logic de; } rx_break_err: Receive break-error event and update enable.

field struct packed { logic d; logic de; } rx_frame_err: Receive framing-error event and update enable.

field struct packed { logic d; logic de; } rx_overflow: Receive FIFO overflow event and update enable.

field struct packed { logic d; logic de; } tx_done: Final-byte transmit completion event and update enable.

field struct packed { logic d; logic de; } rx_watermark: Receive FIFO watermark event and update enable.

field struct packed { logic d; logic de; } tx_watermark: Transmit FIFO watermark event and update enable.

struct packed uart_hw2reg_status_reg_t

Hardware updates to live UART status fields.

field struct packed { logic d; } rxempty: Indicates that the receive FIFO is empty.

field struct packed { logic d; } rxidle: Indicates that the receive datapath is idle.

field struct packed { logic d; } txidle: Indicates that transmission is complete.

field struct packed { logic d; } txempty: Indicates that the transmit FIFO is empty.

field struct packed { logic d; } rxfull: Indicates that the receive FIFO is full.

field struct packed { logic d; } txfull: Indicates that the transmit FIFO is full.

struct packed uart_hw2reg_rdata_reg_t

Hardware-provided receive data.

field logic [7:0] d: Next receive-data register value.

struct packed uart_hw2reg_fifo_ctrl_reg_t

Hardware updates to FIFO threshold fields.

field struct packed { logic [2:0] d; logic de; } txilvl: Transmit threshold value and update enable.

field struct packed { logic [2:0] d; logic de; } rxilvl: Receive threshold value and update enable.

struct packed uart_hw2reg_fifo_status_reg_t

Hardware-provided FIFO fill levels.

field struct packed { logic [7:0] d; } rxlvl: Current receive FIFO fill level.

field struct packed { logic [7:0] d; } txlvl: Current transmit FIFO fill level.

struct packed uart_hw2reg_val_reg_t

Hardware-provided receive oversampling history.

field logic [15:0] d: Last sixteen sampled receive values.

struct packed uart_reg2hw_t

Complete software-to-hardware UART register bundle.

field uart_reg2hw_intr_state_reg_t intr_state: Interrupt state, bits 131:123.

field uart_reg2hw_intr_enable_reg_t intr_enable: Interrupt enables, bits 122:114.

field uart_reg2hw_intr_test_reg_t intr_test: Interrupt test strobes, bits 113:96.

field uart_reg2hw_alert_test_reg_t alert_test: Alert test strobe, bits 95:94.

field uart_reg2hw_ctrl_reg_t ctrl: UART control fields, bits 93:69.

field uart_reg2hw_status_reg_t status: Status read enables, bits 68:57.

field uart_reg2hw_rdata_reg_t rdata: Receive-data interface, bits 56:48.

field uart_reg2hw_wdata_reg_t wdata: Transmit-data interface, bits 47:39.

field uart_reg2hw_fifo_ctrl_reg_t fifo_ctrl: FIFO control, bits 38:27.

field uart_reg2hw_ovrd_reg_t ovrd: Transmit override, bits 26:25.

field uart_reg2hw_timeout_ctrl_reg_t timeout_ctrl: Timeout control, bits 24:0.

struct packed uart_hw2reg_t

Complete hardware-to-software UART register bundle.

field uart_hw2reg_intr_state_reg_t intr_state: Interrupt updates, bits 71:54.

field uart_hw2reg_status_reg_t status: Live status, bits 53:48.

field uart_hw2reg_rdata_reg_t rdata: Receive data, bits 47:40.

field uart_hw2reg_fifo_ctrl_reg_t fifo_ctrl: FIFO control updates, bits 39:32.

field uart_hw2reg_fifo_status_reg_t fifo_status: FIFO fill levels, bits 31:16.

field uart_hw2reg_val_reg_t val: Receive sample history, bits 15:0.

parameter logic [BlockAw - 1:0] UART_INTR_STATE_OFFSET = 6'h 0: Interrupt-state offset.

parameter logic [BlockAw - 1:0] UART_INTR_ENABLE_OFFSET = 6'h 4: Interrupt-enable offset.

parameter logic [BlockAw - 1:0] UART_INTR_TEST_OFFSET = 6'h 8: Interrupt-test offset.

parameter logic [BlockAw - 1:0] UART_ALERT_TEST_OFFSET = 6'h c: Alert-test offset.

parameter logic [BlockAw - 1:0] UART_CTRL_OFFSET = 6'h 10: Control-register offset.

parameter logic [BlockAw - 1:0] UART_STATUS_OFFSET = 6'h 14: Status-register offset.

parameter logic [BlockAw - 1:0] UART_RDATA_OFFSET = 6'h 18: Receive-data offset.

parameter logic [BlockAw - 1:0] UART_WDATA_OFFSET = 6'h 1c: Transmit-data offset.

parameter logic [BlockAw - 1:0] UART_FIFO_CTRL_OFFSET = 6'h 20: FIFO-control offset.

parameter logic [BlockAw - 1:0] UART_FIFO_STATUS_OFFSET = 6'h 24: FIFO-status offset.

parameter logic [BlockAw - 1:0] UART_OVRD_OFFSET = 6'h 28: Pin-override offset.

parameter logic [BlockAw - 1:0] UART_VAL_OFFSET = 6'h 2c: Receive-sample offset.

parameter logic [BlockAw - 1:0] UART_TIMEOUT_CTRL_OFFSET = 6'h 30: Timeout-control offset.

parameter logic [8:0] UART_INTR_TEST_RESVAL = 9'h 0: Interrupt-test reset value.

parameter logic [0:0] UART_INTR_TEST_TX_WATERMARK_RESVAL = 1'h 0: TX-watermark test reset value.

parameter logic [0:0] UART_INTR_TEST_RX_WATERMARK_RESVAL = 1'h 0: RX-watermark test reset value.

parameter logic [0:0] UART_INTR_TEST_TX_DONE_RESVAL = 1'h 0: TX-done test reset value.

parameter logic [0:0] UART_INTR_TEST_RX_OVERFLOW_RESVAL = 1'h 0: RX-overflow test reset value.

parameter logic [0:0] UART_INTR_TEST_RX_FRAME_ERR_RESVAL = 1'h 0: Framing-error test reset value.

parameter logic [0:0] UART_INTR_TEST_RX_BREAK_ERR_RESVAL = 1'h 0: Break-error test reset value.

parameter logic [0:0] UART_INTR_TEST_RX_TIMEOUT_RESVAL = 1'h 0: RX-timeout test reset value.

parameter logic [0:0] UART_INTR_TEST_RX_PARITY_ERR_RESVAL = 1'h 0: Parity-error test reset value.

parameter logic [0:0] UART_INTR_TEST_TX_EMPTY_RESVAL = 1'h 0: TX-empty test reset value.

parameter logic [0:0] UART_ALERT_TEST_RESVAL = 1'h 0: Alert-test register reset value.

parameter logic [0:0] UART_ALERT_TEST_FATAL_FAULT_RESVAL = 1'h 0: Fatal-fault test reset value.

parameter logic [5:0] UART_STATUS_RESVAL = 6'h 3c: Live-status register reset value.

parameter logic [0:0] UART_STATUS_TXEMPTY_RESVAL = 1'h 1: TX-empty status reset value.

parameter logic [0:0] UART_STATUS_TXIDLE_RESVAL = 1'h 1: TX-idle status reset value.

parameter logic [0:0] UART_STATUS_RXIDLE_RESVAL = 1'h 1: RX-idle status reset value.

parameter logic [0:0] UART_STATUS_RXEMPTY_RESVAL = 1'h 1: RX-empty status reset value.

parameter logic [7:0] UART_RDATA_RESVAL = 8'h 0: Receive-data reset value.

parameter logic [23:0] UART_FIFO_STATUS_RESVAL = 24'h 0: FIFO-status reset value.

parameter logic [15:0] UART_VAL_RESVAL = 16'h 0: Receive-sample history reset value.

enum int uart_id_e

UART register indices used by generated decode logic and RACL selection.

enumerator UART_INTR_STATE: Interrupt-state register.

enumerator UART_INTR_ENABLE: Interrupt-enable register.

enumerator UART_INTR_TEST: Interrupt-test register.

enumerator UART_ALERT_TEST: Alert-test register.

enumerator UART_CTRL: UART control register.

enumerator UART_STATUS: UART live-status register.

enumerator UART_RDATA: Receive-data register.

enumerator UART_WDATA: Transmit-data register.

enumerator UART_FIFO_CTRL: FIFO-control register.

enumerator UART_FIFO_STATUS: FIFO-status register.

enumerator UART_OVRD: Transmit-pin override register.

enumerator UART_VAL: Receive oversampling-value register.

enumerator UART_TIMEOUT_CTRL: Receive-timeout control register.

parameter logic [3:0] UART_PERMIT [13] = '{ 4'b 0011, 4'b 0011, 4'b 0011, 4'b 0001, 4'b 1111, 4'b 0001, 4'b 0001, 4'b 0001, 4'b 0001, 4'b 0111, 4'b 0001, 4'b 0011, 4'b 1111 }: Per-register permitted write-byte mask.

Integration wrapper

module uart

OpenTitan UART top-level integration wrapper.

Connects the UART core to the generated register block, TileLink, alert, RACL, chip-I/O, and interrupt interfaces.

parameter logic [NumAlerts - 1:0] AlertAsyncOn = {NumAlerts{1'b1}}: Selects asynchronous alert handling for each alert.

parameter int unsigned AlertSkewCycles = 1: Number of cycles a differential skew is tolerated on the alert signal.

parameter bit EnableRacl = 1'b0: Enables register access-control checks.

parameter bit RaclErrorRsp = EnableRacl: Converts a RACL denial into a TileLink error response.

parameter top_racl_pkg::racl_policy_sel_t RaclPolicySelVec [NumRegs] = '{NumRegs{0}}: Selects the RACL policy for each UART register.

input clk_i: Primary module clock.

input rst_ni: Active-low asynchronous reset.

input tlul_pkg::tl_h2d_t tl_i: TileLink device request channel.

output tlul_pkg::tl_d2h_t tl_o: TileLink device response channel.

input prim_alert_pkg::alert_rx_t [NumAlerts - 1:0] alert_rx_i: Incoming differential alert acknowledgements.

output prim_alert_pkg::alert_tx_t [NumAlerts - 1:0] alert_tx_o: Outgoing differential fatal-alert requests.

input top_racl_pkg::racl_policy_vec_t racl_policies_i: Runtime RACL policy vector.

output top_racl_pkg::racl_error_log_t racl_error_o: RACL access-error log.

output logic lsio_trigger_o: Combined TX/RX watermark trigger for low-speed I/O capture.

input cio_rx_i: Serial receive pin.

output logic cio_tx_o: Serial transmit pin.

output logic cio_tx_en_o: Serial transmit output-enable; always asserted.

output logic intr_tx_watermark_o: Transmit FIFO watermark interrupt.

output logic intr_tx_empty_o: Transmit FIFO empty interrupt.

output logic intr_rx_watermark_o: Receive FIFO watermark interrupt.

output logic intr_tx_done_o: Final transmitted-byte completion interrupt.

output logic intr_rx_overflow_o: Receive FIFO overflow interrupt.

output logic intr_rx_frame_err_o: Receive stop-bit framing-error interrupt.

output logic intr_rx_break_err_o: Receive line-break interrupt.

output logic intr_rx_timeout_o: Receive FIFO timeout interrupt.

output logic intr_rx_parity_err_o: Receive parity-error interrupt.

UART core

module uart_core

UART datapath, FIFOs, baud generator, loopback, and interrupt logic.

Bridges the generated register structures to independent transmit and receive engines. The receiver is synchronized and can use a three-sample majority noise filter.

input clk_i: Primary module clock.

input rst_ni: Active-low asynchronous reset.

input uart_reg_pkg::uart_reg2hw_t reg2hw: Software-controlled register values from the register block.

output uart_reg_pkg::uart_hw2reg_t hw2reg: Hardware status and data returned to the register block.

input rx: Serial receive input.

output logic tx: Serial transmit output.

output logic lsio_trigger_o: Combined TX/RX watermark trigger for low-speed I/O capture.

output logic intr_tx_watermark_o: Transmit FIFO watermark interrupt.

output logic intr_tx_empty_o: Transmit FIFO empty interrupt.

output logic intr_rx_watermark_o: Receive FIFO watermark interrupt.

output logic intr_tx_done_o: Final transmitted-byte completion interrupt.

output logic intr_rx_overflow_o: Receive FIFO overflow interrupt.

output logic intr_rx_frame_err_o: Receive stop-bit framing-error interrupt.

output logic intr_rx_break_err_o: Receive line-break interrupt.

output logic intr_rx_timeout_o: Receive FIFO timeout interrupt.

output logic intr_rx_parity_err_o: Receive parity-error interrupt.

localparam int NcoWidth = $bits(reg2hw.ctrl.nco.q): Width of the baud-rate numerically controlled oscillator.

localparam int TxFifoDepthW = $clog2(TxFifoDepth) + 1: Width needed to represent the transmit FIFO fill level.

localparam int RxFifoDepthW = $clog2(RxFifoDepth) + 1: Width needed to represent the receive FIFO fill level.

enum logic break_st_e

Receive break-detection state.

enumerator BRK_CHK: Check received all-zero characters for a break condition.

enumerator BRK_WAIT: Wait for the receive line to return high after a break.

Transmit datapath

module uart_tx

UART parallel-to-serial transmit engine.

Loads a start bit, eight data bits, optional parity, and a stop bit into a shift register and emits them least-significant bit first.

input clk_i: Primary module clock.

input rst_ni: Active-low asynchronous reset.

input tx_enable: Enables transmission; disabling forces the line idle-high.

input tick_baud_x16: Sixteen-times-baud tick from the core NCO.

input logic parity_enable: Includes the supplied parity bit when asserted.

input wr: Loads a new character into the transmit shift register.

input logic wr_parity: Parity value accompanying the write data.

input [7:0] wr_data: Eight-bit character to transmit.

output idle: Indicates that no character is currently being shifted.

output logic tx: Serial transmit output.

Receive datapath

module uart_rx

UART serial-to-parallel receive engine.

Detects a low start bit, samples each bit at its center, checks the stop and optional parity bits, and presents a valid eight-bit character.

input clk_i: Primary module clock.

input rst_ni: Active-low asynchronous reset.

input rx_enable: Enables the receive engine.

input tick_baud_x16: Sixteen-times-baud sampling tick from the core NCO.

input parity_enable: Enables parity checking.

input parity_odd: Selects odd parity when asserted, otherwise even parity.

output logic tick_baud: One-cycle pulse at the receive baud rate.

output logic rx_valid: Pulses when a complete character has been sampled.

output [7:0] rx_data: Received data byte, least-significant bit first on the wire.

output logic idle: Indicates that no character is currently being received.

output frame_err: Pulses when the sampled stop bit is low.

output rx_parity_err: Pulses when the received parity does not match.

input rx: Asynchronous serial receive input.

Generated register block

module uart_reg_top

Generated TileLink-to-UART register block.

Decodes software transactions, performs integrity and optional RACL checks, and exchanges typed register values with the UART core.

parameter bit EnableRacl = 1'b0: Enables register access-control checks.

parameter bit RaclErrorRsp = 1'b1: Converts a RACL denial into a TileLink error response.

parameter top_racl_pkg::racl_policy_sel_t RaclPolicySelVec [uart_reg_pkg::NumRegs] = '{uart_reg_pkg::NumRegs{0}}: Selects the RACL policy for each UART register.

input clk_i: Primary module clock.

input rst_ni: Active-low asynchronous reset.

input tlul_pkg::tl_h2d_t tl_i: TileLink device request channel.

output tlul_pkg::tl_d2h_t tl_o: TileLink device response channel.

output uart_reg_pkg::uart_reg2hw_t reg2hw: Software writes to hardware.

input uart_reg_pkg::uart_hw2reg_t hw2reg: Hardware updates for software reads.

input top_racl_pkg::racl_policy_vec_t racl_policies_i: Runtime RACL policy vector.

output top_racl_pkg::racl_error_log_t racl_error_o: RACL access-error log.

output logic intg_err_o: Sticky register or bus-integrity error indication.

localparam int AW = 6: Register address width.

localparam int DW = 32: Register data width.

localparam int DBW = DW / 8: Register byte-enable width.