The Three-Register Architecture

RouteRTL's registry isn't a single catalog. It's three separate registers, each answering a different question a user arrives with.

Each register has its own schema, its own storage, and its own lifecycle. They cross-reference through stable IDs (a ref design lists the IPs it uses:; a rule can scope to a specific part and ip_version), but they ship independently.

Why three registers and not one

Early RouteRTL had one catalog. It conflated three things:

1. Reusable building blocks (AXI FIFO, DMA bridge) — small, many, discovered by function.
2. Engineering judgement captured from debugging ("on Quartus 23.1 with Arria 10 LVDS_IO SGMII, the AN FSM ignores IF_MODE writes — go 1000BASE-X or GXB") — small, slow to write, consumed via automatic match at project check time, not search.
3. Complete projects you can actually build (Linux on Zybo, NIC on VCU118) — large, few, discovered by application + board.

Stuffing all three into one catalog meant bad UX for each:

• IPs drowned in reference-design-sized entries with different schema fields.
• Rules had to fit an IP-shaped schema they didn't need.
• Reference designs had no place to live at all — people cloned vendor repos that bit-rot.

Three registers, one interface pattern each.

IPs — rr pkg

The oldest and most mature register.

• Schema: ip.yml — see IP_MANIFEST_REFERENCE.md.
• Storage: github.com/djmazure/routertl-ip-index + Fly.io DB at registry.routertl.dev.
• CLI: rr pkg search|info|add|install|update|list|publish|verify.
• Web: routertl.dev/browse.

The description quality pipeline (P2.311–P2.332 in the CHANGELOG) governs what descriptions are allowed in:

• R1–R9 validator rejects copyright/license leaks, single-word names, code-fence residue, boilerplate, etc.
• Scanner self-heal retries via LLM when a tier produces a suspect result.
• Declaration filter excludes SV interface/package/class — only installable IPs land in the catalog.
• PR-triggered CI on curated_repos.json + weekly drift guard + submit endpoint gate keep the gate locked.

Current state: 878 entries, 99.3% clean (0 R1–R9 suspects on 15/878 entries that represent legitimate orphans pending cleanup).

Rules — rr rules

Engineering judgement from debugging sessions, captured as checkable claims.

• Schema: Rule dataclass at sdk/engine/ip_rules.py — see DESIGN_RULES_AGENT_WORKFLOW.md for how rules get captured.
• Storage: sdk/engine/builtin_rules.yml (shipped with the SDK) + project-local ip_rules.yml overrides. Future: hosted community rules store (RTL-P2.217).
• CLI: rr rules check|list|add.
• Web: none by design — rules are consumed at rr rules check time, not browsed by humans. Surfacing them as a web page would encourage "look at rules once" thinking; the value is automatic per-project matching.

Exact-provenance scoping (RTL-P2.333)

A rule scopes to the exact toolchain combination it was validated against:

- id: TSE-005
  vendor: altera
  tool: Quartus
  tool_version: "23.1"            # exact — no >=, no ranges
  family: [arria-10]
  part: [10AX115S2F45I1SG]        # exact part(s), not family fallback
  ip: altera_eth_tse
  ip_version: []                  # exact IP version(s), when applicable

Family-level scoping overclaims applicability. The TSE-005 debug was run on exactly one part; saying "affects the Arria 10 family" would spread the claim to parts we never tested.

Current canonicals

Eight built-in rules in sdk/engine/builtin_rules.yml:

• AVALON-001, AVALON-002 — Avalon-MM interface traps
• QUARTUS-001 through QUARTUS-003 — toolchain version/edition mismatches
• TSE-001 through TSE-004 — Triple-Speed Ethernet integration patterns
• TSE-005 through TSE-008 — the 2-week Arria 10 + Quartus 23.1 LVDS_IO SGMII debug journey (RTL-P2.323)

Reference Designs — rr ref

The newest and most user-facing register.

• Schema: ref_design.yml — see REF_DESIGN_MANIFEST.md.
• Storage: github.com/djmazure/routertl-ref-index (separate from routertl-ip-index).
• CLI: rr ref list|search|info|install|diff|publish.
• Web: routertl.dev/reference-designs.

The killer feature: reference designs resolve their IP dependencies through the version-pinned IP registry. Vendor reference designs bit-rot — files go missing, IP revisions change meaning, toolchain compatibility silently breaks. RouteRTL reference designs pin:

• The source repo commit SHA.
• The exact part number and tool version they were validated on.
• The exact ip_version of every IP in uses: — resolved fresh through rr pkg add at install time.

rr ref install — dual-mode

# Fresh scaffold (no project.yml in cwd)
rr ref install routertl/linux_zybo my_project/
cd my_project && rr pkg install && rr synth run

# Add as a target (project.yml present in cwd)
cd my_existing_project
rr ref install routertl/linux_zybo
rr target set linux_zybo && rr bit

The CLI detects which mode based on whether a project.yml is discoverable in the current directory. --force-target overrides the detection.

Cross-register linking

• Ref design → IPs: every uses: entry is a namespace/name@version reference into the IP register. Installing the ref design materialises those IPs via rr pkg add.
• Rules → ref design: rules scope via part: and ip_version: (RTL-P2.333). A ref design scaffolded into a new project gives the rules engine a known ToolchainContext, so rules that fire for that exact part + tool_version surface automatically at rr rules check time.

Reverse lookup

"Which reference designs use pulp-platform/axi_fifo?" — the registry catalog's uses: array answers this. Future work (RTL-P2.340) wires it into the web UI.

Lifecycle comparison

See also

• CHANGELOG.md — version-by-version feature log
• IP_MANIFEST_REFERENCE.md — IP register schema
• REF_DESIGN_MANIFEST.md — reference-design register schema
• DESIGN_RULES_AGENT_WORKFLOW.md — rules capture workflow