stream_merge_kernels 模块深度解析

概述：数据流的"交通指挥员"

想象一个繁忙的十字路口，有8条狭窄的车道（低速窄总线）需要合并成4条宽阔的高速公路（高速宽总线）。如果直接硬连接，车辆会混乱碰撞；如果让司机自己协调，效率会极低。stream_merge_kernels 就是这个路口的智能交通信号灯——它负责将多个低速、窄位宽的 AXI-Stream 输入流重新组织、缓冲、排序后，输出到更少但更宽的总线上。

这个模块是 Channelizer 设计中的关键数据重组层。在 Versal ACAP 架构中，AI Engine (AIE) 阵列与可编程逻辑 (PL) 之间的 PLIO 接口运行在相对较低的频率（如 312.5 MHz），而 AIE 核内部可以运行在更高的吞吐量下。为了匹配这种带宽差异，系统需要将多个窄 PLIO 流合并成更宽的内部数据路径。merge_8x4 和 merge_4x1 这两个 HLS kernel 就是实现这种"多对少"流合并的核心组件。

问题空间：为什么要做流合并？

带宽不匹配问题

在 Channelizer 系统中，数据流动面临一个基本矛盾：

• PL 侧限制：PLIO 接口通常宽度为 128-bit，时钟频率约 312.5 MHz
• AIE 侧需求：AIE 核可以以更高并行度处理数据，需要聚合更多样本才能饱和计算单元

如果不进行流合并，每个 PLIO 流只能独立传输，无法充分利用 AIE 阵列的处理能力。这就像用8根细水管给一个大水池注水——每根水管的流量有限，必须把它们汇聚起来才能达到所需的总流量。

多相序 vs 线性序

另一个关键问题是数据顺序。Channelizer 使用多相滤波器组结构，数据天然以"多相序"（polyphase order）到达——即不同相位（子带）的数据交错到达。但后续处理（如 IFFT）通常期望"线性序"（linear order）——即按时间顺序排列的连续样本。

stream_merge_kernels 不仅合并流，还负责这种顺序转换：从多相序输入重组为线性序输出。

核心抽象：Producer-Consumer + Stream-of-Blocks

理解这个模块的关键是掌握三个核心抽象：

1. Producer-Consumer 数据流模型

模块内部采用经典的 Producer-Consumer 模式，通过 #pragma HLS DATAFLOW 指令实现并发：

• Consumer：从多个输入 AXI-Stream 读取数据，写入中间缓冲区
• Producer：从中间缓冲区读取数据，重排后写入输出 AXI-Stream

两个函数作为独立的流水线阶段并行执行，通过 hls::stream_of_blocks 进行数据传递。

2. Stream-of-Blocks：块级流同步

这是 Vitis HLS 提供的高级抽象，可以理解为"带事务语义的 FIFO"：

hls::stream_of_blocks<TT_BLOCK> ss0;  // 块级流通道
hls::write_lock<TT_BLOCK> WL0(ss0);   // Consumer 获取写锁
hls::read_lock<TT_BLOCK> RL0(ss0);    // Producer 获取读锁

• 块（Block）：一个固定大小的数组（这里是 TT_DATA[DEPTH]），作为原子传输单元
• 写锁（write_lock）：Consumer 获取锁后才能写入整个块；写入完成后自动释放，Producer 才能读取
• 读锁（read_lock）：Producer 获取锁后才能读取整个块；读取完成后块被释放回池

这种机制保证了批量数据传输的原子性，避免了逐样本同步的开销。

3. 双端口 BRAM 缓冲

#pragma HLS bind_storage variable=ss0 type=ram_t2p impl=bram

每个 stream_of_blocks 底层映射到真双端口 BRAM（True Dual-Port BRAM）：

• 端口 A：Consumer 写入
• 端口 B：Producer 读取
• 两个端口可以同时访问，实现无冲突的并发读写

两个 Kernel 详解

merge_8x4：8 入 4 出流合并器

功能：将 8 个 128-bit 输入流合并为 4 个 128-bit 输出流，同时进行多相序到线性序的转换。

数据映射关系：

时序特性：

• Consumer II = 2：每 2 个周期消费 8 个输入样本（4 个 128-bit 字）
• Producer II = 2：每 2 个周期产生 8 个输出样本（4 个 128-bit 字）
• 等效吞吐率：在 312.5 MHz 下，每个输出流维持 625 MSamples/s（两个 cint32 @ 312.5 MHz）

数据重排逻辑：

// Consumer：从8个输入流收集到4个块缓冲区
WL0[0] = sig_i[0].read(); WL0[1] = sig_i[1].read();  // 块0: 流0,1
WL1[0] = sig_i[2].read(); WL1[1] = sig_i[3].read();  // 块1: 流2,3
WL2[0] = sig_i[4].read(); WL2[1] = sig_i[5].read();  // 块2: 流4,5
WL3[0] = sig_i[6].read(); WL3[1] = sig_i[7].read();  // 块3: 流6,7

// Producer：从块中解包并重排到4个输出流
// 每个128-bit字包含两个cint32样本 (高位, 低位)
(v08,v00) = RL0[0];  // v00来自流0低半，v08来自流0高半
(v09,v01) = RL0[1];  // v01来自流1低半，v09来自流1高半
// ... 类似解包其他块

// 输出按线性序写入（先写前4个样本，再写后4个）
sig_o[0].write((v04,v00));  // 输出流0: 样本0和4
sig_o[1].write((v05,v01));  // 输出流1: 样本1和5
// ...

关键洞察：输入是多相序（同一时刻不同子带），输出是线性序（同一子带不同时刻）。这种重排是 Channelizer 从滤波器组输出到 IFFT 输入的关键格式转换。

merge_4x1：4 入 1 出流合并器

功能：将 4 个 128-bit 输入流合并为 1 个 128-bit 输出流，完成最终的数据汇聚。

数据映射关系：

存储优化：

#pragma HLS bind_storage variable=ss type=ram_s2p impl=lutram

使用简单双端口 LUTRAM（Single Dual-Port LUTRAM）而非 BRAM，因为：

• 数据量较小（仅 4 个 128-bit 字 = 64 字节）
• LUTRAM 延迟更低，访问更快
• 节省 BRAM 资源用于更大缓冲区

时序特性：

• Consumer II = 8：每 8 个周期消费 4 个输入样本
• Producer II = 8：每 8 个周期产生 4 个输出样本

架构数据流

设计决策与权衡

1. 为什么使用 stream_of_blocks 而不是普通 hls::stream？

选择：使用 hls::stream_of_blocks<TT_BLOCK> 作为中间缓冲

替代方案：直接使用 hls::stream<TT_DATA>

权衡分析：

决策理由：Producer 需要从每个块中按特定模式提取样本（如 (v08,v00) = RL0[0]），这种非顺序访问模式需要块级随机访问能力，普通流无法满足。

2. 为什么选择 II=2（merge_8x4）和 II=8（merge_4x1）？

Initiation Interval (II) 决定流水线的吞吐率。

merge_8x4 的 II=2：

• 每 2 周期处理 8 个输入样本 → 每周期 4 样本
• 匹配 PLIO 带宽：312.5 MHz × 128-bit × 4 流 ≈ 200 Gbps 总带宽
• 若追求 II=1，需要加倍硬件资源（更多并行读取端口），收益有限

merge_4x1 的 II=8：

• 输出只有 1 个流，瓶颈在输出带宽
• II=8 意味着每 8 周期输出 4 个 128-bit 字 = 8 个样本
• 与下游处理速率匹配，避免过度设计

3. 为什么 merge_8x4 用 BRAM，merge_4x1 用 LUTRAM？

关键考量：

• BRAM 的最小粒度通常为 18Kb 或 36Kb，过小 buffer 会造成浪费
• LUTRAM 适合 <100 字节的小缓冲区，且支持更灵活的分布式布局

4. 为什么使用 ap_ctrl_none 控制协议？

#pragma HLS interface mode=ap_ctrl_none port=return

这意味着 kernel 没有阻塞式的启动/完成握手信号，一旦数据到达就开始处理。这是流式处理的典型模式：

• 优点：零开销启动，纯数据驱动，适合持续数据流
• 风险：调用者必须确保数据可用性和时序正确性，无法通过控制信号反压

系统集成上下文

在 Channelizer 中的位置

这两个 kernel 位于 AIE-ML 阵列与 HLS 处理链路之间：

• AIE 输出的多相数据通过 PLIO 进入 merge_8x4
• merge_8x4 将 8 路 PLIO 合并为 4 路更宽的流
• merge_4x1 进一步合并为单路流，供后续 IFFT 处理

与相邻模块的关系

新贡献者注意事项

1. 数据对齐与样本计数约束

测试台明确声明：

static constexpr int NSAMP = 512; // Must be a multiple of 16 (for merge_8x4)
static constexpr int NSAMP = 512; // Must be a multiple of 8 (for merge_4x1)

陷阱：如果样本数不是 16（或 8）的倍数，最后一次迭代会读取不完整块，导致死锁或数据损坏。

2. Stream-of-Blocks 的死锁风险

hls::stream_of_blocks 的锁语义是严格的：

• Consumer 必须写完整个块才能释放写锁
• Producer 必须读完整个块才能释放读锁
• 如果 Consumer 崩溃或提前返回，Producer 永远等待

调试建议：在 C-sim 中启用波形跟踪 (cosim.wave_debug=true) 观察锁状态。

3. 数据打包格式的隐含假设

代码中大量使用了这种打包语法：

(v08,v00) = RL0[0];  // 解包 128-bit 为两个 64-bit cint32
sig_o[0].write((v04,v00));  // 打包两个 64-bit 为 128-bit

这依赖于 ap_uint<128> 的大端打包约定（高位在前）。如果数据类型定义改变，所有打包/解包逻辑都需要同步修改。

4. HLS 综合的资源预估

在修改代码前，了解当前资源占用：

• merge_8x4：4 个 BRAM18K（用于 4 个 ss 缓冲区）+ 少量 FF/LUT
• merge_4x1：~64 LUT（用于 LUTRAM）+ 少量 FF

增加缓冲区深度或并行度会直接增加 BRAM/LUT 消耗，需在面积和性能间权衡。

5. 测试向量生成

merge_8x4 使用外部文件作为测试激励：

tb.file=data/stream0_i.txt
tb.file=data/stream1_i.txt
...

这些文件由 gen_vectors.m MATLAB 脚本生成。修改数据格式或位宽时，必须同步更新向量化脚本。

总结

stream_merge_kernels 是 Channelizer 设计中承上启下的关键组件：

1. 问题解决：解决 AIE-PL 带宽不匹配和多相序到线性序的格式转换问题
2. 核心抽象：Producer-Consumer + Stream-of-Blocks 实现高效并发数据重组
3. 架构角色：作为数据流的"交通指挥员"，在保证吞吐的同时完成必要的顺序转换
4. 设计哲学：在资源（BRAM/LUT）和性能（II）之间取得平衡，优先保证时序收敛

理解这个模块的关键是把握数据如何在时间和空间两个维度上被重新组织——它不仅合并了物理流，更重组了数据的逻辑顺序，为后续的频域处理铺平道路。