Skip to content

Commit 2d831d9

Browse files
WenboCodesWenboCodes
committed
docs: setup MkDocs GitHub Pages site
0 parents  commit 2d831d9

14 files changed

Lines changed: 1154 additions & 0 deletions

‎.github/workflows/deploy-docs.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: deploy-docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yml"
10+
- "requirements.txt"
11+
- ".github/workflows/deploy-docs.yml"
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
concurrency:
20+
group: pages
21+
cancel-in-progress: true
22+
23+
jobs:
24+
build:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
30+
- name: Setup Python
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: "3.11"
34+
35+
- name: Install dependencies
36+
run: pip install -r requirements.txt
37+
38+
- name: Build docs
39+
run: mkdocs build --strict
40+
41+
- name: Upload Pages artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: site
45+
46+
deploy:
47+
needs: build
48+
runs-on: ubuntu-latest
49+
environment:
50+
name: github-pages
51+
url: ${{ steps.deployment.outputs.page_url }}
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
site/
2+
.venv/
3+
__pycache__/
4+
*.pyc

‎PTO_IR_API_comments.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
问题梳理：
2+
1. Section 1的问题：
3+
    * 题目改为PTO IR Reference
4+
    * 第一段不需要提LLVM版本号
5+
6+
2. Section 2的问题：
7+
    * type system的定义，element types与nv tileir保持一致。参考nv TileIR文档(https://docs.nvidia.com/cuda/tile-ir/latest/sections/types.html)
8+
    * pto.ptr, pto.tile, pto.tile_buf标明待补充
9+
10+
3. Section 3的问题：
11+
    * Address space的定义
12+
    * Pipe的定义
13+
    * Layout包括BLayout，SLayout和PadValue，参照pto-isa仓的介绍
14+
15+
4. Section4的问题：
16+
    * 删除整个section
17+
18+
5. Section5的问题：
19+
    * pto.make_tensor_view参考附录
20+
    * pto.partition_view参考附录
21+
    * pto.alloc_tile对一个tile buffer的生命，每一个alloc_tile对应一个独立的tile buffer。alloc_tile()可以接受一个输入参数，即代表起始地址。默认没有输入参数，代表地址由编译器分别。
22+
    * pto.bind_tile不确定是否保留，请标明`待讨论`
23+
    * pto.subset改为pto.subview，即代表了新生命的tile buffer是输入tile buffer的一部分。
24+
    * pto.tload/tstore的定义修改和补充，见附录
25+
    * pto.ttrans需要一个tmp的输入，这个重点标注一下`待讨论`
26+
    * 标注一下pto.tmov和pto.copy区别是啥
27+
    * 删除掉pto.load_dps和pto.store_dps和pto.mov_dps
28+
    * pto.tmatmul去掉bias输入
29+
    * 去掉所有以_dps结尾的api接口相关定义
30+
    *` 5.16 Control Flow Operations`修改为`5.16 CV相关 operation`
31+
   
32+
33+
34+
6. 增加一个Rationale的section
35+
PTO IR中的Tile与Tensor不同，不是SSA格式的。其pto.tile_buf是一层buffer的语义，而不是value。这么做的目的是为了把tiling或内存分配的工作交给程序员或上层框架，PTO AS的pass仅关注调度和排流水。内存分配在编译器里面是一个NP-hard的问题，而排流水同时也是一个NP-hard的问题。这两个NP-hard的问题在一起会对编译pass的结果产生非常大的困扰。因此，在PTO IR的pipeline设计中，buffer复用的问题由用户解决，通过`pto.alloc_tile`来声明tile.buf的生命周期。
36+
37+
##附录：
38+
pto.make_tensor_view
39+
功能：通过指针建立 GlobalTensor 的构造函数 (Constructor)。定义全局内存 (Global Memory) 中原始数据的“物理大底座”。
40+
● 详细解释：此指令不涉及数据搬运，仅用于声明数据在内存中的排列规则（Strides）。它是所有视图变换的基准，确保后续的切片操作能准确定位物理地址。
41+
● 分型映射：若输入视图带有特定 Stride 模式，编译器在此阶段自动注入 Layout::NZ 等硬件提示，指导后续调用 DMA 分型搬运指令，实现最高效率的加载。
42+
● 映射逻辑：
43+
    ○ 映射为 GlobalTensor 的 Stride<...> 模板参数。
44+
    ○ 决定了 Tensor 的“视野边界”。
45+
2.2 pto.partition_view
46+
功能：逻辑窗口切分。在大视图上截取特定的计算区域，生成分块视图。
47+
● 详细解释：无论 Shape 是静态还是动态，均通过 partition_view 捕获。它承载了 offsets（决定“从哪开始读”）和 sizes（决定“读多少”），其返回类型为 !pto.partition_tensor_view。
48+
● 映射逻辑：
49+
    ○ 指针偏移：编译器自动生成 BasePtr + Offset。
50+
    ○ 逻辑 Shape：映射为 GlobalTensor 的 Shape<...> 模板参数。
51+
2.3 pto.tload
52+
功能：物理搬运与维度塌缩 (Dimension Collapse)。
53+
● 详细解释：
54+
    ○ 严格类型约束：仅接受 partition_tensor_view（逻辑高维）作为输入，输出必须为 tile_buf（物理 2D）。
55+
    ○ 核心约束：partition_view 中所有 size 维度的乘积，必须等于 tile_buf 的 valid_row 与 valid_col 的乘积。
56+
    ○ 语义映射：partition_tensor_view 是高维逻辑视图，而 tile_buf 是二维物理实体。pto.tload 完成了从 N 维到 2 维的线性映射。
57+
3. 映射逻辑示例 (From IR to C++)
58+
场景 A：完全静态 Shape (降维加载)
59+
IR Expression:
60+
// 1. 定义 5D 物理视图 (1, 1, 16, 1024, 1024)
61+
%0 = pto.make_tensor_view %arg0,
62+
    shape = [1, 1, 16, 1024, 1024],
63+
    strides = [1048576, 1048576, 1048576, 1024, 1]
64+
    : !pto.tensor_view<1x1x16x1024x1024xf32>
65+
66+
// 2. 使用 partition_view 切出 5D 子视图，总元素量 = 1*1*16*16*16 = 4096
67+
%1 = pto.partition_view %0, offsets = [0,0,0,0,0], sizes = [1, 1, 16, 16, 16]
68+
     : !pto.tensor_view<1x1x16x1024x1024xf32> -> !pto.partition_tensor_view<1x1x16x16x16xf32>
69+
70+
// 3. 执行 TLOAD，目标 Tile 256x16, 总容量 = 256*16 = 4096
71+
// 满足约束：1*1*16*16*16 == 256*16
72+
pto.tload ins(%1 : !pto.partition_tensor_view<1x1x16x16x16xf32>)
73+
          outs(%tile : !pto.tile_buf<256x16xf32>)
74+
Generated PTO C++:
75+
// 编译器自动推导并将 5D 逻辑映射至硬件指令
76+
using ShapeDim = Shape<1, 1, 16, 16, 16>;
77+
using StrideDim = Stride<1, 1, 1048576, 1024, 1>;
78+
79+
GlobalTensor<float, ShapeDim, StrideDim> src(srcPtr);
80+
81+
// 触发硬件 TLOAD，完成高维数据到 256x16 Tile 的填充
82+
TLOAD(src, tile);
83+
场景 B：动态 Shape
84+
IR Expression:
85+
// sizes 使用了运行时变量 %v0, %v1
86+
%1 = pto.partition_view %0, offsets = [%x, %y], sizes = [%v0, %v1]
87+
     : !pto.tensor_view<?x?xf32> -> !pto.partition_tensor_view<?x?xf32>
88+
Generated PTO C++:
89+
using ShapeDim = Shape<1, 1, 1, -1, -1>;
90+
using StrideDim = Stride<1, 1, 1, -1, 1>;
91+
92+
GlobalTensor<float, ShapeDim, StrideDim> gQ(
93+
    srcPtr + (x * stride_val + y),
94+
    ShapeDim(v0, v1),
95+
    StrideDim(stride_val)
96+
);

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# PTO Docs (GitHub Pages)
2+
3+
这个目录已经整理成可直接发布到 GitHub Pages 的 MkDocs 项目。
4+
5+
## 目录结构
6+
7+
- `docs/`: 文档正文
8+
- `mkdocs.yml`: 站点配置与导航
9+
- `requirements.txt`: 构建依赖
10+
- `.github/workflows/deploy-docs.yml`: 自动发布工作流
11+
12+
## 本地预览
13+
14+
```bash
15+
python3 -m venv .venv
16+
source .venv/bin/activate
17+
pip install -r requirements.txt
18+
mkdocs serve
19+
```
20+
21+
默认访问 `http://127.0.0.1:8000`。
22+
23+
## GitHub Pages 发布
24+
25+
1. 把当前目录内容提交到 GitHub 仓库根目录（默认分支 `main`）。
26+
2. 在仓库设置中打开 `Settings -> Pages`。
27+
3. 在 `Build and deployment` 里将 `Source` 设为 `GitHub Actions`。
28+
4. 推送到 `main` 后，工作流 `deploy-docs` 会自动构建并发布。
29+
30+
## 文档入口
31+
32+
站点首页由 `docs/README.md` 提供，导航由 `mkdocs.yml` 管理。

‎bin_intrinsic.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# BinIntrinsic 设计与参数映射说明
2+
3+
## 1. 执行链路（Single-Issue 边界）
4+
`TBIN_INTRIN` 在 A2/A3 后端的执行路径：
5+
6+
1. `TBIN_INTRIN<OpType>(...)`
7+
`include/pto/common/pto_instr.hpp:96`
8+
2. `TBIN_INTRIN_IMPL(...)`
9+
`include/pto/npu/a2a3/TBinIntrin.hpp:71`
10+
3. `BinaryIssueOnce(...)`
11+
`include/pto/npu/a2a3/TBinOp.hpp:21`
12+
4. `Op::BinInstr(...)` -> `vadd/vsub/vmul/vmax/vmin`
13+
`include/pto/npu/a2a3/TAdd.hpp:29`
14+
15+
其中 `BinaryIssueOnce` 是最小粒度边界：一次调用只对应一次 CCE intrinsic 发射，不做循环拆分。
16+
17+
## 2. `BinIntrinsicDesc` 字段与 CCE 参数对照
18+
定义位置：`include/pto/common/bin_intrinsic_desc.hpp:44`
19+
20+
| 字段 | 映射到 CCE 参数 | 单位 | 约束 | 说明 |
21+
|---|---|---|---|---|
22+
| `repeat` | `repeats` | 次 | `0..255` | intrinsic 重复发射次数（u8） |
23+
| `dstBlockStride/src0BlockStride/src1BlockStride` | block stride | 32B block | `0..255` | 同一 repeat 内 block 间距 |
24+
| `dstRepeatStride/src0RepeatStride/src1RepeatStride` | repeat stride | 32B block | `0..255` | 相邻 repeat 间距 |
25+
| `maskMode` | mask mode | 枚举 | `Normal/Count` | 掩码语义选择 |
26+
| `vectorCount` | `SetVectorCount` | 元素数 | Count 模式必须 `>0` | Count 模式有效长度 |
27+
| `tailElements` | `SetContMaskByDType` | 元素数 | `<= 256/sizeof(T)` | Normal 模式尾裁剪 |
28+
| `repeatStrideMode/strideSizeMode` | 扩展模式标志 | 布尔 | 当前必须 `false` | A2/A3 工具链当前不支持 |
29+
30+
## 3. 两种 Mask 语义
31+
校验和执行逻辑在：`include/pto/npu/a2a3/TBinOp.hpp:25`
32+
33+
1. Count 模式
34+
- 要求：`repeat == 0` 且 `vectorCount > 0`
35+
- 动作：`set_mask_count()` + `SetVectorCount(vectorCount)` + 发射 intrinsic
36+
37+
2. Normal 模式
38+
- 要求：`repeat > 0`
39+
- 可选：`tailElements > 0` 时先 `SetContMaskByDType<T>(tailElements)`
40+
- 限制：不允许 `repeat > 1 && tailElements > 0`（单次 issue 无法同时表达“多 repeat + tail”）
41+
42+
## 4. 最小粒度暴露原则
43+
single-issue API 对外暴露的是“1 次 intrinsic 发射”的全部必要参数：
44+
45+
1. 覆盖窗口（满发射）：`repeat * (256 / sizeof(T))` 元素
46+
2. 尾裁剪窗口（仅 Normal）：`tailElements`
47+
3. 地址模式：block stride + repeat stride（dst/src0/src1 三路独立）
48+
49+
超过该粒度的工作（如 `repeat > 255`、复杂 tail 组合）由上层策略负责拆分为多次 `TBIN_INTRIN` 调用。
50+
51+
## 5. 为什么拆出 `bin_intrinsic_desc.hpp`
52+
文件：`include/pto/common/bin_intrinsic_desc.hpp`
53+
54+
1. 轻量依赖，只包含 `<cstdint>`，可直接用于 host/gtest 侧参数校验测试。
55+
2. 避免 `constants.hpp` 的设备限定符依赖（`__ubuf__`、`__gm__`）影响 host 编译。
56+
3. `constants.hpp` 通过 include 复用定义，保持原有代码兼容：
57+
`include/pto/common/constants.hpp:13`
58+
59+
## 6. 典型配置示例（FP32，64x64）
60+
示例来源：`tests/npu/a2a3/src/st/testcase/tadd/tadd_kernel.cpp:67`
61+
62+
- `elemPerRepeat = 256 / 4 = 64`
63+
- `totalElements = 64 * 64 = 4096`
64+
- `repeat = 4096 / 64 = 64`
65+
- `dst/src0/src1 block stride = 1`
66+
- `dst/src0/src1 repeat stride = 8`（连续布局）
67+
68+
这是“整 repeat、无 tail”的标准 intrinsic 直发场景。
69+
70+
## 7. 参数校验接口（便于单测）
71+
定义位置：`include/pto/common/bin_intrinsic_desc.hpp:63`
72+
73+
- `ValidateBinIntrinsicDesc<T>(desc)`：返回 `BinIntrinsicDescStatus`
74+
- `IsBinIntrinsicDescValid<T>(desc)`：返回 `bool`
75+
76+
已有负例单测示例：
77+
`tests/npu/a2a3/src/st/testcase/tadd/main.cpp:254`

‎docs/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# PTO 文档目录
2+
3+
这是一组整理后的 Markdown 文档，适合直接放到 GitHub 仓库的 `docs/` 目录进行托管。
4+
5+
## 文档导航
6+
7+
1. [A3 版 TROWMAX 详细分析（面向小白到进阶）](./intrin-intro.md)
8+
2. [BinIntrinsic 设计与参数映射说明](./bin-intrinsic.md)
9+
3. [A2/A3 TBinOp 无循环 Intrinsic 化改造方案（含公开 Low-Level API）](./pto-intrinsic-plan.md)
10+
4. [PTO IR API 评审问题梳理](./pto-ir-api-comments.md)
11+
12+
## 说明
13+
14+
- 原始文件仍保留在 `/home/sunwenbo/tmp` 根目录。
15+
- 本目录下文件命名已统一为小写 + 连字符，便于链接与 URL 使用。

‎docs/bin-intrinsic.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# BinIntrinsic 设计与参数映射说明
2+
3+
## 1. 执行链路（Single-Issue 边界）
4+
`TBIN_INTRIN` 在 A2/A3 后端的执行路径：
5+
6+
1. `TBIN_INTRIN<OpType>(...)`
7+
`include/pto/common/pto_instr.hpp:96`
8+
2. `TBIN_INTRIN_IMPL(...)`
9+
`include/pto/npu/a2a3/TBinIntrin.hpp:71`
10+
3. `BinaryIssueOnce(...)`
11+
`include/pto/npu/a2a3/TBinOp.hpp:21`
12+
4. `Op::BinInstr(...)` -> `vadd/vsub/vmul/vmax/vmin`
13+
`include/pto/npu/a2a3/TAdd.hpp:29`
14+
15+
其中 `BinaryIssueOnce` 是最小粒度边界：一次调用只对应一次 CCE intrinsic 发射，不做循环拆分。
16+
17+
## 2. `BinIntrinsicDesc` 字段与 CCE 参数对照
18+
定义位置：`include/pto/common/bin_intrinsic_desc.hpp:44`
19+
20+
| 字段 | 映射到 CCE 参数 | 单位 | 约束 | 说明 |
21+
|---|---|---|---|---|
22+
| `repeat` | `repeats` | 次 | `0..255` | intrinsic 重复发射次数（u8） |
23+
| `dstBlockStride/src0BlockStride/src1BlockStride` | block stride | 32B block | `0..255` | 同一 repeat 内 block 间距 |
24+
| `dstRepeatStride/src0RepeatStride/src1RepeatStride` | repeat stride | 32B block | `0..255` | 相邻 repeat 间距 |
25+
| `maskMode` | mask mode | 枚举 | `Normal/Count` | 掩码语义选择 |
26+
| `vectorCount` | `SetVectorCount` | 元素数 | Count 模式必须 `>0` | Count 模式有效长度 |
27+
| `tailElements` | `SetContMaskByDType` | 元素数 | `<= 256/sizeof(T)` | Normal 模式尾裁剪 |
28+
| `repeatStrideMode/strideSizeMode` | 扩展模式标志 | 布尔 | 当前必须 `false` | A2/A3 工具链当前不支持 |
29+
30+
## 3. 两种 Mask 语义
31+
校验和执行逻辑在：`include/pto/npu/a2a3/TBinOp.hpp:25`
32+
33+
1. Count 模式
34+
- 要求：`repeat == 0` 且 `vectorCount > 0`
35+
- 动作：`set_mask_count()` + `SetVectorCount(vectorCount)` + 发射 intrinsic
36+
37+
2. Normal 模式
38+
- 要求：`repeat > 0`
39+
- 可选：`tailElements > 0` 时先 `SetContMaskByDType<T>(tailElements)`
40+
- 限制：不允许 `repeat > 1 && tailElements > 0`（单次 issue 无法同时表达“多 repeat + tail”）
41+
42+
## 4. 最小粒度暴露原则
43+
single-issue API 对外暴露的是“1 次 intrinsic 发射”的全部必要参数：
44+
45+
1. 覆盖窗口（满发射）：`repeat * (256 / sizeof(T))` 元素
46+
2. 尾裁剪窗口（仅 Normal）：`tailElements`
47+
3. 地址模式：block stride + repeat stride（dst/src0/src1 三路独立）
48+
49+
超过该粒度的工作（如 `repeat > 255`、复杂 tail 组合）由上层策略负责拆分为多次 `TBIN_INTRIN` 调用。
50+
51+
## 5. 为什么拆出 `bin_intrinsic_desc.hpp`
52+
文件：`include/pto/common/bin_intrinsic_desc.hpp`
53+
54+
1. 轻量依赖，只包含 `<cstdint>`，可直接用于 host/gtest 侧参数校验测试。
55+
2. 避免 `constants.hpp` 的设备限定符依赖（`__ubuf__`、`__gm__`）影响 host 编译。
56+
3. `constants.hpp` 通过 include 复用定义，保持原有代码兼容：
57+
`include/pto/common/constants.hpp:13`
58+
59+
## 6. 典型配置示例（FP32，64x64）
60+
示例来源：`tests/npu/a2a3/src/st/testcase/tadd/tadd_kernel.cpp:67`
61+
62+
- `elemPerRepeat = 256 / 4 = 64`
63+
- `totalElements = 64 * 64 = 4096`
64+
- `repeat = 4096 / 64 = 64`
65+
- `dst/src0/src1 block stride = 1`
66+
- `dst/src0/src1 repeat stride = 8`（连续布局）
67+
68+
这是“整 repeat、无 tail”的标准 intrinsic 直发场景。
69+
70+
## 7. 参数校验接口（便于单测）
71+
定义位置：`include/pto/common/bin_intrinsic_desc.hpp:63`
72+
73+
- `ValidateBinIntrinsicDesc<T>(desc)`：返回 `BinIntrinsicDescStatus`
74+
- `IsBinIntrinsicDescValid<T>(desc)`：返回 `bool`
75+
76+
已有负例单测示例：
77+
`tests/npu/a2a3/src/st/testcase/tadd/main.cpp:254`

0 commit comments

Comments
 (0)