The synapsectl peripherals command group supports simulating, building, and deploying your peripheral stack. The build and deploy subcommands interact with the build system and the headstage, while the gateware subcommand provides tooling for code generation, simulation, and verification.
Note: Any command that builds the gateware needs a Lattice Radiant license. Set LM_LICENSE_FILE to a license file path or a port@host server before building. An unset license aborts the gateware build immediately.
Build
Initiates compilation of peripheral components
synapsectl peripherals build {driver | gateware | both} [peripheral_dir] [--clean]| Argument | Notes |
|---|---|
driver / gateware / both | Which components to build. both builds the driver .so and the FPGA .bit; driver skips the gateware container; gateware skips cmake/vcpkg. |
peripheral_dir | Path to the peripheral project. Defaults to the current directory. |
--clean | Clean build directories before compiling. |
Usage:
# Build both
synapsectl peripherals build both .
# Rebuild only the gateware, from a clean tree
synapsectl peripherals build gateware . --cleanDeploy
Installs a peripheral .deb on a headstage device over the network. Builds first unless you pass a pre-built package.
synapsectl -u "device-identifier" peripherals deploy {driver | gateware | both} [peripheral_dir] [--package PATH]| Argument | Notes |
|---|---|
-u "device-identifier" | The target device. This is a top-level synapsectl option, given before peripherals. |
driver / gateware / both | Which half of the code to build and deploy. |
peripheral_dir | Path to the peripheral project. Defaults to the current directory. |
--package PATH / -p PATH | Deploy a pre-built .deb and skip the local build. |
Usage:
# Build (if needed) and deploy both
synapsectl -u "my-device" peripherals deploy both .
# Deploy a package you already built
synapsectl -u "my-device" peripherals deploy both . --package dist/scifi-axon-test-source_0.1.0_arm64.debGateware commands
Access gateware-only subcommands.
synapsectl peripherals gateware <verb> [args...]generate
Generates project scaffolding from peripheral.yaml. Allocates any dev_peripheral_id (and writes it back into peripheral.yaml), scaffolds missing per-peripheral stubs (src/<name>_peripheral.sv, test/tb/<name>_tb.sv, test/tb/test_<name>.py — existing files are never overwritten), re-emits the derived files (src/via_top.sv, src/scir_sdk.rdf, and the framework region of src/scir_sdk.pdc / src/scir_sdk.sdc — your user-append constraints below the end marker are left untouched), and validates the project. It does not run Radiant.
synapsectl peripherals gateware generate [--diff | --force] [--keep PATH,...]| Flag | Notes |
|---|---|
--diff | Show what would change without writing anything (IDs are allocated in memory only). |
--force | Discard hand-edits to generated files and re-emit from the manifest. |
--keep PATH,... | Skip the listed derived files when regenerating. |
If you hand-edited a generated file, generate refuses to overwrite it until you pass --force. Your peripheral SystemVerilog and the # CUSTOMIZE:-marked regions in test files are never overwritten.
new
Scaffolds a fresh gateware project. You will rarely call this directly, as the example repository is already a scaffolded project. It writes a minimal skeleton (a peripheral.yaml with IDs omitted, README.md, .gitignore, test/conftest.py) and then runs generate to allocate IDs, scaffold the per-peripheral stubs, and emit the derived files.
synapsectl peripherals gateware new <dest> --peripherals a,b --target via-devkitsim
Runs the cocotb suites listed in each peripheral's verification.cocotb_tests against its testbench. Equivalent to pytest test/tb/test_<name>.py.
synapsectl peripherals gateware sim [--peripheral a,b] [-k FILTER] [--waves] [--sim verilator]--peripheral (-P) scopes the run to the named peripheral(s) and composes with -k.
build
Validates and re-emits the derived files, then runs Radiant to produce a bitstream under build/. Fails early if any dev_peripheral_id is still unallocated (run generate first).
synapsectl peripherals gateware build [--skip-validate]This is what synapsectl peripherals build both runs for the gateware. The target profile and implementation are currently fixed (via-devkit, full bitstream), so there are no --pdc or --impl flags to set.
deploy
Bundles a built bitstream (with its build-summary JSON and a peripheral.yaml snapshot) into a handoff archive.
synapsectl peripherals gateware deploy <bitstream> [--output PATH]list-profiles
Lists the board profiles the SDK ships, by canonical id.
synapsectl peripherals gateware list-profiles