reference-driven-rohd

Reference-Driven ROHD

Overview

Writing a protocol or peripheral from memory is how you ship a design that is subtly wrong: a reserved bit in the wrong place, a handshake that almost matches the spec, an edge case the standard calls out that you never saw. The fix is cheap and boring: get the real sources first, then implement against them.

Core principle: Before writing custom ROHD, fetch the authoritative spec, the existing reference implementations, and any reusable library that already solves part of the problem. Implement from primary sources, not from recall. The spec is the oracle, the references show the behavior, the library saves the parts you should not rewrite.

When to Use

• Implementing a standardized block (a bus, a UART, an SPI controller, a CRC, an ECC, a CSR file, an ISA extension)
• Building something that must interoperate with hardware or software you do not control
• You are about to write RTL from your own memory of how the protocol works
• A datasheet, RFC, ISA manual, or vendor spec exists for what you are building

Skip for genuinely novel internal logic that has no external spec and no prior art.

Fetch The Sources First

Do this before writing a line of RTL. Three buckets, in order:

1. The authoritative spec. The actual standard, datasheet, or ISA manual, not a blog summary. RISC-V unprivileged/privileged manuals, the Wishbone B4 spec, a part's datasheet PDF, the protocol's RFC. Use WebFetch/WebSearch to pull it, and note the exact version and section numbers. A spec you cite by section is a spec you can be held to.
2. Existing reference implementations. Other HDL (Verilog/Chisel/SpinalHDL/migen), a C model, a vendor reference, an emulator. Clone or fetch them to read the behavior, especially the corner cases and reset values. These show you what the spec leaves ambiguous and how real implementations resolved it.
3. Reusable libraries. Check rohd_hcl and existing Midstall ROHD (River, Harbor) before writing anything new. A FIFO, ECC, ready/valid handshake, rotator, or arbiter is probably already there, tested. Compose it; do not reinvent it.