Data Arrays

DataArray is the unified array schema in Waveflow. It defines element type, maximum shape, runtime/static shape behavior, and C++ storage lowering.

1. Declaring DataArray

A DataArray subclass declares:

• element_type: schema type for each element
• max_shape: maximum dimensions
• static: fixed-size (True) or runtime-length (False, leading dimension)
• cpp_storage: C++ layout mode ("struct" or "raw")

Example from examples/stream_inband/poly.py:

class CoeffArray(DataArray):
    ncoeff = 4
    element_type = Float32
    static = True
    max_shape = (ncoeff,)
    cpp_storage = "raw"

2. Runtime construction with array()

For runtime values, use the array factory in waveflow/hw/arrayutils.py:

from waveflow.hw.arrayutils import array

samples = array(Float32, [1.0, -2.0, 3.5])

array(elem_type, data, static=False) specializes DataArray from the runtime shape and returns an initialized instance.

3. cpp_storage="struct" vs "raw"

DataArray supports two C++ lowering modes:

• cpp_storage="struct" (default): generates a struct wrapper with a named member (default data) and schema methods.
• cpp_storage="raw": lowers to a raw C++ array (T[N]) and requires static=True with 1-D shape.

Illustrative lowering shape:

// struct mode (default)
struct Float32Array {
    float data[N];
    template<int WORD_BW> void write_array(ap_uint<WORD_BW> x[]) const;
    template<int WORD_BW> void read_array(const ap_uint<WORD_BW> x[]);
};

// raw mode (used by CoeffArray)
float coeffs[N];

CoeffArray in the poly example uses cpp_storage="raw" to map coefficient storage directly to a flat C++ array.

4. Generated array utilities via ArrayUtilsStep

Array packing helpers are generated by ArrayUtilsStep in a BuildDag:

from waveflow.build.build import BuildConfig, BuildDag
from waveflow.build.streamutils import StreamUtilsStep
from waveflow.hw.arrayutils import ArrayUtilsStep

cfg = BuildConfig(root_dir=project_dir)
dag = BuildDag()
dag.add(StreamUtilsStep(output_dir="include"))
dag.add(ArrayUtilsStep(Float32, [32, 64]))
dag.run(cfg)

ArrayUtilsStep is dependency-aware and resolves StreamUtilsStep in the same DAG. It emits include/<elem>_array_utils.h and include/<elem>_array_utils_tb.h.

Pipelined stream operation note

Pipelined stream operations (get_pipelined, write_pipelined) are only valid inside @synthesizable hook bodies. They are not legal in top-level extracted bodies such as on_start, run_proc, or testbench main(). See Synthesis Extractor.