Register Map Interface for a Simple Function

This is the first end-to-end example in the interface guide. It walks through one Waveflow kernel from the Python specification all the way to RTL co-simulation, using the simplest of the AXI-* interfaces — an AXI-Lite register map.

In going through this example, you will learn to:

  • Declare a VitisRegMap of typed registers and wire it into an HwComponent.
  • Write the kernel’s behavior as a Python method that reads the input registers, computes a result, and writes it back to the output register.
  • Run a Python simulation in which a separate HwTestbench plays the role of the host: it writes x, a, b, asserts ap_start, polls status until done, and reads y.
  • Generate the corresponding Vitis HLS C++ from the Python source — both the kernel and the testbench.
  • Run the Vitis C-simulation and RTL co-simulation flow against the generated artifacts.
  • Compare measured RTL cycle timing against the Python model’s cycle estimate.

Scalar function example

We illustrate the register map with a simple kernel that computes a clipped affine function:

y = max(0, a * x + b)

for signed 32-bit integers a, b, and x. You would not normally build hardware for a function this small, but it isolates exactly one concept — the AXI-Lite register map — without any of the streaming or memory-mapped complexity that a real accelerator brings in.

The kernel has three input registers (x, a, b) and one output register (y), plus the standard Vitis control plane that wraps any AXI-Lite kernel. A host driver running on the CPU performs the following sequence to exercise it:

  1. Write the three inputs to their register offsets.
  2. Write 1 to a specialized register, ap_start, to launch the kernel.
  3. Poll a status (or wait for an interrupt on ap_done) until the kernel signals it is finished.
  4. Read y from its register offset.

The Python simulation in pysim.md implements exactly this sequence in SimPy.

File map

The Python source, build script, and Vitis driver all live in examples/regmap/:

  • simp_fun.py — the HwComponent kernel, its VitisRegMap, and a SimPy host-side testbench.
  • simp_fun_build.py — the build DAG: golden Python sim → HLS codegen → Vitis C-sim → C-synth → cosim timing.
  • simp_fun_compute_impl.cpp — the sticky hand-written body of the kernel’s compute hook (the rest of the C++ is generated).
  • timing_diagram.py — generates a register-trace plot from the co-sim VCD for the synthesis page.
  • run.tcl — Vitis HLS driver script invoked by the build DAG.

End-to-end stages

The build DAG in simp_fun_build.py chains the standard five-stage pipeline introduced by the stream_inband example:

  • Python golden model — run the kernel in SimPy and record y plus a cycle-accurate timing log.
  • HLS code generation — emit the Vitis HLS kernel C++ and testbench C++ from the Python source.
  • Vitis C-sim functional verification — run the generated testbench against the generated kernel and compare its y against the Python golden.
  • Vitis C-synth and RTL co-sim timing extraction — synthesize the kernel, run RTL co-sim, and pull the measured cycle latency out of the cosim report.
  • Timing-diagram generation — turn the cosim VCD into a register-level trace plot that visually walks through the ap_start → status=busy → status=done handshake.

Next

Table of contents

This site uses Just the Docs, a documentation theme for Jekyll.