已合并
新增标量原子操作概述文档 #6523
GRJ_XIDUO创建于 15 天前
新增标量原子操作概述文档 #6523
已合并
共 4 个文件变更+60-5
| @@ -1305,6 +1305,7 @@ | |||
| 1305 | - [asc_set_atomic_min](SIMD-API/c_api/atomic/datamove_atomic/asc_set_atomic_min.md) | 1305 | - [asc_set_atomic_min](SIMD-API/c_api/atomic/datamove_atomic/asc_set_atomic_min.md) |
| 1306 | - [asc_disable_dma_atomic](SIMD-API/c_api/atomic/datamove_atomic/asc_disable_dma_atomic.md) | 1306 | - [asc_disable_dma_atomic](SIMD-API/c_api/atomic/datamove_atomic/asc_disable_dma_atomic.md) |
| 1307 | - [标量原子操作](SIMD-API/c_api/atomic/scalar_atomic/scalar_atomic.md) | 1307 | - [标量原子操作](SIMD-API/c_api/atomic/scalar_atomic/scalar_atomic.md) |
| 1308 | + - [标量原子操作概述](SIMD-API/c_api/atomic/scalar_atomic/scalar_atomic_overview.md) | ||
| 1308 | - [asc_atomic_add](SIMD-API/c_api/atomic/scalar_atomic/asc_atomic_add.md) | 1309 | - [asc_atomic_add](SIMD-API/c_api/atomic/scalar_atomic/asc_atomic_add.md) |
| 1309 | - [asc_atomic_and](SIMD-API/c_api/atomic/scalar_atomic/asc_atomic_and.md) | 1310 | - [asc_atomic_and](SIMD-API/c_api/atomic/scalar_atomic/asc_atomic_and.md) |
| 1310 | - [asc_atomic_cas](SIMD-API/c_api/atomic/scalar_atomic/asc_atomic_cas.md) | 1311 | - [asc_atomic_cas](SIMD-API/c_api/atomic/scalar_atomic/asc_atomic_cas.md) |
| @@ -1,11 +1,12 @@ | |||
| 1 | # 原子操作概述 | 1 | # 原子操作概述 |
| 2 | 2 | ||
| 3 | -数据搬运随路原子操作接口用于对后续目的地址为GM的数据搬运指令开启原子操作，涉及的接口请参见[表1](#table1)。如下图1的左侧子图所示，未开启原子操作时，写入GM的数据搬运完成后，GM中原始数据将被新搬运数据完全覆盖。如图1右侧子图所示，当数据搬运随路原子操作接口被调用后，系统将为后续写入GM的数据搬运开启原子操作。此时，数据搬运完成后，GM中的最终数据由原始GM数据与新搬运数据共同决定。 | 3 | +数据搬运随路原子操作接口用于对后续目的地址为GM的数据搬运指令开启原子操作，涉及的接口请参见[表1](#datamove_atomic_operation_interface)。如下图1的左侧子图所示，未开启原子操作时，写入GM的数据搬运完成后，GM中原始数据将被新搬运数据完全覆盖。如图1右侧子图所示，当数据搬运随路原子操作接口被调用后，系统将为后续写入GM的数据搬运开启原子操作。此时，数据搬运完成后，GM中的最终数据由原始GM数据与新搬运数据共同决定。 |
| 4 | 4 | ||
| 5 | **图1** 数据搬运随路原子累加效果 | 5 | **图1** 数据搬运随路原子累加效果 |
| 6 | + | ||
| 6 |  | 7 |  |
| 7 | 8 | ||
| 8 | -**表1** 数据搬运随路原子操作接口<a name="table1"></a> | 9 | +**表1** 数据搬运随路原子操作接口<a id="datamove_atomic_operation_interface"></a> |
| 9 | 10 | ||
| 10 | | 对应接口 | 接口功能描述 | | 11 | | 对应接口 | 接口功能描述 | |
| 11 | | --- | --- | | 12 | | --- | --- | |
| @@ -14,7 +15,7 @@ | |||
| 14 | | [asc_set_atomic_min](datamove_atomic/asc_set_atomic_min.md) | 设置后续搬运到GM的数据是否执行原子比较：将待拷贝的内容和GM已有内容进行比较，然后将最小值写入GM。 | | 15 | | [asc_set_atomic_min](datamove_atomic/asc_set_atomic_min.md) | 设置后续搬运到GM的数据是否执行原子比较：将待拷贝的内容和GM已有内容进行比较，然后将最小值写入GM。 | |
| 15 | | [asc_disable_dma_atomic](datamove_atomic/asc_disable_dma_atomic.md) | 关闭数据搬运随路原子操作功能。 | | 16 | | [asc_disable_dma_atomic](datamove_atomic/asc_disable_dma_atomic.md) | 关闭数据搬运随路原子操作功能。 | |
| 16 | 17 | ||
| 17 | -Scalar原子操作接口，能够在指定GM地址上进行单点原子计算操作，涉及的接口请参见[表2](#table2)。 | 18 | +Scalar原子操作接口，能够在指定GM地址上进行单点原子计算操作，涉及的接口请参见[表2](#scalar_atomic_operation_interface)。 |
| 18 | 19 | ||
| 19 | 标量原子操作与数据搬运随路原子操作相比，两者的差异如下： | 20 | 标量原子操作与数据搬运随路原子操作相比，两者的差异如下： |
| 20 | 21 | ||
| @@ -23,10 +24,11 @@ Scalar原子操作接口，能够在指定GM地址上进行单点原子计算操 | |||
| 23 | 24 | ||
| 24 | 如下图2左侧子图所示，不使用`asc_atomic_add`接口时，多个AI Core同时对同一GM地址执行累加操作会相互覆盖，操作不具备原子性，最终结果不可预期。如右侧子图所示，使用`asc_atomic_add`接口后，各AI Core的累加操作串行化执行，确保每次累加操作的原子性，最终结果符合预期。 | 25 | 如下图2左侧子图所示，不使用`asc_atomic_add`接口时，多个AI Core同时对同一GM地址执行累加操作会相互覆盖，操作不具备原子性，最终结果不可预期。如右侧子图所示，使用`asc_atomic_add`接口后，各AI Core的累加操作串行化执行，确保每次累加操作的原子性，最终结果符合预期。 |
| 25 | 26 | ||
| 26 | -**图2** 标量原子累加效果 | 27 | +**图2** 标量原子累加效果<a id="scalar_atomic_operation_diagram"></a> |
| 28 | + | ||
| 27 |  | 29 |  |
| 28 | 30 | ||
| 29 | -**表2** Scalar原子操作接口<a name="table2"></a> | 31 | +**表2** Scalar原子操作接口<a id="scalar_atomic_operation_interface"></a> |
| 30 | 32 | ||
| 31 | | 对应接口 | 接口功能描述 | | 33 | | 对应接口 | 接口功能描述 | |
| 32 | | --- | --- | | 34 | | --- | --- | |
| @@ -1,5 +1,6 @@ | |||
| 1 | # 标量原子操作 | 1 | # 标量原子操作 |
| 2 | 2 | ||
| 3 | +- **[标量原子操作概述](scalar_atomic_overview.md)** | ||
| 3 | - **[asc_atomic_add](asc_atomic_add.md)** | 4 | - **[asc_atomic_add](asc_atomic_add.md)** |
| 4 | - **[asc_atomic_and](asc_atomic_and.md)** | 5 | - **[asc_atomic_and](asc_atomic_and.md)** |
| 5 | - **[asc_atomic_cas](asc_atomic_cas.md)** | 6 | - **[asc_atomic_cas](asc_atomic_cas.md)** |
| @@ -0,0 +1,51 @@ | |||
| 1 | +# 标量原子操作概述 | ||
| 2 | + | ||
| 3 | +标量原子操作接口用于在Global Memory（GM）的指定地址上完成单个元素的原子读-改-写操作：读取该地址的旧值`old_value`，按接口语义计算新值并写回该地址，同时返回`old_value`。整个过程由硬件保证为原子操作，其他原子更新无法插入其中，因此多个AI Core或同一AI Core内的多条指令并发访问同一GM地址时不会相互覆盖，最终结果符合预期。不使用原子操作与使用原子操作的效果对比如[标量原子累加效果示意图](../atomic_operations_overview.md#scalar_atomic_operation_diagram)所示。 | ||
| 4 | + | ||
| 5 | +标量原子操作适用于多个核需要更新同一个GM地址的场景，例如多核并行累加同一个统计量、维护多个核共享的计数器、在指定地址上比较并更新状态等场景。 | ||
| 6 | + | ||
| 7 | +## 接口列表 | ||
| 8 | + | ||
| 9 | +标量原子操作接口如表1所示，各接口支持的数据类型如表2所示。其中`old_value`为`address`指向的GM地址上的旧值，`new_value`为写回该地址的新值，表1中的原子计算接口均返回`old_value`。 | ||
| 10 | + | ||
| 11 | +**表1** 标量原子操作接口 | ||
| 12 | + | ||
| 13 | +| 对应接口 | 接口功能描述 | 计算公式 | | ||
| 14 | +| --- | --- | --- | | ||
| 15 | +| [asc_atomic_add](asc_atomic_add.md) | 原子加：将`address`指向的GM地址上的旧值与输入标量值`val`求和，并将结果写回该地址。 | $new\_value = old\_value + val$ | | ||
| 16 | +| [asc_atomic_sub](asc_atomic_sub.md) | 原子减：将`address`指向的GM地址上的旧值减去输入标量值`val`，并将结果写回该地址。 | $new\_value = old\_value - val$ | | ||
| 17 | +| [asc_atomic_max](asc_atomic_max.md) | 原子取大：比较`address`指向的GM地址上的旧值与输入标量值`val`，并将较大值写回该地址。 | $new\_value = Max(old\_value, val)$ | | ||
| 18 | +| [asc_atomic_min](asc_atomic_min.md) | 原子取小：比较`address`指向的GM地址上的旧值与输入标量值`val`，并将较小值写回该地址。 | $new\_value = Min(old\_value, val)$ | | ||
| 19 | +| [asc_atomic_inc](asc_atomic_inc.md) | 原子递增：`address`指向的GM地址上的旧值大于或等于`val`时将该地址置为0，否则将旧值加1后写回。 | $new\_value = (old\_value >= val) ? 0 : (old\_value + 1)$ | | ||
| 20 | +| [asc_atomic_dec](asc_atomic_dec.md) | 原子递减：`address`指向的GM地址上的旧值等于0或大于`val`时将该地址置为`val`，否则将旧值减1后写回。 | $new\_value = (old\_value == 0 \vert\vert old\_value > val) ? val : (old\_value - 1)$ | | ||
| 21 | +| [asc_atomic_and](asc_atomic_and.md) | 原子与：将`address`指向的GM地址上的旧值与输入标量值`val`按位与，并将结果写回该地址。 | $new\_value = old\_value \& val$ | | ||
| 22 | +| [asc_atomic_or](asc_atomic_or.md) | 原子或：将`address`指向的GM地址上的旧值与输入标量值`val`按位或，并将结果写回该地址。 | $new\_value = old\_value \vert val$ | | ||
| 23 | +| [asc_atomic_xor](asc_atomic_xor.md) | 原子异或：将`address`指向的GM地址上的旧值与输入标量值`val`按位异或，并将结果写回该地址。 | $new\_value = old\_value \oplus val$ | | ||
| 24 | +| [asc_atomic_exch](asc_atomic_exch.md) | 原子交换：将输入标量值`val`写入`address`指向的GM地址以替换旧值。 | $new\_value = val$ | | ||
| 25 | +| [asc_atomic_cas](asc_atomic_cas.md) | 原子比较交换：`address`指向的GM地址上的旧值与`compare`相等时，将`val`写入该地址；不相等时保持该地址的值不变。 | $new\_value = (old\_value == compare) ? val : old\_value$ | | ||
| 26 | +| [asc_set_store_atomic_config_v1](asc_set_store_atomic_config_v1.md) | 设置标量原子操作配置：操作类型（仅支持求和操作）和数据类型。 | - | | ||
| 27 | +| [asc_get_store_atomic_config](asc_get_store_atomic_config.md) | 获取asc_set_store_atomic_config_v1设置的标量原子操作配置。 | - | | ||
| 28 | + | ||
| 29 | +表1中两类接口的产品支持情况不同： | ||
| 30 | + | ||
| 31 | +- [asc_atomic_add](asc_atomic_add.md)～[asc_atomic_cas](asc_atomic_cas.md)：仅Ascend 950PR&950DT系列产品支持。 | ||
| 32 | +- [asc_set_store_atomic_config_v1](asc_set_store_atomic_config_v1.md)：仅Atlas A2系列产品、Atlas A3系列产品支持，Ascend 950PR&950DT系列产品不支持，在Ascend 950PR&950DT系列产品可使用[asc_atomic_add](asc_atomic_add.md)实现原子累加。 | ||
| 33 | +- [asc_get_store_atomic_config](asc_get_store_atomic_config.md)：Atlas A2系列产品、Atlas A3系列产品、Ascend 950PR&950DT系列产品均支持，但在Ascend 950PR&950DT系列产品上已废弃，该系列产品可直接使用[asc_atomic_add](asc_atomic_add.md)实现原子累加。 | ||
| 34 | + | ||
| 35 | +**表2** 标量原子操作接口支持的数据类型 | ||
| 36 | + | ||
| 37 | +| 对应接口 | `dtype`支持的数据类型 | | ||
| 38 | +| --- | --- | | ||
| 39 | +| [asc_atomic_add](asc_atomic_add.md) | `int32_t`、`uint32_t`、`float`、`int64_t`、`uint64_t` | | ||
| 40 | +| [asc_atomic_sub](asc_atomic_sub.md) | `int32_t`、`uint32_t`、`float`、`int64_t`、`uint64_t` | | ||
| 41 | +| [asc_atomic_max](asc_atomic_max.md) | `int32_t`、`uint32_t`、`float`、`int64_t`、`uint64_t` | | ||
| 42 | +| [asc_atomic_min](asc_atomic_min.md) | `int32_t`、`uint32_t`、`float`、`int64_t`、`uint64_t` | | ||
| 43 | +| [asc_atomic_inc](asc_atomic_inc.md) | `uint32_t`、`uint64_t` | | ||
| 44 | +| [asc_atomic_dec](asc_atomic_dec.md) | `uint32_t`、`uint64_t` | | ||
| 45 | +| [asc_atomic_and](asc_atomic_and.md) | `int32_t`、`uint32_t`、`int64_t`、`uint64_t` | | ||
| 46 | +| [asc_atomic_or](asc_atomic_or.md) | `int32_t`、`uint32_t`、`int64_t`、`uint64_t` | | ||
| 47 | +| [asc_atomic_xor](asc_atomic_xor.md) | `int32_t`、`uint32_t`、`int64_t`、`uint64_t` | | ||
| 48 | +| [asc_atomic_exch](asc_atomic_exch.md) | `int32_t`、`uint32_t`、`float`、`int64_t`、`uint64_t` | | ||
| 49 | +| [asc_atomic_cas](asc_atomic_cas.md) | `int32_t`、`uint32_t`、`float`、`int64_t`、`uint64_t` | | ||
| 50 | +| [asc_set_store_atomic_config_v1](asc_set_store_atomic_config_v1.md) | `float`、`half`、`int16_t`、`int32_t`、`int8_t`、`bfloat16_t` | | ||
| 51 | +| [asc_get_store_atomic_config](asc_get_store_atomic_config.md) | - | | ||