Plugins¶

Plugins are Python modules that are installed in the same environment as Topwrap. They must define an entry point in the topwrap.plugins group. The entry point is a class that inherits from BasePlugin. pyproject.toml must contain the following:

[project.entry-points."topwrap.plugins"]
<plugin-name> = "<plugin-name>.<module-path>:<PluginBase-subclass>"

Examples¶

Use an existing plugin as a base for developing your own: github.com/antmicro/topwrap-utils.

Plugin Base¶

By defining implementations for the various hooks defined by BasePlugin, the plugin can modify or extend Topwrap’s capabilities. All methods are passed the current BuildContext which contains the internal representation of the design and other metadata.

class BasePlugin¶

Bases: object

priority : int = 0¶

Priority of the plugin. Hooks are invoked in order of decreasing priority.

pre_ir_generation(ctx: BuildContext)¶

Hook invoked before parsing sources.

post_ir_generation(ctx: BuildContext)¶

Hook invoked after parsing sources.

pre_transform(ctx: BuildContext)¶

Hook invoked before applying transformations.

post_transform(ctx: BuildContext)¶

Hook invoked after applying transformations.

pre_validate(ctx: BuildContext)¶

Hook invoked before performing validation.

post_validate(ctx: BuildContext)¶

Hook invoked after performing validation.

pre_output_generation(ctx: BuildContext)¶

Hook invoked before generating outputs.

post_output_generation(ctx: BuildContext)¶

Hook invoked after generating outputs (but before writing outputs to files).

pre_output_writing(ctx: BuildContext, target_dir: OutputDir)¶

Hook invoked before writing outputs to files.

post_output_writing(ctx: BuildContext, target_dir: OutputDir)¶

Hook invoked after writing outputs to files.

Build Context¶

The BuildContext exposes runtime metadata including the internal representation of the design. It is shared between Topwrap and any loaded plugins. Use the documentation on the internal representation for insight into what the metadata represents.

class BuildContext(repo_modules: list[topwrap.model.module.Module], repo_interfaces: list[topwrap.model.interface.InterfaceDefinition], design_source: Union[topwrap.plugin.base.FileSource, topwrap.plugin.base.StringSource, NoneType], extra_sources: list[typing.Union[topwrap.plugin.base.FileSource, topwrap.plugin.base.StringSource]], top_module: Optional[topwrap.model.module.Module], loaded_modules: list[topwrap.model.module.Module], existing_interfaces: set[topwrap.model.misc.Identifier], outputs: dict[str, typing.Any] = <factory>, positions: dict[topwrap.model.misc.Identifier, topwrap.backend.kpm.common.Positions] = <factory>)¶

Bases: object

repo_modules : list[Module]¶

Modules loaded from repositories.

repo_interfaces : list[InterfaceDefinition]¶

Interface definitions loaded from repositories.

design_source : FileSource | StringSource | None¶

Path to the source file containing the design.

extra_sources : list[FileSource | StringSource]¶

Paths to additional source files to be parsed.

top_module : Module | None¶

Top-level module containing the design.

loaded_modules : list[Module]¶

All loaded modules.

existing_interfaces : set[Identifier]¶

List of identifiers of existing definitions in HDL code

outputs : dict[str, Any]¶

Map of generated outputs, keyed on the output stage name.

positions : dict[Identifier, Positions]¶

Map of module identifiers to the KPM position definitions.

property all_modules : Iterable[Module]¶