vrtbin Format

A vrtbin (.vbin) file is the deployment artefact in SLASH. It packages everything needed to program and interact with a V80 design into a single archive.

Overview

A vrtbin is a gzip-compressed tar archive produced by the SLASH linker (slashkit) via the add_vbin() CMake function. VRT extracts the archive at runtime when you construct a vrt::Device.

┌───────────────────────────────┐
│          .vbin file           │  gzip-compressed tar
├───────────────────────────────┤
│  system_map.xml              │  always present — design metadata
│  *.pdi                       │  hardware only — FPGA bitstream(s)
│  vpp_emu                     │  emulation only — C-model executable
│  emu_manifest.json           │  emulation only — argument routing
│  vpp_sim                     │  simulation only — simulator launcher
│  report_utilization.xml      │  optional — FPGA resource usage
└───────────────────────────────┘

Archive Contents

File	Present	Purpose
`system_map.xml`	Always	Design metadata: platform, clock frequency, kernel descriptions, register maps, memory connections, and streaming connections.
`*.pdi`	Hardware	FPGA bitstream file(s). If multiple PDI files exist, VRT prefers `design.pdi`.
`vpp_emu`	Emulation	Compiled C-model executable of the HLS kernels.
`emu_manifest.json`	Emulation	Maps kernel arguments to emulation call types (scalar, buffer) and routing for register read-back.
`vpp_sim`	Simulation	Verilog simulator wrapper executable.
`report_utilization.xml`	Optional	FPGA resource utilisation report (LUTs, FFs, BRAMs, URAMs, DSPs).

system_map.xml

The system_map.xml file is the most important entry in the archive. It drives VRT’s runtime behaviour — kernel discovery, argument routing, memory port mapping, and platform detection all come from this file.

Schema

<SystemMap>
  <Platform>Hardware</Platform>
  <ShellType>service</ShellType>
  <ClockFrequency>250000000</ClockFrequency>

  <ServiceLayer>
    <Ethernet enabled="true">
      <eth index="0" />
    </Ethernet>
    <VIRT>
      <interface index="0" connection="eth0" />
    </VIRT>
  </ServiceLayer>

  <Kernel>
    <Name>increment_0</Name>
    <BaseAddress>0x20100000000</BaseAddress>
    <Range>0x1000</Range>

    <register offset="0x00" name="CTRL" access="RW"
              description="Control register" range="32" />
    <register offset="0x10" name="size" access="W"
              description="Number of elements" range="32" />

    <functional_args>
      <arg idx="0" name="size" type="scalar"
           offset="0x10" range="32" r="0" w="1" />
      <arg idx="1" name="in" type="buffer"
           offset="0x18" range="64" r="1" w="1"
           port="m_axi_gmem0" />
    </functional_args>

    <connection port="m_axi_gmem0" target="HBM1" />
  </Kernel>
</SystemMap>

Key elements:

<Platform>: One of Hardware, Emulation, or Simulation. VRT maps this to the vrt::Platform enum and selects the appropriate back-end.
<ShellType>: Hardware shell required by the design. Hardware vbins use service or compute. VRT passes this to vrtd before programming so the daemon can reset the board to the matching boot partition when needed. Legacy vbins without this element are treated as service.
<ClockFrequency>: Kernel clock frequency in Hz (e.g. 250000000 for 250 MHz).
<Kernel>: One block per kernel instance. Contains the instance name, base address, register definitions, functional argument metadata, and memory port connections.
<functional_args>: Each <arg> describes a kernel argument: index, name, type (scalar or buffer), register offset, range in bits, read/write flags, and the associated AXI port name (for buffer arguments).
<connection>: Maps an AXI memory-mapped port to a physical memory target (e.g. HBM1, DDR0). VRT uses this to determine the correct MemoryConfig for buffer allocation.

How VRT Uses the Vrtbin

When you construct vrt::Device(bdf, vrtbinPath):

Extract — Vrtbin::extract() decompresses the gzip archive into a temporary cache directory.
Discover — VRT locates system_map.xml, PDI files, and emulation/simulation executables within the extracted tree.
Parse — the XML parser reads system_map.xml to build kernel objects with register maps, argument metadata, and memory configurations.
Select platform — the <Platform> value determines whether VRT uses PCIe BAR access (hardware), ZeroMQ to vpp_emu (emulation), or ZeroMQ to vpp_sim (simulation).
Program — on hardware, VRT programs the FPGA with the PDI bitstream(s) via the vrtd daemon. On emulation/simulation, it launches the model executable in a background thread.

Graph API and RP1

The VRT graph FPGA backend also consumes vbin metadata. It does not require a new manifest file: kernel shape is derived from system_map.xml and hardware PDI files are discovered with the same vrt::Vrtbin logic used by vrt::Device.

For RP1 graph execution, each hardware vbin is currently treated as an exclusive user-region image. The graph-facing image spec maps every <Kernel> entry to:

a graph KernelDescriptor / IOTypeMap built from functional_args;
the host-view base address from <BaseAddress>;

the RP1/R5-visible AXI-Lite base address:

r5_addr = 0x88000000 + (system_map_base - 0x020200000000)

Graph authors explicitly request image swaps with a reprogram node. In the RP1 backend this lowers to RP1_OP_PDI_LOAD using the selected vbin’s PDI bytes staged into RP1-visible DDR. No partial-region coexistence metadata is modeled yet; at most one vbin image is active per FPGA device.

See Graph API Architecture for how this image metadata fits into Graph compilation, device plans, and FPGA control-flow lowering.

Inspecting a Vrtbin

Use v80-smi inspect to display a vrtbin’s metadata without programming a device:

v80-smi inspect my_design.vbin

This prints the platform, clock frequency, kernel names, argument lists, and memory connections parsed from system_map.xml.

You can also examine the raw archive contents:

tar tzf my_design.vbin

See Command Reference for the full inspect command reference.

Creating a Vrtbin

Vrtbin archives are produced by the SLASH linker (slashkit) through the CMake add_vbin() function:

add_vbin(TARGET "my_design_hw" PLATFORM "hw" CFG "config.cfg" KERNELS ${_KERNELS})

The linker reads compiled HLS kernel IP (component.xml files) and a connectivity configuration (config.cfg) to produce the archive. One target is created per platform (hw, emu, sim).

See SlashTools for the full add_vbin() reference and Your First Kernel for a worked example.