Workflows

External IP is materialized under vendor/ via Bender’s vendor_package feature. If a vendored tree is also consumed as a Bender package, the root dependencies: entry points at the local package root under vendor/; direct third-party git: dependencies are not used.

Vendored packages preserve upstream GitHub org/repo casing under vendor/<GitHubOrg>/<GitHubRepo>/. Bender materializes selected upstream files into upstream/ (wiped and refreshed by bender vendor init), then applies local patches. Patch files live in the sibling patches/ directory so they survive a refresh:

bender vendor init re-fetches the pinned commit, copies the selected files, excludes exclude_from_upstream: paths, and re-applies all patches from patch_dir in lexicographic order.

CI runs bender vendor diff --err_on_diff on every hardware-CI push so a stale upstream/ tree or a patch that no longer applies fails the gate.

C test images are built via the standard dispatcher:

Each subsystem’s tests link against one of that subsystem’s link modes — memory targets discovered from link/modes/*.ld (e.g. SMC: sram, rom; SEP: tcm) — and output artifacts fold the mode into their name (<test>.<mode>.elf, e.g. version_id.sram.elf). A test uses its subsystem’s default mode unless it overrides FW_TEST_MODE_<test>; see hw/common/dv/fw/compile.mk for the full mechanism.

Most SMC tests default to sram mode. The OCCP master BFM tests (occp_sanity, occp_master) are declared rom-mode in hw/sys/smc/dv/fw/fw.mk because they exercise the I3C master path and must run from the ROM address space. They link against the open-source weak I3C_GetDriverInstance stub (returns NULL) so the build is self-contained.

hw/sys/smc/bootrom/ holds two independent ROM firmware trees:

Build the dummy ROM with its standalone Makefile:

Outputs land under hw/sys/smc/bootrom/dummy/build/tests/dummy/ (e.g. dummy.rom.elf, dummy.rom.bin, dummy.rom.hex, plus .preload.hex / .spi variants from the shared SMC post-process step).

Build the production ROM from the same container (self-contained Makefile, not the shared compile.mk engine). See hw/sys/smc/bootrom/prod/README.md and the SMC Boot ROM appendix of the Programmer’s Guide for the full target list, build variables, and architecture.

The build splits across two halves so each runs in the right environment:

Build products land under build/release/ (or build/debug/ with BUILD_TYPE=debug): bin/ holds the ELF and binary image, hex/ the ROM formats, and disasm/ the disassembly.

hw/sys/sep/bootrom/prod/ is a self-contained production boot ROM for the SEP subsystem (VeeR EL2), with its own includes, drivers, and link script. It implements the full secure-boot flow — manifest loading, RSA-3072 signature verification on OTBN, optional AES payload decryption, PMP setup, and lifecycle enforcement — and uses weak stubs so the open tree links cleanly. A build that carries its own drivers overrides the stubs at link time: it passes the driver sources as OCAH_FW_OVERLAY_SOURCES_sep, and the include flags (-I<dir>) for their register headers as OCAH_FW_REG_OVERLAY_INCLUDE_DIRS_sep, on the make command line. The ROM takes the SMC registers it reaches through its SMC window from the generated SMC map; a build against another SMC map passes the include flags for that map as OCAH_FW_REG_OVERLAY_INCLUDE_DIRS_smc. The Makefile ignores these variables when they are set only in the environment, so a value exported in a shell cannot change an open-tree ROM. See hw/sys/sep/bootrom/prod/README.md and the SEP Boot ROM appendix of the Programmer’s Guide for the full target list, build variables, key provisioning, and boot flow.

The ROM supports two flash transports selected at build time by BOOT_SPI_CONTROLLER_OT; the unused driver is dropped by --gc-sections at link time. The default (BOOT_SPI_CONTROLLER_OT=1) uses the OpenTitan SPI host, and BOOT_OT_SPI_USE_PIO selects its RX-drain method (secure DMA by default, or CPU-programmed I/O). BOOT_SPI_CONTROLLER_OT=0 reads memory-mapped flash through the external XIP window; its controller driver is optional from the open tree’s perspective and is supplied by an integrator through the weak hooks in src/sep_spi.c.

The DV sep testbench has no SPI flash, so it boots instead from the SMC-SRAM manifest path: oca-images packs the non-secure boot-manifest image rebased to the SMC-SRAM base (build/oca_smc_mem.hex).

The build splits into two halves so each can run in the correct environment:

The manifest-tool submodule must be initialized before running oca-images:

DV test manifest configs live under configs/; the corresponding test signing keys are in tests/signing_keys/ (debug builds only — a release build reads public keys from release_signing_keys/ and refuses to produce images anchored on test keys).

Outputs land under hw/sys/sep/bootrom/prod/build/:

The pio-toolchain-images target builds the CPU-PIO drain ROM into build_pio/; the packed images stay under build/.

The Key Manager (KM) subsystem (PicoRV32) runs its firmware from ROM. That firmware is not only a boot loader: it is the KM runtime, serving the SEP mailbox, until the SEP loads alternative firmware into KM SRAM and hands over to it. It therefore lives in hw/ip/key_manager/approm/prod/ rather than a bootrom/ directory, and builds with a self-contained Makefile there. The Key Manager Application ROM appendix of the Programmer’s Guide describes the firmware.

The entry point is src/rom_main.c. The whole image — vectors, code, constants and the .data load image — links into the 16 KB ROM through link/km_production.ld.

Outputs land under hw/ip/key_manager/approm/prod/build/ (or BUILD_DIR):

SEP DV builds its own wipe-disabled copy through hw/sys/sep/dv/cocotb/tests/km_fw (make rom_main), which run_dv.py drives for tests that declare mode = "km_rom_main".

Most components use Cocotb Python tests. Some DUTs also have a nonfree UVM test workflow using VCS. The testbench is run and configured using a Python script. Run the following command to see all available options:

If you want to manage python dependencies yourself, rather than through uv, the environment variable OCAH_DV_SKIP_UV=1 may be set, in which case the system Python installation will be used.

To check that all testsuites are configured properly, run the following:

Use the --doctor flag to check the testbench environment for an individual configuration - note that while this will check for the presence of optional proprietary tools, these remain entirely optional.

Having selected a Device to Test with the --dut flag, use --list to print the available tests and testlists for the device.

To run an individual set of tests, list them using the --items flag.

This may similarly be used to run preconfigured test groups.

Further options, including seeds and regressions are available, consult the --help flag to see usage.

When debugging particularly difficult RTL issues, it is useful to be able to view the signals travelling between components. For this, a wave trace may be generated and inspected. To generate a trace, use the --waves argument.

Each test writes its trace to a waves/ directory beside its results in the run directory, with a debug_context.json listing the trace files and a command to open them. We use Surfer, which the container includes, for viewing wave traces; open a trace with surfer <trace>.

The --waves-on-fail flag may be used instead of --waves; it reruns only the tests that did not pass, with waves enabled.

With VP_CONTAINER=1 the container provides all of these.

To use the container to build and run the VP, set VP_CONTAINER=1

The repository provides optional, check-only hooks for staged Python, C/C++, Tcl, YAML, TOML, and shell files, plus a repo-wide spelling check. They run Ruff, clang-format, tclfmt, tclint, codespell, yamllint, tomllint, shellcheck, and shfmt from the locked uv environment, plus Git’s whitespace/conflict-marker check. The hooks do not modify or stage files. mypy, markdownlint, and checkmake are deliberately left out of this bundle — they are slow, need a separate Node.js toolchain, or ship as a standalone binary rather than a uv-managed package — and stay CI-only; see the CI job table above for their local commands.

Installation uses pre-commit’s standard local .git/hooks/pre-commit launcher. It does not change core.hooksPath, and no setup or checkout command installs it automatically. CI remains authoritative whether or not a contributor enables the hook.

.github/workflows/lint.yml runs lint-sv-slang, lint-sv-verilator, lint-python, lint-python-mypy, format-c, lint-tcl, lint-spelling, lint-sv-comments, lint-sv-enums, lint-yaml, lint-toml, lint-markdown, lint-make, lint-shell, regen-regs, and vendor-diff on pull requests and pushes to main (lint-sv-verible is temporarily disabled). Setup jobs share bender, Verilator, and reviewdog artifacts; jobs report through .github/actions/reviewdog-report. A Checks API HTTP 5xx is retried. lint-sv-verilator and lint-python still pass or fail on the tool exit status when that post does not succeed.

Documentation-only diffs (every changed path is under doc/, an Antora playbook, or a .md / .adoc / image) skip lint, Verilator smoke, the native VP legs, and the nonfree GitLab child; lint-vale, which checks documentation prose, runs on every diff. The required verilator-smoke (dtp) / (sep), sep-vp (native), smc-vp + smu-vp (native) and GitLab checks still report success. scripts/ci/diff_class.py --self-test checks the classifier. Scheduled and manually dispatched pipelines always run in full.

The regen-regs gate regenerates every register block’s collateral from the RDLs and fails if the working tree changes, so the committed **/regs/gen/ outputs (SystemVerilog, C headers, Python, RAL, IP-XACT, AsciiDoc, HTML) always match a fresh run. It is peakrdl-only (no bender or nonfree/), so a plain checkout reproduces it. To fix a failure, run the local command above and commit the result:

The vendor-diff gate re-clones every vendor_package remote, applies patches/, and fails if the committed upstream/ tree does not match. To fix a failure, refresh the tree and commit: