Star626
320
代码
代码
Issues61
Pull Requests74
Actions
项目讨论
Wiki
分析
Star626
320
已合并
docs(dsl): 优化DSL文档部分表述，修复无序列表的缩进问题 #1233
yuantao创建于 27 天前
docs(dsl): 优化DSL文档部分表述，修复无序列表的缩进问题 #1233
已合并
yuantao创建于 27 天前
从yuantao_/catlassdocs/dsl_quickstart合入到cann/catlassmaster
共 14 个文件变更+282-270
A.editorconfig+9-0
@@ -0,0 +1,9 @@
1+root = true
2+ 
3+[*]
4+indent_style = space
5+indent_size = 4
6+ 
7+[*.md]
8+indent_style = space
9+indent_size = 4
Mpython/tla_dsl/README.md+7-11
@@ -6,13 +6,10 @@ CATLASS DSL 是 CATLASS 的 Python 前端。它在 AscendNPU-IR 的基础上构
6 6 
7## 文档7## 文档
8 8 
9-- [环境准备](docs/zh/dsl_development/build_guide/index.md)：环境要求及安装入口。9+- [**快速开始**](docs/zh/quick_start.md)：安装与首个示例
10-- [编译与测试](docs/zh/dsl_development/build_guide/index.md)：构建、pytest、lit 和端到端用例。10+- [**Kernel 开发指南**](docs/zh/kernel_development/index.md)：核心概念（语法约束、控制流、Layout、Tensor 接入、编译启动）与调测优化
11-- [Host API 参考](docs/zh/api/host_api_reference.md)：Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。11+- [**DSL 框架开发指南**](docs/zh/dsl_development/index.md)：环境搭建、构建测试、特性开发、进阶 CMake 调试
12-- [Kernel API 参考](docs/zh/api/kernel_api_reference.md)：Kernel 侧 Core API。12+- [**API 文档**](docs/zh/api/index.md)：Kernel / Host API 参考与文档生成
13-- [API 文档生成](docs/zh/api/generate_api_docs.md)：从源码 docstring 重新生成英文 API 参考。
14-- [AscendNPU-IR 构建](docs/zh/dsl_development/build_guide/ascend_npu_ir.md)：手动构建AscendNPU-IR。
15-- [手动 CMake 构建](docs/zh/dsl_development/advanced/manual_cmake_build.md)：直接配置 `csrc/mlir` 的进阶用法。
16 13 
17## 快速开始14## 快速开始
18 15 
@@ -32,7 +29,7 @@ CATLASS DSL 各版本支持的硬件平台及所需的最低 CANN 版本如下
32- 系统：CANN 支持的 Linux29- 系统：CANN 支持的 Linux
33- 软件依赖：Python `>= 3.10, < 3.14`、CMake `>= 3.28, < 4.0`、Ninja `>= 1.12`、Clang / Clang++ `>= 10`（构建 AscendNPU-IR 时；推荐 19）、lld、lit、FileCheck 与 LLVM 配套、AscendNPU-IR `feature/regbase@a07821269…`30- 软件依赖：Python `>= 3.10, < 3.14`、CMake `>= 3.28, < 4.0`、Ninja `>= 1.12`、Clang / Clang++ `>= 10`（构建 AscendNPU-IR 时；推荐 19）、lld、lit、FileCheck 与 LLVM 配套、AscendNPU-IR `feature/regbase@a07821269…`
34 31 
35-完整的环境要求与安装方式见[环境准备](docs/zh/dsl_development/build_guide/index.md#构建环境要求)。32+完整的环境要求与安装方式见[环境准备](docs/zh/dsl_development/build_guide/environment.md)。
36 33 
37## 目录概览34## 目录概览
38 35 
@@ -41,12 +38,11 @@ python/tla_dsl/
41├── 3rdparty/AscendNPU-IR/ # AscendNPU-IR 子模块38├── 3rdparty/AscendNPU-IR/ # AscendNPU-IR 子模块
42├── catlass/ # Python 前端与运行时39├── catlass/ # Python 前端与运行时
43├── csrc/mlir/ # TLA Dialect 与编译器实现40├── csrc/mlir/ # TLA Dialect 与编译器实现
44-├── docs/zh/ # 中文文档41+├── docs/ # 文档
45-├── docs/en/ # 英文文档
46├── examples/ # 端到端示例42├── examples/ # 端到端示例
47├── tests/ # 单元、lit 与端到端测试43├── tests/ # 单元、lit 与端到端测试
48├── Dockerfile # 开发环境镜像定义44├── Dockerfile # 开发环境镜像定义
49├── build_docker_image.sh # 镜像构建入口45├── build_docker_image.sh # 镜像构建入口
50├── build.sh # 项目构建入口46├── build.sh # 项目构建入口
51-└── requirements.txt # 非 CANN Python 依赖47+└── requirements.txt # 开发 Python 依赖
52```48```
Mpython/tla_dsl/docs/zh/dsl_development/advanced/manual_cmake_build.md+1-1
@@ -4,7 +4,7 @@ nav_order: 50
4 4 
5# CMake 目标调试5# CMake 目标调试
6 6 
7-TLA DSL 通过 [`build.sh`](../build_guide/index.md#构建-catlass-dsl) 统一准备 AscendNPU-IR 路径并配置 CMake。本文面向需要单独编译 CMake 目标或运行编译器回归测试的开发者。7+TLA DSL 通过 [`build.sh`](../build_guide/build.md) 统一准备 AscendNPU-IR 路径并配置 CMake。本文面向需要单独编译 CMake 目标或运行编译器回归测试的开发者。
8 8 
9## 配置和编译9## 配置和编译
10 10 
Mpython/tla_dsl/docs/zh/dsl_development/build_guide/ascend_npu_ir.md+2-2
@@ -6,7 +6,7 @@ nav_order: 40
6 6 
7CATLASS DSL 基于 AscendNPU-IR 的 Dialect 构建 TLA Dialect。构建所需的源码头文件、生成头文件、静态库、MLIR CMake 包和 Python bindings 均来自 AscendNPU-IR。7CATLASS DSL 基于 AscendNPU-IR 的 Dialect 构建 TLA Dialect。构建所需的源码头文件、生成头文件、静态库、MLIR CMake 包和 Python bindings 均来自 AscendNPU-IR。
8 8 
9-AscendNPU-IR 的版本以 CATLASS 锁定的 revision 为准（即 `.gitmodules` 中 `python/tla_dsl/3rdparty/AscendNPU-IR` 指向的提交 `feature/regbase@a07821269…`）。具体的环境版本要求统一见[环境准备](index.md#构建环境要求)。9+AscendNPU-IR 的版本以 CATLASS 锁定的 revision 为准（即 `.gitmodules` 中 `python/tla_dsl/3rdparty/AscendNPU-IR` 指向的提交 `feature/regbase@a07821269…`）。具体的环境版本要求统一见[环境准备](environment.md#构建环境要求)。
10 10 
11## 获取源码11## 获取源码
12 12 
@@ -73,4 +73,4 @@ test -f build/install/lib/libMLIRHIVMDialect.a
73export CATLASS_DSL_PREBUILT_ASCENDNPU_IR="$PWD"73export CATLASS_DSL_PREBUILT_ASCENDNPU_IR="$PWD"
74```74```
75 75 
76-然后返回 DSL 子项目并按照[编译与测试](index.md)继续。76+然后返回 DSL 子项目并按照[构建 CATLASS DSL](build.md)和[运行测试用例](testing.md)继续。
Apython/tla_dsl/docs/zh/dsl_development/build_guide/build.md+43-0
@@ -0,0 +1,43 @@
1+---
2+nav_order: 20
3+---
4+ 
5+# 构建 CATLASS DSL
6+ 
7+除特别说明外，命令均在 `/path/to/catlass/python/tla_dsl` 执行，其中 `/path/to/catlass` 需替换为你 clone 的 CATLASS 仓库根目录。
8+ 
9+## Development 模式构建（开发态）
10+ 
11+```bash
12+cd /path/to/catlass/python/tla_dsl
13+./build.sh
14+# 强制清理并重新构建
15+./build.sh --clean
16+```
17+ 
18+`build.sh` 默认执行 Development 模式构建，主要步骤为：
19+ 
20+1. 检查 `ASCEND_HOME_PATH` 和 AscendNPU-IR 构建产物。
21+2. 在 `csrc/mlir/build` 中构建编译器和 Python 扩展。
22+3. 以 editable 模式安装 `ascend-catlass-dsl`，且不重复安装依赖。
23+ 
24+- `--clean` 会删除 DSL 子项目中的 `build/`、`csrc/mlir/build/`、`dist/`、egg-info、pytest 缓存和二进制库（`_tla_type_bridge_native*.so`）后，再执行 Development 模式构建。
25+ 
26+构建成功后可检查关键产物：
27+ 
28+```bash
29+test -x csrc/mlir/build/tools/tla-compile/TlaCompile
30+test -n "$(find csrc/mlir/build/python/catlass -name '_tla_type_bridge_native*.so' -print -quit)"
31+python -c "from catlass import tla"
32+```
33+ 
34+以上命令均无任何输出、退出码为 `0`，即表示检查通过、产物就绪。
35+ 
36+## Release 模式
37+ 
38+```bash
39+./build.sh --release
40+ls dist/*.whl
41+```
42+ 
43+Release 模式在 `dist/` 生成 wheel。
Mpython/tla_dsl/docs/zh/dsl_development/build_guide/conda.md+5-7
@@ -4,7 +4,10 @@ nav_order: 20
4 4 
5# 使用 Conda 构建开发环境5# 使用 Conda 构建开发环境
6 6 
7-Conda 环境本身**不安装** CANN Toolkit，需要你自行安装（见第 2 节加载 CANN）。NPU 示例还依赖驱动文件和设备节点。7+使用Conda构建开发环境，不包括以下内容:
8+- CANN Toolkit
9+- AscendNPU-IR
10+- torch/torch_npu
8 11 
9## 创建环境12## 创建环境
10 13 
@@ -45,10 +48,5 @@ test -n "${ASCEND_HOME_PATH}"
45export CATLASS_DSL_PREBUILT_ASCENDNPU_IR="/path/to/catlass/python/tla_dsl/3rdparty/AscendNPU-IR"48export CATLASS_DSL_PREBUILT_ASCENDNPU_IR="/path/to/catlass/python/tla_dsl/3rdparty/AscendNPU-IR"
46```49```
47 50 
48-这些环境设置对当前 shell 生效。51+## 安装 torch/torch_npu
49- 
50-## 构建与测试
51- 
52-[编译与测试](index.md)说明项目构建和各类测试入口。
53- 
54运行 NPU 示例时，按照 [PyTorch Ascend 安装部署](https://www.hiascend.com/developer/software/ai-frameworks/pytorch/download)安装与 CANN 和驱动匹配的 `torch`、`torch-npu`。52运行 NPU 示例时，按照 [PyTorch Ascend 安装部署](https://www.hiascend.com/developer/software/ai-frameworks/pytorch/download)安装与 CANN 和驱动匹配的 `torch`、`torch-npu`。
Mpython/tla_dsl/docs/zh/dsl_development/build_guide/docker.md+36-44
@@ -4,9 +4,7 @@ nav_order: 30
4 4 
5# 使用 Docker 构建开发环境5# 使用 Docker 构建开发环境
6 6 
7-Docker 配置基于与目标设备、驱动和 Python 版本匹配的 CANN 基础镜像。7+使用Docker构建的开发环境，包含全部开发运行所需的依赖，但不包含 CATLASS 源码，启动时需从宿主机挂载，或自行克隆。
8- 
9-项目镜像会安装 LLVM 工具链、Python 依赖、`torch`、`torch-npu` 和 AscendNPU-IR。镜像不包含 CATLASS 源码，启动时从宿主机挂载。
10 8 
11## 构建镜像9## 构建镜像
12 10 
@@ -20,59 +18,53 @@ bash build_docker_image.sh swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0
20 18 
21基础镜像名称只是示例。请从 [AscendHub](https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884) 选择与设备、驱动和 Python 版本匹配的 CANN 镜像，并将完整名称作为第一个参数。输出镜像为 `ascend-catlass-dsl:<基础镜像 tag>`。19基础镜像名称只是示例。请从 [AscendHub](https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884) 选择与设备、驱动和 Python 版本匹配的 CANN 镜像，并将完整名称作为第一个参数。输出镜像为 `ascend-catlass-dsl:<基础镜像 tag>`。
22 20 
23-脚本支持替换软件源、指定 LLVM 版本、调整构建并发数和目标平台：21+若您处于中国大陆，建议追加 `--default-mirror` 使用镜像源加速。可阅读脚本内容，更具体地了解镜像配置。
24 22 
25```bash23```bash
26-bash build_docker_image.sh swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-950-ubuntu22.04-py3.12 --help24+bash build_docker_image.sh swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-950-ubuntu22.04-py3.12 --default-mirror
27```25```
28 26 
29AscendNPU-IR 构建耗时和资源占用较高。内存或磁盘 I/O 有限时，通过 `--build-jobs` 降低并发数。27AscendNPU-IR 构建耗时和资源占用较高。内存或磁盘 I/O 有限时，通过 `--build-jobs` 降低并发数。
30 28 
31-## 启动编译容器29+## 启动容器
32- 
33-只进行 DSL 构建、pytest 或 lit 时，不需要挂载 NPU 设备：
34 30 
35```bash31```bash
36-# 镜像名与 tag 需与第 1 节构建产物（ascend-catlass-dsl:<基础镜像 tag>）一致，此处仅为例示32+docker run \
37-# 容器名可自行指定，多人共用宿主机时避免重名33+ --rm \
38-docker run \34+ --name ascend-catlass-dsl-dev \
39- --rm \35+ --device /dev/davinci0 \
40- --name ascend-catlass-dsl-dev \36+ --device /dev/davinci_manager \
41- -v /path/to/catlass:/workspace/catlass \37+ --device /dev/hisi_hdc \
42- -w /workspace/catlass/python/tla_dsl \38+ -v /usr/local/dcmi:/usr/local/dcmi \
39+ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
40+ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
41+ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
42+ -v /etc/ascend_install.info:/etc/ascend_install.info \
43+ -v /path/to/catlass:/workspace/catlass \
44+ -w /workspace/catlass/python/tla_dsl \
43 -it ascend-catlass-dsl:9.1.0-950-ubuntu22.04-py3.12 bash45 -it ascend-catlass-dsl:9.1.0-950-ubuntu22.04-py3.12 bash
44```46```
45 47 
46-容器内的关键环境：48+若您使用的是基于Ascend950系列芯片的超节点设备，例如[Atlas 950 SuperPoD 液冷超节点](https://www.hiascend.com/hardware/cluster?tag=950)或[Atlas 850E 风冷超节点](https://www.hiascend.com/hardware/cluster?tag=850e)，可能需要额外挂载灵渠总线相关的设备：
47 49 
48-```bash50+```diff
49-# 以下命令均无输出、退出码为 0 即表示环境就绪；失败时退出码非零并输出错误信息51+docker run \
50-test -n "${ASCEND_HOME_PATH}"52+ --rm \
51-test -n "${CATLASS_DSL_PREBUILT_ASCENDNPU_IR}"53+ --name ascend-catlass-dsl-dev \
52-test -f "${CATLASS_DSL_PREBUILT_ASCENDNPU_IR}/build/install/lib/cmake/mlir/MLIRConfig.cmake"54+ --device /dev/davinci0 \
53-```55+ --device /dev/davinci_manager \
54- 56+ --device /dev/hisi_hdc \
55-[编译与测试](index.md)说明项目构建和各类测试入口。57++ --device /dev/ubcore \
56- 58++ --device /dev/uburma \
57-## 启动上板容器59++ --device /dev/ummu \
58- 60+ -v /usr/local/dcmi:/usr/local/dcmi \
59-运行 NPU 端到端示例时，需要透传设备节点和宿主机驱动文件：61+ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
60- 62+ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
61-```bash63+ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
62-docker run \64+ -v /etc/ascend_install.info:/etc/ascend_install.info \
63- --rm \65+ -v /path/to/catlass:/workspace/catlass \
64- --name ascend-catlass-dsl-dev \66+ -w /workspace/catlass/python/tla_dsl \
65- --device /dev/davinci0 \
66- --device /dev/davinci_manager \
67- --device /dev/hisi_hdc \
68- -v /usr/local/dcmi:/usr/local/dcmi \
69- -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
70- -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
71- -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
72- -v /etc/ascend_install.info:/etc/ascend_install.info \
73- -v /path/to/catlass:/workspace/catlass \
74- -w /workspace/catlass/python/tla_dsl \
75 -it ascend-catlass-dsl:9.1.0-950-ubuntu22.04-py3.12 bash67 -it ascend-catlass-dsl:9.1.0-950-ubuntu22.04-py3.12 bash
76```68```
77 69 
78-设备节点和驱动路径以宿主机的 CANN/驱动安装为准。容器内可通过 `npu-smi info` 检查设备，再运行 [NPU 端到端示例](index.md#完整的端到端测试)。70+驱动路径以宿主机的实际安装路径为准；容器内可通过 `npu-smi info` 检查设备。
Apython/tla_dsl/docs/zh/dsl_development/build_guide/environment.md+64-0
@@ -0,0 +1,64 @@
1+---
2+nav_order: 10
3+---
4+ 
5+# 环境准备
6+ 
7+本文档介绍 CATLASS DSL 的构建环境要求与环境检查方法。
8+ 
9+## 快速准备构建环境
10+ 
11+可选择下列两种快速准备方式，
12+ 
13+- [Conda 安装](conda.md)：使用仓库的 `environment.yml` 创建开发环境
14+ - 需手动安装CANN和[构建 AscendNPU-IR](ascend_npu_ir.md)
15+- [Docker 安装](docker.md)：使用 Docker 构建开发镜像
16+ - 包含完整开发依赖
17+ 
18+下文将列出所需的所有依赖软件，可根据实际环境自行选择安装方式。
19+ 
20+## 构建环境要求
21+ 
22+CATLASS DSL 仅支持 Ascend950 系列产品。
23+ 
24+| 组件 | 版本或要求 |
25+| --- | --- |
26+| CANN | `>=9.1.0` |
27+| Python | `>=3.10,<3.14` |
28+| CMake | `>=3.28,<4.0` |
29+| Ninja | `>=1.12` |
30+| clang/lld | `>=10`(推荐 `19.1.7`) |
31+| AscendNPU-IR | `feature/regbase@a07821269ede7a5e683ac02c8a2d291608083741` |
32+| numpy | `>=2` |
33+| pybind11 | `2.13.6` |
34+ 
35+- 若需执行纯Host测试用例，还需安装`pytest`
36+- 若需执行端到端测试用例，还需安装`torch`和配套的`torch_npu`，参考[PyTorch Ascend安装部署](https://www.hiascend.com/developer/software/ai-frameworks/pytorch/download)
37+ 
38+## 环境检查
39+ 
40+基础环境检查：
41+ 
42+```bash
43+python --version
44+clang --version
45+clang++ --version
46+lld --version
47+cmake --version
48+ninja --version
49+test -n "${ASCEND_HOME_PATH}"
50+test -f "python/tla_dsl/3rdparty/AscendNPU-IR/build/install/lib/cmake/mlir/MLIRConfig.cmake" || \
51+ test -f "${CATLASS_DSL_PREBUILT_ASCENDNPU_IR}/build/install/lib/cmake/mlir/MLIRConfig.cmake"
52+python -c "import numpy"
53+```
54+ 
55+以上命令均无任何输出、退出码为 `0`，即表示环境就绪；否则将输出错误信息。
56+ 
57+运行端到端示例还需要：
58+ 
59+```bash
60+npu-smi info
61+python -c "import torch; import torch_npu"
62+```
63+ 
64+输出NPU信息，无Python相关报错，则代表依赖就绪。
Mpython/tla_dsl/docs/zh/dsl_development/build_guide/index.md+13-174
@@ -4,181 +4,20 @@ nav_order: 10
4 4 
5# 环境准备与构建5# 环境准备与构建
6 6 
7-本文档介绍如何准备开发环境、构建 CATLASS DSL 并运行测试，包括安装依赖、配置环境变量等。7+本目录介绍如何准备开发环境、构建 CATLASS DSL 并运行测试。
8 8 
9-## 快速准备构建环境9+## 环境搭建
10 10 
11-可选择下列两种快速准备方式，11+| 文档 | 范围 |
12+|------|------|
13+| [环境准备](environment.md) | 环境要求总表、依赖软件与环境检查。 |
14+| [Conda 安装](conda.md) | 使用仓库 `environment.yml` 创建开发环境（不含 CANN 与 AscendNPU-IR）。 |
15+| [Docker 安装](docker.md) | 使用仓库 `Dockerfile` 构建开发镜像，包含任何开发依赖。 |
16+| [构建 AscendNPU-IR](ascend_npu_ir.md) | 手动构建 DSL 所依赖的 AscendNPU-IR。 |
12 17 
13-- [Conda 安装](conda.md)：使用仓库的 `environment.yml` 创建开发环境18+## 构建与测试
14- - 需手动安装CANN和[构建 AscendNPU-IR](ascend_npu_ir.md)
15-- [Docker 安装](docker.md)：使用 Docker 构建开发镜像
16- - 包含完整开发依赖
17 19 
18-下文将列出所需的所有依赖软件，可根据实际环境自行选择安装方式。20+| 文档 | 范围 |
19- 21+|------|------|
20-## 构建环境要求22+| [构建 CATLASS DSL](build.md) | `./build.sh` 构建（Development / Release 模式）、产物检查。 |
21- 23+| [运行测试用例](testing.md) | pytest、lit test 与端到端验证。 |
22-CATLASS DSL 仅支持 Ascend950 系列产品。
23- 
24-| 组件 | 版本或要求 |
25-| --- | --- |
26-| CANN | `>=9.1.0` |
27-| Python | `>=3.10,<3.14` |
28-| CMake | `>=3.28,<4.0` |
29-| Ninja | `>=1.12` |
30-| clang/lld | `>=10`(推荐 `19.1.7`) |
31-| AscendNPU-IR | `feature/regbase@a07821269ede7a5e683ac02c8a2d291608083741` |
32-| numpy | `>=2` |
33-| pybind11 | `2.13.6` |
34- 
35-- 若需执行纯Host测试用例，还需安装`pytest`
36-- 若需执行端到端测试用例，还需安装`torch`和配套的`torch_npu`，参考[PyTorch Ascend安装部署](https://www.hiascend.com/developer/software/ai-frameworks/pytorch/download)
37- 
38-## 环境检查
39- 
40-基础环境检查：
41- 
42-```bash
43-python --version
44-clang --version
45-clang++ --version
46-lld --version
47-cmake --version
48-ninja --version
49-test -n "${ASCEND_HOME_PATH}"
50-test -f "python/tla_dsl/3rdparty/AscendNPU-IR/build/install/lib/cmake/mlir/MLIRConfig.cmake" || \
51- test -f "${CATLASS_DSL_PREBUILT_ASCENDNPU_IR}/build/install/lib/cmake/mlir/MLIRConfig.cmake"
52-python -c "import numpy"
53-```
54- 
55-以上命令均无任何输出、退出码为 `0`，即表示环境就绪；否则将输出错误信息。
56- 
57-运行端到端示例还需要：
58- 
59-```bash
60-npu-smi info
61-python -c "import torch; import torch_npu"
62-```
63- 
64-输出NPU信息，无Python相关报错，则代表依赖就绪。
65- 
66-## 构建 CATLASS DSL
67- 
68-除特别说明外，命令均在 `/path/to/catlass/python/tla_dsl` 执行，其中 `/path/to/catlass` 需替换为你 clone 的 CATLASS 仓库根目录。
69- 
70-### Development 模式构建（开发态）
71- 
72-```bash
73-cd /path/to/catlass/python/tla_dsl
74-./build.sh
75-# 强制清理并重新构建
76-./build.sh --clean
77-```
78- 
79-`build.sh` 默认执行 Development 模式构建，主要步骤为：
80- 
81-1. 检查 `ASCEND_HOME_PATH` 和 AscendNPU-IR 构建产物。
82-2. 在 `csrc/mlir/build` 中构建编译器和 Python 扩展。
83-3. 以 editable 模式安装 `ascend-catlass-dsl`，且不重复安装依赖。
84- 
85-- `--clean` 会删除 DSL 子项目中的 `build/`、`csrc/mlir/build/`、`dist/`、egg-info、pytest 缓存和二进制库（`_tla_type_bridge_native*.so`）后，再执行 Development 模式构建。
86- 
87-构建成功后可检查关键产物：
88- 
89-```bash
90-test -x csrc/mlir/build/tools/tla-compile/TlaCompile
91-test -n "$(find csrc/mlir/build/python/catlass -name '_tla_type_bridge_native*.so' -print -quit)"
92-python -c "from catlass import tla"
93-```
94- 
95-以上命令均无任何输出、退出码为 `0`，即表示检查通过、产物就绪。
96- 
97-### Release模式
98- 
99-```bash
100-./build.sh --release
101-ls dist/*.whl
102-```
103- 
104-Release 模式在 `dist/` 生成 wheel。
105- 
106-## 运行测试用例
107- 
108-### pytest：前端降级到TLA IR
109- 
110-```bash
111-cd /path/to/catlass/python/tla_dsl
112-python -m pytest -q tests
113-```
114- 
115-运行单个测试文件时使用相同入口，例如：
116- 
117-```bash
118-python -m pytest -q tests/test_frontend_lowering.py
119-```
120- 
121-### lit test：TLA IR 降级到 NPUIR
122- 
123-```bash
124-lit -sv csrc/mlir/build/tests/lit
125-```
126- 
127-### e2e test：端到端验证
128- 
129-- 该测试额外依赖NPU环境，并且需要安装`torch` / `torch-npu`。
130- 
131-```bash
132-cd /path/to/catlass/python/tla_dsl
133-python examples/end_to_end/basic_mmad/basic_matmul.py --device 0
134-```
135- 
136-指定矩阵shape、layout和数据类型：
137- 
138-```bash
139-python examples/end_to_end/basic_mmad/basic_matmul.py \
140- --device 0 \
141- --m 256 --n 512 --k 128 \
142- --layout-a row --layout-b col \
143- --dtype-a f16 --dtype-b f16 --dtype-c f32
144-```
145- 
146-成功时输出包含：
147- 
148-```text
149-passed=True cache_key=<CACHE_KEY>
150-kernel.o=<CACHE_DIR>/<CACHE_KEY>/kernel.o
151-```
152- 
153-可用参数以脚本帮助为准：
154- 
155-```bash
156-python examples/end_to_end/basic_mmad/basic_matmul.py --help
157-```
158- 
159-### 完整的端到端测试
160- 
161-在 CATLASS 仓库根目录执行：
162- 
163-```bash
164-cd /path/to/catlass
165-bash tests/run_dsl_test.sh --device 0
166-```
167- 
168-该脚本会加载 CANN、检查 AscendNPU-IR、构建 DSL，并运行 `tests/dsl_battery` 上板回归测试。
169- 
170-常用变量如下：
171- 
172-| 变量 | 含义 |
173-| ----------------------------------- | -------------------------------------------------------- |
174-| `ASCEND_HOME_PATH` | CANN Toolkit 根目录；脚本也会尝试定位并加载 `set_env.sh` |
175-| `CATLASS_DSL_PREBUILT_ASCENDNPU_IR` | 共享的 AscendNPU-IR 源码与构建树根目录，作为仓库内子模块之后的回退路径 |
176-| `CATLASS_DSL_DIR` | DSL 子项目路径；默认从脚本位置推导 |
177-| `DEVICE_ID` | NPU device id；默认 `1`，可由 `--device` 覆盖 |
178-| `CATLASS_DSL_FORCE_RECOMPILE` | 是否强制重新编译运行时产物；脚本默认设为 `1` |
179- 
180-查看脚本当前支持的用例和路径解析规则：
181- 
182-```bash
183-bash tests/run_dsl_test.sh --help
184-```
Apython/tla_dsl/docs/zh/dsl_development/build_guide/testing.md+83-0
@@ -0,0 +1,83 @@
1+---
2+nav_order: 30
3+---
4+ 
5+# 运行测试用例
6+ 
7+## pytest：前端降级到TLA IR
8+ 
9+```bash
10+cd /path/to/catlass/python/tla_dsl
11+python -m pytest -q tests
12+```
13+ 
14+运行单个测试文件时使用相同入口，例如：
15+ 
16+```bash
17+python -m pytest -q tests/test_frontend_lowering.py
18+```
19+ 
20+## lit test：TLA IR 降级到 NPUIR
21+ 
22+```bash
23+lit -sv csrc/mlir/build/tests/lit
24+```
25+ 
26+## e2e test：端到端验证
27+ 
28+- 该测试额外依赖NPU环境，并且需要安装`torch` / `torch-npu`。
29+ 
30+```bash
31+cd /path/to/catlass/python/tla_dsl
32+python examples/end_to_end/basic_mmad/basic_matmul.py --device 0
33+```
34+ 
35+指定矩阵shape、layout和数据类型：
36+ 
37+```bash
38+python examples/end_to_end/basic_mmad/basic_matmul.py \
39+ --device 0 \
40+ --m 256 --n 512 --k 128 \
41+ --layout-a row --layout-b col \
42+ --dtype-a f16 --dtype-b f16 --dtype-c f32
43+```
44+ 
45+成功时输出包含：
46+ 
47+```text
48+passed=True cache_key=<CACHE_KEY>
49+kernel.o=<CACHE_DIR>/<CACHE_KEY>/kernel.o
50+```
51+ 
52+可用参数以脚本帮助为准：
53+ 
54+```bash
55+python examples/end_to_end/basic_mmad/basic_matmul.py --help
56+```
57+ 
58+## 完整的端到端测试
59+ 
60+在 CATLASS 仓库根目录执行：
61+ 
62+```bash
63+cd /path/to/catlass
64+bash tests/run_dsl_test.sh --device 0
65+```
66+ 
67+该脚本会加载 CANN、检查 AscendNPU-IR、构建 DSL，并运行 `tests/dsl_battery` 上板回归测试。
68+ 
69+常用变量如下：
70+ 
71+| 变量 | 含义 |
72+| ----------------------------------- | -------------------------------------------------------- |
73+| `ASCEND_HOME_PATH` | CANN Toolkit 根目录；脚本也会尝试定位并加载 `set_env.sh` |
74+| `CATLASS_DSL_PREBUILT_ASCENDNPU_IR` | 共享的 AscendNPU-IR 源码与构建树根目录，作为仓库内子模块之后的回退路径 |
75+| `CATLASS_DSL_DIR` | DSL 子项目路径；默认从脚本位置推导 |
76+| `DEVICE_ID` | NPU device id；默认 `1`，可由 `--device` 覆盖 |
77+| `CATLASS_DSL_FORCE_RECOMPILE` | 是否强制重新编译运行时产物；脚本默认设为 `1` |
78+ 
79+查看脚本当前支持的用例和路径解析规则：
80+ 
81+```bash
82+bash tests/run_dsl_test.sh --help
83+```
Mpython/tla_dsl/docs/zh/dsl_development/index.md+3-2
@@ -12,15 +12,16 @@ nav_order: 30
12 12 
13| 文档 | 范围 |13| 文档 | 范围 |
14|------|------|14|------|------|
15+| [环境准备](build_guide/environment.md) | 环境要求总表、依赖软件与环境检查。 |
15| [Conda 安装](build_guide/conda.md) | 使用仓库 `environment.yml` 创建开发环境（不含 CANN 与 AscendNPU-IR）。 |16| [Conda 安装](build_guide/conda.md) | 使用仓库 `environment.yml` 创建开发环境（不含 CANN 与 AscendNPU-IR）。 |
16| [Docker 安装](build_guide/docker.md) | 使用仓库 `Dockerfile` 构建开发镜像，包含任何开发依赖。 |17| [Docker 安装](build_guide/docker.md) | 使用仓库 `Dockerfile` 构建开发镜像，包含任何开发依赖。 |
17-| [环境准备](build_guide/index.md) | 环境要求总表、安装方式入口与环境检查。 |
18 18 
19## 构建与测试19## 构建与测试
20 20 
21| 文档 | 范围 |21| 文档 | 范围 |
22|------|------|22|------|------|
23-| [编译 CATLASS DSL 与运行测试](build_guide/index.md) | `./build.sh` 构建、pytest、lit 与 NPU 端到端示例。 |23+| [构建 CATLASS DSL](build_guide/build.md) | `./build.sh` 构建（Development / Release 模式）、产物检查。 |
24+| [运行测试用例](build_guide/testing.md) | pytest、lit test 与端到端验证。 |
24| [构建 AscendNPU-IR](build_guide/ascend_npu_ir.md) | 手动构建 DSL 所依赖的 AscendNPU-IR。 |25| [构建 AscendNPU-IR](build_guide/ascend_npu_ir.md) | 手动构建 DSL 所依赖的 AscendNPU-IR。 |
25| [手动 CMake 构建](advanced/manual_cmake_build.md) | 直接配置 `csrc/mlir` 的进阶用法。 |26| [手动 CMake 构建](advanced/manual_cmake_build.md) | 直接配置 `csrc/mlir` 的进阶用法。 |
26 27 
Mpython/tla_dsl/docs/zh/index.md+3-2
@@ -9,8 +9,9 @@ nav_order: 0
9| 文档 | 范围 |9| 文档 | 范围 |
10|-----|--------|10|-----|--------|
11| [快速开始](quick_start.md) | 兼容性要求、安装方式与首个示例的最短路径。 |11| [快速开始](quick_start.md) | 兼容性要求、安装方式与首个示例的最短路径。 |
12-| [环境准备](dsl_development/build_guide/index.md) | 环境要求、安装方式（Conda / Docker）与最短上手路径。 |12+| [环境准备](dsl_development/build_guide/environment.md) | 环境要求、安装方式（Conda / Docker）与最短上手路径。 |
13-| [编译与测试](dsl_development/build_guide/index.md) | `./build.sh` 构建、pytest、lit 与 NPU 端到端示例。 |13+| [构建 CATLASS DSL](dsl_development/build_guide/build.md) | `./build.sh` 构建（Development / Release 模式）、产物检查。 |
14+| [运行测试用例](dsl_development/build_guide/testing.md) | pytest、lit test 与端到端验证。 |
14| [Kernel API 参考](api/kernel_api_reference.md) | Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 |15| [Kernel API 参考](api/kernel_api_reference.md) | Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 |
15| [Host API 参考](api/host_api_reference.md) | Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。 |16| [Host API 参考](api/host_api_reference.md) | Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。 |
16| [Host Tensor 接入](kernel_development/core_concepts/tensor_binding.md) | Host 侧 `from_dlpack` / `make_fake_tensor`，供 `tla.compile` / 启动使用。 |17| [Host Tensor 接入](kernel_development/core_concepts/tensor_binding.md) | Host 侧 `from_dlpack` / `make_fake_tensor`，供 `tla.compile` / 启动使用。 |
Mpython/tla_dsl/docs/zh/kernel_development/evaluation/index.md+12-26
@@ -1,26 +1,12 @@
1----1+---
2-nav_order: 202+nav_order: 20
3----3+---
4- 4+ 
5-# 调试与优化5+# 调试与优化
6- 6+ 
7-本文档介绍 CATLASS DSL 算子开发中的通用调试调优手段。7+CATLASS DSL 算子开发中的调试与性能调优。
8- 8+ 
9-## 调试思路9+| 文档 | 范围 |
10- 10+|------|------|
11-建议遵循“先功能、后性能”的开发流程：11+| [调试打印](print.md) | kernel 内 `tla.print` 调试标量、格式化字符串与 Tensor。 |
12- 12+| [性能分析工具](performance_tools.md) | msProf 单算子性能分析与 Profiling 整网性能分析。 |
13-1. **功能验证**：用较小的 shape 先跑通编译与执行，通过打印输出确认数据流与控制流正确。
14-2. **性能采集**：功能正确后，用性能分析工具采集算子耗时、流水利用与内存搬运等指标。
15-3. **瓶颈定位**：结合指标与 kernel 结构定位瓶颈，逐项优化后复测。
16- 
17-## 功能调试
18- 
19-- [打印调试](print.md)：使用 `tla.print` 在 kernel 内部打印标量、格式化字符串与 Tensor，适合定位运行时数据流与控制流问题。
20-- 该方案无需额外工具，编译运行即可查看输出，是功能调试的首选手段。
21- 
22-## 性能调优
23- 
24-- [性能分析工具](performance_tools.md)：基于 [msProf](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/850/devaids/Profiling/atlasprofiling_16_0010.html)（单算子）与 [Profiling](https://www.hiascend.com/document/detail/zh/canncommercial/850/graph/graphdevg/atlasag_25_0056.html)（整网）采集并分析算子性能
25- - [单算子性能分析：msProf](performance_tools.md#用msprof进行单算子性能分析)
26- - [整网性能分析：Profiling](performance_tools.md#用profiling进行整网性能分析)
Mpython/tla_dsl/docs/zh/kernel_development/evaluation/performance_tools.md+1-1
@@ -27,7 +27,7 @@ nav_order: 20
27### 基础依赖使能27### 基础依赖使能
28 28 
29在进行 DSL 开发与测试前，请先行确认基础环境已准备完毕。详细步骤请参考 [快速上手](../../../../../../docs/zh/1_Practice/01_quick_start.md)，完成 CANN 的下载安装与环境变量使能。29在进行 DSL 开发与测试前，请先行确认基础环境已准备完毕。详细步骤请参考 [快速上手](../../../../../../docs/zh/1_Practice/01_quick_start.md)，完成 CANN 的下载安装与环境变量使能。
30-DSL 的底层编译依赖于 AscendNPU-IR。在执行后续编译操作前，请参阅 [环境准备](../../../../docs/zh/dsl_development/build_guide/index.md) 并按该文档指引完成至 [运行测试用例](../../../../docs/zh/dsl_development/build_guide/index.md#运行测试用例) 相关内容。30+DSL 的底层编译依赖于 AscendNPU-IR。在执行后续编译操作前，请参阅 [环境准备](../../dsl_development/build_guide/environment.md) 并按该文档指引完成至 [运行测试用例](../../dsl_development/build_guide/testing.md) 相关内容。
31 31 
32## 用msProf进行单算子性能分析32## 用msProf进行单算子性能分析
33 33