This chapter serves as documentation for the XiBIF package.

XiBIF API

from xibif import XibifAPI

to import XibifAPI into your Python script.

api.init

The init API lets you create the foundation for a XiBIF project. It creates the folder structure and the .xibif project file.

Commands

initialize_xibif_project(xibif_project: XibifProject, force: bool, nuke: bool)

Initialize a XiBIF project.

A XiBIF project is intialized with the name and folder being defined as CLI options. The project configuration is stored in the project folder as a ‘.xibif’ file in ‘.json’ format. It contains information about tooling and folder structure.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • force (bool) – Force creation of the project folder if it exists with creating a backup.

  • nuke – Force creation of the project folder if it exists without creating a backup.

Raises:

FileExistsError – The project folder already exists but no project file was found.

api.setup

The setup API populates an initialized XiBIF workspace with a valid project file.

Warning

Some of the APIs depend on files being present that are created through different API calls.

Commands

setup_default_hdl_files(xibif_project: XibifProject)

Creates the HDL files needed for the Vivado project initialization and saves them to ‘hw/src’ unless specified otherwise.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_demo_files(xibif_project: XibifProject)

Creates the XiBIF Python and Matlab demo files.

Creates demo files that show the usage of the Python interface to the XiBIF hardware. The demo files are created in ‘sw/python’ unless specified otherwise.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_git_files(xibif_project: XibifProject)

Creates the XiBIF git files.

Creates the git files for the XiBIF project. This consists of a .gitignore file and a .gitlab-ci.yml file.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_openlogic_files(xibif_project: XibifProject)

Copies the openlogic files to the local folder.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_openlogic_vivado(xibif_project: XibifProject)

Adds the openlogic files to the Vivado project.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_register_files(xibif_project: XibifProject)

Creates the XiBIF user registers.

The user registers are created as an AXIS instance and can be used to easily control the FPGA hardware. Upon project creation, a default register file is created in ‘hw/src’, which can later be changed by adjusting the register file in ‘hw/regs’.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_sigasi_project(xibif_project: XibifProject)

Creates a basic Sigasi project and saves it into ‘hw/sigasi’ unless specified otherwise.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_vitis_project(xibif_project: XibifProject)

Creates and initializes a Vitis project for the given configuration.

The project is created in ‘hw/vitis’ unless specified otherwise.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_vivado_project(xibif_project: XibifProject)

Creates and initializes a Vivado project for the given configuration.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

setup_vunit_python_files(xibif_project: XibifProject)

Creates the VUnit Python files needed for the Vivado project initialization and saves them to ‘hw/tb/vunit’ unless specified otherwise.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

api.register

The register API interfaces with Corsair and let’s you generate project-specific register files.

Commands

register_disable_custom(xibif_project: XibifProject)

Disable custom register generation in the project configuration.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

register_enable_custom(xibif_project: XibifProject, cfg_path: Path)

Enable custom register generation in the project configuration.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • cfg_path (Path) – The path to the corsair configuration file.

register_files_did_change(xibif_project: XibifProject) → bool

Check if the register files Have changed since last generating.

register_generate_custom(xibif_project: XibifProject)

Generate registers with custom generators defined in a corsair configuration file. The paths specified in the configuration file are relative to the corsair source folder of the project (hw/src/).

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

register_generate_stream(xibif_project: XibifProject)

Generate the AXI-Stream Registers for XiBIF.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

register_generate_user(xibif_project: XibifProject)

Generate the user-defined registers for XiBIF.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

api.build

The build API allows you to build your project in Vivado and Vitis.

Commands

build_vitis(xibif_project: XibifProject, stages: list[str] = None, disable_warning: bool = False)

Build the Vitis project

Executes the build stage of the Vitis flow to generate a BOOT.bin file to be loaded onto the FPGA. The timestamp of the last Vivado build is checked to warn the user if the last build is older than one hour.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • list[str] (stages) – List of stages to build. If not provided, all stages are built.

Raises:

FileNotFoundError – A required file was not found.

build_vivado(xibif_project: XibifProject, stages: list[str] = None, noreport: bool = False)

Build the Vivado project.

Executes all build stages of the Vivado flow (compile, synthesize, implement, bitsream) and saves the resulting bitstream and hardware files to the result folder.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • list[str] (stages) – List of stages to build. If not provided, all stages are built.

  • bool (noreport) – Do not generate output reports for Vivado

Raises:

FileNotFoundError – A required file was not found.

regenerate_vitis(xibif_project: XibifProject)

api.flash

The flash API allows you to flash an FPGA.

Warning

The flashed bitstream is not persistent.

Commands

flash_hardware_server(xibif_project: XibifProject, hardware_server: str, port: str)

Flash the generated BOOT.bin to the FPGA.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • hardware_server (str) – Name of the hardware server.

  • port (str) – Port of the hardware server.

Raises:

FileNotFoundError – A required file was not found.

api.simulate

The simulate API allows you to simulate your design in vunit.

Commands

simulate_add_vunit_lib(xibif_project: XibifProject, vhdl_version: str)

Add the VUnit library to the vivado project.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • vhdl_version (str) – The VHDL version to use.

simulate_clean_up_xml(xibif_project: XibifProject)

Clean up the JUnit XML file generated by VUnit.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

simulate_compile_vunit_lib(xibif_project: XibifProject)

Compile the VUnit library.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

simulate_compile_xilinx_lib(xibif_project: XibifProject)

Compile the Xilinx library using Vivado.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

simulate_list_testbenches(xibif_project: XibifProject)

List all available testbenches in the project.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

simulate_run(xibif_project: XibifProject, testbench: list[str] = None, gui: bool = False)

Run the simulation using VUnit.

Parameters:

  • xibif_project (XibifProject) – The configuration object of the project.

  • testbench (list[str]) – The name of the testbench to run.

  • gui (bool) – Whether to run the simulation in GUI mode.

Returns:

True if the simulation was successful, False otherwise.

api.shell

The shell API allows you to connect to a XiBIF board in an interactive shell.

Commands

open_xibif_shell(autoconnect: bool, autoload: bool, ip)

api.testbench

The testbench API allows you to generate testbenches for your design.

Commands

testbench_generate(hdl_vhdl_file: Path, hdl_tb_folder: Path, hdl_tb_vunit_folder: Path, clock: list = None, resetn: list = None, resetp: list = None, gen_excel: bool = False)

Generate a testbench from a VHDL file

Parameters:

  • hdl_vhdl_file (Path) – Path to the VHDL file

  • hdl_tb_folder (Path) – Path to the directory containing the testbench files.

  • hdl_tb_vunit_folder (Path) – Path to the directory containing the VUNIT testbench files.

  • clock (list) – List of clocks

  • resetn (list) – List of negative resets

  • resetp (list) – List of positive resets

  • gen_excel (bool) – Generate an Excel file

Raises:

RuntimeError – An error occurred while creating the testbench.

api.upgrade

The upgrade API allows you to upgrade the project to the latest version of XiBIF.

Commands

upgrade(xibif_project: XibifProject)

Upgrade an existing XiBIF project.

Parameters:

xibif_project (XibifProject) – The configuration object of the project.

Raises:

RuntimeError – An error occurred while modifying the Vivado project file to set up the demo.