aclrtHostRegisterV2

Applicable Products

Product	Supported
Ascend 950PR	√
Ascend 950DT	☓
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	☓
Atlas inference products	☓
Atlas training products	☓

Function

Registers host memory address. To unregister the memory, call the aclrtHostUnregister API.

Prototype

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

Parameters

Parameter	Input/Output	Description
ptr	Input	Host memory address. The host memory address must be 4 KB page-aligned. If the OS kernel version is 5.10 or earlier, using non-page-locked memory will cause exceptions. Therefore, you must call aclrtMallocHost to allocate page-locked host memory. If the OS kernel version is later than 5.10, non-page-locked host memory can be used. Therefore, you can either call aclrtMallocHost to allocate page-locked host memory, or call malloc to allocate non-page-locked host memory.
size	Input	Memory size, in bytes.
flag	Input	Memory registration type. The value can be a single macro or multiple macros combined with bitwise OR, for example, ACL_HOST_REG_MAPPED \| ACL_HOST_REG_PINNED. ACL_HOST_REG_MAPPED: Maps and registers host memory as a memory address that can be accessed by devices, and then calls aclrtHostGetDevicePointer to obtain the mapped device memory address. ACL_HOST_REG_IOMEMORY: Maps and registers the I/O space (registers and cache) of a third-party PCIe device on the host as accessible to devices, including read and write operations. This is a reserved option. ACL_HOST_REG_READONLY: Maps and registers host memory as read-only to devices. This is a reserved option. ACL_HOST_REG_PINNED: registers host non-page-locked memory as page-locked memory. Host non-page-locked memory can be allocated using C/C++ standard library functions (such as malloc, calloc, and new) or the default mmap system call. The macros are defined as follows: #define ACL_HOST_REG_MAPPED 0x2UL #define ACL_HOST_REG_IOMEMORY 0x4UL #define ACL_HOST_REG_READONLY 0x8UL #define ACL_HOST_REG_PINNED 0x10000000UL

Parameter

Input/Output

Description

ptr

Input

Host memory address.

The host memory address must be 4 KB page-aligned.

If the OS kernel version is 5.10 or earlier, using non-page-locked memory will cause exceptions. Therefore, you must call aclrtMallocHost to allocate page-locked host memory.

If the OS kernel version is later than 5.10, non-page-locked host memory can be used. Therefore, you can either call aclrtMallocHost to allocate page-locked host memory, or call malloc to allocate non-page-locked host memory.

size

Input

Memory size, in bytes.

flag

Input

Memory registration type.

The value can be a single macro or multiple macros combined with bitwise OR, for example, ACL_HOST_REG_MAPPED | ACL_HOST_REG_PINNED.

ACL_HOST_REG_MAPPED: Maps and registers host memory as a memory address that can be accessed by devices, and then calls aclrtHostGetDevicePointer to obtain the mapped device memory address.
ACL_HOST_REG_IOMEMORY: Maps and registers the I/O space (registers and cache) of a third-party PCIe device on the host as accessible to devices, including read and write operations. This is a reserved option.
ACL_HOST_REG_READONLY: Maps and registers host memory as read-only to devices. This is a reserved option.
ACL_HOST_REG_PINNED: registers host non-page-locked memory as page-locked memory. Host non-page-locked memory can be allocated using C/C++ standard library functions (such as malloc, calloc, and new) or the default mmap system call.

The macros are defined as follows:

#define ACL_HOST_REG_MAPPED 0x2UL
#define ACL_HOST_REG_IOMEMORY 0x4UL
#define ACL_HOST_REG_READONLY 0x8UL
#define ACL_HOST_REG_PINNED 0x10000000UL

Returns

0 on success; otherwise, failure. For details, see aclError.

Parent topic: Host Memory Management