Module 10：Phase 1 — 硬件抽象层（HAL）

把模型代码从 D3D12 细节中解耦出来：Device / Buffer trait、状态跟踪 buffer、Executor、通用 operator wrapper、compute kernel 路径与 GPU timer。

10.1为什么需要 HAL？

如果 xinfer-model 直接操作 ID3D12Resource、root signature 和 descriptor heap，模型代码会被 Direct3D 12 的对象生命周期、资源状态和绑定规则占据。后续接入 Xbox host-created device、尝试其他 backend，或在测试中使用 CPU reference，都会被平台细节牵连。

HAL（Hardware Abstraction Layer）的作用是给模型层提供较小且稳定的能力接口。模型层依赖 Device / Buffer 等 trait；D3D12/DirectML、未来的其他 backend 或 CPU fallback 负责实现这些 trait。

10.2Device / Buffer trait 的最小设计

Phase 1 中，xinfer-backend 的最小接口保持克制：Buffer 只暴露字节数；Device 负责分配、上传和下载 buffer。这个接口已经足以支撑权重加载、activation buffer、中间结果和 readback，同时不泄露 D3D12 类型。

pub trait Buffer {
    fn size_in_bytes(&self) -> usize;
}

pub trait Device {
    type Buffer: Buffer;

    fn alloc(&self, shape: &Shape, dtype: DType) -> Result<Self::Buffer>;
    fn upload(&self, data: &[u8], shape: &Shape, dtype: DType) -> Result<Self::Buffer>;
    fn download(&self, buffer: &Self::Buffer) -> Result<Vec<u8>>;
}

一个重要细节是：HAL 不直接暴露 D3D12 类型。模型层只需要知道“这是一个 buffer”，而不需要知道它背后是 ID3D12Resource、Vulkan buffer 还是 CPU vector。

10.3状态跟踪 GPU buffer：自动 transition barrier

D3D12 的资源有显式状态：同一个 buffer 在不同时间可能是 COPY_DEST、COPY_SOURCE、 NON_PIXEL_SHADER_RESOURCE 或 UNORDERED_ACCESS。如果状态不对，GPU 行为未定义，调试层会报错。

因此 DmlBuffer 除了保存 ID3D12Resource，还保存当前状态：

pub struct DmlBuffer {
    pub resource: ID3D12Resource,
    pub size: u64,
    pub shape: Shape,
    pub dtype: DType,
    state: Cell<D3D12_RESOURCE_STATES>,
}

当 custom kernel 需要把 buffer 作为 SRV 读取时，ComputeKernel::dispatch_grid 会调用 ensure_state(..., NON_PIXEL_SHADER_RESOURCE)；作为 UAV 写入时调用 ensure_state(..., UNORDERED_ACCESS)。download_buffer 会把源 buffer 转到 COPY_SOURCE，upload_buffer 则先在 default heap 中创建 COPY_DEST，拷贝后转为 UNORDERED_ACCESS。如果当前状态已经匹配，ensure_state 不记录 barrier；否则写入 transition barrier 并更新状态。

10.4One-shot Executor：封装 command list + fence

D3D12 提交命令需要 command allocator、command list、command queue、fence 和 event 协同工作。若每个调用点都直接操作这些对象，代码会重复，并且容易遗漏 close、signal、wait 或 reset。

crates\xinfer-dml\src\resource.rs 将它们封装为 Executor：

let mut exec = dev.executor()?;
kernel.dispatch(&mut exec, ...)?;
exec.submit_and_wait()?;
exec.reset()?;

Executor::submit_and_wait 关闭 command list、提交到 queue、递增 fence 并阻塞等待完成；reset 复用 allocator 和 list；uav_barrier 用于在同一 command list 中排序相互依赖的 UAV 写读。后续把一个 decoder layer 的多个 dispatch 合并提交时，这个封装是关键基础。

10.5通用 DirectML operator wrapper 与 compute-kernel path

Phase 1 中保留两条执行路径，分别服务于 DirectML 已提供的 operator 和项目自写 kernel：

• DmlOperator：封装 DirectML operator 的 create / compile / initialize / bind / dispatch。
• ComputeKernel：封装自写 HLSL compute shader 的 root signature / PSO / root descriptors / dispatch。

二者都向 D3D12 command list 记录工作，但绑定方式不同。DmlOperator 需要 DirectML binding table、temporary resource 与 persistent resource；ComputeKernel 使用 root constants 以及 SRV/UAV root descriptors，适合 RMSNorm、RoPE、SwiGLU、attention 等自写 HLSL kernel。

10.6GPU timestamp profiling

CPU wall-clock 包含命令提交、驱动调度、queue 排队和等待开销。若要测量一段 GPU 工作本身的耗时，需要在 command stream 中写 timestamp query。GpuTimer 的实现包含两个 query、一段 readback buffer，并使用 command queue 的 timestamp frequency 换算毫秒。D3D12 timestamp 的基本流程是：

1. 创建 timestamp query heap；
2. 在 command list 中写 begin timestamp；
3. 记录被测 dispatch；
4. 写 end timestamp；
5. resolve query data 到 readback buffer；
6. 用 queue timestamp frequency 换算毫秒。

Lab 10实现 upload / download + GPU timer

本实验对应 Phase 1。目标是通过 HAL 完成 buffer round-trip，并用 GPU timestamp 测量一段已记录的 GPU 工作。

1. 实现 DmlDevice::alloc_buffer。
2. 实现 DmlDevice::upload_buffer：用 upload heap → default heap。
3. 实现 DmlDevice::download_buffer：default heap → readback heap。
4. 实现 Executor：record、submit、wait、reset。
5. 实现 GpuTimer，给一个 GEMM 或 affine kernel 计时。

# 验收测试
cargo test -p xinfer-dml --test hal

# 期望包含：
buffer_roundtrip ... ok
gpu_timer_reports_nonnegative ... ok

小结

Module 10 将 Phase 0 的 GPU 闭环提升为 HAL：xinfer-backend 定义 Device / Buffer trait，xinfer-dml 以 DmlBuffer 跟踪 D3D12 resource state，以 Executor 统一 command list 与 fence，以 DmlOperator 和 ComputeKernel 分别封装 DirectML operator 与 HLSL kernel。GpuTimer 提供 GPU 侧时间戳，为后续定位 submission、readback 和 kernel 耗时奠定基础。