Function: malloc_host

aclError aclrtMallocHost(void **hostPtr, size_t size)

host_ptr, ret= acl.rt.malloc_host(size)

When the pyACL application is running on the host, this API allocates the host memory (lock page memory). The system ensures that the start address of the memory is 64-byte aligned.

If the pyACL application is running on the device, this API is called to allocate the device memory by normal page. If 64-byte alignment is required for the start address, you need to guarantee the alignment.

size: int, size of the allocated memory, in bytes. The size cannot be 0.

host_ptr: int, address of the pointer that has been allocated with memory on the host.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

• The memory allocated by this API is not initialized. Call acl.rt.memset to initialize the memory and clear random numbers in the memory before using the memory.
• This API does not perform implicit device synchronization or stream synchronization. The memory allocation result, either success or failure, is returned immediately.
• Memory allocated by the acl.rt.malloc_host call needs to be freed by the acl.rt.free_host call.
• If acl.rt.malloc_host is called to allocate too much lock page memory, the physical memory used by the operating system for paging decreases, and the overall system performance deteriorates.
• Performance deterioration will be caused by the frequent calling of acl.rt.malloc_host to allocate memory and acl.rt.free_host to free memory. You are advised to allocate or manage memory in advance to avoid frequent memory allocation and freeing.
• If you use this API to allocate a large memory block, and divide and manage the memory, each memory segment must meet the following requirements:
  • The memory size is rounded up to the nearest multiple of 32 plus 32 bytes (m = ALIGN_UP[len,32] + 32 bytes).
  • The memory start address must be 64-byte aligned (ALIGN_UP[m,64]).
  NOTE:

  len indicates the size of a memory segment. ALIGN_UP[len,k] indicates rounding up to a multiple of k bytes as in this formula: ((len – 1)/k + 1) x k.

For details about the API call example, see Data Copy.