Contract-first verification
Contract-first verification makes the intended interface and behavior of an
IP explicit before tests are written. The contract lives in
requirements.yml; rr checks the HDL against it and maps each requirement
to a test with a substantive assertion.
This page is the short route into the workflow. The full walkthrough explains each field and failure mode in detail.
The shipped protocol contracts
The SDK includes 14 protocol contracts. Each one defines the handshake, ordering, reset, and protocol-specific requirements that its tests can cover.
| Contract | Requirement focus | Specification basis |
|---|---|---|
| AXI4 master | handshakes, bursts, 4 KiB boundaries, IDs, reset | ARM AMBA AXI4 |
| AXI4 slave | bursts, responses, IDs, strobes, transfer size | ARM AMBA AXI4 |
| AXI4-Lite master | channel handshakes, address/data ordering, reset | ARM AMBA AXI4-Lite |
| AXI4-Lite slave | address, size, response, write strobes, reset | ARM AMBA AXI4-Lite |
| AXI-Stream master | valid/ready stability, TLAST, TKEEP, reset | ARM AMBA AXI4-Stream |
| AXI-Stream slave | valid/ready acceptance, TLAST, TKEEP, reset | ARM AMBA AXI4-Stream |
| Avalon-MM master | waitrequest, reads, bursts, byte enables, reset | Intel Avalon-MM |
| Avalon-MM slave | waitrequest, read data/latency, bursts, byte enables, reset | Intel Avalon-MM |
| Avalon-MM classic master | cycle controls, stable transfers, reads, reset | Intel Avalon-MM |
| Avalon-MM classic slave | cycle controls, response timing, byte enables, reset | Intel Avalon-MM |
| Avalon-ST master | ready latency, SOP/EOP, empty, reset | Intel Avalon-ST |
| Avalon-ST slave | ready/valid flow, SOP/EOP, empty, channel, reset | Intel Avalon-ST |
| Wishbone B4 master | CYC/STB, stable controls, stall, reset | OpenCores Wishbone B4 |
| Wishbone B4 slave | cycle/response, select, stall, reset | OpenCores Wishbone B4 |
The protocol files are shipped under sdk/protocol_contracts/ in the SDK.
Their requirement IDs are the authoritative names used by contract coverage.
Start here
From a fresh project:
git clone https://github.com/your-org/your-ip.git
cd your-ip
pip install routertl
Scaffold a contract from the current HDL, then review it before treating it as an intended interface:
rr sim contract-init hw/ip/<name>/hdl/<name>.sv
Add requirements: requirements.yml to the IP's ip.yml. Then check the
declared shape and generate test stubs:
rr sim contract-check rr sim scaffold hw/ip/<name>
Replace every generated placeholder with a test that can fail when the DUT is wrong. Check that every requirement is anchored by a non-vacuous test:
rr sim coverage-map rr sim run --ip hw/ip/<name>
The passing gate is the combination of contract-check, coverage-map, and
the simulator run. Add the same checks to CI once the IP's contract is ready.
MCP for coding agents
Install the project-scoped MCP registration:
rr mcp install
The routertl-mcp server exposes three contract tools to MCP-capable agents:
| Tool | Use |
|---|---|
rr_ip_contract_init | Scaffold requirements.yml from an HDL file |
rr_ip_contract_check | Check declared ports and requirements against the HDL |
rr_ip_coverage | Report requirement-to-test coverage and vacuous tests |
The tools report structured results; the agent still has to review the scaffold, write real assertions, and resolve any failed requirement.