aclrtHostRegister

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 a host memory address. To unregister the memory, call aclrtHostUnregister.

This is an encapsulated API that applies only to C++ programs. It internally calls the C API aclrtHostRegister or aclrtHostRegisterV2.

Prototype

# Map and register the host memory as a memory address that can be accessed by the device, and obtains the mapped device memory address.
template <typename T>
aclError aclrtHostRegister(T *ptr, uint64_t size, aclrtHostRegisterType type, T **devPtr)

# Specify a memory registration type and register a host memory address.
template <typename T>
aclError aclrtHostRegister(T *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.
type	Input	Memory registration type. For details about the type definition, see aclrtHostRegisterType.
devPtr	Output	Memory address mapped from the host memory. This address can be accessed by the device. This address can only be accessed on the device. For example, it can be used as a parameter of the kernel function for the AI Core on the device to access. If host memory processing is involved, use the original host memory address.
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 the device, 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 the device, including read and write operations. ACL_HOST_REG_READONLY: Maps and registers host memory as read-only to the device. This reserved option is not supported currently. 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: C++ Extension APIs