已合并
docs: 统一标量原子接口文档描述 #6753
docs: 统一标量原子接口文档描述 #6753
已合并
lihuaichao创建于 17 天前
共 16 个文件变更+31-26
@@ -56,7 +56,7 @@ __aicore__ inline T AtomicAdd(__gm__ T *address, T value)
56 56 
57| 参数名 | 输入/输出 | 描述 |57| 参数名 | 输入/输出 | 描述 |
58| --- | --- | --- |58| --- | --- | --- |
59-| address | 输入 | 输入GM的地址。 |59+| address | 输入/输出 | 输入GM的地址。 |
60| value | 输入 | 标量值,支持数据类型和address指向的数据类型一致。 |60| value | 输入 | 标量值,支持数据类型和address指向的数据类型一致。 |
61 61 
62## 数据类型<a name="section832119018128"></a>62## 数据类型<a name="section832119018128"></a>
@@ -60,7 +60,7 @@ __aicore__ inline T AtomicCas(__gm__ T *address, T value1, T value2)
60 60 
61| 参数名 | 输入/输出 | 描述 |61| 参数名 | 输入/输出 | 描述 |
62| --- | --- | --- |62| --- | --- | --- |
63-| address | 输入 | 输入GM的地址。 |63+| address | 输入/输出 | 输入GM的地址。 |
64| value1/value2 | 输入 | 标量值,支持数据类型和address指向的数据类型保持一致。 |64| value1/value2 | 输入 | 标量值,支持数据类型和address指向的数据类型保持一致。 |
65 65 
66## 数据类型<a name="section832119018128"></a>66## 数据类型<a name="section832119018128"></a>
@@ -56,7 +56,7 @@ __aicore__ inline T AtomicExch(__gm__ T *address, T value)
56 56 
57| 参数名 | 输入/输出 | 描述 |57| 参数名 | 输入/输出 | 描述 |
58| --- | --- | --- |58| --- | --- | --- |
59-| address | 输入 | 输入GM的地址。 |59+| address | 输入/输出 | 输入GM的地址。 |
60| value | 输入 | 标量值,支持数据类型和address指向的数据类型保持一致。 |60| value | 输入 | 标量值,支持数据类型和address指向的数据类型保持一致。 |
61 61 
62## 数据类型<a name="section832119018128"></a>62## 数据类型<a name="section832119018128"></a>
@@ -56,7 +56,7 @@ __aicore__ inline T AtomicMax(__gm__ T *address, T value)
56 56 
57| 参数名 | 输入/输出 | 描述 |57| 参数名 | 输入/输出 | 描述 |
58| --- | --- | --- |58| --- | --- | --- |
59-| address | 输入 | 输入GM的地址。 |59+| address | 输入/输出 | 输入GM的地址。 |
60| value | 输入 | 标量值,支持数据类型和address指向的数据类型一致。 |60| value | 输入 | 标量值,支持数据类型和address指向的数据类型一致。 |
61 61 
62## 数据类型<a name="section832119018128"></a>62## 数据类型<a name="section832119018128"></a>
@@ -56,7 +56,7 @@ __aicore__ inline T AtomicMin(__gm__ T *address, T value)
56 56 
57| 参数名 | 输入/输出 | 描述 |57| 参数名 | 输入/输出 | 描述 |
58| --- | --- | --- |58| --- | --- | --- |
59-| address | 输入 | 输入GM的地址。 |59+| address | 输入/输出 | 输入GM的地址。 |
60| value | 输入 | 标量值,支持数据类型和address指向的数据类型一致。 |60| value | 输入 | 标量值,支持数据类型和address指向的数据类型一致。 |
61 61 
62## 数据类型<a name="section832119018128"></a>62## 数据类型<a name="section832119018128"></a>
@@ -55,7 +55,7 @@ __aicore__ inline int32_t asc_atomic_add(__gm__ int32_t* address,
55 55 
56| 参数名 | 输入/输出 | 描述 |56| 参数名 | 输入/输出 | 描述 |
57| --- | --- | --- |57| --- | --- | --- |
58-| address | 输入 | Global Memory的地址。 |58+| address | 输入/输出 | Global Memory的地址。 |
59| val | 输入 | 源操作数。 |59| val | 输入 | 源操作数。 |
60 60 
61## 返回值说明61## 返回值说明
@@ -55,7 +55,7 @@ __aicore__ inline int32_t asc_atomic_and(__gm__ int32_t* address,
55 55 
56| 参数名 | 输入/输出 | 描述 |56| 参数名 | 输入/输出 | 描述 |
57| --- | --- | --- |57| --- | --- | --- |
58-| address | 输入 | Global Memory的地址。 |58+| address | 输入/输出 | Global Memory的地址。 |
59| val | 输入 | 源操作数。 |59| val | 输入 | 源操作数。 |
60 60 
61## 返回值说明61## 返回值说明
@@ -63,7 +63,7 @@ __aicore__ inline int32_t asc_atomic_cas(__gm__ int32_t* address,
63 63 
64| 参数名 | 输入/输出 | 描述 |64| 参数名 | 输入/输出 | 描述 |
65| --- | --- | --- |65| --- | --- | --- |
66-| address | 输入 | Global Memory的地址。 |66+| address | 输入/输出 | Global Memory的地址。 |
67| compare | 输入 | 源操作数,做比较的值。 |67| compare | 输入 | 源操作数,做比较的值。 |
68| val | 输入 | 源操作数,用于赋值的值。 |68| val | 输入 | 源操作数,用于赋值的值。 |
69 69 
@@ -61,7 +61,7 @@ __aicore__ inline uint32_t asc_atomic_dec(__gm__ uint32_t* address,
61 61 
62| 参数名 | 输入/输出 | 描述 |62| 参数名 | 输入/输出 | 描述 |
63| --- | --- | --- |63| --- | --- | --- |
64-| address | 输入 | Global Memory的地址。 |64+| address | 输入/输出 | Global Memory的地址。 |
65| val | 输入 | 源操作数。 |65| val | 输入 | 源操作数。 |
66 66 
67## 返回值说明67## 返回值说明
@@ -55,7 +55,7 @@ __aicore__ inline int32_t asc_atomic_exch(__gm__ int32_t* address,
55 55 
56| 参数名 | 输入/输出 | 描述 |56| 参数名 | 输入/输出 | 描述 |
57| --- | --- | --- |57| --- | --- | --- |
58-| address | 输入 | Global Memory的地址。 |58+| address | 输入/输出 | Global Memory的地址。 |
59| val | 输入 | 源操作数。 |59| val | 输入 | 源操作数。 |
60 60 
61## 返回值说明61## 返回值说明
@@ -61,7 +61,7 @@ __aicore__ inline uint32_t asc_atomic_inc(__gm__ uint32_t* address,
61 61 
62| 参数名 | 输入/输出 | 描述 |62| 参数名 | 输入/输出 | 描述 |
63| --- | --- | --- |63| --- | --- | --- |
64-| address | 输入 | Global Memory的地址。 |64+| address | 输入/输出 | Global Memory的地址。 |
65| val | 输入 | 源操作数。 |65| val | 输入 | 源操作数。 |
66 66 
67## 返回值说明67## 返回值说明
@@ -68,12 +68,13 @@ __aicore__ inline int32_t asc_atomic_max(__gm__ int32_t* address,
68 68 
69返回`address`地址中计算前的原始数据`old_value`。69返回`address`地址中计算前的原始数据`old_value`。
70 70 
71+## 流水类型
72+ 
73+PIPE_S
74+ 
71## 约束说明75## 约束说明
72 76 
73-- `address`必须落在Global Memory地址空间。
74-- `address`需按`sizeof(dtype)`字节对齐。
75- 本接口不受[asc_set_atomic_max](../datamove_atomic/asc_set_atomic_max.md)等数据搬运随路原子设置影响,也不会影响后续搬运指令。77- 本接口不受[asc_set_atomic_max](../datamove_atomic/asc_set_atomic_max.md)等数据搬运随路原子设置影响,也不会影响后续搬运指令。
76-- 对同一`address`的并发调用以原子方式完成“读取、比较、写回”,不会丢失更新;最终写入结果为各参与值中的最大值。
77- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。78- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。
78- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。79- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。
79- `float`类型下接口的性能与接口返回值是否被使用有关,具体情况如下:80- `float`类型下接口的性能与接口返回值是否被使用有关,具体情况如下:
@@ -68,12 +68,13 @@ __aicore__ inline int32_t asc_atomic_min(__gm__ int32_t* address,
68 68 
69返回`address`地址中计算前的原始数据`old_value`。69返回`address`地址中计算前的原始数据`old_value`。
70 70 
71+## 流水类型
72+ 
73+PIPE_S
74+ 
71## 约束说明75## 约束说明
72 76 
73-- `address`必须落在Global Memory地址空间。
74-- `address`需按`sizeof(dtype)`字节对齐。
75- 本接口不受[asc_set_atomic_min](../datamove_atomic/asc_set_atomic_min.md)等数据搬运随路原子设置影响,也不会影响后续搬运指令。77- 本接口不受[asc_set_atomic_min](../datamove_atomic/asc_set_atomic_min.md)等数据搬运随路原子设置影响,也不会影响后续搬运指令。
76-- 对同一`address`的并发调用以原子方式完成“读取、比较、写回”,不会丢失更新;最终写入结果为各参与值中的最小值。
77- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。78- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。
78- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。79- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。
79- `float`类型下接口的性能与接口返回值是否被使用有关,具体情况如下:80- `float`类型下接口的性能与接口返回值是否被使用有关,具体情况如下:
@@ -68,11 +68,12 @@ __aicore__ inline int32_t asc_atomic_or(__gm__ int32_t* address,
68 68 
69返回`address`地址中计算前的原始数据`old_value`。69返回`address`地址中计算前的原始数据`old_value`。
70 70 
71+## 流水类型
72+ 
73+PIPE_S
74+ 
71## 约束说明75## 约束说明
72 76 
73-- `address`必须落在Global Memory地址空间。
74-- `address`需按`sizeof(dtype)`字节对齐。
75-- 对同一`address`的并发调用以原子方式完成“读取、按位或、写回”,不会丢失更新;最终写入结果为各参与值的按位或结果。
76- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。77- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。
77- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。78- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。
78 79 
@@ -68,11 +68,12 @@ __aicore__ inline int32_t asc_atomic_sub(__gm__ int32_t* address,
68 68 
69返回`address`地址中计算前的原始数据`old_value`。69返回`address`地址中计算前的原始数据`old_value`。
70 70 
71+## 流水类型
72+ 
73+PIPE_S
74+ 
71## 约束说明75## 约束说明
72 76 
73-- `address`必须落在Global Memory地址空间。
74-- `address`需按`sizeof(dtype)`字节对齐。
75-- 对同一`address`的并发调用以原子方式完成“读取、计算、写回”,不会丢失更新。`dtype`为`float`时,最终结果可能因执行顺序不同而存在差异;如需确定性计算结果,需要通过同步指令控制执行顺序。
76- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。77- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。
77- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。78- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。
78 79 
@@ -68,11 +68,12 @@ __aicore__ inline int32_t asc_atomic_xor(__gm__ int32_t* address,
68 68 
69返回`address`地址中计算前的原始数据`old_value`。69返回`address`地址中计算前的原始数据`old_value`。
70 70 
71+## 流水类型
72+ 
73+PIPE_S
74+ 
71## 约束说明75## 约束说明
72 76 
73-- `address`必须落在Global Memory地址空间。
74-- `address`需按`sizeof(dtype)`字节对齐。
75-- 对同一`address`的并发调用以原子方式完成“读取、计算、写回”,不会丢失更新;最终写入结果为各参与值的按位异或结果。
76- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。77- 本接口运行在标量流水(`PIPE_S`)上,同一标量流水内的数据依赖由指令执行顺序保证。若本接口与`PIPE_MTE2`或`PIPE_MTE3`上的数据搬运指令访问同一GM地址,且执行顺序影响结果,编译器无法自动完成跨流水同步,调用方需按实际依赖插入[asc_sync_pipe](../../sync/intra_core_sync/asc_sync_pipe.md),或配合使用[asc_sync_notify](../../sync/intra_core_sync/asc_sync_notify.md)与[asc_sync_wait](../../sync/intra_core_sync/asc_sync_wait.md)保证执行顺序。
77- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。78- 本接口访问GM时绕过DCache,不维护缓存一致性。若其他核或其他通路通过缓存访问同一GM地址,调用方需使用[asc_dcci](../../cache_ctrl/asc_dcci.md)清理或失效对应Cache Line,并使用[asc_sync_data_barrier](../../sync/intra_core_sync/asc_sync_data_barrier.md)保证相关访存操作的执行顺序和数据可见性。详情可参考[Scalar原子操作与DCache一致性](../../../../../guide/programming_guide/advanced_programming/memory_model/cache_coherence.md#scalar原子操作与dcache一致性)。
78 79