Metadata-Version: 2.4
Name: vitis-hls-init
Version: 0.1.1
Summary: Initialize versioned Vitis HLS host and kernel projects
Author: vitis-hls-init contributors
License-Expression: MIT
Keywords: vitis,hls,fpga,xrt,alveo
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/vitis_hls_init/vendor/2023.2/LICENSE.txt
License-File: src/vitis_hls_init/vendor/APACHE-2.0.txt
Requires-Dist: questionary<3,>=2.0
Requires-Dist: rich<15,>=13
Dynamic: license-file

# 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`](https://github.com/Xilinx/Vitis_Accel_Examples/tree/2023.2/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:

```bash
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:

```bash
vitis-hls-init my-project
```

Upgrade it in the same environment with:

```bash
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:

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

To keep it available in future Bash sessions:

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

The module can also be run without changing `PATH`:

```bash
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`:

```bash
pipx install vitis-hls-init
```

Upgrade an existing pipx installation with:

```bash
pipx upgrade vitis-hls-init
```

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

```bash
python -m pip install -e .
```

## Quick start

Run the interactive generator:

```bash
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`.

```text
? 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:

```text
? 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:

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

The project is ready when the generator finishes:

```bash
cd my-project
make run TARGET=sw_emu
```

For scripts and CI, pass every option without prompts:

```bash
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

```text
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:

```text
.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:

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

Available build targets follow the original example:

```bash
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:

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

Alternatively, pass it to each Make invocation:

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

An unpinned project keeps an empty assignment in `Makefile`:

```make
PLATFORM ?=
```

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

```make
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```text
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.
