Merged
docs: ViewCopy接口新增inplaceFlag参数说明 #1129
ren-botaoAdd on 11 days ago
docs: ViewCopy接口新增inplaceFlag参数说明 #1129
Merged
Merged fromren-botao/opbaseadd_view_copy_inplace_apiintocann/opbasemaster
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 | ```cpp | 36 | ```cpp |
| 35 | const aclTensor *ViewCopy(const aclTensor *x, const aclTensor *y, aclOpExecutor *executor) | 37 | const 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 | ```cpp | 72 | ```cpp |
| 57 | // 标准写法,创建OpExecutor | 73 | // 标准写法,创建OpExecutor |
| 58 | auto uniqueExecutor = CREATE_EXECUTOR(); | 74 | auto 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 | ``` |