Module 6：HLSL 与 Direct3D 12 编程模型

把 compute shader 写出来、编译出来、绑定资源、提交到 GPU，并正确处理资源状态与同步。

6.1HLSL compute shader 的最小形态

Compute shader 是由 GPU 执行的程序单元。它的入口函数虽然通常命名为 main，但参数不来自命令行；数据来自绑定到 SRV/UAV/CBV 槽位的 GPU 资源，执行规模由 CPU 侧记录的 dispatch 命令决定。

// shaders/affine.hlsl：out[i] = in[i] * 2 + 1
StructuredBuffer<float> In  : register(t0);
RWStructuredBuffer<float> Out : register(u0);

cbuffer Params : register(b0)
{
    uint count;
};

[numthreads(64, 1, 1)]
void main(uint3 tid : SV_DispatchThreadID)
{
    uint i = tid.x;
    if (i < count)
        Out[i] = In[i] * 2.0f + 1.0f;
}

[numthreads(64,1,1)] 表示每个 threadgroup 有 64 个线程。CPU 侧 dispatch $G$ 个 group 时，最多启动 $64G$ 个线程；每个线程用 SV_DispatchThreadID 得到全局编号，并用边界检查处理 $N$ 不能被 64 整除的情况。

6.2资源类型：SRV、UAV 与 raw byte access

HLSL 中常见的 buffer 类型可按访问权限和寻址方式区分：

在 HLSL binding 语法中，t0 通常表示 SRV（read-only），u0 表示 UAV（read/write）， b0 表示 constant buffer：

StructuredBuffer<float> A : register(t0);      // SRV
ByteAddressBuffer W       : register(t1);      // SRV, raw bytes
RWStructuredBuffer<float> Out : register(u0);  // UAV
cbuffer Params : register(b0) { uint M; uint K; uint N; };

6.3groupshared memory 与 barrier

groupshared 是同一 threadgroup 内线程共享的片上内存（AMD 文档中常称 LDS）。它适合归约、tile 缓存和线程间交换临时结果。由于同组线程不会在每条指令后自动同步，写入后被其他线程读取前必须显式使用 barrier。典型模式如下：

1. 每个线程计算一个 partial result；
2. 写入 groupshared 数组；
3. 调用 GroupMemoryBarrierWithGroupSync()；
4. 再做树形归约。

#define TG 64
groupshared float partials[TG];

[numthreads(TG, 1, 1)]
void main(uint3 lid : SV_GroupThreadID) {
    uint t = lid.x;
    partials[t] = local_sum;
    GroupMemoryBarrierWithGroupSync();

    for (uint s = TG / 2; s > 0; s >>= 1) {
        if (t < s) partials[t] += partials[t + s];
        GroupMemoryBarrierWithGroupSync();
    }
}

6.4编译 Shader：FXC / SM5 与 DXC / SM6

HLSL 源码不能直接提交给 GPU 执行，必须先编译为驱动可接受的 shader 字节码。Windows 生态中常见两条路线：

项目源码中的 ComputeKernel 当前调用 D3DCompile，目标为 cs_5_0。因此 f16 权重路径使用 SM5 的 f16tof32：

uint packed = W.Load(byte_offset);
float w0 = f16tof32(packed & 0xFFFF);
float w1 = f16tof32(packed >> 16);

这使当前代码可在 FXC/SM5 路径下运行。现代 D3D12 shader 通常由 DXC 编译为 DXIL；若后续要使用 wave intrinsics、native half arithmetic 或更完整的 SM6 优化，迁移到 DXC/SM6 更合适。

6.5D3D12 核心对象：从 device 到 fence

D3D12 是显式 API。程序需要创建资源和管线对象，向 command list 记录命令，把 command list 提交到 queue，并用 fence 等待 GPU 完成：

6.6资源状态与 barrier：Transition vs UAV

D3D12 要求程序明确资源状态：copy source、copy destination、shader resource 或 unordered access 等。状态与实际访问不一致时，调试层会报告错误；在更严重的情况下，驱动可能移除设备。

例如，前一个 dispatch 写入 activation 或 KV cache，后一个 dispatch 立即读取同一资源时，必须保证写入已完成且资源状态正确。源码中的 DmlBuffer::ensure_state 负责按需记录 transition barrier；Executor::uav_barrier() 负责同一 command list 内 UAV 写后的可见性和顺序。

6.7Root signature：shader 如何看到资源？

Shader 中的 register(t0)、register(u0) 只是逻辑槽位；运行时还必须说明这些槽位如何映射到实际 GPU 资源。Root signature 描述 compute pipeline 可访问的资源布局。xinfer 的 ComputeKernel 为 custom kernel 构造的布局主要包括：

• root constants：少量参数，如 $M,K,N$、count、offset；
• root descriptors：直接把 buffer GPU virtual address 绑定给 shader；
• descriptor tables：更适合大量资源，本教程前半部分暂不重点使用。

小结

本章把 HLSL compute 与 D3D12 执行对象连接起来。HLSL shader 通过 SV_DispatchThreadID、SV_GroupID 与 SV_GroupThreadID 定位数据，通过 SRV/UAV/constant buffer 访问资源；groupshared 与 GroupMemoryBarrierWithGroupSync() 用于同一 threadgroup 内的协作归约。xinfer 当前的 ComputeKernel 使用 FXC/SM5 编译 cs_5_0，而现代 D3D12 shader 通常由 DXC 生成 DXIL。D3D12 侧的核心工作是创建 device、buffer、root signature 与 PSO，记录 dispatch，维护 transition/UAV barrier，并通过 fence 等待完成。

Lab 6写并 dispatch 一个 affine kernel

Lab 6 对应仓库中的 shaders/affine.hlsl。目标是完成一个最小 GPU compute path：

1. 创建输入 buffer 与输出 buffer；
2. 把输入数据上传到 GPU；
3. 编译 HLSL compute shader；
4. 创建 root signature 和 compute pipeline state；
5. 绑定 count、SRV、UAV；
6. dispatch；
7. 把结果读回 CPU，验证 $out[i]=in[i]\times2+1$。

这条路径包含 custom HLSL kernel 的必要步骤，也是后续 RMSNorm、RoPE、attention、linear 和 argmax kernel 的最小原型。