Add NanoXplore NG-ULTRA accelerator backend - #1510
Draft
nghielme wants to merge 15 commits into
Draft
Conversation
…earning#1448) Vendored here so this branch builds and tests on its own. This code is NOT part of this PR's contribution -- it is the content of open PR fastmachinelearning#1448 by the same author, on which the Bambu backend depends: * parse_vivado_report() split into per-report helpers; bambu_report.py reuses _parse_csim_results, _parse_rtl_cosim_results, _parse_implementation_report, _parse_timing_report, _parse_power_report * PATHS table and _path(), including the vivado_reports/post_route_*.rpt locations Bambu writes its own results into * statistics.tcl and the vivado_synth.tcl rewrite that produce them Review it in fastmachinelearning#1448, not here. When fastmachinelearning#1448 merges, rebasing drops this commit.
Firmware templates, build scripts and the nnet_utils header library used by the Bambu backend. Two submodules come with them: templates/bambu/ac_types ferrandi/ac_types, Bambu's fork templates/bambu/nnet_utils/gcem kthohr/gcem, constexpr math for tables ac_types diverges from the hlslibs/ac_types already vendored for Catapult, so it cannot be shared with that backend.
This was referenced Jul 23, 2026
nghielme
force-pushed
the
pr2-accelerator-layer
branch
2 times, most recently
from
July 24, 2026 00:20
bb86ddf to
cd42621
Compare
Proposed fix: Extend the generator with a Bambu-only file category (or add the file's nodeids
|
BambuBackend converts hls4ml models to HLS C++ and drives Bambu/PandA to synthesizable Verilog, for both io_parallel and io_stream. partname_to_bambu maps hls4ml part names onto Bambu device names. Not registered yet -- registration lands with the writer and report modules it depends on.
bambu_writer.py emits the HLS C++ project; bambu_report.py parses Bambu's XML results and reuses the Vivado report helpers for the post-route utilization, timing and power numbers.
Only the Bambu lines: the accelerator layer registers itself separately.
test_build_bambu.py drives csim, cosim, synth and vsynth on the default Xilinx part. The existing keras/activation/softmax/pooling suites gain 'Bambu' alongside the other backends. conftest.py grows --backend-filter / --backend-exclude / --ci-exclude-nodeid so a pipeline without the Bambu toolchain can deselect these cases; the CI wiring that uses them is a separate PR.
nghielme
force-pushed
the
pr2-accelerator-layer
branch
from
July 24, 2026 11:57
cd42621 to
317660b
Compare
Picks up six upstream commits on ferrandi/ac_types dev/panda-hls since 35e101a, mostly hls::stream/ac_channel work: DEPTH template parameter on the stream copy constructor and assignment operator (#3), peek support (#4), a gcc 15 / system C++ library fix (#5), improved hls::stream channel data type support (#6), a cosim regression fix (#7), and better set_slc/set_slc2 (#8).
Since ac_types became a git submodule the headers live under ac_types/include, not at the top level, so the USE_HLS4ML_AC_TYPES escape hatch was passing an include path with no headers in it.
AXI4-Lite slave for both IO flows, the top-level wrappers that instantiate the Bambu-generated core alongside it, and the supporting skid buffer, FIFO and address-increment modules.
BambuAcceleratorBackend turns a Bambu-generated HLS core into an integrable accelerator: float I/O wrapper, AXI slave instantiation, PLL configuration and a versioned manifest.json describing the artefact. The backend never imports a vendor tool. Everything a place-and-route flow needs -- RTL file list, clock, port map, data widths -- goes into manifest.json, and the concrete backend shells out to a single CLI. The one abstract method is _generate_bitstream, so this layer is fully testable without a vendor licence. pll_solver.py solves an NX_PLL_U configuration for a requested clock period so the hardware clock and the timing constraint agree by construction. It needs OR-Tools, an optional dependency. Abstract and unregistered; the concrete backend follows.
Concrete BambuAccelerator subclass: NG-ULTRA defaults (nx2h540tsc, 20 ns to match the DevKit's 50 MHz oscillator) and the place-and-route call, made through the CLI seam (hls4ml-nanoxplore-bitstream <project_dir>, overridable via BitStreamCommand) with report.json read back.
Adds the accelerator half of the registration files, on top of the Bambu half from the previous PR. BambuAcceleratorBackend stays unregistered -- it is abstract. The pll extra ships as optional-dependencies.nanoxplore (OR-Tools).
Builds both IO flows with bitstream=False, so the tests need Bambu but no vendor place-and-route tool, and assert on the manifest contract, the RTL file list, and the generated top-level localparams. The model shapes are deliberately not powers of two. Bambu rounds each BRAM address port up to the next power of two, so the element count and the BRAM depth differ -- which matters because HLS_*_N_WORDS means the depth on io_parallel and the element count on io_stream. With power-of-two shapes the two coincide and the assertions pass under either convention, so a dedicated test guards the shapes themselves.
nghielme
force-pushed
the
pr2-accelerator-layer
branch
from
July 28, 2026 11:33
317660b to
f2fe150
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds an accelerator layer on top of the Bambu backend that wraps a synthesized model in
AXI4 RTL and targets the NanoXplore NG-ULTRA FPGA.
Stacked on #1509 (the Bambu backend PR) — review/merge that first. This
PR is opened against
mainbecause its true base branch lives in the fork; until theBambu backend PR merges, the diff here includes its commits. It will shrink automatically
once that PR lands, at which point this can be retargeted.
Design — public/private seam. Bitstream generation needs NanoXplore's proprietary
nxpythontoolchain, which can't live in hls4ml. The boundary is a manifest + CLIcontract:
BambuAcceleratorBackend(abstract) writesmanifest.jsondescribing the builtproject (clock period, IO flow, RTL/mem files, port geometry, device).
NanoXploreAcceleratorBackend(concrete, registered) shells out tohls4ml-nanoxplore-bitstream <project_dir>, a separately-distributed driver that readsthe manifest and runs nxpython. hls4ml ships no vendor internals; everything up to
RTL + manifest works from hls4ml alone (
model.build()with the defaultbitstream=False).Contents:
hls4ml/backends/bambu_accelerator/— abstract accelerator layer + PLL solver + wrapperhls4ml/backends/nanoxplore_accelerator/— NG-ULTRA concrete backendhls4ml/templates/bambu_accelerator/rtl/— AXI4 slave + top-level templatespyproject.toml—hls4ml[nanoxplore]extra (ortools, for the PLL solver)docs/backend/nanoxplore.rstStack & dependencies
Part of a three-PR stack, review in order:
Builds on #1509; the whole stack depends on #1448 merging first (vendored in #1509's
first commit, dropped on rebase once #1448 lands).
Type of change
Tests
test/pytest/test_build_bambu_accelerator.pycovers the accelerator layer end to end(RTL + manifest emission; the vendor bitstream step is off by default so the test runs
without nxpython).
Test Configuration: same Bambu image as the backend PR.
CI note
GitHub PR checks here cover pre-commit, the docs build, and the packaging step. The
pytest suite runs on hls4ml's self-hosted GitLab pipeline, triggered by a maintainer
with the
please testlabel. The accelerator test needs the private Bambu image, soit is gated off on upstream runners — its result comes from running that suite in the
Bambu CI image locally, not from upstream CI.
Acknowledgements
The Bambu backend grew out of a collaboration with Politecnico di Milano, developed over 30 merged PRs on the
bambu-backendbranch of this fork.Thanks to Prof. Fabrizio Ferrandi (
@fabrizioferrandi), who supervised the effort and contributed thennet_utilsfoundation for Bambu, a redesign of thehls::streamclass, softplus support, and numerical fixes to the activation helpers (exp_fcn_floatoverflow,iv_baseinitialisation,ac_int).And to the students who worked on it:
@brios-polimi) — theBambuBackend.build()flow, refactored over several rounds into the Vitis-like interface this PR ships, plus thebuild_bambu.shrewrite.@tommasopau) — compile-time activation LUTs (tanh, legacy softmax), softmax bug fixes and the Bambu cases intest_softmax.py, and initialisation fixes innnet_conv1d_resource.h.@danielecursano) — theac_channelconstructor fix, compile-time SELU/ELU tables, and the fixes that got Bambu C-simulation running end to end.@frabazz) — adapted the unrolled Dense codegen to Bambu and enabledtest_resource_unrolled_dense, added Bambu totest_dense, and raisedbuild_lib.shto C++14.@etabeta1) — dropped the vendoredap_typescopy in favour of the headers Bambu ships, and enabled cosimulation in the pooling tests.@pietrobenecchi) — agcem-based compile-time softsign.@Gab-San) — carried the pytest 9 fixture rework (Remove parametrized fixtures from pytests for pytest 9 compatability #1417) through the Bambu tests.@FilippoGarofalo) — a string bug fix intest_pooling.py.Checklist
pre-commiton the files I edited or added.