Mem

Contents

Mem#

oneAPI Level Zero Specification - Version 1.18.31

Mem Functions#

zeMemAllocShared#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemAllocShared(ze_context_handle_t hContext, const ze_device_mem_alloc_desc_t *device_desc, const ze_host_mem_alloc_desc_t *host_desc, size_t size, size_t alignment, ze_device_handle_t hDevice, void **pptr)#

Allocates shared memory on the context.

  • Shared allocations share ownership between the host and one or more devices.

  • Shared allocations may optionally be associated with a device by passing a handle to the device.

  • Devices supporting only single-device shared access capabilities may access shared memory associated with the device. For these devices, ownership of the allocation is shared between the host and the associated device only.

  • Passing nullptr as the device handle does not associate the shared allocation with any device. For allocations with no associated device, ownership of the allocation is shared between the host and all devices supporting cross-device shared access capabilities.

  • The application must only use the memory allocation for the context and device, or its sub-devices, which was provided during allocation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • device_desc – [in] pointer to device memory allocation descriptor

  • host_desc – [in] pointer to host memory allocation descriptor

  • size – [in] size in bytes to allocate; must be less than or equal to the maxMemAllocSize member of ze_device_properties_t

  • alignment – [in] minimum alignment in bytes for the allocation; must be a power of two

  • hDevice – [in][optional] device handle to associate with

  • pptr – [out] pointer to shared allocation

Returns:

zeMemAllocDevice#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemAllocDevice(ze_context_handle_t hContext, const ze_device_mem_alloc_desc_t *device_desc, size_t size, size_t alignment, ze_device_handle_t hDevice, void **pptr)#

Allocates device memory on the context.

  • Device allocations are owned by a specific device.

  • In general, a device allocation may only be accessed by the device that owns it.

  • The application must only use the memory allocation for the context and device, or its sub-devices, which was provided during allocation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • device_desc – [in] pointer to device memory allocation descriptor

  • size – [in] size in bytes to allocate; must be less than or equal to the maxMemAllocSize member of ze_device_properties_t

  • alignment – [in] minimum alignment in bytes for the allocation; must be a power of two

  • hDevice – [in] handle of the device

  • pptr – [out] pointer to device allocation

Returns:

zeMemAllocHost#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemAllocHost(ze_context_handle_t hContext, const ze_host_mem_alloc_desc_t *host_desc, size_t size, size_t alignment, void **pptr)#

Allocates host memory on the context.

  • Host allocations are owned by the host process.

  • Host allocations are accessible by the host and all devices within the driver’s context.

  • Host allocations are frequently used as staging areas to transfer data to or from devices.

  • The application must only use the memory allocation for the context which was provided during allocation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • host_desc – [in] pointer to host memory allocation descriptor

  • size – [in] size in bytes to allocate; must be less than or equal to the maxMemAllocSize member of ze_device_properties_t

  • alignment – [in] minimum alignment in bytes for the allocation; must be a power of two

  • pptr – [out] pointer to host allocation

Returns:

zeMemFree#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemFree(ze_context_handle_t hContext, void *ptr)#

Frees allocated host memory, device memory, or shared memory on the context.

  • The application must ensure the device is not currently referencing the memory before it is freed

  • The implementation will use the default and immediate policy to schedule all Host and Device allocations associated with this memory to be freed, without any safety checking. Actual freeing of memory is specific to user mode driver and kernel mode driver implementation and may be done asynchronously.

  • The application must not call this function from simultaneous threads with the same pointer.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in][release] pointer to memory to free

Returns:

zeMemGetAllocProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetAllocProperties(ze_context_handle_t hContext, const void *ptr, ze_memory_allocation_properties_t *pMemAllocProperties, ze_device_handle_t *phDevice)#

Retrieves attributes of a memory allocation.

  • The application may call this function from simultaneous threads.

  • The application may query attributes of a memory allocation unrelated to the context. When this occurs, the returned allocation type will be ZE_MEMORY_TYPE_UNKNOWN, and the returned identifier and associated device is unspecified.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] memory pointer to query

  • pMemAllocProperties – [in,out] query result for memory allocation properties

  • phDevice – [out][optional] device associated with this allocation

Returns:

zeMemGetAddressRange#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetAddressRange(ze_context_handle_t hContext, const void *ptr, void **pBase, size_t *pSize)#

Retrieves the base address and/or size of an allocation.

  • The application may call this function from simultaneous threads.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] memory pointer to query

  • pBase – [in,out][optional] base address of the allocation

  • pSize – [in,out][optional] size of the allocation

Returns:

zeMemGetIpcHandle#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetIpcHandle(ze_context_handle_t hContext, const void *ptr, ze_ipc_mem_handle_t *pIpcHandle)#

Creates an IPC memory handle for the specified allocation.

  • Takes a pointer to a device memory allocation and creates an IPC memory handle for exporting it for use in another process.

  • The pointer may also be a physical memory handle cast to void* (i.e. (void*)hPhysicalMem); in that case, the IPC handle represents the physical memory object directly and no virtual address mapping is required in the sending process.

  • Only one physical memory object may be associated with a single IPC handle at a time; the virtual address range passed must map to exactly one physical memory object, unless a ze_ipc_phys_mem_handle_range_ext_desc_t is chained via pNext to capture a range spanning multiple physical memory objects into a single IPC handle.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to the device memory allocation

  • pIpcHandle – [out] Returned IPC memory handle

Returns:

zeMemOpenIpcHandle#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemOpenIpcHandle(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_ipc_mem_handle_t handle, ze_ipc_memory_flags_t flags, void **pptr)#

Opens an IPC memory handle to retrieve a device pointer on the context.

  • Takes an IPC memory handle from a remote process and associates it with a device pointer usable in this process.

  • The ‘hDevice’ parameter identifies the device into which the allocation is imported. If this device differs from the one where the memory was originally allocated, it must have P2P access to the exporting device. P2P accessibility can be verified using zeDeviceGetP2PProperties or zeDeviceCanAccessPeer.

  • The hContext parameter has no requirement to match the context used during the original allocation in the exporting process. Any context of the importing process may be used.

  • After the handle is successfully opened, the returned pointer may be accessed by hDevice and by any other device of the importing process that has P2P connectivity to the exporting device.

  • When the IPC handle was originally created from a physical memory object (directly via a mapped virtual address), opening the handle assigns a new virtual address in the importing process that maps to the underlying physical memory; no prior zeVirtualMemReserve or zeVirtualMemMap call is required in the importing process.

  • The device pointer in this process should not be freed with zeMemFree, but rather with zeMemCloseIpcHandle.

  • Multiple calls to this function with the same IPC handle will return unique pointers.

  • The driver must not release the underlying physical memory until all IPC handles referencing it have been closed via zeMemCloseIpcHandle or returned via zeMemPutIpcHandle.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device to associate with the IPC memory handle

  • handle – [in] IPC memory handle

  • flags – [in] flags controlling the operation. must be 0 (default) or a valid combination of ze_ipc_memory_flag_t.

  • pptr – [out] pointer to device allocation in this process

Returns:

zeMemCloseIpcHandle#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemCloseIpcHandle(ze_context_handle_t hContext, const void *ptr)#

Closes an IPC memory handle.

  • Closes an IPC memory handle by unmapping memory that was opened in this process using zeMemOpenIpcHandle.

  • ptr must be the base pointer returned by zeMemOpenIpcHandle; passing an interior address is not valid.

  • This call unmaps every physical memory object that zeMemOpenIpcHandle mapped for this pointer and frees any virtual address reservation the driver created on the caller’s behalf to back it. When the handle encoded a range of multiple physical objects, all of those objects are unmapped by this single call. The application never reserved this address range and must not attempt to release it with zeVirtualMemFree; this call leaves no mappings or virtual address reservation behind.

  • The application must not call this function from simultaneous threads with the same pointer.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in][release] pointer to device allocation in this process

Returns:

zeMemPutIpcHandle#

Added in version 1.6

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemPutIpcHandle(ze_context_handle_t hContext, ze_ipc_mem_handle_t handle)#

Returns an IPC memory handle to the driver.

  • This call may be used for IPC handles previously obtained with either zeMemGetIpcHandle or with ze_external_memory_export_fd_t via zeMemGetAllocProperties or zePhysicalMemGetProperties.

  • Upon call, driver may release any underlying resources associated with the IPC handle. For instance, it may close the file descriptor contained in the IPC handle, if such type of handle is being used by the driver.

  • When the IPC handle encodes multiple physical memory objects (for example, a handle representing a range of objects), the driver releases all of the underlying resources it holds for that handle, not just one; for instance, it closes every file descriptor the driver opened to represent the encoded objects.

  • This call does not free the original allocation for which the IPC handle was created.

  • This function may not be called from simultaneous threads with the same IPC handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hContext – [in] handle of the context object

  • handle – [in] IPC memory handle

Returns:

zeMemGetPitchFor2dImage#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetPitchFor2dImage(ze_context_handle_t hContext, ze_device_handle_t hDevice, size_t imageWidth, size_t imageHeight, unsigned int elementSizeInBytes, size_t *rowPitch)#

Retrieves pitch information that can be used to allocate USM memory for a given image.

  • Retrieves pitch for 2D image given the width, height and size in bytes

  • The memory is then allocated using zeMemAllocDevice by providing input size calculated as the returned pitch value multiplied by image height

  • The application may call this function from simultaneous threads

  • The implementation of this function must be thread-safe.

  • The implementation of this function should be lock-free.

  • The implementation must support ZE_BINDLESS_IMAGE_EXP_NAME extension.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • imageWidth – [in] imageWidth

  • imageHeight – [in] imageHeight

  • elementSizeInBytes – [in] Element size in bytes

  • rowPitch – [out] rowPitch

Returns:

zeMemGetIpcHandleWithProperties#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetIpcHandleWithProperties(ze_context_handle_t hContext, const void *ptr, void *pNext, ze_ipc_mem_handle_t *pIpcHandle)#

Creates an IPC memory handle for the specified allocation with properties for the requested handle.

  • Takes a pointer to a device or host memory allocation and creates an IPC memory handle for exporting it for use in another process.

  • The pointer must be the base pointer of a device or host memory allocation; i.e. the value returned from zeMemAllocDevice or from zeMemAllocHost, respectively or allocated from zePhysicalMemCreate.

  • The pointer may also be a virtual address that was mapped to a physical memory object via zeVirtualMemMap; in that case, the IPC handle represents the underlying physical memory object.

  • Only one physical memory object may be associated with a single IPC handle at a time; the virtual address range passed must map to exactly one physical memory object, unless a ze_ipc_phys_mem_handle_range_ext_desc_t is chained via pNext to capture a range spanning multiple physical memory objects into a single IPC handle.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to the device memory allocation

  • pNext – [in][optional] Pointer to extension-specific structure.

  • pIpcHandle – [out] Returned IPC memory handle

Returns:

Mem Enums#

ze_device_mem_alloc_flags_t#

Added in version 1.0

enum ze_device_mem_alloc_flag_t#

Values:

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_CACHED#

device should cache allocation

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_UNCACHED#

device should not cache allocation (UC)

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_INITIAL_PLACEMENT#

optimize shared allocation for first access on the device (since v1.2)

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_FORCE_UINT32#

Value marking end of ZE_DEVICE_MEM_ALLOC_FLAG_* ENUMs.

ze_host_mem_alloc_flags_t#

Added in version 1.0

enum ze_host_mem_alloc_flag_t#

Values:

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_CACHED#

host should cache allocation

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_UNCACHED#

host should not cache allocation (UC)

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_WRITE_COMBINED#

host memory should be allocated write-combined (WC)

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_INITIAL_PLACEMENT#

optimize shared allocation for first access on the host (since v1.2)

enumerator ZE_HOST_MEM_ALLOC_FLAG_MEM_READ_ONLY#

device access will be read-only, mutually exclusive with ZE_HOST_MEM_ALLOC_FLAG_BIAS_WRITE_COMBINED (since v1.16)

enumerator ZE_HOST_MEM_ALLOC_FLAG_FORCE_UINT32#

Value marking end of ZE_HOST_MEM_ALLOC_FLAG_* ENUMs.

ze_memory_type_t#

Added in version 1.0

enum ze_memory_type_t#

Memory allocation type.

Values:

enumerator ZE_MEMORY_TYPE_UNKNOWN#

the memory pointed to is of unknown type

enumerator ZE_MEMORY_TYPE_HOST#

the memory pointed to is a host allocation

enumerator ZE_MEMORY_TYPE_DEVICE#

the memory pointed to is a device allocation

enumerator ZE_MEMORY_TYPE_SHARED#

the memory pointed to is a shared ownership allocation

enumerator ZE_MEMORY_TYPE_HOST_IMPORTED#

the memory pointed to is a host allocation created from external system memory

enumerator ZE_MEMORY_TYPE_FORCE_UINT32#

Value marking end of ZE_MEMORY_TYPE_* ENUMs.

ze_ipc_memory_flags_t#

Added in version 1.0

enum ze_ipc_memory_flag_t#

Values:

enumerator ZE_IPC_MEMORY_FLAG_BIAS_CACHED#

device should cache allocation (since v1.2)

enumerator ZE_IPC_MEMORY_FLAG_BIAS_UNCACHED#

device should not cache allocation (UC) (since v1.2)

enumerator ZE_IPC_MEMORY_FLAG_FORCE_UINT32#

Value marking end of ZE_IPC_MEMORY_FLAG_* ENUMs.

ze_ipc_mem_handle_type_flags_t#

Added in version 1.15

enum ze_ipc_mem_handle_type_flag_t#

Values:

enumerator ZE_IPC_MEM_HANDLE_TYPE_FLAG_DEFAULT#

Local IPC memory handle type for use within the same device. This is the default if no flags are specified and does not indicate if the handle is shareable across devices or machines.

enumerator ZE_IPC_MEM_HANDLE_TYPE_FLAG_FABRIC_ACCESSIBLE#

Fabric accessible IPC memory handle type for use across devices or machines via a supported fabric.

enumerator ZE_IPC_MEM_HANDLE_TYPE_FLAG_FORCE_UINT32#

Value marking end of ZE_IPC_MEM_HANDLE_TYPE_FLAG_* ENUMs.

Mem Structures#

ze_device_mem_alloc_desc_t#

Added in version 1.0

struct ze_device_mem_alloc_desc_t#

Device memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_device_mem_alloc_flags_t flags#

[in] flags specifying additional allocation controls. must be 0 (default) or a valid combination of ze_device_mem_alloc_flag_t; default behavior may use implicit driver-based heuristics.

uint32_t ordinal#

[in] ordinal of the device’s local memory to allocate from. must be less than the count returned from zeDeviceGetMemoryProperties.

ze_host_mem_alloc_desc_t#

Added in version 1.0

struct ze_host_mem_alloc_desc_t#

Host memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_host_mem_alloc_flags_t flags#

[in] flags specifying additional allocation controls. must be 0 (default) or a valid combination of ze_host_mem_alloc_flag_t; default behavior may use implicit driver-based heuristics.

ze_memory_allocation_properties_t#

Added in version 1.0

struct ze_memory_allocation_properties_t#

Memory allocation properties queried using zeMemGetAllocProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_memory_type_t type#

[out] type of allocated memory

uint64_t id#

[out] identifier for this allocation

uint64_t pageSize#

[out] page size used for allocation

ze_external_memory_export_desc_t#

Added in version 1.0

struct ze_external_memory_export_desc_t#

Additional allocation descriptor for exporting external memory.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_external_memory_type_flags_t flags#

[in] flags specifying memory export types for this allocation. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t

ze_external_memory_import_fd_t#

Added in version 1.0

struct ze_external_memory_import_fd_t#

Additional allocation descriptor for importing external memory as a file descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_external_memory_type_flags_t flags#

[in] flags specifying the memory import type for the file descriptor. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t

int fd#

[in] the file descriptor handle to import

ze_external_memory_export_fd_t#

Added in version 1.0

struct ze_external_memory_export_fd_t#

Exports an allocation as a file descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_external_memory_type_flags_t flags#

[in] flags specifying the memory export type for the file descriptor. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t

int fd#

[out] the exported file descriptor handle representing the allocation. Owned by the driver; must not be closed directly by the application.

ze_external_memory_import_win32_handle_t#

Added in version 1.2

struct ze_external_memory_import_win32_handle_t#

Additional allocation descriptor for importing external memory as a Win32 handle.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_external_memory_type_flags_t flags#

[in] flags specifying the memory import type for the Win32 handle. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t

void *handle#

[in][optional] the Win32 handle to import

const void *name#

[in][optional] name of a memory object to import

ze_external_memory_export_win32_handle_t#

Added in version 1.2

struct ze_external_memory_export_win32_handle_t#

Exports an allocation as a Win32 handle.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_external_memory_type_flags_t flags#

[in] flags specifying the memory export type for the Win32 handle. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t

void *handle#

[out] the exported Win32 handle representing the allocation.

ze_sub_allocation_t#

Added in version 1.5

struct ze_sub_allocation_t#

Properties returned for a sub-allocation.

Public Members

void *base#

[in,out][optional] base address of the sub-allocation

size_t size#

[in,out][optional] size of the allocation