Merged
docs: ViewCopy接口新增inplaceFlag参数说明 #1129
ren-botaoAdd on 11 days ago
docs: ViewCopy接口新增inplaceFlag参数说明 #1129
Merged
ren-botaoAdd on 11 days ago
Total: 3 files changed+23-3
@@ -32,7 +32,7 @@ Possible causes:
32- When a single-operator API is called, aclOpExecutor reuse cannot be enabled in the following scenarios:32- When a single-operator API is called, aclOpExecutor reuse cannot be enabled in the following scenarios:
33 33 
34 - If L0 APIs related to host-to-device and device-to-device copy are used, such as CopyToNpu, CopyNpuToNpu, and CopyToNpuSync, aclOpExecutor cannot be reused.34 - If L0 APIs related to host-to-device and device-to-device copy are used, such as CopyToNpu, CopyNpuToNpu, and CopyToNpuSync, aclOpExecutor cannot be reused.
35- - If the L0 ViewCopy API is used and the source address and destination address of ViewCopy are the same, aclOpExecutor cannot be reused.35+ - If the L0 ViewCopy API is used and the source address and destination address of ViewCopy are the same, aclOpExecutor cannot be reused. If an in-place scenario is declared through the `inplaceFlag` parameter (four-parameter prototype) when ViewCopy is called, the same source and destination addresses no longer affect aclOpExecutor reuse.
36 36 
37- When a single-operator API is called, a device tensor cannot be created in the operator API. Only external tensors can be used.37- When a single-operator API is called, a device tensor cannot be created in the operator API. Only external tensors can be used.
38- aclOpExecutor that is set to the reusable state does not clear the executor resources after the second-phase API is executed. It needs to be used together with [aclDestroyAclOpExecutor](aclDestroyAclOpExecutor.md) to destroy the resources.38- aclOpExecutor that is set to the reusable state does not clear the executor resources after the second-phase API is executed. It needs to be used together with [aclDestroyAclOpExecutor](aclDestroyAclOpExecutor.md) to destroy the resources.
@@ -32,7 +32,7 @@ aclnnStatus aclSetAclOpExecutorRepeatable(aclOpExecutor *executor)
32- 调用单算子API执行接口时,如下场景无法开启aclOpExecutor复用:32- 调用单算子API执行接口时,如下场景无法开启aclOpExecutor复用:
33 33 
34 - 如果使用了HostToDevice、DeviceToDevice拷贝相关的L0层API,如CopyToNpu、CopyNpuToNpu、CopyToNpuSync等,不支持aclOpExecutor复用。34 - 如果使用了HostToDevice、DeviceToDevice拷贝相关的L0层API,如CopyToNpu、CopyNpuToNpu、CopyToNpuSync等,不支持aclOpExecutor复用。
35- - 如果使用了L0层ViewCopy接口,同时ViewCopy的源地址和目的地址相同时,不支持aclOpExecutor复用。35+ - 如果使用了L0层ViewCopy接口,同时ViewCopy的源地址和目的地址相同时,不支持aclOpExecutor复用;如果调用ViewCopy时通过inplaceFlag参数(4参数原型)声明为原地场景,则同址不再影响aclOpExecutor复用。
36 36 
37- 调用单算子API执行接口时,不允许算子API内部创建Device Tensor,只允许使用外部传入的Tensor。37- 调用单算子API执行接口时,不允许算子API内部创建Device Tensor,只允许使用外部传入的Tensor。
38- 设置成复用状态的aclOpExecutor在第二段接口执行完后不会对executor的资源进行清理,需要和[aclDestroyAclOpExecutor](aclDestroyAclOpExecutor.md)配套使用清理资源。38- 设置成复用状态的aclOpExecutor在第二段接口执行完后不会对executor的资源进行清理,需要和[aclDestroyAclOpExecutor](aclDestroyAclOpExecutor.md)配套使用清理资源。
@@ -29,12 +29,18 @@
29 29 
30输出tensor可以是连续或非连续的,接口内部会兼容处理,但输入要求是连续的。30输出tensor可以是连续或非连续的,接口内部会兼容处理,但输入要求是连续的。
31 31 
32+部分aclnn接口采用原地实现,即输出与输入指向同一块内存。当调用ViewCopy的x、y构成原地关系(判定条件见[约束说明](#约束说明))时,3参数原型会禁用aclnn算子缓存;使用4参数原型并将`inplaceFlag`设置为true,则不禁用aclnn算子缓存。
33+ 
32## 函数原型34## 函数原型
33 35 
34```cpp36```cpp
35const aclTensor *ViewCopy(const aclTensor *x, const aclTensor *y, aclOpExecutor *executor)37const aclTensor *ViewCopy(const aclTensor *x, const aclTensor *y, aclOpExecutor *executor)
36```38```
37 39 
40+```cpp
41+const aclTensor *ViewCopy(const aclTensor *x, const aclTensor *y, aclOpExecutor *executor, bool inplaceFlag)
42+```
43+ 
38## 参数说明44## 参数说明
39 45 
40| 参数 | 输入/输出 | 说明 |46| 参数 | 输入/输出 | 说明 |
@@ -42,6 +48,7 @@ const aclTensor *ViewCopy(const aclTensor *x, const aclTensor *y, aclOpExecutor
42| x | 输入 | 输入tensor。数据类型和数据格式不限制。输入必须保证是连续内存数据。 |48| x | 输入 | 输入tensor。数据类型和数据格式不限制。输入必须保证是连续内存数据。 |
43| y | 输出 | 输出tensor。数据类型和数据格式不限制,但数据类型、ViewShape和数据格式要求与x一致。 |49| y | 输出 | 输出tensor。数据类型和数据格式不限制,但数据类型、ViewShape和数据格式要求与x一致。 |
44| executor | 输入 | op执行器,包含了算子计算流程。 |50| executor | 输入 | op执行器,包含了算子计算流程。 |
51+| inplaceFlag | 输入 | 原地场景标记,仅4参数原型支持。当调用方能确定x、y构成原地关系时,设置为true;否则为false。详细说明参见[约束说明](#约束说明)。 |
45 52 
46## 返回值说明53## 返回值说明
47 54 
@@ -51,11 +58,24 @@ const aclTensor *ViewCopy(const aclTensor *x, const aclTensor *y, aclOpExecutor
51 58 
52要求输入tensor是连续的tensor。59要求输入tensor是连续的tensor。
53 60 
61+x与y的数据类型、数据格式和ViewShape需一致,且y不能来自workspace,否则接口返回nullptr。
62+ 
63+x与y构成原地关系的条件为:x、y均为连续tensor,均不是executor分配的workspace数据(即二者的数据均来自aclnn接口传入的tensor),且`x->GetData()`与`y->GetData()`相等(即二者指向同一块tensor数据的内存地址)。当调用方能确定x、y构成原地关系时,可将`inplaceFlag`设置为true;否则应设置为false(或使用3参数原型)。接口按下述逻辑识别并处理该参数:
64+ 
65+- **识别场景**:仅在x与y构成原地关系时,接口识别`inplaceFlag`;其余情况不识别该参数。
66+- **处理方式**:识别到该参数后,接口据其取值决定是否禁用aclnn算子缓存:
67+ - `inplaceFlag`为false(或未指定):禁用aclnn算子缓存。原因是缓存key不包含tensor数据的内存地址,无法区分“x与y同址”和“x与y不同址”这两种调用,而这两种调用下aclnn算子的执行逻辑并不相同,同址时复用按不同址场景生成的缓存会与预期不符。
68+ - `inplaceFlag`为true:不禁用aclnn算子缓存。调用方已确定x、y为原地关系,不存在同址与不同址混用的场景,缓存key不再有上述歧义,可避免原地场景下不必要的缓存失效。
69+ 
54## 调用示例70## 调用示例
55 71 
56```cpp72```cpp
57// 标准写法,创建OpExecutor73// 标准写法,创建OpExecutor
58auto uniqueExecutor = CREATE_EXECUTOR();74auto uniqueExecutor = CREATE_EXECUTOR();
75+ 
59// 如果出参out是非连续Tensor,需要把计算完的连续Tensor转非连续76// 如果出参out是非连续Tensor,需要把计算完的连续Tensor转非连续
60-auto viewCopyResult = l0op::ViewCopy(absResult, out, executor);77+auto viewCopyResult = l0op::ViewCopy(absResult, out, uniqueExecutor.get());
78+ 
79+// 原地场景:x和y指向同一块内存,将inplaceFlag设置为true
80+auto viewCopyInplaceResult = l0op::ViewCopy(selfRef, selfRef, uniqueExecutor.get(), true);
61```81```