Overview
Using this Guide
Chapter 1: Introduction to VFS
What is VFS?
Why use VFS?
Architecture Overview
Next Steps
Chapter 2: Installation and Environment Setup
Enabling Editor Autocomplete and Docstrings for VFS
Problem
Prerequisites
Solution
Step 1: Source the Vitis environment
Step 2: Create the vfs.pth file
Step 3: Restart your editor
Removing
Troubleshooting
VFS Standalone Installation
Overview
Benefits
Prerequisites
Creating a Standalone Installation
Step 1: Set Up the Environment
Step 2: Run the Script
What the Script Does
Using the Standalone Installation
Output Contents
Portability
Troubleshooting
XILINX_VITIS Not Set
Missing Component Warnings
Supported Python and MATLAB Versions
Related Information
Chapter 3: Quick Start / Hello VFS
Prerequisites
Hello HLS Kernel
Python
MATLAB
C++
Hello AIE Graph
Python
MATLAB
C++
Next Steps
Chapter 4: varray Data Model
Supported Data Types at a Glance
AXI4-Stream Sidebands for varray
When to use axis
AIE PLIO Stream Inputs
axis_config
Common Settings
Beats and Multi-element Beats
One Element per Beat (Default)
Multi-element Beats
Converting the AXI4-Stream Width in Python
Converting the AXI4-Stream Width in MATLAB
Reading the Display
Python Basics
Create the Array
Set and Read the Default Sidebands
Enable TUSER
MATLAB Basics
Create the Array
Set and Read the Default Sidebands
Enable TUSER
Default Fields
Add or Remove Sidebands
Strip Sidebands
Add Sidebands to a Plain Array
Replace an Existing Configuration
Slicing at Beat Boundaries
One Element per Beat
Multi-element Beats
Slicing Sidebands by Beat
Matching the Port
Related Information
C++ varray
Setup and Include
Supported Data Types
Integer
Floating Point
Complex
Fixed-point (fi, cfi)
HLS arbitrary-precision floating point (ap_float, ap_cfloat)
Microscaling (mx4, mx6, mx9)
Creating Containers
Type Properties
Operations
Indexing and Iteration
Arithmetic and Math (Standard Aliases and Quantized Types)
Reshaping and Grouping
Serialization
Fixed-Point, Microscaling, and Half Types
Fixed-point Quantization
Fixed Point Formatting (hex, bin, dec2hex, dec2bin)
Microscaling Blocks
HLS half and float16
Troubleshooting
API Reference
Scalar Types
Helpers
fi Compile-time Constants
Related Information
MATLAB varray
Setup and Version Check
Supported Data Types
Integer
Floating Point
Complex
Fixed Point (fi, cfi)
HLS Arbitrary Precision Floating Point (ap_float, ap_cfloat)
Computing Byte Width
Microscaling (mx4, mx6, mx9)
Creating Arrays
Array Properties
Type-specific Properties
Array Operations
Indexing, Assignment, Deletion, and Slicing
Reshape, Concatenate, Transpose
Arithmetic and Math Operations (Not Supported)
Comparisons
MATLAB Interoperability
Casting to Native MATLAB Types
Casting between varray Types
MATLAB Functions that Work on varray Directly
Fixed-Point, Microscaling, and Half Types
Fixed-point Quantization
Microscaling Blocks
HLS half vs. float16
Troubleshooting
API Reference
Constructors
Properties Common to All Types
Methods common to all types
AXI4-Stream Sideband Helpers
Type-Specific Properties and Methods
Helpers
Version
Related Information
Python varray
Setup and Import
Supported Data Types
Integer
Floating Point
Complex
Fixed Point (fi, cfi)
HLS Arbitrary Precision Floating Point (ap_float, ap_cfloat)
Computing Byte Width
Microscaling (mx4, mx6, mx9)
Creating Arrays
From lists or tuples: dtype is required
From a NumPy array: dtype is optional
From a Scalar
Array Properties
Array Operations
Indexing, Assignment, Deletion, and Slicing
Reshape
Arithmetic and Math Operations (Not Supported)
astype(): Convert between Types
view(): Reinterpret the Bytes
NumPy Interoperability
Converting to NumPy
Supported NumPy functions
Comparison Operations
Complex Arrays
Fixed Point, Microscaling, and Half Types
Fixed Point Quantization
Inspecting the Stored Integer: hex() / bin()
va.dec2hex(D, minDigits=0)
va.dec2bin(D, minDigits=0)
Microscaling Blocks
HLS half vs. float16
Troubleshooting
API Reference
varray.array
Type factories
Helpers
Related Information
Chapter 5: Simulating HLS Kernels and AIE Graphs
Which Language Should I Choose?
AIE Packet Switching
Frame Boundaries (tlast)
Labeled Packets
Compiler-Assigned Packet IDs
Identifying Stream Ports
varray.aiePacketUtils Reference
pack_packets
unpack_packets
generate_packet_header
get_packet_id
Related Information
C++ API
Setup and Compilation
Component Lifecycle
vfs::hlsKernel
Constructor
What vfs_build_dir Must Ccntain
Running
Pointer Arguments
Zero-input Kernels (setNumKernelRuns)
Inspecting Ports
vfs::aieGraph
Constructor
What vfs_build_dir must contain
Running
Graph Iterations (setNumIterations)
Port Dump
HDL IPs
Combined AIE and HLS Workflows
API Reference
vfs::hlsKernel
vfs::aieGraph
vfs::DRCException
Troubleshooting
Related Information
MATLAB API
Setup
Execution Modes: release and debug
Component Lifecycle
vfs.hlsKernel
Constructor
What vfs_build_dir must contain
Examples
Running
Pointer Arguments
Output Shape
Inspecting Ports
Zero-input Kernels (setNumKernelRuns)
vfs.aieGraph
Constructor
What vfs_build_dir must contain
Examples
Running
Output AXIS Side Channels
Graph Iterations (setNumIterations)
Port Dump
HDL IPs
Combined AIE and HLS Workflows
Utility Functions
API Reference
vfs.hlsKernel
vfs.aieGraph
Troubleshooting
Related Information
Python API
Setup
Component Lifecycle
vfs.hlsKernel
Constructor
What vfs_build_dir must contain
Examples
Running
Pointer Arguments
Output Shape
Inspecting Ports
Zero Input Kernels (setNumKernelRuns)
vfs.aieGraph
Constructor
What vfs_build_dir must contain
Examples
Running
Output AXIS Side Channels
Graph Iterations (setNumIterations)
Port Dump
graph.setPortDump() # default directory
graph.setPortDump("my_dump_dir") # custom directory
graph.run(din)
graph.writePortDump() # flush to disk
HDL IPs
Combined AIE and HLS Workflows
API Reference
vfs.hlsKernel
vfs.aieGraph
vfs.readDumpFile.read_dump_file(path)
shape= Values
Troubleshooting
Related Information
Chapter 6: Component Interfaces and Behavior
AIE Stream and Buffer Interfaces
Interface Types
Stream Interface
Buffer / Window Interface
Data Processing Behavior
Stream-Based Kernels
Buffer / Window-Based Kernels
Output AXIS Side Channels on PLIO Ports
When to use each interface
Mixed Inputs: Synchronous and Asynchronous Parameters
Case 1: Synchronous Parameter
Case 2: Asynchronous Parameter
Summary of Cases 1 and 2
Summary
Related Information
HLS Stream and Buffer Interfaces
Interface Types
Stream Interface
Buffer / Array Interface
Data Processing Behavior
Stream-based Kernels
Buffer / Array-based Kernels
Pointer Arguments
How VFS Sizes a Pointer Port
Running a Pointer Kernel
Mixed Interface Types (Stream and Scalar)
When to use each interface
Summary
Related pages
Chapter 7: HDL IP
Examples
FFT Family
Channelizer
Data Converters
Filters
Error Correction Decoders
Resamplers
FIR Compiler (firCompiler) Guide
Overview
Setup
Concepts
Configuration Lifecycle
Filter Types
Data and Coefficient Types
Fixed-Point Format
Data Layout
Advanced Channel Patterns (TDM)
Coefficient Reload
Persistent State
Data Types: varray In, varray Out
Python API
Import
Config
Pattern
Mode Selectors
ConfigPacket and ReloadPacket
Constructor
Filtering with an Array
Filtering Complex Data
Filtering with a Dict (Per-Channel)
Building Inputs with a Loop:
Stream Inspection
Other Methods
Python Examples
Default Filter
Custom Coefficients with Quantization
Multi-Channel Filter
Multi-Path Filter (I/Q)
Multi-Path, Multi-Channel
Advanced Channel Pattern (P4_3) with Dict
Reloadable Filter
Persistent State
MATLAB API
Import
Config
Pattern
Mode Selectors
ConfigPacket and ReloadPacket
Constructor
Filtering with an Array
Filtering Complex Data
Filtering with a Struct (Per-Channel)
Stream Inspection
Other Methods
MATLAB Examples
Default Filter
Custom Coefficients with Quantization
Multi-Channel Filter
Multi-Path Filter (I/Q)
Advanced Channel Pattern (P4_3) with Struct
Reloadable Filter
Persistent State
Best Practices
Troubleshooting
Related Information
Poly Block Arbitrary Resampler (pbArbResampler) Guide
Overview
Setup
Concepts
Configuration Lifecycle
Data Types: varray In, varray Out
Resampling Ratio
Python API
Import
Config
Control
Constructor
run()
Other Methods
MATLAB API
Namespace
Config
Control
Constructor
run()
Other Methods
Configuration
Stream input and output
Status
Runtime phase updates
Python
MATLAB
Reset
Troubleshooting
Limitations
Related Information
Poly Block Channelizer (pbChannelizer) Guide
Overview
Setup
Concepts
Configuration Lifecycle
Data Types: varray In, varray Out
Operating Modes
Python API
Import
Config
Control
Constructor
run()
Other Methods
MATLAB API
Namespace
Config
Control
Constructor
run()
Other Methods
Configuration
Processing and sample flow
Coefficients
Numeric and Output Behavior
Transform and Frame Checks
Data and Control
Inverse Example (Python)
Inverse Example (MATLAB)
MCF Example (Python)
MCF Example (MATLAB)
Frame and State behavior
Coefficient Files and Runtime Updates
Load a Coefficient CSV with Python
Load a Coefficient CSV with MATLAB
Status and Recovery
Troubleshooting
Limitations
Related Information
Versal LDPC Decoder (versalLDPC) Guide
Overview
Setup
Quick Start
Python
MATLAB
Concepts
Configuration Lifecycle
Preparing the LLR Input
Reading the Result
Diagnostics and Warnings
Data Types: varray In, varray Out
Python API
Import
Config
Control
Constructor
run()
Other Methods
Static Utilities
Python Examples
Returning Soft Output with and without Parity in Python
Decoding a Custom Code in Python
Decoding a Built-in 5G Code in Python
Decoding a Reordered DVB-S2 Codeword in Python
MATLAB API
Namespace
Config
Control
Constructor
run()
Other Methods
Static Utilities
MATLAB Examples
Returning Soft Output with and without Parity in MATLAB
Decoding a Custom Code in MATLAB
Decoding a Built-in 5G Code in MATLAB
Decoding a Reordered DVB-S2 Codeword in MATLAB
Reference
Configure Decoding
Config Reference
Control Reference
Advanced Source Selection and Overrides
Status Reference
Selecting a Built-in Non-5G Code
Preparing Data for Each Standard
Preparing a 5G NR Codeword
Preparing a DVB-S2/S2X Codeword
Custom LDPC Code Files
Selecting Custom Codes with Slots
Writing a Custom YAML Definition
Generating a Custom Code File
Matrix Requirements
Destination Behavior
Generated File Behavior
Checking Custom Code Limits
Checking the Decoder Limits
Rejected Inputs and Configurations
Python Exceptions and Warnings
MATLAB Errors and Warnings
Practical Caveats
Best Practices
Troubleshooting
run() says the input length is wrong
A custom-code file cannot be found
A custom YAML file cannot be read
One decode output is empty
A modifier value is rejected
run() reports an LLR warning
A built-in code identifier is not recognized
A 5G code selection is rejected
status.parity_pass remains false
A custom code is unavailable after resetting or reconfiguring
Related Information
Versal RF Channelizer (vrfChannelizer) Guide
Overview
What is Channelization?
Setup
Concepts
Configuration Lifecycle
Operating Modes
Mode Selection Guidelines
Data Structures
Config
Control
OverflowStatus
Mode Reference Quick Table
Performance Notes
Data Types: varray In, varray Out
Python API
Import
Config
Control
Interface Introspection
Constructor
run()
Other Methods
Python Examples
Basic RX Channelizer (Mode 0)
Filter-Only Mode (Mode 2)
Common Workflows (Python)
1. Digital Down Converter (DDC) RX Channelizer
2. Digital Up Converter (DUC) TX Channelizer
3. Multi-Channel Filtering
4. High-Throughput Processing (SSR Modes)
MATLAB API
Import
Config
Control
Interface Introspection
Constructor
run()
Other Methods
MATLAB Examples
RX Channelizer with Real Coefficients
Oversampled TX Channelizer (Mode 4)
Common Workflows (MATLAB)
1. Digital Down Converter (DDC) RX Channelizer
2. Digital Up Converter (DUC) TX Channelizer
3. Multi-Channel Filtering
4. High-Throughput Processing (SSR Modes)
Best Practices
Fixed-Point Considerations
Performance Optimization
Debugging Tips
Troubleshooting
Common Issues
Dimension mismatch Errors
All Outputs Are Zero
Persistent Overflow Flags
Unexpected Output Values in Mode 4, 5, or 6
FIR Coefficient Shape Mismatch
Error Messages
Related Information
Versal RF Data Converter User Guide
Overview
Setup
Concepts
Channels and Bands
Configuration Lifecycle
Frequency Hopping Between Runs
Stateful Operation
Configuration Parameters
Data Types: varray In, varray Out
API Summary
vrfADC
Python API
Import
Data Structures
initializeArrays
getInputSpec / getOutputSpec
Python Example
Multi-Channel RF Sampling
MATLAB API
Data Structures
initializeArrays
getInputSpec / getOutputSpec
MATLAB Example
vrfDAC
Python API
Import
Data Structures
initializeArrays
getInputSpec / getOutputSpec
Python Example
Multi-Carrier Transmit
Loopback Simulation (DAC to ADC)
MATLAB API
Data Structures
initializeArrays
getInputSpec / getOutputSpec
MATLAB Example
Frequency Planning
Troubleshooting
ADC Issues
Empty Output Bands
Unexpected Output Array Size
DC Offset in Baseband Output
DAC Issues
Low Output Power
Spectral Images
Output Array Dimension Mismatch
General Issues
Error on run() about Non-varray Input
Inconsistent Results between Runs
Configuration Changes Not Taking Effect
Memory Usage Growing
Related Information
Versal RF FFT (vrfFFT) Guide
Overview
Setup
Concepts
Configuration Lifecycle
Config Parameters
Control Parameters
Operating Modes
Unscaled Mode (data_width_out=31)
Scaled Mode (data_width_out=16 or data_width_out=18)
Mode Summary Table
Output Index Order
When Is Each Order Available?
Comparing Against NumPy/MATLAB Reference
Scaling Factor
Internal Pipeline
Guidelines
Batch Processing (Data Larger than FFT Size)
Partial Frame Input (Streaming Mode)
Data Types: varray In, varray Out
Python API
Import
Config
Control
Constructor
run()
getInputSpec / getOutputSpec
Python Examples
Scaled Mode: Natural Order Output
Scaled Mode: Bit-Reversed Output
Unscaled Mode: Full Precision (31-bit)
Comparing Scaling Factors
Batch Processing (Multi-Frame)
Inverse FFT Round-Trip
MATLAB API
Namespace
Config
Control
Constructor
run()
getInputSpec / getOutputSpec
MATLAB Examples
Scaled Mode: Natural Order
Scaled Mode: Bit-Reversed Output
Unscaled Mode: Full Precision (31-bit)
Comparing Scaling Factors
Batch Processing (Multi-Frame)
Best Practices
Troubleshooting
Performance Considerations
Related Information
xFFT Guide
Overview
Setup
Concepts
Configuration Lifecycle
Config Parameters
Control Parameters
Scaling Schedule Guidelines
Batch Processing (Data Larger than FFT Size)
Partial Frame Input (Streaming Mode)
Architecture Selection Guide
Performance Trade-offs
Data Types: varray In, varray Out
Python API
Import
Config
Control
Constructor
getInputSpec / getOutputSpec
Python Examples
Basic Usage Flow
Spectral Analysis
Filtering in Frequency Domain
Convolution via FFT
Batch Processing
Partial Frame Input
MATLAB API
Namespace
Config
Control
Constructor
run() Method
getInputSpec / getOutputSpec
MATLAB Example
Batch Processing
Partial Frame Input
Best Practices
Troubleshooting
Related Information
Additional Resources and Legal Notices
Support Resources
Revision History
Please Read: Important Legal Notices
AUTOMOTIVE APPLICATIONS DISCLAIMER
Copyright