Skip to content

hlsBs: engine bug fixes, new system_vitis_unified_hlsBs.mk make backend, vitispy flake8 cleanup, and doc fixes - #404

Open
ruck314 wants to merge 8 commits into
jj-devfrom
ruckman-dev
Open

hlsBs: engine bug fixes, new system_vitis_unified_hlsBs.mk make backend, vitispy flake8 cleanup, and doc fixes#404
ruck314 wants to merge 8 commits into
jj-devfrom
ruckman-dev

Conversation

@ruck314

@ruck314 ruck314 commented Jul 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Cleans up and extends the hlsBs (Vitis-unified HLS) subsystem under vitis/hlsBs/, targeting jj-dev. Scope is confined to that subsystem plus a 4-line CI tweak — no repo-root scripts/, root .flake8, or .vhd changes. Squashed into 7 thematic commits for review.

Commits (review in this order)

  1. fix(hlsBs): correct engine run, cosim, config, and IP bugs — behavioral fixes in the vitispy engine: multi-stage run/latent command bugs; emit rel_path #defines bare so cosim can #include them; repair IP family augmentation + propagate the run exit status; emit the clock_uncertainty cfg key (was the ignored uncertainity); hlsWs --status returns a usable exit status; remove the stale IP zip before rezip; realpath both operands in make_relative so symlinked repo paths resolve.
  2. feat(hlsBs): add system_vitis_unified_hlsBs.mk make wrapper — a make front-end over the reusable hlsBs engine, steered by a single per-target project descriptor (firmware/targets/<Name>/project/<Name>.py). Mirrors the system_vitis_unified_hls.mk CLI flow so a target builds with plain make instead of the hlsWs/hlsCfg/hlsRun sequence. clean removes build/ + the target .Xil scratch dir, preserving ip/.
  3. docs(hlsBs): fix README/man typos, FPGA family list, and HLSBS_INI env var name — grammar/typos across README.md and man1/*; FPGA family list; HLSBS_INI env var name; corrects the documented logical symbol fpga_uncertainity → fpga_uncertainty to match the name the engine actually generates (maps.py Fpgas table).
  4. style(hlsBs): flake8-clean the vitispy engine under surf config — mechanical only. Whitespace/spacing/unused-import cleanup of vitis/hlsBs/vitispy under the surf flake8 config, plus a few undefined-name fixes surfaced by the linter. Large diff but no behavior change — safe to skim.
  5. ci(ruckus): lint the hlsBs vitispy engine — add vitis/hlsBs/vitispy to the CI compileall + flake8 step (alongside the existing scripts/). 4-line change to .github/workflows/ruckus_ci.yml.
  6. fix(hlsBs): sys.path bootstrap before vitispy imports; engine typos and dead branch — run the sys.path bootstrap before vitispy imports in the CLI entry points; correct engine typos and a dead-branch call.
  7. docs(hlsBs): fix man-page roff markup, README code-block typos, and Caveats heading — roff markup fixes, README code-block typos, .SS for the Caveats heading in hlsBs.1.

Scope notes

  • Confined to the hlsBs subsystem: the vitispy engine, vitis/hlsBs/scripts/setup_hls.sh, README.md + man1/*, the new system_vitis_unified_hlsBs.mk, and one CI-step edit.
  • The repo-root scripts/ and the root .flake8 are intentionally not modified (they match the base branch).

Documentation

  • The hlsBs subsystem is documented by its own vitis/hlsBs/README.md + man1/* pages — updated here (commits 3 and 7).
  • No Sphinx .rst changes are required: the docs/ tree does not reference hlsBs/vitispy/the hls* commands, and nothing this PR renamed or changed is referenced by any .rst file. The system_vitis_unified_hls.mk mentioned in docs/how-to/vitis_hls.rst is a separate, untouched backend.
  • Not-in-scope gap: the new system_vitis_unified_hlsBs.mk backend is not covered in the Sphinx docs/ how-to / makefile reference — consistent with the whole hlsBs subsystem being absent from the Sphinx tree today. Can be added as follow-up if desired.

Test plan

CI (.github/workflows/ruckus_ci.yml) runs and passes locally on the branch:

  • flake8 --count scripts/ vitis/hlsBs/vitispy/ — clean
  • python -m compileall -f scripts/ vitis/hlsBs/vitispy/ — clean
  • trailing-whitespace/tab check over {tcl,py,sh} — clean

ruck314 added 3 commits July 11, 2026 18:46
@ruck314
fix(hlsBs): correct engine run, cosim, config, and IP bugs
2673878 
- fix multi-stage run and latent command bugs in the run/targets engine
- emit rel_path #defines bare so cosim can #include them
- repair IP family augmentation and propagate the run exit status
- emit the clock_uncertainty cfg key instead of the ignored 'uncertainity'
- return status from hlsWs --status so it can be used as a probe
- remove the stale IP zip before rezip to avoid a corrupt archive on rebuild
- realpath both operands in make_relative so symlinked repo paths resolve
@ruck314
feat(hlsBs): add system_vitis_unified_hlsBs.mk make wrapper for singl…
8eee3b3 
…e-target builds

Provide a `make` front-end over the reusable hlsBs engine (vitis/hlsBs),
steered by a single per-target project descriptor
(firmware/targets/<Name>/project/<Name>.py). This mirrors the
Vitis-Unified-CLI flow (system_vitis_unified_hls.mk) so a target can be built
with plain `make` instead of the hlsWs/hlsCfg/hlsRun command sequence.

clean removes build/ (Vitis workspace + generated cfg) and the target .Xil
scratch dir while preserving the packaged IP in ip/.
@ruck314
docs(hlsBs): fix README/man typos, FPGA family list, and HLSBS_INI en…
5ef3272 
…v var name

- fix grammar and typos across README.md and the man1/ pages
- correct the FPGA family list typos and the HLSBS_INI env var name
- correct the documented logical symbol fpga_uncertainity -> fpga_uncertainty
  to match the name the engine actually generates (maps.py Fpgas table)
@ruck314 ruck314 changed the title hlsBs: Vitis unified HLS build engine fixes, flake8/CI cleanup, and docs hlsBs: engine bug fixes, system_vitis_unified_hlsBs.mk make backend, flake8/CI cleanup, and doc fixes Jul 12, 2026
ruck314 added 4 commits July 11, 2026 18:56
@ruck314
style(hlsBs): flake8-clean the vitispy engine under surf config
80b86a0 
Mechanical flake8 cleanup (whitespace, spacing, unused imports) of the
vitis/hlsBs/vitispy engine under the surf flake8 config. Also fixes several
undefined-name bugs surfaced by the linter.
@ruck314
ci(ruckus): lint the hlsBs vitispy engine
da497e3 
Run compileall + flake8 over vitis/hlsBs/vitispy in addition to scripts/.
@ruck314
fix(hlsBs): sys.path bootstrap before vitispy imports; correct engine…
c3c5814 
… typos and dead branch

- run the sys.path bootstrap before the vitispy imports in the CLI entry points
  so the package resolves regardless of invocation cwd
- correct engine typos and a dead-branch call surfaced during cleanup
@ruck314
docs(hlsBs): fix man-page roff markup, README code-block typos, and C…
2945f33 
…aveats heading

- fix man-page roff markup and README code-block typos
- use .SS for the Caveats heading in the hlsBs.1 man page
@ruck314
ruck314 requested review from russell-slac and scompa18 July 12, 2026 02:00
@ruck314
ruck314 marked this pull request as ready for review July 12, 2026 02:00
@ruck314 ruck314 changed the title hlsBs: engine bug fixes, system_vitis_unified_hlsBs.mk make backend, flake8/CI cleanup, and doc fixes hlsBs: engine bug fixes, new system_vitis_unified_hlsBs.mk make backend, vitispy flake8 cleanup, and doc fixes Jul 12, 2026
@ruck314
fix(hlsBs): emit file-path defines via generated header so csim and c…
f89ace5 
…osim agree

File-path defines (abs_file/rel_path) put the macro value on the command line
as a quoted or bare -D, which cannot satisfy both simulators: csim passes the
cflags through a shell (one round of quote removal) while cosim re-tokenizes
the same string verbatim (no quote removal), so no single quoted or bare form
survives both.

Route abs_file/rel_path defines through a generated header instead: write
'#define NAME "path"' into hlsBs_defs/<cfg>_<label><idx>_defs.h and append
'-include <basename> -I hlsBs_defs' to that source's cflags. Those tokens are
quote-free and reach both compilers identically, so the testbench keeps a
plain '#include MACRO' with no stringizing. The header is referenced by base
name and located through -I because Vitis compiles each source from a
per-component sub-directory and rewrites -I paths to absolute. string and flag
defines are unchanged (plain -D). The header is keyed on the configuration
name so seed/define sweeps that share one testbench each get their own header.

Also document the mechanism and the standing no-whitespace-in-paths constraint
in the hlsBs README and the hlsBs.1 man page.
@russell-slac

russell-slac commented Jul 13, 2026

Copy link
Copy Markdown

The issue with compile-time includes is an issue, but that looks like there is a viable solution on the horizon

There is verbiage in hlsBs about the #include and #defines which I don't think belongs in there

  • The manpages are about the commands. This verbiage is about one particular aspect of the project file, not the commands
  • The project file has (or is close to having) its own sphinx documentation.
  • The project file is much bigger than just the compile time defines and includes

As a step to a real release, I think this is fine.

@russell-slac russell-slac reopened this Jul 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@russell-slac russell-slac Awaiting requested review from russell-slac
@scompa18 scompa18 Awaiting requested review from scompa18

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ruck314 @russell-slac