Mem - Extensions

Mem - Extensions#

oneAPI Level Zero Specification - Version 1.18.31

Mem - Extension Functions#

zeMemFreeExt#

Added in version 1.3

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemFreeExt(ze_context_handle_t hContext, const ze_memory_free_ext_desc_t *pMemFreeDesc, void *ptr)#

Frees allocated host memory, device memory, or shared memory on the context using the specified free policy.

  • Similar to zeMemFree, with added parameter to choose the free policy.

  • Does not guarantee memory is freed upon return. See free policy descriptions for details.

  • 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

  • pMemFreeDesc – [in] pointer to memory free descriptor

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

Returns:

Mem - Extension Enums#

ze_relaxed_allocation_limits_ext_flags_t#

Added in version 1.17

enum ze_relaxed_allocation_limits_ext_flag_t#

Values:

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXT_FLAG_MAX_SIZE#

Allocation size may exceed the maxMemAllocSize member of ze_device_properties_t.

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXT_FLAG_FORCE_UINT32#

Value marking end of ZE_RELAXED_ALLOCATION_LIMITS_EXT_FLAG_* ENUMs.

ze_memory_compression_hints_ext_flags_t#

Added in version 1.3

enum ze_memory_compression_hints_ext_flag_t#

Values:

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_COMPRESSED#

Hint Driver implementation to make allocation compressible.

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_UNCOMPRESSED#

Hint Driver implementation to make allocation not compressible.

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_FORCE_UINT32#

Value marking end of ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_* ENUMs.

Mem - Extension Structures#

ze_relaxed_allocation_limits_ext_desc_t#

Added in version 1.17

struct ze_relaxed_allocation_limits_ext_desc_t#

Relaxed limits 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_relaxed_allocation_limits_ext_flags_t flags#

[in] flags specifying allocation limits to relax. must be 0 (default) or a valid combination of ze_relaxed_allocation_limits_ext_flag_t;

ze_memory_compression_hints_ext_desc_t#

Added in version 1.3

struct ze_memory_compression_hints_ext_desc_t#

Compression hints 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_memory_compression_hints_ext_flags_t flags#

[in] flags specifying if allocation should be compressible or not. Must be set to one of the ze_memory_compression_hints_ext_flag_t;

ze_memory_free_ext_desc_t#

Added in version 1.3

struct ze_memory_free_ext_desc_t#

Memory free descriptor with free policy.

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_driver_memory_free_policy_ext_flags_t freePolicy#

[in] flags specifying the memory free policy. must be 0 (default) or a supported ze_driver_memory_free_policy_ext_flag_t; default behavior is to free immediately.

ze_external_memmap_sysmem_ext_desc_t#

Added in version 1.14

struct ze_external_memmap_sysmem_ext_desc_t#

Maps external system memory for an allocation.

  • This structure may be passed to zeMemAllocHost, via the pNext member of ze_host_mem_alloc_desc_t to map system memory for a host allocation.

  • The pSystemMemory pointer and size being mapped must be aligned to the host page size. The host page size must be queried using operating-system-specific calls, as the mapped memory originates from the system allocator rather than from Level-Zero; there is no Level-Zero query for this value.

  • On success, the pointer returned from zeMemAllocHost is identical to pSystemMemory; the mapping preserves the virtual address, so the same address is valid on both the host and the device.

  • Memory from the application’s heap, stack, or statically-allocated (global) storage is supported. Support for memory obtained by other means is platform- and driver-dependent and is not guaranteed. If pSystemMemory points to a memory type that cannot be mapped, zeMemAllocHost returns ZE_RESULT_ERROR_INVALID_ARGUMENT.

  • Host memory that is read-only can only be mapped successfully when the ZE_HOST_MEM_ALLOC_FLAG_MEM_READ_ONLY flag is set in ze_host_mem_alloc_desc_t; in that case device access to the mapped memory is read-only.

  • The system memory referenced by pSystemMemory must remain valid for the entire lifetime of the resulting allocation. Freeing or unmapping the underlying system memory before the allocation is released results in undefined behavior.

  • Mapped memory ranges must not overlap. Releasing a mapping with zeMemFree tears down the device page-table entries for its virtual address range. Because these page tables are shared across imports, releasing a mapping that overlaps another import also tears down the overlapping device page-table entries, leaving the other allocation invalid for device access. The host system memory itself is unaffected.

  • After mapping, zeMemGetAllocProperties reports the allocation type as ZE_MEMORY_TYPE_HOST_IMPORTED.

  • The mapping is released by passing the pointer to zeMemFree, like any other host allocation.

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

void *pSystemMemory#

[in] system memory pointer to map; must be page-aligned.

uint64_t size#

[in] size of the system memory to map; must be a multiple of the page size.

ze_ipc_mem_handle_type_ext_desc_t#

Added in version 1.15

struct ze_ipc_mem_handle_type_ext_desc_t#

[‘IPC Memory Handle Type Extension Descriptor’, ‘Used in zeMemGetIpcHandleWithProperties, zeMemAllocDevice, and zeMemAllocHost, zePhysicalMemCreate to specify the IPC memory handle type to create for this allocation.’]

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_ipc_mem_handle_type_flags_t typeFlags#

[in] valid combination of ze_ipc_mem_handle_type_flag_t

ze_ipc_phys_mem_handle_range_ext_desc_t#

Added in version 1.18

struct ze_ipc_phys_mem_handle_range_ext_desc_t#

Descriptor for capturing a VA range into an IPC memory handle.

  • Pass this structure via the pNext parameter of zeMemGetIpcHandleWithProperties. When present, the ptr argument specifies the base VA of the range rather than the base of a single allocation.

  • The ptr argument of zeMemGetIpcHandleWithProperties specifies the base VA of the range.

  • The range may span more than one reserved VA region created by zeVirtualMemReserve; the underlying reservations are not significant. What is captured is the ordered set of physical memory objects mapped along [ptr, ptr+size).

  • The caller may start at an arbitrary offset within a mapped range and may capture a subset of a larger mapped range, provided the requested [ptr, ptr+size) is itself fully and contiguously mapped.

  • An individual physical memory object along the range need not be mapped at its own offset zero; zeVirtualMemMap may have mapped it at a non-zero offset into the physical object. The export captures the offset at which each physical object was mapped, and the importer reproduces each mapping at that same offset, so the importer views exactly the same memory as the exporter.

  • This extension is only supported for ranges backed by virtual reservations (zeVirtualMemReserve) mapped to physical memory objects (zeVirtualMemMap). Device, host, and shared USM pointers (from zeMemAllocDevice, zeMemAllocHost, and zeMemAllocShared) are not supported and will not be grouped into a range handle. If [ptr, ptr+size) includes any standard USM VA rather than a reserved VA, zeMemGetIpcHandleWithProperties returns ZE_RESULT_ERROR_INVALID_ARGUMENT.

  • The driver enumerates all physical memory objects mapped to [ptr, ptr+size) and encodes them into the returned IPC handle in VA order.

  • On the importer side, zeMemOpenIpcHandle decodes the handle and maps all physical objects into a fresh contiguous VA reservation in the same order.

  • The total addressable size on the importer equals size. When ptr begins at an offset within a physical memory object, the returned importer pointer corresponds to ptr, not to the base of the first encoded object.

  • The importer does not need to be told size out of band: the range handle is self-describing. Calling zeMemGetAddressRange on the pointer returned by zeMemOpenIpcHandle reports the base and full size of the imported range.

  • The exported IPC handle is a static snapshot taken at the time of the call. Physical memory subsequently mapped into, unmapped from, or grown beyond the exporter’s VA range is not reflected in a previously exported handle or in any already-open importer view; a new export is required to share the additional mappings.

  • There is no application-visible limit on the number of physical memory objects a range may encode; how the driver represents and stores them is opaque and is not bound by the size of ze_ipc_mem_handle_t. If the driver cannot accommodate the range, for example it cannot store the number of physical objects being represented, zeMemGetIpcHandleWithProperties fails with ZE_RESULT_ERROR_UNSUPPORTED_SIZE.

  • Returns ZE_RESULT_ERROR_ADDRESS_NOT_FOUND if any sub-region within [ptr, ptr+size) is not mapped to a physical memory object. The range must be fully mapped with no holes, because the importer is guaranteed a contiguous range and unmapped gaps cannot be represented.

  • Returns ZE_RESULT_ERROR_INVALID_SIZE if size is 0.

  • Returns ZE_RESULT_ERROR_UNSUPPORTED_SIZE if the driver cannot accommodate the range, for example the number of physical memory objects encoded exceeds what the implementation can store.

  • Returns ZE_RESULT_ERROR_INVALID_NULL_POINTER if the ptr argument is NULL.

  • Returns ZE_RESULT_ERROR_INVALID_ARGUMENT if [ptr, ptr+size) includes a device, host, or shared USM allocation rather than reserved VA mapped to physical memory.

  • Returns ZE_RESULT_ERROR_UNSUPPORTED_FEATURE if the driver or device does not support the ZE_IPC_PHYS_MEM_HANDLE_RANGE_EXT_NAME extension.

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

size_t size#

[in] size in bytes of the VA range starting at the ptr argument of zeMemGetIpcHandleWithProperties; must be non-zero. The range [ptr, ptr+size) must be fully mapped; see the details for error behavior.