2. Getting started¶

PRISM contains the canonical software library in repo/prism-ccl and the RTL and verification environment in repo/prism-hdl.

Run the tests¶

From the repository root, the recommended command is:

make test DOCKER=1

It builds the test image and runs the complete suite with the same runner used locally. Run a smaller suite while developing with:

make test SUITE=rtl-integration DOCKER=1

Use make env DOCKER=1 to print the environment and make build DOCKER=1 to check RTL elaboration without running tests. Remove DOCKER=1 only when Python, Verilator, Cocotb, and tshark are installed locally.

XML test reports are temporary and deleted by default. Preserve JUnit-compatible reports under build/prism-hdl/results/ with:

make test XML=1 DOCKER=1

Build the OpenNIC targets¶

The production integration targets the official OpenNIC Shell on Alveo U50 and Alveo U280. Install Vivado 2026.1 for U50 and Vivado 2022.1 for U280, together with the required device and CMAC licenses. Where GNU Make is installed, use:

make open-nic BOARD=au50
make open-nic BOARD=au280

The dependency-free Python CLI through uv is the native cross-platform entrypoint and does not require Make:

uv run --isolated python repo/prism-hdl/integrations/open-nic/build.py --board all

The integration profiles only select shell-facing resources; they do not fork or specialize the PRISM RTL:

Both use the same defaults (ISSUE_SLICES=4, ACCUMULATOR_RANGES=32, and KULISCH_ACC_W=279). These remain elaboration parameters: a constrained build may reduce capacity or exact-accumulator width without changing the protocol. The rates above are raw internal AXI capacities (width × clock), not Ethernet wire rates. Each OpenNIC CMAC is a 100 GbE port; Ethernet framing further reduces the application-level numeric payload carried on that physical link.

OpenNIC builds expose those values directly, for example:

make open-nic BOARD=au50 ACCUMULATOR_RANGES=64 \
  ISSUE_SLICES=4 KULISCH_ACC_W=279

Keep four issue slices to retain the documented full-beat rate for every input format. A smaller value is a deliberate area/throughput trade-off. A smaller Kulisch width remains functional and saturating, but operations that need more exact state report ACCUMULATION_INEXACT.

The script pins the OpenNIC revision and keeps its clone, generated projects, logs, reports, and bitstreams under the repository build/ directory. On Windows, the CLI also uses a short temporary drive mapping to stay below Vivado's path-length limits.

For a shell-only timing baseline with the pinned upstream P2P plugin, run make open-nic-reference BOARD=au280. It uses the same CMAC count and keeps its generated project separate from the PRISM build.

The pinned OpenNIC revision supports Vivado 2022.1, which is used for U280. Vivado 2026.1 is newer than its documented release range, so a successful U50 implementation is the compatibility proof for that target. Both targets must complete synthesis and implementation before a change is accepted.

Run standalone Vivado synthesis¶

The standalone project is a fast synthesizability check. It does not replace the complete OpenNIC implementation and timing reports.

make vivado BOARD=au50
make vivado BOARD=au280

The direct CLI is identical on Windows and Linux:

uv run --isolated python repo/prism-hdl/integrations/vivado/build.py --board au280

All generated projects, reports, logs, checkpoints, and bitstreams remain under build/ and are excluded from version control.

Windows without Make¶

Docker Desktop and PowerShell are sufficient. This command builds the image and runs the full suite in a container that is removed when the run finishes:

docker build --target test -t prism-hdl:dev -f repo/prism-hdl/Dockerfile .; if ($LASTEXITCODE -eq 0) { docker run --rm --mount "type=bind,source=$($PWD.Path),target=/work" --workdir /work --env PRISM_BUILD_DIR=/tmp/prism-build --env COVERAGE_FILE=/tmp/.coverage prism-hdl:dev }

DUT-observed captures are written to repo/prism-hdl/verification/traces/<test-name>/.

Where to start reading¶