This tutorial will explain briefly how to take Reconfigurable modules (RM) from one of the three Reconfigurable Partitions (RP) in the composable overlay design and rebuild them within a different RP. This is mainly a proof of concept for adding to the composable overlay design but using the already developed filters that make up the RM. The composable overlay is a very effective and versatile design that I believe is revolutionising the video processing capability that FPGAs possess.
This example uses vivado 2022.2 to generate bitstreams for a Kria KV260 operating on PYNQ 3.0.1.
This operation was carried out on a linux PC so that the Github repo below could be cloned retaining its file structure and then the makefile was ran to build the project from the surrounding build files. (PYNQ Composable Overlay Default Path - #13 by cking onwards for the process and error propagation)
The correct github for cloning can be found: GitHub - mariodruiz/PYNQ_Composable_Pipeline: Composabe Pipeline
Set Up
The design is optimised for the abstract shell flow vivado provides, which greatly reduces the steps and implementation time required to create partial bitstream files (of the new RM) that can be loaded onto the board alongside the static bitstream and loaded to the handy Jupyter API via PYNQ. This procedure requires a strong understanding of how the Abstract shell flow works, which can be sourced from the following guides:
- Creating a new RM for a similar design on the KV260: Create a new accelerator RM — Kria SOM DFX Examples 1.0 documentation
- More in depth tutorial of abstract shell for an unrelated project: AMD Adaptive Computing Documentation Portal
- Breaking down the Abstract flow: AMD Adaptive Computing Documentation Portal
From guide one I was able to create two tcl scripts which can be run in order within vivado to automate the procedure:
Template script for building + synthesising RM: Adding_RM_template.tcl (3.7 KB)
Template script for linking RM with RP: link_design.tcl (1.2 KB)
KEY: Create a new vivado project, without any sources declared and the KV260 board specifications selected. Then change the working directory to the source of the build files (from the cloned github repo) to where the “cv_dfx_3_pr.tcl” file resides. Then within the vivado tcl console run “source cv_dfx_3_pr.tcl” - this will declare necessary variables and I/O required to add RM
→ in sourcing the file it requires other files nearby to source such as the pinout.xdc as well as the IP repository - hence it is easier to clone the repo.
→ note: the “cv_dfx_3_pr.tcl” should run untill it prompts the following error:
The"bdc_dfx.tcl" file is not required, by this point all essential variables have been defined and the “video_cp.bd” design can be opened.
The Procedure
In this example the new RM are built following the same format as that in the initial build as can be found in the “bdc_dfx.tcl” as part of the github (bdc_dfx.tcl (24.8 KB)). This script can act as a template from which all code required to build the RM within Vivado can be copied from, into the “Adding_RM_template.tcl” script under the correct section, see below:
Just make sure to change all instances of the “pr_” to the new RP you desire to place the RM into, for example above the corner harris filter is moved from pr_1 to pr_0.
You will need to personalize this script before operation to make it work with your vivado project and for your specific purpose. Firstly, change the introductory variable definitions to match:
After this, with the build script for the new RM inserted the block design requires synthesised. This is carried out in the section of the script shown below, which needs adjusted to fit. Un-hash the target RP and add the block design name (.bd file) of the new RM to this list per RP (ensuring to change the “pr_”) as shown for the corner harris to pr_0 example:
The last part of the script shouldn’t require any changes, it carries out block design generation and creates the design checkpoint file (dcp) for the newly generated RM.
ERRORS: note that the majority of errors which crop up will be because the working directory within vivado is looking for files in the wrong place. Investigate the filepaths shown in the script and investigate the working location in vivado using standard linux “cd” and “pwd” commands.
After running the “adding_RM_template.tcl” script the dcp created for the RM will be located beside the block design for the RM, under the project.sources file structure. In the Abstract shell flow this RM dcp is paired with the dcp output from the original project generation that provides a snapshot of the essential routing in and out of the target RP. This procedure is carried out in the “link_design.tcl” script
As before, this script requires some project personalisation. Hence enter the “link_design.tcl” in an editor of choice and add the correct file path directed towards the two required dcp files, shown below is the corner harris to pr_0 example:
Once edited, within the vivado project in the tcl console direct the working directory to the correct location where the tcl script resides and run “source link_design.tcl”. This will launch a new project, add the two dcp files and link the two designs before generating a bitstream to a location the user must specify beside the “write_bitstream” command .
Adding the partial bitstream to the board
There is one golden rule to follow with the abstract shell flow:
The full static bitstream and the design checkpoint file used to pair the RM must be from the same initial build
This is because the dcp of the RP region used is created from a snapshot of the same floorplan as was used for the full static bitstream - hence the routing is identical.
Therefore when adding the partial .bit (alongside the partial.hwh file!!) to the board the best way is to place it into the original “overlay” folder where the static and partial .bit and .hwh files were generated. Then transfer this folder over to the KV260 board.
Within Jupyter then dictate the full path of the full static bitstream in the new folder when declaring the “overlay” variable, as shown below:
As you can see in the above image “cpipe.c_dict.unloaded” can be used within the tutorials to check if the new RM are recognised by PYNQ (see the cornerharris under the new pr_0 RP).
And that’s it! You have added a new RM to a different RP, a working proof that new filters can be added to the already equipped composable pipeline.
Note: for any error propagation check out the initial support thread that started this work: Adding Reconfigurable Modules to Partitions in the Composable Pipeline Design