Resolving Vivado HLS Synthesis Warnings in HLS4ML Generated Code

[AbuAli3]

Issue Description

When synthesizing HLS4ML-generated code using hls4ml v1.1.0 and Vivado 2020.1, several synthesis warnings are generated, hindering both dataflow optimization and correct AXI interface handling.These warnings mostly stem from improper variable scoping within DATAFLOW regions and misplaced interface directives

Warnings Encountered

1. Dataflow Variable Declaration Warnings (HLS 214-113)

WARNING: [HLS 214-113] Either use an argument of the function or declare the variable inside the dataflow loop body

These warnings occurred for weight and bias variables (w2, b2, w5, b5, w8, b8) that were declared outside the dataflow region but used within it.

2. Dataflow Form Check Warnings (HLS 200-471)

WARNING: [HLS 200-471] Dataflow form checks found 10 issue(s) in file firmware/myproject.cpp
WARNING: [HLS 200-471] Dataflow form checks found 2 issue(s) in file firmware/myproject_axi.cpp

3. Interface Directive Warnings (XFORM 203-803)

WARNING: [XFORM 203-803] Cannot specify interface mode 'axis' on argument... This interface directive will be discarded.

4. Canonical Dataflow Region Warnings (HLS 214-114)

WARNING: [HLS 214-114] Since the only kind of statements allowed in a canonical dataflow region are variable declarations and function calls...

Solutions Applied

Solution 1: Restructure Weight and Bias Declaration in myproject.cpp

Problem: Although the weight arrays like w2 were statically declared and initialized in the weight header files (e.g., w2.h), using them directly within a DATAFLOW region led to Vivado HLS analysis warnings. This is because weight and bias arrays were declared as global variables but used inside a DATAFLOW region, which can interfere with Vivado’s scheduling and optimization

Original Code:

void myproject(hls::stream<input_t> &fc1_input, hls::stream<result_t> &layer8_out) {
    #pragma HLS INTERFACE axis port=fc1_input,layer8_out
    #pragma HLS DATAFLOW
    
    // Global weight declarations caused warnings
    #ifndef __SYNTHESIS__
    static bool loaded_weights = false;
    if (!loaded_weights) {
        nnet::load_weights_from_txt<weight2_t, 640>(w2, "w2.txt");
        // ... other weight loading
    }
    #endif
}

Fixed Code:

void myproject(hls::stream<input_t> &fc1_input, hls::stream<result_t> &layer8_out) {
    // Remove axis interface directives from non-top function
    #pragma HLS DATAFLOW

    // Declare weights and biases inside dataflow region
    weight2_t w2[640];
    bias2_t b2[32];
    weight5_t w5[512];
    bias5_t b5[16];
    weight8_t w8[16];
    bias8_t b8[1];

    // Load weights inside dataflow region
    #ifndef __SYNTHESIS__
        static bool loaded_weights = false;
        if (!loaded_weights) {
            nnet::load_weights_from_txt<weight2_t, 640>(w2, "w2.txt");
            nnet::load_weights_from_txt<bias2_t, 32>(b2, "b2.txt");
            nnet::load_weights_from_txt<weight5_t, 512>(w5, "w5.txt");
            nnet::load_weights_from_txt<bias5_t, 16>(b5, "b5.txt");
            nnet::load_weights_from_txt<weight8_t, 16>(w8, "w8.txt");
            nnet::load_weights_from_txt<bias8_t, 1>(b8, "b8.txt");
            loaded_weights = true;
        }
    #endif
    
    // NETWORK INSTANTIATION remain the same...
}

Solution 2: Restructure AXI Interface in myproject_axi.cpp

Problem: Array-based interface with embedded loops violated dataflow canonical form.

Original Code:

void myproject_axi(input_axi_t in[N_IN], output_axi_t out[N_OUT]) {
    #pragma HLS INTERFACE axis port=in
    #pragma HLS INTERFACE axis port=out
    #pragma HLS INTERFACE ap_ctrl_none port=return
    #pragma HLS DATAFLOW

    // Embedded loops in dataflow region caused warnings
    for(unsigned i = 0; i < N_IN / input_t::size; ++i) {
        // ... processing
    }
    
    myproject(in_local, out_local);
    
    for(unsigned i = 0; i < N_OUT / result_t::size; ++i) {
        // ... processing
    }
}

Fixed Code:

// Separate functions for input/output processing
void read_input_stream(hls::stream<input_axi_t>& in, hls::stream<input_t>& in_local, hls::stream<bool>& last_stream) {
#pragma HLS INLINE off
    bool is_last = false;
    for(unsigned i = 0; i < N_IN / input_t::size; ++i) {
#pragma HLS PIPELINE II=1
        input_t ctype;
#pragma HLS DATA_PACK variable=ctype
        for(unsigned j = 0; j < input_t::size; j++) {
            input_axi_t word = in.read();
            ctype[j] = typename input_t::value_type(word.data);
            is_last |= (word.last == 1) ? true : false;
        }
        in_local.write(ctype);
    }
    last_stream.write(is_last);
}

void process_prediction(hls::stream<input_t>& in_local, hls::stream<result_t>& out_local) {
#pragma HLS INLINE off
    myproject(in_local, out_local);
}

void write_output_stream(hls::stream<result_t>& out_local, hls::stream<bool>& last_stream, hls::stream<output_axi_t>& out) {
#pragma HLS INLINE off
    bool is_last = last_stream.read();
    for(unsigned i = 0; i < N_OUT / result_t::size; ++i) {
#pragma HLS PIPELINE II=1
        result_t ctype = out_local.read();
        for(unsigned j = 0; j < result_t::size; j++) {
            bool last = (is_last && (i * result_t::size + j == N_OUT - 1)) ? true : false;
            output_axi_t pkt;
            pkt.data = ctype[j];
            pkt.last = last ? 1 : 0;
            out.write(pkt);
        }
    }
}

void myproject_axi(hls::stream<input_axi_t>& in, hls::stream<output_axi_t>& out) {
#pragma HLS INTERFACE axis port=in
#pragma HLS INTERFACE axis port=out
#pragma HLS INTERFACE ap_ctrl_none port=return
#pragma HLS DATAFLOW

    hls::stream<input_t> in_local("input_1");
    hls::stream<result_t> out_local("output_1");
    hls::stream<bool> last_stream("last_stream");
#pragma HLS STREAM variable=in_local depth=1
#pragma HLS STREAM variable=out_local depth=1
#pragma HLS STREAM variable=last_stream depth=1

    // Clean dataflow with only function calls
    read_input_stream(in, in_local, last_stream);
    process_prediction(in_local, out_local);
    write_output_stream(out_local, last_stream, out);
}

Key Changes Summary

1. Scoped weight and bias declarations inside DATAFLOW region in myproject.cpp
2. Interface Directives: Removed axis interface directives from non-top-level functions
3. Dataflow Structure: Separated complex logic into individual functions to maintain canonical dataflow form
4. Stream-based Interface: Changed from array-based to stream-based AXI interface for better dataflow compatibility
5. Function Separation: Created dedicated functions for input reading, processing, and output writing

Results

After implementing these changes:

• All HLS 214-113 warnings eliminated
• Dataflow form check warnings resolved
• Interface directive warnings cleared
• Synthesis completed successfully with improved dataflow optimization

This solution maintains the original functionality while ensuring compliance with Vivado HLS dataflow requirements and eliminating synthesis warnings.

[vloncar]

Thanks for the report. Can you provide synthesis results before and after to compare?

[AbuAli3]

Thank you for your reply. After further investigation and experimentation, I realized that while the initial synthesis warnings were resolved, I had not carefully reviewed the synthesis report. Upon closer inspection, I found that the DSP resources were not utilized as expected, which indicated an underlying issue.

The root cause was that although the dataflow and other warnings disappeared, the weights and biases were not properly loaded. This was because the weight arrays were declared as local, non-static variables inside the function, and the weight loading code attempted to initialize them there. Consequently, these arrays were re-created on every function call and immediately discarded, preventing the weights from persisting or being properly initialized. This led to zero or incorrect predictions and the elimination of DSP usage during synthesis.

To fix this, I refactored the weight-using operations into separate helper functions and isolated global weight access outside the dataflow region while maintaining the original functionality. This approach resolved the warnings while ensuring correct DSP utilization and proper weight initialization from the header files.

I also tested both designs — the original hls4ml-generated code and my optimized version — using the NeuralNetworkOverlay driver. The optimized design almost doubled the inference speed:

Performance Testing Results

I tested both designs using the NeuralNetworkOverlay driver:

Original HLS4ML Design

from axi_stream_driver import NeuralNetworkOverlay
import numpy as np

X_test = np.load('X_test_scaled.npy')
y_test = np.load('y_test_scaled.npy')

nn = NeuralNetworkOverlay('ANN.bit', X_test.shape, y_test.shape)
y_hw_prediction, latency, throughput = nn.predict(X_test, profile=True)

Result: Classified 3464 samples in 0.005578 seconds (621,011.12 inferences/s)

Optimized HLS4ML Design

from axi_stream_driver import NeuralNetworkOverlay
import numpy as np

X_test = np.load('X_test_scaled.npy')
y_test = np.load('y_test_scaled.npy')

nn = NeuralNetworkOverlay('hls4ml_t.bit', X_test.shape, y_test.shape)
y_hw_prediction, latency, throughput = nn.predict(X_test, profile=True)

Result: Classified 3464 samples in 0.003679 seconds (941,560.21 inferences/s)

Performance Improvement

The optimized design achieved nearly double the inference speed:

• Original Design: 621,011 inferences/s
• Optimized Design: 941,560 inferences/s
• Improvement: ~51.6% faster (1.52x speedup)

Optimized Code Implementation

Main Neural Network Implementation (myproject.cpp)

#include <iostream>
#include "myproject.h"
#include "parameters.h"

// Helper function for first dense layer
void dense_layer_1(hls::stream<input_t> &input_1, hls::stream<q_dense_result_t> &layer2_out) {
    #pragma HLS INLINE off
    nnet::dense<input_t, q_dense_result_t, config2>(input_1, layer2_out, w2, b2);
}

// Helper function for normalization 1
void norm_layer_1(hls::stream<layer4_t> &layer4_out, hls::stream<batch_normalization_result_t> &layer5_out) {
    #pragma HLS INLINE off
    nnet::normalize<layer4_t, batch_normalization_result_t, config5>(layer4_out, layer5_out, s5, b5);
}

// Helper function for second dense layer
void dense_layer_2(hls::stream<batch_normalization_result_t> &layer5_out, hls::stream<q_dense_1_result_t> &layer6_out) {
    #pragma HLS INLINE off
    nnet::dense<batch_normalization_result_t, q_dense_1_result_t, config6>(layer5_out, layer6_out, w6, b6);
}

// Helper function for normalization 2
void norm_layer_2(hls::stream<layer8_t> &layer8_out, hls::stream<batch_normalization_1_result_t> &layer9_out) {
    #pragma HLS INLINE off
    nnet::normalize<layer8_t, batch_normalization_1_result_t, config9>(layer8_out, layer9_out, s9, b9);
}

// Helper function for final dense layer
void dense_layer_3(hls::stream<batch_normalization_1_result_t> &layer9_out, hls::stream<result_t> &layer10_out) {
    #pragma HLS INLINE off
    nnet::dense<batch_normalization_1_result_t, result_t, config10>(layer9_out, layer10_out, w10, b10);
}

void myproject(
    hls::stream<input_t> &input_1,
    hls::stream<result_t> &layer10_out
) {
    #pragma HLS DATAFLOW
    
    hls::stream<q_dense_result_t> layer2_out("layer2_out");
    #pragma HLS STREAM variable=layer2_out depth=1
    hls::stream<layer4_t> layer4_out("layer4_out");
    #pragma HLS STREAM variable=layer4_out depth=1
    hls::stream<batch_normalization_result_t> layer5_out("layer5_out");
    #pragma HLS STREAM variable=layer5_out depth=1
    hls::stream<q_dense_1_result_t> layer6_out("layer6_out");
    #pragma HLS STREAM variable=layer6_out depth=1
    hls::stream<layer8_t> layer8_out("layer8_out");
    #pragma HLS STREAM variable=layer8_out depth=1
    hls::stream<batch_normalization_1_result_t> layer9_out("layer9_out");
    #pragma HLS STREAM variable=layer9_out depth=1
    
    dense_layer_1(input_1, layer2_out);
    nnet::hard_tanh<q_dense_result_t, layer4_t, hard_tanh_config4>(layer2_out, layer4_out);
    norm_layer_1(layer4_out, layer5_out);
    dense_layer_2(layer5_out, layer6_out);
    nnet::hard_tanh<q_dense_1_result_t, layer8_t, hard_tanh_config8>(layer6_out, layer8_out);
    norm_layer_2(layer8_out, layer9_out);
    dense_layer_3(layer9_out, layer10_out);
}

AXI Stream Interface Implementation (myproject_axi.cpp)

#include "myproject_axi.h"

// Read and pack input stream from AXI interface into internal data stream,
// while tracking the 'last' signal as a local boolean flag.
void read_and_pack(
    hls::stream<input_axi_t>& in,
    hls::stream<input_t>&     in_local,
    bool &is_last)
{
    #pragma HLS INLINE
    is_last = false;
    for (unsigned i = 0; i < N_IN / input_t::size; ++i) {
        #pragma HLS PIPELINE II=1
        input_t ctype;
        #pragma HLS DATA_PACK variable=ctype
        for (unsigned j = 0; j < input_t::size; ++j) {
            input_axi_t word = in.read();
            ctype[j]        = typename input_t::value_type(word.data);
            is_last       |= (word.last == 1);
        }
        in_local.write(ctype);
    }
}

// The neural network compute function remains unchanged,
// taking packed input stream and producing result stream.
void process_prediction(
    hls::stream<input_t>&  in_local,
    hls::stream<result_t>& out_local)
{
    #pragma HLS INLINE
    myproject(in_local, out_local);
}

// Write output data from internal result stream to AXI stream interface,
// sending the 'last' flag only on the final output packet.

void write_output_stream(
    hls::stream<result_t>&    out_local,
    bool                      is_last,
    hls::stream<output_axi_t>& out)
{
    #pragma HLS INLINE off
    // Prefetch first output vector to start streaming
    result_t buf = out_local.read();
    unsigned elem = 0;
    for (unsigned idx = 0; idx < N_OUT; ++idx) {
        #pragma HLS PIPELINE II=1
        if (elem == result_t::size) {
            buf  = out_local.read();
            elem = 0;
        }
        output_axi_t pkt;
        pkt.data = buf[elem];
        pkt.last = (is_last && (idx == N_OUT - 1)) ? 1 : 0;
        out.write(pkt);
        ++elem;
    }
}

// Top-level function connecting AXI-stream input/output ports,
// orchestrating read, process, and write functions in a dataflow manner.
void myproject_axi(
    hls::stream<input_axi_t>&   in,
    hls::stream<output_axi_t>&  out)
{
    #pragma HLS INTERFACE axis port=in
    #pragma HLS INTERFACE axis port=out
    #pragma HLS INTERFACE ap_ctrl_none port=return
    #pragma HLS DATAFLOW
    
    hls::stream<input_t>  in_local("in_local");
    hls::stream<result_t> out_local("out_local");
    #pragma HLS STREAM variable=in_local  depth=1
    #pragma HLS STREAM variable=out_local depth=1
    
    bool is_last;
    read_and_pack(in,  in_local,  is_last);
    process_prediction(in_local, out_local);
    write_output_stream(out_local, is_last, out);
}

I have attached both synthesis reports (before and after) for your reference.

Please let me know if I am on the right path!

After.txt
before.txt