API Reference

Core Modules

zuspec.be.hdlsim

Main module providing runtime integration.

class HDLSimRuntime

Singleton runtime that manages testbench registration and factory configuration.

classmethod get_instance() → HDLSimRuntime

Get or create the singleton runtime instance.

register_tb_class(tb_class: Type) → None

Register a testbench class for this simulation. Called by generated SV.

Parameters:

tb_class – Top-level testbench component class

get_registered_tb_class() → Type | None

Get the currently registered testbench class.

Returns:

Registered testbench class or None

configure_objfactory(tb_class_path: str) → None

Configure ObjFactory from SystemVerilog before launching pytest.

Parameters:

tb_class_path – Fully qualified class path (e.g., “mymodule.MyTB”)

zuspec.be.hdlsim.sv_generator

SystemVerilog code generation.

class SVTestbenchGenerator

Generates SystemVerilog testbench from Zuspec component class.

__init__(top_component_cls)

Initialize generator with top-level component.

Parameters:

top_component_cls – Zuspec component class for top-level testbench

generate() → Dict[str, str]

Generate all SystemVerilog and Python files.

Returns:

Dictionary mapping filename to file content

get_source_filesets() → List[Any]

Get source filesets from all Extern components.

Returns:

List of AnnotationFileSet objects

zuspec.be.hdlsim.py_runtime

Python runtime factory for creating testbench proxies.

class PyTestbenchFactory

Factory for creating executable Python testbench objects at simulation runtime.

__init__()

Initialize factory with PyHDL-IF object registry.

create(component_cls: Type, inst_path: str = 'top') → Any

Create executable instance of component class.

Parameters:

  • component_cls – Zuspec component class

  • inst_path – Hierarchical instance path

Returns:

Proxy object with connections to SV components

zuspec.be.hdlsim.checker

Profile validation and checking.

class HDLTestbenchChecker

Validates HDLTestbench profile rules for domain separation.

__init__()

Initialize checker with empty error list.

check_component(comp) → None

Check a component definition against profile rules.

Parameters:

comp – Component class to validate

get_errors() → List[str]

Get list of validation errors found.

Returns:

List of error messages

has_errors() → bool

Check if any validation errors were found.

Returns:

True if errors exist

zuspec.be.hdlsim.profile

Profile definition for HDL testbenches.

HDLTestbenchProfile

Singleton profile instance for HDL testbench components.

get_checker()

Return the HDLTestbenchChecker for this profile.

Returns:

HDLTestbenchChecker instance

zuspec.be.hdlsim.json_api_gen

PyHDL-IF API generation.

class TransactorJsonApiGenerator

Generate PyHDL-IF JSON API definitions from XtorComponent classes.

__init__(xtor_cls, module_name: str = 'generated_api')

Initialize generator.

Parameters:

  • xtor_cls – XtorComponent class

  • module_name – Module name for generated API

generate() → Dict[str, Any]

Generate JSON API definition conforming to pyhdl-if.schema.json.

Returns:

Dictionary suitable for JSON serialization

zuspec.be.hdlsim.dfm.gen_tb

DV Flow Manager integration.

class GenTB

DFM task for generating HDL testbench from Zuspec component.

async run(ctxt) → TaskDataResult

Execute the testbench generation task.

Parameters:

ctxt – Task context with rundir, params, log

Returns:

TaskDataResult with status and output files

Task Parameters:

  • class_name (required): Fully qualified testbench class name

Task Outputs:

  • sv_files: List of generated SystemVerilog files

  • py_files: List of generated Python files

  • filesets: Ordered compilation fileset

Type Definitions

Protocols

class Extern

Protocol marker for external HDL components.

Components inheriting from Extern are expected to provide SystemVerilog source files via @annotation_fileset decorator.

class XtorComponent[ProtocolT]

Generic base for transactor components.

Parameters:

ProtocolT – Protocol class defining transaction-level API

Transactors generate both SystemVerilog implementation and Python API wrapper.

Annotations

@annotation_fileset(sources: List[str], incdirs: List[str] = None, defines: Dict[str, str] = None)

Annotate component with HDL source file information.

Parameters:

  • sources – List of source file paths (relative or absolute)

  • incdirs – Optional list of include directories

  • defines – Optional dictionary of preprocessor defines

Example:

@annotation_fileset(
    sources=["rtl/dut.sv", "rtl/dut_pkg.sv"],
    incdirs=["rtl/include"],
    defines={"DEBUG": "1"}
)
def __post_init__(self):
    pass

Examples

Basic Testbench

from zuspec.dataclasses import dataclass, Component, Signal
from zuspec.dataclasses.protocols import Extern, XtorComponent
from zuspec.be.hdlsim import HDLSimRuntime

# Define protocol
class MyProtocol:
    async def send(self, data: int): ...

# Define components
@dataclass
class DUT(Component, Extern):
    clock: Signal = zdc.input()

    @annotation_fileset(sources=["dut.sv"])
    def __post_init__(self): pass

@dataclass
class Driver(XtorComponent[MyProtocol]):
    clock: Signal = zdc.input()
    data_out: Signal = zdc.output()

@dataclass
class TB(Component):
    dut: DUT = zdc.inst()
    drv: Driver = zdc.inst()

    def __bind__(self):
        return (
            (self.drv.clock, self.dut.clock),
            (self.drv.data_out, self.dut.data_in),
        )

Profile Checking

from zuspec.be.hdlsim.checker import HDLTestbenchChecker

# Create and run checker
checker = HDLTestbenchChecker()
checker.check_component(TB)

# Handle errors
if checker.has_errors():
    for error in checker.get_errors():
        print(f"Validation error: {error}")
    sys.exit(1)

SV Generation

from zuspec.be.hdlsim.sv_generator import SVTestbenchGenerator

# Generate files
gen = SVTestbenchGenerator(TB)
files = gen.generate()

# Write to disk
for filename, content in files.items():
    with open(f"generated/{filename}", 'w') as f:
        f.write(content)

See Also