Stream In-Band Control (polynomial)

End-to-end Waveflow tutorial for a small polynomial accelerator — covering every stage from the Python golden model through RTL cosim timing verification. Every stage downstream of the Python source is derived and verified against the Python golden, which is the philosophy this example is meant to teach.

The five-group narrative arc

The full pipeline reads as five conceptually distinct groups, in examples/stream_inband/poly_build.py expressed as docstring markers in the DAG-construction function:

   Python golden model        →  build_inputs, py_sim, extract_py_timing
        │
        ▼
   HLS codegen                →  gen_include, gen_kernel, gen_tb
        │
        ▼
   C-sim functional verify    →  csim, validate_csim
        │
        ▼
   C-synth resource estimate  →  csynth, inspect_synth
        │
        ▼
   RTL cosim timing verify    →  extract_cosim_timing, validate_timing

Each group has its own dedicated page in this tutorial:

1. Python golden model — schemas + sim + Python-side cycle measurement.
2. HLS code generation — kernel + testbench C++ generated from the same Python sources.
3. C-sim functional verification — Vitis runs the generated kernel, outputs compared to the Python golden.
4. C-synth resource estimation — C-synthesis report, resource + II tables.
5. RTL cosim timing verification — measured RTL cycles vs PySim cycles, ±20 cycle tolerance.

A supplementary page covers AXI4-Stream timing analysis from VCD, useful once cosim has run with tracing enabled.

The polynomial accelerator protocol

• The host writes polynomial coefficients to the accelerator’s AXI-Lite register map (a VitisRegMap), then writes ap_start to launch the kernel.
• The host sends a PolyCmdHdr (cmd_type = DATA) carrying the transaction ID and sample count over the input AXI-Stream.
• The host streams nsamp input values (x).
• The accelerator returns a PolyRespHdr echoing the transaction ID, then streams nsamp result values (y).
• The host sends a PolyCmdHdr (cmd_type = END) to break the kernel’s persistent loop cleanly.
• On error the kernel halts: it sets halted = 1, error = <code>, tx_id = <offending txn> in the regmap and returns.

Files

File	What it holds
examples/stream_inband/poly.py	Schemas, PolyAccelComponent, PolyTB (SimPy), PolyTBHls (codegen-source)
examples/stream_inband/poly_build.py	Build DAG — the five groups above plus step definitions
examples/stream_inband/poly_evaluate_impl.tpp	Hand-written Horner evaluation hook (sticky impl)
examples/stream_inband/run.tcl	Vitis HLS TCL driver consumed by CSimStep / CSynthStep

gen/ (kernel + TB C++) and include/ (schema + utility headers) are generated artifacts — they are .gitignored and rebuilt by the DAG.

Running the full pipeline

python -m examples.stream_inband.poly_build --through validate_timing --force --live-output

The last step (validate_timing) emits results/timing_verdict.json with both measured cycle counts and a pass bit.

---

Next: Python golden model →

---

Table of contents

• Python Golden Model
• HLS Code Generation
• C-Sim Functional Verification
• C-Synth Resource Estimation
• RTL Cosim Timing Verification
• AXI4-Stream Timing Analysis