Example projects¶
These example projects show some useful ways in which Topwrap can be used by the end-user.
Information about embedded GUI
This section extensively uses an embedded version of Topwrap’s GUI, Kenning Pipeline Manager, to visualize the design of all the examples.
You can use it to freely explore the entire design, add new blocks, connections, nodes and hierarchies. You cannot however use features that require direct connection with the Topwrap’s backend. These features include, among others:
Saving and loading data from/to
.yamlfilesVerifying designs
Building designs
Tip
Don’t forget to use the “Enable fullscreen” button if the viewport feels too small!
Constant¶
There is often a need to pass constant values to input ports of some IP Cores.
This example shows how easy expressing that is in the GUI and correspondingly, in the design description file (project.yml).
Tip
You can find the constant node blueprint in the Nodes browser under the Metanode section.
Usage¶
Enter the example’s directory
cd examples/constant
Generate HDL source
make generate
Inout¶
This example showcases the usage of an inout port and the way it’s represented in the GUI.
Tip
An inout port is denoted in the GUI by a green circle without a directional arrow inside.
The design consists of 3 modules: input buffer ibuf, output buffer obuf, and bidirectional buffer iobuf.
Their operation can be described as:
input buffer is a synchronous D-type flip flop with an asynchronous reset
output buffer is a synchronous D-type flip flop with an asynchronous reset and an
output enable, which sets output to high impedance state (Hi-Z)inout buffer instantiates 1 input and 1 output buffer. Input of the
ibufand output of theobufare connected with an inout wire (port).
Usage¶
Enter the example’s directory
cd examples/inout
Install required dependencies
pip install -r requirements.txt
Generate bitstream for Zynq
make
Generate HDL sources without implementation
make generate
User repository¶
This example presents a structure of a user repository containing prepackaged IP cores with sources and custom interface definitions, the design file and the config file.
Elements of the repo directory can be easily reused in different designs as long as you point to it either in the config file or in the CLI.
See also
For more information about user repositories see Packaging multiple files.
Tip
Because other components of the design are automatically imported from the repository, it’s possible to load the entire example by specifying just the design file:
topwrap kpm_client -d project.yml
Usage¶
Build and run Pipeline Manager server
python -m topwrap kpm_build_server
python -m topwrap kpm_run_server
Navigate to /examples/user_repository/ directory and run:
python -m topwrap kpm_client -d project.yml
Connect to the web GUI frontend in your browser on http://127.0.0.1:5000.
Expected result
Topwrap will load two cores from the cores directory that use an interface from the interfaces directory.
In the Nodes browser under IPcore, two loaded cores: core1 and core2, should be visible.
Hierarchy¶
This example shows how to create a hierarchical design in Topwrap. It includes a hierarchy containing some IP cores and other nested hierarchies.
Check out project.yml to learn how does the above design translate to a design description file
See also
For more information about hierarchies see hierarchies docs.
Tip
Hierarchies are represented in the GUI by nodes with a green header.
You can display their inner designs by clicking the Edit subgraph option from the right click menu.
To exit from the hierarchy subgraph, find the back arrow button in the top left.
To add a new hierarchy node use the New Graph Node option in the node browser!
Usage¶
This example contains user repo (repo directory) and a configuration file for topwrap (topwrap.yaml) so it can be loaded by running
python -m topwrap kpm_client -d project.yml
in this example’s directory.
PWM¶
Tip
The IP Core in the center of the design (axi_axil_adapter) showcases how IP Cores with overridable parameters are represented in the GUI.
This is an example of an AXI-mapped PWM IP Core that can be generated with LiteX being connected to the ZYNQ Processing System.
The Core uses AXILite interface, so a proper AXI -> AXILite converter is needed.
You can access its registers starting from address 0x4000000 (that’s the base address of AXI_GP0 on ZYNQ).
The generated signal can be used in FPGA or connected to a physical port on a board.
Note
To connect the I/O signals to specific FPGA pins, you need proper mappings in a constraints file. See zynq.xdc used in the setup and modify it accordingly.
Usage¶
Enter the example’s directory
cd examples/pwm
Install required dependencies
pip install -r requirements.txt
In order to be able to generate a bitstream you also need to install Vivado and add it to your PATH.
Generate bitstream for Zynq
make
If you wish to generate HDL sources without running Vivado, you can use
make generate
HDMI¶
This is an example on how to use Topwrap to build a complex, synthesizable design.
Usage¶
Enter the example’s directory
cd examples/hdmi
Install required dependencies
pip install -r requirements.txt
In order to be able to generate a bitstream you also need to install Vivado and add it to your PATH.
Generate bitstream for desired target
Snickerdoodle Black:
make snickerdoodle
Zynq Video Board:
make zvb
If you wish to generate HDL sources without running Vivado, you can use
make generate
SoC¶
This is an example on how to use Topwrap to build a synthesizable SoC design. The SoC contains a VexRiscv core, data and instruction memory, UART and interconnect that ties all components together.
Usage¶
Enter the example’s directory
cd examples/soc
Install required dependencies
sudo apt install git make g++ ninja-build gcc-riscv64-unknown-elf bsdextrautils
To run the simulation you also need:
verilator
To create and load bitstream you also need:
vivado (preferably version 2020.2)
openFPGALoader (this branch)
Generate HDL sources
make generate
Build and run simulation
make sim
Expected waveform generated by the simulation is shown in expected-waveform.svg.
Generate bitstream
make bitstream