Skip to content

[dv] Add initial UART16550 UVM smoke bench and testplan - #18

Draft
bonnie-banks123 wants to merge 10 commits into
dv/uart16550-dv-depsfrom
dv/v1-smoke
Draft

bonnie-banks123 wants to merge 10 commits into
dv/uart16550-dv-depsfrom
dv/v1-smoke

Conversation

@bonnie-banks123

@bonnie-banks123 bonnie-banks123 commented Nov 19, 2026 •

Copy link
Copy Markdown

Depends on #19. This PR targets dv/uart16550-dv-deps so its diff shows only the 13 UART bench/project files, with no imported OpenTitan files. Merge #19 first, then retarget this PR to main; do not merge the bench into the dependency branch.

Adds an initial UVM smoke bench and a source-backed testplan. The smoke checks reset/configuration, four TX frames and four RX bytes at 50 MHz / approximately 1 Mbaud / 8N1, with bounded waits, independent data comparisons and explicit completion checks. Expected behavior comes from TI SNLS378C and documented wrapper exceptions.

Uses the pinned TL/UART/alert agents supplied by #19, straightforward register-access helpers, interface assertions and DVSim smoke/nightly selections. Full RAL/CSR suites, exhaustive features and coverage closure remain later work. Existing RTL is unchanged.

Validation after the split, at 3837f9a:

  • Fresh Xcelium 24.03-s007 / DVSim 1.33.0 smoke with SHM waves passes.
  • Wrong-RX control reports the expected RBR mismatch (0xAB versus 0xAA) and DVSim exits 1; the restored clean nightly-selection smoke passes.
  • Original lint/pre-DV, REUSE, commit metadata and diff checks pass.
  • All UART functional files are byte-identical to the previously reviewed head dfa640b. The earlier ten-seed and six-control qualification remains recorded at its actual revision b424bde; it has not been relabelled as newly run. Only dependency selection and unused software-build configuration changed during the split.

The dependency PR removes 48 unused tooling files from the original combined import. Its remaining CSR utility classes are transitive agent dependencies, not a full CSR test suite.

Run instructions, specification references and earlier results are in hw/ip/uart16550/doc/dv/README.md. This is an initial bench, not full V1 sign-off or scheduled Mocha integration; the latter remains tracked in lowRISC/mocha#806. PRs #13/#14 remain separate work.

The repository's PR CI targets main; it will run again after this stacked PR is retargeted to main. The checks above were executed locally on the new head.

Closes #17. Part of #15; implements the contract from #16.

Add a DVSim testplan and a short DV page that define the V1 smoke test
before the bench is written: fixed 50 MHz / 1 Mbaud 8N1 configuration,
reset readback values, divisor programming, TX and RX bytes, expected
counts, bounded waits, end-of-test checks and negative controls.

Expected values come from the TI PC16550D datasheet (SNLS378C) and the
wrapper's documented exceptions. V2 and V3 testpoints only list later
work. No bench or test is implemented yet.

Signed-off-by: Colin McKellar <colser@live.co.uk>
Address the first contract review of the V1 smoke plan:

- Keep passive alert protocol checking in V1 through an alert receiver
  agent with legal alert_rx_i wiring. Only directed alert fault
  injection and pings move to the V2 alerts testpoint.
- State the LSR clear-on-read expectations for OE, PE, FE, BI and
  LSR[7] in the V2 rx_errors testpoint, and cite the wrapper README for
  errored characters not being pushed into the RCVR FIFO.
- Describe 8N1 as the single selected smoke mode, since the wrapper
  also supports parity.
- Start the per-access TL-UL deadline when the request is first
  presented, so it covers waiting for a_ready.

Signed-off-by: Colin McKellar <colser@live.co.uk>
Address the second contract review (F04, F05):

- rx_errors (V2): LSR[7] is the OR of PE, FE and BI only
  (doc/registers.md LSR row; datasheet Section 8.6.3 bit 7). An
  isolated overrun sets OE with LSR[7] = 0. A second LSR read with no
  new error reads all of OE, PE, FE, BI and LSR[7] as 0.
- Name the pinned OpenTitan agent correctly: alert_agent
  (lowrisc:dv:alert_agent) at 012fb0fe; alert_esc_agent does not exist
  there. Record what it checks: known-value assertions in alert_if,
  init handshake and acks from the receiver driver, and integrity
  failures and alerts published on m_alert_port. The monitor does not
  raise errors itself, so the environment reports any item as an
  error. Pings are kept out of the test window.

Signed-off-by: Colin McKellar <colser@live.co.uk>
The alert handler theory of operation (OpenTitan 012fb0fe,
hw/top_earlgrey/ip_autogen/alert_handler/doc) defines an in-band
initialization in which the receiver deliberately places signal
integrity errors on ack/ping and the sender acknowledges with
alert_p == alert_n. The contract's "always legal differential values"
was therefore too strong.

Split the smoke's alert checks into a bounded initialization phase
(1000 clock cycles after reset, invalid pairs allowed) and normal
operation (all three pairs correctly encoded, no native alert, no item
from the agent monitor).

Signed-off-by: Colin McKellar <colser@live.co.uk>
Add the V1 smoke bench defined by doc/dv/README.md:

- tb: DUT at 50 MHz with tl_if, uart_if and alert_if, documented
  tie-offs, tlul_assert bound to the TL-UL port, and assertions that
  the never-enabled interrupts stay low.
- env: plain uvm_env with the OpenTitan tl_agent (host), uart_agent
  (1 Mbaud, 8N1) and alert_agent (receiver). It checks decoded TX
  frames in order against expected bytes (unexpected, wrong and
  badly framed frames are errors) and the alert channel: bounded
  initialization, then correct encoding and no alert.
- uart16550_smoke_test: reset readback, configuration, 4 TX and 4 RX
  bytes, quiet window and end checks, with every wait bounded. Expected
  values are constants from the contract. +smoke_fault=<name> selects
  a negative control that changes only the stimulus.
- FuseSoC core lowrisc:dv:uart16550_sim and DVSim configuration with
  smoke and nightly regressions. A run passes only with both "TEST
  PASSED CHECKS" and the test's end-check marker in the log.

The bench resolves with FuseSoC and DVSim (dry run) but has not been
simulated yet.

Signed-off-by: Colin McKellar <colser@live.co.uk>
- R2: map the unimplemented V2/V3 testpoints to no test. Their
  descriptions keep the planned stimulus and checks. DVSim no longer
  reports errors for nonexistent tests.
- R3: assert that cio_tx_o is known out of reset. The UART agent
  stores decoded bits two-state, so an X would otherwise read as 0.
- R4: describe RX checking as it is implemented (one byte at a time
  against a fixed list, counted; no RX queue), add --reseed 1 to the
  single-seed recipe, record the seed-1 and negative-control results
  at 33016fe with qualification still pending, and link the DV page
  from the top-level README.

The doc page also lists the rx_frame_err control added next.

Signed-off-by: Colin McKellar <colser@live.co.uk>
Add the default-off +smoke_fault=rx_frame_err control. Before the
first RX byte it drives one frame with a 0 stop bit directly on
cio_rx_i (framing error; such frames are not pushed into the RCVR
FIFO, README.md), then polls LSR while the first valid byte is still
arriving. Early polls see FE and LSR[7] with DR = 0, and the LSR read
clears them (datasheet Section 8.6.3). No error is expected, so the
test must fail.

Each LSR poll read is now logged at UVM_MEDIUM. The polls themselves
still check only the ready bits, so this control is expected to pass
wrongly at this revision; that run demonstrates the gap fixed next
(review finding R1). Expected values are unchanged.

Signed-off-by: Colin McKellar <colser@live.co.uk>
Review finding R1. An LSR read clears OE, PE, FE, BI and LSR[7]
(datasheet Section 8.6.3), so an error seen by an early poll read was
cleared before the final read, which was the only one checked. The
upper 3 bytes of polled reads (registers.md: read 0) were not checked
either.

Check every poll read before the next one: upper 3 bytes are 0 and
OE, PE, FE, BI and LSR[7] are clear. DR, THRE and TEMT may change
while polling. The separate error check after the RX poll is now
redundant and is removed.

At 15b14b1 the rx_frame_err control passed wrongly (DVSim exit 0, poll
read 0xE8 then clean reads), confirming the gap. Record that, keep the
control default-off as checker QA, and update the contract text. The
fixed check has not been simulated yet.

Signed-off-by: Colin McKellar <colser@live.co.uk>
Replace the outdated status paragraph in the DV page with the results
at b424bde: the clean smoke and ten seeds pass, and each of the six
negative controls fails with DVSim exit status 1 for its intended
reason. The page also notes the existing flow, REUSE and commit checks,
and that the tool-failure control was not run.

Keep the before/after explanation of the rx_frame_err control in
short form, and state the scope: an initial bench, not a V1 sign-off
or a scheduled Mocha nightly run.

Documentation only; the bench, configuration and RTL are unchanged.

Signed-off-by: Colin McKellar <colser@live.co.uk>
The project DVSim configuration imported OpenTitan's bazel.hjson only to
define the software-build keys that DVSim requires. No test uses
software images, and bazel.hjson is no longer vendored. Define the two
keys as empty instead.

The pass/fail patterns, simulator settings and debug modes are
unchanged.

Signed-off-by: Colin McKellar <colser@live.co.uk>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[dv] Implement and validate the basic UART16550 UVM smoke bench

1 participant