Ascend C算子从昇腾910迁移到昇腾310P，往往不是简单地新增一个 SoC名称。Host注册、构建路由、kernel宏分支、DataCopy语义、dtype能力、tiling key和尾块写回都可能成为迁移过程中的隐性风险。
本文介绍的`op-ascend-migration`Skill，聚焦昇腾910到昇腾310P的迁移场景，提供一套从静态扫描、路线选择、兼容改造到验证交付的标准化流程。
背景介绍
随着昇腾硬件代际持续演进，越来越多已有Ascend C自定义算子需要从昇腾910路径扩展到昇腾310P。对开发者而言，迁移的难点并不只在“能不能编译”，更在于迁移后的能力边界是否清晰、源代际路径是否被保留、目标代际是否真正通过精度与功能验证。
在实际工程中，一个算子的代际支持通常分散在多个位置：Host侧 `AddConfig`、`opFile.value` 路由、CMake 和 `build.sh` 的 SoC 清单、kernel中的 `__CCE_AICORE__` 或 `__NPU_ARCH__` 分支、测试配置，以及算子内部的搬运和流水逻辑。人工逐项排查不仅耗时，也容易遗漏。
迁移挑战
以常见的昇腾910算子迁移到昇腾310P为例，开发者经常会遇到以下问题：
Host侧声明了昇腾310P，但kernel仍然误走源代际专用路径。
昇腾310P路径上仍然存在 `DataCopyPad` 或非32B对齐写回，导致尾块覆盖相邻逻辑输出的风险。
BF16、量化或其他dtype能力被机械复制，但昇腾310P 路径缺少kernel、tiling和精度验证结果。
构建、测试、SoC路由脚本没有同步更新，导致代码看似迁移完成，实际不会进入昇腾310P 验证链路。
只修改单个文件，没有形成可复查的改动清单、验证命令和残余风险说明。
因此，昇腾910到昇腾310P的迁移需要的不只是经验清单，而是一套能够主动发现风险、约束修改范围、沉淀验证结果的工程流程。
Skills架构设计
`op-ascend-migration` Skill将昇腾910到昇腾310P的迁移拆成“扫描识别、路线选择、分层改造、验证交付”四个核心环节。它的目标不是用模板覆盖所有场景，而是在不破坏源代际路径的前提下，帮助开发者选择最小足够的昇腾310P迁移方案。
阶段一：
静态扫描，先建立迁移画像
迁移开始前，Skill会优先运行静态扫描器 `scan_ascendc_migration.py`，对算子仓库或算子目录进行模式识别。扫描目标覆盖Host、kernel、构建脚本、测试配置和静态config文件，避免开发者一上来就陷入局部代码修改。
OP_ASCEND_MIGRATION_SKILL_DIR="/path/to/op-ascend-migration"python3 "$OP_ASCEND_MIGRATION_SKILL_DIR/scripts/scan_ascendc_migration.py" --target .
扫描器会统计 `AddConfig("ascend310p")`、`opFile.value`、`SUPPORT_COMPUTE_UNIT`、`ASCEND_SOC_UNITS`、`DataCopyPad`、`__CCE_AICORE__`、`__NPU_ARCH__`、`tilingKey`、`runtime_kb`、dtype 等模式，并输出审查提示。
阶段二：
路线选择，先确认昇腾310P改造边界
Skill不会默认把所有源代际能力都复制到昇腾310P，而是先判断目标路径需要做到哪一步。
如果算子逻辑简单，且dtype、搬运和tiling在昇腾310P上没有差异，优先采用最小改造：补齐Host注册、构建清单和测试配置。
如果源路径包含BF16、量化或平台专用实现，则先确认昇腾310P是否真的支持对应能力；不支持的能力需要明确收窄，不能机械暴露。
如果kernel中存在 `DataCopyPad`、非32B对齐写回或复杂尾块处理，则必须进入kernel差异审查，确认昇腾310P可达路径不会读写越界。
关键原则：不要为了让昇腾310P编译通过而删除或削弱昇腾910路径；没有昇腾310P编译、精度或功能验证结果时，也不要声称“迁移完成”。
阶段三：
Host与构建路由，
先保证昇腾310P路径可达
Host侧迁移采用“最小足够”原则。简单算子可以只新增 `AddConfig("ascend310p")`；当昇腾310P需要target-specific flag、不同kernel或dtype收窄时，再构造独立的 `OpAICoreConfig`。
构建侧则需要同步检查 `CMakeLists.txt`、`build.sh`、`SUPPORT_COMPUTE_UNIT`、`ASCEND_SOC_UNITS`、`SOC_ARRAY`、`test_soc_config.yaml`、`get_soc_version.py` 以及 `op_host/config/ascend310p` 目录。Skill会提醒开发者确认新增文件不会被错误排除，也不会误路由到不兼容的源代际目录。
阶段四：
Kernel差异处理，
重点处理DataCopy与尾块风险
在kernel侧，昇腾310P迁移最容易被忽略的是搬运语义和尾块边界。Skill会把这些差异前置成迁移决策，减少“照搬源代际代码”的风险。
DataCopyPad检查：逐点检查 `DataCopyPad` 是否位于昇腾310P可达路径上。GM（Global Memory）到UB（Unified Buffer）场景需要确认 padding tail是否会被后续计算读取；UB到GM场景不能简单向上取整写回，必须证明GM行尾padding可覆盖，或使用tail-safe写回方案。
32B对齐与尾块写回：如果输出shape、stride或block划分导致尾块不足32B，迁移时需要明确写回策略。能编译不代表安全，关键是确认不会覆盖相邻逻辑输出，也不会把padding数据带入后续计算。
dtype能力收窄：如果源路径声明了昇腾310P暂未验证的dtype，Skill会建议先收窄能力边界，等kernel、tiling和精度验证补齐后再开放。
阶段五：
验证与交付，让迁移结果可复用
跨代际迁移的最后一步，是把“改了什么、支持什么、没支持什么、验证到了哪里”写清楚。Skill的完成标准要求输出简短迁移报告，包含改动文件、昇腾310P注册、支持dtype、构建/测试命令与结果，以及残余风险。
报告 `DataCopyPad` 替换状态、尾块对齐风险、dtype 能力收窄情况。
记录昇腾310P 构建命令、AclNN 测试命令、精度结果和失败项。
如果目标硬件、编译器或测试环境不可用，报告明确标记为“静态迁移”或“静态审查”，不把缺失验证包装成完成态。
一次迁移的推荐输入与输出
总结
昇腾910到昇腾310P的Ascend C算子迁移，本质上是一项工程一致性工作：既要让昇腾310P路径可达，也要确保源代际能力不被破坏；既要处理Host和构建配置，也要审查kernel中真正会执行的搬运、计算和同步路径。
`op-ascend-migration` Skill 将这些经验沉淀成可执行的扫描器、分路线参考和报告标准，帮助开发者把迁移过程从“靠经验逐项翻代码”，推进到“先扫描、再选择路线、按检查结果修改、按验证交付”的标准流程。
待续：从昇腾910到昇腾950，一套Skill继续打通扫描、迁移、验证与交付。
社区共建：欢迎开发者贡献Skills，共同完善昇腾AI生态。
开源地址：
https://gitcode.com/Ascend/agent-skills
