# Dv Flow Manager > Create and modify DV Flow Manager (dfm) YAML-based build flows for silicon design and verification projects. Use when working with flow.yaml, flow.dv files, or dfm commands. Use when this capability is needed. - Skill: `tomevault-io/dv-flow-manager` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/dv-flow-manager` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dv-flow-manager/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/dv-flow-manager --- # DV Flow Manager (dfm) DV Flow Manager is a YAML-based build system and execution engine designed for silicon design and verification projects. It orchestrates tasks through declarative workflows with dataflow-based dependency management. ## When to Use This Skill Use this skill when: - Creating or modifying `flow.yaml` or `flow.dv` files - Writing task definitions for HDL compilation, simulation, or verification - Configuring dataflow between tasks using `needs`, `consumes`, `produces`, `passthrough` - Discovering tasks by their outputs using `produces` patterns - Validating dataflow compatibility between producer and consumer tasks - Setting up package parameters and configurations - Running `dfm` commands (run, show, graph, validate) - Debugging build flow issues - Working with standard library tasks (std.FileSet, std.Message, etc.) - Executing shell commands with `shell: bash` and `run:` - **Executing dfm commands from within an LLM-driven Agent task** ## Quick Reference ### Minimal Flow Example ```yaml package: name: my_project tasks: - name: rtl_files uses: std.FileSet with: type: systemVerilogSource include: "*.sv" produces: - type: std.FileSet filetype: systemVerilogSource - name: sim uses: hdlsim.vlt.SimImage needs: [rtl_files] consumes: - type: std.FileSet filetype: systemVerilogSource with: top: [my_top] ``` ### Key Commands ```bash # Run commands dfm run [tasks...] # Execute tasks dfm run -j 4 # Run with 4 parallel jobs dfm run --clean # Clean rebuild dfm run -c debug # Use 'debug' configuration dfm run -D param=value # Override parameter # Discovery commands (for humans and Agents) dfm show packages # List all available packages dfm show packages --json # JSON output for Agents dfm show tasks # List all visible tasks dfm show tasks --search kw # Search tasks by keyword dfm show task std.FileSet # Show detailed task info (includes produces) dfm show types # List data types and tags dfm show project # Show current project structure dfm context --json # Get full project context (for Agents) # Task discovery by outputs (uses produces) dfm show tasks --produces "type=std.FileSet,filetype=verilog" dfm show tasks --produces "type=std.FileSet" --json # Visualization dfm graph task -o flow.dot # Generate dependency graph # Validation dfm validate # Validate flow configuration dfm validate --json # JSON output for programmatic use ``` ### Expression Syntax Use `${{ }}` for dynamic parameter evaluation: ```yaml msg: "Building version ${{ version }}" iff: ${{ debug_level > 0 }} command: ${{ "make debug" if debug else "make release" }} ``` ## LLM Call Interface (Running Inside Agent Tasks) When running inside an LLM-driven `std.Agent` task, the `dfm` command automatically connects to the parent DFM session via a Unix socket. This enables LLMs to: - Execute tasks that share resources with the parent session - Query project state and task information - Validate configurations before execution ### Environment Detection When `DFM_SERVER_SOCKET` environment variable is set, `dfm` runs in client mode: ```bash # These commands work inside an Agent task: dfm run task1 task2 # Execute tasks via parent session dfm show tasks # Query available tasks dfm context --json # Get project context dfm validate # Validate configuration dfm ping # Health check ``` ### Running Tasks from Within a Prompt When an LLM needs to compile or simulate code it generated: ```bash # 1. Create RTL files cat > counter.sv << 'EOF' module counter(input clk, rst_n, output logic [7:0] count); always_ff @(posedge clk or negedge rst_n) if (!rst_n) count <= 0; else count <= count + 1; endmodule EOF # 2. Run compilation via parent DFM session dfm run hdlsim.vlt.SimImage -D hdlsim.vlt.SimImage.top=counter # 3. Check result (JSON output) # Returns: {"status": 0, "outputs": [...], "markers": []} ``` ### Querying Project State ```bash # Get full project context dfm context --json # Returns: # { # "project": {"name": "my_project", "root_dir": "/path/to/project"}, # "tasks": [{"name": "my_project.build", "scope": "root", ...}], # "types": [...], # "skills": [...] # } # Get specific task details dfm show task my_project.build --json # Returns detailed task information including parameters and dependencies ``` ### Benefits of Server Mode 1. **Resource Sharing**: Respects parent session's parallelism limits (`-j`) 2. **State Consistency**: Sees outputs from tasks already completed 3. **Cache Sharing**: Uses same memento cache for incremental builds 4. **Unified Logging**: All task output appears in parent session's logs ## Using Produces/Consumes for Task Discovery (AI Assistants) When helping users build workflows, use produces/consumes to identify compatible tasks: ### Finding Tasks by Output Type ```bash # Find all tasks that produce verilog files dfm show tasks --produces "type=std.FileSet,filetype=verilog" --json # Find tasks that produce any FileSet dfm show tasks --produces "type=std.FileSet" --json # Find tasks with specific output characteristics dfm show tasks --produces "type=std.FileSet,filetype=verilog,stage=compiled" ``` ### Understanding Task Relationships When a task needs specific inputs, find compatible producers: ```bash # 1. User wants to simulate - what tasks produce simulation inputs? dfm show tasks --produces "type=std.FileSet,filetype=verilog" --json # 2. Check what a specific task produces dfm show task VerilogCompiler --json # Look at "produces" field in output # 3. Validate compatibility before suggesting workflow dfm validate --json # Check for warnings about produces/consumes mismatches ``` ### Matching Logic **OR Logic**: If ANY consume pattern matches ANY produce pattern → compatible **Subset Matching**: Consumer can be less specific than producer ```yaml # Producer (more specific) produces: - type: std.FileSet filetype: verilog vendor: synopsys optimization: speed # Consumer (less specific) - MATCHES! consumes: - type: std.FileSet filetype: verilog ``` ### Building Compatible Workflows 1. **Identify user's goal** - What output do they need? 2. **Find producers** - `dfm show tasks --produces "type=..."` 3. **Check consumer requirements** - `dfm show task ConsumerTask` → look at consumes 4. **Validate** - `dfm validate` to check compatibility 5. **Suggest workflow** - Connect producer → consumer via `needs` ### Example: Building a Compilation Pipeline ```bash # User: "I need to compile and simulate my Verilog" # 1. Find verilog compilers dfm show tasks --produces "type=std.FileSet,filetype=verilog" --json # Returns: [VerilogCompiler, PreProcessor, ...] # 2. Find simulators that consume verilog dfm show task Simulator --json # Check consumes field: [{"type": "std.FileSet", "filetype": "verilog"}] # 3. Suggest workflow # - name: sim # uses: Simulator # needs: [VerilogCompiler] # Compatible! ``` ### Pattern Attribute Matching Match patterns by any attributes defined in produces/consumes: ```yaml # Common attributes for std.FileSet: filetype: verilog|systemVerilog|vhdl|... stage: preprocessed|compiled|optimized vendor: synopsys|cadence|mentor|... optimization: speed|area|power format: json|xml|ucdb|... # Custom types can have arbitrary attributes produces: - type: custom.BuildArtifact language: python arch: x86_64 debug: true ``` ### Validation Warnings If validation shows warnings, help fix them: ```bash $ dfm validate WARNING: Task 'Consumer' consumes [{'type': 'std.FileSet', 'filetype': 'vhdl'}] but 'Producer' produces [{'type': 'std.FileSet', 'filetype': 'verilog'}]. ``` **Solutions:** 1. Change consumer to accept verilog: `filetype: verilog` 2. Find different producer that outputs vhdl 3. Add converter task in between 4. Check if parameter can adjust producer's output ## Detailed Documentation For comprehensive documentation, see the following reference files: - [Core Concepts](references/concepts.md) - Tasks, packages, dataflow, types - [Task Reference](references/tasks.md) - Using and defining tasks - [Standard Library](references/stdlib.md) - Built-in std.* tasks - [CLI Reference](references/cli.md) - Command line interface - [Advanced Patterns](references/advanced.md) - Complex workflows and optimization - [Flow Schema](dv.flow.schema.json) - JSON Schema for flow.yaml validation ## Flow File Format DV Flow uses YAML files (`flow.yaml` or `flow.dv`) to define workflows. The file structure is validated against a JSON Schema located at `dv.flow.schema.json`. ### Schema Validation To validate your flow file or generate the schema: ```bash # Get the JSON Schema dfm util schema > flow.schema.json # Use with YAML validators (e.g., VS Code YAML extension) # Add to your flow.yaml: # yaml-language-server: $schema=./dv.flow.schema.json ``` The schema defines two root types: - **package** - Full project definition with tasks, types, configs, and imports - **fragment** - Reusable partial definition for inclusion in packages ## Core Concepts Summary ### Tasks Fundamental units of behavior. Tasks accept data from dependencies (`needs`) and produce outputs. Most tasks inherit from existing tasks using `uses`: ```yaml - name: my_task uses: std.Message with: msg: "Hello!" ``` ### Task Visibility Control which tasks are entry points and which are API boundaries: | Scope | Behavior | |-------|----------| | `root` | Entry point - shown in `dfm run` listing | | `export` | Visible outside package for `needs` references | | `local` | Only visible within its declaration fragment | | (none) | Package-visible only (default) | ```yaml # Entry point (shown in task listing) - root: build desc: "Build project" run: make build # Public API (other packages can use) - export: compile run: ./compile.sh # Both entry point AND public API - name: main scope: [root, export] run: ./main.sh ``` **Best Practices:** - Mark user-facing tasks as `root` so they appear in `dfm run` listing - Mark tasks other packages should depend on as `export` - Use `local` for helper tasks in compound task bodies - Tasks without scope are only visible within the same package ### Packages Parameterized namespaces that organize tasks. Defined in `flow.yaml` or `flow.dv`: ```yaml package: name: my_package with: debug: type: bool value: false tasks: - name: task1 uses: std.Message ``` ### Dataflow & Produces/Consumes Tasks communicate via typed data items, not global variables: - `needs: [task1, task2]` - Specify dependencies - `produces: [patterns]` - Declare what output datasets this task creates - `consumes: all|none|[patterns]` - Control what inputs reach implementation - `passthrough: all|none|unused|[patterns]` - Control what inputs forward to output **Produces/Consumes enable:** 1. **Task Discovery** - Find tasks that produce specific outputs 2. **Dependency Validation** - Check dataflow compatibility 3. **Relationship Understanding** - Identify which tasks can work together ```yaml # Producer declares outputs - name: VerilogCompiler produces: - type: std.FileSet filetype: verilog run: compile_verilog.sh # Consumer declares requirements - name: Simulator needs: [VerilogCompiler] consumes: - type: std.FileSet filetype: verilog run: simulate.sh ``` ## File Structure ``` project/ ├── flow.yaml # Main package definition ├── rundir/ # Task execution workspace (created by dfm) │ ├── cache/ # Task mementos and artifacts │ └── log/ # Execution traces └── packages/ # Optional sub-packages ``` ## Installation ```bash pip install dv-flow-mgr pip install dv-flow-libhdlsim # Optional: HDL simulator support ``` ## Detailed Documentation For comprehensive documentation, see the following reference files: - [Core Concepts](references/concepts.md) - Tasks, packages, dataflow, types - [Task Reference](references/tasks.md) - Using and defining tasks - [Standard Library](references/stdlib.md) - Built-in std.* tasks - [CLI Reference](references/cli.md) - Command line interface - [Advanced Patterns](references/advanced.md) - Complex workflows and optimization - [Task Development](references/task_development.md) - **Creating custom task implementations and plugin packages** (use when developing new tasks) **For dataflow and produces/consumes:** - See the User Guide: Dataflow & Produces (docs/userguide/dataflow.rst) for complete documentation - See docs/produces.md for quick reference --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/dv-flow) — claim your Tome and manage your conversions.