SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsexternal-cannbot-ops-ascendc-blaze-best-practice

external-cannbot-ops-ascendc-blaze-best-practice

Coding & development

View repository

Updated 10-15 17:19

About this skill

Ascend C Matmul single-operator generation (Blaze path)

This capability addresses problems in Matmul single-operator generation scenarios: tensor_api/Blaze API constraint confirmation, three-template selection (pure AIC / StreamK / FixpOpti), unified project template reuse, SWAT/full-load Tiling modification, pipeline and troubleshooting.

Architecture constraint: Core validation is on DAV_3510. Other architectures must explicitly state differences in DESIGN.md and provide adaptation solutions.

First-time use：matmul_custom/ depends on tensor_api/, external dependencies need to be pulled on first use. See steps in matmul_pattern.md §0.5.0。

When to use

Use this capability when any of the following conditions is met:

  • The operator type is in the Matmul family (GEMM/BMM/quantized matmul/matmul+bias/mxfp8 matmul).
  • Signals such as tensor_api、blaze appear in code or discussion.
  • Need to select a template (pure AIC/StreamK/FixpOpti), switch dispatch mode (NO_FULL/A_FULL/B_FULL_LOAD), perform Tiling modification, or troubleshoot the pipeline.

Do not treat this capability as a general substitute for the default operator development path. Vector-type element-wise/reduction operators, matmul+eltwise deep fusion (including Vector post-processing such as activation/residual), matmul+softmax, etc. are not directly covered by this skill's templates; for these scenarios, use this skill's FixpOpti template for the Cube section, and the epilogue part needs to be extended by yourself.

Three-template quick overview

Template Typical scenario Delivery status
Pure AIC General scenarios (default) Delivered
StreamK MN under-parallelism + long K (≥4096) Design document
FixpOpti AIC/AIV pipeline overlap, customizable epilogue Delivered

The three templates share the same base references/matmul_custom/(common/, tiling/, scheduler/, utils/). FixpOpti-specific files (matmul_fixpopti.cpp、matmul_kernel_fused.h, epilogue/) are also in this directory.

For detailed comparison (execution mode, scheduler, synchronization mechanism, Workspace, ASCII data flow diagram, decision tree), see matmul_pattern.md §10; not repeated here.

Consult by role/stage

Reading order: first quickly review tensor_api_user_guide.md to understand the API → matmul_pattern.md §10 select template → for the pure AIC path continue to §0 select mode → §0.5 copy + modify → shared basics §1–§9 + dedicated in-depth documents.

Stage/Role Main document Auxiliary / In-depth
Solution decision (Architect) matmul_pattern.md §10 three-template selection + §0 mode overview tensor_api_user_guide.md(API quick reference)
Design (Architect) After selecting a template, go to the in-depth documents: - Pure AIC:matmul_basic.md / matmul_full_load.md- StreamK：matmul_streamk.md- FixpOpti：matmul_fixpopti.md matmul_pattern.md §1–§9 shared basics
Implementation (Developer) Uniformly start from the references/matmul_custom/ base: pure AIC → matmul_custom.cpp（[MODIFY] N/C/A）FixpOpti → matmul_fixpopti.cpp（[MODIFY] N/C/A/E), according to matmul_fixpopti.md §3 modify matmul_fixpopti.md(modification cookbook)
Review (Reviewer) matmul_pattern.md §8 troubleshooting quick reference Corresponds to the "Common Pitfalls" table in the template deep-dive document
Fix debugging matmul_pattern.md §8 (compile-time / precision / run-through self-check) matmul_fixpopti.md §6 Pitfalls table

Constraints

  • Architecture validation scope: DAV_3510. Other architectures may be incompatible due to tensor_api dependencies and L1/L0 capacity differences.
  • Full-load delivery status：A_FULL_LOAD_MODE has landed (matmul_block_mmad_a_full_load.h + MatmulTilingAFullLoad, 3-line diff to switch).B_FULL_LOAD_MODE Design draft only(see matmul_full_load.md §3.2 / §4.2 / §4.3); the repository has no B_FULL_LOAD_MODE constants,MatmulMultiBlockPolicy<B_FULL_LOAD_MODE> specializations,MatmulSwatScheduler<B_FULL_LOAD_MODE> selector、MatmulTilingBFullLoad classes,matmul_block_mmad_b_full_load.h header files—before use, you must mirror and fill them in yourself according to the symmetric design, and cannot apply the matmul_pattern.md §0.5.3 switch diff (the B full-load section has been replaced with a warning NOTE).
  • Starting from template copy: Pure AIC starts from references/matmul_custom/matmul_custom.cpp , FixpOpti starts from references/matmul_custom/matmul_fixpopti.cpp ; the two paths share common/, tiling/, scheduler/, and utils/ under references/matmul_custom/ . Both are modified according to the [MODIFY] markings. FixpOpti additionally requires: (1) replacing the launcher matmul_custom.cpp→matmul_fixpopti.cpp, (2) changing BlockMmad's CopyL0C2GM to CopyL0C2UB+SPLIT_M Trait (see matmul_fixpopti.md §3.5), (3) adding matmul_kernel_fused.h and the epilogue file. It has one more tier than pure AIC: [MODIFY] E for custom Epilogue.
  • Do not guess API signatures：AscendC::Te:: The series interfaces have many overloads and template specializations. Consult references/tensor_api_user_guide.md or the official documentation.
  • Pseudocode is not equivalent to a compilable implementation: The code snippets in the design document are simplified to illustrate concepts. When writing code, return to the corresponding template project—the details have already been handled.
  • Explain the basis for mode and template selection: In DESIGN.md, clearly write why this mode/template was chosen.

Integration with CANNBot

CANNBot stage Caller Loading method
Step 2 Design Architect Subagent When the user requirement path is determined to be "tensor_api / CUTLASS-style API", explicitly load this skill
Step 3 Development Developer Subagent Select a template according to the design, reuse the template project
Step 4 Review Reviewer Subagent Use matmul_pattern.md §8 troubleshooting quick reference for cross-validation