Intel® FPGA SDK for OpenCL™ Pro Edition: Custom Platform Toolkit User Guide

ID 683085
Date 3/28/2022
Document Table of Contents

2.3.20. aocl_mmd_host_alloc

Host allocations provide memory that is allocated on the host. This memory must be deallocated with the aocl_mmd_free function. Host allocations are accessible by the host and one or more devices. The same pointer to a host allocation may be used on the host and all supported devices. They have address equivalence.


Once the device has signaled completion through the aocl_mmd_interrupt_handler_fn function, the host can assume it has access to the latest contents of the memory, allocated by the aocl_mmd_host_alloc function call.

void* aocl_mmd_host_alloc (int* handles, 
                           size_t num_devices,
                           size_t size,
                           size_t alignment,
                           aocl_mmd_mem_properties_t *properties,
                           int* error);

Function Arguments

  • handles—Handles for devices that needs access to this memory.
  • num_devices—Number of devices in the handles.
  • size—The size of the memory region.
  • alignment—The alignment (in bytes) of the allocation.
  • properties—Specifies additional information about the allocated memory, described by a property type name and its corresponding value. Each property type name is immediately followed by the corresponding desired value. The list is terminated with a zero. Supported values are described above. For example, [<property1>, <value1>, <property2>, <value2>, 0]
  • error—The error code defined by AOCL_MMD_ERROR*:
    • AOCL_MMD_ERROR_SUCCESS—No error occurred.
    • AOCL_MMD_ERROR_INVALID_HANDLE—The device handle provided is invalid.
    • AOCL_MMD_ERROR_OUT_OF_MEMORY—Ran out of memory.
    • AOCL_MMD_ERROR_UNSUPPORTED_ALIGNMENT—The device does not support the provided alignment.
    • AOCL_MMD_ERROR_UNSUPPORTED_PROPERTY—The device does not support the provided property.

Return Value

If the aocl_mmd_host_alloc function executes successfully, the return value is a valid pointer value. Otherwise, the return value is NULL.