SuperAPI AI Directory

atb-ops-to-aclnn-migration-workflow

Coding & development

View repository

Updated 10-24 04:38

About this skill

ATB OPS→ACLNN Migration Standardized Workflow

Function Overview

Defines the standardized 7-phase workflow for migrating ATB operators from the OPS interface to the ACLNN interfacestandardized 7-phase workflow, including a Human in the Loop user confirmation mechanism.

When to Use

  • {xxx}Quant、{xxx}Norm、Softmax OPS→ACLNN migration of operators such as
  • Enable ACLNN acceleration on 910B/950 devices
  • Maintain compatibility with other devices

Detailed Content

Phase Gates Overview

[Phase 0] 前置知识学习
    │
    ▼
[Phase 1] 设计文档生成 ────→ [用户确认 Gate 1] ───┐
    │                                         │
    ▼                                         │
[Phase 2] CSV用例设计 ─────→ [用户确认 Gate 2] ───┤
    │                                         │
    ▼                                         ▼
[Phase 3] 实际迁移(TDD) ←───────────────────────┘
    │
    ▼
[Phase 4] 编译验证(≤3次尝试)
    │
    ▼
[Phase 5a] 小范围验证
    ├─ Step 1: 前台跑 _func.csv(正例+反例, ~30s)
    └─ Step 2: 后台 subagent 跑 _perf.csv(性能, ~10min, 不阻塞)
    │
    ▼
[Phase 5b] 全量回归(所有相关 CSV)──→ [Gate 5b: 全量通过] ──┐
    │ (汇合 subagent 性能结果)                               │
    ▼                                                        ▼
[Phase 6] 交付报告 ←──────────────────────────────────────────┘

Detailed Description of Phase 0-6

See the detailed documents for each phase below.


No-Skipping Rules ⛔

⚠️ The following rules must be enforced at every Phase transition and cannot be bypassed:

Phase Dependency Matrix

Phase Prerequisite Gate Behavior When Not Passed
Phase 1 Gate 0 (Documents Complete) Block — Entering the design phase is prohibited when interface documents are missing
Phase 2 Gate 1 (Design Confirmation) Block — Writing CSV is prohibited before the user confirms the design document
Phase 3 Gate 2 (CSV Confirmation) Block — Writing code is prohibited before the user confirms the CSV test cases
Phase 4 Phase 3 Complete Executable (compilation verification)
Phase 5a Phase 4 Passed Run Phase 2 first, then Phase 5a — Testing is prohibited before test case design is complete
Phase 5b Phase 5a Passed Full regression — All related CSV must be fully run and pass
Phase 6 Gate 5b Passed Executable (delivery report)

Checks That Must Be Performed at the Start of Each Phase

1. 确认上一阶段 Gate 状态:
   - Gate X 是否已获用户确认?
   - 确认记录在哪里 (commit message / working_files / 对话记录)?

2. 如果 Gate 未通过:
   - 立即停止
   - 向用户报告: "Phase Y 需要 Gate X 确认,当前 Gate X 状态: 未确认"
   - 等待用户指示

3. 如果 Gate 已通过:
   - 明确告知用户: "Gate X 已通过,进入 Phase Y"
   - 继续执行

Common Skipping Errors and Interception Scripts

Erroneous Behavior Agent Self-Check Question Interception Script
Run tests directly after compilation "Have the CSV test cases been designed and confirmed?" ⛔ Phase 5a requires Gate 2 confirmation. Current Gate 2 status: not confirmed. Please complete Phase 2 CSV test case design first.
Write the delivery report directly after 5a passes "Has the full regression been executed?" ⛔ Gate 5b not passed: full regression testing is incomplete. Please execute Phase 5b first and confirm that all related CSV pass.
Skip the design document after implementation "Has the design document been generated?" ⛔ Phase 3 requires Gate 1 confirmation. Current Gate 1 status: not confirmed. Please complete the Phase 1 design document first.
Infer from code after WebFetch fails "Are the interface documents complete?" ⛔ Gate 0 not passed: failed to obtain the ATB/ACLNN interface documents; inferring from code is prohibited. Please ask the user to provide the documents.
Write code directly after CSV design is complete "Has the user confirmed the CSV?" ⛔ Phase 3 requires Gate 2 confirmation. Please wait for the user to confirm the CSV test cases first.

Phase Status Self-Check at Agent Startup

Every time the Agent is invoked to execute a migration task, it must first execute:

1. git log --oneline -5    → 检查当前分支做了什么
2. ls working_files/        → 检查哪些阶段产物已存在
3. 判断当前处于哪个 Phase  → 报告用户当前状态
4. 确认下一 Phase 的前置 Gate 是否通过 → 按依赖矩阵校验

Skills invocation sequence

Stage Skill invoked
Phase 1 atb-aclnn-operator-replacement-designer
Phase 2 atb-csv-testcase-generator
Phase 3 atb-aclnn-operator-migration
Phase 4 atb-testframework-build
Phase 5a atb-csv-tester(1 run by default for positive/negative cases, 400 runs by default for performance)
Phase 5b atb-csv-tester (Gate 5 full regression)
Debugging atb-debug-guide

Quick reference

# Phase 0-1: 设计和用例生成
# → atb-aclnn-operator-replacement-designer
# → atb-csv-testcase-generator
# → [等待用户确认 Gate 1 & 2]

# Phase 3: 实际迁移
# → atb-aclnn-operator-migration

# Phase 4: 编译
# → atb-testframework-build
# → [失败] atb-debug-guide

# Phase 5a: 小范围验证
# → atb-csv-tester(不指定 -t,正例/反例默认1次,性能默认400次)
# → [失败] atb-debug-guide
#
# Phase 5b: 全量回归
# → atb-csv-tester (Gate 5)
# → [失败] atb-debug-guide

Detailed stage documentation

Objective

Understand the technical background related to the operator, laying the foundation for subsequent design.

Prerequisites

None

Input

  • Operator name (e.g., {xxx}Quant)
  • Task background document (if any)

Output

  • Prerequisite knowledge summary document (saved to working_files)

Learning content

Topic Content Output location
Quantization basics Differences between per-token/per-channel/per-tensor {WORKING_DIR}/quant_basics.md
ACLNN interface documentation Understanding of official API specifications Record key parameters
Existing ATB implementation Analysis of the current OPS implementation Record migration points

Checkpoint

Check item Verification method
Quantization knowledge has been summarized File exists in working_files
Key parameters of the ACLNN interface have been extracted Parameter list is present in the document

Gate 0

  • Type: Automatic pass (no user confirmation)
  • Condition: Learning document has been generated

Objective

Generate a complete detailed design document for operator replacement (7-chapter structure).

Prerequisites

  • Phase 0 completed
  • ATB/ACLNN interface documentation links have been provided

Skills invocation

atb-aclnn-operator-replacement-designer

Checkpoint

Check item Verification method
ATB interface URL has been provided Documentation link is valid
ACLNN interface URL has been provided Documentation link is valid
ATB operator parameters have been extracted Chapter 2 of the design document is complete
ACLNN interface parameters have been extracted Chapter 2 of the design document is complete
Parameter mapping table has been created Section 2.3 of the design document exists
All 7 chapters of the design document are complete Chapters 1-7 all exist

Gate 1: User confirmation ⭐

⚠️ Mandatory checkpoint - cannot be skipped

Before confirmation is received, entering Phase 2 is prohibited

Objective

Design a CSV test case set covering positive cases, negative cases, and performance tests,producing two separate files。

Output artifacts

File Content Purpose
{op}_func.csv Positive cases + negative cases Phase 5a foreground quick verification
{op}_perf.csv Performance test cases Phase 5a background subagent runs them one by one
{op}_test.csv(Optional) All merged Phase 5b full regression

Prerequisites

  • Phase 1 has passed Gate 1 user confirmation

Skills invocation

atb-csv-testcase-generator

Checkpoint

Check item Quantity Verification method
Positive cases cover typical scenarios 5-15 Cover float16/bf16
Negative cases cover all validation branches 10-20 Cover all ERROR_INVALID_*
Performance tests cover large and small shapes 5-10 Include large/medium/small shapes
Split into _func.csv and _perf.csv 2 independent files Each has a complete 21-column header
CSV format conforms to the specification - Column count=21, delimiter=|

Gate 2: User confirmation ⭐

⚠️ Mandatory checkpoint - cannot be skipped

Before confirmation is received, entering Phase 3 is prohibited

Objective

Implement the ACLNN Runner and modify Operation to enable 910B/950 acceleration.

Prerequisites

  • Phase 2 has passed Gate 2 user confirmation

Skills invocation

atb-aclnn-operator-migration

Implementation points

  1. Inherit AclnnRunner: The new runner must inherit from the base class
  2. Implement the four major methods:
    • BuildAclnnVariantPack: Handle input and output tensors
    • SetAclNNWorkspaceExecutor: Configure workspace
    • LaunchAclnnKernel: Execute computation
    • LoadMethod: Dynamically load ACLNN functions
  3. Device detection: Use GetSingleton<Config>().Is910B() and Is950()
  4. Backward compatibility: Non-910B/950 devices retain the OPS implementation

Objective

Verify that the code compiles successfully, with a maximum of 3 attempts.

Skills invocation

atb-testframework-build
atb-debug-guide(编译失败时)

Compilation rules

Attempt Action
1st failure Analyze the error, locate the problem, fix it, and recompile
2nd failure Analyze in depth, review the reference implementation, fix it, and recompile
3rd failure Stop, record the error and modification plan,ask the user

Objective

Run the CSVs produced in Phase 2 in two steps: quickly verify functionality in the foreground, and run performance tests in a background subagent.

Prerequisites

  • Phase 4 compilation passed
  • Phase 2 has produced {op}_func.csv and {op}_perf.csv

Step 1: Run the functional CSV in the foreground

cd <ATB_REPO_PATH>/tests/framework/python/CsvOpsTestTool
python3 atb_csv_ops_test.py -i <CSV_DIR>/{op}_func.csv
  • Do not specify -t, defaults to 1 time, completes in seconds
  • Must wait for all to pass, stop and troubleshoot if any fail

Step 2: Run the performance CSV in a background Subagent

Agent(
    description="运行 {op} 性能测试",
    prompt="""
逐个运行 {op}_perf.csv 中的性能测试用例,避免 OOM:

cd {ATB_REPO_PATH}/tests/framework/python/CsvOpsTestTool
source {CANN_PATH}/set_env.sh
source {ATB_REPO_PATH}/output/atb/set_env.sh

# 获取性能用例总数
lines=$(tail -n +2 {ATB_REPO_PATH}/tests/apitest/opstest/csv/{op}_perf.csv | wc -l)

# 逐个运行每个性能 case
for i in $(seq 1 $lines); do
    echo "=== 运行性能 case $i/$lines ==="
    python3 atb_csv_ops_test.py -i {ATB_REPO_PATH}/tests/apitest/opstest/csv/{op}_perf.csv -n $i:$i
done

完成后汇总:通过/失败/耗时。
""",
    subagent_type="general-purpose",
    run_in_background=True
)

Key points:

  • Use -n N:N to run one by one, loading only 1 performance case each time
  • run_in_background=True Execute in the background without blocking the main flow
  • The subagent notifies automatically upon completion, and the results are consolidated into the Phase 6 delivery report

Skills invocation

atb-csv-tester(双文件 + 前台/后台两种模式)
atb-debug-guide(测试失败时)

Post-completion actions

After Step 1 fully passes, start the Step 2 background subagent,and immediately continue in the foreground with Phase 5b full regression。

Objective

Run all CSV files related to the target operator to ensure no regressions are introduced.

Prerequisites

  • Phase 5a Step 1 (foreground functional CSV) all passed
  • Phase 5a Step 2 (background performance subagent) may still be running

Skills invocation

atb-csv-tester(Gate 5 全量回归门控模式)

Test scope

Enumerate and run all related CSVs:

find <ATB_REPO_PATH>/tests/apitest/opstest/csv/ -name '{op_name}*.csv' -type f | sort

Subagent result aggregation

If the background performance subagent has not yet completed, wait for completion and then summarize:

### Phase 5a 后台性能测试结果
| Case | ExecuteTime(us) | precision | 状态 |
|------|----------------|-----------|------|
| case 1 | xxx | 100% | ✅ |
| ...

Test requirements

Requirement Description
All CSVs run in full Partial runs are not allowed
All test cases pass Failures or skips are not allowed
Use default iteration counts Do not specify -t(positive/negative cases 1 time, performance 400 times)
Aggregate background subagent results Wait for the subagent to complete and summarize

Gate 5b: Full regression confirmation

Mandatory checkpoint — cannot be skipped

## Gate 5b — 全量回归结果

| CSV 文件 | 总用例 | 通过 | 失败 | 状态 |
|---------|--------|------|------|------|
| {op}_test.csv | N | N | 0 | ✅ |
| {op}.csv | M | M | 0 | ✅ |

**全部通过,Gate 5b 满足,可进入 Phase 6 交付。**

When blocked, see atb-csv-tester Gate 5 blocking script.

Goal

Automatically aggregate the outputs of Phase 1/2/5 to generate a standardized delivery report.

Prerequisites

  • Phase 5a tests passed
  • Phase 5b full regression passed (Gate 5b confirmed)

Automatic aggregation process

The data for the delivery report should be automatically extracted from preceding phases; do not fill it in manually:

Report section Data source Extraction method
Design document summary {WORKING_DIR}/{op}_replacement_design.md Read the requirements summary/parameter mapping/risk assessment
CSV case statistics {op}_test.csv wc -l + awk Group by ExpectedError
Code changes git diff / git log git diff --stat + git log --oneline
Compilation verification Phase 4 compilation log Extract compilation status
Phase 5a results Test output Extract passed/failed/skipped
Phase 5b results Test output Summarize all CSVs
Outstanding items Phase 5b items that did not pass If there are failure records

Automatic aggregation command snippet

# 统计 CSV 用例数
tail -n +2 {CSV_FILE} | wc -l

# 统计正例/反例/性能
tail -n +2 {CSV_FILE} | grep -c 'NO_ERROR$'
tail -n +2 {CSV_FILE} | grep -c 'Performance'
tail -n +2 {CSV_FILE} | awk -F'|' '{print $21}' | sort | uniq -c | sort -rn

# 代码变更
git diff --stat HEAD~1..HEAD
git log --oneline -5

Report template

# {Op} OPS→ACLNN 迁移交付报告

> **自动生成时间**: {timestamp}
> **生成方式**: 自动聚合 Phase 1/2/5 输出

## 任务概述
- **算子名称**: {Op}
- **迁移目标**: OPS → ACLNN
- **目标设备**: 910B/950
- **执行日期**: {date}

## 阶段完成情况
| 阶段 | 状态 | 关键输出 |
|------|------|----------|
| Phase 0 前置学习 | ✅ | working_files |
| Phase 1 设计文档 | ✅ | {op}_replacement_design.md |
| Phase 2 CSV用例 | ✅ | {op}_test.csv({total} 个用例) |
| Phase 3 实际迁移 | ✅ | 代码变更({files}个文件) |
| Phase 4 编译验证 | ✅ | 第 {N} 次编译通过 |
| Phase 5a 小范围验证 | ✅ | {designed_pass}/{designed_total} 通过 |
| Phase 5b 全量回归 | ✅ | {regression_total} 通过({csv_count} 个 CSV) |
| Gate 1/2 确认 | ✅ | 用户已确认 |
| Gate 5b 全量回归 | ✅ | 所有 CSV 通过 |

## 测试结果汇总
### Phase 5a: 小范围验证
- 执行 CSV: {op}_test.csv
- 通过: N/N

### Phase 5b: 全量回归
| CSV | 总用例 | 通过 | 失败 |
|-----|--------|------|------|
| {op}_test.csv | N | N | 0 |
| {op}.csv | M | M | 0 |

## 代码变更

{git diff --stat ...}


## 遗留事项
[如有未通过用例或已知问题]

## 附件清单
- 设计文档: {path}
- CSV用例: {path}
- 代码变更: git commit {hash}
- 交付报告: {path}

Gate 6: Final delivery ⭐

⚠️ Mandatory checkpoint


FAQ

Skipping Gate 1 and Gate 2 is prohibited. If the user does not respond in time:

  1. Remind the user to confirm pending
  2. If there is still no response after 24 hours, record the risk and pause the task
  3. Do not proceed to the next phase without authorization
  1. Record the complete error log to working_files
  2. Analyze using atb-debug-guide
  3. Ask the user (Socratic style):
    • Phenomenon description
    • Fixes already attempted
    • Possible root cause hypotheses
    • Support needed

Related documentation