Lock
产品支持情况
- Ascend 950PR&950DT系列产品:支持
- Atlas A3系列产品:不支持
- Atlas A2系列产品:不支持
- Atlas 200I/500 A2推理产品:不支持
- Atlas推理系列产品AI Core:不支持
- Atlas推理系列产品Vector Core:不支持
- Atlas训练系列产品:不支持
功能说明
头文件路径为:"basic_api/kernel_common.h"。
根据MutexID获取Mutex,若Mutex已被锁定,将阻塞指定流水上后续指令的执行,直到所有流水中具有相同MutexID的Mutex都已经被Unlock释放。
函数原型
template <pipe_t pipe>
static __aicore__ inline void Lock(MutexID id)
参数说明
表 1 模板参数说明
| 参数名 | 描述 |
|---|---|
| pipe | 模板参数,表示流水类别。支持PIPE_S、PIPE_M、PIPE_V、PIPE_MTE1、PIPE_MTE2、PIPE_MTE3、PIPE_FIX,各流水类型的含义请参考硬件流水类型。 |
表 2 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| id | 输入 | 进行流水同步管理的MutexID。在不同编程范式中,该ID的获取以及释放方式不同,详细情况参考约束说明。 |
返回值说明
无
约束说明
每个锁有固定的一个MutexID,在不同编程范式中,该ID的获取以及释放方式不同:
- 采用TPipe-TQue框架编程范式时,MutexID需要通过AllocMutexID/ReleaseMutexID进行申请释放,由框架统一管理MutexID分配记录,避免与TQue等资源管理接口使用的MutexID冲突。
- 采用静态Tensor编程范式时,MutexID可以通过AllocMutexID/ReleaseMutexID申请释放,也可以由开发者自行管理。自行管理可减少接口调用开销,但开发者需要自行保证MutexID不与其他同步或资源管理接口使用的MutexID冲突。自行管理MutexID时,建议使用0-27,28-31为系统内部规划预留,不建议使用。
调用
Lock/Unlock时,如果由开发者自行管理MutexID,不得同时使用以下可能申请、取得或操作MutexID的资源管理接口:TPipe接口:InitBuffer(仅指参数类型为TQue或TQueBind的重载)、InitBufPool。TBufPool接口:InitBuffer、InitBufPool、Reset。TQue接口:AllocTensor、FreeTensor、EnQue、DeQue。TQueBind接口:InitBufHandle、AllocTensor、FreeTensor、EnQue、DeQue。
在相应架构和配置下,上述资源管理接口可能申请、分配或使用MutexID。开发者自行管理的MutexID不会登记到资源管理机制的MutexID分配记录中,可能与上述资源管理接口使用的MutexID重复,导致同步行为未定义。同时使用上述资源管理接口和
Lock/Unlock时,Lock/Unlock使用的MutexID必须通过AllocMutexID申请,并在使用结束后通过ReleaseMutexID释放。Lock与Unlock必须严格成对使用,并使用相同的pipe和id。此外,对应的Unlock必须始终写在Lock之后,否则属于未定义行为。
C++// 反例:先Unlock再Lock,顺序颠倒。 AscendC::Mutex::Unlock<PIPE_MTE2>(0); AscendC::Mutex::Lock<PIPE_MTE2>(0);对于id相同的Lock与Unlock组合,无论pipe是否相同,都不得在代码中嵌套使用,否则属于未定义行为。
C++// 反例:id相同,Lock与Unlock嵌套。 AscendC::Mutex::Lock<PIPE_MTE2>(0); AscendC::Mutex::Lock<PIPE_MTE3>(0); AscendC::Mutex::Unlock<PIPE_MTE3>(0); AscendC::Mutex::Unlock<PIPE_MTE2>(0);当具有相同id与pipe的两对Lock与Unlock连续调用时,第一次调用的Lock将由参数pipe指定的流水阻塞后,第二次调用的Lock不能再次阻塞该流水。换言之,连续调用的、具有相同id与pipe的两对Lock与Unlock不能实现单流水(参数pipe指定)内不同指令之间的同步,单流水内多个指令之间的同步请使用PipeBarrier接口。
如图1所示,两次搬运的目的地址在Unified Buffer(UB)存在重叠时,开发者需要控制PIPE_MTE2上两条指令执行的先后顺序。在此场景中如下写法(具有相同id与pipe的两对Lock与Unlock连续调用)只能保证两条PIPE_MTE2上指令执行后,PIPE_V上指令才能执行,但并不能控制PIPE_MTE2上两条指令执行的先后顺序,正确写法是在
CopyInY与CopyInX之间插入PipeBarrier<PIPE_MTE2>()。图1 PIPE_MTE2上两次搬运目的地址(UB)存在重叠
C++// x和y在UB上的地址存在重叠(重叠部分x覆盖y),预期先搬入y后搬入x,需要保证搬入顺序。 void CopyInX(LocalTensor<float>& x, const GlobalTensor<float>& xGm, uint32_t len, uint8_t mutexId) { AscendC::Mutex::Lock<PIPE_MTE2>(mutexId); AscendC::DataCopy(x, xGm, len); AscendC::Mutex::Unlock<PIPE_MTE2>(mutexId); } void CopyInY(LocalTensor<float>& y, const GlobalTensor<float>& yGm, uint32_t len, uint8_t mutexId) { AscendC::Mutex::Lock<PIPE_MTE2>(mutexId); AscendC::DataCopy(y, yGm, len); AscendC::Mutex::Unlock<PIPE_MTE2>(mutexId); } void Process(LocalTensor<float>& z, LocalTensor<float>& x, LocalTensor<float>& y, uint32_t len, uint8_t mutexId) { // 先搬入y,再搬入x(重叠部分x覆盖y),顺序错误会导致精度异常。 CopyInY(y, yGm, len, mutexId); /* * // 必须在CopyInY与CopyInX之间插入PipeBarrier,保证前一次搬入完成后才执行下一次搬入。 * AscendC::PipeBarrier<PIPE_MTE2>(); */ CopyInX(x, xGm, len, mutexId); AscendC::Mutex::Lock<PIPE_V>(mutexId); AscendC::Add(z, x, y, len); AscendC::Mutex::Unlock<PIPE_V>(mutexId); }
调用示例
// 申请两个MutexID,供双缓冲流水交替复用。
uint8_t mutexId0 = AscendC::AllocMutexID();
uint8_t mutexId1 = AscendC::AllocMutexID();
// 交替使用两个MutexID,保证MTE2、V、MTE3三段流水按顺序串联。
for (int32_t i = 0; i < loopCount; i++) {
uint8_t mutexId = (i % 2 == 0) ? mutexId0 : mutexId1;
// 锁住MTE2流水,保证当前tile的搬入按该MutexID顺序执行。
AscendC::Mutex::Lock<PIPE_MTE2>(mutexId);
AscendC::DataCopy(xLocal, src0Global[TILE_LENGTH * progress], TILE_LENGTH);
AscendC::DataCopy(yLocal, src1Global[TILE_LENGTH * progress], TILE_LENGTH);
// 搬入完成后解锁MTE2流水,允许后续阶段继续推进。
AscendC::Mutex::Unlock<PIPE_MTE2>(mutexId);
// 锁住V流水,等待对应tile的搬入完成后再开始计算。
AscendC::Mutex::Lock<PIPE_V>(mutexId);
AscendC::Add(zLocal, xLocal, yLocal, TILE_LENGTH);
// 计算完成后解锁V流水,放行后续计算或搬出。
AscendC::Mutex::Unlock<PIPE_V>(mutexId);
// 锁住MTE3流水,确保计算结果完成后再写回GM。
AscendC::Mutex::Lock<PIPE_MTE3>(mutexId);
AscendC::DataCopy(dstGlobal[TILE_LENGTH * progress], zLocal, TILE_LENGTH);
// 搬出完成后解锁MTE3流水,结束当前tile的处理。
AscendC::Mutex::Unlock<PIPE_MTE3>(mutexId);
}
// 释放本次样例申请的两个MutexID。
AscendC::ReleaseMutexID(mutexId0);
AscendC::ReleaseMutexID(mutexId1);
完整样例请参考:Mutex样例。