# GPU 设备标识查询工具 1.1.2

本源码包采用 MIT 许可证，仅许可此独立查询工具，不包括求解器 SDK、显卡驱动或第三方编译器。工具无网络功能、无签名私钥，不生成授权。工具默认输出 JSON，保留 --plain 和 --text 供脚本或人工查看。

## Linux 本机编译

需要 GCC 或 Clang、标准 C 库开发文件和对应 GPU 驱动。编译不需要
CUDA/MUSA/HIP/HCR/Level Zero/OpenCL SDK 头文件，运行通过动态加载系统驱动
查询设备。

```sh
cc -O2 -Wall -Wextra -Werror -fstack-protector-strong -D_FORTIFY_SOURCE=2 \
  -Wl,-z,relro,-z,now gpu_id.c -ldl -o opensparse-gpu-id
./opensparse-gpu-id --json --output gpu-ids.json
```

在目标 GPU 机器或 Slurm 分配到的 GPU 作业内运行，保持与求解器相同的设备可见性。报告保留前导零；网页只接受导入 JSON 文件，按报告顺序列出设备，勾选需要授权的卡。complete=false 表示查询失败，须先解决工具报错，不应据此购买授权。

## 跨平台构建

build.sh 使用 Zig 0.16.0 构建 Linux x86_64 / ARM64（glibc 2.17）以及 Windows x64。安装可信的 Zig 后设置 GPU_ID_ZIG 为它的可执行文件路径，再运行 bash build.sh。Windows 版面向 NVIDIA，尚待 Windows 实机验证。下载其他版本的编译器会改变构建结果，不能据此声称二进制完全相同。

## Intel 与砺算

`--backend intel` 通过 Level Zero（`libze_loader.so`）读取 Intel GPU 的 128 位
设备 UUID。Level Zero 按低字节在前返回 UUID，工具按高字节在前整理成
`00000000-0000-0003-0000-0000e20b8086` 这种与 PanguLU 授权一致的规范形式；
UUID 全零时按查询失败处理。

`--backend lisuan` 通过 Khronos OpenCL（`libOpenCL.so.1`）枚举砺算 GPU，读取
`CL_DEVICE_UUID_KHR` 并生成 `lisuan-` 前缀标识。当前砺算运行时未暴露非零
UUID 时，工具沿用 PanguLU OpenCL-lisuan 交付版的行为，输出全零 UUID 的
`lisuan-00000000-00000000-00000000-00000000`。

`build-sycl.sh` 与 `gpu_id_sycl.cpp` 是历史遗留的独立 SYCL 适配，仅供检查；
主工具的 Intel 路径不需要 oneAPI 头文件或 `icpx`。龙芯（OpenCL LACm）暂未加入。

## 输出与安全

--backend cuda|musa|hip|hcr|intel|lisuan 可以显式选择驱动；--plain 只显示标识。JSON schema 为 opensparse.gpu-ids.v1，包含设备型号、平台、PCI 地址和 License ID。工具不自动上传；将报告提交到商城时，ID 用于授权，平台类别仅用于匿名汇总，统计不关联账户或设备标识，商城不保存完整报告、型号或 PCI 地址。输出文件必须尚不存在。

NVIDIA 优先使用驱动读取的硬件串号，其他平台按当前 SDK 的 UUID / PCI 规则生成标识，HCR 使用 hc- 前缀，Intel 使用规范形式 UUID，砺算使用 lisuan- 前缀。此算法不能证明报告未被修改；授权校验由求解器库在实际硬件上执行。

## 本地模拟驱动检查

仅在 Linux 的临时目录中运行，不能将模拟驱动装入系统驱动目录。需要 Python 3 和 GCC：

```sh
GPU_ID_BINARY="$PWD/opensparse-gpu-id" python3 test_helper.py
```

模拟测试不替代目标硬件上的授权兼容性验证。源码包没有用户设备数据、内部逆向记录、签名密钥或管理权限。