Edalize Integration

This module provides integration with Edalize for EDA tool flows.

edam_builder

class dv_flow.libfusesoc.edam_builder.EdamBuilder(name: str)[source]

Bases: object

Builds EDAM (EDA Metadata) structures for Edalize.

EDAM is the data structure that Edalize uses to describe all inputs needed for EDA tool operations (simulation, synthesis, etc.).

__init__(name: str)[source]

Initialize EDAM builder.

Parameters:: name – Project/design name

add_files(files: List[Dict]) → EdamBuilder[source]

Add files to EDAM.

Parameters:: files – List of file dictionaries with ‘name’ and ‘file_type’
Returns:: Self for chaining

set_toplevel(toplevel: str) → EdamBuilder[source]

Set toplevel module(s).

Parameters:: toplevel – Toplevel module name (string for Edalize compatibility)
Returns:: Self for chaining

add_parameters(parameters: Dict[str, Any]) → EdamBuilder[source]

Add parameters (Verilog defines, VHDL generics, plusargs).

Parameters:: parameters – Dictionary of parameter names to values
Returns:: Self for chaining

add_plusargs(plusargs: Dict[str, Any]) → EdamBuilder[source]

Add runtime plusargs.

Parameters:: plusargs – Dictionary of plusarg names to values
Returns:: Self for chaining

set_tool_options(tool: str, options: Dict[str, Any]) → EdamBuilder[source]

Set tool-specific options.

Parameters:

tool – Tool name (e.g., ‘icarus’, ‘verilator’)
options – Dictionary of tool options

Returns:

Self for chaining

set_flow_options(options: Dict[str, Any]) → EdamBuilder[source]

Set flow-level options.

Parameters:: options – Dictionary of flow options (e.g., {‘tool’: ‘icarus’, ‘target’: ‘sim’})
Returns:: Self for chaining

add_include_dirs(include_dirs: List[str]) → EdamBuilder[source]

Add include directories (convenience method).

Parameters:: include_dirs – List of include directory paths
Returns:: Self for chaining

build() → Dict[source]

Build and return the EDAM structure.

Returns:: Complete EDAM dictionary

dv_flow.libfusesoc.edam_builder.build_edam_from_core(core_files: Dict, toplevel: str, tool: str = 'icarus', parameters: Dict | None = None, plusargs: Dict | None = None) → Dict[source]

Convenience function to build EDAM from FuseSoC core files.

Parameters:

core_files – Dictionary from FuseSoCManager.get_core_files()
toplevel – Toplevel module name
tool – Target tool (default: ‘icarus’)
parameters – Optional build-time parameters
plusargs – Optional runtime plusargs

Returns:

Complete EDAM dictionary

The EDAM Builder constructs Edalize Design Abstraction Model (EDAM) structures.

EDAM Structure

EDAM is Edalize’s unified data structure for describing designs:

edam = {
    'name': 'design_name',
    'files': [
        {'name': 'file.v', 'file_type': 'verilogSource'},
        {'name': 'file.sv', 'file_type': 'systemVerilogSource'},
    ],
    'toplevel': 'top_module',
    'parameters': {
        'WIDTH': 32,
        'DEPTH': 1024
    },
    'tool_options': {
        'icarus': {
            'iverilog_options': ['-g2009']
        }
    }
}

Builder Pattern

The EdamBuilder uses a fluent interface for constructing EDAM:

from dv_flow.libfusesoc.edam_builder import EdamBuilder

builder = EdamBuilder("my_design")
builder.set_toplevel("top_module")
builder.add_files(file_list)
builder.add_parameters({'WIDTH': 32})
builder.add_include_dirs(['/path/to/includes'])
builder.set_tool_options('icarus', {'iverilog_options': ['-g2009']})

edam = builder.build()

Convenience Functions

build_edam_from_core(): Builds EDAM directly from CoreResolve output:

from dv_flow.libfusesoc.edam_builder import build_edam_from_core

edam = build_edam_from_core(
    core_name="uart",
    files=core_result.output['files'],
    toplevel="uart_top",
    tool="icarus",
    parameters={'BAUD_RATE': 115200}
)

edalize_backend

class dv_flow.libfusesoc.edalize_backend.EdalizeBackend(flow_class, edam: Dict, work_root: Path, verbose: bool = False)[source]

Bases: object

Wrapper around Edalize backend/flow instantiation and execution. Handles the configure/build/run lifecycle for EDA tools.

__init__(flow_class, edam: Dict, work_root: Path, verbose: bool = False)[source]

Initialize Edalize backend.

Parameters:

flow_class – Edalize flow class (e.g., Sim, Vivado)
edam – EDAM dictionary
work_root – Working directory for tool execution
verbose – Enable verbose output

configure() → bool[source]

Configure the flow (setup files, generate scripts).

Returns:: True if successful, False otherwise

build(args: List[str] | None = None) → tuple[bool, str][source]

Build the design (compile, elaborate).

Parameters:: args – Optional additional build arguments (deprecated, unused)
Returns:: Tuple of (success, output)

run(args: List[str] | None = None) → tuple[bool, str][source]

Run the design (simulate, program FPGA, etc.).

Parameters:: args – Optional additional run arguments (deprecated, unused)
Returns:: Tuple of (success, output)

get_tool() → str | None[source]: Get the tool name being used.

get_work_root() → Path[source]: Get the work directory path.

get_log_files() → List[Path][source]

Get list of log files generated during build/run.

Returns:: List of log file paths

cleanup()[source]: Clean up work directory.

dv_flow.libfusesoc.edalize_backend.create_sim_backend(edam: Dict, work_root: Path, verbose: bool = False) → EdalizeBackend[source]

Convenience function to create a simulation backend.

Parameters:

edam – EDAM dictionary
work_root – Working directory
verbose – Enable verbose output

Returns:

EdalizeBackend instance configured for simulation

dv_flow.libfusesoc.edalize_backend.create_fpga_backend(edam: Dict, work_root: Path, verbose: bool = False) → EdalizeBackend[source]

Convenience function to create an FPGA synthesis backend.

Parameters:

edam – EDAM dictionary
work_root – Working directory
verbose – Enable verbose output

Returns:

EdalizeBackend instance configured for FPGA synthesis

The Edalize Backend provides a wrapper around Edalize tool flows.

Backend Lifecycle

The backend manages the three-phase Edalize lifecycle:

Configure: Setup tool environment and generate build scripts
Build: Compile/elaborate the design
Run: Execute the tool (simulation, synthesis, etc.)

from dv_flow.libfusesoc.edalize_backend import EdalizeBackend

backend = EdalizeBackend(edam, work_root, tool="icarus")

# Phase 1: Configure
backend.configure()

# Phase 2: Build
success = backend.build()
if not success:
    print("Build failed!")
    print(backend.get_stderr())

# Phase 3: Run
success = backend.run()

Error Handling

The backend provides comprehensive error reporting:

get_stdout() - Capture tool standard output
get_stderr() - Capture tool standard error
get_returncode() - Get tool exit code
Tool-specific success verification

Convenience Functions

create_sim_backend(): Creates a backend configured for simulation:

from dv_flow.libfusesoc.edalize_backend import create_sim_backend

backend = create_sim_backend(
    edam=edam,
    work_root="/path/to/work",
    tool="verilator"
)

create_fpga_backend(): Creates a backend configured for FPGA synthesis:

from dv_flow.libfusesoc.edalize_backend import create_fpga_backend

backend = create_fpga_backend(
    edam=edam,
    work_root="/path/to/work",
    tool="vivado"
)

edalize_sim

class dv_flow.libfusesoc.edalize_sim.SimConfigureParams(*, core_name: str, files: ~typing.List[~typing.Dict], include_dirs: ~typing.List[str] = <factory>, toplevel: str, tool: str = 'icarus', parameters: ~typing.Dict = <factory>, plusargs: ~typing.Dict = <factory>, tool_options: ~typing.Dict = <factory>)[source]

Bases: BaseModel

Parameters for SimConfigure task.

Configures a simulation using Edalize.

core_name: str

files: List[Dict]

include_dirs: List[str]

toplevel: str

tool: str

parameters: Dict

plusargs: Dict

tool_options: Dict

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dv_flow.libfusesoc.edalize_sim.SimConfigureOutput(*, work_root: str, tool: str, configured: bool)[source]

Bases: BaseModel

Output from SimConfigure task.

work_root: str

tool: str

configured: bool

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dv_flow.libfusesoc.edalize_sim.SimBuildParams(*, work_root: str, tool: str)[source]

Bases: BaseModel

Parameters for SimBuild task.

work_root: str

tool: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dv_flow.libfusesoc.edalize_sim.SimBuildOutput(*, work_root: str, build_success: bool, executable: str | None = None)[source]

Bases: BaseModel

Output from SimBuild task.

work_root: str

build_success: bool

executable: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dv_flow.libfusesoc.edalize_sim.SimRunParams(*, work_root: str, tool: str, runtime_plusargs: ~typing.Dict = <factory>)[source]

Bases: BaseModel

Parameters for SimRun task.

work_root: str

tool: str

runtime_plusargs: Dict

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dv_flow.libfusesoc.edalize_sim.SimRunOutput(*, work_root: str, run_success: bool, log_file: str | None = None)[source]

Bases: BaseModel

Output from SimRun task.

work_root: str

run_success: bool

log_file: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async dv_flow.libfusesoc.edalize_sim.SimConfigure(runner, input: TaskDataInput[SimConfigureParams]) → TaskDataResult[source]

Configure a simulation using Edalize.

Creates EDAM structure and configures the Edalize backend.

Parameters:

runner – Task runner context
input – Task input with SimConfigureParams

Returns:

TaskDataResult with SimConfigureOutput

async dv_flow.libfusesoc.edalize_sim.SimBuild(runner, input: TaskDataInput[SimBuildParams]) → TaskDataResult[source]

Build simulation executable.

Compiles and elaborates the design using the configured Edalize backend.

Parameters:

runner – Task runner context
input – Task input with SimBuildParams

Returns:

TaskDataResult with SimBuildOutput

async dv_flow.libfusesoc.edalize_sim.SimRun(runner, input: TaskDataInput[SimRunParams]) → TaskDataResult[source]

Run simulation.

Executes the built simulation model.

Parameters:

runner – Task runner context
input – Task input with SimRunParams

Returns:

TaskDataResult with SimRunOutput

Simulation tasks for running HDL simulations through Edalize.

SimConfigure Task

Configures a simulation environment.

Parameters:

class SimConfigureParams(BaseModel):
    core_name: str
    files: List[Dict]
    include_dirs: List[str] = []
    toplevel: str
    tool: str = "icarus"
    parameters: Dict[str, Any] = {}
    plusargs: List[str] = []
    tool_options: Dict[str, Any] = {}

Outputs:

class SimConfigureOutput(BaseModel):
    work_root: str
    tool: str
    configured: bool

Example:

from dv_flow.libfusesoc.edalize_sim import SimConfigure, SimConfigureParams

result = await SimConfigure(runner, SimConfigureParams(
    core_name="uart",
    files=file_list,
    toplevel="uart_tb",
    tool="icarus",
    parameters={'BAUD_RATE': 115200}
))

SimBuild Task

Builds the simulation executable.

Parameters:

class SimBuildParams(BaseModel):
    work_root: str
    tool: str

Outputs:

class SimBuildOutput(BaseModel):
    work_root: str
    build_success: bool
    executable: str

Example:

from dv_flow.libfusesoc.edalize_sim import SimBuild, SimBuildParams

result = await SimBuild(runner, SimBuildParams(
    work_root=config_result.output['work_root'],
    tool="icarus"
))

SimRun Task

Executes the simulation.

Parameters:

class SimRunParams(BaseModel):
    work_root: str
    tool: str
    runtime_plusargs: List[str] = []

Outputs:

class SimRunOutput(BaseModel):
    work_root: str
    run_success: bool
    log_file: str

Example:

from dv_flow.libfusesoc.edalize_sim import SimRun, SimRunParams

result = await SimRun(runner, SimRunParams(
    work_root=build_result.output['work_root'],
    tool="icarus",
    runtime_plusargs=['+verbose=1']
))

Task Chaining

The simulation tasks are designed to be chained together:

# Complete simulation flow
config = await SimConfigure(runner, config_params)

build = await SimBuild(runner, SimBuildParams(
    work_root=config.output['work_root'],
    tool=config.output['tool']
))

run = await SimRun(runner, SimRunParams(
    work_root=build.output['work_root'],
    tool=build.output['tool']
))

if run.output['run_success']:
    print("Simulation passed!")
    print(f"Log: {run.output['log_file']}")