HIPRT

本仓库保留 HIPRT 项目名称以及 hiprt* 对外 API 命名，当前主实现已收敛到 CUDA-only 后端。

• 保留：
  • hiprt.h
  • hiprtew.h
  • hiprtCreateContext
  • hiprtBuildTraceKernels
  • hiprtBuildTraceKernelsFromLinkedBundle
• 已移出当前主构建链：
  • AMD HIP runtime 主路径
  • ROCm toolchain 依赖
  • hipcc
  • 历史 HIP loader 主路径
• 当前阶段目标：
  • 优先确保纯 CUDA 基线具备可编译、可运行、可复现的稳定状态
  • 在此基础上再推进 MACA + cu-bridge 适配与扩展

hiprt/hiprtew.h 仍保留为兼容入口头，但当前实现已不再承担运行时动态加载器的职责。

git clone https://github.com/GPUOpen-LibrariesAndSDKs/HIPRT.git
cd HIPRT
git submodule update --init --recursive

说明：

• 默认推荐使用 CMake + Ninja。

建议优先直接使用仓库脚本：

./scripts/build.sh

在环境满足时，脚本会自动接入：

• ccache
• mold
• Ninja

如需手动指定常用构建参数，可直接设置环境变量：

CUDA_ARCHITECTURES=89 BUILD_TYPE=Release ./scripts/build.sh

等价的原生 CMake 调用为：

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j

按照当前仓库约定，功能正确性验证不应依赖历史 JIT cache 结果。回归前建议先清理测试过程中生成的 scripts/cache/：

cd scripts
rm -rf cache
./unittest.sh

建议先执行非性能功能测试，性能测试另行执行。

为保持首页聚焦，主要 public API 的主机侧用法、对象生命周期，以及 trace-kernel 三条构建路径，已整理到单独的中文指南：

• 主要 API 使用指南（中文）

指南重点覆盖：

• hiprtCreateContext / hiprtDestroyContext
• hiprtCreateGeometry / hiprtBuildGeometry
• hiprtCreateScene / hiprtBuildScene
• hiprtCreateFuncTable / hiprtSetFuncTable
• hiprtBuildTraceKernels
• hiprtBuildTraceKernelsFromBitcode
• hiprtBuildTraceKernelsFromLinkedBundle

• 纯 CUDA 基线：
  • 优先保证 ./scripts/build.sh + cd scripts && ./unittest.sh 可稳定通过
  • source-based trace kernel 使用 hiprtBuildTraceKernels(...)
  • 已有可重定位 PTX/CUBIN 时，可使用 hiprtBuildTraceKernelsFromBitcode(...)
• MACA + cu-bridge：
  • 当前推荐使用 precompiled / linked-bundle 路径
  • 显式 public API 为 hiprtBuildTraceKernelsFromLinkedBundle(...)
  • 相关限制与状态说明见下列文档

在验证 trace kernel / runtime JIT 行为时，应优先避免复用旧缓存；必要时请显式关闭 cache，或切换到新的临时 cache 目录。

• 主要 API 使用指南（中文）
• CUDA-only 编译与改造说明
• bitcode / precompile / bake_kernel 当前状态
• 当前 main 分支 MACA 修复说明
• main 与 upstream 差异分类
• mxcc offline 进展
• mxcc offline 计划

以下图片展示了当前仓库与 HIPRTSDK 联调后的实际结果：

• CUDAToolkit 是主构建前提。
• CMAKE_CUDA_ARCHITECTURES 可通过 cache 或脚本环境变量指定。
• 单测默认参与构建；如需关闭可使用 BUILD_TESTS=OFF ./scripts/build.sh 或 -DNO_UNITTEST=ON。
• 构建产物默认输出到 dist/bin/<Config>/。
• 可选 bitcode / precompile 开关：
  • HIPRT_ENABLE_BAKE_KERNEL=ON
  • HIPRT_ENABLE_BITCODE=ON
  • HIPRT_ENABLE_PRECOMPILED_TRACE_KERNEL=ON

当前测试主要分为三类：

1. HiprtTests：基础功能覆盖
2. ObjTestCases：网格与场景相关功能
3. PerformanceTestCases：性能相关测试

常用入口如下：

• cd scripts && ./unittest.sh
• cd scripts && ./unittest_perf.sh

• Resolve compiler warnings.
• Use lower camel case for variable names (e.g., nodeCount) and upper camel case for constants (e.g., LogSize).
• Separate functions by one line.
• Use prefix m_ for non-static member variables.
• Do not use static local variables.
• Do not use void for functions without arguments (leave it blank).
• Do not use blocks without any reason.
• Use references instead of pointers if possible.
• Use bit-fields instead of explicit bit masking if possible.
• Use nullptr instead of NULL or zero.
• Use using instead of typedef.
• Use C++-style casts (e.g., static_cast) instead of C-style cast.
• Add const for references and pointers if they are not being changed.
• Add constexpr for variables and functions if they can be constant in compile time (do not use #define if possible).
• Use if constexpr instead of #ifdef if possible.
• Throw std::runtime_error with an appropriate message in case of failure in the core and catch it in hiprt.cpp.

• Use std::string instead of C strings (i.e., char*) and avoid C string functions as much as possible.
• Use std::cout and std::cerr instead of printf.
• Do not assign char8_t (or std::u8string) to char (or std::string). They will not be compatible in C++20.

• Use std::ifstream and std::ofstream instead of FILE.
• Use std::filesystem::path for files and paths instead of std::string.

• Use the in-class initializer instead of the default constructor.
• Use the keyword override instead of virtual (or nothing) when overriding a virtual function from the base class.
• Use std::optional instead of pointers for optional parameters.
• A base class destructor should be either public and virtual, or protected and non-virtual.
• Implement the customized {copy/move} {constructor/assignment operator} if an user-defined destructor of a class is needed, or remove them using = delete.

• When we update the master branch, we need to update the version number of hiprt in version.txt.
• If there is a change in the API, you need to update minor version.
• If the major and minor versions matches, the binaries are compatible.
• Each commit in the master should have a unique patch version.