Mem - Experimental

oneAPI Level Zero Specification - Version 1.18.31

Mem - Experimental Functions

zeMemGetIpcHandleFromFileDescriptorExp

Added in version 1.6

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetIpcHandleFromFileDescriptorExp(ze_context_handle_t hContext, uint64_t handle, ze_ipc_mem_handle_t *pIpcHandle)

Creates an IPC memory handle out of a file descriptor.

• Handle passed must be a valid file descriptor obtained with ze_external_memory_export_fd_t via zeMemGetAllocProperties or zePhysicalMemGetProperties.

• Returned IPC handle may contain metadata in addition to the file descriptor.

• 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

• handle – [in] file descriptor

• pIpcHandle – [out] Returned IPC memory handle

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pIpcHandle

zeMemGetFileDescriptorFromIpcHandleExp

Added in version 1.6

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetFileDescriptorFromIpcHandleExp(ze_context_handle_t hContext, ze_ipc_mem_handle_t ipcHandle, uint64_t *pHandle)

Gets the file descriptor contained in an IPC memory handle.

• IPC memory handle must be a valid handle obtained with zeMemGetIpcHandle.

• 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

• ipcHandle – [in] IPC memory handle

• pHandle – [out] Returned file descriptor

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pHandle

zeMemSetAtomicAccessAttributeExp

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemSetAtomicAccessAttributeExp(ze_context_handle_t hContext, ze_device_handle_t hDevice, const void *ptr, size_t size, ze_memory_atomic_attr_exp_flags_t attr)

Sets atomic access attributes for a shared allocation.

• If the shared-allocation is owned by multiple devices (i.e. nullptr was passed to zeMemAllocShared when creating it), then hDevice may be passed to set the attributes in that specific device. If nullptr is passed in hDevice, then the atomic attributes are set in all devices associated with the allocation.

• If the atomic access attribute select is not supported by the driver, ZE_RESULT_ERROR_INVALID_ARGUMENT is returned.

• The atomic access attribute may be only supported at a device-specific granularity, such as at a page boundary. In this case, the memory range may be expanded such that the start and end of the range satisfy granularity requirements.

• When calling this function multiple times with different flags, only the attributes from last call are honored.

• The application must not call this function for shared-allocations currently being used by the device.

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

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

Parameters:

• hContext – [in] handle of context

• hDevice – [in] device associated with the memory advice

• ptr – [in] Pointer to the start of the memory range

• size – [in] Size in bytes of the memory range

• attr – [in] Atomic access attributes to set for the specified range. Must be 0 (default) or a valid combination of ze_memory_atomic_attr_exp_flag_t.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7f < attr

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

zeMemGetAtomicAccessAttributeExp

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetAtomicAccessAttributeExp(ze_context_handle_t hContext, ze_device_handle_t hDevice, const void *ptr, size_t size, ze_memory_atomic_attr_exp_flags_t *pAttr)

Retrieves the atomic access attributes previously set for a shared allocation.

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

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

Parameters:

• hContext – [in] handle of context

• hDevice – [in] device associated with the memory advice

• ptr – [in] Pointer to the start of the memory range

• size – [in] Size in bytes of the memory range

• pAttr – [out] Atomic access attributes for the specified range

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

  • nullptr == pAttr

Mem - Experimental Enums

ze_memory_atomic_attr_exp_flags_t

Added in version 1.7

enum ze_memory_atomic_attr_exp_flag_t

Values:

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_ATOMICS

Atomics on the pointer are not allowed.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_HOST_ATOMICS

Host atomics on the pointer are not allowed.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_HOST_ATOMICS

Host atomics on the pointer are allowed. Requires ZE_MEMORY_ACCESS_CAP_FLAG_ATOMIC returned by zeDeviceGetMemoryAccessProperties.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_DEVICE_ATOMICS

Device atomics on the pointer are not allowed.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_DEVICE_ATOMICS

Device atomics on the pointer are allowed. Requires ZE_MEMORY_ACCESS_CAP_FLAG_ATOMIC returned by zeDeviceGetMemoryAccessProperties.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_SYSTEM_ATOMICS

Concurrent atomics on the pointer from both host and device are not allowed

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_SYSTEM_ATOMICS

Concurrent atomics on the pointer from both host and device are allowed. Requires ZE_MEMORY_ACCESS_CAP_FLAG_CONCURRENT_ATOMIC returned by zeDeviceGetMemoryAccessProperties.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_FORCE_UINT32

Value marking end of ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_* ENUMs.

ze_relaxed_allocation_limits_exp_flags_t

Added in version 1.1

enum ze_relaxed_allocation_limits_exp_flag_t

Values:

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_MAX_SIZE

[DEPRECATED] Allocation size may exceed the maxMemAllocSize member of ze_device_properties_t. Use ze_relaxed_allocation_limits_ext_flags_t MAX_SIZE instead.

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_FORCE_UINT32

Value marking end of ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_* ENUMs.

Mem - Experimental Structures

ze_relaxed_allocation_limits_exp_desc_t

Added in version 1.1

struct ze_relaxed_allocation_limits_exp_desc_t

[DEPRECATED] Relaxed limits memory allocation descriptor. Use ze_relaxed_allocation_limits_ext_desc_t instead.

• [DEPRECATED] This structure may be passed to zeMemAllocShared or zeMemAllocDevice, via the pNext member of ze_device_mem_alloc_desc_t. Use ze_relaxed_allocation_limits_ext_desc_t instead.

• [DEPRECATED] This structure may also be passed to zeMemAllocHost, via the pNext member of ze_host_mem_alloc_desc_t. Use ze_relaxed_allocation_limits_ext_desc_t instead.

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_exp_flags_t flags

[in] [DEPRECATED] no longer supported, use ze_relaxed_allocation_limits_ext_desc_t instead

ze_memory_sub_allocations_exp_properties_t

Added in version 1.5

struct ze_memory_sub_allocations_exp_properties_t

Sub-Allocations Properties.

• This structure may be passed to zeMemGetAllocProperties, via the pNext member of ze_memory_allocation_properties_t.

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

uint32_t *pCount

[in,out] pointer to the number of sub-allocations. if count is zero, then the driver shall update the value with the total number of sub-allocations on which the allocation has been divided. if count is greater than the number of sub-allocations, then the driver shall update the value with the correct number of sub-allocations.

ze_sub_allocation_t *pSubAllocations

[in,out][optional][range(0, *pCount)] array of properties for sub-allocations. if count is less than the number of sub-allocations available, then driver shall only retrieve properties for that number of sub-allocations.