shinei-nouzen-arch/fpga-agent/vitis-hls-synthesis

Vitis HLS Synthesis Development Assistant

This skill helps you efficiently perform FPGA high-level synthesis development in the Vitis HLS environment. For complete syntax reference, see REFERENCE.md.

When to Use This Skill

• Need to write or optimize C/C++ HLS kernel code
• Need to add pragma optimization instructions (pipeline, unroll, dataflow, array_partition, etc.)
• Need to configure synthesis constraint files (.cfg)
• Need to run Vitis HLS synthesis commands
• Need to analyze synthesis reports (timing, resource, II value)
• Need to configure interface protocols (AXI4-Stream, M_AXI, s_axilite, etc.)
• Need to select appropriate data types (arbitrary precision types, HLS-specific types)
• Need to optimize DDR access and HBM bandwidth

Workflow

Select only the stages needed for the requested outcome and reuse the existing project and results. Report interpretation does not require project initialization or a new build. Code or configuration changes include proportionate validation; an execution request includes the requested run stages and result checks. Generate or review scripts without executing them when that is the requested deliverable. Existing authorization covers necessary in-scope follow-up, but does not automatically extend the task to packaging, implementation, or hardware programming.

1. Project Initialization

When initialization is needed, determine the project structure and target device from existing sources, configuration, and prior user instructions. Reuse established settings and create only missing directories. Ask only for consequential information that is unavailable; never guess a device or clock required for a run. A generic example can retain clearly marked parameters without blocking on device selection.

mkdir -p <project>/src <project>/tb

2. Code Development

Write HLS kernel code, add pragma optimization instructions as needed, select appropriate data types and interface protocols.

3. Configuration File

Create or update the relevant .cfg file, preserving established device, clock, interface, and flow settings unless changing them is part of the request.

4. Run Flow

For execution requests, run the applicable stages and their prerequisites:

1. C simulation to verify functional correctness
2. C synthesis to generate RTL
3. C/RTL co-simulation to verify hardware functionality
4. Export IP or Vitis kernel when packaging is part of the requested deliverable

5. Report Analysis

Check the status, relevant logs, and outputs of each requested stage. Use simulation results to assess tested functionality and HLS synthesis estimates to assess clock performance, II, latency, and resources against the stated requirements. HLS estimates are not post-route timing signoff; apply the Vivado timing acceptance criteria only when implementation is in scope. Report what was verified, what remains unverified, and the requested artifact locations. Continue necessary authorized work rather than treating report generation or a partial run as completion.

Quick Reference

Core Commands

Common Pragmas

Core Configuration Parameters

For complete syntax and parameter reference, see REFERENCE.md. Reference implementation examples are available in the examples/ directory - read these files first when users need coding patterns or best practices.

Common Scenario Examples

1. Pipeline Optimization Kernel

Add pipeline optimization to loops to achieve II=1:

void kernel(float A[32][32], float B[32][32], float C[32][32]) {
    #pragma HLS INTERFACE m_axi port=A bundle=gmem
    #pragma HLS INTERFACE m_axi port=B bundle=gmem
    #pragma HLS INTERFACE m_axi port=C bundle=gmem
 
    for (int i = 0; i < 32; i++) {
        for (int j = 0; j < 32; j++) {
            #pragma HLS PIPELINE II=1
            float sum = 0;
            for (int k = 0; k < 32; k++) {
                sum += A[i][k] * B[k][j];
            }
            C[i][j] = sum;
        }
    }
}

2. Array Partition Optimization

Partition arrays to improve parallel access:

#pragma HLS ARRAY_PARTITION variable=input_data type=cyclic factor=4 dim=1
#pragma HLS ARRAY_PARTITION variable=weights type=complete dim=1

3. Dataflow Task Parallelism

Implement multi-stage task parallelism:

void top(hls::stream<int> &in, hls::stream<int> &out) {
    #pragma HLS DATAFLOW
    hls::stream<int> fifo1, fifo2;
    #pragma HLS STREAM variable=fifo1 depth=16
    #pragma HLS STREAM variable=fifo2 depth=16
 
    read_image(in, fifo1);
    process_image(fifo1, fifo2);
    write_image(fifo2, out);
}

4. AXI4-Stream Interface

Implement AXI4-Stream input and output:

#include "hls_stream.h"
 
void axis_process(hls::stream<ap_int<32>> &in, hls::stream<ap_int<32>> &out) {
    #pragma HLS INTERFACE axis port=in
    #pragma HLS INTERFACE axis port=out
    #pragma HLS PIPELINE II=1
 
    ap_int<32> data = in.read();
    // Data processing
    out.write(data);
}

5. Fixed-Point Conversion

Convert floating-point to fixed-point for performance optimization:

#include "ap_fixed.h"
// ap_fixed<total_width, integer_bits, quantization_mode, overflow_mode>
typedef ap_fixed<16, 8, AP_RND, AP_SAT> fixed_t;
fixed_t value = 1.5f; // Automatic quantization

Related Skills

Post-Synthesis Flow

• vivado-impl: Place and route optimization for HLS-generated IP
• vivado-analysis: Timing report analysis and closure strategies
• vivado-constraints: Add top-level timing and physical constraints

Simulation and Debug

• vivado-sim: RTL functional and timing simulation
• vivado-debug: ILA/VIO hardware debug configuration

Automation

• vivado-tcl: HLS IP integration and project automation scripts