CANN/runtime 主机内存管理

11-02 主机内存管理

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本章节描述主机（Host）内存的分配、释放、注册及指针获取接口。

• aclError aclrtMallocHost(void **hostPtr, size_t size)：申请Host内存（该内存是锁页内存），由系统保证内存首地址64字节对齐。
• aclError aclrtMallocHostWithCfg(void **ptr, uint64_t size, aclrtMallocConfig *cfg)：申请Host内存（该内存是锁页内存），由系统保证内存首地址64字节对齐。
• aclError aclrtFreeHost(void *hostPtr)：释放通过aclrtMallocHost接口或aclrtMallocHostWithCfg接口申请的Host内存。
• aclError aclrtFreeHostWithDevSync(void *hostPtr)：释放通过aclrtMallocHost接口或aclrtMallocHostWithCfg接口申请的Host内存。
• aclError aclrtHostRegister(void *ptr, uint64_t size, aclrtHostRegisterType type, void **devPtr)：将Host内存映射注册为Device可访问的内存地址，并获取映射后的Device内存地址。映射后的Device内存地址不能用于内存操作，例如内存复制。
• aclError aclrtHostRegisterV2(void *ptr, uint64_t size, uint32_t flag)：注册Host内存地址。
• aclError aclrtHostGetDevicePointer(void *pHost, void **pDevice, uint32_t flag)：获取由aclrtHostRegister或aclrtHostRegisterV2接口注册映射的Device内存地址。映射后的Device内存地址不能用于内存操作，例如内存复制。
• aclError aclrtHostMemMapCapabilities(uint32_t deviceId, aclrtHacType hacType, aclrtHostMemMapCapability *capabilities)：查询指定的硬件驱动加速器是否支持访问通过aclrtHostRegister接口注册的内存。
• aclError aclrtHostUnregister(void *ptr)：取消注册Host内存。

aclrtMallocHost

aclError aclrtMallocHost(void **hostPtr, size_t size)

产品支持情况

功能说明

申请Host内存（该内存是锁页内存），由系统保证内存首地址64字节对齐。

通过本接口申请的内存，需要通过aclrtFreeHost接口或aclrtFreeHostWithDevSync接口释放内存。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

• 本接口分配的内存不会进行对内容进行初始化，建议在使用内存前先调用aclrtMemset接口先初始化内存，清除内存中的随机数。
• 本接口内部不会进行隐式的device同步或流同步。如果申请内存成功或申请内存失败会立刻返回结果。
• 使用aclrtMallocHost接口分配过多的锁页内存，将导致操作系统用于分页的物理内存变少，从而降低系统整体的性能。
• 频繁调用aclrtMallocHost接口申请内存、调用aclrtFreeHost接口释放内存，会损耗性能，建议用户提前做内存预先分配或二次管理，避免频繁申请/释放内存。

aclrtMallocHostWithCfg

aclError aclrtMallocHostWithCfg(void **ptr, uint64_t size, aclrtMallocConfig *cfg)

产品支持情况

功能说明

申请Host内存（该内存是锁页内存），由系统保证内存首地址64字节对齐。

与aclrtMallocHost接口相比，本接口在申请内存时，还可以指定内存相关的配置信息。

通过本接口申请的内存，需要通过aclrtFreeHost接口或aclrtFreeHostWithDevSync接口释放内存。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtFreeHost

aclError aclrtFreeHost(void *hostPtr)

产品支持情况

功能说明

释放通过aclrtMallocHost接口或aclrtMallocHostWithCfg接口申请的Host内存。

本接口会立刻释放传入的内存，接口内部不会进行隐式的Device同步或流同步、也不会等待使用该内存的任务完成。用户需确保在调用本接口后不再访问该内存指针。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtFreeHostWithDevSync

aclError aclrtFreeHostWithDevSync(void *hostPtr)

产品支持情况

功能说明

释放通过aclrtMallocHost接口或aclrtMallocHostWithCfg接口申请的Host内存。

本接口内部会进行隐式的Device同步，并等待使用该内存的任务完成。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtHostRegister

aclError aclrtHostRegister(void *ptr, uint64_t size, aclrtHostRegisterType type, void **devPtr)

产品支持情况

功能说明

将Host内存映射注册为Device可访问的内存地址，并获取映射后的Device内存地址。映射后的Device内存地址不能用于内存操作，例如内存复制。

如果注册的ptr是通过aclrtMallocHostWithCfg申请的，并且申请时配置的attr类型是ACL_RT_MEM_ATTR_VA_FLAG，vaFlag的值为1，则映射后的Device地址与Host地址一致，可以进行内存操作。

取消注册Host内存需调用aclrtHostUnregister接口。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtHostRegisterV2

aclError aclrtHostRegisterV2(void *ptr, uint64_t size, uint32_t flag)

产品支持情况

功能说明

注册Host内存地址。

取消注册需调用aclrtHostUnregister接口。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtHostGetDevicePointer

aclError aclrtHostGetDevicePointer(void *pHost, void **pDevice, uint32_t flag)

产品支持情况

功能说明

获取由aclrtHostRegister或aclrtHostRegisterV2接口注册映射的Device内存地址。映射后的Device内存地址不能用于内存操作，例如内存复制。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtHostMemMapCapabilities

aclError aclrtHostMemMapCapabilities(uint32_t deviceId, aclrtHacType hacType, aclrtHostMemMapCapability *capabilities)

产品支持情况

功能说明

查询指定的硬件驱动加速器是否支持访问通过aclrtHostRegister接口注册的内存。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtHostUnregister

aclError aclrtHostUnregister(void *ptr)

产品支持情况

功能说明

取消注册Host内存。

本接口与aclrtHostRegister接口成对使用。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime