FuseSocBuilder¶

Topwrap supports generating FuseSoC .core files with FuseSocBuilder.The .core file contains information about source files and synthesis tools.

Generation of FuseSoC .core files is based on a Jinja template that defaults to topwrap/templates/core.yaml.j2, but can be overridden.

Here’s an example of how to generate a simple project:

from topwrap.fuse_helper import FuseSocBuilder
fuse = FuseSocBuilder()

# add source of the IPs used in the project
fuse.add_source('DMATop.v', 'verilogSource')

# add source of the top file
fuse.add_source('top.v', 'verilogSource')

# specify the names of the core file and the directory where sources are stored
# generate the project
fuse.build('build/top.core', 'sources')

class FuseSocBuilder(part: str | None)¶

Use this class to generate a FuseSoc .core file

add_dependency(dependency: str | Identifier)¶

Adds a dependency to the list of dependencies in the core file

add_external_ip(vlnv: str, name: str)¶

Store information about IP Cores from Vivado library to generate hooks that will add the IPs in a TCL script.

add_fileset(name: str, files: list[SourceFile], depends: list[Identifier])¶

Add a complete fileset to the core file

add_script(name: str, args: list[str])¶

Add a named fusesoc script

add_source(filename: Path, type: str)¶

Adds an HDL source to the list of sources in the core file

add_sources_dir(sources_dir: Collection[Path], core_path: Path)¶

Given a name of a directory, add all files found inside it. Recognize VHDL, Verilog, and XDC files.

add_target(target: FuseSocTarget)¶

Add a named fusesoc target

build(top_name: str, core_path: Path, sources_dir: Collection[Path] = [])¶

Generate the final create .core file

Parameters:¶

sources_dir: Collection[Path] = []¶

additional directory with source files to add

template_name

name of jinja2 template to be used, either in working directory, or bundled with the package. defaults to a bundled template

Customizations¶

By default, Topwrap will generate a core file with a default target of running Vivado on the top-level defined by the Topwrap project.
This can be overridden in several ways. To disable the generation of a default Vivado target, you would call

from topwrap.fuse_helper import FuseSocBuilder
fuse = FuseSocBuilder(None)

fuse.set_generate_vivado(False) # disables the default vivado target

You can add custom targets by constructing FuseSocTarget. Here’s an example to create a Verilator flow-target that builds and runs a testbench:

from pathlib import Path

from topwrap.fuse_helper import (
    FuseSocBuilder,
    FuseSocFlowApi,
    FuseSocTarget,
    SourceFile,
)

fuse = FuseSocBuilder(None)

fuse.set_generate_vivado(False)

# Add a source to the default `rtl` fileset
fuse.add_source(Path("top.v"), "verilogSource")
toplevel = "top"  # toplevel, as defined in top.v

# Add a second fileset, `verilator_tb`, with testbench
fuse.add_fileset(
    "verilator_tb",
    files=[SourceFile(Path("top_tb.sv"), "systemVerilogSource")],
    depends=[],
)

# Add a testbench target `tb`, that references both the default fileset and the custom
fuse.add_target(
    FuseSocTarget(
        "tb",
        toplevel,
        FuseSocFlowApi(
            type="sim",
            options={
                "tool": "verilator",
                "mode": "cc",
                "verilator_options": ["-Wno-fatal", "--main", ["--timing"]],
            },
            make_options=["-s"],
        ),
        filesets=["rtl", "verilator_tb"],
        hooks=[],
    )
)

fuse.build(toplevel, Path("top.core"))

This will generate the following:

CAPI=2:
name: ::top
description: Core file generated by TopWrap
filesets:
    verilator_tb:
        files:
        -   top_tb.sv:
                file_type: systemVerilogSource
    rtl:
        files:
        -   top.v:
                file_type: verilogSource
targets:
    tb:
        filesets:
        - rtl
        - verilator_tb
        toplevel: top
        flow: sim
        flow_options:
            tool: verilator
            mode: cc
            verilator_options:
            - -Wno-fatal
            - --main
            -   - --timing
            flow_make_options:
            - -s