Constructing, configuring and loading repositories

By using Topwrap repositories, you can package and load different resources and use them in your designs.

You can specify the repositories to be loaded each time Topwrap runs, by listing them in a configuration file or by supplying a path to one or more repository directories using the --repo CLI argument.

A single repository can store multiple resource types. Each supported type is associated with a subdirectory in the top-level repository directory.

A sample repository can be found in examples/user_repository.

Supported resource types

IP cores

  • Path: repo_dir/cores/

The “Core” resource represents a self-contained IP core/module that can then be used as a component in a custom design created by the user. It corresponds to Internal Representation Module object.

A resource is stored in the module.yaml file, it follows IP description format. It contains information about the HDL module and should be generated by topwrap repo parse, but it can be done manually. The module.yaml should be edited by a user to fill in information’s that cannot be deduced from the HDL file or when there is a custom interface that does not have an Interface Definition.

Interface definitions

  • Path: repo_dir/interfaces/

This resource represents a custom definition of an interface that can be used to make connections between IP cores.

Each such definition is stored as a separate interface description file under the interfaces subdirectory.

Interface port mappings

  • Path: repo_dir/mappings/

This resource represents a custom mapping from a module’s ports to an interface.

Mappings are stored in interface mapping files under the mappings subdirectory, with each file containing one or more mapping.

CLI

topwrap repo init

topwrap repo init [OPTIONS] REPO_NAME REPO_PATH

This command creates and initializes a new repository named REPO_NAME in a chosen REPO_PATH.

By default, it also adds the entry with the new repository into the local Topwrap configuration file. If the file does not exist, it gets created. This behavior can be disabled using the --no-config-update CLI flag.

topwrap repo list

topwrap repo list

This will print out names and paths of all repositories from which resources are loaded and can be used in other Topwrap commands.

topwrap repo parse

topwrap repo parse [OPTIONS] REPOSITORY SOURCES...

This command will parse all supported source files given in the SOURCES argument, extract IP cores from them, and save them in a repository given by the REPOSITORY argument.

Note

When a directory path is given among the SOURCES argument, it gets recursively expanded and all nested files are extracted from it.

To see the listing of all supported OPTIONS, see topwrap repo parse --help

Using the open source IP cores library with Topwrap

Topwrap comes with built-in support for an extensive library of open source IP cores available through the FuseSoC package manager, which also serves as a build system. This library offers a wide range of reusable IP cores for various applications, enabling easy integration into Topwrap projects. Topwrap simplifies the process of accessing, downloading, and packaging these IP cores, making them readily available for local use in your designs.

To include an IP core from the open source library, there are two methods:

  1. Select the Desired Core: Browse the available cores (cores_export artifact).

  2. Download and build all available cores: Use Topwrap’s package management command:

  nox -s package_cores

This will download and parse all the cores from Fusesoc into build/fusesoc_workspace/build/export/cores/, making them accessible from within Topwrap.

You can learn more about Topwrap integration with FuseSoC here

Last update: 2026-06-03