| feat: migrate fast kernel launch example to ASC CMake
Co-authored-by: zhangzijie<zhangzijie11@hisilicon.com>
# message auto-generated for no-merge-commit merge:
!2520 merge feature/fast-kernel-launch-asc into master
feat: migrate fast kernel launch example to ASC CMake
Created-by: zhangzijie
Commit-by: zhangzijie
Merged-by: cann-robot
Description: ## 描述
将 examples/fast_kernel_launch_example 迁移到 CMake 原生 ASC 语言构建，并整理 Fast Kernel Launch 示例的算子构建组织方式：
- 将 add/sqrt/gelu/layer_norm 算子实现从 .cpp 重命名为 .asc
- 顶层 CMake 使用 find_package(ASC REQUIRED) 和 project(... LANGUAGES C CXX ASC) 启用 ASC 语言
- 将示例算子目录从 ascend910b 收敛到编译器使用的 NPU_ARCH 命名，例如 dav-2201
- 将算子对象文件收集方式从全局 OBJECTS_LIST cache 变量改为 CMake object target + global property
- 构建入口优先使用 Ninja，并在 README 中补充 NPU_ARCH 和新增算子的开发方式
## Refactor 方案
### 1. 构建入口改为 CMake 原生 ASC 语言
原方案通过普通 C/CXX 工程、手动指定 bisheng 编译器、给 .cpp 源文件追加 -xasc 的方式触发 ASC 编译。该方式把 ASC 编译细节散落在自定义宏和全局变量中，新增算子时需要理解较多隐藏约定。
本次重构改为在顶层 CMakeLists.txt 中先加载 cmake/ascend.cmake，再执行：
```cmake
find_package(ASC REQUIRED)
project(${PKG_NAME} VERSION 1.0.0 LANGUAGES C CXX ASC)
```
这样 ASC 被声明为工程语言，.asc 源文件由 CMake/ASC 包正常识别，不再依赖 LANGUAGE CXX + -xasc 的绕行方式。cmake/ascend.cmake 只负责定位 Ascend Toolkit、bisheng 和默认 toolchain，ASC include/link 细节交给 find_package(ASC) 提供的能力处理。
### 2. NPU 架构命名从芯片名切换到编译器参数
原目录使用 ascend910b，但实际传给编译器的是 --npu-arch=dav-2201。这会让目录名、CMake 参数和编译器参数不一致。
本次重构统一使用编译器 --npu-arch 对应的取值作为目录名和构建参数：
- 默认 NPU_ARCH=dav-2201
- 支持 dav-2201 和 dav-3510
- 支持通过环境变量 NPU_ARCH 或 CMake cache 覆盖
- 配置阶段校验不支持的架构并直接报错
因此示例目录迁移为：
```text
csrc/<op_name>/<NPU_ARCH>/<op_name>.asc
```
当前 PR 中 add/sqrt/gelu/layer_norm 均迁移到 dav-2201 目录。
### 3. 算子发现从手写遍历改为按架构目录收敛
原 recursive_add_subdirectory() 会扫描 csrc 下每个算子的 ${NPU_ARCH}/CMakeLists.txt，但配合旧的 ascend910b 默认值时，目录名和真实编译参数存在错位。
新实现按如下规则发现算子：
```text
csrc/*/${NPU_ARCH}/CMakeLists.txt
```
并对结果排序后逐个 add_subdirectory()，保证构建输入稳定。如果当前架构下没有算子目录，会输出 warning，顶层仍可生成 dummy extension module，便于定位问题而不是在隐式变量处失败。
### 4. 算子编译单元改为 object target
原 add_sources() 宏会：
- 清理/重置部分全局 CMake 变量
- 递归查找 .cpp
- 手动设置 LANGUAGE CXX 和 COMPILE_FLAGS
- 将 $<TARGET_OBJECTS:...> 写入全局 cache 变量 OBJECTS_LIST
这类全局可变状态不利于维护，也容易受 CMake 配置顺序影响。
新方案提供：
```cmake
ascend_ops_add_current_op(OP_TARGET)
```
每个算子目录调用后会生成独立 object library，target 名包含算子名和 NPU_ARCH，例如 add_dav_2201_obj。函数内部负责：
- 查找当前目录下的 .asc 源文件
- 为该 object target 添加通用编译选项
- 显式追加 --npu-arch=${NPU_ARCH}
- 添加当前算子目录和公共 include 目录
- 将 object target 注册到全局 property ASCEND_OPS_OPERATOR_TARGETS
顶层 _C extension 再从 ASCEND_OPS_OPERATOR_TARGETS 中收集 $<TARGET_OBJECTS:${OPERATOR_TARGET}>，并在存在算子 target 时链接这些 target。这样算子自身需要的库可以留在各自目录，例如：
```cmake
ascend_ops_add_current_op(OP_TARGET)
target_link_libraries(${OP_TARGET} PUBLIC platform)
target_link_libraries(${OP_TARGET} PUBLIC tiling_api)
```
### 5. Python 构建入口保持轻量
setup.py 不再负责把 NPU_ARCH 翻译成 CMake 参数。架构选择统一留给 CMake 层处理，Python 侧只传入 Torch/Torch NPU 路径和构建类型。
同时 Python 构建入口优先选择 Ninja：
- 环境中存在 ninja 时使用 -G Ninja
- 否则回退到 Unix Makefiles
requirements.txt 补充 ninja，使示例默认构建路径更稳定。
### 6. 新增算子的维护方式
新增算子只需要按目标架构创建目录和 .asc 文件：
```text
csrc/<op_name>/<NPU_ARCH>/CMakeLists.txt
csrc/<op_name>/<NPU_ARCH>/<op_name>.asc
```
CMakeLists.txt 的最小内容为：
```cmake
ascend_ops_add_current_op(OP_TARGET)
```
如果算子需要额外库或编译选项，可继续对 ${OP_TARGET} 调用 target_link_libraries()、target_compile_options() 等 target 级 CMake API，不需要修改顶层对象列表或全局变量。
## 关联的Issue
无
## 测试
测试结果：
```text
119 passed, 1 warning in 6.80s
```
## 文档更新
更新 examples/fast_kernel_launch_example/README.md：
- 补充默认 NPU_ARCH=dav-2201、可通过环境变量覆盖，以及当前支持 dav-2201/dav-3510
- 将新增算子开发说明从 .cpp + add_sources("--npu-arch=...") 更新为 .asc + ascend_ops_add_current_op(OP_TARGET)
## 类型标签
- [ ] Bug修复
- [x] 新特性
- [ ] 性能优化
- [x] 文档更新
- [x] 其他，请描述：构建重构
See merge request: cann/ops-math!2520 | 1 个月前 |
