Metadata-Version: 2.4
Name: cannbot-dsl
Version: 0.7.0
Summary: Python DSL and MLIR compiler for AscendC kernels
Keywords: ascend,ascendc,compiler,dsl,mlir
Author: Huawei Technologies Co., Ltd.
License-Expression: LicenseRef-CANN-Open-Software-License-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown

# CANNBotDSL

## 1. 项目简介 (Introduction)

---

## 2. 目录结构 (Directory Structure)

---

## 3. 构建指南 (Build Instructions)

请根据目标独立阅读对应文档。开发与发行指南各自包含完整步骤，不互为前置。

| 目标 | 文档入口 |
| ---- | -------- |
| 新环境搭建、native CMake、editable 和增量编译（开发） | [构建与增量开发指南](docs/BUILD.md) |
| PEP 517 raw Wheel、auditwheel、验证和发布（发行） | [Wheel 构建与发布指南](docs/WHEEL.md) |
| 算子导出、编译工厂缓存与 ACLNN Host 接口 | [OpKit](opkit/README.md) |
| 运行时和调试环境变量 | [环境变量参考](docs/usage/ENV.md) |
| GM、片上内存和 raw VF 寄存器打印 | [原生 dump 使用说明](docs/native_dump.md) |
| 向 CANN profiling 工具上报 kernel 和 Tensor 元数据 | [Profiling Tensor 信息上报](docs/PROFILING.md) |
| Tensor 向量计算实验组件（暂时移除）及恢复方式 | [实验组件状态](docs/usage/EXPERIMENTAL.md) |
| host 侧硬件平台查询（SoC 版本、核数、片上存储容量） | [平台信息查询](docs/usage/PLATFORM.md) |
| `for` 循环、后端 unroll 与前端静态展开 | [循环与 UNROLL](docs/usage/LOOPS.md) |
| 自动分配与手动 view 绑定 | [片上存储接口](docs/usage/ONCHIP_STORAGE.md) |
| 片上存储标准化、容量边界与回归结果 | [标准化验收记录](docs/design/onchip_storage_standardization_validation.md) |
| 同核 Channel 显式游标、Tensor 与自动同步 | [Channel 使用说明](docs/usage/CHANNEL.md) |
| Tensor 下标、`None` keep 语义与迁移 | [Tensor 下标与切片](docs/tensor_indexing.md) |
| GM Tensor 轴排列零拷贝 view | [`permute` 设计与 API](docs/design/permute.md) |

CANNBotDSL 在 CANN 9.1/9.2 环境提供 `dump_tensor` 和 raw VF `dump_reg`，支持 GM、UB、L1、
L0C、BIAS、FIXBUF 地址分派与寄存器打印。自动 Channel、视图偏移、显示 shape、
地址对齐及 VF 缓冲预算均有对应校验。用法、测试命令和验证范围见
[原生 dump 使用说明](docs/native_dump.md)。

---

## 4. Submodule 管理 (Submodule Management)

`cannbot-arena` 通过 Git submodule 引入。父仓库会锁定其提交版本。

首次克隆仓库时，可以同时初始化 submodule：

```bash
git clone --recurse-submodules https://gitcode.com/mabing1118/cannbot-dsl.git
```

对于已经克隆的仓库，或在更新父仓库后，将 submodule 同步到父仓库锁定的版本：

```bash
git submodule update --init --recursive
```

维护者如需将 `cannbot-arena` 更新到上游最新版本，应检查变化并提交新的 submodule 指针：

```bash
git submodule update --remote cannbot-arena
git diff --submodule=log -- cannbot-arena
git add cannbot-arena
git commit -m "chore: update cannbot-arena submodule"
```

入口使用 `@host`，设备函数使用 `@kernel`，内联辅助函数使用 `@jit`。
迁移与调用矩阵见 [Host/kernel/JIT 调用约定](docs/usage/HOST_KERNEL_JIT.md)。
