Config group reference

The packaged Hydra config tree is dau_build/config. Each subdirectory is a Hydra config group; selecting an option from a group is a CLI override of the form <group>=<option-path>. Options are addressed by their path relative to the group directory, so a file at config/task/tasks/sim/simulate.yaml is selected with task=tasks/sim/simulate.

The base config config/base.yaml declares the groups and their defaults:

defaults:
  - _self_
  - optional task: null
  - optional step: null
  - optional platform: null
  - optional board: null
  - optional backend: null
  - optional driver: null
  - optional memory: null
  - optional simulator: null
  - optional spec: null
  - optional plan: null
  - optional design: null

Every group is optional … null: nothing is selected unless you override it. A run selects task= to populate model, and may add spec=, board=, backend=, driver=, memory=, simulator=, platform=, host= and plan=.

Each option file begins with a # @package <key> directive that places its content under that top-level key. Tasks and steps use # @package model; the other groups use their singular key (# @package board, and so on).

Group	@package key	Instantiated model	Selects
task	model	a …Task ccflow.CallableModel	The unit of work to run.
spec	spec	dau_build.build_spec.BuildSpec	The build spec a task works on.
board	board	dau_build.build_config.BoardConfig	A board’s build-config view.
backend	backend	a SynthesisEngine (e.g. VivadoEngine)	The synthesis engine.
driver	driver	dau_build.build_config.DriverConfig	The host driver (OS + transport) in the resolved config.
memory	memory	dau_build.build_config.MemoryConfig	The build-time staging buffers in the resolved config.
simulator	simulator	a Simulator (e.g. VerilatorSimulator)	The simulator (used by SimulateTask).
platform	platform	dau_build.platforms.PlatformDefinition	The full physical platform definition.
plan	plan	a HardwarePlan (e.g. RecoveryPlan)	The hardware-session plan (HardwarePlanTask).
host	host	dau_build.build_config.HostConfig	The build host’s source checkout roots (none packaged).
design	design	(none packaged)	Reserved; registered by extension packages.

task

Packaged options (task=<path>):

tasks/build/build-shell-project
tasks/build/build-vivado-artifacts
tasks/build/overlay-build
tasks/build/render-cores
tasks/build/synthesize
tasks/build/synthesize-cores
tasks/hardware/hardware-plan
tasks/sim/simulate
tasks/spec/build
tasks/spec/inspect
tasks/spec/validate
tasks/stage/stage-shell
tasks/stage/stage-vivado-overlay
tasks/stage/stage-vivado-project
tasks/validate/validate-vivado-artifacts

Fields per task are in the task catalog.

spec

spec=specs/identity composes dau_build.build_spec.BuildSpec into the spec key; tasks read it through spec: ${oc.select:spec,null}, and it is the only way a task receives a spec. Your own spec is an option in a --config-dir overlay (<dir>/spec/specs/<name>.yaml with the _target_ and the fields). The packaged specs/identity option has base_dir: examples/identity, so it resolves only when run from the dau-build repository root.

board

board=boards/example/probe composes BoardConfig into the board key. Options live under boards/<vendor>/<board>. dau-build packages no real board; add yours from a search-path package. The only packaged option is the fictional example, boards/example/probe:

_target_: dau_build.build_config.BoardConfig
name: probe
platform: vivado-xdma
shell: xdma-ddr

BoardConfig fields: name (str), platform (str), shell (str).

backend

backend=backends/<name> composes a synthesis engine into the backend key. SynthesizeTask uses it as the engine (default backends/vivado); other tasks use its name and invocation as the resolved-config backend label.

Option	Model	Fields	Description
backends/vivado	VivadoEngine	name, invocation	Vivado handoff (FPGA bitstream flow).
backends/yosys	YosysEngine	name, invocation, frontend, yosys	Open-source synthesis; runs in CI.
backends/none	BackendConfig	name, invocation	No engine; a dry-run label.

The engines are polymorphic SynthesisEngine models, so every field is a Hydra override: backend=backends/yosys backend.frontend=slang, or +backend.<field>=.... YosysEngine.frontend is verilog (read_verilog -sv) or slang (yosys-slang); yosys sets the executable. The architecture explanation describes how the two engines differ.

driver and memory

driver=drivers/<name> and memory=memories/<name> compose a DriverConfig (os, transport) and a MemoryConfig (host_staging_bytes, device_staging_bytes) into the resolved build config, taking precedence over the spec-derived defaults (drivers/host = host/xdma; memories/default = zeros). They appear in the resolved-config step and are the axes a board or platform selects. Override them like any group, for example memory=memories/default memory.host_staging_bytes=4096.

simulator

simulator=simulators/<name> composes a Simulator model into the simulator key; SimulateTask uses it (default simulators/svparser).

Option	Model	Fields
simulators/svparser	SvparserSimulator	name
simulators/cocotb	CocotbSimulator	name, profile, profile_manifest
simulators/verilator	VerilatorSimulator	name, profile, profile_manifest, testbench_path, top_module, expect_stdout, verilator, extra_args

Like the engines, simulators are polymorphic models configured through overrides: simulator=simulators/verilator simulator.profile=<name>, or +simulator.<field>=....

platform

platform=platforms/example/probe composes dau_build.platforms.PlatformDefinition into the platform key. Options live under platforms/<vendor>/<board>.

dau-build ships exactly one, platforms/example/probe, and it is a fiction: internally consistent, plausible for a Kintex-7 x8 XDMA card, measured on nothing. It is the template you copy and the board dau-build’s own tests build against. Never build a real design with it. Your board belongs in your package, added through the Hydra search path with no dau-build source change.

A real board’s option is the authoritative definition of that board: part number, program method, ResourceBudget, storage_tiers, and a HostLink whose XdmaPersonality.params are its proven bring-up XCI parameters, quoted verbatim and in order, so the generated Vivado CONFIG.* block matches the known-good core byte for byte.

PlatformDefinition is made of:

• ResourceBudget (lut, ff, bram36, dsp).

• storage_tiers, each a StorageTier (name, technology, capacity_bytes, access, persistent, bandwidth_bytes_per_s, mig_prj, constraints_xdc); platform.memory selects the active shared tier.

• HostLink (interface, pcie_lanes, xdma_personality, expected_link_width, expected_link_speed_gts).

• The board-level constraints_xdc: pin constraint text the shell project generators emit behind their banner.

• lane_placements: the GT lane swizzle, applied as a pre-opt_design implementation hook. Empty means the board needs none.

• placeholders: names of hardware-derived values not yet measured on the board. require_measured rejects placeholder boards for real builds while config-only generation stays open.

• host_access (HostAccess: pci_id, endpoint_bdf, rescan_bdfs, runtime_pm_patterns, runtime_pm_executable, jtag_cable): the bench host’s measured access facts. A board option leaves this unset; a host option extending the board (platforms/<vendor>/<board>-<host>, composed from a --config-dir) sets it. HardwarePlanTask composes its toolchain config from these when platform= is selected; explicit task fields take precedence.

The shell project requests (MmJobShellRequest, MmDdrJobShellRequest) take a platform and default to dpv1; part defaults from the platform.

host

host=hosts/<name> composes dau_build.build_config.HostConfig: where the build host keeps its source checkouts (dau_core_root, dau_driver_root, dau_utils_root). dau-build packages no host options, because checkout layouts are site-specific; register them from a search-path package or a --config-dir overlay. The stage tasks and hardware plans interpolate their checkout roots from the composed host, and a direct <field>=... override always takes precedence.

plan

plan=plans/<name> composes a HardwarePlan model into the plan key; HardwarePlanTask delegates to it. Each plan owns its required fields, so pydantic enforces them rather than a runtime check.

Option	Model	Extra fields
plans/build-and-program	BuildAndProgramPlan	none
plans/local-build-and-program	LocalBuildAndProgramPlan	dau_core_root (from host= or plan.dau_core_root=), source_shell_root, dau_utils_root, overlay_tcl, smoke_command, python, vivado_settings
plans/validate-bitstream	ValidateBitstreamPlan	smoke_command, dau_utils_root, python
plans/flash	FlashPlan	dau_utils_root, python, vivado_settings
plans/sram-program	SramProgramPlan	deadman_timeout_s, verify_command
plans/recovery	RecoveryPlan	none
plans/thunderbolt-hold	ThunderboltHoldPlan	none
plans/thunderbolt-release	ThunderboltReleasePlan	none

Configure a plan with plan.<field>=…; see Program a bitstream on a board.

design

Declared in the defaults (optional design: null) but no option is packaged in dau-build. It is the reserved group for higher-level design and tile compositions registered by extension packages on the search path.

callable

callable is a plain key in base.yaml, not a group. callable: /model tells ccflow’s cfg_run which registry entry to run. Override it with callable=/<entry>. The evaluator (GraphEvaluator + MemoryCacheEvaluator through MultiEvaluator) is wired by cli.model in the same file.