ascendc

AscendC オペレーター開発（一括）

このスキルは、AscendC のカスタムオペレーターを仕様から本番環境対応のベンチマーク済みオペレーターへと開発するプロセスを、ascend-kernel プロジェクト（csrc/ops/、csrc/register.cpp、build.sh を介してオペレーターを torch.ops.npu.<op> として公開する PyTorch カスタムオペレータープロジェクト）内で支援します。このスキルは自己完結型で、各フェーズ、テンプレート、参照資料はすべてこのスキルディレクトリ内にあります。

対象範囲：このスキルは、ascend-kernel / csrc/ops の PyTorch カスタムオペレーターのワークフロー（ベクトル／行／インデックス／ソート／プールオペレーター、FP16/BF16 のアップキャスト、2 レベルのタイリング）を対象とします。ops-transformer の aclnn/genop フローは対象外です。

このスキルの使用方法

1. まず、この SKILL.md を最初から最後まで読みます（ライフサイクル、ゲート、アンチパターン）。
2. 各フェーズで作業を始める前に、該当する references/NN-*.md を必ず開きます。
3. 同梱の templates/、examples/、scripts/ を再利用し、プロジェクト構成や API を独自に作成しないでください。
4. ステージゲートを守ります。前のフェーズのチェックリストに合格するまで、次のフェーズを開始しないでください。チャット内での結果表示ルールも必ず守ってください。

使用する場面

• 「新しい AscendC オペレーター <name> を開発／実装／作成する」（例：acosh、rms_norm）。
• 「オペレーター開発を続ける」→ 成果物から現在のフェーズを判定し、そこから再開します。
• 既存のオペレーターで単一のフェーズを実施する場合：設計のみ、コード生成のみ、精度評価のみ、性能ベンチマークのみ、最適化のみ、またはコードレビューのみ。

ライフサイクルの概要

Phase 0  Environment + requirements
Phase 1  Project init        -> references/01-project-init.md
Phase 2  Design (design.md)  -> references/02-design.md
Phase 3  Test cases          -> references/03-testcase-gen.md
Phase 4  Code generation     -> references/04-code-gen.md (+ 04a-kernel-api.md)
Phase 5  Compile / debug     -> references/05-compile-debug.md
Phase 6  Interface docs      -> references/06-doc-gen.md
Phase 7  Precision eval      -> references/07-precision-eval.md (fail -> 07b-precision-debug.md)
Phase 8  Performance eval    -> references/08-performance-eval.md
Phase 9  Performance optim   -> references/09-performance-optim.md
Phase 10 Code review         -> references/10-code-review.md
(opt)    Memory check        -> references/11-mssanitizer.md

入力：オペレーター名（snake_case）＋関数仕様／数学的仕様。 出力：ビルドおよびインストール済みオペレーター、design.md、統一テストケース文書、PyTorch スタイルの README、精度レポート、性能レポート（実施した場合は最適化／レビューの各レポートも）。

フェーズ 0 — 環境と要件

開発作業を始める前に、ビルド／実行環境を確認します。

• CANN：echo $ASCEND_HOME_PATH を実行します。設定されている場合は、それを CANN_PATH として使用します。設定されていない場合は、CANN のインストールパスをユーザーに必ず確認します。シェルごとに source ${CANN_PATH}/*/set_env.sh を実行して有効化します。
• Conda：echo $CONDA_DEFAULT_ENV を実行します。値が空でなく、base でもない場合は、それを使用します。それ以外の場合は、conda 環境名をユーザーに必ず確認し、conda activate <env> で有効化します。
• 要件：オペレーター名（snake_case、必須）、関数仕様／数式（必須）、サポートするデータ型（省略可、既定値は float16, float32。bfloat16 を追加可能）、SoC（省略可、既定値は ascend910b。実行時にプラットフォーム API から取得）。

詳細と判断フロー：references/00-environment.md。

ゲート：CANN パスが特定され、有効化できること。conda 環境が特定され、有効化できること。オペレーター名と関数仕様が確認済みであること。

フェーズ 1 — プロジェクトの初期化

ascend-kernel プロジェクトを特定または作成し、csrc/ops/<op>/ のひな形を作成します。

• scripts/detect_ascend_kernel_project.sh で検出します。見つからない場合は、同梱のテンプレート templates/ascend-kernel/ をコピーし、chmod +x build.sh を実行します。
• csrc/ops/<op>/{op_host/<op>.cpp, op_kernel/<op>.cpp, CMakeLists.txt, design.md} を作成します（プレースホルダー）。
• 後続フェーズで更新する3 つの登録箇所に印を付けます：csrc/ops.h、csrc/register.cpp、csrc/CMakeLists.txt。

references/01-project-init.md を読みます。

ゲート：プロジェクトが存在すること（build.sh、CMakeLists.txt、csrc/）。csrc/ops/<op>/ のひな形として 4 つのファイルが作成されていること。

Phase 2 — 設計（design.md）

完全な設計ドキュメントを作成します。コード生成に直接使用します。

• 実装パスを選択します（デフォルトは AscendC Kernel、CATLASS は matmul/cube の場合のみ）。
• 数式を AscendC API 呼び出しシーケンスに対応付けます。2 階層のタイル分割（ブロックレベルのコア間分割＋UB レベルのコア内分割）を設計し、UB 割り当て表を埋め、dtype ごとの bufferCoefficient を導出します。FP16/BF16 → FP32 のアップキャストパスについて記述します。
• templates/design-template.md を埋め、csrc/ops/<op>/design.md に書き込みます。

references/02-design.md（演算タイプ別のタイル分割、UB 割り当て、API マップ、ハードウェア制約）を参照してください。

ゲート：design.md に関数シグネチャ、サポート対象 dtype、API 疑似コード、dtype ごとの bufferCoefficient を含む UB 割り当て表、タイル分割構造体、アップキャストパスが記載されていること。

Phase 3 — テストケース

後続の精度テストと性能テストで共用する、統一されたテストケースドキュメントを生成します。

• design.md を読み、SUPPORTED_DTYPES、TEST_SHAPES、GENERAL_SHAPES、 BOUNDARY_VALUES、演算子のベースライン（CPU 参照実装＋NPU 呼び出し）を作成します。
• ケースの合計数 (TEST_SHAPES + GENERAL_SHAPES) x SUPPORTED_DTYPES は 30 以上にします。通常のケースでは、単一形状の要素数を適切な範囲（<= 約 200K）に保ちます。
• templates/test-cases-template.md を埋め、 csrc/ops/<op>/test/<op>-test-cases.md に書き込みます。

references/03-testcase-gen.mdを参照してください。

ゲート：dtype、形状、境界値、ベースラインを含むテストケースドキュメントが存在し、値が design.md の制約に従っていること。

Phase 4 — コード生成＋フレームワークへの適応

op_host と op_kernel を生成し、フレームワークに組み込みます。

• 演算子タイプ（elementwise / row / index / index-per-elem / sort / pool）に応じて、templates/code-gen/ からテンプレートのペアを選択し、csrc/ops/<op>/ にコピーして適応させます。
• op_host：シグネチャ、入力チェック、coreNum/ubSize 用のプラットフォーム API（ハードコードは不可）、bufferCoefficient、左辺値の EXEC_KERNEL_CMD 引数。
• op_kernel：BUFFER_NUM=2、コアオフセットの初期化、InitBuffer サイズ、計算ロジック、末尾タイルのアラインメント、FP16/BF16 から FP32 へのアップキャスト、GM↔UB 間の DataCopyPad、Reduce の前のバックアップ。
• フレームワーク：csrc/ops.h に宣言を追加し、csrc/register.cpp に m.def+m.impl を追加し、csrc/CMakeLists.txt にホストとカーネルのソースを追加します。

references/04-code-gen.mdと、references/04a-kernel-api.mdの API 基本事項を参照してください。

ゲート：両方のソースが生成され、3 つの登録箇所が更新され、参考資料のチェックリストを満たしていること。

Phase 5 — コンパイル、インストール、テスト、デバッグ

プロジェクトをビルドし、wheel をインストールして基本テストを生成・実行し、デバッグします。

• chmod +x build.sh && bash build.sh を実行し、output/ascend_kernel*.whl が生成されたことを確認します。
• pip install output/ascend_kernel*.whl --force-reinstall --no-deps を実行します。
• tests/test_<op>.py を生成し、機能テスト（python ...）、続いて精度テスト（pytest -v）を実行します。各シェルコマンドの前に環境をソースしてください。
• 失敗した場合は、エラー判定ツリーを使って**デバッグループ（最大 3 回）**を実行します。

references/05-compile-debug.mdを参照してください。

ゲート：wheel がビルド・インストールされ、機能テストが終了コード 0 で終了し、精度テストの pytest がすべて成功していること。

Phase 6 — インターフェースドキュメント

ソースからインターフェースに関する情報を抽出し、PyTorch 形式の README を出力します。

• register.cpp（m.def）からスキーマを、ops.h から C++ シグネチャを、design.md からアルゴリズム／dtype／制約を、op_host から TORCH_CHECK を、テストファイルから例を取得します。
• 固定セクションを組み立て、csrc/ops/<op>/README.md に書き込みます。デフォルトの言語は英語です。リクエストに応じて中国語に切り替えます。
• README の内容全体をチャットに必ず表示してください。パスだけを表示するのは不可です。

references/06-doc-gen.mdを参照してください。

ゲート：README にシグネチャ、パラメーター、dtype、形状、制約、例、戻り値が記載され、register.cpp のスキーマと一致し、チャットに表示されていること。

フェーズ 7 — 精度評価

包括的な精度テストスイートを実行し、レポートを作成します。

• フェーズ 3 のテストケース文書を読み込み、(shapes + boundary) x dtypes >= 30 となるように調整します。
• templates/precision/ から test_<op>_precision.py と run_<op>_precision_report.py を生成し、pytest を実行してからレポート生成スクリプトを実行します。
• 合格条件（MERE/MARE、エコシステムのオープンソース標準）：MERE < Threshold かつ MARE < 10 x Threshold。基準の表は references/07a-precision-standards.md にあります。
• 閾値で解決できない精度の失敗が発生した場合は、 references/07b-precision-debug.md に従って根本原因をデバッグします。
• チャットには、概要（合計数と合格率）、失敗内容、主な調査結果を 3 件以上必ず表示し、その後にレポートのパスを表示します。

references/07-precision-eval.md を読んでください。

ゲート：pytest が成功すること、JSON と Markdown のレポートが書き出されること、結果がチャットに表示されること。

フェーズ 8 — 性能評価

torch_npu.profiler を使って、カスタム演算子とベースラインをベンチマークします。

• テストケース文書と design.md から JSONL ケースファイル（>= 8 ケース）を作成し、必ず デュアルパス 比較を実行します（カスタムとベースラインの比較。ベースラインは NPU 上で実行する必要があります。同等の API がない場合は、小規模な演算の組み合わせを使用してください）。
• 固定スケジュール warmup=5, active=5 を使用し、ASCEND_PROFILER_OUTPUT/op_statistic.csv から Total Time(us) を集計します。examples/layer_norm_profiler_reference/ を出発点としてコピーします。
• チャットには、統合比較表（DType 列を含む）、概要、簡潔な結論を 3 件以上必ず表示し、その後にレポートのパスを表示します。

references/08-performance-eval.md、 references/08a-profiler-and-metrics.md、および references/08b-perf-case-jsonl.md を読んでください。

ゲート：デュアルパスのレポートが作成され、表、概要、結論とともにチャットに表示されること。

フェーズ 9 — 性能最適化（任意、閉ループ）

調査、変更、検証を最大 3 ラウンド実施します。

• 5 つの観点（タイリング、データコピー、API の使用、メモリ、パイプライン）から調査し、優先順位を付けたレポートを出力して、ベースラインを記録します。
• アンチパターン一覧を守って変更を適用し、精度テスト（合格必須）を再実行してから、同じ性能ケースを実行します。ベースラインと比較し、反復します。

references/09-performance-optim.md を読んでください。

ゲート：精度テストに引き続き合格すること、性能をベースラインと比較すること、結果がチャットに表示されること。

フェーズ 10 — コードレビュー（任意）

コーディング上の禁止事項（数値、メモリ／ポインター、リソース、入力検証、並行処理、演算子インターフェース、ABI 互換性）に照らして、仮説検証型のセキュリティレビューを実施します。

references/10-code-review.md を読んでください。

任意 — メモリチェック

mssanitizer を実行して、不正なアクセス、リーク、範囲外アクセスを含む未定義動作を検出します。 references/11-mssanitizer.md を読んでください。

共通のアンチパターン（絶対にしないこと）

• 設計を省略して直接コードを書いてはいけません。コード生成は design.md を使用します。
• FP16/BF16 を複雑な数学演算に直接渡してはいけません。まず FP32 にアップキャストします。
• GM↔UB に DataCopy を使ってはいけません。DataCopyPad を使用します。
• EXEC_KERNEL_CMD に右辺値（一時値／リテラル／式）を渡してはいけません。
• コア数や UB サイズをハードコードしてはいけません。プラットフォーム API で取得します。
• cmake/ または csrc/utils/ 以下のファイルを変更してはいけません。
• ReduceSum／ReduceMax の直後にソーステンソルを再利用してはいけません（リダクションによって変更される場合があります）。
• カーネル内で std::min/max/abs/sqrt/exp などを使用してはいけません。
• 高次元分割 API に repeatTime > 255 を渡してはいけません（uint8 への切り詰めが警告なしで発生します）。
• 性能の結論に、プロファイラーを使用しない計測方法を使ってはいけません。
• 精度／性能／最適化についてファイルパスだけを報告してはいけません。表と結論をチャットに表示します。

中断からの再開

検出された状態	未完了のフェーズ	再開位置
csrc/ops/<op>/ が存在しない	1	フェーズ 1
design.md がプレースホルダーまたは空	2	フェーズ 2
<op>-test-cases.md が存在しない	3	フェーズ 3
op_host がまだスケルトンの状態	4	フェーズ 4
wheel がビルドされていない／基本テストに失敗	5	フェーズ 5
README.md が存在しない	6	フェーズ 6
精度レポートがない／精度テストに失敗	7	フェーズ 7
精度レポートはあるが、パフォーマンスレポートがない	8	フェーズ 8

ステータストラッカー

フェーズ	前提条件	リファレンス	主な成果物
0 環境＋要件	—	00-environment	CANN＋conda＋名前＋仕様
1 初期化	0	01-project-init	csrc/ops/<op>/ のスケルトン
2 設計	1	02-design	design.md
3 テストケース	2	03-testcase-gen	<op>-test-cases.md
4 コード生成	3	04-code-gen	op_host＋op_kernel＋登録
5 コンパイル／デバッグ	4	05-compile-debug	インストール済み wheel＋テスト成功
6 ドキュメント	5	06-doc-gen	README.md
7 精度	6	07-precision-eval	精度レポート
8 パフォーマンス	7	08-performance-eval	パフォーマンスレポート
9 最適化	8	09-performance-optim	最適化の概要
10 レビュー	4+	10-code-review	レビューレポート

依存関係

このスキルは自己完結型です（テンプレート、リファレンス、サンプル、スクリプトが同梱されています）。 演算子をコンパイルして実行するには、Ascend NPU を搭載したホスト上で、動作する CANN ツールキットと PyTorch＋torch_npu の conda 環境が必要です。