26. C++扩展接口
本章节描述 C++ 扩展接口，包括函数重载和模板封装，用于简化 C++ 场景下的 API 调用并提供类型安全的内存操作。
aclError aclrtSynchronizeDevice(int32_t timeout)：设备同步，简化接口。aclError aclrtSynchronizeStream(aclrtStream stream, int32_t timeout)：流同步，简化接口。aclError aclrtSynchronizeEvent(aclrtEvent event, int32_t timeout)：事件同步，简化接口。aclError aclrtStreamWaitEvent(aclrtStream stream, aclrtEvent event, int32_t timeout)：流等待事件，简化接口。aclError aclrtCreateStream(aclrtStream *stream, uint32_t priority, uint32_t flag)：创建流，简化接口。aclError aclrtSetOpExecuteTimeOut(uint64_t timeout, uint64_t *actualTimeout)：设置算子执行超时，简化接口。aclError aclrtCreateEvent(aclrtEvent *event, uint32_t flag)：创建事件，简化接口。template <typename T> aclError aclrtMalloc(T **devPtr, size_t size, aclrtMallocConfig *cfg = nullptr)：类型安全的设备内存分配。template <typename T> aclError aclrtMallocHost(T **hostPtr, size_t size, aclrtMallocConfig *cfg = nullptr)：类型安全的主机内存分配。template <typename T, typename U> aclError aclrtMemcpy(T *dst, size_t destMax, const U *src, size_t count, aclrtMemcpyKind kind)：类型安全的内存拷贝。template <typename T, typename U> aclError aclrtMemcpyAsync(T *dst, size_t destMax, const U *src, size_t count, aclrtMemcpyKind kind, aclrtStream stream)：异步内存拷贝。template <typename T, typename U> aclError aclrtMemcpy2d(T *dst, size_t dpitch, const U *src, size_t spitch, size_t width, size_t height, aclrtMemcpyKind kind)：2D内存拷贝。template <typename T, typename U> aclError aclrtMemcpy2dAsync(T *dst, size_t dpitch, const U *src, size_t spitch, size_t width, size_t height, aclrtMemcpyKind kind, aclrtStream stream)：异步2D内存拷贝。template <typename T, typename U> aclError aclrtMemcpyBatch(...)：批量内存拷贝。template <typename T, typename U> aclError aclrtMemcpyBatchAsync(...)：异步批量内存拷贝。template <typename T> aclError aclrtPointerGetAttributes(const T *ptr, aclrtPtrAttributes *attributes)：类型安全的指针属性查询。template <typename T> aclError aclrtHostRegister(...)：类型安全的主机内存注册。template <typename T> aclError aclrtHostGetDevicePointer(T *pHost, T **pDevice, uint32_t flag)：主机内存到设备指针映射。template <typename T> aclError aclrtHostUnregister(T *ptr)：类型安全的主机内存注销。template <typename T> aclError aclrtMemAllocManaged(T **devPtr, size_t size, uint32_t flags = ACL_RT_MEM_ATTACH_GLOBAL)：类型安全的统一内存分配。template <typename T> aclError aclrtMemManagedPrefetchAsync(const T *ptr, size_t size, aclrtMemManagedLocation location, uint32_t flags, aclrtStream stream)：预取统一内存。template <typename T> aclError aclrtMemManagedPrefetchBatchAsync(...)：批量预取统一内存。template <typename T> aclError aclrtGetSymbolAddress(...)：获取Device变量的地址。template <typename T> aclError aclrtGetSymbolSize(...)：获取Device变量占用的内存大小。template <typename T> aclError aclrtMemcpyFromSymbol(...)：实现Device变量的数据到Host的同步内存复制。template <typename T> aclError aclrtMemcpyFromSymbolAsync(...)：实现Device变量的数据到Host的异步内存复制。template <typename T> aclError aclrtMemcpyToSymbol(...)：实现Host数据到Device变量的同步内存复制。template <typename T> aclError aclrtMemcpyToSymbolAsync(...)：实现Host数据到Device变量的异步内存复制。
aclrtSynchronizeDevice
aclError aclrtSynchronizeDevice(int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
阻塞当前线程，直到与当前线程绑定的Context所对应的Device完成运算。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtSynchronizeDeviceWithTimeout。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| timeout | 输入 | 接口的超时时间。 取值说明如下： - -1：表示永久等待； - >0：配置具体的超时时间，单位是毫秒。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtSynchronizeStream
aclError aclrtSynchronizeStream(aclrtStream stream, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
阻塞Host侧当前线程直到指定Stream中的所有任务都完成。同时，本接口支持用户设置超时时间，当应用程序异常时可根据所设置的超时时间自行退出。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtSynchronizeStreamWithTimeout。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stream | 输入 | 指定需要完成所有任务的Stream。类型定义请参见aclrtStream。 |
| timeout | 输入 | 接口的超时时间。 取值说明如下： - -1：表示永久等待； - >0：配置具体的超时时间，单位是毫秒。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtSynchronizeEvent
aclError aclrtSynchronizeEvent(aclrtEvent event, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
阻塞当前线程运行直到Event捕获的所有任务都执行完成。同时，本接口支持用户设置永久等待、或配置具体的超时时间，若配置具体的超时时间，则当应用程序异常时可根据所设置的超时时间自行退出。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtSynchronizeEventWithTimeout。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| event | 输入 | 需等待的Event。类型定义请参见aclrtEvent。 |
| timeout | 输入 | 接口的超时时间。 取值说明如下： - -1：表示永久等待。 - >0：配置具体的超时时间，单位是毫秒。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtStreamWaitEvent
aclError aclrtStreamWaitEvent(aclrtStream stream, aclrtEvent event, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
阻塞指定Stream的运行，直到指定的Event完成。异步接口。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtStreamWaitEventWithTimeout。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stream | 输入 | 指定Stream。类型定义请参见aclrtStream。 多Stream同步等待场景下，例如，Stream2等待Stream1的场景，此处配置为Stream2。 |
| event | 输入 | 需等待的Event。类型定义请参见aclrtEvent。 |
| timeout | 输入 | 超时时间。 取值说明如下： - 0：表示永不超时。 - >0：用于配置具体的超时时间，单位是毫秒。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtCreateStream
aclError aclrtCreateStream(aclrtStream *stream, uint32_t priority, uint32_t flag)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
在当前进程或线程中创建Stream。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtCreateStreamWithConfig。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stream | 输出 | Stream的指针。类型定义请参见aclrtStream。 |
| priority | 输入 | 优先级。 该参数取值范围：[0, 7]，总共最多支持8个优先级，数字越小代表优先级越高，其中，0的优先级最高，7的优先级最低。如果设置的优先级超过取值范围，则就近修正为边界值。 |
| flag | 输入 | Stream指针的flag。 flag参数值请参见C接口aclrtCreateStreamWithConfig中的“flag取值说明”。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtSetOpExecuteTimeOut
aclError aclrtSetOpExecuteTimeOut(uint64_t timeout, uint64_t *actualTimeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
设置算子执行的超时时间，单位为微秒。如果算子下发时携带了超时时间，则该超时时间优先级高于本接口设置的超时时间。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtSetOpExecuteTimeOutV2。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| timeout | 输入 | 设置超时时间，单位为微秒。 将该参数设置为0时，表示使用最大超时时间。 |
| actualTimeout | 输出 | 返回实际生效的超时时间，单位为微秒。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtCreateEvent
aclError aclrtCreateEvent(aclrtEvent *event, uint32_t flag)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
创建带flag的Event，不同flag的Event用于不同的功能。支持创建Event时携带多个flag（按位进行或操作），从而同时启用对应flag的功能。创建Event时，Event资源不受硬件限制。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtCreateEventExWithFlag。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| event | 输出 | Event的指针。类型定义请参见aclrtEvent。 |
| flag | 输入 | Event指针的flag。 flag为bitmap，支持将flag设置为单个宏、或者对多个宏进行或操作。 当前支持将flag设置为如下宏： - ACL_EVENT_TIME_LINE：使用该bit表示创建的Event需要记录时间戳信息。注意：使用时间戳功能会影响Event相关接口的性能。 - ACL_EVENT_SYNC：使用该bit表示创建的Event支持多Stream间的同步。 - ACL_EVENT_CAPTURE_STREAM_PROGRESS：使用该bit表示创建的Event用于跟踪stream的任务执行进度。 - ACL_EVENT_IPC：使用该bit表示创建的Event用于进程间通信，详细说明请参见aclrtIpcGetEventHandle。注意：Ascend 950DT上不支持使用本flag创建Event；本flag不支持与其他flag进行位或操作；本flag创建出来的Event不支持在以下接口或场景中使用：aclrtResetEvent、aclrtQueryEvent、aclrtQueryEventWaitStatus、aclrtEventElapsedTime、aclrtEventGetTimestamp、aclrtGetEventId、模型捕获场景（参见aclmdlRICaptureBegin中的说明），否则返回报错。 宏的定义如下： #define ACL_EVENT_TIME_LINE 0x00000008U #define ACL_EVENT_SYNC 0x00000001U #define ACL_EVENT_CAPTURE_STREAM_PROGRESS 0x00000002U #define ACL_EVENT_IPC 0x00000040U |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtCreateEventExWithFlag保持一致。
aclrtMemcpyBatch
template <typename T, typename U>
aclError aclrtMemcpyBatch(T **dsts, size_t *destMaxs, U **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr attr)
template <typename T, typename U>
aclError aclrtMemcpyBatch(T **dsts, size_t *destMaxs, U **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接口申请的内存）。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyBatchV2。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dsts | 输入 | 目的内存地址数组。 |
| destMaxs | 输入 | 内存复制最大长度数组，用于存放每一段要复制的内存的最大长度，单位Byte。 |
| srcs | 输入 | 源内存地址数组。 |
| sizes | 输入 | 内存复制长度数组，用于存放每一段要复制的内存大小，单位Byte。 |
| numBatches | 输入 | dsts、srcs和sizes数组的长度。 |
| attr | 输入 | 内存复制属性。针对所有内存，使用同一个内存复制属性。 类型定义请参见aclrtMemcpyBatchAttr。 |
| 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。
约束说明
约束与C接口aclrtMemcpyBatchV2保持一致。
aclrtMemcpyBatchAsync
template <typename T, typename U>
aclError aclrtMemcpyBatchAsync(T **dsts, size_t *destMaxs, U **srcs, size_t *sizes, size_t numBatches, aclrtMemcpyBatchAttr attr, aclrtStream stream)
template <typename T, typename U>
aclError aclrtMemcpyBatchAsync(T **dsts, size_t *destMaxs, U **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）确保内存复制的任务已执行完成。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyBatchAsyncV2。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dsts | 输入 | 目的内存地址数组。 |
| destMaxs | 输入 | 内存复制最大长度数组，用于存放每一段要复制的内存的最大长度，单位Byte。 |
| srcs | 输入 | 源内存地址数组。 |
| sizes | 输入 | 内存复制长度数组，用于存放每一段要复制的内存大小，单位Byte。 |
| numBatches | 输入 | dsts、srcs和sizes数组的长度。 |
| attr | 输入 | 内存复制属性。针对所有内存，使用同一个内存复制属性。 类型定义请参见aclrtMemcpyBatchAttr。 |
| 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。
约束说明
约束与C接口aclrtMemcpyBatchAsyncV2接口保持一致。
aclrtPointerGetAttributes
template <typename T>
aclError aclrtPointerGetAttributes(const T *ptr, aclrtPtrAttributes *attributes)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取内存属性信息，包括内存是位于Host还是Device、页表大小等信息。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtPointerGetAttributes。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptr | 输入 | 内存地址。 此处不允许传入通过aclrtHostRegister接口映射的Device地址，也不允许传入通过aclrtHostGetDevicePointer接口获取的Device地址，否则会导致未定义行为。 |
| attributes | 输出 | 内存属性信息。类型定义请参见aclrtPtrAttributes。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtHostRegister
template <typename T>
aclError aclrtHostRegister(T *ptr, uint64_t size, aclrtHostRegisterType type, T **devPtr)
template <typename T>
aclError aclrtHostRegister(T *ptr, uint64_t size, uint32_t flag)
产品支持情况
- Ascend 950PR：支持
- Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
注册Host内存地址。取消注册需调用aclrtHostUnregister接口。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtHostRegister或aclrtHostRegisterV2。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptr | 输入 | Host内存地址。 Host内存地址需4K页对齐。 当os内核版本为5.10或更低时，使用非锁页内存会导致异常，因此必须调用aclrtMallocHost接口来申请Host锁页内存。 当os内核版本为5.10以上时，支持使用非锁页的Host内存，因此既支持调用aclrtMallocHost接口申请Host锁页内存，也支持使用malloc接口申请Host非锁页内存。 |
| size | 输入 | 内存大小，单位Byte。 |
| type | 输入 | 内存注册类型。类型定义请参见aclrtHostRegisterType。 |
| devPtr | 输出 | Host内存映射成的Device可访问的内存地址。 该地址仅支持在Device上访问，例如作为核函数的参数，供Device的AI Core访问。若涉及Host侧的内存处理，需使用原始Host内存地址。 |
| flag | 输入 | 内存注册类型。 取值为如下宏，支持配置单个宏，也支持配置多个宏位或（例如ACL_HOST_REG_MAPPED | ACL_HOST_REG_PINNED）。 - ACL_HOST_REG_MAPPED：将Host内存映射注册为Device可访问的内存地址，再配合调用aclrtHostGetDevicePointer接口获取映射后的Device内存地址。 - ACL_HOST_REG_IOMEMORY：将Host上第三方PCIe设备的IO space(寄存器、缓存)映射注册为Device可访问，包括读写。 - ACL_HOST_REG_READONLY：Host内存映射注册为Device只读。预留选项，当前不支持。 - ACL_HOST_REG_PINNED：将Host非锁页内存注册为锁页内存。Host非锁页内存可通过C/C++标准库函数（如malloc、calloc、new）或默认的mmap系统调用等方式申请。 宏定义如下： #define ACL_HOST_REG_MAPPED 0x2UL #define ACL_HOST_REG_IOMEMORY 0x4UL #define ACL_HOST_REG_READONLY 0x8UL #define ACL_HOST_REG_PINNED 0X10000000UL |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtHostGetDevicePointer
template <typename T>
aclError aclrtHostGetDevicePointer(T *pHost, T **pDevice, uint32_t flag)
产品支持情况
- Ascend 950PR：支持
- Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
获取由aclrtHostRegister接口注册映射的Device内存地址。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtHostGetDevicePointer。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| pHost | 输入 | 通过aclrtHostRegister接口注册映射的Host内存地址。 |
| pDevice | 输出 | Host内存映射成的Device内存地址。 |
| flag | 输入 | 预留参数，当前固定配置为0。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtHostUnregister
template <typename T>
aclError aclrtHostUnregister(T *ptr)
产品支持情况
- Ascend 950PR：支持
- Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
取消注册Host内存。
本接口与aclrtHostRegister接口成对使用。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtHostUnregister。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptr | 输入 | Host侧内存地址。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemAllocManaged
template <typename T>
aclError aclrtMemAllocManaged(T **devPtr, size_t size, uint32_t flags = ACL_RT_MEM_ATTACH_GLOBAL)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
申请统一虚拟内存（Unified Virtual Memory, UVM），通过*ptr返回已申请内存的指针，且申请的内存大小会根据用户指定的size向上按2M对齐。使用本接口申请的内存，若需释放内存，需调用aclrtFree接口。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemAllocManaged。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| devPtr | 输出 | “已分配内存的指针”的指针，由于Host和Device虚拟地址统一编址，该参数不区分申请位置。 |
| size | 输入 | 内存大小，单位Byte。 size不能为0，单个应用进程最大可申请3TB UVM类型的虚拟内存。 |
| flag | 输入 | 内存标识。 当前flag仅支持设置为ACL_RT_MEM_ATTACH_GLOBAL，所对应数值为1。设置为ACL_RT_MEM_ATTACH_GLOBAL后，通过本接口申请的内存在Device和Host侧都可以被访问。 宏定义如下： #define ACL_RT_MEM_ATTACH_GLOBAL (0x01U) |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtMemAllocManaged接口保持一致。
aclrtMemManagedPrefetchAsync
template <typename T>
aclError aclrtMemManagedPrefetchAsync(const T *ptr, size_t size, aclrtMemManagedLocation location, uint32_t flags, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现统一虚拟内存（Unified Virtual Memory, UVM）的预取。
本接口操作的内存必须是通过aclrtMemAllocManaged接口分配的。本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存预取的任务已执行完成。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemManagedPrefetchAsync。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptr | 输入 | 待预取的内存地址，地址范围必须在UVM内存范围之内，即[0x90000000000ULL, 0x90000000000ULL+3TB)。 |
| size | 输入 | 待预取的内存长度，单位Byte，要求2MB对齐。取值范围为(0, 3TB]。 |
| location | 输入 | 物理内存的位置信息，location参数包含id和type两个成员。类型定义请参见aclrtMemManagedLocation。 |
| flags | 输入 | 预留参数。当前固定配置为0。 |
| stream | 输入 | 指定执行内存预取任务的stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemManagedPrefetchBatchAsync
template <typename T>
aclError aclrtMemManagedPrefetchBatchAsync(const T **ptrs, size_t *sizes, size_t count, aclrtMemManagedLocation prefetchLoc, uint64_t flags, aclrtStream stream)
template <typename T>
aclError aclrtMemManagedPrefetchBatchAsync(const T **ptrs, size_t *sizes, size_t count, aclrtMemManagedLocation *prefetchLocs, size_t *prefetchLocIdxs, size_t numPrefetchLocs, uint64_t flags, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现统一虚拟内存（Unified Virtual Memory, UVM）的批量预取。
本接口操作的内存必须是通过aclrtMemAllocManaged接口分配的。本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存预取的任务已执行完成。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemManagedPrefetchBatchAsync。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| ptrs | 输入 | 待预取的内存地址数组，每个地址的范围都必须在UVM内存范围之内，即[0x90000000000ULL, 0x90000000000ULL+3TB)。 |
| sizes | 输入 | 内存预取长度数组，用于存放每一段要预取的UVM内存长度，单位Byte。每段长度都要求2MB对齐，取值范围为(0, 3TB]。 |
| count | 输入 | ptrs和sizes数组的长度。 |
| prefetchLoc | 输入 | 物理内存的位置信息，每个位置信息都包含id和type两个成员。针对所有待预取的内存，使用同一个物理内存的位置信息 类型定义请参见aclrtMemManagedLocation。 |
| prefetchLocs | 输入 | 物理内存的位置信息数组，每个位置信息都包含id和type两个成员。针对每一段待预取的内存，使用相应的物理内存的位置信息 类型定义请参见aclrtMemManagedLocation。 |
| prefetchLocIdxs | 输入 | 物理内存预取信息索引数组，用于指定prefetchLocs数组中的每个物理地址适用的预取范围。对于prefetchLocs[k]指定的物理地址，将预取ptrs数组中从第prefetchLocIdxs[k]个下标到第prefetchLocIdxs[k+1] – 1个下标指向元素的UVM内存地址，同时对于prefetchLocs[numPrefetchLocs -1]指定的物理地址，将预取ptrs数组中从第prefetchLocIdxs[numPrefetchLocs -1]个下标到第count - 1个下标指向元素的UVM内存地址。 |
| numPrefetchLocs | 输入 | prefetchLocs和prefetchLocIdxs数组的长度。 |
| flags | 输入 | 预留参数。当前固定配置为0。 |
| stream | 输入 | 指定执行内存预取任务的stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtMemManagedPrefetchBatchAsync接口保持一致。
aclrtMalloc
template <typename T>
aclError aclrtMalloc(T **devPtr, size_t size, aclrtMallocConfig *cfg = nullptr)
template <typename T>
aclError aclrtMalloc(T **devPtr, size_t size, aclrtMemMallocPolicy policy, aclrtMallocConfig *cfg = nullptr)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：支持
功能说明
在Device上分配size大小的线性内存，并通过*devPtr返回已分配内存的指针，且内存首地址64字节对齐。
使用本接口申请的内存，需要通过aclrtFree接口或aclrtFreeWithDevSync接口释放内存。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMallocWithCfg。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| devPtr | 输出 | “Device上已分配内存的指针”的指针。 |
| size | 输入 | 申请内存的大小，单位Byte。 size不能为0。 |
| policy | 输入 | 内存分配规则。类型定义请参见aclrtMemMallocPolicy。 若配置的内存分配规则超出aclrtMemMallocPolicy取值范围，size≥2M时，按大页申请内存，否则按普通页申请内存。 |
| cfg | 输入 | 内存配置信息。类型定义请参见aclrtMallocConfig。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMallocHost
template <typename T>
aclError aclrtMallocHost(T **hostPtr, size_t size, aclrtMallocConfig *cfg = nullptr)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
申请Host内存（该内存是锁页内存），由系统保证内存首地址64字节对齐。
通过本接口申请的内存，需要通过aclrtFreeHost接口或aclrtFreeHostWithDevSync接口释放内存。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMallocHostWithCfg。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| hostPtr | 输出 | “已分配内存的指针”的指针。 |
| size | 输入 | 申请内存的大小，单位Byte。 size不能为0。 |
| cfg | 输入 | 内存配置信息。类型定义请参见aclrtMallocConfig。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemcpy
template <typename T, typename U>
aclError aclrtMemcpy(T *dst, size_t destMax, const U *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：支持
功能说明
实现内存复制。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpy。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| destMax | 输入 | 目的内存地址的最大内存长度，单位Byte。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| kind | 输入 | 内存复制的类型，预留参数，配置枚举值中的值无效，系统内部会根据源内存地址指针、目的内存地址指针判断是否可以将源地址的数据复制到目的地址，如果不可以，则系统会返回报错。 类型定义请参见aclrtMemcpyKind。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtMemcpy保持一致
aclrtMemcpyAsync
template <typename T, typename U>
aclError aclrtMemcpyAsync(T *dst, size_t destMax, const U *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内存是非锁页内存时，本接口在内存复制任务完成后才返回。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyAsync。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| destMax | 输入 | 目的内存地址的最大内存长度，单位Byte。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtMemcpyAsync保持一致。
aclrtMemcpy2d
template <typename T, typename U>
aclError aclrtMemcpy2d(T *dst, size_t dpitch, const U *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：不支持
功能说明
实现同步内存复制，主要用于矩阵数据的复制。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpy2d。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| dpitch | 输入 | 目的内存中相邻两列向量的地址距离。 |
| src | 输入 | 源内存地址指针。 |
| spitch | 输入 | 源内存中相邻两列向量的地址距离。 |
| width | 输入 | 待复制的数据宽度。 |
| height | 输入 | 待复制的数据高度。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtMemcpy2d保持一致。
aclrtMemcpy2dAsync
template <typename T, typename U>
aclError aclrtMemcpy2dAsync(T *dst, size_t dpitch, const U *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）确保内存复制的任务已执行完成。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpy2dAsync。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| dpitch | 输入 | 目的内存中相邻两列向量的地址距离。 |
| src | 输入 | 源内存地址指针。 |
| spitch | 输入 | 源内存中相邻两列向量的地址距离。 |
| width | 输入 | 待复制的数据宽度。 width最大设置为5000000，且必须小于或等于dpitch和spitch。 |
| height | 输入 | 待复制的数据高度。 height最大设置为510241024=5242880，否则接口返回失败。 |
| kind | 输入 | 内存复制的类型。类型定义请参见aclrtMemcpyKind。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
约束与C接口aclrtMemcpy2dAsync保持一致。
aclrtGetSymbolAddress
template <typename T>
aclError aclrtGetSymbolAddress(const T &symbol, void **devPtr)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
获取Device变量的地址。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtGetSymbolAddress。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| symbol | 输入 | Device变量名。此处传入__gm__声明的变量名。 |
| devPtr | 输出 | Device变量的内存地址指针。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 本接口仅适用于 C++ 程序。
- 本接口仅适用于Ascend C语言开发自定义算子并基于毕昇编译器进行Host和Device代码混合编译的场景。
- Device变量地址仅在当前Device有效，切换Device后需重新获取地址。
- 仅支持AI Core算子中的Device变量，具体约束如下：
- 支持在main函数所在文件中定义的Device变量（如
__gm__ float convWeights）。 - 支持通过extern关键字跨文件引用Device变量。例如，在文件A中定义
__gm__ float convWeights，文件B中可通过extern __gm__ float convWeights声明并引用该变量。需要满足编译要求：使用毕昇编译器的-dc模式，将多个源文件编译为单个算子二进制文件。 - 支持基础数据类型、函数指针、结构体及数组，不支持class类型。注意：函数指针只支持指向纯Scalar的函数，不能有效区分Cube和Vector的函数逻辑。
- 支持在main函数所在文件中定义的Device变量（如
aclrtGetSymbolSize
template <typename T>
aclError aclrtGetSymbolSize(const T &symbol, size_t *size)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
获取Device变量占用的内存大小。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtGetSymbolSize。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| symbol | 输入 | Device变量名。此处传入__gm__声明的变量名。 |
| size | 输出 | Device变量的大小，单位Byte。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
同aclrtGetSymbolAddress接口约束说明。
aclrtMemcpyFromSymbol
template <typename T>
aclError aclrtMemcpyFromSymbol(void *dst, size_t dstMax, const T &symbol, size_t count,
size_t offset, aclrtMemcpyKind kind)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现Device变量的数据到Host的同步内存复制。用于读取Device变量的数据。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyFromSymbol。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| dstMax | 输入 | 目标内存最大长度，单位Byte。需满足 dstMax ≥ count。 |
| symbol | 输入 | Device变量名。此处传入__gm__声明的变量名。 |
| count | 输入 | 内存复制的长度，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| offset | 输入 | Device变量地址偏移，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| kind | 输入 | 拷贝类型，类型定义请参见aclrtMemcpyKind。本接口仅支持ACL_MEMCPY_DEVICE_TO_HOST和ACL_MEMCPY_DEFAULT。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
同aclrtGetSymbolAddress接口约束说明。
aclrtMemcpyFromSymbolAsync
template <typename T>
aclError aclrtMemcpyFromSymbolAsync(void *dst, size_t dstMax, const T &symbol, size_t count,
size_t offset, aclrtMemcpyKind kind, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现Device变量的数据到Host的异步内存复制。用于读取Device变量的数据。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成；当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyFromSymbolAsync。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| dst | 输入 | 目的内存地址指针。 |
| dstMax | 输入 | 目标内存最大长度，单位Byte。需满足 dstMax ≥ count。 |
| symbol | 输入 | Device变量名。此处传入__gm__声明的变量名。 |
| count | 输入 | 内存复制的长度，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| offset | 输入 | Device变量地址偏移，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| kind | 输入 | 拷贝类型，类型定义请参见aclrtMemcpyKind。本接口仅支持ACL_MEMCPY_DEVICE_TO_HOST和ACL_MEMCPY_DEFAULT。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 同aclrtGetSymbolAddress接口约束说明。
- 本接口为异步接口，调用后需同步等待拷贝完成。
aclrtMemcpyToSymbol
template <typename T>
aclError aclrtMemcpyToSymbol(const T &symbol, const void *src, size_t count, size_t offset, aclrtMemcpyKind kind)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现Host数据到Device变量的同步内存复制。用于向Device变量写入数据。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyToSymbol。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| symbol | 输入 | Device变量名。此处传入__gm__声明的变量名。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| offset | 输入 | Device变量地址偏移，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| kind | 输入 | 拷贝类型，类型定义请参见aclrtMemcpyKind。本接口仅支持ACL_MEMCPY_HOST_TO_DEVICE和ACL_MEMCPY_DEFAULT。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
同aclrtGetSymbolAddress接口约束说明。
aclrtMemcpyToSymbolAsync
template <typename T>
aclError aclrtMemcpyToSymbolAsync(const T &symbol, const void *src, size_t count, size_t offset,
aclrtMemcpyKind kind, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
实现Host数据到Device变量的异步内存复制。用于向Device变量写入数据。
本接口中的Host内存支持锁页内存（例如通过aclrtMallocHost接口申请的内存）、非锁页内存（通过malloc接口申请的内存）。当Host内存是锁页内存时，本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，调用本接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保内存复制的任务已执行完成；当Host内存是非锁页内存时，本接口在内存复制任务完成后才返回。
本接口为封装接口，仅适用于C++程序，接口内部调用C接口aclrtMemcpyToSymbolAsync。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| symbol | 输入 | Device变量名。此处传入__gm__声明的变量名。 |
| src | 输入 | 源内存地址指针。 |
| count | 输入 | 内存复制的长度，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| offset | 输入 | Device变量地址偏移，单位Byte。需满足 offset + count ≤ Device变量大小，Device变量大小可通过 aclrtGetSymbolSize接口查询获取。 |
| kind | 输入 | 拷贝类型，类型定义请参见aclrtMemcpyKind。本接口仅支持ACL_MEMCPY_HOST_TO_DEVICE和ACL_MEMCPY_DEFAULT。 |
| stream | 输入 | 指定执行内存复制任务的Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 同aclrtGetSymbolAddress接口约束说明。
- 本接口为异步接口，调用后需同步等待拷贝完成。