NOTES

模块 003：HLS/PL 算子

HLS 目录保存多个独立 C/C++ kernel。每个 kernel 以 HLS pragma 声明若干 `m_axi` DDR 端口与 `s_axilite` 控制端口；testbench 或未来 PS scheduler 负责准备缓冲区并启动 kernel。

Qwen2.5/modules/003_hls_pl_kernels.md 2026-07-13 约 10 分钟阅读

模块边界

HLS 目录保存多个独立 C/C++ kernel。每个 kernel 以 HLS pragma 声明若干 m_axi DDR 端口与 s_axilite 控制端口；testbench 或未来 PS scheduler 负责准备缓冲区并启动 kernel。

flowchart LR
    Fixture[fixture / DDR buffers] -->|m_axi| K[独立 HLS kernel]
    Ctrl[AXI-Lite control] --> K
    K -->|m_axi| Out[输出 buffers]
    K -->|done/status| Ctrl

流程或关系图。

已有 kernel

目录 / 顶层函数	输入	控制参数	输出	算法行为
`layer0_q6k_down_projection/layer0_q6k_down_projection`	4 行以内 Q6_K payload、4864 个 F32 输入	行数、行字节数	每行一个 F32	解码每个 256-lane Q6_K block，计算 `ffn_down` 选定行 dot。
`smollm2_attention_core/smollm2_attention_core`	masked scores、V	`seq_len`，最大 8	probs、context、checksum	对每个 query 做稳定 softmax，再与 V 相乘。
`smollm2_qkv_rope_projection/smollm2_qkv_rope_projection`	hidden、norm 权重、Q/K/V quant rows	position、qtype、row bytes、epsilon、RoPE base	Q/K RoPE、V	RMSNorm 后执行 Q5_0(Q/K) 和 Q5_1(V) 投影，旋转 Q/K。
`smollm2_mlp_full_layer/smollm2_mlp_full_layer`	residual、norm、gate/up Q5_0 rows、down Q5_K rows	输出行数、量化类型、stride、epsilon	residual output	`RMSNorm -> gate/up dot -> SiLU(gate)*up -> down dot -> residual add`。
`smollm2_lm_head_streaming_topk/smollm2_lm_head_streaming_topk`	576 F32 hidden、Q8_0 lm_head rows	row limit、stride、tile、requested K	top token、row、score	16 行一批扫描词表并维护 top-5。
`q25rt_i8_matvec_tile/q25rt_i8_matvec_tile`	int8 weights、int8 activation	rows、in_dim、input/output stride	int32 dots	最多 16 行的 int8 点积 tile。
`q25rt_i8_lm_head_paged/q25rt_i8_lm_head_paged`	int8 page weights、int8 activation、page token base	page count、weight/output stride	每行 dot、top-4、status	最多 16 页，每页 16 行的 int8 lm_head 扫描。
`smollm2_quant_matvec_common_h0_q25_hls_066/smollm2_quant_matvec_common_h0_rowblock`	weight/activation 保留参数	qtype、block/row 描述	status、partial output	提供 Q8_0/Q5_0/Q5_1/Q5_K/Q4_K 的共用 ABI、block 尺寸查询和 fixture 输出。

HLS 端口约定

端口类型	谁提供	数据
`m_axi` 输入	testbench 或 PS	tensor 行、F32/int8 activation、norm 权重、页索引。
`m_axi` 输出	kernel 写入	F32 向量、int32 dot、top-k 数组、状态字。
`s_axilite` 标量	testbench 或 PS	行数、维度、stride、位置、qtype、epsilon、top-k 长度。
`s_axilite return`	kernel	启动、完成和空闲控制。

HLS 目录覆盖表

ZCU106/hls/ 中的目录按以下功能族组织。一个功能族内可能有 selected-row、full、CSim、cosim 或不同量化格式的独立实现；它们都以 fixture 和 HLS 参数为输入。

功能族	目录	模块功能
embedding 与 token bridge	`token_embd_f32_lookup`、`token_embd_q8_0_lookup`、`token_step_q8_0_top1`、`token_step_rmsnorm_q8_0_top1`、`smollm2_embedding_rmsnorm_full_vector`	从选定 embedding 行读取/解码 hidden，或接 RMSNorm 与候选行 top1。
QKV 与 RoPE	`layer0_q5_projection`、`smollm2_qkv_rope_projection`、`smollm2_qkv_rope_projection_reduced_20260629`、`m1i_exact_q5_q8_vecdot_csim`、`m1i_exact_qkv_selected_rows_csim`、`m1i_exact_qkv_selected_rows_csim_fix`	解码 Q5 投影行，计算 Q/K/V，或针对选定行验证 RoPE 之前/之后的数值。
attention	`smollm2_attention_core`、`smollm2_attention_core_headwise_cosim_20260629`、`smollm2_attention_integrated_20260629`、`smollm2_attention_output_projection_residual`、`m1i_attention_output_projection_residual_small_core`、`m1i_ref004b_attn_context_selected_chain_core`、`m1i_ref004b_f16qk_score_core`、`m1i_ref004b_f16qk_score_selected_core`、`m1i_ref004b_f16qk_score_qtile_fullkey_core`、`m1i_ref004b_value_mix_selected_core`、`m1i_ref004b_value_mix_qtile_fullkey_core`、`m1i_ref004b_vpost_value_mix_selected_core`、`m1i_ref004b_vpost_value_mix_qtile_fullkey_core`	计算 score、softmax、value mix、attention output projection 与 residual 的不同粒度。
MLP 与 down projection	`layer0_q5k_down_projection`、`layer0_q6k_down_projection`、`layer0_q6k_down_projection_full`、`layer2_q4k_down_projection`、`layer2_q4k_down_projection_full`、`smollm2_mlp_full_layer`	处理 Q5_K/Q6_K/Q4_K down projection，或完成一层 MLP 的 norm、gate、up、SiLU、down、residual。
通用量化 matvec	`smollm2_quant_matvec_common_h0_q25_hls_066`	定义并扩展 Q8_0/Q5_0/Q5_1/Q5_K/Q4_K row-block 入口和 fixture。
int8 runtime tile	`q25rt_i8_matvec_tile`、`q25rt_i8_matvec_batch_tile`	计算 int8 activation 与 int8 权重的单 tile 或 batch tile。
lm_head 与 top-k	`lm_head_int4_top1`、`smollm2_lm_head_streaming_topk`、`smollm2_lm_head_tiled_topk`、`smollm2_lm_head_axi_vip_probe_20260629`、`q25rt_i8_lm_head_paged`、`q25_hls_065_20260630`	对量化词表行打分，计算 top1/top-k，或验证 paged lm_head 的内存访问。
cache 与 W8A8	`smollm2_kv_cache_handoff_20260629`、`m1i_w8a8_rmsnorm_csim`、`m1i_w8a8_rmsnorm_opt_candidate`	交接 KV cache buffer，或计算/试验 W8A8 RMSNorm。
AXI memory harness	`hls_cosim_m_axi_reproducer`	复现和测试多端口/stride/ap_memory 的 AXI 访问配置。

算子之间的关系

这些 kernel 反映 transformer token step 的计算片段，但当前各自独立：

flowchart LR
    E[embedding / RMSNorm] --> Q[QKV + RoPE]
    Q --> A[attention core]
    A --> O[output projection / residual]
    O --> M[MLP full layer]
    M --> N[final norm]
    N --> L[lm_head / top-k]
    R[row-block matvec] -.可供 QKV、MLP、lm_head 复用.-> Q
    R -.-> M
    R -.-> L

流程或关系图。

上述箭头表示模型计算顺序或可复用关系；当前仓库没有一个 PS 程序把这些 kernel 在一次 UART 请求内全部串起来。