ip.yml Reference

Complete field reference for the RouteRTL SDK IP manifest file.

Run routertl ip init (or rr ip init) to generate an ip.yml interactively.

Quick Reference

Sections

ip

IP identity. Used for display, library mapping, and language detection.

ip:
  name: uart_core          # IP name (required)
  library: uart_lib         # VHDL library (default: work)
  language: vhdl            # vhdl | systemverilog | mixed

paths

Source scan directory. Only relevant for synthesis.mode: rtl.

paths:
  sources: src              # Scanned by rr update --ips / rr ip update

synthesis

Build mode and source files. The mode field determines how the IP is handled during synthesis.

synthesis:
  mode: rtl                 # rtl | xci | qsys | ipx | cxz | netlist | ooc_dcp
  sources:
    - src/uart_tx.vhd
    - src/uart_rx.vhd

Mode Reference

Vendor Compatibility Matrix

A mismatch between project.yml vendor and ip.yml mode will fail the build with a clear error message.

ips

Child IP dependencies. Resolved recursively (depth-first). Circular dependencies are detected and rejected.

ips:
  - ../fifo_ip/ip.yml       # Relative to this ip.yml
  - ../crypto_ip/ip.yml

CLI Commands

Quick Edit with rr config

# Read IP fields
rr config -f ip/uart/ip.yml get ip.library

# Change library or language
rr config -f ip/uart/ip.yml set ip.library uart_lib
rr config -f ip/uart/ip.yml set ip.language systemverilog

# Inspect all fields
rr config -f ip/uart/ip.yml list --flat

Examples

RTL IP (compiled with project)

ip:
  name: uart_core
  library: uart_lib
  language: vhdl

paths:
  sources: src

synthesis:
  mode: rtl
  sources:
    - src/uart_tx.vhd
    - src/uart_rx.vhd
    - src/uart_pkg.vhd

Xilinx XCI IP (vendor-managed)

ip:
  name: axi_fifo

synthesis:
  mode: xci
  sources:
    - axi_fifo.xci

Pre-compiled Netlist

ip:
  name: crypto_core

synthesis:
  mode: netlist
  sources:
    - crypto_core.edf

RTL IP with Child Dependencies

ip:
  name: uart_subsystem
  language: vhdl

paths:
  sources: src

synthesis:
  mode: rtl
  sources:
    - src/uart_subsystem.vhd

ips:
  - ../uart_core/ip.yml       # RTL dependency
  - ../axi_fifo/ip.yml        # XCI dependency

project.yml Integration

Reference IP manifests in your project.yml:

sources:
  syn:
    - src/top.vhd
  ips:
    - ip/uart_core/ip.yml
    - ip/axi_fifo/ip.yml
    - ip/crypto_core/ip.yml

Files from mode: rtl IPs are automatically appended to SYN_FILES. Vendor IP files populate XCI_FILES. Netlists populate NETLIST_FILES.

IPs as Git Submodules

Reusable IP blocks can be managed as git submodules within your project. Each IP submodule contains its own ip.yml manifest, making it a self-describing, version-controlled component.

Project layout

my_project/
├── vendor/routertl/              ← SDK submodule
├── ip/
│   ├── uart_core/                ← IP submodule (its own git repo)
│   │   ├── ip.yml                ← IP manifest
│   │   ├── src/
│   │   └── sim/
│   ├── dsp_filter/               ← another IP submodule
│   │   ├── ip.yml
│   │   ├── src/
│   │   └── vendor/math_lib/      ← nested submodule inside IP
│   └── local_glue/               ← regular directory (not a submodule)
│       └── ip.yml
├── project.yml
└── .gitmodules

Setup

1. Add the IP as a submodule:

   git submodule add https://git.example.com/uart_core.git ip/uart_core
   

2. Add an ip.yml to the IP (if it doesn't have one):

   cd ip/uart_core
   rr ip init
   

3. Reference it in project.yml:

   sources:
     ips:
       - ip/uart_core/ip.yml
       - ip/dsp_filter/ip.yml
   

4. Clone with recursive submodules:

   git clone --recurse-submodules https://git.example.com/my_project.git
   

Health checking

rr doctor automatically verifies all git submodules recursively. If a team member clones without --recurse-submodules, the doctor reports exactly which submodules are missing — including nested ones:

❌ Submodule (uart_core)   not initialized: ip/uart_core
❌ Submodule (math_lib)    not initialized: ip/dsp_filter/vendor/math_lib
   → Initialize submodules after cloning
     $ git submodule update --init --recursive

Any git repository can become a RouteRTL-managed IP just by adding an ip.yml file to its root. The SDK discovers it through project.yml → sources.ips references — the IP does not need to know anything about the consuming project.

Path Resolution

All paths inside ip.yml are relative to the ip.yml file's directory, not the project root. The resolver converts them to project-relative paths for the build system.