11-03 内存拷贝与设置
本章节描述 Host-Device 间及 Device-Device 间的内存拷贝与内存设置接口。
aclError aclrtMemcpy(void *dst, size_t destMax, const void *src, size_t count, aclrtMemcpyKind kind)：实现内存复制。aclError aclrtMemcpyAsync(void *dst, size_t destMax, const void *src, size_t count, aclrtMemcpyKind kind, aclrtStream stream)：实现内存复制。aclError aclrtMemcpyAsyncWithCondition(void *dst, size_t destMax, const void *src, size_t count, aclrtMemcpyKind kind, aclrtStream stream)：实现内存复制。（废弃接口，请使用aclrtMemcpyAsync接口）aclError aclrtMemcpyBatch(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs, size_t *failIndex)：实现批量内存复制。aclError aclrtMemcpyBatchAsync(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs, size_t *failIndex, aclrtStream stream)：实现批量内存复制。aclError aclrtMemcpyBatchV2(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs)：实现批量内存复制。aclError aclrtMemcpyBatchAsyncV2(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs, aclrtStream stream)：实现批量内存复制。aclError aclrtMemcpy2d(void *dst, size_t dpitch, const void *src, size_t spitch, size_t width, size_t height, aclrtMemcpyKind kind)：实现同步内存复制，主要用于矩阵数据的复制。aclError aclrtMemcpy2dAsync(void *dst, size_t dpitch, const void *src, size_t spitch, size_t width, size_t height, aclrtMemcpyKind kind, aclrtStream stream)：实现异步内存复制，主要用于矩阵数据的复制。异步接口。aclError aclrtGetMemcpyDescSize(aclrtMemcpyKind kind, size_t *descSize)：获取当前Device的内存复制描述符占用的内存大小。aclError aclrtSetMemcpyDesc(void *desc, aclrtMemcpyKind kind, void *srcAddr, void *dstAddr, size_t count, void *config)：设置内存复制描述符，此接口调用完成后，会将源地址，目的地址、内存复制长度记录到内存复制描述符中。aclError aclrtMemcpyAsyncWithDesc(void *desc, aclrtMemcpyKind kind, aclrtStream stream)：使用内存复制描述符（二级指针方式）进行内存复制。异步接口。aclError aclrtMemcpyAsyncWithOffset(void **dst, size_t destMax, size_t dstDataOffset, const void **src, size_t count, size_t srcDataOffset, aclrtMemcpyKind kind, aclrtStream stream)：实现内存复制，适用于基地址是二级指针、有地址偏移的场景。异步接口。aclError aclrtMemset(void *devPtr, size_t maxCount, int32_t value, size_t count)：初始化内存，将内存中的内容设置为指定的值。aclError aclrtMemsetAsync(void *devPtr, size_t maxCount, int32_t value, size_t count, aclrtStream stream)：初始化内存，将内存中的内容设置为指定的值。异步接口。aclError aclrtMemsetD32(void *ptr, size_t memSize, uint32_t value, size_t N)：初始化内存，将内存中的内容设置为指定的32位无符号整数值，按元素填充。aclError aclrtMemsetD32Async(void *ptr, size_t memSize, uint32_t value, size_t N, aclrtStream stream)：初始化内存，将内存中的内容设置为指定的32位无符号整数值。异步接口。
aclrtMemcpy
aclError aclrtMemcpy(void *dst, size_t destMax, const void *src, size_t count, aclrtMemcpyKind kind)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：支持
功能说明
实现内存复制。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| destMax | 输入 | 目的内存地址的最大内存长度，单位Byte。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| kind | 输入 | 内存复制的类型，预留参数，配置枚举值中的值无效，系统内部会根据源内存地址指针、目的内存地址指针判断是否可以将源地址的数据复制到目的地址，如果不可以，则系统会返回报错。 类型定义请参见aclrtMemcpyKind。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 本接口会立刻进行内存复制，函数内部不会进行隐式的device同步或流同步。
-
如果执行两个Device间的内存复制，需先调用aclrtDeviceCanAccessPeer接口查询两个Device间是否支持数据交互、调用aclrtDeviceEnablePeerAccess接口开启两个Device间的数据交互功能，再调用本接口进行内存复制。
该约束适用以下型号：
Ascend 950PR/Ascend 950DT
Atlas A2 训练系列产品/Atlas A2 推理系列产品
Atlas 推理系列产品
Atlas 训练系列产品
aclrtMemcpyAsync
aclError aclrtMemcpyAsync(void *dst, size_t destMax, const void *src, size_t count, aclrtMemcpyKind kind, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
实现内存复制。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成；当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| destMax | 输入 | 目的内存地址的最大内存长度，单位Byte。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- Ascend EP形态下，本接口不支持异步Host内的内存复制功能，若传入的kind为ACL_MEMCPY_HOST_TO_HOST时，接口返回报错ACL_ERROR_RT_FEATURE_NOT_SUPPORT。
- Ascend RC形态下，在板端运行应用时，若调用本接口传入的kind为ACL_MEMCPY_HOST_TO_DEVICE或ACL_MEMCPY_DEVICE_TO_HOST或ACL_MEMCPY_HOST_TO_HOST，系统内部将默认使用ACL_MEMCPY_DEVICE_TO_DEVICE执行Device内的内存复制。
- Control CPU开放形态下，在Device上运行应用时，若调用本接口传入的kind为ACL_MEMCPY_HOST_TO_DEVICE或ACL_MEMCPY_DEVICE_TO_HOST或ACL_MEMCPY_HOST_TO_HOST，系统内部将默认使用ACL_MEMCPY_DEVICE_TO_DEVICE执行Device内的内存复制。
aclrtMemcpyAsyncWithCondition（废弃）
aclError aclrtMemcpyAsyncWithCondition(void *dst, size_t destMax, const void *src, size_t count, aclrtMemcpyKind kind, aclrtStream stream)
须知：此接口后续版本会废弃，请使用aclrtMemcpyAsync接口。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：支持
功能说明
实现内存复制。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回；当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| destMax | 输入 | 目的内存地址的最大内存长度，单位Byte。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- Ascend EP形态下，本接口不支持异步Host内的内存复制功能，若传入的kind为ACL_MEMCPY_HOST_TO_HOST时，接口返回报错ACL_ERROR_RT_FEATURE_NOT_SUPPORT。
- Ascend RC形态下，在板端运行应用时，若调用本接口传入的kind为ACL_MEMCPY_HOST_TO_DEVICE或ACL_MEMCPY_DEVICE_TO_HOST或ACL_MEMCPY_HOST_TO_HOST，系统内部将默认使用ACL_MEMCPY_DEVICE_TO_DEVICE执行Device内的内存复制。
- Control CPU开放形态下，在Device上运行应用时，若调用本接口传入的kind为ACL_MEMCPY_HOST_TO_DEVICE或ACL_MEMCPY_DEVICE_TO_HOST或ACL_MEMCPY_HOST_TO_HOST，系统内部将默认使用ACL_MEMCPY_DEVICE_TO_DEVICE执行Device内的内存复制。
aclrtMemcpyBatch
aclError aclrtMemcpyBatch(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs, size_t *failIndex)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现批量内存复制。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dsts | 输入 | 目的内存地址数组。 |
| destMaxs | 输入 | 内存复制最大长度数组，用于存放每一段要复制的内存的最大长度，单位Byte。 |
| srcs | 输入 | 源内存地址数组。 |
| sizes | 输入 | 内存复制长度数组，用于存放每一段要复制的内存大小，单位Byte。 |
| numBatches | 输入 | dsts、srcs和sizes数组的长度。 |
| attrs | 输入 | 内存复制属性数组。类型定义请参见aclrtMemcpyBatchAttr。 |
| attrsIndexes | 输入 | 内存复制属性索引数组，用于指定attrs数组中每个条目适用的复制范围。attrs[k]中指定的属性将应用于从attrsIndexes[k]到attrsIndexes[k+1] - 1的复制操作，同时attrs[numAttrs-1]将应用于从attrsIndexes[numAttrs-1]到numBatches - 1的复制操作。 |
| numAttrs | 输入 | attrs和attrsIndexes数组的长度。 |
| failIndex | 输出 | 用于发生错误时指示出错的复制项下标（仅支持对内存属性和复制方向的校验）。若错误不涉及特定复制操作，该值将为SIZE_MAX。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 批次内的内存拷贝是无序的，不会按照数组中元素的顺序拷贝。
- 将srcs中指定的数据复制到dsts中指定的内存区域，每个复制操作的大小由sizes指定，dsts、srcs、sizes这三个数组必须具有numBatches指定的相同长度。
- 批处理中的每个复制操作必须与attrs数组中指定的属性集相关联，attrs数组中的每个条目可应用于多个复制操作，具体通过attrsIndexes数组指定对应属性条目生效的起始复制索引。attrs和attrsIndexes这两个数组必须具有numAttrs指定的相同长度。例如：若批处理包含dsts/srcs/sizes列出的10个复制操作，其中前6个使用一组属性，后4个使用另一组属性，则numAttrs为2，attrsIndexes为{0,6}，attrs包含两组属性。注意，attrsIndexes的首个条目必须为0，且每个条目必须大于前一个条目，最后一个条目应小于numBatches。此外numAttrs必须小于等于numBatches。
- 批量内存复制的方向仅支持“从Host到Device”或者“从Device到Host”中的一种。
aclrtMemcpyBatchAsync
aclError aclrtMemcpyBatchAsync(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs, size_t *failIndex, aclrtStream stream)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现批量内存复制。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回；当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dsts | 输入 | 目的内存地址数组。 |
| destMaxs | 输入 | 内存复制最大长度数组，用于存放每一段要复制的内存的最大长度，单位Byte。 |
| srcs | 输入 | 源内存地址数组。 |
| sizes | 输入 | 内存复制长度数组，用于存放每一段要复制的内存大小，单位Byte。 |
| numBatches | 输入 | dsts、srcs和sizes数组的长度。 |
| attrs | 输入 | 内存复制属性数组。类型定义请参见aclrtMemcpyBatchAttr。 |
| attrsIndexes | 输入 | 内存复制属性索引数组，用于指定attrs数组中每个条目适用的复制范围。attrs[k]中指定的属性将应用于从attrsIndexes[k]到attrsIndexes[k+1] - 1的复制操作，同时attrs[numAttrs-1]将应用于从attrsIndexes[numAttrs-1]到numBatches - 1的复制操作。 |
| numAttrs | 输入 | attrs和attrsIndexes数组的长度。 |
| failIndex | 输出 | 用于发生错误时指示出错的复制项下标（仅支持对内存属性和复制方向的校验）。若错误不涉及特定复制操作，该值将为SIZE_MAX。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 批次内的内存拷贝是无序的，不会按照数组中元素的顺序拷贝。
- 将srcs中指定的数据复制到dsts中指定的内存区域，每个复制操作的大小由sizes指定，dsts、srcs、sizes这三个数组必须具有numBatches指定的相同长度。
- 批处理中的每个复制操作必须与attrs数组中指定的属性集相关联，attrs数组中的每个条目可应用于多个复制操作，具体通过attrsIndexes数组指定对应属性条目生效的起始复制索引。attrs和attrsIndexes这两个数组必须具有numAttrs指定的相同长度。例如：若批处理包含dsts/srcs/sizes列出的10个复制操作，其中前6个使用一组属性，后4个使用另一组属性，则numAttrs为2，attrsIndexes为{0,6}，attrs包含两组属性。注意，attrsIndexes的首个条目必须为0，且每个条目必须大于前一个条目，最后一个条目应小于numBatches。此外numAttrs必须小于等于numBatches。
- 批量内存复制的方向仅支持“从Host到Device”或者“从Device到Host”中的一种。
aclrtMemcpyBatchV2
aclError aclrtMemcpyBatchV2(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现批量内存复制。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。
与aclrtMemcpyBatch接口相比，本接口不再通过failIndex参数返回失败的复制项下标。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dsts | 输入 | 目的内存地址数组。 |
| destMaxs | 输入 | 内存复制最大长度数组，用于存放每一段要复制的内存的最大长度，单位Byte。 |
| srcs | 输入 | 源内存地址数组。 |
| sizes | 输入 | 内存复制长度数组，用于存放每一段要复制的内存大小，单位Byte。 |
| numBatches | 输入 | dsts、srcs和sizes数组的长度。 |
| attrs | 输入 | 内存复制属性数组。类型定义请参见aclrtMemcpyBatchAttr。 |
| attrsIndexes | 输入 | 内存复制属性索引数组，用于指定attrs数组中每个条目适用的复制范围。attrs[k]中指定的属性将应用于从attrsIndexes[k]到attrsIndexes[k+1] - 1的复制操作，同时attrs[numAttrs-1]将应用于从attrsIndexes[numAttrs-1]到numBatches - 1的复制操作。 |
| numAttrs | 输入 | attrs和attrsIndexes数组的长度。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 批次内的内存拷贝是无序的，不会按照数组中元素的顺序拷贝。
- 将srcs中指定的数据复制到dsts中指定的内存区域，每个复制操作的大小由sizes指定，dsts、srcs、sizes这三个数组必须具有numBatches指定的相同长度。
- 批处理中的每个复制操作必须与attrs数组中指定的属性集相关联，attrs数组中的每个条目可应用于多个复制操作，具体通过attrsIndexes数组指定对应属性条目生效的起始复制索引。attrs和attrsIndexes这两个数组必须具有numAttrs指定的相同长度。例如：若批处理包含dsts/srcs/sizes列出的10个复制操作，其中前6个使用一组属性，后4个使用另一组属性，则numAttrs为2，attrsIndexes为{0,6}，attrs包含两组属性。注意，attrsIndexes的首个条目必须为0，且每个条目必须大于前一个条目，最后一个条目应小于numBatches。此外numAttrs必须小于等于numBatches。
- 批量内存复制的方向仅支持“从Host到Device”或者“从Device到Host”中的一种。
aclrtMemcpyBatchAsyncV2
aclError aclrtMemcpyBatchAsyncV2(void **dsts, size_t *destMaxs, void **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr *attrs, size_t *attrsIndexes, size_t numAttrs, aclrtStream stream)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现批量内存复制。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回；当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成。
与aclrtMemcpyBatchAsync接口相比，本接口不再通过failIndex参数返回失败的复制项下标。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dsts | 输入 | 目的内存地址数组。 |
| destMaxs | 输入 | 内存复制最大长度数组，用于存放每一段要复制的内存的最大长度，单位Byte。 |
| srcs | 输入 | 源内存地址数组。 |
| sizes | 输入 | 内存复制长度数组，用于存放每一段要复制的内存大小，单位Byte。 |
| numBatches | 输入 | dsts、srcs和sizes数组的长度。 |
| attrs | 输入 | 内存复制属性数组。类型定义请参见aclrtMemcpyBatchAttr。 |
| attrsIndexes | 输入 | 内存复制属性索引数组，用于指定attrs数组中每个条目适用的复制范围。attrs[k]中指定的属性将应用于从attrsIndexes[k]到attrsIndexes[k+1] - 1的复制操作，同时attrs[numAttrs-1]将应用于从attrsIndexes[numAttrs-1]到numBatches - 1的复制操作。 |
| numAttrs | 输入 | attrs和attrsIndexes数组的长度。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 批次内的内存拷贝是无序的，不会按照数组中元素的顺序拷贝。
- 将srcs中指定的数据复制到dsts中指定的内存区域，每个复制操作的大小由sizes指定，dsts、srcs、sizes这三个数组必须具有numBatches指定的相同长度。
- 批处理中的每个复制操作必须与attrs数组中指定的属性集相关联，attrs数组中的每个条目可应用于多个复制操作，具体通过attrsIndexes数组指定对应属性条目生效的起始复制索引。attrs和attrsIndexes这两个数组必须具有numAttrs指定的相同长度。例如：若批处理包含dsts/srcs/sizes列出的10个复制操作，其中前6个使用一组属性，后4个使用另一组属性，则numAttrs为2，attrsIndexes为{0,6}，attrs包含两组属性。注意，attrsIndexes的首个条目必须为0，且每个条目必须大于前一个条目，最后一个条目应小于numBatches。此外numAttrs必须小于等于numBatches。
- 批量内存复制的方向仅支持“从Host到Device”或者“从Device到Host”中的一种。
aclrtMemcpy2d
aclError aclrtMemcpy2d(void *dst, size_t dpitch, const void *src, size_t spitch, size_t width, size_t height, aclrtMemcpyKind kind)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
实现同步内存复制，主要用于矩阵数据的复制。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| dpitch | 输入 | 目的内存中相邻两列向量的地址距离。 |
| src | 输入 | 源内存地址指针。 |
| spitch | 输入 | 源内存中相邻两列向量的地址距离。 |
| width | 输入 | 待复制的数据宽度。 |
| height | 输入 | 待复制的数据高度。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 当前仅支持ACL_MEMCPY_HOST_TO_DEVICE类型和ACL_MEMCPY_DEVICE_TO_HOST类型的内存复制。
- 对于Atlas 推理系列产品，Control CPU开放形态下，不支持调用本接口。另外，Atlas 推理系列加速模块产品也不支持本接口。
- 对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。
参考资源
本接口的内存复制示意图：
aclrtMemcpy2dAsync
aclError aclrtMemcpy2dAsync(void *dst, size_t dpitch, const void *src, size_t spitch, size_t width, size_t height, aclrtMemcpyKind kind, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
实现异步内存复制，主要用于矩阵数据的复制。异步接口。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回；当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| dpitch | 输入 | 目的内存中相邻两列向量的地址距离。 |
| src | 输入 | 源内存地址指针。 |
| spitch | 输入 | 源内存中相邻两列向量的地址距离。 |
| width | 输入 | 待复制的数据宽度。 width最大设置为5000000，且必须小于或等于dpitch和spitch。 |
| height | 输入 | 待复制的数据高度。 height最大设置为510241024=5242880，否则接口返回失败。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
-
本接口仅支持ACL_MEMCPY_HOST_TO_DEVICE、ACL_MEMCPY_DEVICE_TO_HOST或ACL_MEMCPY_DEVICE_TO_DEVICE内存复制类型，且不同型号支持的类型不同。对于不支持的内存复制类型，接口返回ACL_ERROR_INVALID_PARAM。
其中，ACL_MEMCPY_DEVICE_TO_DEVICE类型，仅Ascend 950PR/Ascend 950DT、Atlas A3 训练系列产品/Atlas A3 推理系列产品、Atlas A2 训练系列产品/Atlas A2 推理系列产品支持。
- 对于Atlas 推理系列产品，Control CPU开放形态下，不支持调用本接口。另外，Atlas 推理系列加速模块产品也不支持本接口。
- 对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。
参考资源
本接口的内存复制示意图：
aclrtGetMemcpyDescSize
aclError aclrtGetMemcpyDescSize(aclrtMemcpyKind kind, size_t *descSize)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
获取当前Device的内存复制描述符占用的内存大小。
本接口需与其它关键接口配合使用，以便实现内存复制，详细描述请参见aclrtMemcpyAsyncWithDesc。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 当前仅支持ACL_MEMCPY_INNER_DEVICE_TO_DEVICE，表示Device内的内存复制。 |
| descSize | 输出 | 内存大小，单位Byte。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtSetMemcpyDesc
aclError aclrtSetMemcpyDesc(void *desc, aclrtMemcpyKind kind, void *srcAddr, void *dstAddr, size_t count, void *config)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
设置内存复制描述符，此接口调用完成后，会将源地址，目的地址、内存复制长度记录到内存复制描述符中。
本接口需与其它关键接口配合使用，以便实现内存复制，详细描述请参见aclrtMemcpyAsyncWithDesc。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| desc | 输出 | 内存复制描述符地址指针。 需先调用aclrtGetMemcpyDescSize接口获取内存描述符所需的内存大小，再申请Device内存后（例如aclrtMalloc接口），将Device内存地址作为入参传入此处。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 当前仅支持ACL_MEMCPY_INNER_DEVICE_TO_DEVICE，表示Device内的内存复制。 |
| srcAddr | 输入 | 源内存地址指针。 由用户申请内存并管理内存。 |
| dstAddr | 输入 | 目的内存地址指针。 由用户申请内存并管理内存。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| config | 输入 | 预留参数，当前固定传NULL。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemcpyAsyncWithDesc
aclError aclrtMemcpyAsyncWithDesc(void *desc, aclrtMemcpyKind kind, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
使用内存复制描述符（二级指针方式）进行内存复制。异步接口。
本接口需与以下其它关键接口配合使用，以便实现内存复制：
- 调用aclrtGetMemcpyDescSize接口获取内存描述符所需的内存大小。
- 申请Device内存，用于存放内存描述符。
- 申请源内存、目的内存，分别用于存放复制前后的数据。
- 调用aclrtSetMemcpyDesc接口将源内存地址、目的内存地址等信息设置到内存描述符中。
- 调用aclrtMemcpyAsyncWithDesc接口实现内存复制。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| desc | 输入 | 内存复制描述符地址指针，Device侧内存地址。 此处需先调用aclrtSetMemcpyDesc接口设置内存复制描述符，再将内存复制描述符地址指针作为入参传入本接口。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 当前仅支持ACL_MEMCPY_INNER_DEVICE_TO_DEVICE，表示Device内的内存复制。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemcpyAsyncWithOffset
aclError aclrtMemcpyAsyncWithOffset(void **dst, size_t destMax, size_t dstDataOffset, const void **src, size_t count, size_t srcDataOffset, aclrtMemcpyKind kind, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
实现内存复制，适用于基地址是二级指针、有地址偏移的场景。异步接口。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| destMax | 输入 | 目的内存地址的最大内存长度，单位Byte。 |
| dstDataOffset | 输入 | 目的内存地址偏移。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| srcDataOffset | 输入 | 源内存地址偏移。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 当前kind只支持ACL_MEMCPY_INNER_DEVICE_TO_DEVICE（Device内的内存复制）。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemset
aclError aclrtMemset(void *devPtr, size_t maxCount, int32_t value, size_t count)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：支持
功能说明
初始化内存，将内存中的内容设置为指定的值。
要初始化的内存支持在Host侧或Device侧，系统根据地址判定是Host还是Device。如果Host内存不是用acl接口（例如aclrtMallocHost）申请的，将会导致未定义的行为。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| devPtr | 输入 | 内存起始地址的指针。 |
| maxCount | 输入 | 内存的最大长度，单位Byte。 |
| value | 输入 | 设置的值。 |
| count | 输入 | 需要设置为指定值的内存长度，单位Byte。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
本接口会立刻进行内存初始化，函数内部不会进行隐式的device同步或流同步。
aclrtMemsetAsync
aclError aclrtMemsetAsync(void *devPtr, size_t maxCount, int32_t value, size_t count, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
初始化内存，将内存中的内容设置为指定的值。异步接口。
要初始化的内存支持在Host侧或Device侧，系统根据地址判定是Host还是Device。如果Host内存不是用acl接口（例如aclrtMallocHost）申请的，将会导致未定义的行为。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| devPtr | 输入 | 内存起始地址的指针。 |
| maxCount | 输入 | 内存的最大长度，单位Byte。 |
| value | 输入 | 设置的值。 |
| count | 输入 | 需要设置为指定值的内存长度，单位Byte。 |
| stream | 输入 | 指定执行内存初始化任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemsetD32
aclError aclrtMemsetD32(void *ptr, size_t memSize, uint32_t value, size_t N)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
初始化内存，将其内容设置为指定的32位无符号整数值。
与aclrtMemset的区别在于：本接口以32位无符号整数为单位进行填充，其中N表示所填充的32位无符号整数值的数量。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptr | 输入 | 内存起始地址的指针。此处的内存仅支持aclrtMallocHost或aclrtMalloc申请。 |
| memSize | 输入 | 内存的最大长度，单位Byte（必须≥N*4）。 |
| value | 输入 | 要填充的32位无符号整数值。 |
| N | 输入 | 所填充的32位无符号整数值的数量。 |
返回值说明
返回ACL_SUCCESS表示成功，返回其他值表示失败，请参见aclError。
约束说明
本接口会立即执行内存初始化，函数内部不会进行隐式device同步或流同步。
aclrtMemsetD32Async
aclError aclrtMemsetD32Async(void *ptr, size_t memSize, uint32_t value, size_t N, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
初始化内存，将其内容设置为指定的32位无符号整数值。异步接口。
与aclrtMemset的区别在于：本接口以32位无符号整数为单位进行填充，其中N表示所填充的32位无符号整数值的数量。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptr | 输入 | 内存起始地址的指针。此处的内存仅支持aclrtMallocHost或aclrtMalloc申请。 |
| memSize | 输入 | 内存的最大长度，单位Byte（必须≥N*4）。 |
| value | 输入 | 要填充的32位无符号整数值。 |
| N | 输入 | 所填充的32位无符号整数值的数量。 |
| stream | 输入 | 指定执行内存初始化任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回ACL_SUCCESS表示成功，返回其他值表示失败，请参见aclError。
约束说明
Device内存的初始化任务将被下发到指定的Stream上执行，调用方需确保该Stream有效且未被销毁。如果在stream参数处传入nullptr，则会使用默认Stream。
Host内存的初始化任务不会下发到Stream上执行，因此该接口的行为与aclrtMemsetD32接口一致。