DMA Endpoint Kernels (dma_endpoint_kernels)

一句话概括

dma_endpoint_kernels 是 Channelizer 系统的"数据大门"——它负责把 DDR 内存中的原始数据高效地搬进搬出 AIE-ML 计算阵列，就像一座精心设计的桥梁，既要承受 2 GSPS 的数据洪流，又要确保数据格式在 PL 和 AIE 之间无缝转换。

问题空间：为什么需要这个模块？

异构计算的带宽鸿沟

在 Versal AIE-ML 架构中，我们面临一个经典挑战：DDR 内存 ↔ PL ↔ AIE-ML 三者之间的数据搬运和格式转换。

想象一下：你有一个每秒处理 20 亿个采样点（2 GSPS）的 Channelizer，但数据最初以线性顺序存储在 DDR4 内存中。而 AIE-ML 引擎期望的是多路并行流式数据，且数据排列方式需要符合多相滤波器的特殊要求。

如果没有专门的数据搬运内核，你会遇到：

1. 带宽瓶颈：DDR 访问延迟高，直接随机访问会饿死计算单元
2. 格式不匹配：DDR 存储的是线性样本序列，AIE 需要的是多相分解后的并行流
3. 时钟域跨越：DDR 控制器、PL 逻辑、AIE 阵列运行在不同频率，需要平滑过渡
4. 吞吐量缺口：单个 AXI4-Stream 只能提供 32-bit/cycle，要达到 2 GSPS 需要多条并行流

设计动机：专用硬件数据搬运器

与其让 CPU 或通用 DMA 控制器来处理这些复杂的格式转换，不如在可编程逻辑（PL）中实现专用的 HLS 内核。这样可以：

• 利用 burst 传输摊平 DDR 访问延迟
• 在 PL 中进行数据重排，释放 AIE 计算资源
• 通过多路并行流满足带宽需求
• 使用 ping-pong 缓冲实现流水线化数据传输

核心抽象与心智模型

类比：快递分拣中心

想象 dma_endpoint_kernels 是一个大型快递分拣中心：

两个核心组件

本模块包含两个对称的内核：

1. channelizer_dma_src —— "入口大门"

DDR4 (线性样本) → load_buffer() → 内部缓冲区 → transmit() → 2x AXI4-Stream → AIE-ML

关键职责：

• 从 DDR 批量读取原始数据（burst 模式）
• 将线性样本序列转换为多相并行流格式
• 每个 DDR word 包含 4 个 cint16 样本，分发到 2 条输出流
• 支持循环播放（loop_cnt 参数）

2. channelizer_dma_snk —— "出口大门"

AIE-ML → 4x AXI4-Stream → capture_streams() → 内部缓冲区 → read_buffer() → DDR4

关键职责：

• 从 4 条输入流捕获 AIE 计算结果
• 支持选择性捕获（loop_sel 只保存指定迭代的结果）
• 将并行流合并回线性 DDR 存储格式
• 每个 DDR word 包含 2 个 cint32 样本

架构详解

整体数据流

关键设计参数

Source Kernel (channelizer_dma_src)

Sink Kernel (channelizer_dma_snk)

代码深度解析

Source Kernel: channelizer_dma_src_wrapper

void channelizer_dma_src_wrapper(
    TT_DATA mem[DEPTH*NSTREAM],      // m_axi: DDR4 数据源
    int loop_cnt,                     // s_axilite: 循环次数控制
    TT_STREAM sig_o[NSTREAM]          // axis: AIE 输出流
)

阶段 1: load_buffer() —— 数据重排的艺术

void load_buffer( TT_DATA mem[DEPTH*NSTREAM], 
                  TT_SAMPLE (&buff)[NSTREAM][DEPTH*4] )
{
  LOAD_SAMP : for (int mm=0,dd=0,ss=0; mm < DEPTH*NSTREAM; mm++) {
#pragma HLS pipeline II=1
    TT_SAMPLE val0, val1, val2, val3;
    (val3,val2,val1,val0) = mem[mm];     // 解包 128-bit word
    buff[ss  ][dd  ] = val0;             // 多相分配到 stream 0
    buff[ss+1][dd  ] = val1;             // 多相分配到 stream 1
    buff[ss  ][dd+1] = val2;
    buff[ss+1][dd+1] = val3;
    dd+=2;
  }
}

关键洞察：

• 输入是线性存储：[sample0, sample1, sample2, sample3, ...]
• 输出是多相排列：stream0: [s0, s2, s4, ...], stream1: [s1, s3, s5, ...]
• 这是 Channelizer 算法的核心要求——多相分解必须在数据进入 AIE 前完成

阶段 2: transmit() —— 流式生成

void transmit( TT_SAMPLE (&buff)[NSTREAM][DEPTH*4], 
               TT_STREAM sig_o[NSTREAM], 
               const int& loop_cnt )
{
 REPEAT: for (int ll=0; ll < loop_cnt; ll++) {
#pragma HLS LOOP_TRIPCOUNT min=1 max=8
  RUN_DEPTH: for (int cc=0,dd=0; cc < DEPTH; cc++) {
#pragma HLS PIPELINE II=1
    STREAM1: for (int ss=0; ss < NSTREAM; ss++) {
        // 每次发送 4 个样本打包成 128-bit
        sig_o[ss].write( (val3,val2,val1,val0) );
    }
    dd+=4;
  }
 }
}

性能分析：

• II=1 意味着每周期输出一个 128-bit word
• 在 312.5 MHz 下，单流带宽 = 128 × 312.5M = 40 Gbps = 5 GB/s
• 双流合计 = 10 GB/s，足以支撑 2 GSPS × 4 bytes/sample = 8 GB/s 的需求

内存架构

TT_SAMPLE buff[NSTREAM][DEPTH*4];
#pragma HLS array_partition variable=buff dim=1      // 按 stream 分区
#pragma HLS bind_storage variable=buff type=RAM_T2P impl=uram  // URAM 实现
#pragma HLS dependence variable=buff type=intra false // 消除假依赖

• array_partition dim=1：将 2 个 stream 的存储完全分离，允许同时访问
• RAM_T2P impl=uram：使用 UltraRAM（VE2802 有丰富 URAM 资源）
• dependence intra false：告诉 HLS load_buffer 和 transmit 不会冲突

Sink Kernel: channelizer_dma_snk_wrapper

void channelizer_dma_snk_wrapper(
    TT_DATA mem[DEPTH*NSTREAM],      // m_axi: DDR4 目标
    int loop_sel,                     // s_axilite: 选择保存哪一轮
    int loop_cnt,                     // s_axilite: 总循环次数
    TT_STREAM sig_i[NSTREAM]          // axis: AIE 输入流
)

阶段 1: capture_streams() —— 选择性捕获

void capture_streams( TT_SAMPLE (&buff)[NSTREAM][2*DEPTH], 
                      TT_STREAM sig_i[NSTREAM],
                      const int& loop_sel, const int& loop_cnt )
{
 CAPTURE: for (int ll=0; ll < loop_cnt; ll++) {
#pragma HLS LOOP_TRIPCOUNT min=1 max=8
    for (int cc=0,addr=0; cc < DEPTH; cc++) {
#pragma HLS pipeline II=1
      for (int ss=0; ss < NSTREAM; ss++) {
        ( val1, val0 ) = sig_i[ss].read();
        if ( ll == loop_sel ) {          // 只保存指定轮次
          buff[ss][addr+0] = val0;
          buff[ss][addr+1] = val1;
        }
      }
    }
 }
}

设计意图：

• loop_sel 允许调试时只捕获特定迭代的数据
• 避免重复运行整个设计来获取中间状态
• 如果 loop_sel >= loop_cnt，则不保存任何数据（空运行）

阶段 2: read_buffer() —— 流合并

void read_buffer( TT_DATA mem[DEPTH], TT_SAMPLE (&buff)[NSTREAM][2*DEPTH] )
{
  for (int rr=0,mm=0; rr < 2*DEPTH; rr+=2) {
    int addr0 = rr;
    int ss0=0;
    for (int cc=0; cc < NSTREAM; cc++) {
#pragma HLS PIPELINE II=1
      TT_SAMPLE val0 = buff[ss0  ][addr0];
      TT_SAMPLE val1 = buff[ss0+1][addr0];
      mem[mm++] = ( val1, val0 );        // 打包回 DDR 格式
      // ... 地址计算逻辑
    }
  }
}

注意复杂性：

• 4 条输入流需要交错合并回线性存储
• 地址计算逻辑比 source kernel 更复杂（stride 模式不同）
• 这反映了 2D IFFT 输出到 Channelizer 最终输出的格式转换需求

关键设计决策与权衡

1. DATAFLOW vs PIPELINE

决策：在两个 kernel 中都使用 #pragma HLS DATAFLOW

#pragma HLS DATAFLOW
load_buffer(mem, buff);   // Stage 1
transmit(buff, sig_o, loop_cnt);  // Stage 2

替代方案：单个大循环内联所有逻辑

权衡分析：

为什么选 DATAFLOW：Channelizer 是吞吐导向的设计，隐藏延迟比节省资源更重要。

2. URAM vs BRAM

决策：使用 impl=uram 绑定存储

背景：VE2802 器件有：

• ~600 个 BRAM（36 Kbit each）
• ~300 个 URAM（288 Kbit each）

权衡分析：

为什么选 URAM：大容量、低功耗，正好适合这种大块连续缓冲的场景。

3. Stream 数量的不对称性

观察：Source 用 2 条流，Sink 用 4 条流

原因：

• 输入侧：TDM FIR 接受 cint16 @ 2 GSPS，每条 128-bit 流承载 4× cint16 @ 312.5 MHz
  • 需要 2 条流达到 8 cint16/cycle = 2 GSPS
• 输出侧：2D IFFT 产生 cint32 结果，每条流承载 2× cint32
  • 需要 4 条流达到 8 cint32/cycle（等效带宽）

权衡：这种不对称增加了 PL 侧 merge/split kernel 的复杂度（见同目录下的 merge_4x1、split_1x16 等），但简化了 AIE 侧的 IP 配置。

4. 固定参数 vs 运行时配置

决策：大多数参数（NSTREAM, DEPTH, NCHAN）是编译时常量，只有 loop_cnt 和 loop_sel 是运行时配置

权衡分析：

为什么选编译时常量：Channelizer 是垂直领域应用，规格固定（4096 通道、2 GSPS），追求极致性能胜过灵活性。

接口协议详解

AXI4-Full (m_axi)

#pragma HLS interface m_axi port=mem bundle=gmem offset=slave depth=DEPTH*NSTREAM

• bundle=gmem：与其他 kernel 共享同一 DDR 端口
• offset=slave：基地址通过 AXI4-Lite 配置寄存器设置
• depth：指导 HLS 生成合适的 burst 长度

Burst 行为：

• load_buffer 会生成最大长度的 burst 读取
• 假设 DDR4-2400，理论带宽 ~19 GB/s，实际考虑效率后 ~15 GB/s
• 远超过 8 GB/s 的需求，因此不是瓶颈

AXI4-Stream (axis)

#pragma HLS interface axis port=sig_o

• 标准 AXI4-Stream，无 sideband 信号（TLAST, TKEEP 等）
• 依赖上层协议保证数据完整性
• 与 AIE-ML PLIO 直接对接

AXI4-Lite (s_axilite)

#pragma HLS interface s_axilite port=loop_cnt bundle=control
#pragma HLS interface s_axilite port=mem     bundle=control  // 基地址
#pragma HLS interface s_axilite port=return  bundle=control  // 中断/状态

• 主机（ARM PS）通过 memory-mapped 寄存器控制 kernel
• loop_cnt：配置循环次数
• mem：设置 DDR 缓冲区基地址
• return：kernel 完成中断

新贡献者必读：陷阱与注意事项

1. 数据对齐要求

陷阱：DDR 缓冲区必须 128-bit 对齐（16 字节边界）

// 错误：可能导致未定义行为
void* raw_ptr = malloc(DEPTH * NSTREAM * sizeof(TT_DATA));
TT_DATA* mem = (TT_DATA*)raw_ptr;  // 可能未对齐！

// 正确：使用对齐分配
alignas(16) TT_DATA mem[DEPTH * NSTREAM];
// 或在 Linux 中用 posix_memalign

后果：未对齐访问可能导致：

• 性能下降（AXI 拆分事务）
• 硬件挂起（某些平台）
• 静默数据损坏

2. Loop Tripcount 提示的重要性

#pragma HLS LOOP_TRIPCOUNT min=1 max=8

这不是可选的装饰！

• HLS 使用 tripcount 估计性能（latency/throughput report）
• 如果实际 loop_cnt > 8，综合报告会低估 latency
• 但不会造成功能错误——只是让你对性能判断失误

建议：根据实际应用场景调整 max 值

3. DATAFLOW 的死锁风险

危险模式：

// 错误示例：条件写入 hls::stream
if (some_condition) {
    sig_o[ss].write(data);  // 可能导致死锁！
}

原因：DATAFLOW 要求 producer-consumer 之间的 token 数量匹配。条件写入会破坏这个假设。

当前代码的安全性：

• transmit() 总是写入固定数量的数据（DEPTH × loop_cnt）
• capture_streams() 总是读取固定数量，即使不保存也读取（丢弃）
• 这是正确的做法

4. URAM 的复位行为

陷阱：URAM 在上电时内容不确定，仿真时可能显示为 'X'

测试影响：

• C-simulation 中，未初始化的 URAM 可能包含垃圾值
• 如果 kernel 逻辑依赖于初始零值，仿真会失败
• Co-simulation 更接近硬件，但仍有差异

缓解措施：

• 确保所有写入路径覆盖全部地址
• 或使用 ap_int 的显式初始化（但会增加初始化时间）

5. Stream 深度不足的风险

虽然代码中没有显式设置 hls::stream 深度，但在实际系统中：

// 如果下游 AIE 暂时 stall，stream 需要足够深度缓冲
hls::stream<TT_DATA> sig_o[NSTREAM];  // 默认深度可能不够！

建议：在 system integration 时检查 FIFO 深度配置，通常需要 16~64 的深度来吸收 AIE 的 jitter。

6. 类型别名的一致性

头文件定义：

// channelizer_dma_src.h
typedef ap_uint<NBITS>       TT_DATA;     // 128-bit
typedef ap_uint<NBITS/4>     TT_SAMPLE;   // 32-bit (cint16)

// channelizer_dma_snk.h  
typedef ap_uint<NBITS>       TT_DATA;     // 128-bit
typedef ap_uint<NBITS/2>     TT_SAMPLE;   // 64-bit (cint32)!

陷阱：同样的名字 TT_SAMPLE 在不同 kernel 中宽度不同！

• Source: 32-bit（容纳 cint16）
• Sink: 64-bit（容纳 cint32）

后果：如果在测试中混用头文件，会导致位宽不匹配的错误。

7. Loop Select 的越界行为

// 如果 loop_sel >= loop_cnt，会发生什么？
capture_streams(buff, sig_i, loop_sel=10, loop_cnt=5);

答案：什么都不会保存，kernel 正常完成，返回成功。

这可能是 feature 也可能是 bug：

• Feature：允许"干跑"来预热缓存
• Bug：如果配置错误， silently 丢失数据

建议：在 host code 中添加断言检查 loop_sel < loop_cnt。

与系统其他部分的交互

上游依赖

下游依赖

系统集成视图

性能特征

理论吞吐量

资源消耗（估计）

基于 VE2802 器件的综合经验：

注：实际数值因 HLS 版本和约束而异，请以实际综合报告为准。

时序收敛

• 目标时钟：3.2 ns（约 312.5 MHz）
• HLS 估算：通常能达到 ~2.5 ns（有 22% 余量）
• 关键路径通常在 m_axi 接口的地址生成逻辑

扩展与修改指南

场景 1：修改通道数（如 2048 通道）

需要修改的文件：

1. channelizer_dma_src.h：更新 NCHAN
2. channelizer_dma_snk.h：更新 NFFT（如果需要）
3. 重新运行 HLS 综合和导出

注意：这会改变 DEPTH 计算，可能影响 URAM 用量。

场景 2：支持更多循环次数

当前限制：LOOP_TRIPCOUNT max=8

修改步骤：

1. 更新 pragma：max=16 或更大
2. 确保 URAM 深度足够（当前设计不受循环次数影响，因为是回放模式）
3. 重新综合

场景 3：添加 TLAST 信号

如果需要精确的帧边界指示：

// 修改接口声明
#pragma HLS interface axis port=sig_o  // 默认无 TLAST

// 改为显式 struct
typedef struct {
    ap_uint<128> data;
    ap_uint<1>   last;
} axis_word;

#pragma HLS interface axis port=sig_o

影响：需要同步修改 AIE 侧和消费者 kernel 的接口定义。

总结

dma_endpoint_kernels 是 Channelizer 系统的数据门户，其设计体现了异构计算中数据搬运的核心原则：

1. 带宽匹配：通过多路并行流满足 2 GSPS 需求
2. 格式转换：在 PL 中完成多相分解，释放 AIE 算力
3. 延迟隐藏：DATAFLOW 架构重叠 I/O 和计算
4. 资源优化：URAM 大容量缓冲降低功耗

对于新加入团队的工程师，理解这个模块的关键在于把握数据如何在不同子系统之间流动和变形——从 DDR 的线性存储，到 PL 的多相并行，再到 AIE 的 SIMD 计算，每一步转换都有其物理和算法上的必然性。