# 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 `=`. 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: ```yaml 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 ` 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=`): ```text 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](tasks-and-steps.md). ## `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 (`/spec/specs/.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//`. dau-build packages no real board; add yours from a search-path package. The only packaged option is the fictional example, `boards/example/probe`: ```yaml _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/` 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.=...`. `YosysEngine.frontend` is `verilog` (`read_verilog -sv`) or `slang` (yosys-slang); `yosys` sets the executable. The [architecture explanation](../explanation/architecture.md) describes how the two engines differ. ## `driver` and `memory` `driver=drivers/` and `memory=memories/` 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/` 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=`, or `+simulator.=...`. ## `platform` `platform=platforms/example/probe` composes `dau_build.platforms.PlatformDefinition` into the `platform` key. Options live under `platforms//`. 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//-`, 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/` 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 `=...` override always takes precedence. ## `plan` `plan=plans/` 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.=…`; see [Program a bitstream on a board](../how-to/program-hardware.md). ## `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=/`. The evaluator (`GraphEvaluator` + `MemoryCacheEvaluator` through `MultiEvaluator`) is wired by `cli.model` in the same file.