Module 18：面向 Xbox GDK

在没有官方 Rust Xbox console target 的条件下，将 Rust 推理核心封装为 C ABI staticlib/cdylib，并由 C++ GDK host 完成进程入口、D3D12 device 创建与注入。

18.1问题：没有官方 Rust Xbox console target

Windows PC 上，Rust 的x86_64-pc-windows-msvctarget 可以直接构建可执行程序。Xbox console 属于 GDK 平台：process entry、应用打包、设备创建和运行时库由 GDK 管理；Rust 官方没有提供可直接使用的 Xbox console target。

xinfer 采用清晰的宿主划分：Rust core 编译为 C ABI library，C++ GDK host 负责平台入口和 device creation。这样既保留 Rust 侧的模型、DirectML 与采样实现，又让平台相关代码留在 GDK 支持最完整的 C++ 工程中。

18.2FFI 边界：Rust core 作为 C ABI library

xinfer-ffi同时构建为：

• staticlib：供 C++ GDK host 链接；
• cdylib：供 PC 工具 / Python ctypes 测试加载。

C ABI 中暴露的核心函数以crates\xinfer-ffi\include\xinfer.h为准：

const char* xinfer_version(void);

int xinfer_create(const char* model_dir,
                  int stream_layers,
                  XinferContext** out_ctx);

int xinfer_create_with_device(void* d3d12_device,
                              void* command_queue,
                              const char* model_dir,
                              int stream_layers,
                              XinferContext** out_ctx);

int xinfer_generate(XinferContext* ctx,
                    const char* prompt_utf8,
                    const char* system_utf8,
                    int use_chat,
                    int max_tokens,
                    float temperature,
                    int top_k,
                    float top_p,
                    uint64_t seed,
                    XinferTokenCallback callback,
                    void* user_data);

const char* xinfer_last_error(const XinferContext* ctx);
void xinfer_free(XinferContext* ctx);

XinferContext是 opaque handle：C++ 只持有指针，不依赖 Rust 内部结构布局。由 Rust 分配的 context 必须用xinfer_free释放；xinfer_version返回静态字符串，不需要释放；callback 收到的 UTF-8 片段只在本次调用期间有效。

18.3安全 C ABI：错误码、opaque handle、no unwinding

跨语言边界的首要规则是：Rust panic 不能穿过 C ABI。xinfer-ffi在导出函数内部使用catch_unwind，把 panic 转换为XINFER_PANIC，普通错误则返回负数状态码。生成阶段的错误消息保存在 context 中，可通过xinfer_last_error查询；创建失败时 context 尚未建立，调用者应先检查返回码。

18.4Device injection：为什么不能用 DXGI？

Windows PC 上可以通过 DXGI 选择 adapter 并创建 D3D12 device；Xbox console 上不提供桌面 DXGI adapter 枚举。GDK host 使用D3D12XboxCreateDevice创建设备，再把ID3D12Device*和ID3D12CommandQueue*交给 Rust core。

DmlDevice::from_raw_pointers接收两个 raw COM pointer，并为 context 生命周期持有相应引用：

• ID3D12Device*
• ID3D12CommandQueue*

然后在这个 device 上创建 DirectML device：

18.5C++ GDK host：链接 Rust lib

C++ host 的职责集中在平台边界：

1. 创建 D3D12 device 和 command queue；
2. 调用xinfer_create_with_device创建推理 context；
3. 调用xinfer_generate，用 callback 接收 token 文本；
4. 退出时调用xinfer_free。

XinferContext* ctx = nullptr;
int rc = xinfer_create_with_device(device.Get(), queue.Get(),
                                   model_dir, stream_layers, &ctx);

rc = xinfer_generate(ctx, prompt, nullptr, 1, 64,
                     0.0f, 0, 1.0f, 42,
                     &OnToken, nullptr);

xinfer_free(ctx);

链接时需要处理 CRT 与 Rust staticlib 的系统依赖。当前 GDK desktop 验证路径使用/MD匹配 Rust 的动态 CRT，并链接bcrypt、ntdll、userenv、ws2_32、advapi32、dbghelp以及 windows-rs import library。

18.6用 GDK desktop toolchain 验证

没有 console dev kit 时，仍可用 GDK desktop toolchain 验证从 C++ host 到 Rust staticlib、device injection、真实推理的完整链路：

# 构建 Rust staticlib + C++ host
.\xbox\build_host.ps1

# 运行 host，创建 D3D12 device 并注入 Rust core
.\xbox\xinfer_host.exe models\Qwen2.5-0.5B-Instruct "What is 2 plus 2?"

验证输出示例：

xinfer (Xbox host) version 0.1.0
--- output ---
2 plus 2 is 4.
--------------

Lab 18从 C 调用引擎，再从 C++ host 调用

本实验检查同一 C ABI 的两个入口：

1. 用 Pythonctypes加载xinfer_ffi.dll，调用xinfer_create、xinfer_generate和xinfer_free。
2. 构建xbox\xinfer_host.exe，验证 C++ host 调用xinfer_create_with_device。

python crates\xinfer-ffi\tests\ctypes_smoke.py `
  target\release\xinfer_ffi.dll `
  models\Qwen2.5-0.5B-Instruct `
  "What is the capital of France?"

.\xbox\build_host.ps1
.\xbox\xinfer_host.exe models\Qwen2.5-0.5B-Instruct "Name three primary colors."

小结

本章说明了 xinfer 的 Xbox GDK 部署路径。Rust core 通过xinfer-ffi导出 C ABI，并同时构建为 staticlib 与 cdylib；C++ GDK host 负责 process entry、D3D12 device 与 command queue 创建，并通过xinfer_create_with_device把 raw COM pointer 注入 Rust。这个设计把平台职责和推理职责分离，也把 FFI 约束明确化：opaque handle、负数状态码、xinfer_last_error、panic 不跨边界、由分配方负责释放。当前已验证的路径包括 Python ctypes smoke test 和 GDK desktop host 的 end-to-end 运行；真正 console 分支还需要 GXDK 与 dev kit。