Best Practices - Best Practices - 2026.1 English - UG1864

1. Use axis only when your kernel requires it. If your HLS kernel uses plain hls::stream<int> (no sideband signals), you do not need to attach an axis configuration. VFS handles plain streams transparently.

2. Match axis configuration to the HLS interface. If your kernel uses ap_axis<32, 0, 0, 0> or hls::axis<ap_uint<32>>, use a default axis configuration. If the kernel has nonzero user/id/dest widths, set the corresponding parameters:

# Python
cfg = va.axis(w_user=8, w_id=4, w_dest=4)

% MATLAB
cfg = varray.axis(w_user=8, w_id=4, w_dest=4);

3. Set tlast on the final element of each logical packet. Many AXI4-Stream consumers rely on tlast for framing. If your kernel expects packet-delimited data, mark the boundaries:

# Python
arr.tlast[-1] = 1

% MATLAB
arr.tlast(N) = 1;

4. Leave tkeep and tstrb at defaults unless needed. The defaults (all bytes valid) are correct for the vast majority of use cases. Only modify them if your design explicitly uses null bytes or partial transfers.

5. Use slicing to work with packet sub-ranges. Slicing preserves the axis configuration and produces a copy of the sideband arrays for the selected elements. In Python, slices are views (changes propagate to the parent). In MATLAB, slices are independent copies.

6. A single axis config can be shared across arrays in MATLAB. In MATLAB, a single varray.axis config can be reused across multiple arrays. Each array gets its own sideband storage automatically:

cfg = varray.axis(w_user=8);
a_fi  = varray.fi([1, 2, 3], 1, 16, 0, axis=cfg);
a_flt = varray.float([10, 20, 30], axis=cfg);

7. Use set_axis() to fix axis config mismatches. When VFS reports an axis mismatch error at runtime, use set_axis() to correct the configuration in place rather than recreating the array:

# Python — error says: expected axis(enable_tkeep=False, enable_tstrb=False)
arr.set_axis(va.axis(enable_tkeep=False, enable_tstrb=False))

% MATLAB — same fix
arr.set_axis(varray.axis(enable_tkeep=false, enable_tstrb=false));

The validation error messages include a suggested set_axis() call you can use to fix the mismatch.