Skip to content

kali20gakki/msAgent / skills/operator/mstx-report-soft-sync

mstx-report-soft-sync

Verified

分析 AscendC 算子中自实现的软同步代码,判断其所属同步语义(核间 barrier/set-wait、卡间 barrier/signal),并接入 mssanitizer 的 Sanitizer 接口(sanitizer_report.h)上报软同步语义,避免 racecheck 对软同步误报。触发:算子存在自实现软同步(GM 地址轮询、flag 计数、跨核/跨卡信号等)需要配合 mssanitizer 检测、需要上报软同步语义、需要判断某段同步代码属于哪种同步语义时。

FileKindSize
SKILL.mdskill md7.2 KB
references/recognition-examples.mdmarkdown4.9 KB
references/sanitizer-interface.mdmarkdown5.0 KB
---
name: mstx-report-soft-sync
description: 分析 AscendC 算子中自实现的软同步代码,判断其所属同步语义(核间 barrier/set-wait、卡间 barrier/signal),并接入 mssanitizer 的 Sanitizer 接口(sanitizer_report.h)上报软同步语义,避免 racecheck 对软同步误报。触发:算子存在自实现软同步(GM 地址轮询、flag 计数、跨核/跨卡信号等)需要配合 mssanitizer 检测、需要上报软同步语义、需要判断某段同步代码属于哪种同步语义时。
---

# 算子软同步语义分析与 mssanitizer 上报

## 概述

mssanitizer 的 racecheck 会检测访存竞态。算子中由用户自行实现的软同步(轮询 GM 地址 / 写 flag / 计数等)会被 racecheck 误判为竞态,需要通过 `sanitizer_report.h` 提供的 `Sanitizer` 接口上报同步语义,让检测器识别这些软同步、跳过误报。

- 接口头文件:`$ASCEND_HOME_PATH/tools/mssanitizer/include/sanitizer_report.h`
- 完整接口签名、结构体字段、参数说明见 [references/sanitizer-interface.md](references/sanitizer-interface.md)

## 软同步语义分类

| 语义 | 场景 | 上报结构体(`Sanitizer::`) |
|------|------|------------------------------|
| 核间 barrier | 同卡多个核到达同步点后一起继续 | `MstxCrossCoreBarrier` |
| 核间 set/wait | 核 A 发信号,核 B 等待后才继续 | `MstxCrossCoreSetFlag` / `MstxCrossCoreWaitFlag` |
| 卡间 barrier | 跨卡所有核到达后继续(隐含全流水+核间 barrier) | `MstxCrossNpuBarrier` |
| 卡间 signal | 基于 GM 地址写值 + 轮询该地址满足条件 | `MstxSignalSet` / `MstxSignalWait` |

## 处理流程

### 步骤 1:识别自实现软同步

**排除项(无需上报)**:

- 直接调用已封装的软同步接口,如 `aclshmem_signal_wait_until`、`aclshmemx_signal_op`、`aclshmem_barrier_all` 等(这些内部已上报)。
- 硬件同步(非软同步):`SetFlag`/`WaitFlag`/`PipeBarrier`(核内事件同步)、`CrossCoreSetFlag`/`CrossCoreWaitFlag`(硬件核间同步)。

**识别特征(自实现软同步,需上报)**:

- GM 地址轮询:`while (*(__gm__ T*)addr != value)`、`while (ReadGmByPassDCache(ptr) != target)`
- 写 flag / 计数:`*(__gm__ T*)addr = value`、`WriteGmByPassDCache(ptr, v)`、`AtomicAdd(flag, n)`
- 配合 `dcci_cacheline(s)` 显式刷新 dcache 的轮询/写值

### 步骤 2:判断同步语义

按三个维度归类:

1. **参与方**:核内(同核流水)→ 跨核(同卡不同 core)→ 跨卡(不同 device/rank)。
2. **同步方式**:barrier(所有参与方到达才释放)→ set/wait(一方发布、另一方等待)→ signal(基于 GM 地址写值+轮询)。
3. **happens-before 粒度**:决定能否消除「数据区」的写-读误报(关键!)。

对照「软同步语义分类」表确定上报结构体。

**语义选择关键经验**(来自 allgather 实测):

- **同卡多核软同步 → 用核间 barrier(`MstxCrossCoreBarrier`)或核间 set/wait(`MstxCrossCoreSetFlag`/`WaitFlag`)**。其 happens-before 是**全局**的(barrier 之前所有写 → 之后所有读),能消除「数据区」写-读误报。
- **跨卡软同步 → 用卡间 signal(`MstxSignalSet`/`Wait`)或卡间 barrier(`MstxCrossNpuBarrier`)**。`signal` 的 happens-before **按地址**(文档「仅与保存信号的地址有关」),只消除 signal 地址(flag 区)的误报,**无法跨到数据区**——若误报发生在「生产者写数据 vs 消费者读数据」这类数据区竞争,signal 上报无效,应改用 barrier 语义。

判断方法:先看 racecheck 误报的**地址是否等于软同步 flag 地址**(是→signal 即可;否、且为数据区写-读→barrier/set-wait)。

### 步骤 3:先封装宏,再插入上报

为避免每个同步点重复构造结构体,仿照 shmem 内部 `shmemi_mstx_report.h` 的写法,**在算子文件顶部先定义一组宏**封装 `sanitizer_report.h` 的 `Sanitizer::` 接口(不依赖 shmem 内部头文件,便于移植到其他算子仓)。宏名改用 `MSTX_SOFT_SYNC_` 前缀,与 shmem 内部的 `MSTX_*` 宏区分,避免编译期冲突:

```cpp
#include "sanitizer_report.h"

#ifdef __MSTX_DFX_REPORT__
#define MSTX_SOFT_SYNC_FUSE_SCOPE_START() Sanitizer::SanitizerFuseScopeStart()
#define MSTX_SOFT_SYNC_FUSE_SCOPE_END() Sanitizer::SanitizerFuseScopeEnd()
#define MSTX_SOFT_SYNC_SIGNAL_SET_REPORT(addr_, val_)     \
    do {                                        \
        Sanitizer::MstxSignalSet soft_sync_set__{};  \
        soft_sync_set__.addr = (uint64_t)(addr_);    \
        soft_sync_set__.value = (val_);              \
        Sanitizer::SanitizerReport(soft_sync_set__); \
    } while (0)
#define MSTX_SOFT_SYNC_SIGNAL_WAIT_REPORT(addr_, cmp_, val_)        \
    do {                                                  \
        Sanitizer::MstxSignalWait soft_sync_wait__{};          \
        soft_sync_wait__.addr = (uint64_t)(addr_);             \
        soft_sync_wait__.cmpValue = (val_);                    \
        soft_sync_wait__.cmpOp = (Sanitizer::CompareOp)(cmp_); \
        Sanitizer::SanitizerReport(soft_sync_wait__);          \
    } while (0)
#define MSTX_SOFT_SYNC_CROSS_CORE_BARRIER_REPORT(core_num)         \
    do {                                                           \
        Sanitizer::MstxCrossCoreBarrier soft_sync_barrier__{};     \
        soft_sync_barrier__.usedCoreNum = (core_num);              \
        Sanitizer::SanitizerReport(soft_sync_barrier__);           \
    } while (0)
#else
#define MSTX_SOFT_SYNC_FUSE_SCOPE_START()
#define MSTX_SOFT_SYNC_FUSE_SCOPE_END()
#define MSTX_SOFT_SYNC_SIGNAL_SET_REPORT(addr_, val_)
#define MSTX_SOFT_SYNC_SIGNAL_WAIT_REPORT(addr_, cmp_, val_)
#define MSTX_SOFT_SYNC_CROSS_CORE_BARRIER_REPORT(core_num)
#endif
```

然后在每个同步点插入:

```cpp
// set 侧(写 flag / 发信号)
MSTX_SOFT_SYNC_FUSE_SCOPE_START();
/* user-defined 软同步逻辑:写 flag、put、AtomicAdd 等 */
MSTX_SOFT_SYNC_FUSE_SCOPE_END();
MSTX_SOFT_SYNC_SIGNAL_SET_REPORT(flag_addr, written_value);

// wait 侧(轮询 flag / 等信号)
MSTX_SOFT_SYNC_FUSE_SCOPE_START();
/* user-defined 软同步逻辑:while 轮询 */
MSTX_SOFT_SYNC_FUSE_SCOPE_END();
MSTX_SOFT_SYNC_SIGNAL_WAIT_REPORT(flag_addr, Sanitizer::CompareOp::EQ, expected_value);
```

要点:

- `SanitizerFuseScopeStart()` / `SanitizerFuseScopeEnd()` 包裹的自定义软同步指令不会被 racecheck 检测,`SanitizerReport(record)` 上报同步语义。
- signal 的 set/wait 通过 `addr` 配对:对称内存下 set 方写入的地址与 wait 方轮询的地址数值相同。
- `(uint64_t)` 强转兼容 `GM_ADDR` 的指针/整型两种底层类型。
- 宏受 `__MSTX_DFX_REPORT__` 门控:非 mssanitizer 构建时为空,不影响普通编译。其余语义(barrier、set/wait)可仿照同一模式扩展对应宏。

## 参考资料

- [references/sanitizer-interface.md](references/sanitizer-interface.md) - Sanitizer 接口签名、结构体字段、CompareOp 枚举、参数说明
- [references/recognition-examples.md](references/recognition-examples.md) - 自实现软同步识别与归类的典型样例
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall