chipStar
v1.2.1
chipStar 能够在支持 SPIR-V 作为设备中间表示的平台上编译和运行 HIP 和 CUDA 应用程序。它支持 OpenCL 和零级作为低级运行时替代方案。
用户文档
开发者文档
（不）支持的功能列表
chipStar 最初是通过结合（现已废弃的）HIPCL 和 HIPLZ 项目中完成的原型设计工作而构建的。
如果您希望在学术出版物中引用chipStar，请在讨论 OpenCL 后端时参考 HIPCL 海报摘要和/或在提及零级后端时参考 HIPLZ 会议论文。 chipStar的核心开发人员正在撰写集成chipStar项目的正式文章，但正在进行中。
ChipStar这个名字来源于c uda和hip ， Star一词的意思是星号，是典型的shell通配符，表示让“CUDA和HIP应用程序到处运行”的意图。该项目以前称为 CHIP-SPV。
以下库已通过 MKL 移植到 Intel GPU 上：
hipBLAS（可以通过添加-DCHIP_BUILD_HIPBLAS=ON来构建为chipStar的一部分）
hipFTT（可以通过添加-DCHIP_BUILD_HIPFTT=ON来构建为chipStar的一部分）
髋解算器
臀部CUB
以下库已被移植并且应该可以在任何平台上运行：
洛克兰德
罗克PRIM
如果您需要的库尚未受支持，请打开一个问题，说明您需要哪些库以及您正在尝试构建什么应用程序。
迄今为止，chipStar 已使用以下应用程序进行了测试：
libCEED 我们的分支包含一些解决方法。
GAMESS 源代码不公开。
HeCBench CUDA 基准测试。
最快的入门方法是使用预构建的 Docker 容器。请参阅 Docker README 如果您想自己构建所有内容，可以按照详细的入门指南
虽然chipStar 1.1已可用于成功运行各种大型HPC应用程序，但它仍处于严重开发模式，存在大量已知问题和未实现的功能。还有一些已知的低性能优化仍有待完成。然而，我们认为chipStar已经准备好进行更广泛的测试，并欢迎社区以可重现的错误报告和高质量拉取请求的形式做出贡献。
1.1、1.0 和 0.9 的发行说明。
Cmake >= 3.20.0
Clang 和 LLVM 17（Clang/LLVM 15 和 16 也可能有效）
例如，可以通过添加 LLVM 的 Debian/Ubuntu 存储库并安装软件包“clang-17 llvm-17 clang-tools-17”来安装。
为了获得最佳结果，请从chipStar LLVM/Clang 分支安装Clang/LLVM，该分支具有LLVM 上游项目中尚未包含的修复程序。请参阅下文，了解构建和安装修补版本的脚本化方法。
来自与 LLVM 主要版本匹配的分支的 SPIRV-LLVM-Translator：（例如 LLVM 17 的 llvm_release_170）、llvm-spirv。
确保构建的 llvm-spirv 二进制文件安装到与 clang 二进制文件相同的路径中，否则 clang 可能会找到并使用不同的 llvm-spirv，从而导致错误。
建议使用 LLVM 的chipStar 分支，它有一些补丁尚未上传到上游。为此，您可以使用chipStar存储库中包含的脚本：
./scripts/configure_llvm.sh 用法： ./configure_llvm.sh --version <版本> --install-dir <目录> --link-type static（默认）/动态 --only-necessary-spirv-exts <on|off> --binutils- header-location <路径>--版本：LLVM 版本 15、16、17、18、19 --install-dir: 安装目录 --link-type：静态或动态（默认：静态） --only-necessary-spirv-exts：打开或关闭（默认值：关闭） --binutils-header-location：binutils 标头的路径（默认值：空） ./scripts/configure_llvm.sh --version 17 --install-dir /opt/install/llvm/17.0cd llvm-project/llvm/build_17 make -j 16<sudo> 进行安装
或者您可以手动执行以下步骤：
git克隆--深度1 https://github.com/CHIP-SPV/llvm-project.git -bchipStar-llvm-17cd llvm-project/llvm/projects git clone --depth 1 https://github.com/CHIP-SPV/SPIRV-LLVM-Translator.git -bchipStar-llvm-17cd ../..# DLLVM_ENABLE_PROJECTS="clang;openmp" OpenMP 是可选的，但有很多应用程序使用它# DLLVM_TARGETS_TO_BUILD 通过仅构建必要的 CPU 主机目标来加速编译# CMAKE_INSTALL_PREFIX 安装位置LLVMcmake -S llvm -B 构建 -DCMAKE_BUILD_TYPE=发布 -DLLVM_ENABLE_PROJECTS="clang;openmp" -DLLVM_TARGETS_TO_BUILD=X86 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm-17 make -C build -j8 全部安装
OpenCL 2.0 或 3.0 驱动程序至少支持以下功能：
粗粒度缓冲区共享虚拟内存 (SVM)
SPIR-V 输入
通用地址空间
程序范围变量
根据编译的 CUDA/HIP 应用程序，可能需要进一步的 OpenCL 扩展或功能。例如，为了支持 warp-primitives，OpenCL 驱动程序还应支持其他子组功能，例如随机播放、选票和 cl_intel_required_subgroup_size。
英特尔计算运行时或 oneAPI
oneAPI级别零加载器
对于 HIP-SYCL 和 HIP-MKL 互操作性：oneAPI
您可以下载并解压最新发布的源码包或通过git克隆开发分支。我们的目标是保持main开发分支的稳定，但它在开发周期中可能会出现稳定性问题。
要从 Github 克隆源：
git 克隆 https://github.com/CHIP-SPV/chipStar.gitcdchipStar git 子模块更新 --init --recursive
mkdir build && cd build# LLVM_CONFIG_BIN 是可选的，如果 LLVM 可以在 PATH 中找到，或者如果不使用 version-sufficed# 二进制文件（例如 llvm-config-17）cmake ..
-DLLVM_CONFIG_BIN=/path/to/llvm-config
-DCMAKE_INSTALL_PREFIX=/路径/到/安装
使所有 build_tests 安装 -j8 |您还可以通过添加-DCHIP_BUILD_HIPBLAS=ON来编译并安装 hipBLAS
注意：如果您没有 libOpenCL.so（例如来自ocl-icd-opencl-dev包），但仅安装了 libOpenCL.so.1，则 CMake 无法找到它并禁用 OpenCL 后端。此问题描述了一种解决方法。
要构建与 ARM Mali G52 GPU 一起使用的chipStar，请使用以下步骤：
如上所述构建 LLVM 和 SPIRV-LLVM-Translator
使用 -DCHIP_MALI_GPU_WORKAROUNDS=ON cmake 选项构建chipStar
有一些限制 - 使用双精度类型的内核将无法工作，并且使用子组的内核可能无法工作。
请注意，chipStar 依赖于 ARM 提供的专有 OpenCL 实现。我们已经成功地在 Odroid N2 设备上编译并运行了chipStar，使用 Ubuntu 22.04.2 LTS，驱动程序版本为 OpenCL 3.0 v1.r40p0-01eac0。
要构建与 PowerVR GPU 一起使用的chipStar，可以遵循默认步骤。针对 PowerVR 的 OpenCL 实现中的问题应用了自动解决方法。
有一些限制：使用双精度类型的内核将无法工作，使用子组的内核可能无法工作，您还可能遇到意外的 OpenCL 错误，例如 CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST 和其他问题。
请注意，chipStar 依赖于 Imagination Technologies 提供的专有 OpenCL 实现。我们使用 VisionFive2 的预构建 Debian 映像 202403、驱动程序版本 1.19，成功地在 VisionFive2 设备上编译并运行了chipStar。其他 SBC 可能需要额外的解决方法。
有一个脚本check.py可用于运行单元测试并过滤掉不同平台的已知失败测试。其用法如下。
BUILD_DIR={构建目录的路径。确保 build_tests 目标已构建}
后端={opencl/level0}
^ 您希望测试哪个后端/驱动程序/平台：“opencl”= Intel OpenCL 运行时，“level0”= Intel LevelZero 运行时
DEVICE={cpu,igpu,dgpu,pocl} # 要测试的设备类型。^ 这会选择预期的测试通过列表。 'igpu' 是 Intel Iris Xe iGPU，'dgpu' 是典型的最新 Intel dGPU，例如数据中心 GPU Max 系列或 Arc.export CHIP_PLATFORM=N # 如果系统上存在多个 OpenCL 平台，请选择使用哪一个您始终可以通过以下方式验证chipStar正在使用哪个设备：
CHIP_LOGLEVEL=信息 ./build/hipInfo python3 $SOURCE_DIR/scripts/check.py $BUILD_DIR $DEVICE $BACKEND
有关如何使用已安装的chipStar 构建CUDA/HIP 程序的说明，请参阅用户文档。
CHIP_BE=<opencl/level0> # 选择要使用的后端。如果零级和 OpenCL 都可用，则默认使用零级CHIP_PLATFORM=<N> # 如果系统上存在多个平台，则选择使用哪一个。默认为 0CHIP_DEVICE=<N> # 如果系统上存在多个设备，请选择使用哪一个。默认为 0CHIP_DEVICE_TYPE=<gpu/cpu/accel/fpga> 或空 # 选择要使用的设备类型。默认为空。CHIP_LOGLEVEL=<trace/debug/info/warn/err/crit> # 设置日志级别。如果在 RELEASE 中编译，则只有 err/crit 可用CHIP_DUMP_SPIRV=<ON/OFF(default)> # 将生成的 SPIR-V 代码转储到文件CHIP_JIT_FLAGS=<flags> # 附加 JIT 标志CHIP_L0_COLLECT_EVENTS_TIMEOUT=<N(默认 30 秒)> # 超时收集零级秒数eventsCHIP_L0_EVENT_TIMEOUT=<N（默认为 0） # 超时（以秒为单位），零级在超时之前应等待事件多长时间CHIP_SKIP_UNINIT=<ON/OFF（默认）> # 如果启用，则在程序终止时跳过chipStar 后端对象的未初始化CHIP_MODULE_CACHE_DIR=/ path/to/desired/dir # 模块/程序缓存目录。默认为$HOME/.cache/chipStar，如果不需要缓存，则设置为空字符串，即导出CHIP_MODULE_CACHE_DIR=
例子：
╭─pvelesko@cupcake ~╰─$ clinfo -l 平台 #0：英特尔(R) OpenCL 显卡 `-- 设备 #0：英特尔(R) Arc(TM) A380 显卡平台 #1：英特尔(R) OpenCL 显卡 `-- 设备 #0：英特尔(R) UHD 显卡 770
根据这些值，如果我们想在 OpenCL iGPU 上运行：
导出 CHIP_BE=openclexport CHIP_PLATFORM=1导出 CHIP_DEVICE=0
注意：零级没有 clinfo 等效项。通常，如果您有多个零级设备，则只会有一个平台，因此请设置 CHIP_PLATFORM=0，然后将 CHIP_DEVICE 设置为您要使用的设备。 *您可以通过运行打印名称的示例来检查设备的名称，例如build/samples/0_MatrixMultiply/MatrixMultiply
当最新安装的 GCC 版本不包含 libstdc++ 时，通常会发生这种情况，并且 Clang++ 默认情况下会选择最新找到的版本，最终无法链接 C++ 程序。这里讨论这个问题。
这个问题可以通过定义一个 Clang++ 配置文件来解决，该文件强制 GCC 达到我们想要的效果。例子：
echo --gcc-install-dir=/usr/lib/gcc/x86_64-linux-gnu/11 > ~/local/llvm-17/bin/x86_64-unknown-linux-gnu-clang++.cfg
在不支持双精度浮点数的 OpenCL 设备上运行测试时，会有多个测试出错。
通过设置两个环境变量以使使用双精度的内核工作，可以为 Intel iGPU 启用双精度浮点的软件模拟，但软件模拟的主要开销是：
导出 IGC_EnableDPEmulation=1导出 OverrideDefaultFP64Settings=1
如果您的设备不支持仿真，则可以在 cmake 配置时提供-DSKIP_TESTS_WITH_DOUBLES=ON选项来跳过这些测试。
