Function: malloc

Applicability

Product	Supported (√/x)
Atlas A3 training products / Atlas A3 inference products	√
Atlas A2 training products / Atlas A2 inference products	√
Atlas training products	√
Atlas inference products	√
Atlas 200I/500 A2 inference products	√

Function Usage

Allocates linear memory of the size bytes on the device and returns the allocated memory pointer through dev_ptr. The start address of the memory is 64-byte aligned. The memory allocated by this API is byte-aligned. The size bytes requested by the user are rounded up to the nearest multiple of 32 bytes, with an additional 32 bytes added. However, for huge page memory with the memory allocation granularity of 1 GB, to save huge page memory, this API only rounds the input size up to the nearest multiple of 32 bytes, but does not add an extra 32 bytes.

Prototype

C Prototype

        
             aclError aclrtMalloc(void **devPtr, size_t size, aclrtMemMallocPolicy policy)

Python Function

        
             dev_ptr, ret = acl.rt.malloc(size, policy)

Parameter Description

Parameter	Description
size	Int, size of the memory to be allocated, in bytes. The value cannot be 0.
policy	Int, memory allocation policy. If the configured memory allocation policy is not within the value range of aclrtMemMallocPolicy, and the size is greater than or equal to 2 MB, the huge page memory is allocated; otherwise, the common page memory is allocated.

Parameter

Description

size

Int, size of the memory to be allocated, in bytes. The value cannot be 0.

policy

Int, memory allocation policy.

If the configured memory allocation policy is not within the value range of aclrtMemMallocPolicy, and the size is greater than or equal to 2 MB, the huge page memory is allocated; otherwise, the common page memory is allocated.

Return Value Description

Return Value	Description
dev_ptr	Int, address of the pointer to the allocated device memory.
ret	Int, error code: 0 on success; else, failure.

Restrictions

Media data processing has higher requirements on the memory for storing the input and output data (for example, the start address of the memory must be 128-byte aligned). Therefore, the following dedicated memory allocation APIs are required:
- acl.media.dvpp_malloc: Allocates memory for the media data processing V1 API calls to perform operations such as cropping and resizing on images.
- acl.himpi.dvpp_malloc: Allocates memory for the media data processing V2 API calls to perform operations such as cropping and resizing on images.
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 call needs to be freed by the acl.rt.free call.
Performance deterioration will be caused by the frequent calling of acl.rt.malloc to allocate memory and acl.rt.free to free memory. You are advised to perform memory preallocation and management in advance to avoid frequent memory allocation and deallocation.
The size of memory allocated by calling acl.rt.malloc is the input size rounded up to the nearest multiple of 32, plus 32 bytes.
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.

Parent topic: Memory Management