feat: add MACA backend support

.clang-format

@@ -0,0 +1,30 @@
+---
+BasedOnStyle: LLVM
+IndentWidth: 4
+AccessModifierOffset: -4
+AlignOperands: AlignAfterOperator
+BreakBeforeBinaryOperators: All
+ColumnLimit: 120
+AllowShortBlocksOnASingleLine: Always
+AllowShortLoopsOnASingleLine: true
+InsertBraces: true
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterCaseLabel: false
+  AfterClass: false
+  AfterControlStatement: Never
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterObjCDeclaration: false
+  AfterStruct: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: false
+  BeforeLambdaBody: false
+  BeforeWhile: false
+  IndentBraces: false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true

.clang-tidy

@@ -0,0 +1,17 @@
+---
+Checks: >
+  -*,
+  infinitrain-no-member-definitions-in-headers,
+  readability-identifier-naming
+WarningsAsErrors: '*'
+HeaderFilterRegex: '(^|.*/)(backends|tools)/'
+HeaderFileExtensions: [h, hh, hpp, hxx, cuh]
+FormatStyle: none
+CheckOptions:
+  # InfiniTrain custom checks.
+  infinitrain-no-member-definitions-in-headers.IgnoreEmptyBodies: true
+
+  # Enum constants: kFooBar
+  readability-identifier-naming.EnumConstantCase: CamelCase
+  readability-identifier-naming.EnumConstantPrefix: k
+...

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Formatting-only commits; preserve attribution to the original changes.
+baddcda9429658cb0d4a55e850302940a58b868f

.github/workflows/format-check.yaml

@@ -0,0 +1,27 @@
+name: Format Check
+
+on:
+  pull_request:
+  push:
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+
+jobs:
+  format-check:
+    name: Check Code Format
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install formatters
+      run: |
+        python3 -m pip install --upgrade pip
+        python3 -m pip install black clang-format==16.0.6
+
+    - name: Run format check
+      run: |
+        python3 scripts/format.py --c clang-format --path backends --check
+

.gitignore

@@ -0,0 +1,9 @@
+/build*/
+/cmake-build-*/
+/.cache/
+/.vscode/
+/compile_commands.json
+
+*.log
+*.report.rank*
+*.records.log.rank*

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "third_party/InfiniTrain"]
+	path = third_party/InfiniTrain
+	url = https://github.com/InfiniTensor/InfiniTrain.git

CMakeLists.txt

@@ -0,0 +1,71 @@
+cmake_minimum_required(VERSION 3.28)
+
+set(INFINITRAIN_BACKEND "" CACHE STRING
+  "Accelerator provider to build from backends/<provider>")
+if(INFINITRAIN_BACKEND STREQUAL "")
+  message(FATAL_ERROR
+    "INFINITRAIN_BACKEND is required. Configure with "
+    "-DINFINITRAIN_BACKEND=<provider>.")
+endif()
+string(TOLOWER "${INFINITRAIN_BACKEND}" INFINITRAIN_BACKEND)
+if(NOT INFINITRAIN_BACKEND MATCHES "^[a-z0-9_]+$")
+  message(FATAL_ERROR
+    "INFINITRAIN_BACKEND must name a directory under backends/: "
+    "${INFINITRAIN_BACKEND}")
+endif()
+
+set(INFINITRAIN_BACKEND_DIR
+  "${CMAKE_CURRENT_SOURCE_DIR}/backends/${INFINITRAIN_BACKEND}")
+set(INFINITRAIN_BACKEND_PRE_PROJECT
+  "${INFINITRAIN_BACKEND_DIR}/cmake/pre_project.cmake")
+if(NOT EXISTS "${INFINITRAIN_BACKEND_PRE_PROJECT}")
+  message(FATAL_ERROR
+    "Unknown or incomplete InfiniTrain backend '${INFINITRAIN_BACKEND}': "
+    "${INFINITRAIN_BACKEND_PRE_PROJECT} was not found.")
+endif()
+
+if(USE_CUDA)
+  message(FATAL_ERROR
+    "USE_CUDA=ON is incompatible with the '${INFINITRAIN_BACKEND}' "
+    "PrivateUse1 provider. Configure with -DUSE_CUDA=OFF or use a separate "
+    "build directory.")
+endif()
+
+# A provider owns compiler and dependency-probe setup that must happen before
+# project(). This keeps vendor SDK assumptions out of the repository root.
+include("${INFINITRAIN_BACKEND_PRE_PROJECT}")
+
+project(InfiniTrainBackends VERSION 0.1.0 LANGUAGES CXX)
+
+option(INFINITRAIN_BACKENDS_BUILD_EXAMPLES
+  "Build backend-enabled InfiniTrain examples" ${PROJECT_IS_TOP_LEVEL})
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+set(INFINITRAIN_SOURCE_DIR
+    "${CMAKE_CURRENT_SOURCE_DIR}/third_party/InfiniTrain"
+    CACHE PATH "InfiniTrain source tree (normally the pinned submodule)")
+if(NOT EXISTS "${INFINITRAIN_SOURCE_DIR}/CMakeLists.txt")
+  message(FATAL_ERROR
+    "InfiniTrain was not found at ${INFINITRAIN_SOURCE_DIR}. "
+    "Run git submodule update --init --recursive or set INFINITRAIN_SOURCE_DIR.")
+endif()
+
+add_subdirectory("${INFINITRAIN_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/InfiniTrain")
+if(INFINITRAIN_BACKENDS_BUILD_EXAMPLES AND NOT TARGET infini_run)
+  # InfiniTrain omits top-level tools when embedded, but multi-process model
+  # runs still require its launcher next to the provider-enabled examples.
+  add_subdirectory(
+    "${INFINITRAIN_SOURCE_DIR}/tools/infini_run"
+    "${CMAKE_CURRENT_BINARY_DIR}/InfiniTrain/tools/infini_run")
+  set_target_properties(infini_run PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}")
+endif()
+if(BUILD_TEST)
+  # InfiniTrain registers the shared suites in its subdirectory. Enable CTest
+  # at this repository root before the provider instantiates PrivateUse1.
+  enable_testing()
+endif()
+add_subdirectory("backends/${INFINITRAIN_BACKEND}")

README.md

@@ -1 +1,119 @@
-# InfiniTrain-Backends
+# InfiniTrain Backends
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![Issues](https://img.shields.io/github/issues/InfiniTensor/InfiniTrain-Backends)](
+https://github.com/InfiniTensor/InfiniTrain-Backends/issues
+)
+[![PR](https://img.shields.io/github/issues-pr/InfiniTensor/InfiniTrain-Backends)](
+https://github.com/InfiniTensor/InfiniTrain-Backends/pulls
+)
+[![License](https://img.shields.io/github/license/InfiniTensor/InfiniTrain-Backends)](
+https://github.com/InfiniTensor/InfiniTrain-Backends/blob/master/LICENSE
+)
+
+InfiniTrain Backends provides out-of-tree accelerator backends for
+[InfiniTrain](https://github.com/InfiniTensor/InfiniTrain). It keeps
+vendor-specific SDK integration, runtime support, collective communication,
+and kernels outside the framework core while implementing InfiniTrain's
+`PrivateUse1` backend interfaces.
+
+Each provider is isolated under `backends/<provider>` and normally consumes the
+InfiniTrain submodule pinned to `v0.7.0`. One build tree selects one provider, and a
+process may register at most one provider for `DeviceType::kPrivateUse1`.
+
+## Supported Backends
+
+| Backend | Runtime | Collectives | Model examples |
+| ------- | ------- | ----------- | -------------- |
+| [MACA](backends/maca/README.md) | MACA | MCCL (optional) | GPT-2, LLaMA 3, Mixtral |
+
+The model sources normally come from the pinned InfiniTrain submodule. Each
+backend supplies the runtime, kernels, collective implementation, and build
+integration needed to run its supported examples on the corresponding
+accelerator. See the linked backend guides for setup and usage.
+
+## Common Requirements
+
+- **Linux**
+- **CMake**: 3.28 or newer
+- **Git** with submodule support
+- A **C++20** compiler and vendor SDK compatible with the selected backend
+
+Additional dependencies and SDK setup are documented in each backend's guide.
+
+## Build Options
+
+These options apply across backends. Provider-specific options are documented
+in the corresponding backend guide.
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `INFINITRAIN_BACKEND` | Required | Provider selected from `backends/<provider>` |
+| `INFINITRAIN_SOURCE_DIR` | `third_party/InfiniTrain` | InfiniTrain source tree, normally the pinned submodule |
+| `INFINITRAIN_BACKENDS_BUILD_EXAMPLES` | `ON` for a top-level build | Build provider-enabled InfiniTrain examples |
+| `BUILD_TEST` | `OFF` | Build InfiniTrain's unit tests and variants for the selected provider |
+
+Use a separate build directory for each provider so compiler and SDK cache
+entries do not leak between them. Top-level builds enable backend examples by
+default.
+
+For development against another InfiniTrain checkout, add
+`-DINFINITRAIN_SOURCE_DIR=/path/to/InfiniTrain` to the configure command. The
+selected checkout must implement the PrivateUse1 extension API expected by
+the backend.
+
+PrivateUse1 providers require `USE_CUDA=OFF`; configuration fails rather than
+silently overriding an explicit `USE_CUDA=ON`. Unit tests for the selected
+provider use the PrivateUse1 device type and `PRIVATEUSE1/*` GTest prefix,
+independent of the provider's name.
+
+## Architecture
+
+```text
+backends/<provider>/
+  README.md              provider setup and usage guide
+  cmake/                 compiler and vendor SDK setup before project()
+  include/               public provider API
+  src/backend.cc         provider metadata registration entry point
+  src/common/            provider-internal shared helpers
+  src/runtime/           device, stream, event, and allocator integration
+  src/kernels/           provider kernel implementations and registration
+  src/ccl/               optional collective communication integration
+  examples/              CMake adapters for upstream InfiniTrain examples
+  scripts/               provider model-run configuration and wrappers
+
+third_party/InfiniTrain/ framework source, normally a pinned git submodule
+```
+
+The root build selects and includes
+`backends/<provider>/cmake/pre_project.cmake` before its first `project()` call.
+This lets each provider select its compiler and prepare SDK-specific dependency
+probes without adding vendor branches to the root `CMakeLists.txt`.
+
+When adding this repository as a third-party library with `add_subdirectory()`,
+select the compiler required by the provider in the parent project before
+enabling the C++ language. After setting up the vendor SDK environment, use
+the following order in the parent's `CMakeLists.txt`, replacing the compiler
+path and provider name:
+
+```cmake
+cmake_minimum_required(VERSION 3.28)
+
+set(CMAKE_CXX_COMPILER "/path/to/vendor/compiler" CACHE FILEPATH "")
+set(INFINITRAIN_BACKEND "<provider>" CACHE STRING "")
+
+project(MyTrainingApp LANGUAGES CXX)
+add_subdirectory(third_party/InfiniTrain-Backends)
+```
+
+CMake cannot replace a compiler after a language has been enabled.
+
+## Development checks
+
+See [formatting and static checks](scripts/README.md) for clang-format,
+clang-tidy and IWYU setup, scope and manual usage (in Chinese).
+
+## License
+
+InfiniTrain Backends is released under the [MIT License](LICENSE).

README.zh-CN.md

@@ -0,0 +1,109 @@
+# InfiniTrain Backends
+
+[English](README.md) | **简体中文**
+
+[![Issues](https://img.shields.io/github/issues/InfiniTensor/InfiniTrain-Backends)](
+https://github.com/InfiniTensor/InfiniTrain-Backends/issues
+)
+[![PR](https://img.shields.io/github/issues-pr/InfiniTensor/InfiniTrain-Backends)](
+https://github.com/InfiniTensor/InfiniTrain-Backends/pulls
+)
+[![License](https://img.shields.io/github/license/InfiniTensor/InfiniTrain-Backends)](
+https://github.com/InfiniTensor/InfiniTrain-Backends/blob/master/LICENSE
+)
+
+InfiniTrain Backends 为 [InfiniTrain](https://github.com/InfiniTensor/InfiniTrain)
+提供独立于框架核心维护的加速器后端。各后端实现 InfiniTrain 的 `PrivateUse1`
+接口，将厂商 SDK 集成、运行时支持、集合通信和算子实现放在框架核心之外。
+
+每个后端位于独立的 `backends/<provider>` 目录中，通常使用固定为 `v0.7.0` 的
+InfiniTrain 子模块。每个构建目录只选择一个后端，每个进程最多注册一个
+`DeviceType::kPrivateUse1` 后端。
+
+## 支持的后端
+
+| 后端 | 运行时 | 集合通信 | 模型示例 |
+| ---- | ------ | -------- | -------- |
+| [MACA](backends/maca/README.zh-CN.md) | MACA | MCCL（可选） | GPT-2、LLaMA 3、Mixtral |
+
+模型源码通常来自锁定版本的 InfiniTrain 子模块。各后端提供运行时、算子、集合通信
+实现和构建集成，以便在对应加速器上运行其支持的模型示例。环境配置和使用方式见上表
+链接的各后端指南。
+
+## 通用依赖
+
+- **Linux**
+- **CMake**：3.28 或更新版本
+- 支持子模块的 **Git**
+- 与所选后端兼容的 **C++20** 编译器和厂商 SDK
+
+额外依赖及 SDK 配置方式见对应后端指南。
+
+## 构建选项
+
+以下选项适用于各后端。后端专用选项见对应后端指南。
+
+| 选项 | 默认值 | 说明 |
+| ---- | ------ | ---- |
+| `INFINITRAIN_BACKEND` | 必填 | 选择 `backends/<provider>` 下的后端 |
+| `INFINITRAIN_SOURCE_DIR` | `third_party/InfiniTrain` | InfiniTrain 源码目录，通常为锁定版本的子模块 |
+| `INFINITRAIN_BACKENDS_BUILD_EXAMPLES` | 独立构建本仓库时为 `ON` | 构建启用所选后端的 InfiniTrain 示例 |
+| `BUILD_TEST` | `OFF` | 构建 InfiniTrain 单元测试及所选后端的测试版本 |
+
+请为不同后端使用独立的构建目录，避免混用编译器和 SDK 缓存。独立构建本仓库时，
+默认启用后端示例。
+
+如需使用其他 InfiniTrain 工作副本进行开发，可在 CMake 配置命令中添加
+`-DINFINITRAIN_SOURCE_DIR=/path/to/InfiniTrain`。所选源码版本必须实现该后端所需的
+PrivateUse1 扩展接口。
+
+PrivateUse1 后端要求 `USE_CUDA=OFF`。如果显式设置 `USE_CUDA=ON`，配置会报错，
+而不会静默覆盖该选项。所选后端的单元测试使用 PrivateUse1 设备类型和
+`PRIVATEUSE1/*` GTest 前缀，与后端名称无关。
+
+## 架构
+
+```text
+backends/<provider>/
+  README.md              后端环境配置与使用指南
+  cmake/                 在 project() 前配置编译器和厂商 SDK
+  include/               后端公共接口
+  src/backend.cc         后端元数据注册入口
+  src/common/            后端内部共享辅助代码
+  src/runtime/           设备、流、事件和内存分配集成
+  src/kernels/           后端算子实现及注册
+  src/ccl/               可选的集合通信集成
+  examples/              上游 InfiniTrain 示例的 CMake 适配
+  scripts/               后端模型运行配置及封装脚本
+
+third_party/InfiniTrain/ 框架源码，通常为锁定版本的 Git 子模块
+```
+
+根目录构建脚本在首次调用 `project()` 之前，根据所选后端加载
+`backends/<provider>/cmake/pre_project.cmake`。各后端可在此选择编译器并准备
+SDK 相关的依赖探测配置，无需在根目录 `CMakeLists.txt` 中增加厂商分支。
+
+通过 `add_subdirectory()` 将本仓库作为第三方库添加到父项目时，应在启用 C++
+语言前选择后端所需的编译器。配置好厂商 SDK 环境后，可按以下顺序编写父项目的
+`CMakeLists.txt`，并替换编译器路径和后端名称：
+
+```cmake
+cmake_minimum_required(VERSION 3.28)
+
+set(CMAKE_CXX_COMPILER "/path/to/vendor/compiler" CACHE FILEPATH "")
+set(INFINITRAIN_BACKEND "<provider>" CACHE STRING "")
+
+project(MyTrainingApp LANGUAGES CXX)
+add_subdirectory(third_party/InfiniTrain-Backends)
+```
+
+CMake 无法在启用某种语言后更换其编译器。
+
+## 开发检查
+
+clang-format、clang-tidy 和 IWYU 的范围、依赖及手动使用方式见
+[代码格式和静态检查](scripts/README.md)。
+
+## 许可证
+
+InfiniTrain Backends 使用 [MIT 许可证](LICENSE)。