Skip to content

Commit 2de5b0c

Browse files
xup16claude
authored and
zhzhcookie
committed
[RPU][DOC] Add RPU backend install guide (English + 中文) (#694)
Add documents/install_rpu.md and documents/install_rpu_cn.md describing how to build and test the Rhino RPU backend. Unlike the CPU/GPU backends, the RPU backend has no preinstalled image and no CPU simulator -- it compiles and runs only on a physical Huixi 光至 R1 SoC board, with driver/runtime/toolchain obtained from the vendor, so the guide walks through building and testing directly on the board. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 09fb128 commit 2de5b0c

2 files changed

Lines changed: 226 additions & 0 deletions

File tree

‎documents/install_rpu.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
[[中文版](./install_rpu_cn.md)|English]
2+
3+
## 💫 Huixi Intelligence（辉羲智能）[rpu](https://github.com/flagos-ai/FlagTree/tree/triton_v3.6.x/third_party/rpu/)
4+
5+
- Based on Triton 3.6, aarch64
6+
7+
The **Rhino RPU** is the AI accelerator inside Huixi Intelligence's 光至 R1 SoC
8+
([rhino.auto](https://www.rhino.auto/)). Unlike the CPU/GPU backends, the RPU
9+
backend has **no preinstalled image and no CPU simulator** — it compiles and
10+
runs only on a physical R1 SoC board, and its driver, runtime, and toolchain are
11+
obtained from the vendor. Build and test directly on the board.
12+
13+
> The RPU driver, runtime, and LLVM toolchain are not publicly distributed.
14+
> Contact **Huixi Intelligence** ([rhino.auto](https://www.rhino.auto/)) to
15+
> obtain them.
16+
17+
### 1. Build and run environment
18+
19+
#### 1.1 Hardware and OS
20+
21+
- An R1 SoC board running aarch64 Linux that exposes the RPU device node
22+
`/dev/rpu` (kernel module loaded).
23+
- Minimum 24 GB RAM and 60 GB free disk.
24+
- Python 3.10+, `cmake >= 3.20`, `ninja`, and a recent `pip`.
25+
26+
There is no Docker image for the RPU backend; all steps below run natively on
27+
the R1 SoC board. Verify the device node:
28+
29+
```shell
30+
ls /dev/rpu
31+
```
32+
33+
#### 1.2 RPU driver and runtime (vendor-provided)
34+
35+
Install, per the vendor's instructions:
36+
37+
- the RPU kernel driver that provides `/dev/rpu`;
38+
- the `rhino-launch-kernel` runtime library (`librhino_launch.so`), used by the
39+
on-board launch_kernel test.
40+
41+
#### 1.3 RPU LLVM toolchain (vendor-provided)
42+
43+
The RPU backend uses a custom LLVM as its `.rpubin` emitter. Point
44+
`RPU_LLVM_ROOT` at the toolchain install prefix (the directory containing
45+
`bin/clang`):
46+
47+
```shell
48+
# Toolchain layout:
49+
# $RPU_LLVM_ROOT/bin/clang
50+
# $RPU_LLVM_ROOT/lib/...
51+
export RPU_LLVM_ROOT=/opt/rpu/llvm
52+
```
53+
54+
### 2. Installation Commands
55+
56+
The RPU backend is built from source on the board. There is no source-free
57+
(pip wheel) installation.
58+
59+
#### 2.1 Pull the source code
60+
61+
```shell
62+
cd ~
63+
git clone https://github.com/flagos-ai/FlagTree.git
64+
cd FlagTree
65+
git checkout -b triton_v3.6.x origin/triton_v3.6.x
66+
```
67+
68+
#### 2.2 Build from source
69+
70+
```shell
71+
export FLAGTREE_BACKEND=rpu
72+
export MAX_JOBS=8 # tune to available RAM
73+
74+
cd ~/FlagTree/python
75+
pip3 install -r requirements.txt # build-time dependencies
76+
77+
cd ~/FlagTree
78+
# Initial build
79+
pip3 install . --no-build-isolation -v
80+
# Rebuild after source changes
81+
pip3 install . --no-build-isolation --force-reinstall -v
82+
```
83+
84+
The Triton MLIR LLVM is downloaded automatically from the public oaitriton blob
85+
the first time setup runs; no manual action is needed.
86+
87+
### 3. Testing and validation
88+
89+
#### 3.1 Unit tests
90+
91+
The compile tests drive the real toolchain, so set `RPU_LLVM_ROOT` first (the
92+
directory containing `bin/clang`). If it is unset or its path is missing, the
93+
tests stop with a clear message naming the variable.
94+
95+
```shell
96+
cd ~/FlagTree
97+
export RPU_LLVM_ROOT=/opt/rpu/llvm
98+
pytest -s third_party/rpu/python/test/unit
99+
```
100+
101+
#### 3.2 On-board launch_kernel check
102+
103+
This needs the `launch_kernel_runner` CLI, a thin front-end over the
104+
`rhino-launch-kernel` runtime library. Build it together with the backend by
105+
enabling `RPU_BUILD_LAUNCH_RUNNER` (off by default; it needs the
106+
`rhino-launch-kernel` install), then run the smoke test on a board with
107+
`/dev/rpu`:
108+
109+
```shell
110+
TRITON_APPEND_CMAKE_ARGS="-DRPU_BUILD_LAUNCH_RUNNER=ON -DCMAKE_PREFIX_PATH=/path/to/rhino-launch-kernel/install" \
111+
pip3 install . --no-build-isolation --force-reinstall -v
112+
export RPU_LK_RUNNER=$PWD/third_party/rpu/tools/launch_runner/launch_kernel_runner
113+
python3 third_party/rpu/python/test/board/lk_board_smoke.py --require-board
114+
```
115+
116+
It compiles a small kernel, dispatches it on the device, and compares the result
117+
to a numpy golden.
118+
119+
Refer to [Tests of rpu backend](https://github.com/flagos-ai/FlagTree/blob/triton_v3.6.x/.github/workflows/rpu3.6-build-and-test.yml)

‎documents/install_rpu_cn.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
[中文版|[English](./install_rpu.md)]
2+
3+
## 💫 Huixi Intelligence（辉羲智能）[rpu](https://github.com/flagos-ai/FlagTree/tree/triton_v3.6.x/third_party/rpu/)
4+
5+
- 对应的 Triton 版本为 3.6，基于 aarch64 平台
6+
7+
**Rhino RPU** 是辉羲智能光至 R1 SoC 内的 AI 加速器
8+
（[rhino.auto](https://www.rhino.auto/)）。与 CPU/GPU 后端不同，RPU 后端**没有预装镜像，也没有
9+
CPU 模拟环境**——只能在物理 R1 SoC 板卡上编译和运行，其驱动、运行时与工具链均需从厂家获取。
10+
请直接在板卡上构建与测试。
11+
12+
> RPU 的驱动、运行时与 LLVM 工具链不公开分发。请联系**辉羲智能**
13+
> （[rhino.auto](https://www.rhino.auto/)）获取。
14+
15+
### 1. 构建及运行环境
16+
17+
#### 1.1 硬件与操作系统
18+
19+
- 一块运行 aarch64 Linux 的 R1 SoC 板卡，且暴露 RPU 设备节点 `/dev/rpu`（内核模块已加载）。
20+
- 最低 24 GB 内存、60 GB 可用磁盘。
21+
- Python 3.10+、`cmake >= 3.20`、`ninja`，以及较新版本的 `pip`。
22+
23+
RPU 后端没有 Docker 镜像，以下所有步骤均在 R1 SoC 板卡上原生执行。确认设备节点：
24+
25+
```shell
26+
ls /dev/rpu
27+
```
28+
29+
#### 1.2 RPU 驱动与运行时（厂家提供）
30+
31+
请按厂家说明安装：
32+
33+
- 提供 `/dev/rpu` 的 RPU 内核驱动；
34+
- `rhino-launch-kernel` 运行时库（`librhino_launch.so`），供板上 launch_kernel 测试使用。
35+
36+
#### 1.3 RPU LLVM 工具链（厂家提供）
37+
38+
RPU 后端使用一套定制 LLVM 作为 `.rpubin` 发射器。将 `RPU_LLVM_ROOT` 指向工具链安装前缀
39+
（即包含 `bin/clang` 的目录）：
40+
41+
```shell
42+
# 工具链目录结构：
43+
# $RPU_LLVM_ROOT/bin/clang
44+
# $RPU_LLVM_ROOT/lib/...
45+
export RPU_LLVM_ROOT=/opt/rpu/llvm
46+
```
47+
48+
### 2. 安装命令
49+
50+
RPU 后端在板卡上从源码构建，没有免源码（pip wheel）安装方式。
51+
52+
#### 2.1 拉取源码
53+
54+
```shell
55+
cd ~
56+
git clone https://github.com/flagos-ai/FlagTree.git
57+
cd FlagTree
58+
git checkout -b triton_v3.6.x origin/triton_v3.6.x
59+
```
60+
61+
#### 2.2 从源码构建
62+
63+
```shell
64+
export FLAGTREE_BACKEND=rpu
65+
export MAX_JOBS=8 # 根据可用内存调整
66+
67+
cd ~/FlagTree/python
68+
pip3 install -r requirements.txt # 构建期依赖
69+
70+
cd ~/FlagTree
71+
# 首次构建
72+
pip3 install . --no-build-isolation -v
73+
# 修改源码后重新构建
74+
pip3 install . --no-build-isolation --force-reinstall -v
75+
```
76+
77+
Triton 的 MLIR LLVM 会在首次执行 setup 时自动从公开的 oaitriton blob 下载，无需手动操作。
78+
79+
### 3. 测试验证
80+
81+
#### 3.1 单元测试
82+
83+
编译测试会驱动真实工具链，因此需先设置 `RPU_LLVM_ROOT`（即包含 `bin/clang` 的目录）。若未设置或
84+
路径不存在，测试会停止并给出明确提示，指明缺失的变量名。
85+
86+
```shell
87+
cd ~/FlagTree
88+
export RPU_LLVM_ROOT=/opt/rpu/llvm
89+
pytest -s third_party/rpu/python/test/unit
90+
```
91+
92+
#### 3.2 板上 launch_kernel 验证
93+
94+
该步骤需要 `launch_kernel_runner` CLI，它是 `rhino-launch-kernel` 运行时库的一层薄封装。通过开启
95+
`RPU_BUILD_LAUNCH_RUNNER`（默认关闭；需要已安装 `rhino-launch-kernel`）随后端一起构建，然后在带
96+
`/dev/rpu` 的板卡上运行冒烟测试：
97+
98+
```shell
99+
TRITON_APPEND_CMAKE_ARGS="-DRPU_BUILD_LAUNCH_RUNNER=ON -DCMAKE_PREFIX_PATH=/path/to/rhino-launch-kernel/install" \
100+
pip3 install . --no-build-isolation --force-reinstall -v
101+
export RPU_LK_RUNNER=$PWD/third_party/rpu/tools/launch_runner/launch_kernel_runner
102+
python3 third_party/rpu/python/test/board/lk_board_smoke.py --require-board
103+
```
104+
105+
它会编译一个小 kernel，在设备上派发执行，并与 numpy golden 结果比对。
106+
107+
参考 [Tests of rpu backend](https://github.com/flagos-ai/FlagTree/blob/triton_v3.6.x/.github/workflows/rpu3.6-build-and-test.yml)

0 commit comments

Comments
 (0)