Function: malloc_host

Applicability

Function Usage

Allocates the host memory (lock page memory) if the app is running on the host. The system ensures that the start address of the memory is 64-byte aligned.

Allocates the device memory by normal page if the app is running on the device. If 64-byte alignment is required for the start address, you need to guarantee the alignment.

Prototype

• C Prototype

  1	aclError aclrtMallocHost(void **hostPtr, size_t size)

• Python Function

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

Parameter Description

Return Value Description

Restrictions

• 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]).
  

  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.

Reference

For the API call example, see Data Copy.