dv-flow-libfusesoc Documentation

DV Flow extension providing FuseSoC core management and Edalize tool integration.

Overview 

dv-flow-libfusesoc is a DV Flow extension that integrates FuseSoC IP core management with Edalize tool flows. It provides a unified interface for resolving FuseSoC cores and running simulations, synthesis, linting, and formal verification using various EDA tools.

Features 

FuseSoC Integration: Resolve and manage FuseSoC IP cores with automatic dependency resolution
Edalize Support: Unified interface to EDA tools via Edalize
Simulation Flows: Run simulations with Icarus Verilog, Verilator, ModelSim, VCS, Xcelium, and GHDL
FPGA Flows: Synthesis and implementation for Vivado, Quartus, and open-source tools
Linting: HDL code quality checks with tool-agnostic interface
Formal Verification: Formal property checking flows

Installation 

Install from PyPI:

pip install dv-flow-libfusesoc

Or install from source:

git clone https://github.com/your-org/dv-flow-libfusesoc.git
cd dv-flow-libfusesoc
pip install -e .

Quick Start 

Basic Simulation Flow 

from dv_flow.libfusesoc.fusesoc_core_resolve import CoreResolve
from dv_flow.libfusesoc.edalize_sim import SimConfigure, SimBuild, SimRun

# 1. Resolve FuseSoC core
core_result = await CoreResolve(runner, CoreResolveParams(
    core="vendor:lib:uart:1.0",
    target="sim",
    workspace="/path/to/fusesoc/workspace"
))

# 2. Configure simulation
config_result = await SimConfigure(runner, SimConfigureParams(
    core_name=core_result.output['core_name'],
    files=core_result.output['files'],
    toplevel="uart_tb",
    tool="icarus",
    parameters={'BAUD_RATE': 115200}
))

# 3. Build simulation
build_result = await SimBuild(runner, SimBuildParams(
    work_root=config_result.output['work_root'],
    tool="icarus"
))

# 4. Run simulation
run_result = await SimRun(runner, SimRunParams(
    work_root=build_result.output['work_root'],
    tool="icarus"
))

Architecture 

Pipeline Overview 

The library provides a complete pipeline from FuseSoC core files to simulation/synthesis results:

FuseSoC Core File (.core)
    ↓
┌───────────────────────┐
│  CoreResolve Task     │
│  - Parse VLNV         │
│  - Resolve deps       │
│  - Extract files      │
└───────────┬───────────┘
            ↓
   (files, includes, parameters)
            ↓
┌───────────────────────┐
│  FilesetConverter     │
│  - Convert formats    │
│  - Map file types     │
└───────────┬───────────┘
            ↓
   (converted files)
            ↓
┌───────────────────────┐
│  EdamBuilder          │
│  - Build EDAM         │
│  - Add parameters     │
└───────────┬───────────┘
            ↓
   (EDAM structure)
            ↓
┌───────────────────────┐
│  SimConfigure Task    │
│  - Setup tool         │
│  - Create scripts     │
└───────────┬───────────┘
            ↓
┌───────────────────────┐
│  SimBuild Task        │
│  - Compile design     │
│  - Generate model     │
└───────────┬───────────┘
            ↓
┌───────────────────────┐
│  SimRun Task          │
│  - Execute sim        │
│  - Capture results    │
└───────────────────────┘

Core Components 

FuseSoC Integration 

fusesoc_manager.py

Complete FuseSoC API wrapper providing:

Core resolution with VLNV parsing
Library management with core discovery
File list extraction with target/flags support
Dependency resolution
Full workspace isolation support

fusesoc_core_resolve.py

DV Flow task for resolving FuseSoC cores:

Pydantic parameter models
Output models with file lists
Memento support for caching
Error handling with markers
Async task implementation

fusesoc_fileset.py

Fileset converter:

FuseSoC → DV Flow format conversion
File type mapping (Verilog, SystemVerilog, VHDL, constraints)
Include directory extraction
Logical name/library handling
Separate files_root support

Edalize Integration 

edam_builder.py

EDAM (Edalize Design Abstraction Model) construction:

Builder pattern for EDAM structures
File list conversion
Parameter & plusarg support
Tool & flow options
Include directory handling
Convenience function: build_edam_from_core()

edalize_backend.py

Edalize wrapper:

Generic wrapper for any Edalize flow
Configure/Build/Run lifecycle
Error handling and reporting
Build artifact checking
Tool-specific success verification
Convenience functions (create_sim_backend, create_fpga_backend)

edalize_sim.py

Simulation tasks:

SimConfigure - Configure simulation
SimBuild - Build simulation
SimRun - Execute simulation
Task parameter/output models
Task chaining support
Tool-agnostic API

DV Flow Tasks 

fusesoc Package 

CoreResolve

Resolves a FuseSoC core by name/VLNV and extracts file lists, dependencies, and metadata.

Parameters:

core (str): Core VLNV (vendor:library:name:version)
target (str, optional): Target configuration (e.g., ‘sim’, ‘synth’)
tool (str, optional): Tool name for tool-specific filesets
libraries (dict, optional): Additional libraries to add {name: path}
workspace (str): FuseSoC workspace directory

Outputs:

core_name (str): Resolved core name
core_root (str): Core root directory
files (list): Converted file list
dependencies (list): Core dependencies
parameters (dict): Core parameters
include_dirs (list): Include directories

fusesoc.edalize.sim Package 

SimConfigure

Configures a simulation flow using Edalize. Builds EDAM structure from file lists and configures the simulation tool.

Supported Tools: Icarus Verilog, Verilator, ModelSim, VCS, Xcelium, GHDL

Parameters:

core_name (str): Name of the design
files (list): File list from core resolution
include_dirs (list): Include directories
toplevel (str): Toplevel module name
tool (str): Simulation tool (icarus, verilator, etc.)
parameters (dict, optional): Build-time parameters
plusargs (list, optional): Runtime plusargs
tool_options (dict, optional): Tool-specific options

Outputs:

work_root (str): Edalize work directory
tool (str): Configured simulation tool
configured (bool): Configuration success

SimBuild

Builds the simulation model. Handles compilation, elaboration, and generates simulation executable.

Parameters:

work_root (str): Edalize work directory
tool (str): Simulation tool

Outputs:

work_root (str): Edalize work directory
build_success (bool): Build success status
executable (str): Path to simulation executable

SimRun

Runs the simulation with specified parameters. Captures simulation output and determines pass/fail status.

Parameters:

work_root (str): Edalize work directory
tool (str): Simulation tool
runtime_plusargs (list, optional): Additional runtime plusargs

Outputs:

work_root (str): Edalize work directory
run_success (bool): Simulation success status
log_file (str): Path to simulation log

Supported Tools 

Simulators 

Via Edalize integration:

✅ Icarus Verilog - Open-source Verilog simulator
✅ Verilator - High-performance Verilog/SystemVerilog simulator
🔄 ModelSim/Questa - Commercial simulator (API ready)
🔄 VCS - Synopsys Verilog Compiler Simulator (API ready)
🔄 Xcelium - Cadence advanced simulator (API ready)
🔄 GHDL - Open-source VHDL simulator (API ready)

FPGA Tools 

Via Edalize integration:

🔄 Vivado - Xilinx FPGA toolchain (API ready)
🔄 Quartus - Intel FPGA toolchain (API ready)
🔄 Open-source flows - Yosys, nextpnr, etc. (API ready)

Testing 

The project includes comprehensive test coverage:

Total Tests: 38
Passing: 36 ✅ (94.7%)
Skipped: 2 (tool-dependent - Icarus/Verilator)
Failing: 0 ❌

Running Tests 

# Run all tests
pytest

# Run with coverage
pytest --cov=dv_flow.libfusesoc

# Run specific test category
pytest tests/unit/test_fusesoc_manager.py

Development 

Project Structure 

src/dv_flow/libfusesoc/
  __ext__.py                    - Extension registration
  flow.dv                       - Main package tasks
  sim_flow.dv                   - Simulation flow tasks
  fpga_flow.dv                  - FPGA flow (stub)
  lint_flow.dv                  - Lint flow (stub)
  fusesoc_manager.py            - FuseSoC API wrapper
  fusesoc_fileset.py            - File format converter
  fusesoc_core_resolve.py       - CoreResolve task
  edam_builder.py               - EDAM builder
  edalize_backend.py            - Edalize wrapper
  edalize_sim.py                - Simulation tasks

tests/
  conftest.py                   - Test fixtures
  fixtures/test_cores/          - Test .core files
  unit/                         - Unit tests
  integration/                  - Integration tests

Contributing 

Fork the repository
Create a feature branch
Make your changes with tests
Run the test suite
Submit a pull request

All contributions must:

Include tests for new functionality
Maintain or improve test coverage
Follow existing code style
Update documentation as needed

License 

Apache License 2.0 - See LICENSE file for details.

Documentation Contents 

API Reference 

API Documentation:

Additional Information 

Additional:

Changelog

dv-flow-libfusesoc Documentation

Overview 

Features 

Installation 

Quick Start 

Basic Simulation Flow 

Architecture 

Pipeline Overview 

Core Components 

FuseSoC Integration 

Edalize Integration 

DV Flow Tasks 

fusesoc Package 

CoreResolve

fusesoc.edalize.sim Package 

SimConfigure

SimBuild

SimRun

Supported Tools 

Simulators 

FPGA Tools 

Testing 

Test Categories 

Running Tests 

Development 

Project Structure 

Contributing 

License 

Documentation Contents 

User Guide 

API Reference 

Additional Information 

Indices and tables 