FvmFramework

The FvmFramework class is the intended interface for users.

Note

Callables (classes, functions and methods) that are not documented in this Public API are not intented to be directly used and thus may change between minor versions.

class fvm.FvmFramework

Bases: object

This class defines the FVM framework

add_clock(name, design='*', module=None, group=None, period=None, waveform=None, external=None, ignore=False, remove=False)

Add a clock signal to the design.

This method registers a clock. The clock can have various properties such as period, waveform, domain association, and external status.

Parameters:

• name (str) – Name of the clock signal.

• design (str) – Name of the design to add the clock for. Defaults to ‘*’, which matches all designs.

• module (str or None) – Optional module name associated with the clock.

• group (str or None) – Optional clock group name to classify the clock signal.

• period (float or int or None) – Clock period in ns.

• waveform (tuple[float, float] or tuple[int, int] or None) – Clock waveform definition, a tuple (rise_time, fall_time) to define duty cycle. If period is 10, default waveform is (0, 5), i. e. a 50% duty cycle.

• external (bool or None) – Indicates that the clock comes from an external source.

• ignore (bool or None) – If True, this clock will be ignored.

• remove (bool or None) – If True, this clock will be removed.

add_clock_domain(port_list, design='*', clock_name=None, asynchronous=None, ignore=None, posedge=None, negedge=None, module=None, inout_clock_in=None, inout_clock_out=None)

Add a clock domain definition to the framework.

This method registers a new clock domain with its associated ports and synchronization properties.

Parameters:

• port_list (list[str]) – List of ports belonging to the clock domain.

• design (str) – Name of the design to add the clock domain for. Defaults to ‘*’, which matches all designs.

• clock_name (str or None) – Name of the clock. If None, the port domain may be asynchronous or ignored based on other parameters.

• asynchronous (bool or None) – Ports that are asynchronous to all clock domains. If clock_name has been specified, the ports are considered asynchronous, but the ports’ receiving clock domain is derived from clock_name.

• ignore (bool or None) – Input ports that should be ignored.

• posedge (bool or None) – Clocked by the positive edge of the clock signal. If both posedge and negedge are specified, both edges of the clock are considered active for this domain. Default: positive edge only.

• negedge (bool or None) – Clocked by the negative edge of the clock signal.

• module (str or None) – Optional module name to which the domain belongs.

• inout_clock_in (bool or None) – Specify the input direction clock domain name for inout ports.

• inout_clock_out (bool or None) – Specify the output direction clock domain name for inout ports.

add_config(design, name, generics)

Add a design configuration.

This method registers a configuration for a given design. Each configuration has a name and a dictionary with the generics/parameters. Once at least one configuration exists for a design, the framework default configuration is not used.

Parameters:

• design (str) – Name of the design to which the configuration applies. Must be one of the toplevel modules.

• name (str) – Name of the configuration.

• generics (dict) – Dictionary with the generics/parameters for the configuration.

add_drom_source(src, flavor, library='work')

Add a single Wavedrom source file to the framework.

This method validates that the provided file exists and checks whether it has a typical Wavedrom extension (.json, .JSON, .drom, or .wavedrom). If the file does not exist, the framework logs an error and exits. If the extension is unusual, a warning is logged. The flavor parameter must be either “vhdl” or “verilog”.

Warning

Verilog flavor is not available yet when using Wavedrom sources.

The library parameter specifies the library to which the PSL source belongs, i.e., the library where the design bound to the PSL properties is located.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• src (str) – Path to the Wavedrom source file.

• flavor (str) – Flavor of PSL, either “vhdl” or “verilog”.

• library (str) – Library of the design bound to the PSL properties. Defaults to "work".

add_drom_sources(globstr, flavor, library='work')

Add multiple Wavedrom source files to the framework using a glob pattern.

This method searches for all files matching the provided glob pattern and adds them as Wavedrom sources. Each matching file is added via add_drom_source(). If no files match the pattern, an error is logged and the framework exits. The flavor parameter must be either “vhdl” or “verilog”.

Warning

Verilog flavor is not available yet when using Wavedrom sources.

The library parameter specifies the library to which the PSL source belongs, i.e., the library where the design bound to the PSL properties is located.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• src (str) – Path to the Wavedrom source file.

• flavor (str) – Flavor of PSL, either “vhdl” or “verilog”.

• library (str) – Library of the design bound to the PSL properties. Defaults to "work".

add_psl_source(src, flavor, library='work')

Add a single PSL (Property Specification Language) source file to the framework.

The function validates that the provided file exists and checks whether it has a common PSL extension. If the file does not exist, the framework will log an error and exit. If the extension is unusual, a warning is logged. The flavor parameter must be either “vhdl” or “verilog”. The library parameter specifies the library to which the PSL source belongs, i.e., the library where the design bound to the PSL properties is located.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• src (str) – Path to the PSL source file.

• flavor (str) – Flavor of PSL, either “vhdl” or “verilog”.

• library (str) – Library of the design bound to the PSL properties. Defaults to "work".

add_psl_sources(globstr, flavor, library='work')

Add multiple PSL source files to the framework using a glob pattern.

This method searches for all files matching the provided glob pattern and adds them as PSL sources. Each matching file is added via add_psl_source(). If no files match the pattern, an error is logged and the framework exits. The flavor parameter must be either “vhdl” or “verilog”. The library parameter specifies the library to which the PSL source belongs, i.e., the library where the design bound to the PSL properties is located.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• globstr (str) – Glob pattern to search for PSL source files.

• flavor (str) – Flavor of PSL, either “vhdl” or “verilog”.

• library (str) – Library of the design bound to the PSL properties. Defaults to "work".

add_reset(name, design='*', module=None, group=None, active_low=None, active_high=None, asynchronous=None, synchronous=None, external=None, ignore=None, remove=None)

Add a reset signal to the design.

This method registers a reset signal. The reset can have various properties such as polarity, synchronization, and domain association.

Parameters:

• name (str) – Name of the reset signal.

• design (str) – Name of the design to add the reset signal for. Defaults to ‘*’, which matches all designs.

• module (str or None) – Optional name of the module associated with the reset.

• group (str or None) – Optional reset group name to classify the reset signal.

• active_low (bool or None) – If True, the reset signal is active low.

• active_high (bool or None) – If True, the reset signal is active high.

• asynchronous (bool or None) – If True, the reset signal is considered asynchronous.

• synchronous (bool or None) – If True, the reset signal is considered synchronous.

• external (bool or None) – If True, the reset signal is considered external.

• ignore (bool or None) – If True, the reset signal is ignored.

• remove (bool or None) – If True, the inferred reset signal is removed.

add_reset_domain(port_list, design='*', name=None, asynchronous=None, synchronous=None, active_high=None, active_low=None, is_set=None, no_reset=None, module=None, ignore=None)

Adds a reset domain definition to the framework.

This function registers a new reset domain by specifying the ports that belong to it, its name, and various properties such as polarity, synchronization…

Parameters:

• port_list (list[str]) – List of ports that belong to the reset domain.

• design (str) – Name of the design to add the reset domain for. Defaults to ‘*’, which matches all designs.

• name (str or None) – Name of the reset domain. If None, the port domain may be ignored or have no reset based on other parameters.

• asynchronous (bool or None) – If True, the reset signal is considered asynchronous.

• synchronous (bool or None) – If True, the reset signal is considered synchronous.

• active_high (bool or None) – If True, the reset signal is active high.

• active_low (bool or None) – If True, the reset signal is active low.

• is_set (bool or None) – If True, the reset signal behaves as a set-type control instead of reset.

• no_reset (bool or None) – If True, indicates the port has no reset control.

• module (str or None) – Optional module name associated with the reset domain.

• ignore (bool or None) – Ports ignored for reset analysis.

add_systemverilog_source(src, library='work')

Add a single SystemVerilog source file to the framework.

This method registers a SystemVerilog source file for later compilation. It checks whether the file exists and validates its extension. Non-standard extensions trigger a warning but are still accepted.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Warning

Currently, SystemVerilog support is experimental and may not work as intended for all designs

Parameters:

src (str) – Path to the SystemVerilog source file.

add_systemverilog_sources(globstr, library='work')

Add multiple SystemVerilog source files to the framework using a glob pattern.

This method searches for all files matching the provided glob pattern and adds them as SystemVerilog sources. Each matching file is added via add_systemverilog_source(). If no files match the pattern, an error is logged and the framework exits.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• globstr (str) – Glob pattern to search for SystemVerilog source files.

• library (str) – VHDL library name to associate with the sources. Defaults to "work".

add_verilog_source(src, library='work')

Add a single Verilog source file to the framework.

This method registers a Verilog source file for later compilation. It checks whether the file exists and validates its extension. Non-standard extensions trigger a warning but are still accepted.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Warning

Currently, Verilog support is experimental and may not work as intended for all designs

Parameters:

src (str) – Path to the Verilog source file.

add_verilog_sources(globstr, library='work')

Add multiple Verilog source files to the framework using a glob pattern.

This method searches for all files matching the provided glob pattern and adds them as Verilog sources. Each matching file is added via add_verilog_source(). If no files match the pattern, an error is logged and the framework exits.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• globstr (str) – Glob pattern to search for Verilog source files.

• library (str) – VHDL library name to associate with the sources. Defaults to "work".

add_vhdl_source(src, library='work')

Add a single VHDL source file to the framework.

This method registers a VHDL source file for later compilation and associates it with a VHDL library (defaulting to work). It checks whether the file exists and validates its extension. Non-standard extensions trigger a warning but are still accepted.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• src (str) – Path to the VHDL source file.

• library (str) – VHDL library name to associate with the source file. Defaults to "work".

add_vhdl_sources(globstr, library='work')

Add multiple VHDL source files to the framework using a glob pattern.

This method searches for all files matching the provided glob pattern and adds them as VHDL sources. Each matching file is added via add_vhdl_source(). If no files match the pattern, an error is logged and the framework exits.

Libraries have to be specified in the order they want to be compiled. For example, if library A depends on library B, then B must be added before A. The order of the source files within each library is not significant.

Parameters:

• globstr (str) – Glob pattern to search for VHDL source files.

• library (str) – VHDL library name to associate with the sources. Defaults to "work".

allow_failure(step, design='*')

Allow specific steps to fail.

The fail will be marked but the execution will continue. Both the step and the design can be specified. The special wildcard ‘*’ can be used to indicate all steps or all designs.

Parameters:

• step (str) – Name of the step to allow the fail.

• design (str) – Name of the design to allow the fail for. Defaults to ‘*’, which matches all designs.

blackbox(entity, design='*')

Blackboxes all instances of a given entity or module.

Parameters:

• entity (str) – Name of the entity or module to be blackboxed.

• design (str) – Name of the design to add the blackbox for. Defaults to ‘*’, which matches all designs.

blackbox_instance(instance, design='*')

Blackboxes a specific instance of a given entity or module.

Parameters:

• instance (str) – Name of the instance to be blackboxed.

• design (str) – Name of the design to add the blackbox instance for. Defaults to ‘*’, which matches all designs.

check_tool(tool, quiet=False)

Check whether a tool name is available in the system PATH.

This method searches for the specified tool name in the system PATH. It logs a warning if the tool is not found, and logs a success message if it is found.

Parameters:

tool (str) – Name of the tool name to search for in PATH.

Returns:

True if the tool is found in PATH, False otherwise.

Return type:

bool

clear_drom_sources()

Remove all registered Wavedrom sources from the framework.

This method clears the internal list of Wavedrom sources.

clear_psl_sources()

Remove all registered PSL sources from the framework.

This method clears the internal list of PSL sources.

clear_systemverilog_sources()

Remove all registered SystemVerilog sources from the framework.

This method clears the internal list of SystemVerilog sources.

clear_verilog_sources()

Remove all registered Verilog sources from the framework.

This method clears the internal list of Verilog sources.

clear_vhdl_sources()

Remove all registered VHDL sources from the framework.

This method clears the internal list of VHDL sources.

cutpoint(signal, design='*', module=None, resetval=None, condition=None, driver=None, wildcards_dont_match_hierarchy_separators=False)

Define a cutpoint on a specific signal in the design.

Parameters:

• signal (str) – Name of the signal to mark as a cutpoint.

• design (str) – Name of the design to add the cutpoint for. Defaults to ‘*’, which matches all designs.

• module (str or None) – Optional module name that contains the signal.

• resetval (bool or None) – If True, the cutpoint will take the reset value.

• driver (str or None) – Optional signal or port driving this cutpoint.

• condition (str or None) – Optional condition expression under which the cutpoint is active.

• wildcards_dont_match_hierarchy_separators (bool) – If True, wildcard patterns in signal names will not match hierarchy separators (typically ‘.’).

disable_coverage(covtype, design='*')

Disable specific types of coverage collection for a design or all designs.

This method allows the user to disable certain coverage types during formal coverage. The special wildcard ‘*’ can be used for the design parameter to apply the disablement to all designs. If the specified coverage type is not allowed, an error will be logged and the framework will exit.

Allowed coverage types are:

• observability

• reachability

• bounded_reachability

• signoff

Parameters:

• covtype (str) – Type of coverage to disable.

• design (str) – Name of the design to disable coverage for. Defaults to ‘*’, which applies to all designs.

formal_initialize_reset(reset, active_high=True, cycles=1)

Initialize a reset signal for formal steps.

This method initializes the reset signal in formal when the tool cannot infer it. Only formal steps can use it.

Parameters:

• reset (str) – Name of the reset signal to initialize.

• active_high (bool) – Whether the reset is active high (True) or active low (False). Defaults to True.

• cycles (int) – Number of cycles the reset should be asserted during initialization. Defaults to 1.

get_steps()

Generate a list of the available tool steps including post-steps.

Returns:

List of all available steps including post-steps.

Return type:

list[str]

get_tool_flags(tool)

Get user-defined flags for a specific tool. If flags are not set, returns an empty string, so the script generators can just call this function and expect it to always return a value of string type

get_vhdl_std()

Get the current VHDL standard version.

Returns:

The current VHDL standard version.

Return type:

str

list_drom_sources()

List all Wavedrom source files in the framework.

This method logs the current list of Wavedrom source files stored in the framework.

list_psl_sources()

List all PSL source files in the framework.

This method logs the current list of PSL source files stored in the framework.

list_sources()

List all source files in the framework.

This method logs all sources currently added to the framework, including:

• VHDL sources

• PSL sources

• Wavedrom sources

list_systemverilog_sources()

List all SystemVerilog source files in the framework.

This method logs the current list of SystemVerilog source files stored in the framework.

list_verilog_sources()

List all Verilog source files in the framework.

This method logs the current list of Verilog source files stored in the framework.

list_vhdl_sources()

List all VHDL source files in the framework.

This method logs the current list of VHDL source files stored in the framework.

log(severity, string)

Log a message from external code using the framework’s logger.

This method allows external scripts or test files to log messages through the framework’s logging system. The severity level are the loguru levels, mentioned in set_loglevel().

Parameters:

• severity (str) – Logging level to use. The value is case-insensitive.

• string (str) – Message text to be logged.

run(skip_setup=False)

Execute the full flow of the framework for all specified toplevels.

This method run the framework and, optionally, skips the setup phase, resulting in the use of existing scripts, which can be defined manually or generated in a previous run.

Parameters:

skip_setup (bool) – If True, the setup is skipped and existing scripts are used.

set_coverage_goal(step, goal)

Set the coverage goal for a specific step.

This method allows configuring the target coverage percentage for a given step. The goal must be a number between 0 and 100 (inclusive).

Parameters:

• step (str) – Name of the step to set the coverage goal for.

• goal (int or float) – Coverage goal value, must be between 0 and 100.

set_post_hook(hook, step, design='*')

Register a hook after a specific step.

A post-hook is a user-defined callable that will be executed after the specified step runs. Hooks can be assigned to a specific design or to all designs using the wildcard ‘*’.

Parameters:

• hook (callable) – Callable to execute after the step.

• step (str) – Name of the step to attach the post-hook to.

• design (str) – Name of the design to apply the hook to, or ‘*’ to apply to all designs. Defaults to ‘*’.

set_pre_hook(hook, step, design='*')

Register a hook before a specific step.

A pre-hook is a user-defined callable that will be executed before the specified step runs. Hooks can be assigned to a specific design or to all designs using the wildcard ‘*’.

Parameters:

• hook (callable) – Callable to execute before the step.

• step (str) – Name of the step to attach the pre-hook to.

• design (str) – Name of the design to apply the hook to, or ‘*’ to apply to all designs. Defaults to ‘*’.

set_prefix(prefix)

Set the prefix string for the framework.

The prefix is used to distinguish between different executions of the same toplevel in the reports (shows <prefix>.<toplevel>.<config>). This method validates that the provided prefix is a string. If the value is not a string, an error is logged and the framework exits.

Parameters:

prefix (str) – The prefix string to set.

set_timeout(step, timeout)

Set the execution timeout for a specific step.

The timeout specifies the maximum allowed execution time for the given step. It may be that the time during the step is slightly longer than the timeout because the timeout is for the tool execution, but does not take into account the tool compilation. Not all steps have a timeout, although if they don’t, they probably won’t take long.

The timeout should be provided as a string combining a number and a unit:

• s for seconds (e.g., “1s”)

• m for minutes (e.g., “10m”)

• h for hours (e.g., “1h”)

• d for days (e.g., “2d”)

Parameters:

• step (str) – Name of the step to set the timeout for.

• timeout (str) – Timeout value as a string with a number and unit.

Returns:

None

Return type:

None

set_tool_flags(tool, flags)

Set user-defined flags for a specific tool.

These flags will be used when invoking the specified tool during the framework flow. This allows customizing tool behavior without modifying internal scripts or commands.

Parameters:

• tool (str) – Name of the tool to set flags for.

• flags (str) – Flags to pass to the tool.

set_toolchain(toolchain)

Override the current toolchain selection.

This method allows overriding the FVM_TOOLCHAIN environment variable and explicitly setting a different toolchain for the framework. If the provided toolchain is not supported, the framework logs an error and exits.

Parameters:

toolchain (str) – Name of the toolchain to be set.

set_toplevel(toplevel)

Set the name of the toplevel module.

This method allows specifying one or multiple toplevel modules. If a single toplevel module is provided as a string, it is converted into a single-element list. If a list is provided, duplicates are checked and an error is logged if any are found.

Certain reserved names are prohibited (fvm_dashboard and fvm_reports) to avoid conflicts with framework directories.

If a specific design has already been set with framework argument -d, --design, only that design will be kept in the toplevel list; an error is raised if the design is not present in the provided toplevel list.

Parameters:

toplevel (str or list of str) – Name of the toplevel module as a string, or a list of toplevel module names.

set_vhdl_std(vhdlstd)

Set the VHDL standard version for the framework.

This method allows specifying the VHDL standard version to be used during compilation, default is “2008”. Supported versions are “87”, “93”, “02”, and “08”.

Parameters:

vhdlstd (str) – VHDL standard version as a string.

skip(step, design='*')

Allow to skip specific steps.

Both the step and the design can be specified. The special wildcard ‘*’ can be used to indicate all steps or all designs.

Parameters:

• step (str) – Name of the step to skip.

• design (str) – Name of the design to skip the step for. Defaults to ‘*’, which matches all designs.