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. .. code-block:: console xibif new [-h] -n NAME [-p PATH] [--force | --nuke] -b {zyboz710,zyboz720,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. .. list-table:: `xibif new` Arguments :widths: 20 80 :header-rows: 1 * - Argument - Description * - ``-n NAME, --name NAME`` - Name of the project to create * - ``-p PATH, --path PATH`` - Directory path where the project will be created * - ``--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: zyboz710, zyboz720, 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 simulation support via the VUnit framework (using the simulator selected with ``--simulator``). Refer to the `Simulation <../tutorials/simulation.html>`_ 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. .. code-block:: python 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 .. code-block:: python xibif build --to vivado:reportTiming to build the complete hardware project, or .. code-block:: python xibif build --stage vivado:synthesize to only perform the synthesis stage of the hardware building step. **Vivado Build Steps** .. list-table:: Vivado Build Options :widths: 25 75 :header-rows: 1 * - Build Step - Description * - ``blockdesign`` - Generate or refresh the Vivado block design * - ``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 **Vitis Build Steps** .. list-table:: Vitis Build Options :widths: 25 75 :header-rows: 1 * - 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 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 .. code-block:: python xibif build --stage vivado:bitstream vivado:export vitis:update vitis:build vitis:export vitis:bootfile vitis:updateLaunch 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 .. code-block:: python 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 .. code-block:: python xibif build --from vivado:bitstream .. note:: The `--from` and `--to` options can also be combined with specific stage selections defined with `--stage`. .. 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 .. code-block:: python xibif start hw_server After startup, you can flash the FPGA with the following command: .. code-block:: python 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. .. warning:: For boards that are powered over a USB connection (e.g. Zybo), flashing the bitstream can cause issues with board power. This depends on the USB board and other factors, so if you require this feature, make sure to use a dedicated power source. .. 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.