SDK Behavior Contract

Status: Living specification — maintained alongside the codebase.

This document is the single truth source for what the RouteRTL SDK must do automatically and what the consumer is responsible for. Use it to validate SDK behavior, write tests, and guide new features.

1. Source Discovery

1.1 Explicit Sources

1.2 Auto-Injected Sources

Parity Rule: Every entity/package available in the submodule workflow (vendor/routertl/src/units/) must be equally discoverable in the pip workflow. If a consumer can entity tich.X in submodule mode, it must also work in pip mode without extra configuration.

1.3 Gitignore Filtering

• Files inside .gitignore-matched directories are excluded by default
• Exception: Files under an explicitly-requested --src path are always included (prevents pip SDK paths like .venv/site-packages/... from being filtered)
• Disable with --no-respect-gitignore

1.4 Gitignore Management (Pre-Build Outputs)

• rr ws update-config syncs hooks.pre_build[*].expected_outputs into .gitignore using an idempotent sentinel block
• If outputs are added/changed, the sentinel block is replaced (not duplicated)
• If hooks are removed, the sentinel block is cleaned up
• Paths containing .. or starting with / are silently skipped (safety)
• No-op if .gitignore doesn't exist (consumer must create it via rr init)

1.5 Path Resolution and Source Scanning

The paths.* fields control directory scanning (rr ws update), not the actual build file list (that is sources.syn).

Multi-directory union: When paths.sources is a list, all directories are scanned and results are deduplicated against existing sources.syn entries before insertion. Files retain their relative project-root paths.

1.6 RTL Testbenches vs. Python Tests

Contract: These are separate file types serving separate purposes. A tb_* VHDL file wraps the DUT for HDL simulation; a test_*.py file drives the simulation via Cocotb's Python API. Consumers must populate both for a complete verification flow.

1.7 Auto-Sources Merge Semantics

When auto_sources: true, the DependencyResolver crawls from project.top_module and appends resolved files to sources.syn.

Contract:

• Resolved files must not replace existing sources.syn entries
• Duplicates must be skipped silently
• Results must be cached in .routertl_cache/dependencies.json

The resolver uses paths.sources for its search directories (supports both string and list forms). Falls back to src/ if unset.

1.8 Configuration Precedence Chain

Values flow through multiple layers. Later layers override earlier ones:

SDK defaults → project.yml → build_env.mk (?= only) → CLI arguments

?= (conditional assignment) only takes effect if the variable is not already set. := (unconditional) always overrides. Vendor-specific version fields emit := to guarantee precedence over the generic tool_version.

2. Dependency Management

2.1 XPM Library (Vendor Primitives)

The XPM library provides VHDL simulation models for Xilinx primitives (FIFOs, CDCs, etc.). Any unit that uses library xpm; use xpm.vcomponents.all; requires these stubs.

2.2 Unisim Library (Xilinx Primitives)

The unisim library provides VHDL simulation models for Xilinx I/O and clock primitives (BUFG, IBUFDS, MMCM, etc.). SDK utility wrappers (unisim_bufg_wrap.vhd, unisim_ibufds_wrap.vhd, unisim_mmcm_wrap.vhd) use library unisim; use unisim.vcomponents.all;.

Resolved (P1.50): The linting command now calls ensure_ghdl_unisim() from vendor_libraries.py before invoking the smart linter. The 5-tier cascade (precompiled → Vivado → cached → download → actionable warning) handles all environments automatically.

2.3 Custom Libraries

Custom libraries (e.g. tich) are auto-discovered from source code via library <name>; declarations and entity <lib>.X instantiations.

Contract:

• Auto-discovery must find all library members without manual config
• Package pre-compilation into the library must precede entity compilation
• Topological sort must handle intra-library dependencies
• Manual libraries.json overrides act as extensions, not requirements

2.4 Transitive Dependencies

The rr deps fetch system resolves transitive dependencies from ip.yml manifests. Each dependency declares:

dependencies:
  xpm_vhdl:
    url: https://github.com/fransschreuder/xpm_vhdl.git
    fallback_url: https://github.com/djmazure/xpm_vhdl.git
    path: libs/xpm_vhdl
    library: xpm        # maps to XPM_FILES in build_env.mk

Contract: If a dependency has library: xpm, its source files must be exported as XPM_FILES and precompiled before any consumer source that references library xpm.

2.5 Vendor and Simulator Selection

Vendors: The SDK recognizes xilinx, intel, altera, lattice, and microchip. altera and intel are treated as equivalent — both resolve to the Quartus toolchain. As of 2025, Intel divested the FPGA business and Altera recovered its original name, so altera is the preferred value for new projects.

Simulators: The SDK supports nvc, ghdl, questa, verilator, icarus, and riviera.

Auto-selection: When no simulation.simulator is configured and the design contains only Verilog/SystemVerilog sources with no VHDL, the SDK auto-switches to verilator. Conversely, if the configured simulator is verilator but VHDL sources are detected, the SDK emits a warning.

3. Linting Pipeline

3.1 Phase Ordering

Phase 1:   PRECOMPILE     → XPM stubs, utility pkgs, project pkgs
Phase 1.5: COMPILE_LIB    → Custom libraries (topo-sorted)
Phase 2a:  LINT (VHDL)    → Hierarchy files via GHDL
Phase 2b:  LINT (SV)      → SystemVerilog files via Verilator

Contract: Each phase must complete before the next begins. Failure in Phase 1 or 1.5 must halt the pipeline with a clear diagnostic.

3.2 Incremental Compilation

• GHDL work directories persist in sim/work/
• Files are skipped when their timestamp matches the cached .cf catalog
• rr linting --clean or rm -rf sim/work/ forces full recompilation
• Stale work directories are auto-detected via .cf health check

3.3 Exit Code Contract (Dual-Mode Architecture)

smart_linter.py always exits 0 regardless of lint result. The actual status is written to sim/lint.status. Consumers must read sim/lint.status for CI integration.

Why exit 0? The linter is invoked by both Make targets and the Python CLI. Make aborts the entire recipe on non-zero exit, preventing multi-hierarchy analysis. The exit 0 + status-file pattern lets all hierarchies complete before the caller inspects the result.

Three consumers read sim/lint.status:

1. rr linting — reads the file and sets the CLI exit code
2. tools/githooks/pre-commit — gates commits on status ≠ 0 (P1.33)
3. project-pre-commit — consumer hook, same gate (P1.33)

Do NOT change exit_with_status() to propagate the real exit code without updating all three consumers.

4. Pip vs. Submodule Parity

Every CLI command must produce identical functional results regardless of install method.

5. Error Taxonomy

5.1 SDK Bugs (Must Fix)

Failures where the SDK silently produces wrong results or fails without actionable diagnostics:

• Missing entity in auto-discovered library (source file not in --src)
• Unisim stubs needed but not precompiled (P1.50 — resolved)
• Custom library package compiled after entity that depends on it

5.2 Consumer-Fixable Issues

Failures that require consumer action, with clear error messages:

• GHDL/Verilator/Icarus not installed → rr doctor diagnostic
• Missing project.yml → rr init suggestion
• Uncloned dependency → rr deps fetch suggestion
• Invalid entity name → _clean_top() validation

5.3 Environment Limitations

Known limitations that cannot be fixed by either SDK or consumer:

• GHDL+Cocotb 2.0+ HierarchyArrayObject errors on scalar signals
• Vendor tools not available (no license, no installation)

6. Test Oracle Rules

Each contract clause maps to a testable assertion:

7. Python Dependency Contract

Every third-party package imported anywhere in the shipped SDK (sdk/, sim/, routertl_core/, src/, tcl/) must be declared in pyproject.toml → [project].dependencies.

No silent crashes. If a pip consumer runs pip install routertl and then invokes any rr command or simulation flow, it must work without additional pip install steps. There are no optional simulation dependencies — cocotb is the simulation engine.

7.1 Declared Dependencies (Audit: 2026-03-13)

7.2 Vendored / Editable Dependencies

7.3 Dev-Only (Not Shipped)

8. Hook API Contract

Pre-build hook scripts must use sdk.api.tools for vendor tool resolution instead of calling shutil.which() directly.

8.1 Public API Surface

8.2 Resolution Contract

resolve_tool_binary("quartus_sh") must:

1. Check hardware.tool_path from project.yml first
2. Probe vendor-specific subdirectories (bin/, quartus/bin/, Vivado/bin/, Designer/bin/, Designer/bin64/)
3. Fall back to shutil.which() only if tool_path is unset or the binary is not found under it

Contract: The tool_path binary must always take priority over whatever is on system PATH. This prevents edition mismatches (e.g. Quartus Pro on PATH vs Standard in project.yml).

8.3 Backward Compatibility

sdk.cli.commands.license re-exports resolve_tool_binary for backward compatibility. Existing code using the old import path continues to work. New code should import from sdk.api.tools.