vitis-hls-init 0.1.1

Initialize versioned Vitis HLS host and kernel projects

vitis-hls-init

Create a versioned Vitis accelerator project without manually renaming kernels, executables, source paths, and XCLBIN targets.

The generated project follows the Vitis_Accel_Examples/hello_world layout and retains its Makefile → makefile_us_alveo.mk → utils.mk build structure.

Requirements

The generator requires Python 3.9 or later. Building a generated project requires:

• Vitis 2023.2
• Xilinx Runtime (XRT)
• A supported Alveo platform
• Linux host environment

Supported Vitis versions

The initial release supports Vitis 2023.2 only. Project generation already includes an explicit version selection step and the non-interactive --vitis-version option. Future releases can add snapshots from other Vitis_Accel_Examples branches without changing the generated project layout.

Each supported release keeps separate upstream and starter-code snapshots. Do not assume that projects or build files generated for different Vitis releases are interchangeable.

Installation

The package is published as a command-line application. You can install it with regular pip inside a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install vitis-hls-init

The vitis-hls-init command is available while that environment is active:

vitis-hls-init my-project

Upgrade it in the same environment with:

python -m pip install --upgrade vitis-hls-init

Using a virtual environment avoids modifying a system or Homebrew-managed Python installation. Do not use --break-system-packages for normal installation.

If pip falls back to a user installation and reports that ~/.local/bin is not on PATH, the package is installed but the shell cannot find its command. Add the directory for the current shell:

export PATH="$HOME/.local/bin:$PATH"
vitis-hls-init --version

To keep it available in future Bash sessions:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

The module can also be run without changing PATH:

python3 -m vitis_hls_init --version

Because this package is a standalone CLI, pipx is a convenient alternative that manages the virtual environment automatically and exposes the command on your PATH:

pipx install vitis-hls-init

Upgrade an existing pipx installation with:

pipx upgrade vitis-hls-init

For local development, install the checkout in editable mode from an active virtual environment:

python -m pip install -e .

Quick start

Run the interactive generator:

vitis-hls-init my-project

Select the Vitis release and kernel name, then choose whether to pin a default platform in the project. Platform pinning defaults to n so generated projects remain portable. If pinning is enabled and PLATFORM exists in the current environment, the generator offers that value before asking for another name or .xpfm path. VS Code integration is also a y/n question and defaults to n.

? Vitis version
  2023.2
? Kernel name my_project
? Pin a default platform in this project? (y/N)

No default platform will be written. Set $PLATFORM in each shell or pass
PLATFORM=... to Make.
? Add Visual Studio Code settings? (y/N)

When platform pinning is enabled:

? Pin a default platform in this project? Yes

Detected platform from $PLATFORM
  xilinx_u250_gen3x16_xdma_4_1_202210_1

? Use this platform? (Y/n)

PLATFORM must be exported so the generator and Make can read it:

export PLATFORM=xilinx_u250_gen3x16_xdma_4_1_202210_1
vitis-hls-init my-project

The project is ready when the generator finishes:

cd my-project
make run TARGET=sw_emu

For scripts and CI, pass every option without prompts:

vitis-hls-init my-project \
  --vitis-version 2023.2 \
  --kernel vector_add \
  --platform xilinx_u250_gen3x16_xdma_4_1_202210_1 \
  --ide vscode \
  --yes

With --yes, no default platform is pinned unless --platform is explicitly provided. The current PLATFORM environment variable is intentionally not written into the project in non-interactive mode. VS Code files are generated only when --ide vscode is specified.

Name validation

Names are validated while they are entered in interactive mode.

• Project directory names may contain ASCII letters, digits, hyphens, and underscores, and must start with a letter or digit.
• Kernel names must be valid portable C++ identifiers containing letters, digits, and underscores, and must start with a letter.
• C++ reserved keywords such as class, template, and operator are rejected.
• Leading underscore kernel names are rejected because they can enter reserved implementation namespaces at global scope.
• Existing non-empty destinations are rejected before generation begins.

Non-interactive arguments are validated using the same rules.

Generated project

my-project/
├── common/
│   ├── data/
│   ├── includes/
│   └── utility/
├── src/
│   ├── host.cpp
│   └── vector_add.cpp
├── Makefile
├── makefile_us_alveo.mk
├── utils.mk
├── README.rst
├── description.json
├── details.rst
├── qor.json
├── xrt.ini
├── APACHE-2.0.txt
└── LICENSE.txt

When --ide vscode is selected, the generator also adds:

.vscode/
├── c_cpp_properties.json
├── extensions.json
└── tasks.json

The selected kernel name is applied consistently to:

• The kernel C++ function and source filename
• The XRT kernel name used by the host
• XO, linked XCLBIN, and packaged XCLBIN paths
• Makefile build and run targets
• description.json, qor.json, and generated documentation

The generated Makefile recursively tracks C/C++ sources, headers, and include fragments under src/. Adding or changing files such as src/include/types.hpp therefore rebuilds the host executable and kernel object as needed; the compile commands still receive only their intended entry-point source files.

The top-level Makefile explicitly uses /bin/bash because the upstream build recipes contain Bash-specific conditionals such as [[ ... ]]. This avoids [[: not found errors on systems where /bin/sh points to dash.

The complete upstream common/ directory from branch 2023.2 is included in each generated project. Files are copied byte-for-byte from the upstream snapshot. The surrounding project layout and build files come from the upstream hello_world example; project parameters, the HLS starter kernel, host test structure, and memory mappings are adapted for boilerplate use. The generated project therefore does not depend on a separately cloned examples repository.

Kernel and host starter code

The generated kernel uses a load/compute/store dataflow structure. Every loop in those modules has an explicit #pragma HLS pipeline II = 1, and streams use .read() and .write() calls. Stream depths are left to HLS unless the design requires explicit FIFO sizing.

In src/host.cpp, command-line parsing, device selection, and XCLBIN loading remain in main(). The section marked PROJECT TEST CODE contains the intended customization points:

• prepare_test_data() creates inputs and the software reference.
• run_test() allocates buffers and invokes the kernel; update it when the kernel signature changes.
• verify_test_result() checks device output.

main() calls run_test() and reports pass or failure, keeping reusable XRT application setup separate from project-specific testing.

run_test() also measures the host-observed XRT kernel execution interval from kernel launch through xrt::run::wait() with std::chrono::steady_clock and prints it in seconds with nanosecond decimal precision. Input and output buffer synchronization is outside this interval.

Building

Load Vitis 2023.2 and XRT before invoking Make:

source <Vitis installation>/Vitis/2023.2/settings64.sh
source /opt/xilinx/xrt/setup.sh

Available build targets follow the original example:

make host
make build TARGET=sw_emu
make run TARGET=sw_emu
make run TARGET=hw_emu
make run TARGET=hw
make clean
make cleanall

When no default platform is pinned, export it after opening a new shell:

export PLATFORM=/path/to/platform.xpfm
make run TARGET=sw_emu

Alternatively, pass it to each Make invocation:

make run TARGET=sw_emu PLATFORM=/path/to/platform.xpfm

An unpinned project keeps an empty assignment in Makefile:

PLATFORM ?=

Exported environment values are still used because ?= only assigns when the variable is undefined. To pin a default later, edit the same line:

PLATFORM ?= /path/to/platform.xpfm

DDR and HBM mapping

The generated utils.mk includes --connectivity.sp mappings selected by MEMORY_TYPE. DDR is the default:

make build TARGET=hw MEMORY_TYPE=DDR

It maps in1 and out to DDR[0] because those arguments share the kernel's gmem0 interface, and maps in2 to DDR[1]. On an HBM-capable platform, use:

make build TARGET=hw MEMORY_TYPE=HBM

The HBM variant uses HBM[0] and HBM[1]. These are starter mappings: the selected banks must exist on the chosen platform, and utils.mk must be updated when kernel ports or HLS interface bundles change.

Visual Studio Code

VS Code integration is optional and does not change the upstream-derived project files:

vitis-hls-init my-project --ide vscode

The generated IntelliSense configuration uses XILINX_XRT, XILINX_VITIS, XILINX_HLS, and XILINX_VIVADO instead of hard-coded installation paths. The C/C++ extension detects the compiler and IntelliSense architecture from the active local, Remote SSH, container, or ARM64 environment. Load the Vitis and XRT environments before launching VS Code:

source <Vitis installation>/Vitis/2023.2/settings64.sh
source <XRT installation>/setup.sh
code .

The generated tasks build the host, build and run sw_emu, and clean build outputs. The Microsoft C/C++ extension is listed as a workspace recommendation.

CLI reference

vitis-hls-init [PROJECT] [OPTIONS]

Options:
  -k, --kernel NAME       C++ kernel function name
      --vitis-version V   Vitis release to target (currently: 2023.2)
  -p, --platform VALUE    Pin a default Vitis platform name or .xpfm path
      --ide VALUE          Optional IDE configuration: none or vscode
  -y, --yes               Accept defaults without interactive questions
      --version           Print the installed version
  -h, --help              Show help

Current scope

The first release supports Vitis 2023.2, Alveo platforms, the XRT native API, and a single HLS C++ kernel based on the vector-add hello_world example.

License

The Python generator is available under the MIT License. The vendored upstream MIT LICENSE.txt, the full APACHE-2.0.txt, and applicable file-level notices and attributions are preserved in generated projects. Additional attribution details are included in THIRD_PARTY_NOTICES.md in the source distribution.

Xilinx, Vitis, and Alveo are trademarks of their respective owners. This is an independent community project and is not affiliated with or endorsed by AMD or Xilinx.