Star612
759
代码
代码
Issues35
Pull Requests183
Actions
项目讨论
Wiki
分析
Star612
759
cann-robotcann-robot【fix】: add ipc mem doc
92a70280创建于 10 天前历史提交

11-04 虚拟内存管理

本章节描述虚拟内存管理接口，包括物理内存分配、虚拟地址预留、内存映射及跨进程共享。

aclrtMallocPhysical

aclError aclrtMallocPhysical(aclrtDrvMemHandle *handle, size_t size, const aclrtPhysicalMemProp *prop, uint64_t flags)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

申请Host或Device物理内存，并返回一个物理内存handle。

本接口可配合aclrtReserveMemAddress接口（申请虚拟内存）、aclrtMapMem接口（建立虚拟内存与物理内存之间的映射）使用，以便申请地址连续的虚拟内存、最大化利用物理内存。

本接口可配合aclrtMemExportToShareableHandle接口（导出物理内存handle）、aclrtMemImportFromShareableHandle（导入共享handle）使用，用于实现多进程之间的物理内存共享。同时，也支持在共享物理内存时，使用虚拟内存，请参见aclrtMemExportToShareableHandle接口处的说明。

参数说明

参数名 输入/输出 说明
handle 输出 存放物理内存信息的handle。类型定义请参见aclrtDrvMemHandle。
size 输入 物理内存大小，单位Byte。
先调用aclrtMemGetAllocationGranularity接口获取内存申请粒度，然后再调用本接口申请物理内存时size按获取到的内存申请粒度对齐，以便节约内存。
prop 输入 物理内存属性信息。类型定义请参见aclrtPhysicalMemProp。
flags 输入 预留，当前只能设置为0。

返回值说明

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

约束说明

  • 对于Atlas 200I/500 A2 推理产品，Ascend RC形态不支持调用本接口。
  • 针对Atlas A3 训练系列产品/Atlas A3 推理系列产品中的超节点产品，当内存所在位置aclrtPhysicalMemProp.location.type = ACL_MEM_LOCATION_TYPE_HOST_NUMA，且内存属性类型aclrtPhysicalMemProp.aclrtMemAttr为P2P选项（例如ACL_MEM_P2P_HUGE）时，可申请到的最大内存大小根据服务器型号、Bios版本会有所不同。建议通过aclrtMallocPhysical接口按内存规划尝试申请，以确认内存是否足够。
  • 内存属性类型aclrtPhysicalMemProp.aclrtMemAttr当前仅支持如下选项：

    • ACL_MEM_NORMAL：普通内存。

    • ACL_MEM_HUGE：2MB粒度对齐的大页内存。

    • ACL_MEM_HUGE1G：1GB粒度对齐的大页内存，仅支持Device。

      仅Atlas A3 训练系列产品/Atlas A3 推理系列产品、Atlas A2 训练系列产品/Atlas A2 推理系列产品支持该类型。

      Ascend 950PR/Ascend 950DT不支持该类型。

      Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持该类型。

    • ACL_MEM_P2P_NORMAL：用于Device间数据复制的普通内存。

    • ACL_MEM_P2P_HUGE：用于Device间数据复制的大页内存，内存申请粒度为2MB。

    • ACL_MEM_P2P_HUGE1G：用于Device间数据复制的大页内存，内存申请粒度为1GB，仅支持Device。

      仅Atlas A3 训练系列产品/Atlas A3 推理系列产品中的部分互联形态支持该类型，以接口实际返回情况为准。

      Ascend 950PR/Ascend 950DT、Atlas A2 训练系列产品/Atlas A2 推理系列产品不支持该类型。

      Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持该类型。

    • ACL_HBM_MEM_HUGE：2MB粒度对齐的大页内存。

    • ACL_HBM_MEM_HUGE1G：1GB粒度对齐的大页内存，仅支持Device。

      Ascend 950PR/Ascend 950DT、Atlas A3 训练系列产品/Atlas A3 推理系列产品、Atlas A2 训练系列产品/Atlas A2 推理系列产品支持该类型。

      Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持该类型。

    • ACL_HBM_MEM_NORMAL：普通内存，接口内部会按照ACL_HBM_MEM_HUGE类型申请大页内存。

    • ACL_DDR_MEM_HUGE：大页内存，仅支持Host内存。

    • ACL_DDR_MEM_NORMAL：普通内存，仅支持Host内存。

    • ACL_DDR_MEM_P2P_HUGE：用于Device间数据复制的大页内存，仅支持Host内存。

    • ACL_DDR_MEM_P2P_NORMAL：用于Device间数据复制的普通内存，仅支持Host内存。




aclrtFreePhysical

aclError aclrtFreePhysical(aclrtDrvMemHandle handle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

释放通过aclrtMallocPhysical接口申请的物理内存。

如果物理内存与虚拟内存之间存在映射关系，则此处不会实际释放物理内存。只有在调用aclrtUnmapMem接口取消该物理内存与虚拟内存的映射之后，物理内存才会被真正释放。

参数说明

参数名 输入/输出 说明
handle 输入 待释放的物理内存信息handle。类型定义请参见aclrtDrvMemHandle。

返回值说明

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

约束说明

Atlas 200I/500 A2 推理产品上，Ascend RC形态不支持调用本接口。




aclrtReserveMemAddress

aclError aclrtReserveMemAddress(void **virPtr, size_t size, size_t alignment, void *expectPtr, uint64_t flags)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

预留虚拟内存。

本接口需与以下其它接口配合使用，以便申请地址连续的虚拟内存、最大化利用物理内存：

  1. 申请虚拟内存（aclrtReserveMemAddress接口）；
  2. 申请物理内存（aclrtMallocPhysical接口）；
  3. 将虚拟内存映射到物理内存（aclrtMapMem接口）；
  4. 执行任务（调用具体的任务接口）；
  5. 取消虚拟内存与物理内存的映射（aclrtUnmapMem接口）；
  6. 释放物理内存（aclrtFreePhysical接口）；
  7. 释放虚拟内存（aclrtReleaseMemAddress接口）。

参数说明

参数名 输入/输出 说明
virPtr 输出 “已分配的虚拟内存地址的指针”的指针。
size 输入 虚拟内存大小，单位Byte。
size不能为0。
alignment 输入 虚拟地址对齐值，预留，当前只能设置为0。
expectPtr 输入 指定期望返回的虚拟内存起始地址。
取值说明如下：
- nullptr：系统自动分配符合对齐规则的虚拟地址。
- 非nullptr：由用户指定起始地址，地址必须在8T范围内（16T-24T）。用户需确保指定的地址未被占用，且符合对齐规则，否则预留虚拟内存失败，接口返回错误。对齐规则为：若size小于1GB，expectPtr需按2的n次方对齐；如果size大于1GB，expectPtr需按1GB对齐。须知：由用户指定起始地址是试验特性，后续版本可能存在变更，不支持应用于生产环境中。
flags 输入 预留参数，建议固定配置为0。

返回值说明

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

约束说明

  • 对于Ascend 950PR/Ascend 950DT，expectPtr参数处仅支持配置为nullptr。
  • Atlas 200I/500 A2 推理产品上，Ascend RC形态下，不支持调用本接口。
  • 使用本接口预留的虚拟内存，单进程场景下只支持调用aclrtMemcpyAsync接口实现两个Device之间的数据拷贝。



aclrtReserveMemAddressNoUCMemory

aclError aclrtReserveMemAddressNoUCMemory(void **virPtr, size_t size, size_t alignment, void *expectPtr, uint64_t flags)

须知：由用户指定起始地址是试验特性，后续版本可能存在变更，不支持应用于生产环境中

产品支持情况

  • Ascend 950PR/Ascend 950DT：不支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：不支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

预留虚拟内存。

本接口与aclrtReserveMemAddress接口的使用方法相同，区别在于：根据环境变量AUTO_USE_UC_MEMORY决定是否允许数据搬移不经过L2 Cache的算子，本接口预留的虚拟内存不能用作此类算子的输入或输出内存，否则可能会导致算子精度问题或异常。AUTO_USE_UC_MEMORY环境变量的详细说明请参见《环境变量参考》。

另外，本接口中的虚拟内存起始地址不支持由系统自动分配，只能由用户指定，且地址建议在40T-224T范围内。

参数说明

参数名 输入/输出 说明
virPtr 输出 “已分配的虚拟内存地址的指针”的指针。
size 输入 虚拟内存大小，单位Byte。
size不能为0，只能为1GB的整数倍，最小为1GB。
alignment 输入 虚拟地址对齐值，预留，当前只能设置为0。
expectPtr 输入 指定期望返回的虚拟内存起始地址。
由用户指定起始地址，地址建议在40T-224T范围内。用户需确保指定的地址未被占用，否则预留虚拟内存失败，接口返回错误。
flags 输入 预留参数，建议固定配置为0。

返回值说明

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




aclrtReleaseMemAddress

aclError aclrtReleaseMemAddress(void *virPtr)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

释放通过aclrtReserveMemAddress接口申请的虚拟内存。

本接口需与以下其它接口配合使用，以便申请地址连续的虚拟内存、最大化利用物理内存：

  1. 申请虚拟内存（aclrtReserveMemAddress接口）；
  2. 申请物理内存（aclrtMallocPhysical接口）；
  3. 将虚拟内存映射到物理内存（aclrtMapMem接口）；
  4. 执行任务（调用具体的任务接口）；
  5. 取消虚拟内存与物理内存的映射（aclrtUnmapMem接口）；
  6. 释放物理内存（aclrtFreePhysical接口）；
  7. 释放虚拟内存（aclrtReleaseMemAddress接口）。

参数说明

参数名 输入/输出 说明
virPtr 输入 待释放的虚拟内存地址指针。

返回值说明

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

约束说明

  • 对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。
  • 若该虚拟内存与物理内存存在映射关系，则释放虚拟内存前，需调用aclrtUnmapMem接口取消该虚拟内存与物理内存的映射。



aclrtMapMem

aclError aclrtMapMem(void *virPtr, size_t size, size_t offset, aclrtDrvMemHandle handle, uint64_t flags)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

将虚拟内存映射到物理内存。

本接口需与以下其它接口配合使用，以便申请地址连续的虚拟内存、最大化利用物理内存：

  1. 申请虚拟内存（aclrtReserveMemAddress接口）；
  2. 申请物理内存（aclrtMallocPhysical接口）；
  3. 将虚拟内存映射到物理内存（aclrtMapMem接口）；
  4. 执行任务（调用具体的任务接口）；
  5. 取消虚拟内存与物理内存的映射（aclrtUnmapMem接口）；
  6. 释放物理内存（aclrtFreePhysical接口）；
  7. 释放虚拟内存（aclrtReleaseMemAddress接口）。

参数说明

参数名 输入/输出 说明
virPtr 输入 待映射的虚拟内存地址指针。
这个地址不一定是起始地址，用户也可以根据起始地址自行偏移后，再映射。
size 输入 待映射的内存大小，单位Byte。
此处的size必须与aclrtMallocPhysical接口的size参数值相同，size必须与aclrtMemGetAllocationGranularity接口获取的ACL_RT_MEM_ALLOC_GRANULARITY_MINIMUM对齐。
offset 输入 物理内存偏移值，当前只能设置为0。
handle 输入 物理内存信息handle。类型定义请参见aclrtDrvMemHandle。
通过aclrtReserveMemAddress接口预留出来的一整段虚拟地址，由用户自行管理、划分时，不能同时与两个Device上申请的物理地址绑定。
通过aclrtReserveMemAddress接口预留出来的一整段虚拟地址，由用户自行管理、划分时，不能同时与aclrtMallocPhysical、aclrtMemImportFromShareableHandle、aclrtMemImportFromShareableHandleV2接口输出的handle绑定。
flags 输入 预留，当前只能设置为0。

返回值说明

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

约束说明

对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。




aclrtMemMapNoAccess

aclError aclrtMemMapNoAccess(void *virPtr, size_t size, size_t offset, aclrtDrvMemHandle handle, uint64_t flags)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

将虚拟内存映射到物理内存。 本接口与aclrtMapMem接口的区别在于：调用本接口成功后，目标Device上尚未建立可访问页表，虚拟地址区间不可访问。因此，需先调用aclrtMemSetAccess接口设置内存访问权限，以触发在Device上建立可访问页表，方可访问该虚拟地址区间。

本接口需与以下其它接口配合使用，以便申请地址连续的虚拟内存、最大化利用物理内存：

  1. 申请虚拟内存（aclrtReserveMemAddress接口）；
  2. 申请物理内存（aclrtMallocPhysical接口）；
  3. 将虚拟内存映射到物理内存（aclrtMemMapNoAccess接口）；
  4. 为目标Device设置访问权限（aclrtMemSetAccess接口）；
  5. 执行任务（调用具体的任务接口）；
  6. 取消虚拟内存与物理内存的映射（aclrtUnmapMem接口）；
  7. 释放物理内存（aclrtFreePhysical接口）；
  8. 释放虚拟内存（aclrtReleaseMemAddress接口）。

参数说明

参数名 输入/输出 说明
virPtr 输入 待映射的虚拟内存地址指针。
这个地址不一定是起始地址，用户也可以根据起始地址自行偏移后，再映射。
size 输入 待映射的内存大小，单位Byte。
此处的size必须与aclrtMallocPhysical接口的size参数值相同，size必须与aclrtMemGetAllocationGranularity接口获取的ACL_RT_MEM_ALLOC_GRANULARITY_MINIMUM对齐。
offset 输入 物理内存偏移值，当前只能设置为0。
handle 输入 物理内存信息handle。类型定义请参见aclrtDrvMemHandle。
通过aclrtReserveMemAddress接口预留出来的一整段虚拟地址，由用户自行管理、划分时，不能同时与两个Device上申请的物理地址绑定。
通过aclrtReserveMemAddress接口预留出来的一整段虚拟地址，由用户自行管理、划分时，不能同时与aclrtMallocPhysical、aclrtMemImportFromShareableHandle、aclrtMemImportFromShareableHandleV2接口输出的handle绑定。
flags 输入 预留，当前只能设置为0。

返回值说明

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

约束说明

对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。

对于Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品、Ascend 950PR/Ascend 950DT，本接口不支持PCIe互连形态的设备。




aclrtUnmapMem

aclError aclrtUnmapMem(void *virPtr)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

取消通过aclrtMapMem或aclrtMemMapNoAccess接口建立的虚拟内存与物理内存之间的映射关系。

参数说明

参数名 输入/输出 说明
virPtr 输入 待取消映射的虚拟内存地址指针。

返回值说明

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

约束说明

对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。




aclrtMemExportToShareableHandle

aclError aclrtMemExportToShareableHandle(aclrtDrvMemHandle handle, aclrtMemHandleType handleType, uint64_t flags, uint64_t *shareableHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

将本进程通过aclrtMallocPhysical接口获取到的Device物理内存handle导出，以便后续将Device物理内存共享给其它进程。

本接口需与以下其它关键接口配合使用，以便实现内存共享，此处以A、B进程为例，说明两个进程间的物理内存共享接口调用流程：

  1. 在A进程中：

    1. 调用aclrtMallocPhysical接口，申请物理内存。

      先调用aclrtMemGetAllocationGranularity接口获取内存申请粒度，然后再调用aclrtMallocPhysical接口申请物理内存时size按获取到的内存申请粒度对齐，以便节约内存。

      若需申请地址连续的虚拟内存、最大化利用物理内存，此处可配合aclrtReserveMemAddress、aclrtMapMem、aclrtMemSetAccess等接口申请虚拟内存、建立虚拟内存与物理内存之间的映射、设置虚拟内存的访问权限。

    2. 调用aclrtMemExportToShareableHandle接口，导出物理内存handle，输出shareableHandle。

      调用aclrtMemExportToShareableHandle接口时，可指定是否启用进程白名单校验，若启用，则需单独调用aclrtMemSetPidToShareableHandle接口将B进程的进程ID设置为白名单；反之，则无需调用aclrtMemSetPidToShareableHandle接口。

    3. 调用aclrtFreePhysical接口，释放物理内存。

      内存使用完成后，要及时调用aclrtFreePhysical接口释放物理内存，实现销毁shareableHandle。若有进程还在使用shareableHandle，则等待shareableHandle使用完成后再执行销毁任务。

      所有涉及共享内存的进程都必须释放其物理内存，只有当所有相关进程都完成释放操作后，物理内存才能真正被释放。释放物理内存后，原先分配的内存将被归还给操作系统，此后使用该handle将导致未定义的行为。

  2. 在B进程中：

    1. 调用aclrtDeviceGetBareTgid接口，获取B进程的进程ID。

      本接口内部在获取进程ID时已适配物理机、虚拟机场景，用户只需调用本接口获取进程ID，再配合其它接口使用，达到物理内存共享的目的。若用户不调用本接口、自行获取进程ID，可能会导致后续使用进程ID异常。

    2. 调用aclrtMemImportFromShareableHandle，获取shareableHandle里的信息，并返回本进程中的handle。

      在调用aclrtMemImportFromShareableHandle接口前，需确保待共享的物理内存存在，不能提前释放。

      若需申请地址连续的虚拟内存、最大化利用物理内存地址，此处可配合aclrtReserveMemAddress、aclrtMapMem、aclrtMemSetAccess等接口申请虚拟内存、建立虚拟内存与物理内存之间的映射、设置虚拟内存的访问权限，请参见对应接口的说明。

    3. 调用aclrtFreePhysical接口，释放物理内存。

参数说明

参数名 输入/输出 说明
handle 输入 存放物理内存信息的handle。类型定义请参见aclrtDrvMemHandle。
需先在本进程调用aclrtMallocPhysical接口申请物理内存，该接口调用成功，会返回一个handle。
handle与shareableHandle是一一对应的关系，在同一个进程中，不允许一对多、或多对一，否则报错，例如重复调用本接口导出时则会返回报错。
handleType 输入 预留参数，当前固定填ACL_MEM_HANDLE_TYPE_NONE。
类型定义请参见aclrtMemHandleType。
flags 输入 是否启用进程白名单校验。
取值为如下宏：

- ACL_RT_VMM_EXPORT_FLAG_DEFAULT：默认值，启用进程白名单校验。配置为该值时，需单独调用aclrtMemSetPidToShareableHandle接口将使用shareableHandle的进程ID设置为白名单。
- ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION：关闭进程白名单校验。配置为该值时，则无需调用aclrtMemSetPidToShareableHandle接口。


宏的定义如下：
#define ACL_RT_VMM_EXPORT_FLAG_DEFAULT 0x0UL
#define ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION 0x1UL
shareableHandle 输出 标识共享给其它进程的shareableHandle。

返回值说明

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

约束说明

  • 对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。
  • 支持AI Server内跨进程共享物理内存。若跨Device，则还需配合aclrtDeviceEnablePeerAccess接口使用。AI Server通常是多个Device组成的服务器形态的统称。
  • 不支持昇腾虚拟化实例场景。
  • 不支持算力分组场景。



aclrtMemSetPidToShareableHandle

aclError aclrtMemSetPidToShareableHandle(uint64_t shareableHandle, int32_t *pid, size_t pidNum)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

设置共享内存的进程白名单**。**

在调用aclrtMemExportToShareableHandle接口的进程中，调用本接口设置进程白名单。本接口需与其它接口配合使用，以便实现内存共享的目的，请参见aclrtMemExportToShareableHandle接口处的说明。

参数说明

参数名 输入/输出 说明
shareableHandle 输入 通过aclrtMemExportToShareableHandle接口导出的shareableHandle。
pid 输入 用于存放白名单进程ID的数组。
进程ID可调用aclrtDeviceGetBareTgid接口获取，Docker场景下获取到的是物理机上的进程ID，非Docker场景下获取到的是进程ID。
pidNum 输入 白名单进程数量，与pid参数数组的大小保持一致。

返回值说明

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




aclrtMemImportFromShareableHandle

aclError aclrtMemImportFromShareableHandle(uint64_t shareableHandle, int32_t deviceId, aclrtDrvMemHandle *handle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

在本进程中获取shareableHandle里的信息，并返回本进程中的handle，用于在本进程中建立虚拟地址与物理地址之间的映射关系。本接口还支持生成指定Device上的handle。

本接口需与其它接口配合使用，以便实现内存共享的目的，配合使用流程请参见aclrtMemExportToShareableHandle接口处的说明。

参数说明

参数名 输入/输出 说明
shareableHandle 输入 待共享的shareableHandle，与aclrtMemExportToShareableHandle接口中导出的shareableHandle保持一致。
handle与shareableHandle是一一对应的关系，在同一个进程中，不允许一对多、或多对一。
deviceId 输入 用于生成指定Device ID上的handle。
用户调用aclrtGetDeviceCount接口获取可用的Device数量后，这个Device ID的取值范围：[0, (可用的Device数量-1)]
handle 输出 本进程的物理内存handle。类型定义请参见aclrtDrvMemHandle。

返回值说明

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

约束说明

  • 在调用本接口前，需确保待共享的物理内存存在，不能提前释放。
  • 不支持同一个进程中调用aclrtMemImportFromShareableHandle、aclrtMemExportToShareableHandle这两个接口，只支持跨进程调用。
  • 支持在一个Device上调用aclrtMemExportToShareableHandle接口导出handle，然后调用本接口生成另一个Device上的handle。
  • 内存使用完成后，要及时调用aclrtFreePhysical销毁handle，并且需所有调用本接口的进程都销毁shareableHandle的情况下，handle才会真正销毁。



aclrtMemExportToShareableHandleV2

aclError aclrtMemExportToShareableHandleV2(aclrtDrvMemHandle handle, uint64_t flags, aclrtMemSharedHandleType shareType, void *shareableHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

将本进程通过aclrtMallocPhysical接口获取到的Device物理内存handle导出，以便后续将Device物理内存共享给其它进程。

本接口是在接口aclrtMemExportToShareableHandle基础上进行了增强，用户可通过shareType参数指定导出AI Server内的共享句柄，或导出跨AI Server的共享句柄。AI Server通常是多个Device组成的服务器形态的统称。

本接口的使用流程可参见aclrtMemExportToShareableHandle，但本接口需配合调用aclrtMemSetPidToShareableHandleV2接口设置进程白名单、调用aclrtMemImportFromShareableHandleV2接口导入共享句柄。

参数说明

参数名 输入/输出 说明
handle 输入 存放物理内存信息的handle。类型定义请参见aclrtDrvMemHandle。
需先在本进程调用aclrtMallocPhysical接口申请物理内存，该接口调用成功，会返回一个handle。
handle与shareableHandle是一一对应的关系，在同一个进程中，不允许一对多、或多对一，否则报错，例如重复调用本接口导出时则会返回报错。
flags 输入 是否启用进程白名单校验。
取值为如下宏：

- ACL_RT_VMM_EXPORT_FLAG_DEFAULT：默认值，启用进程白名单校验。配置为该值时，需单独调用aclrtMemSetPidToShareableHandleV2接口将使用shareableHandle的进程ID设置为白名单。
- ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION：关闭进程白名单校验。配置为该值时，则无需调用aclrtMemSetPidToShareableHandleV2接口。


宏的定义如下：
#define ACL_RT_VMM_EXPORT_FLAG_DEFAULT 0x0UL
#define ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION 0x1UL
shareType 输入 导出的共享句柄类型。类型定义请参见aclrtMemSharedHandleType。
shareableHandle 输出 指向共享句柄的指针。其指向的内存由调用者提供，大小根据shareType决定：
若shareType为ACL_MEM_SHARE_HANDLE_TYPE_DEFAULT，则指向一个uint64_t变量。
若shareType为ACL_MEM_SHARE_HANDLE_TYPE_FABRIC，则指向一个aclrtMemFabricHandle结构体。
typedef struct aclrtMemFabricHandle {
uint8_t data[128];
} aclrtMemFabricHandle;

返回值说明

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

约束说明

  • 对于Atlas 200I/500 A2 推理产品，Ascend RC形态下，不支持调用本接口。
  • 仅Atlas A3 训练系列产品/Atlas A3 推理系列产品支持跨AI Server的跨进程共享物理内存。
  • 不支持昇腾虚拟化实例场景。
  • 不支持算力分组场景。



aclrtMemSetPidToShareableHandleV2

aclError aclrtMemSetPidToShareableHandleV2(void *shareableHandle, aclrtMemSharedHandleType shareType, int32_t *pid, size_t pidNum)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

设置共享内存的进程白名单**。**

本接口是在接口aclrtMemSetPidToShareableHandle基础上进行了增强，用户可通过shareType参数指定导出AI Server内的共享句柄，或导出跨AI Server的共享句柄。

本接口的使用流程可参见aclrtMemExportToShareableHandle，但本接口需配合调用aclrtMemExportToShareableHandleV2接口导出共享句柄、调用aclrtMemImportFromShareableHandleV2接口导入共享句柄。

参数说明

参数名 输入/输出 说明
shareableHandle 输入 通过aclrtMemExportToShareableHandleV2接口导出的shareableHandle，表示指向共享句柄的指针。
shareType 输入 导出的共享句柄类型。类型定义请参见aclrtMemSharedHandleType。
pid 输入 用于存放白名单进程ID的数组。
进程ID可调用aclrtDeviceGetBareTgid接口获取，Docker场景下获取到的是物理机上的进程ID，非Docker场景下获取到的是进程ID。
pidNum 输入 白名单进程数量，与pid参数数组的大小保持一致。

返回值说明

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




aclrtMemImportFromShareableHandleV2

aclError aclrtMemImportFromShareableHandleV2(void *shareableHandle, aclrtMemSharedHandleType shareType, uint64_t flags, aclrtDrvMemHandle *handle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

在本进程中获取shareableHandle里的信息，并返回本进程中的handle，用于在本进程中建立虚拟地址与物理地址之间的映射关系。

本接口是在接口aclrtMemImportFromShareableHandle基础上进行了增强，用户可通过shareType参数指定导出AI Server内的共享句柄，或导出跨AI Server的共享句柄。

本接口的使用流程可参见aclrtMemExportToShareableHandle，但本接口需配合调用aclrtMemExportToShareableHandleV2接口导出共享句柄、调用aclrtMemSetPidToShareableHandleV2接口设置进程白名单。

参数说明

参数名 输入/输出 说明
shareableHandle 输入 待共享的shareableHandle，与aclrtMemExportToShareableHandleV2接口中导出的shareableHandle保持一致。
handle与shareableHandle是一一对应的关系，在同一个进程中，不允许一对多、或多对一。
shareType 输入 导出的共享句柄类型。类型定义请参见aclrtMemSharedHandleType。
flags 输入 预留参数，当前固定设置为0。
handle 输出 本进程的物理内存handle。类型定义请参见aclrtDrvMemHandle。

返回值说明

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

约束说明




aclrtMemGetAllocationGranularity

aclError aclrtMemGetAllocationGranularity(aclrtPhysicalMemProp *prop, aclrtMemGranularityOptions option, size_t *granularity)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

查询内存申请粒度。

系统内部会根据用户指定的内存属性信息计算最小粒度或建议粒度，并以granularity参数返回粒度。此粒度可用作对齐、地址大小或地址映射的倍数。

参数说明

参数名 输入/输出 说明
prop 输入 物理内存属性信息。类型定义请参见aclrtPhysicalMemProp。
option 输入 最小粒度或推荐粒度。类型定义请参见aclrtMemGranularityOptions。
granularity 输出 内存申请粒度，单位为Byte。

返回值说明

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

约束说明

Atlas 200I/500 A2 推理产品上，Ascend RC形态不支持调用本接口。




aclrtMemSetAccess

aclError aclrtMemSetAccess(void* virPtr, size_t size, aclrtMemAccessDesc* desc, size_t count)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

设置内存的访问权限。

参数说明

参数名 输入/输出 说明
virPtr 输入 虚拟内存的起始地址。
必须与aclrtMapMem或aclrtMemMapNoAccess接口的virPtr地址相同。
size 输入 虚拟内存的长度。
必须与aclrtMapMem或aclrtMemMapNoAccess接口的size相同。
desc 输入 内存访问的配置信息，包含内存访问保护标志、内存所在位置等。类型定义请参见aclrtMemAccessDesc。
count 输入 desc数组长度。

返回值说明

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




aclrtMemGetAccess

aclError aclrtMemGetAccess(void *virPtr, aclrtMemLocation *location, uint64_t *flag)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

获取内存的访问权限。

参数说明

参数名 输入/输出 说明
virPtr 输入 虚拟内存的起始地址。
必须与aclrtMapMem接口的virPtr地址相同。
location 输入 内存所在位置。类型定义请参见aclrtMemLocation。
当前仅支持将aclrtMemLocation.type设置为ACL_MEM_LOCATION_TYPE_HOST或ACL_MEM_LOCATION_TYPE_DEVICE。当aclrtMemLocation.type为ACL_MEM_LOCATION_TYPE_HOST时，aclrtMemLocation.id无效，固定设置为0即可。
flag 输出 内存访问保护标志。

返回值说明

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




aclrtMemRetainAllocationHandle

aclError aclrtMemRetainAllocationHandle(void* virPtr, aclrtDrvMemHandle *handle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据虚拟内存地址获取物理内存信息的handle。

若多次调用本接口，则需相应地调用相同次数的aclrtFreePhysical来释放物理内存handle。

若调用接口时返回ACL_ERROR_RT_FEATURE_NOT_SUPPORT，这表示底层驱动不支持该特性，需将驱动包升级到26.0.RC1或更高版本。您可以单击Link，在“固件与驱动”页面下载对应版本的驱动安装包，并参照其文档进行安装和升级。

参数说明

参数名 输入/输出 说明
virPtr 输入 “已分配的虚拟内存地址的指针”的指针。
必须与aclrtMapMem接口的virPtr地址相同。
handle 输出 存放物理内存信息的handle。类型定义请参见aclrtDrvMemHandle。

返回值说明

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

约束说明

Atlas 200I/500 A2 推理产品上，Ascend RC形态不支持调用本接口。




aclrtMemGetAllocationPropertiesFromHandle

aclError aclrtMemGetAllocationPropertiesFromHandle(aclrtDrvMemHandle handle, aclrtPhysicalMemProp* prop)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据物理内存信息的handle查询其内存属性信息。

参数说明

参数名 输入/输出 说明
handle 输入 存放物理内存信息的handle。类型定义请参见aclrtDrvMemHandle。
查询通过aclrtMallocPhysical接口申请的物理内存属性信息。
prop 输出 物理内存属性信息。类型定义请参见aclrtPhysicalMemProp。

返回值说明

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

约束说明

Atlas 200I/500 A2 推理产品上，Ascend RC形态不支持调用本接口。




aclrtMemGetAddressRange

aclError aclrtMemGetAddressRange(void *ptr, void **pbase, size_t *psize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

获取待查询地址所属内存块的起始地址以及内存块大小。

参数说明

参数名 输入/输出 说明
ptr 输入 待查询的内存地址。
pbase 输出 返回待查询地址所属内存块的起始地址。
psize 输出 返回待查询地址所属内存块的大小，单位Byte。

返回值说明

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

参考信息

使用场景 aclrtMemGetAddressRange接口行为
查询通过aclrtMalloc接口或aclrtMallocWithCfg接口返回的Device内存 返回内存块的起始地址和内存大小
查询通过aclrtMallocHost接口或aclrtMallocHostWithCfg接口返回的Host内存 返回内存块的起始地址和内存大小。
查询通过aclrtReserveMemAddress、aclrtMallocPhysical、aclrtMapMem等接口映射过的虚拟内存地址 返回经过映射的内存块的起始地址和内存大小 



aclError aclrtMemMapSelectedLink(void *virPtrDst, size_t size, void *virPtrSrc, uint32_t linkIdx)

产品支持情况

  • Ascend 950PR/Ascend 950DT：不支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：不支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

将虚拟地址 virPtrDst 映射到虚拟地址 virPtrSrc 对应的物理地址，可以通过 linkIdx 选择 HCCS 链路或者 SIO 链路。

参数说明

参数名 输入/输出 说明
virPtrDst 输入 待映射的虚拟内存地址。
需要通过aclrtReserveMemAddress接口提前预留虚拟地址内存，然后将虚拟内存的首地址作为入参传入本接口。不支持将虚拟内存首地址进行偏移后再传入本接口。
size 输入 虚拟内存大小，单位Byte。
virPtrDst与virPtrSrc处的虚拟内存大小需保持一致，且与size相等。
virPtrSrc 输入 已与物理内存建立映射关系的虚拟内存地址。
需提前通过aclrtMapMem接口完成虚拟内存与物理内存的映射，然后将虚拟内存的首地址作为入参传入本接口。不支持对虚拟内存首地址进行偏移后再传入本接口。
linkIdx 输入 链路标识。
- ACL_RT_MEM_LINK_IDX_0：SIO（Small Input Output），表示片内连接方式，两个DIE之间通过该方式连接。
- ACL_RT_MEM_LINK_IDX_1：HCCS（Huawei Cache Coherence System），HCCS是华为缓存一致性系统，用于CPU/NPU之间的高速互联。

宏定义如下：
#define ACL_RT_MEM_LINK_IDX_0 0U // SIO
#define ACL_RT_MEM_LINK_IDX_1 1U // HCCS

返回值说明

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

约束说明

若virPtrSrc虚拟内存的首地址在偏移后映射至多个不同的物理内存，则在调用aclrtMemMapSelectedLink接口将virPtrDst与virPtrSrc进行映射时，virPtrDst同样会映射至这些不同的物理内存，且virPtrDst与virPtrSrc的地址偏移量保持一致。在此场景下，需多次调用aclrtUnmapMem接口取消virPtrDst与多个物理地址之间的映射关系。




aclError aclrtMemMapSetLink(aclrtDrvMemHandle handle, aclrtMemLinkType adviceLink)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：不支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

设置物理内存映射时使用的访问链路类型。

如需指定访问链路类型，需先调用aclrtMemImportFromShareableHandle接口获取物理内存handle，再调用本接口设置该handle的访问链路类型，最后调用aclrtMapMem接口建立虚拟内存与物理内存的映射关系。

参数说明

参数名 输入/输出 说明
handle 输入 物理内存信息handle。类型定义请参见aclrtDrvMemHandle。
该handle需通过aclrtMemImportFromShareableHandle接口获取。
adviceLink 输入 内存访问链路类型。类型定义请参见aclrtMemLinkType。

返回值说明

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

约束说明

  • 对于Ascend 950PR/Ascend 950DT，adviceLink支持以下取值：
    • ACL_RT_MEM_ACCESS_UB_ONE_PORT_PATH：UB（Unified Bus）单端口路径：FM（Full Mesh）连线方式，无层级、全点对点直连。
    • ACL_RT_MEM_ACCESS_UB_MULTI_PORT_PATH：UB（Unified Bus）多端口路径：CLOS连线方式，分层结构化互联。
  • 对于Atlas A3 训练系列产品/Atlas A3 推理系列产品，adviceLink支持以下取值：
    • ACL_RT_MEM_ACCESS_LINK_SIO：SIO通道，片内连接方式，两个DIE之间通过该方式连接。
    • ACL_RT_MEM_ACCESS_LINK_HCCS：HCCS通道，HCCS是Huawei Cache Coherence System（华为缓存一致性系统），用于CPU/NPU之间的高速互联。

若当前产品不支持adviceLink指定的访问链路类型，则返回ACL_ERROR_RT_LINK_TYPE_NOT_SUPPORTED错误码。