ref_design.yml Reference

Complete field reference for RouteRTL reference design manifests.

A reference design manifest describes a complete buildable FPGA project: target board, IP dependencies (resolved through the IP registry), source repo pointer, build command, and verification status. The routertl-ref-index GitHub repo stores these manifests under ref-designs/<org>/<name>/<version>.yml.

See THREE_REGISTER_ARCHITECTURE.md for context on how reference designs fit with IPs and Rules.

Quick Reference

Sections

ref_design

Identity block. What this reference design is.

ref_design:
  org: routertl                   # publisher namespace (required)
  name: linux_zybo                # slug, unique within org (required)
  version: "1.0.0"                # semver (required)
  description: "Linux booting on Zybo Z7 — Zynq PS+PL reference"
  license: MIT
  tags: [zynq, linux, zybo, ps-pl]

Deliberately NOT a field: difficulty. Technical skill on FPGA work varies by domain, not by project — labelling designs "beginner / intermediate / advanced" is judgmental framing the register shouldn't impose.

target

Board + toolchain binding. Exact values only — no semver ranges, no family fallbacks. If the design was validated on exactly one part + tool version, that's what goes here.

target:
  board: zybo-z7-20               # canonical board ID (required)
  vendor: xilinx                  # xilinx | altera | microchip | lattice
  family: zynq-7000
  part: xc7z020clg400-1           # exact part (required)
  tool: Vivado                    # Vivado | Quartus
  tool_version: "2024.1"          # exact — no >= / <= / commas

project

Top-level entity + language.

project:
  top_module: stereoVision_top
  language: vhdl                  # vhdl | vhdl-2008 | systemverilog | verilog | mixed

uses

IP dependencies. Each entry is a namespace/name@version pointer into the IP register, resolved at install time through rr pkg add.

uses:
  - { ref: open-logic/olo_intf_uart, version: "^4.4.1" }
  - { ref: fpganinja/taxi_axil_rom,  version: "1.0.3" }
  - { ref: pulp-platform/axi_fifo,   version: "^1.2.0" }

When a user runs rr ref install, every uses: entry becomes a rr pkg add <ref>@<version> call under the hood.

source

Git pointer for the design's source repo. Pinned commit SHA is required for reproducibility.

source:
  repo: https://github.com/djmazure/routertl-linux-zybo
  commit: abc123def456...

build

How to build the design from the scaffolded project root.

build:
  command: "rr project run && rr synth run && rr bitstream"
  expected_bitstream: "project/stereoVision_top.bit"
  estimated_time_minutes: 15

resources

Resource utilization from the last known successful build. Optional — surfaces on the detail page and helps users filter by fit.

resources:
  luts: 8200
  ffs: 6400
  bram_kbits: 256
  fmax_mhz: 100.0

All fields default to 0 / 0.0 and are treated as "not reported" at those values.

verification

Current verification state. Updated by the sandbox-synth pipeline (RTL-P2.339 — planned).

verification:
  last_verified_commit: "abc123"
  last_verified_tool_version: "2024.1"
  last_verified_date: "2026-04-19"
  status: claimed                 # claimed | sandbox-verified | community-verified

Seeds start at claimed. Sandbox verification upgrades the status automatically when the Phase 2 pipeline ships.

Validation

The schema validator (sdk/engine/ref_design_schema.py::validate_manifest) runs on:

• rr ref publish — locally, before the manifest is submitted.
• The routertl-ref-index CI — when a manifest PR lands.
• The registry.routertl.dev submit endpoint (future).

Hard-fail conditions:

• Missing required fields (org, name, version, description, target.board, target.vendor, target.part, target.tool, target.tool_version, project.top_module, project.language).
• version not in semver form.
• tool_version contains range operators (>=, <=, >, <, ,).
• language outside {vhdl, vhdl-2008, systemverilog, verilog, mixed}.
• verification.status outside {claimed, sandbox-verified, community-verified}.
• uses: entries with ref missing a slash.

Soft warnings (logged, not hard-fail):

• target.board not in boards.yml canonical list — so new boards don't block PRs.
• ip_version set without an ip field on a rule — the scoping is ignored but the rule still loads.

End-to-end example — seed manifest

A complete, valid manifest as the routertl/linux_zybo@1.0.0 seed will ship (pending the user's source-repo brush-up):

ref_design:
  org: routertl
  name: linux_zybo
  version: "1.0.0"
  description: "Linux on Zybo Z7 — Zynq-7020 PS+PL reference with stereo-vision processing pipeline"
  license: MIT
  tags: [zynq, linux, zybo, ps-pl, stereo-vision]

target:
  board: zybo-z7-20
  vendor: xilinx
  family: zynq-7000
  part: xc7z020clg400-1
  tool: Vivado
  tool_version: "2024.1"

project:
  top_module: stereoVision_top
  language: vhdl

uses:
  - { ref: open-logic/olo_intf_uart,        version: "^4.4.1" }
  - { ref: open-logic/olo_base_fifo_async,  version: "^4.4.1" }

source:
  repo: https://github.com/djmazure/routertl-linux-zybo
  commit: <sha-filled-at-publish>

build:
  command: "rr project run && rr synth run && rr implementation && rr bitstream"
  expected_bitstream: "project/stereoVision_top.bit"
  estimated_time_minutes: 20

resources:
  luts: 12400
  ffs: 9800
  bram_kbits: 512
  fmax_mhz: 150.0

verification:
  last_verified_commit: <sha>
  last_verified_tool_version: "2024.1"
  last_verified_date: "2026-04-19"
  status: claimed

See also

• sdk/engine/ref_design_schema.py — Python implementation
• sdk/engine/boards.yml — canonical board IDs
• THREE_REGISTER_ARCHITECTURE.md — how this fits with IPs and Rules
• IP_MANIFEST_REFERENCE.md — the IP register's schema
• DESIGN_RULES_AGENT_WORKFLOW.md — rule capture workflow