Hardware Design Flow

Creating a Project

Creating a XiBIF project means that a new directory is created and set up for hardware design. The necessary project files are created.

xibif new [-h] -n NAME [-p PATH] [-f | --nuke] -b {zyboz10,zyboz20,zedboard,zcu104,zcu102,kv260} [-x XILINX] [-v VERSION]

The command requires that you specify a name and a target board for the project. The project will then be created in ${pwd}/NAME unless you specify a different path with the -p option. If the directory already exists, you can use the –force or –nuke options to delete existing files. The –force backs up the existing project before creating the new one, the –nuke deletes everything in the directory.

XiBIF tries to find a Xilinx installation on your system by looking at the default installation paths. If the path cannot be found or you want to use an older (not the newest) version of the toolchain, you can specify the path to your Xilinx installation with the -x option and the version with the -v option.

xibif new Arguments
Argument	Description
`-n NAME, --name NAME`	Name of the project to create
`-p PATH, --path PATH`	Directory path where the project will be created
`-f, --force`	Delete only project-related files if directory exists
`--nuke`	Delete everything in the project directory if it exists
`-b BOARD, --board BOARD`	Target board: zyboz10, zyboz20, zedboard, zcu104, zcu102, or kv260
`-x XILINX, --xilinx XILINX`	Path to Xilinx installation (typically C:\Xilinx)
`-v VERSION, --version VERSION`	Xilinx toolchain version to use (e.g., 2024.2)

Warning

There are some restrictions on the name your project can have. The project name can only consist of alphanumeric characters (a-z, A-Z, and 0-9) and underscores. Any other character is illegal. Furthermore, the path to a project folder is also restricted to alphanumeric characters, underscores, dashes, and dots.

If you are still in the habit of using spaces in your project names and/or paths, please get rid of them! Spaces in names are a pain to deal with when programming, especially when going cross-platform.

Note

If you are interested, the Regex patterns to match are:

^[a-zA-Z0-9_]+$ for the project name
^[a-zA-Z0-9_/-\.]+$ for project paths on Unix-based systems
^[a-zA-Z]:[\\a-zA-Z0-9_/\-\.]+$ for project paths on Windows

Warning

Vitis version 2024.1 has a nasty bug which leads to failed builds after the initial build. Try to avoid using version 2024.1 if possible.

Simulating the Design

Before building the hardware design, it is often useful to simulate it to verify that it behaves as expected. XiBIF provides a way to run simulations using Vivado’s built-in simulator. Refer to the Simulation for more information on how to set up and run simulations for your XiBIF project.

Building a Project

To generate something that can be used by the FPGA to boot from, you must build the project. Building refers to many steps: logic synthesis, place-and-route, bitstream generation, hardware export, software compilation, and finally bundling of the bitstream with the software to generate a boot file from which the FPGA can load its hardware and software configuration.

xibif build

This executes all Vivado and Vitis build stages for the project. Assuming that your design passes all timing checks and has no violations in Vivado, this step should succeed. Since this is a complete run-through of all Vivado and Vitis design stages, it takes a while, so go get a coffee (or tea, whichever you prefer).

Once finished, you will find a lot of reports in hw/results/ containing information about the design run, such as FPGA utilization, timing reports, and more. In the same folder, you will also find the aforementioned BOOT.bin file which you can copy to an SD card for the FPGA to boot from.

Hint

If you need to open Vivado or Vitis, this can be done with xibif start vivado or xibif start vitis. This will then open the respective tool with your project loaded.

Building in Steps

If you only wish to build the hardware project, you can use

xibif build --vivado all

to build the complete hardware project, or

xibif build --vivado synthesize

to only perform the synthesis stage of the hardware building step.

Vivado Build Steps

Vivado Build Options
Build Step	Description
`installBoard`	Install board support files into Vivado
`synthesize`	Run logic synthesis on the hardware design
`implement`	Run place and route (implementation)
`bitstream`	Generate the FPGA bitstream file
`export`	Export hardware design for Vitis software development
`reportTiming`	Generate timing analysis reports
`all`	Execute all Vivado build steps in order

Vitis Build Steps

Vitis Build Options
Build Step	Description
`update`	Update the Vitis workspace with latest hardware export
`build`	Compile the software application
`export`	Export the compiled software artifacts
`bootfile`	Generate the BOOT.bin file for SD card boot
`updateLaunch`	Update Vitis launch configurations to use the latest bitstream
`all`	Execute all Vitis build steps in order

It is also possible to combine multiple steps. They will be executed in the correct order, regardless of the order in which you specify them. For example, to build the bitstream and then export the hardware design for Vitis, and finally build the complete software project, use

xibif build --vivado bitstream --vivado export --vitis all # Build bitstream, export hardware, and build software. The tool is given for clarity.
xibif build --vivado bitstream export --vitis all # Same as above, but shorter.

Alternatively, you can also specify a range of stages to build using the –from and –to options. For example, to build everything from synthesis to bitstream generation in Vivado, use

xibif build --from vivado:synthesize --to vivado:bitstream

It is also possible to use only one of the two options. For example, to start at bitstream generation and build everything until the end of the build process, use

xibif build --from vivado:bitstream

Note

The –from and –to options can also be combined with specific stage selections defined with –vivado and/or –vitis.

Note

Building in steps can be especially useful when things go wrong. You usually do not want to re-build everything every single time. But be aware: for many designs, a failure to build can come from earlier errors.

Flashing the FPGA

The process of configuring the FPGA with the bitstream is referred to as flashing. To flash the FPGA with the generated bitstream, you must connect your FPGA board to your computer via USB or JTAG and ensure that the Xilinx Hardware server is running.

You can start the hardware server using

xibif start hardware_server

After startup, you can flash the FPGA with the following command:

xibif flash

This uses the Xilinx Hardware server to flash the bitstream onto the FPGA. Be aware that the FPGA must already have an appropriate xibif software part for this to work. This command exists to speed up hardware iterations.

Hint

The flashed bitstream is not persistent! If you wish to boot using a bitstream every time, you need to build the hardware and software part of the project and copy the BOOT.bin file to the FPGA’s SD card.