Core API

oneAPI Level Zero Specification - Version 1.1.2

Common

• Enumerations

  • ze_result_t

  • ze_structure_type_t

  • ze_external_memory_type_flags_t

• Structures

  • ze_ipc_mem_handle_t

  • ze_ipc_event_pool_handle_t

  • ze_base_properties_t

  • ze_base_desc_t

Common Enums

ze_result_t

enum ze_result_t

Defines Return/Error codes.

Values:

ZE_RESULT_SUCCESS = 0

[Core] success

ZE_RESULT_NOT_READY = 1

[Core] synchronization primitive not signaled

ZE_RESULT_ERROR_DEVICE_LOST = 0x70000001

[Core] device hung, reset, was removed, or driver update occurred

ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY = 0x70000002

[Core] insufficient host memory to satisfy call

ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY = 0x70000003

[Core] insufficient device memory to satisfy call

ZE_RESULT_ERROR_MODULE_BUILD_FAILURE = 0x70000004

[Core] error occurred when building module, see build log for details

ZE_RESULT_ERROR_MODULE_LINK_FAILURE = 0x70000005

[Core] error occurred when linking modules, see build log for details

ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS = 0x70010000

[Sysman] access denied due to permission level

ZE_RESULT_ERROR_NOT_AVAILABLE = 0x70010001

[Sysman] resource already in use and simultaneous access not allowed or resource was removed

ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE = 0x70020000

[Tools] external required dependency is unavailable or missing

ZE_RESULT_ERROR_UNINITIALIZED = 0x78000001

[Validation] driver is not initialized

ZE_RESULT_ERROR_UNSUPPORTED_VERSION = 0x78000002

[Validation] generic error code for unsupported versions

ZE_RESULT_ERROR_UNSUPPORTED_FEATURE = 0x78000003

[Validation] generic error code for unsupported features

ZE_RESULT_ERROR_INVALID_ARGUMENT = 0x78000004

[Validation] generic error code for invalid arguments

ZE_RESULT_ERROR_INVALID_NULL_HANDLE = 0x78000005

[Validation] handle argument is not valid

ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE = 0x78000006

[Validation] object pointed to by handle still in-use by device

ZE_RESULT_ERROR_INVALID_NULL_POINTER = 0x78000007

[Validation] pointer argument may not be nullptr

ZE_RESULT_ERROR_INVALID_SIZE = 0x78000008

[Validation] size argument is invalid (e.g., must not be zero)

ZE_RESULT_ERROR_UNSUPPORTED_SIZE = 0x78000009

[Validation] size argument is not supported by the device (e.g., too large)

ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT = 0x7800000a

too small)

[Validation] alignment argument is not supported by the device (e.g.,

ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT = 0x7800000b

[Validation] synchronization object in invalid state

ZE_RESULT_ERROR_INVALID_ENUMERATION = 0x7800000c

[Validation] enumerator argument is not valid

ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION = 0x7800000d

[Validation] enumerator argument is not supported by the device

ZE_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT = 0x7800000e

[Validation] image format is not supported by the device

ZE_RESULT_ERROR_INVALID_NATIVE_BINARY = 0x7800000f

[Validation] native binary is not supported by the device

ZE_RESULT_ERROR_INVALID_GLOBAL_NAME = 0x78000010

[Validation] global variable is not found in the module

ZE_RESULT_ERROR_INVALID_KERNEL_NAME = 0x78000011

[Validation] kernel name is not found in the module

ZE_RESULT_ERROR_INVALID_FUNCTION_NAME = 0x78000012

[Validation] function name is not found in the module

ZE_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION = 0x78000013

device

[Validation] group size dimension is not valid for the kernel or

ZE_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION = 0x78000014

device

[Validation] global width dimension is not valid for the kernel or

ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX = 0x78000015

[Validation] kernel argument index is not valid for kernel

ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE = 0x78000016

[Validation] kernel argument size does not match kernel

ZE_RESULT_ERROR_INVALID_KERNEL_ATTRIBUTE_VALUE = 0x78000017

device

[Validation] value of kernel attribute is not valid for the kernel or

ZE_RESULT_ERROR_INVALID_MODULE_UNLINKED = 0x78000018

be created from it.

[Validation] module with imports needs to be linked before kernels can

ZE_RESULT_ERROR_INVALID_COMMAND_LIST_TYPE = 0x78000019

[Validation] command list type does not match command queue type

ZE_RESULT_ERROR_OVERLAPPING_REGIONS = 0x7800001a

memory

[Validation] copy operations do not support overlapping regions of

ZE_RESULT_ERROR_UNKNOWN = 0x7ffffffe

[Core] unknown or internal error

ZE_RESULT_FORCE_UINT32 = 0x7fffffff

ze_structure_type_t

enum ze_structure_type_t

Defines structure types.

Values:

ZE_STRUCTURE_TYPE_DRIVER_PROPERTIES = 0x1

ze_driver_properties_t

ZE_STRUCTURE_TYPE_DRIVER_IPC_PROPERTIES = 0x2

ze_driver_ipc_properties_t

ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES = 0x3

ze_device_properties_t

ZE_STRUCTURE_TYPE_DEVICE_COMPUTE_PROPERTIES = 0x4

ze_device_compute_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MODULE_PROPERTIES = 0x5

ze_device_module_properties_t

ZE_STRUCTURE_TYPE_COMMAND_QUEUE_GROUP_PROPERTIES = 0x6

ze_command_queue_group_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MEMORY_PROPERTIES = 0x7

ze_device_memory_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MEMORY_ACCESS_PROPERTIES = 0x8

ze_device_memory_access_properties_t

ZE_STRUCTURE_TYPE_DEVICE_CACHE_PROPERTIES = 0x9

ze_device_cache_properties_t

ZE_STRUCTURE_TYPE_DEVICE_IMAGE_PROPERTIES = 0xa

ze_device_image_properties_t

ZE_STRUCTURE_TYPE_DEVICE_P2P_PROPERTIES = 0xb

ze_device_p2p_properties_t

ZE_STRUCTURE_TYPE_DEVICE_EXTERNAL_MEMORY_PROPERTIES = 0xc

ze_device_external_memory_properties_t

ZE_STRUCTURE_TYPE_CONTEXT_DESC = 0xd

ze_context_desc_t

ZE_STRUCTURE_TYPE_COMMAND_QUEUE_DESC = 0xe

ze_command_queue_desc_t

ZE_STRUCTURE_TYPE_COMMAND_LIST_DESC = 0xf

ze_command_list_desc_t

ZE_STRUCTURE_TYPE_EVENT_POOL_DESC = 0x10

ze_event_pool_desc_t

ZE_STRUCTURE_TYPE_EVENT_DESC = 0x11

ze_event_desc_t

ZE_STRUCTURE_TYPE_FENCE_DESC = 0x12

ze_fence_desc_t

ZE_STRUCTURE_TYPE_IMAGE_DESC = 0x13

ze_image_desc_t

ZE_STRUCTURE_TYPE_IMAGE_PROPERTIES = 0x14

ze_image_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MEM_ALLOC_DESC = 0x15

ze_device_mem_alloc_desc_t

ZE_STRUCTURE_TYPE_HOST_MEM_ALLOC_DESC = 0x16

ze_host_mem_alloc_desc_t

ZE_STRUCTURE_TYPE_MEMORY_ALLOCATION_PROPERTIES = 0x17

ze_memory_allocation_properties_t

ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_EXPORT_DESC = 0x18

ze_external_memory_export_desc_t

ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMPORT_FD = 0x19

ze_external_memory_import_fd_t

ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_EXPORT_FD = 0x1a

ze_external_memory_export_fd_t

ZE_STRUCTURE_TYPE_MODULE_DESC = 0x1b

ze_module_desc_t

ZE_STRUCTURE_TYPE_MODULE_PROPERTIES = 0x1c

ze_module_properties_t

ZE_STRUCTURE_TYPE_KERNEL_DESC = 0x1d

ze_kernel_desc_t

ZE_STRUCTURE_TYPE_KERNEL_PROPERTIES = 0x1e

ze_kernel_properties_t

ZE_STRUCTURE_TYPE_SAMPLER_DESC = 0x1f

ze_sampler_desc_t

ZE_STRUCTURE_TYPE_PHYSICAL_MEM_DESC = 0x20

ze_physical_mem_desc_t

ZE_STRUCTURE_TYPE_DEVICE_RAYTRACING_EXT_PROPERTIES = 0x00010001

ze_device_raytracing_ext_properties_t

ZE_STRUCTURE_TYPE_RAYTRACING_MEM_ALLOC_EXT_DESC = 0x10002

ze_raytracing_mem_alloc_ext_desc_t

ZE_STRUCTURE_TYPE_FLOAT_ATOMIC_EXT_PROPERTIES = 0x10003

ze_float_atomic_ext_properties_t

ZE_STRUCTURE_TYPE_RELAXED_ALLOCATION_LIMITS_EXP_DESC = 0x00020001

ze_relaxed_allocation_limits_exp_desc_t

ZE_STRUCTURE_TYPE_MODULE_PROGRAM_EXP_DESC = 0x00020002

ze_module_program_exp_desc_t

ZE_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff

ze_external_memory_type_flags_t

enum ze_external_memory_type_flag_t

Values:

ZE_EXTERNAL_MEMORY_TYPE_FLAG_OPAQUE_FD = ZE_BIT(0)

an opaque POSIX file descriptor handle

ZE_EXTERNAL_MEMORY_TYPE_FLAG_DMA_BUF = ZE_BIT(1)

a file descriptor handle for a Linux dma_buf

ZE_EXTERNAL_MEMORY_TYPE_FLAG_FORCE_UINT32 = 0x7fffffff

Common Structures

ze_ipc_mem_handle_t

struct ze_ipc_mem_handle_t

IPC handle to a memory allocation.

Public Members

char data[ZE_MAX_IPC_HANDLE_SIZE]

[out] Opaque data representing an IPC handle

ze_ipc_event_pool_handle_t

struct ze_ipc_event_pool_handle_t

IPC handle to a event pool allocation.

Public Members

char data[ZE_MAX_IPC_HANDLE_SIZE]

[out] Opaque data representing an IPC handle

ze_base_properties_t

struct ze_base_properties_t

Base for all properties types.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_base_desc_t

struct ze_base_desc_t

Base for all descriptor types.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

Driver

• Functions

  • zeInit

  • zeDriverGet

  • zeDriverGetApiVersion

  • zeDriverGetProperties

  • zeDriverGetIpcProperties

  • zeDriverGetExtensionProperties

  • zeDriverGetExtensionFunctionAddress

• Enumerations

  • ze_init_flags_t

  • ze_api_version_t

  • ze_ipc_property_flags_t

• Structures

  • ze_driver_uuid_t

  • ze_driver_properties_t

  • ze_driver_ipc_properties_t

  • ze_driver_extension_properties_t

Driver Functions

zeInit

ZE_APIEXPORT ze_result_t ZE_APICALL zeInit(ze_init_flags_t flags)

Initialize the ‘oneAPI’ driver(s)

Parameters

• flags: [in] initialization flags. must be 0 (default) or a combination of ze_init_flag_t.

• The application must call this function before calling any other function.

• If this function is not called then all other functions will return ZE_RESULT_ERROR_UNINITIALIZED.

• Only one instance of each driver will be initialized per process.

• The application may call this function multiple times with different flags or environment variables enabled.

• The application may call this function from simultaneous threads.

• The implementation of this function must be thread-safe for scenarios where multiple libraries may initialize the driver(s) simultaneously.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < flags

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

zeDriverGet

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGet(uint32_t *pCount, ze_driver_handle_t *phDrivers)

Retrieves driver instances.

Parameters

• pCount: [in,out] pointer to the number of driver instances. if count is zero, then the loader shall update the value with the total number of drivers available. if count is greater than the number of drivers available, then the loader shall update the value with the correct number of drivers available.

• phDrivers: [in,out][optional][range(0, *pCount)] array of driver instance handles. if count is less than the number of drivers available, then the loader shall only retrieve that number of drivers.

• A driver represents a collection of physical devices.

• Multiple calls to this function will return identical driver handles, in the same order.

• The application may pass nullptr for pDrivers when only querying the number of drivers.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetPlatformIDs

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDriverGetApiVersion

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetApiVersion(ze_driver_handle_t hDriver, ze_api_version_t *version)

Returns the API version supported by the specified driver.

Parameters

• hDriver: [in] handle of the driver instance

• version: [out] api version

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == version

zeDriverGetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetProperties(ze_driver_handle_t hDriver, ze_driver_properties_t *pDriverProperties)

Retrieves properties of the driver.

Parameters

• hDriver: [in] handle of the driver instance

• pDriverProperties: [in,out] query result for driver properties

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetPlatformInfo

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pDriverProperties

zeDriverGetIpcProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetIpcProperties(ze_driver_handle_t hDriver, ze_driver_ipc_properties_t *pIpcProperties)

Retrieves IPC attributes of the driver.

Parameters

• hDriver: [in] handle of the driver instance

• pIpcProperties: [in,out] query result for IPC properties

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pIpcProperties

zeDriverGetExtensionProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetExtensionProperties(ze_driver_handle_t hDriver, uint32_t *pCount, ze_driver_extension_properties_t *pExtensionProperties)

Retrieves extension properties.

Parameters

• hDriver: [in] handle of the driver instance

• pCount: [in,out] pointer to the number of extension properties. if count is zero, then the driver shall update the value with the total number of extension properties available. if count is greater than the number of extension properties available, then the driver shall update the value with the correct number of extension properties available.

• pExtensionProperties: [in,out][optional][range(0, *pCount)] array of query results for extension properties. if count is less than the number of extension properties available, then driver shall only retrieve that number of extension properties.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkEnumerateInstanceExtensionProperties

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDriverGetExtensionFunctionAddress

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetExtensionFunctionAddress(ze_driver_handle_t hDriver, const char *name, void **ppFunctionAddress)

Retrieves function pointer for vendor-specific or experimental extensions.

Parameters

• hDriver: [in] handle of the driver instance

• name: [in] extension name

• ppFunctionAddress: [out] pointer to function pointer

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == name

  • nullptr == ppFunctionAddress

Driver Enums

ze_init_flags_t

enum ze_init_flag_t

Values:

ZE_INIT_FLAG_GPU_ONLY = ZE_BIT(0)

only initialize GPU drivers

ZE_INIT_FLAG_FORCE_UINT32 = 0x7fffffff

ze_api_version_t

enum ze_api_version_t

Supported API versions.

• API versions contain major and minor attributes, use ZE_MAJOR_VERSION and ZE_MINOR_VERSION

Values:

ZE_API_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZE_API_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZE_API_VERSION_FORCE_UINT32 = 0x7fffffff

ze_ipc_property_flags_t

enum ze_ipc_property_flag_t

Values:

ZE_IPC_PROPERTY_FLAG_MEMORY = ZE_BIT(0)

Supports passing memory allocations between processes. See zeMemGetIpcHandle.

ZE_IPC_PROPERTY_FLAG_EVENT_POOL = ZE_BIT(1)

Supports passing event pools between processes. See zeEventPoolGetIpcHandle.

ZE_IPC_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

Driver Structures

ze_driver_uuid_t

struct ze_driver_uuid_t

Driver universal unique id (UUID)

Public Members

uint8_t id[ZE_MAX_DRIVER_UUID_SIZE]

[out] opaque data representing a driver UUID

ze_driver_properties_t

struct ze_driver_properties_t

Driver properties queried using zeDriverGetProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_driver_uuid_t uuid

[out] universal unique identifier.

uint32_t driverVersion

[out] driver version The driver version is a non-zero, monotonically increasing value where higher values always indicate a more recent version.

ze_driver_ipc_properties_t

struct ze_driver_ipc_properties_t

IPC properties queried using zeDriverGetIpcProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_ipc_property_flags_t flags

[out] 0 (none) or a valid combination of ze_ipc_property_flag_t

ze_driver_extension_properties_t

struct ze_driver_extension_properties_t

Extension properties queried using zeDriverGetExtensionProperties.

Public Members

char name[ZE_MAX_EXTENSION_NAME]

[out] extension name

uint32_t version

[out] extension version using ZE_MAKE_VERSION

Device

• Functions

  • zeDeviceGet

  • zeDeviceGetSubDevices

  • zeDeviceGetProperties

  • zeDeviceGetComputeProperties

  • zeDeviceGetModuleProperties

  • zeDeviceGetCommandQueueGroupProperties

  • zeDeviceGetMemoryProperties

  • zeDeviceGetMemoryAccessProperties

  • zeDeviceGetCacheProperties

  • zeDeviceGetImageProperties

  • zeDeviceGetExternalMemoryProperties

  • zeDeviceGetP2PProperties

  • zeDeviceCanAccessPeer

  • zeDeviceGetStatus

  • zeDeviceGetGlobalTimestamps

• Enumerations

  • ze_device_type_t

  • ze_device_property_flags_t

  • ze_device_module_flags_t

  • ze_device_fp_flags_t

  • ze_command_queue_group_property_flags_t

  • ze_device_memory_property_flags_t

  • ze_memory_access_cap_flags_t

  • ze_device_cache_property_flags_t

  • ze_device_p2p_property_flags_t

• Structures

  • ze_device_uuid_t

  • ze_device_properties_t

  • ze_device_thread_t

  • ze_device_compute_properties_t

  • ze_native_kernel_uuid_t

  • ze_device_module_properties_t

  • ze_command_queue_group_properties_t

  • ze_device_memory_properties_t

  • ze_device_memory_access_properties_t

  • ze_device_cache_properties_t

  • ze_device_image_properties_t

  • ze_device_external_memory_properties_t

  • ze_device_p2p_properties_t

Device Functions

zeDeviceGet

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGet(ze_driver_handle_t hDriver, uint32_t *pCount, ze_device_handle_t *phDevices)

Retrieves devices within a driver.

Parameters

• hDriver: [in] handle of the driver instance

• pCount: [in,out] pointer to the number of devices. if count is zero, then the driver shall update the value with the total number of devices available. if count is greater than the number of devices available, then the driver shall update the value with the correct number of devices available.

• phDevices: [in,out][optional][range(0, *pCount)] array of handle of devices. if count is less than the number of devices available, then driver shall only retrieve that number of devices.

• Multiple calls to this function will return identical device handles, in the same order.

• The number and order of handles returned from this function is affected by the ::ZE_AFFINITY_MASK and ::ZE_ENABLE_PCI_ID_DEVICE_ORDER environment variables.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDeviceGetSubDevices

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetSubDevices(ze_device_handle_t hDevice, uint32_t *pCount, ze_device_handle_t *phSubdevices)

Retrieves a sub-device from a device.

Parameters

• hDevice: [in] handle of the device object

• pCount: [in,out] pointer to the number of sub-devices. if count is zero, then the driver shall update the value with the total number of sub-devices available. if count is greater than the number of sub-devices available, then the driver shall update the value with the correct number of sub-devices available.

• phSubdevices: [in,out][optional][range(0, *pCount)] array of handle of sub-devices. if count is less than the number of sub-devices available, then driver shall only retrieve that number of sub-devices.

• Multiple calls to this function will return identical device handles, in the same order.

• The number of handles returned from this function is affected by the ::ZE_AFFINITY_MASK environment variable.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clCreateSubDevices

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDeviceGetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetProperties(ze_device_handle_t hDevice, ze_device_properties_t *pDeviceProperties)

Retrieves properties of the device.

Parameters

• hDevice: [in] handle of the device

• pDeviceProperties: [in,out] query result for device properties

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetDeviceInfo

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pDeviceProperties

zeDeviceGetComputeProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetComputeProperties(ze_device_handle_t hDevice, ze_device_compute_properties_t *pComputeProperties)

Retrieves compute properties of the device.

Parameters

• hDevice: [in] handle of the device

• pComputeProperties: [in,out] query result for compute properties

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetDeviceInfo

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pComputeProperties

zeDeviceGetModuleProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetModuleProperties(ze_device_handle_t hDevice, ze_device_module_properties_t *pModuleProperties)

Retrieves module properties of the device.

Parameters

• hDevice: [in] handle of the device

• pModuleProperties: [in,out] query result for module properties

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pModuleProperties

zeDeviceGetCommandQueueGroupProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetCommandQueueGroupProperties(ze_device_handle_t hDevice, uint32_t *pCount, ze_command_queue_group_properties_t *pCommandQueueGroupProperties)

Retrieves command queue group properties of the device.

Parameters

• hDevice: [in] handle of the device

• pCount: [in,out] pointer to the number of command queue group properties. if count is zero, then the driver shall update the value with the total number of command queue group properties available. if count is greater than the number of command queue group properties available, then the driver shall update the value with the correct number of command queue group properties available.

• pCommandQueueGroupProperties: [in,out][optional][range(0, *pCount)] array of query results for command queue group properties. if count is less than the number of command queue group properties available, then driver shall only retrieve that number of command queue group properties.

• Properties are reported for each physical command queue type supported by the device.

• Multiple calls to this function will return properties in the same order.

• The order in which the properties are returned defines the command queue group’s ordinal.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkGetPhysicalDeviceQueueFamilyProperties

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDeviceGetMemoryProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetMemoryProperties(ze_device_handle_t hDevice, uint32_t *pCount, ze_device_memory_properties_t *pMemProperties)

Retrieves local memory properties of the device.

Parameters

• hDevice: [in] handle of the device

• pCount: [in,out] pointer to the number of memory properties. if count is zero, then the driver shall update the value with the total number of memory properties available. if count is greater than the number of memory properties available, then the driver shall update the value with the correct number of memory properties available.

• pMemProperties: [in,out][optional][range(0, *pCount)] array of query results for memory properties. if count is less than the number of memory properties available, then driver shall only retrieve that number of memory properties.

• Properties are reported for each physical memory type supported by the device.

• Multiple calls to this function will return properties in the same order.

• The order in which the properties are returned defines the device’s local memory ordinal.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetDeviceInfo

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDeviceGetMemoryAccessProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetMemoryAccessProperties(ze_device_handle_t hDevice, ze_device_memory_access_properties_t *pMemAccessProperties)

Retrieves memory access properties of the device.

Parameters

• hDevice: [in] handle of the device

• pMemAccessProperties: [in,out] query result for memory access properties

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetDeviceInfo

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pMemAccessProperties

zeDeviceGetCacheProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetCacheProperties(ze_device_handle_t hDevice, uint32_t *pCount, ze_device_cache_properties_t *pCacheProperties)

Retrieves cache properties of the device.

Parameters

• hDevice: [in] handle of the device

• pCount: [in,out] pointer to the number of cache properties. if count is zero, then the driver shall update the value with the total number of cache properties available. if count is greater than the number of cache properties available, then the driver shall update the value with the correct number of cache properties available.

• pCacheProperties: [in,out][optional][range(0, *pCount)] array of query results for cache properties. if count is less than the number of cache properties available, then driver shall only retrieve that number of cache properties.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetDeviceInfo

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeDeviceGetImageProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetImageProperties(ze_device_handle_t hDevice, ze_device_image_properties_t *pImageProperties)

Retrieves image properties of the device.

Parameters

• hDevice: [in] handle of the device

• pImageProperties: [in,out] query result for image properties

• See zeImageGetProperties for format-specific capabilities.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pImageProperties

zeDeviceGetExternalMemoryProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetExternalMemoryProperties(ze_device_handle_t hDevice, ze_device_external_memory_properties_t *pExternalMemoryProperties)

Retrieves external memory import and export of the device.

Parameters

• hDevice: [in] handle of the device

• pExternalMemoryProperties: [in,out] query result for external memory properties

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pExternalMemoryProperties

zeDeviceGetP2PProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetP2PProperties(ze_device_handle_t hDevice, ze_device_handle_t hPeerDevice, ze_device_p2p_properties_t *pP2PProperties)

Retrieves peer-to-peer properties between one device and a peer devices.

Parameters

• hDevice: [in] handle of the device performing the access

• hPeerDevice: [in] handle of the peer device with the allocation

• pP2PProperties: [in,out] Peer-to-Peer properties between source and peer device

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

  • nullptr == hPeerDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pP2PProperties

zeDeviceCanAccessPeer

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceCanAccessPeer(ze_device_handle_t hDevice, ze_device_handle_t hPeerDevice, ze_bool_t *value)

Queries if one device can directly access peer device allocations.

Parameters

• hDevice: [in] handle of the device performing the access

• hPeerDevice: [in] handle of the peer device with the allocation

• value: [out] returned access capability

• Any device can access any other device within a node through a scale-up fabric.

• The following are conditions for CanAccessPeer query.

  • If both device and peer device are the same then return true.

  • If both sub-device and peer sub-device are the same then return true.

  • If both are sub-devices and share the same parent device then return true.

  • If both device and remote device are connected by a direct or indirect scale-up fabric or over PCIe (same root complex or shared PCIe switch) then true.

  • If both sub-device and remote parent device (and vice-versa) are connected by a direct or indirect scale-up fabric or over PCIe (same root complex or shared PCIe switch) then true.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

  • nullptr == hPeerDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == value

zeDeviceGetStatus

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetStatus(ze_device_handle_t hDevice)

Returns current status of the device.

Parameters

• hDevice: [in] handle of the device

• Once a device is reset, this call will update the OS handle attached to the device handle.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_SUCCESS

  • Device is available for use.

• ZE_RESULT_ERROR_DEVICE_LOST

  • Device is lost; must be reset for use.

zeDeviceGetGlobalTimestamps

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetGlobalTimestamps(ze_device_handle_t hDevice, uint64_t *hostTimestamp, uint64_t *deviceTimestamp)

Returns synchronized Host and device global timestamps.

Parameters

• hDevice: [in] handle of the device

• hostTimestamp: [out] value of the Host’s global timestamp that correlates with the Device’s global timestamp value

• deviceTimestamp: [out] value of the Device’s global timestamp that correlates with the Host’s global timestamp value

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == hostTimestamp

  • nullptr == deviceTimestamp

Device Enums

ze_device_type_t

enum ze_device_type_t

Supported device types.

Values:

ZE_DEVICE_TYPE_GPU = 1

Graphics Processing Unit.

ZE_DEVICE_TYPE_CPU = 2

Central Processing Unit.

ZE_DEVICE_TYPE_FPGA = 3

Field Programmable Gate Array.

ZE_DEVICE_TYPE_MCA = 4

Memory Copy Accelerator.

ZE_DEVICE_TYPE_FORCE_UINT32 = 0x7fffffff

ze_device_property_flags_t

enum ze_device_property_flag_t

Values:

ZE_DEVICE_PROPERTY_FLAG_INTEGRATED = ZE_BIT(0)

Device is integrated with the Host.

ZE_DEVICE_PROPERTY_FLAG_SUBDEVICE = ZE_BIT(1)

Device handle used for query represents a sub-device.

ZE_DEVICE_PROPERTY_FLAG_ECC = ZE_BIT(2)

Device supports error correction memory access.

ZE_DEVICE_PROPERTY_FLAG_ONDEMANDPAGING = ZE_BIT(3)

Device supports on-demand page-faulting.

ZE_DEVICE_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

ze_device_module_flags_t

enum ze_device_module_flag_t

Values:

ZE_DEVICE_MODULE_FLAG_FP16 = ZE_BIT(0)

Device supports 16-bit floating-point operations.

ZE_DEVICE_MODULE_FLAG_FP64 = ZE_BIT(1)

Device supports 64-bit floating-point operations.

ZE_DEVICE_MODULE_FLAG_INT64_ATOMICS = ZE_BIT(2)

Device supports 64-bit atomic operations.

ZE_DEVICE_MODULE_FLAG_DP4A = ZE_BIT(3)

Device supports four component dot product and accumulate operations.

ZE_DEVICE_MODULE_FLAG_FORCE_UINT32 = 0x7fffffff

ze_device_fp_flags_t

enum ze_device_fp_flag_t

Values:

ZE_DEVICE_FP_FLAG_DENORM = ZE_BIT(0)

Supports denorms.

ZE_DEVICE_FP_FLAG_INF_NAN = ZE_BIT(1)

Supports INF and quiet NaNs.

ZE_DEVICE_FP_FLAG_ROUND_TO_NEAREST = ZE_BIT(2)

Supports rounding to nearest even rounding mode.

ZE_DEVICE_FP_FLAG_ROUND_TO_ZERO = ZE_BIT(3)

Supports rounding to zero.

ZE_DEVICE_FP_FLAG_ROUND_TO_INF = ZE_BIT(4)

Supports rounding to both positive and negative INF.

ZE_DEVICE_FP_FLAG_FMA = ZE_BIT(5)

Supports IEEE754-2008 fused multiply-add.

ZE_DEVICE_FP_FLAG_ROUNDED_DIVIDE_SQRT = ZE_BIT(6)

operations.

Supports rounding as defined by IEEE754 for divide and sqrt

ZE_DEVICE_FP_FLAG_SOFT_FLOAT = ZE_BIT(7)

Uses software implementation for basic floating-point operations.

ZE_DEVICE_FP_FLAG_FORCE_UINT32 = 0x7fffffff

ze_command_queue_group_property_flags_t

enum ze_command_queue_group_property_flag_t

Values:

ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_COMPUTE = ZE_BIT(0)

Command queue group supports enqueing compute commands.

ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_COPY = ZE_BIT(1)

Command queue group supports enqueing copy commands.

ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_COOPERATIVE_KERNELS = ZE_BIT(2)

See zeCommandListAppendLaunchCooperativeKernel for more details.

Command queue group supports cooperative kernels.

ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_METRICS = ZE_BIT(3)

Command queue groups supports metric queries.

ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

ze_device_memory_property_flags_t

enum ze_device_memory_property_flag_t

Values:

ZE_DEVICE_MEMORY_PROPERTY_FLAG_TBD = ZE_BIT(0)

reserved for future use

ZE_DEVICE_MEMORY_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

ze_memory_access_cap_flags_t

enum ze_memory_access_cap_flag_t

Values:

ZE_MEMORY_ACCESS_CAP_FLAG_RW = ZE_BIT(0)

Supports load/store access.

ZE_MEMORY_ACCESS_CAP_FLAG_ATOMIC = ZE_BIT(1)

Supports atomic access.

ZE_MEMORY_ACCESS_CAP_FLAG_CONCURRENT = ZE_BIT(2)

Supports concurrent access.

ZE_MEMORY_ACCESS_CAP_FLAG_CONCURRENT_ATOMIC = ZE_BIT(3)

Supports concurrent atomic access.

ZE_MEMORY_ACCESS_CAP_FLAG_FORCE_UINT32 = 0x7fffffff

ze_device_cache_property_flags_t

enum ze_device_cache_property_flag_t

Values:

ZE_DEVICE_CACHE_PROPERTY_FLAG_USER_CONTROL = ZE_BIT(0)

Device support User Cache Control (i.e. SLM section vs Generic Cache)

ZE_DEVICE_CACHE_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

ze_device_p2p_property_flags_t

enum ze_device_p2p_property_flag_t

Values:

ZE_DEVICE_P2P_PROPERTY_FLAG_ACCESS = ZE_BIT(0)

Device supports access between peer devices.

ZE_DEVICE_P2P_PROPERTY_FLAG_ATOMICS = ZE_BIT(1)

Device supports atomics between peer devices.

ZE_DEVICE_P2P_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

Device Structures

ze_device_uuid_t

struct ze_device_uuid_t

Device universal unique id (UUID)

Public Members

uint8_t id[ZE_MAX_DEVICE_UUID_SIZE]

[out] opaque data representing a device UUID

ze_device_properties_t

struct ze_device_properties_t

Device properties queried using zeDeviceGetProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_device_type_t type

[out] generic device type

uint32_t vendorId

[out] vendor id from PCI configuration

uint32_t deviceId

[out] device id from PCI configuration

ze_device_property_flags_t flags

[out] 0 (none) or a valid combination of ze_device_property_flag_t

uint32_t subdeviceId

[out] sub-device id. Only valid if ZE_DEVICE_PROPERTY_FLAG_SUBDEVICE is set.

uint32_t coreClockRate

[out] Clock rate for device core.

uint64_t maxMemAllocSize

[out] Maximum memory allocation size.

uint32_t maxHardwareContexts

[out] Maximum number of logical hardware contexts.

uint32_t maxCommandQueuePriority

[out] Maximum priority for command queues. Higher value is higher priority.

uint32_t numThreadsPerEU

[out] Number of threads per EU.

uint32_t physicalEUSimdWidth

[out] The physical EU simd width.

uint32_t numEUsPerSubslice

[out] Number of EUs per sub-slice.

uint32_t numSubslicesPerSlice

[out] Number of sub-slices per slice.

uint32_t numSlices

[out] Number of slices.

uint64_t timerResolution

[out] Returns the resolution of device timer in cycles per second used for profiling, timestamps, etc.

uint32_t timestampValidBits

[out] Returns the number of valid bits in the timestamp value.

uint32_t kernelTimestampValidBits

[out] Returns the number of valid bits in the kernel timestamp values

ze_device_uuid_t uuid

[out] universal unique identifier. Note: Subdevices will have their own uuid.

char name[ZE_MAX_DEVICE_NAME]

[out] Device name

ze_device_thread_t

struct ze_device_thread_t

Device thread identifier.

Public Members

uint32_t slice

[in,out] the slice number. Must be UINT32_MAX (all) or less than ze_device_properties_t.numSlices.

uint32_t subslice

[in,out] the sub-slice number within its slice. Must be UINT32_MAX (all) or less than ze_device_properties_t.numSubslicesPerSlice.

uint32_t eu

[in,out] the EU number within its sub-slice. Must be UINT32_MAX (all) or less than ze_device_properties_t.numEUsPerSubslice.

uint32_t thread

[in,out] the thread number within its EU. Must be UINT32_MAX (all) or less than ze_device_properties_t.numThreadsPerEU.

ze_device_compute_properties_t

struct ze_device_compute_properties_t

Device compute properties queried using zeDeviceGetComputeProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

uint32_t maxTotalGroupSize

[out] Maximum items per compute group. (groupSizeX * groupSizeY * groupSizeZ) <= maxTotalGroupSize

uint32_t maxGroupSizeX

[out] Maximum items for X dimension in group

uint32_t maxGroupSizeY

[out] Maximum items for Y dimension in group

uint32_t maxGroupSizeZ

[out] Maximum items for Z dimension in group

uint32_t maxGroupCountX

[out] Maximum groups that can be launched for x dimension

uint32_t maxGroupCountY

[out] Maximum groups that can be launched for y dimension

uint32_t maxGroupCountZ

[out] Maximum groups that can be launched for z dimension

uint32_t maxSharedLocalMemory

[out] Maximum shared local memory per group.

uint32_t numSubGroupSizes

[out] Number of subgroup sizes supported. This indicates number of entries in subGroupSizes.

uint32_t subGroupSizes[ZE_SUBGROUPSIZE_COUNT]

[out] Size group sizes supported.

ze_native_kernel_uuid_t

struct ze_native_kernel_uuid_t

Native kernel universal unique id (UUID)

Public Members

uint8_t id[ZE_MAX_NATIVE_KERNEL_UUID_SIZE]

[out] opaque data representing a native kernel UUID

ze_device_module_properties_t

struct ze_device_module_properties_t

Device module properties queried using zeDeviceGetModuleProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

uint32_t spirvVersionSupported

[out] Maximum supported SPIR-V version. Returns zero if SPIR-V is not supported. Contains major and minor attributes, use ZE_MAJOR_VERSION and ZE_MINOR_VERSION.

ze_device_module_flags_t flags

[out] 0 or a valid combination of ze_device_module_flag_t

ze_device_fp_flags_t fp16flags

[out] Capabilities for half-precision floating-point operations. returns 0 (if ZE_DEVICE_MODULE_FLAG_FP16 is not set) or a combination of ze_device_fp_flag_t.

ze_device_fp_flags_t fp32flags

[out] Capabilities for single-precision floating-point operations. returns a combination of ze_device_fp_flag_t.

ze_device_fp_flags_t fp64flags

[out] Capabilities for double-precision floating-point operations. returns 0 (if ZE_DEVICE_MODULE_FLAG_FP64 is not set) or a combination of ze_device_fp_flag_t.

uint32_t maxArgumentsSize

[out] Maximum kernel argument size that is supported.

uint32_t printfBufferSize

[out] Maximum size of internal buffer that holds output of printf calls from kernel.

ze_native_kernel_uuid_t nativeKernelSupported

[out] Compatibility UUID of supported native kernel. UUID may or may not be the same across driver release, devices, or operating systems. Application is responsible for ensuring UUID matches before creating module using previously created native kernel.

ze_command_queue_group_properties_t

struct ze_command_queue_group_properties_t

Command queue group properties queried using zeDeviceGetCommandQueueGroupProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_command_queue_group_property_flags_t flags

[out] 0 (none) or a valid combination of ze_command_queue_group_property_flag_t

size_t maxMemoryFillPatternSize

[out] maximum pattern_size supported by command queue group. See zeCommandListAppendMemoryFill for more details.

uint32_t numQueues

[out] the number of physical engines within the group.

ze_device_memory_properties_t

struct ze_device_memory_properties_t

Device local memory properties queried using zeDeviceGetMemoryProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_device_memory_property_flags_t flags

[out] 0 (none) or a valid combination of ze_device_memory_property_flag_t

uint32_t maxClockRate

[out] Maximum clock rate for device memory.

uint32_t maxBusWidth

[out] Maximum bus width between device and memory.

uint64_t totalSize

[out] Total memory size in bytes that is available to the device.

char name[ZE_MAX_DEVICE_NAME]

[out] Memory name

ze_device_memory_access_properties_t

struct ze_device_memory_access_properties_t

Device memory access properties queried using zeDeviceGetMemoryAccessProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_memory_access_cap_flags_t hostAllocCapabilities

returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

[out] host memory capabilities.

ze_memory_access_cap_flags_t deviceAllocCapabilities

returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

[out] device memory capabilities.

ze_memory_access_cap_flags_t sharedSingleDeviceAllocCapabilities

returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

[out] shared, single-device memory capabilities.

ze_memory_access_cap_flags_t sharedCrossDeviceAllocCapabilities

returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

[out] shared, cross-device memory capabilities.

ze_memory_access_cap_flags_t sharedSystemAllocCapabilities

returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

[out] shared, system memory capabilities.

ze_device_cache_properties_t

struct ze_device_cache_properties_t

Device cache properties queried using zeDeviceGetCacheProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_device_cache_property_flags_t flags

[out] 0 (none) or a valid combination of ze_device_cache_property_flag_t

size_t cacheSize

[out] Per-cache size, in bytes

ze_device_image_properties_t

struct ze_device_image_properties_t

Device image properties queried using zeDeviceGetImageProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

uint32_t maxImageDims1D

[out] Maximum image dimensions for 1D resources. if 0, then 1D images are unsupported.

uint32_t maxImageDims2D

[out] Maximum image dimensions for 2D resources. if 0, then 2D images are unsupported.

uint32_t maxImageDims3D

[out] Maximum image dimensions for 3D resources. if 0, then 3D images are unsupported.

uint64_t maxImageBufferSize

[out] Maximum image buffer size in bytes. if 0, then buffer images are unsupported.

uint32_t maxImageArraySlices

[out] Maximum image array slices. if 0, then image arrays are unsupported.

uint32_t maxSamplers

[out] Max samplers that can be used in kernel. if 0, then sampling is unsupported.

uint32_t maxReadImageArgs

[out] Returns the maximum number of simultaneous image objects that can be read from by a kernel. if 0, then reading images is unsupported.

uint32_t maxWriteImageArgs

[out] Returns the maximum number of simultaneous image objects that can be written to by a kernel. if 0, then writing images is unsupported.

ze_device_external_memory_properties_t

struct ze_device_external_memory_properties_t

Device external memory import and export properties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_external_memory_type_flags_t memoryAllocationImportTypes

[out] Supported external memory import types for memory allocations.

ze_external_memory_type_flags_t memoryAllocationExportTypes

[out] Supported external memory export types for memory allocations.

ze_external_memory_type_flags_t imageImportTypes

[out] Supported external memory import types for images.

ze_external_memory_type_flags_t imageExportTypes

[out] Supported external memory export types for images.

ze_device_p2p_properties_t

struct ze_device_p2p_properties_t

Device peer-to-peer properties queried using zeDeviceGetP2PProperties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_device_p2p_property_flags_t flags

[out] 0 (none) or a valid combination of ze_device_p2p_property_flag_t

Context

• Functions

  • zeContextCreate

  • zeContextCreateEx

  • zeContextDestroy

  • zeContextGetStatus

• Enumerations

  • ze_context_flags_t

• Structures

  • ze_context_desc_t

Context Functions

zeContextCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextCreate(ze_driver_handle_t hDriver, const ze_context_desc_t *desc, ze_context_handle_t *phContext)

Creates a context for the driver.

Parameters

• hDriver: [in] handle of the driver object

• desc: [in] pointer to context descriptor

• phContext: [out] pointer to handle of context object created

• The application must only use the context for the driver which was provided during creation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phContext

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < desc->flags

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeContextCreateEx

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextCreateEx(ze_driver_handle_t hDriver, const ze_context_desc_t *desc, uint32_t numDevices, ze_device_handle_t *phDevices, ze_context_handle_t *phContext)

Creates a context for the driver.

Parameters

• hDriver: [in] handle of the driver object

• desc: [in] pointer to context descriptor

• numDevices: [in][optional] number of device handles; must be 0 if `nullptr == phDevices`

• phDevices: [in][optional][range(0, numDevices)] array of device handles which context has visibility. if nullptr, then all devices supported by the driver instance are visible to the context. otherwise, context only has visibility to devices in this array.

• phContext: [out] pointer to handle of context object created

• The application must only use the context for the driver which was provided during creation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phContext

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < desc->flags

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phDevices) && (0 < numDevices)

zeContextDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextDestroy(ze_context_handle_t hContext)

Destroys a context.

Parameters

• hContext: [in][release] handle of context object to destroy

• The application must ensure the device is not currently referencing the context before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this context.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeContextGetStatus

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextGetStatus(ze_context_handle_t hContext)

Returns current status of the context.

Parameters

• hContext: [in] handle of context object

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_SUCCESS

  • Context is available for use.

• ZE_RESULT_ERROR_DEVICE_LOST

  • Context is invalid; due to device lost or reset.

Context Enums

ze_context_flags_t

enum ze_context_flag_t

Values:

ZE_CONTEXT_FLAG_TBD = ZE_BIT(0)

reserved for future use

ZE_CONTEXT_FLAG_FORCE_UINT32 = 0x7fffffff

Context Structures

ze_context_desc_t

struct ze_context_desc_t

Context descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_context_flags_t flags

[in] creation flags. must be 0 (default) or a valid combination of ze_context_flag_t; default behavior may use implicit driver-based heuristics.

Cmdqueue

• Functions

  • zeCommandQueueCreate

  • zeCommandQueueDestroy

  • zeCommandQueueExecuteCommandLists

  • zeCommandQueueSynchronize

• Enumerations

  • ze_command_queue_flags_t

  • ze_command_queue_mode_t

  • ze_command_queue_priority_t

• Structures

  • ze_command_queue_desc_t

Cmdqueue Functions

zeCommandQueueCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_command_queue_desc_t *desc, ze_command_queue_handle_t *phCommandQueue)

Creates a command queue on the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device object

• desc: [in] pointer to command queue descriptor

• phCommandQueue: [out] pointer to handle of command queue object created

• A command queue represents a logical input stream to the device, tied to a physical input stream.

• The application must only use the command queue for the device, or its sub-devices, which was provided during creation.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clCreateCommandQueue

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phCommandQueue

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < desc->flags

  • ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS < desc->mode

  • ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH < desc->priority

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeCommandQueueDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueDestroy(ze_command_queue_handle_t hCommandQueue)

Destroys a command queue.

Parameters

• hCommandQueue: [in][release] handle of command queue object to destroy

• The application must destroy all fence handles created from the command queue before destroying the command queue itself

• The application must ensure the device is not currently referencing the command queue before it is deleted

• The implementation of this function may immediately free all Host and Device allocations associated with this command queue

• The application must not call this function from simultaneous threads with the same command queue handle.

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

Remark

Analogues

• clReleaseCommandQueue

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandQueue

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeCommandQueueExecuteCommandLists

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueExecuteCommandLists(ze_command_queue_handle_t hCommandQueue, uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists, ze_fence_handle_t hFence)

Executes a command list in a command queue.

Parameters

• hCommandQueue: [in] handle of the command queue

• numCommandLists: [in] number of command lists to execute

• phCommandLists: [in][range(0, numCommandLists)] list of handles of the command lists to execute

• hFence: [in][optional] handle of the fence to signal on completion

• The command lists are submitted to the device in the order they are received, whether from multiple calls (on the same or different threads) or a single call with multiple command lists.

• The application must ensure the command lists are accessible by the device on which the command queue was created.

• The application must ensure the command lists are not currently referencing the command list since the implementation is allowed to modify the contents of the command list for submission.

• The application must only execute command lists created with an identical command queue group ordinal to the command queue.

• The application must use a fence created using the same command queue.

• The application must ensure the command queue, command list and fence were created on the same context.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkQueueSubmit

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandQueue

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phCommandLists

• ZE_RESULT_ERROR_INVALID_SIZE

  • 0 == numCommandLists

• ZE_RESULT_ERROR_INVALID_COMMAND_LIST_TYPE

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeCommandQueueSynchronize

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueSynchronize(ze_command_queue_handle_t hCommandQueue, uint64_t timeout)

Synchronizes a command queue by waiting on the host.

Parameters

• hCommandQueue: [in] handle of the command queue

• timeout: [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then immediately returns the status of the command queue; if UINT64_MAX, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandQueue

• ZE_RESULT_NOT_READY

  • timeout expired

Cmdqueue Enums

ze_command_queue_flags_t

enum ze_command_queue_flag_t

Values:

ZE_COMMAND_QUEUE_FLAG_EXPLICIT_ONLY = ZE_BIT(0)

command queue should be optimized for submission to a single device engine. driver must disable any implicit optimizations for distributing work across multiple engines. this flag should be used when applications want full control over multi-engine submission and scheduling.

ZE_COMMAND_QUEUE_FLAG_FORCE_UINT32 = 0x7fffffff

ze_command_queue_mode_t

enum ze_command_queue_mode_t

Supported command queue modes.

Values:

ZE_COMMAND_QUEUE_MODE_DEFAULT = 0

implicit default behavior; uses driver-based heuristics

ZE_COMMAND_QUEUE_MODE_SYNCHRONOUS = 1

Device execution always completes immediately on execute; Host thread is blocked using wait on implicit synchronization object

ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS = 2

Device execution is scheduled and will complete in future; explicit synchronization object must be used to determine completeness

ZE_COMMAND_QUEUE_MODE_FORCE_UINT32 = 0x7fffffff

ze_command_queue_priority_t

enum ze_command_queue_priority_t

Supported command queue priorities.

Values:

ZE_COMMAND_QUEUE_PRIORITY_NORMAL = 0

[default] normal priority

ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_LOW = 1

lower priority than normal

ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH = 2

higher priority than normal

ZE_COMMAND_QUEUE_PRIORITY_FORCE_UINT32 = 0x7fffffff

Cmdqueue Structures

ze_command_queue_desc_t

struct ze_command_queue_desc_t

Command Queue descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

uint32_t ordinal

[in] command queue group ordinal

uint32_t index

[in] command queue index within the group; must be zero if ZE_COMMAND_QUEUE_FLAG_EXPLICIT_ONLY is not set

ze_command_queue_flags_t flags

[in] usage flags. must be 0 (default) or a valid combination of ze_command_queue_flag_t; default behavior may use implicit driver-based heuristics to balance latency and throughput.

ze_command_queue_mode_t mode

[in] operation mode

ze_command_queue_priority_t priority

[in] priority

Cmdlist

• Functions

  • zeCommandListCreate

  • zeCommandListCreateImmediate

  • zeCommandListDestroy

  • zeCommandListClose

  • zeCommandListReset

  • zeCommandListAppendWriteGlobalTimestamp

• Enumerations

  • ze_command_list_flags_t

• Structures

  • ze_command_list_desc_t

Cmdlist Functions

zeCommandListCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_command_list_desc_t *desc, ze_command_list_handle_t *phCommandList)

Creates a command list on the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device object

• desc: [in] pointer to command list descriptor

• phCommandList: [out] pointer to handle of command list object created

• A command list represents a sequence of commands for execution on a command queue.

• The command list is created in the ‘open’ state.

• The application must only use the command list for the device, or its sub-devices, which was provided during creation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phCommandList

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7 < desc->flags

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeCommandListCreateImmediate

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListCreateImmediate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_command_queue_desc_t *altdesc, ze_command_list_handle_t *phCommandList)

Creates an immediate command list on the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device object

• altdesc: [in] pointer to command queue descriptor

• phCommandList: [out] pointer to handle of command list object created

• An immediate command list is used for low-latency submission of commands.

• An immediate command list creates an implicit command queue.

• The command list is created in the ‘open’ state and never needs to be closed.

• The application must only use the command list for the device, or its sub-devices, which was provided during creation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == altdesc

  • nullptr == phCommandList

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < altdesc->flags

  • ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS < altdesc->mode

  • ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH < altdesc->priority

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeCommandListDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListDestroy(ze_command_list_handle_t hCommandList)

Destroys a command list.

Parameters

• hCommandList: [in][release] handle of command list object to destroy

• The application must ensure the device is not currently referencing the command list before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this command list.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeCommandListClose

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListClose(ze_command_list_handle_t hCommandList)

Closes a command list; ready to be executed by a command queue.

Parameters

• hCommandList: [in] handle of command list object to close

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

zeCommandListReset

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListReset(ze_command_list_handle_t hCommandList)

Reset a command list to initial (empty) state; ready for appending commands.

Parameters

• hCommandList: [in] handle of command list object to reset

• The application must ensure the device is not currently referencing the command list before it is reset

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

zeCommandListAppendWriteGlobalTimestamp

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendWriteGlobalTimestamp(ze_command_list_handle_t hCommandList, uint64_t *dstptr, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Appends a memory write of the device’s global timestamp value into a command list.

Parameters

• hCommandList: [in] handle of the command list

• dstptr: [in,out] pointer to memory where timestamp value will be written; must be 8byte-aligned.

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before executing query; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing query

• The application must ensure the events are accessible by the device on which the command list was created.

• The timestamp frequency can be queried from ze_device_properties_t.timerResolution.

• The number of valid bits in the timestamp value can be queried from ze_device_properties_t.timestampValidBits.

• The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.

• The application must ensure the command list and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == dstptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

Cmdlist Enums

ze_command_list_flags_t

enum ze_command_list_flag_t

Values:

ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING = ZE_BIT(0)

driver may reorder commands (e.g., kernels, copies) between barriers and synchronization primitives. using this flag may increase Host overhead of zeCommandListClose. therefore, this flag should not be set for low-latency usage-models.

ZE_COMMAND_LIST_FLAG_MAXIMIZE_THROUGHPUT = ZE_BIT(1)

driver may perform additional optimizations that increase execution throughput. using this flag may increase Host overhead of zeCommandListClose and zeCommandQueueExecuteCommandLists. therefore, this flag should not be set for low-latency usage-models.

ZE_COMMAND_LIST_FLAG_EXPLICIT_ONLY = ZE_BIT(2)

command list should be optimized for submission to a single command queue and device engine. driver must disable any implicit optimizations for distributing work across multiple engines. this flag should be used when applications want full control over multi-engine submission and scheduling.

ZE_COMMAND_LIST_FLAG_FORCE_UINT32 = 0x7fffffff

Cmdlist Structures

ze_command_list_desc_t

struct ze_command_list_desc_t

Command List descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

uint32_t commandQueueGroupOrdinal

[in] command queue group ordinal to which this command list will be submitted

ze_command_list_flags_t flags

[in] usage flags. must be 0 (default) or a valid combination of ze_command_list_flag_t; default behavior may use implicit driver-based heuristics to balance latency and throughput.

Barrier

• Functions

  • zeCommandListAppendBarrier

  • zeCommandListAppendMemoryRangesBarrier

  • zeContextSystemBarrier

Barrier Functions

zeCommandListAppendBarrier

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendBarrier(ze_command_list_handle_t hCommandList, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Appends an execution and global memory barrier into a command list.

Parameters

• hCommandList: [in] handle of the command list

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before executing barrier; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing barrier

• The application must ensure the events are accessible by the device on which the command list was created.

• If numWaitEvents is zero, then all previous commands are completed prior to the execution of the barrier.

• If numWaitEvents is non-zero, then then all phWaitEvents must be signaled prior to the execution of the barrier.

• This command blocks all following commands from beginning until the execution of the barrier completes.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• vkCmdPipelineBarrier

• clEnqueueBarrierWithWaitList

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendMemoryRangesBarrier

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryRangesBarrier(ze_command_list_handle_t hCommandList, uint32_t numRanges, const size_t *pRangeSizes, const void **pRanges, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Appends a global memory ranges barrier into a command list.

Parameters

• hCommandList: [in] handle of the command list

• numRanges: [in] number of memory ranges

• pRangeSizes: [in][range(0, numRanges)] array of sizes of memory range

• pRanges: [in][range(0, numRanges)] array of memory ranges

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before executing barrier; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing barrier

• The application must ensure the events are accessible by the device on which the command list was created.

• If numWaitEvents is zero, then all previous commands are completed prior to the execution of the barrier.

• If numWaitEvents is non-zero, then then all phWaitEvents must be signaled prior to the execution of the barrier.

• This command blocks all following commands from beginning until the execution of the barrier completes.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pRangeSizes

  • nullptr == pRanges

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeContextSystemBarrier

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextSystemBarrier(ze_context_handle_t hContext, ze_device_handle_t hDevice)

Ensures in-bound writes to the device are globally observable.

Parameters

• hContext: [in] handle of context object

• hDevice: [in] handle of the device

• This is a special-case system level barrier that can be used to ensure global observability of writes; typically needed after a producer (e.g., NIC) performs direct writes to the device’s memory (e.g., Direct RDMA writes). This is typically required when the memory corresponding to the writes is subsequently accessed from a remote device.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

Copy

• Functions

  • zeCommandListAppendMemoryCopy

  • zeCommandListAppendMemoryFill

  • zeCommandListAppendMemoryCopyRegion

  • zeCommandListAppendMemoryCopyFromContext

  • zeCommandListAppendImageCopy

  • zeCommandListAppendImageCopyRegion

  • zeCommandListAppendImageCopyToMemory

  • zeCommandListAppendImageCopyFromMemory

  • zeCommandListAppendMemoryPrefetch

  • zeCommandListAppendMemAdvise

• Enumerations

  • ze_memory_advice_t

• Structures

  • ze_copy_region_t

  • ze_image_region_t

Copy Functions

zeCommandListAppendMemoryCopy

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryCopy(ze_command_list_handle_t hCommandList, void *dstptr, const void *srcptr, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies host, device, or shared memory.

Parameters

• hCommandList: [in] handle of command list

• dstptr: [in] pointer to destination memory to copy to

• srcptr: [in] pointer to source memory to copy from

• size: [in] size in bytes to copy

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

• The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must ensure the command list and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clEnqueueCopyBuffer

• clEnqueueReadBuffer

• clEnqueueWriteBuffer

• clEnqueueSVMMemcpy

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == dstptr

  • nullptr == srcptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendMemoryFill

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryFill(ze_command_list_handle_t hCommandList, void *ptr, const void *pattern, size_t pattern_size, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Initializes host, device, or shared memory.

Parameters

• hCommandList: [in] handle of command list

• ptr: [in] pointer to memory to initialize

• pattern: [in] pointer to value to initialize memory to

• pattern_size: [in] size in bytes of the value to initialize memory to

• size: [in] size in bytes to initialize

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.

• The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.

• The value to initialize memory to is described by the pattern and the pattern size.

• The pattern size must be a power-of-two and less than ze_command_queue_group_properties_t.maxMemoryFillPatternSize.

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must enusre the command list and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clEnqueueFillBuffer

• clEnqueueSVMMemFill

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

  • nullptr == pattern

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendMemoryCopyRegion

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryCopyRegion(ze_command_list_handle_t hCommandList, void *dstptr, const ze_copy_region_t *dstRegion, uint32_t dstPitch, uint32_t dstSlicePitch, const void *srcptr, const ze_copy_region_t *srcRegion, uint32_t srcPitch, uint32_t srcSlicePitch, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies a region from a 2D or 3D array of host, device, or shared memory.

Parameters

• hCommandList: [in] handle of command list

• dstptr: [in] pointer to destination memory to copy to

• dstRegion: [in] pointer to destination region to copy to

• dstPitch: [in] destination pitch in bytes

• dstSlicePitch: [in] destination slice pitch in bytes. This is required for 3D region copies where ze_copy_region_t.depth is not 0, otherwise it’s ignored.

• srcptr: [in] pointer to source memory to copy from

• srcRegion: [in] pointer to source region to copy from

• srcPitch: [in] source pitch in bytes

• srcSlicePitch: [in] source slice pitch in bytes. This is required for 3D region copies where ze_copy_region_t.depth is not 0, otherwise it’s ignored.

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

• The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

• The region width, height, and depth for both src and dst must be same. The origins can be different.

• The src and dst regions cannot be overlapping.

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must ensure the command list and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == dstptr

  • nullptr == dstRegion

  • nullptr == srcptr

  • nullptr == srcRegion

• ZE_RESULT_ERROR_OVERLAPPING_REGIONS

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendMemoryCopyFromContext

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryCopyFromContext(ze_command_list_handle_t hCommandList, void *dstptr, ze_context_handle_t hContextSrc, const void *srcptr, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies host, device, or shared memory from another context.

Parameters

• hCommandList: [in] handle of command list

• dstptr: [in] pointer to destination memory to copy to

• hContextSrc: [in] handle of source context object

• srcptr: [in] pointer to source memory to copy from

• size: [in] size in bytes to copy

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The current active and source context must be from the same driver.

• The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

• The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must ensure the command list and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hContextSrc

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == dstptr

  • nullptr == srcptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendImageCopy

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopy(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, ze_image_handle_t hSrcImage, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies an image.

Parameters

• hCommandList: [in] handle of command list

• hDstImage: [in] handle of destination image to copy to

• hSrcImage: [in] handle of source image to copy from

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the image and events are accessible by the device on which the command list was created.

• The application must ensure the image format descriptors for both source and destination images are the same.

• The application must ensure the command list, images and events were created on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clEnqueueCopyImage

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hDstImage

  • nullptr == hSrcImage

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendImageCopyRegion

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyRegion(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, ze_image_handle_t hSrcImage, const ze_image_region_t *pDstRegion, const ze_image_region_t *pSrcRegion, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies a region of an image to another image.

Parameters

• hCommandList: [in] handle of command list

• hDstImage: [in] handle of destination image to copy to

• hSrcImage: [in] handle of source image to copy from

• pDstRegion: [in][optional] destination region descriptor

• pSrcRegion: [in][optional] source region descriptor

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the image and events are accessible by the device on which the command list was created.

• The region width and height for both src and dst must be same. The origins can be different.

• The src and dst regions cannot be overlapping.

• The application must ensure the image format descriptors for both source and destination images are the same.

• The application must ensure the command list, images and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hDstImage

  • nullptr == hSrcImage

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_OVERLAPPING_REGIONS

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendImageCopyToMemory

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyToMemory(ze_command_list_handle_t hCommandList, void *dstptr, ze_image_handle_t hSrcImage, const ze_image_region_t *pSrcRegion, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies from an image to device or shared memory.

Parameters

• hCommandList: [in] handle of command list

• dstptr: [in] pointer to destination memory to copy to

• hSrcImage: [in] handle of source image to copy from

• pSrcRegion: [in][optional] source region descriptor

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.

• The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.

• The application must ensure the image and events are accessible by the device on which the command list was created.

• The application must ensure the image format descriptor for the source image is not a media format.

• The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clEnqueueReadImage

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hSrcImage

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == dstptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendImageCopyFromMemory

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyFromMemory(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, const void *srcptr, const ze_image_region_t *pDstRegion, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Copies to an image from device or shared memory.

Parameters

• hCommandList: [in] handle of command list

• hDstImage: [in] handle of destination image to copy to

• srcptr: [in] pointer to source memory to copy from

• pDstRegion: [in][optional] destination region descriptor

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the memory pointed to by srcptr is accessible by the device on which the command list was created.

• The implementation must not access the memory pointed to by srcptr as it is free to be modified by either the Host or device up until execution.

• The application must ensure the image and events are accessible by the device on which the command list was created.

• The application must ensure the image format descriptor for the destination image is not a media format.

• The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clEnqueueWriteImage

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hDstImage

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == srcptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendMemoryPrefetch

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryPrefetch(ze_command_list_handle_t hCommandList, const void *ptr, size_t size)

Asynchronously prefetches shared memory to the device associated with the specified command list.

Parameters

• hCommandList: [in] handle of command list

• ptr: [in] pointer to start of the memory range to prefetch

• size: [in] size in bytes of the memory range to prefetch

• This is a hint to improve performance only and is not required for correctness.

• Only prefetching to the device associated with the specified command list is supported. Prefetching to the host or to a peer device is not supported.

• Prefetching may not be supported for all allocation types for all devices. If memory prefetching is not supported for the specified memory range the prefetch hint may be ignored.

• Prefetching may only be 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.

• The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.

• The application must ensure the command list was created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clEnqueueSVMMigrateMem

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

zeCommandListAppendMemAdvise

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemAdvise(ze_command_list_handle_t hCommandList, ze_device_handle_t hDevice, const void *ptr, size_t size, ze_memory_advice_t advice)

Provides advice about the use of a shared memory range.

Parameters

• hCommandList: [in] handle of command list

• 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

• advice: [in] Memory advice for the memory range

• Memory advice is a performance hint only and is not required for functional correctness.

• Memory advice can be used to override driver heuristics to explicitly control shared memory behavior.

• Not all memory advice hints may be supported for all allocation types for all devices. If a memory advice hint is not supported by the device it will be ignored.

• Memory advice may only be 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.

• The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.

• The application must ensure the command list was created, and memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle, and the memory was allocated.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZE_MEMORY_ADVICE_BIAS_UNCACHED < advice

Copy Enums

ze_memory_advice_t

enum ze_memory_advice_t

Supported memory advice hints.

Values:

ZE_MEMORY_ADVICE_SET_READ_MOSTLY = 0

hint that memory will be read from frequently and written to rarely

ZE_MEMORY_ADVICE_CLEAR_READ_MOSTLY = 1

removes the affect of ZE_MEMORY_ADVICE_SET_READ_MOSTLY

ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION = 2

hint that the preferred memory location is the specified device

ZE_MEMORY_ADVICE_CLEAR_PREFERRED_LOCATION = 3

removes the affect of ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION

ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY = 4

hints that memory will mostly be accessed non-atomically

ZE_MEMORY_ADVICE_CLEAR_NON_ATOMIC_MOSTLY = 5

removes the affect of ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY

ZE_MEMORY_ADVICE_BIAS_CACHED = 6

hints that memory should be cached

ZE_MEMORY_ADVICE_BIAS_UNCACHED = 7

hints that memory should be not be cached

ZE_MEMORY_ADVICE_FORCE_UINT32 = 0x7fffffff

Copy Structures

ze_copy_region_t

struct ze_copy_region_t

Copy region descriptor.

Public Members

uint32_t originX

[in] The origin x offset for region in bytes

uint32_t originY

[in] The origin y offset for region in rows

uint32_t originZ

[in] The origin z offset for region in slices

uint32_t width

[in] The region width relative to origin in bytes

uint32_t height

[in] The region height relative to origin in rows

uint32_t depth

[in] The region depth relative to origin in slices. Set this to 0 for 2D copy.

ze_image_region_t

struct ze_image_region_t

Region descriptor.

Public Members

uint32_t originX

[in] The origin x offset for region in pixels

uint32_t originY

[in] The origin y offset for region in pixels

uint32_t originZ

[in] The origin z offset for region in pixels

uint32_t width

[in] The region width relative to origin in pixels

uint32_t height

[in] The region height relative to origin in pixels

uint32_t depth

[in] The region depth relative to origin. For 1D or 2D images, set this to 1.

Event

• Functions

  • zeEventPoolCreate

  • zeEventPoolDestroy

  • zeEventCreate

  • zeEventDestroy

  • zeEventPoolGetIpcHandle

  • zeEventPoolOpenIpcHandle

  • zeEventPoolCloseIpcHandle

  • zeCommandListAppendSignalEvent

  • zeCommandListAppendWaitOnEvents

  • zeEventHostSignal

  • zeEventHostSynchronize

  • zeEventQueryStatus

  • zeCommandListAppendEventReset

  • zeEventHostReset

  • zeEventQueryKernelTimestamp

  • zeCommandListAppendQueryKernelTimestamps

• Enumerations

  • ze_event_pool_flags_t

  • ze_event_scope_flags_t

• Structures

  • ze_event_pool_desc_t

  • ze_event_desc_t

  • ze_kernel_timestamp_data_t

  • ze_kernel_timestamp_result_t

Event Functions

zeEventPoolCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolCreate(ze_context_handle_t hContext, const ze_event_pool_desc_t *desc, uint32_t numDevices, ze_device_handle_t *phDevices, ze_event_pool_handle_t *phEventPool)

Creates a pool of events on the context.

Parameters

• hContext: [in] handle of the context object

• desc: [in] pointer to event pool descriptor

• numDevices: [in][optional] number of device handles; must be 0 if `nullptr == phDevices`

• phDevices: [in][optional][range(0, numDevices)] array of device handles which have visibility to the event pool. if nullptr, then event pool is visible to all devices supported by the driver instance.

• phEventPool: [out] pointer handle of event pool object created

• The application must only use events within the pool for the device(s), or their sub-devices, which were provided during creation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phEventPool

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7 < desc->flags

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_SIZE

  • 0 == desc->count

  • (nullptr == phDevices) && (0 < numDevices)

zeEventPoolDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolDestroy(ze_event_pool_handle_t hEventPool)

Deletes an event pool object.

Parameters

• hEventPool: [in][release] handle of event pool object to destroy

• The application must destroy all event handles created from the pool before destroying the pool itself.

• The application must ensure the device is not currently referencing the any event within the pool before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this event pool.

• The application must not call this function from simultaneous threads with the same event pool handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEventPool

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeEventCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCreate(ze_event_pool_handle_t hEventPool, const ze_event_desc_t *desc, ze_event_handle_t *phEvent)

Creates an event from the pool.

Parameters

• hEventPool: [in] handle of the event pool

• desc: [in] pointer to event descriptor

• phEvent: [out] pointer to handle of event object created

• An event is used to communicate fine-grain host-to-device, device-to-host or device-to-device dependencies have completed.

• The application must ensure the location in the pool is not being used by another event.

• The application must not call this function from simultaneous threads with the same event pool handle.

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

Remark

Analogues

• clCreateUserEvent

• vkCreateEvent

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEventPool

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phEvent

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7 < desc->signal

  • 0x7 < desc->wait

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

zeEventDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventDestroy(ze_event_handle_t hEvent)

Deletes an event object.

Parameters

• hEvent: [in][release] handle of event object to destroy

• The application must ensure the device is not currently referencing the event before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this event.

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

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

Remark

Analogues

• clReleaseEvent

• vkDestroyEvent

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEvent

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeEventPoolGetIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolGetIpcHandle(ze_event_pool_handle_t hEventPool, ze_ipc_event_pool_handle_t *phIpc)

Gets an IPC event pool handle for the specified event handle that can be shared with another process.

Parameters

• hEventPool: [in] handle of event pool object

• phIpc: [out] Returned IPC event handle

• Event pool must have been created with ZE_EVENT_POOL_FLAG_IPC.

• The application may call this function from simultaneous threads.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEventPool

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phIpc

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeEventPoolOpenIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolOpenIpcHandle(ze_context_handle_t hContext, ze_ipc_event_pool_handle_t hIpc, ze_event_pool_handle_t *phEventPool)

Opens an IPC event pool handle to retrieve an event pool handle from another process.

Parameters

• hContext: [in] handle of the context object to associate with the IPC event pool handle

• hIpc: [in] IPC event pool handle

• phEventPool: [out] pointer handle of event pool object created

• Multiple calls to this function with the same IPC handle will return unique event pool handles.

• The event handle in this process should not be freed with zeEventPoolDestroy, but rather with zeEventPoolCloseIpcHandle.

• The application may call this function from simultaneous threads.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phEventPool

zeEventPoolCloseIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolCloseIpcHandle(ze_event_pool_handle_t hEventPool)

Closes an IPC event handle in the current process.

Parameters

• hEventPool: [in][release] handle of event pool object

• Closes an IPC event handle by destroying events that were opened in this process using zeEventPoolOpenIpcHandle.

• The application must not call this function from simultaneous threads with the same event pool handle.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEventPool

zeCommandListAppendSignalEvent

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendSignalEvent(ze_command_list_handle_t hCommandList, ze_event_handle_t hEvent)

Appends a signal of the event from the device into a command list.

Parameters

• hCommandList: [in] handle of the command list

• hEvent: [in] handle of the event

• The application must ensure the events are accessible by the device on which the command list was created.

• The duration of an event created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality.

• The application must ensure the command list and events were created on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• clSetUserEventStatus

• vkCmdSetEvent

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeCommandListAppendWaitOnEvents

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendWaitOnEvents(ze_command_list_handle_t hCommandList, uint32_t numEvents, ze_event_handle_t *phEvents)

Appends wait on event(s) on the device into a command list.

Parameters

• hCommandList: [in] handle of the command list

• numEvents: [in] number of events to wait on before continuing

• phEvents: [in][range(0, numEvents)] handles of the events to wait on before continuing

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must ensure the command list and events were created on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phEvents

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeEventHostSignal

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostSignal(ze_event_handle_t hEvent)

Signals a event from host.

Parameters

• hEvent: [in] handle of the event

• The duration of an event created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clSetUserEventStatus

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeEventHostSynchronize

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostSynchronize(ze_event_handle_t hEvent, uint64_t timeout)

The current host thread waits on an event to be signaled.

Parameters

• hEvent: [in] handle of the event

• timeout: [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then operates exactly like zeEventQueryStatus; if UINT64_MAX, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clWaitForEvents

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_NOT_READY

  • timeout expired

zeEventQueryStatus

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryStatus(ze_event_handle_t hEvent)

Queries an event object’s status on the host.

Parameters

• hEvent: [in] handle of the event

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clGetEventInfo

• vkGetEventStatus

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_NOT_READY

  • not signaled

zeCommandListAppendEventReset

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendEventReset(ze_command_list_handle_t hCommandList, ze_event_handle_t hEvent)

Appends a reset of an event back to not signaled state into a command list.

Parameters

• hCommandList: [in] handle of the command list

• hEvent: [in] handle of the event

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must ensure the command list and events were created on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Remark

Analogues

• vkResetEvent

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeEventHostReset

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostReset(ze_event_handle_t hEvent)

The current host thread resets an event back to not signaled state.

Parameters

• hEvent: [in] handle of the event

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkResetEvent

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

zeEventQueryKernelTimestamp

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryKernelTimestamp(ze_event_handle_t hEvent, ze_kernel_timestamp_result_t *dstptr)

Queries an event’s timestamp value on the host.

Parameters

• hEvent: [in] handle of the event

• dstptr: [in,out] pointer to memory for where timestamp result will be written.

• The application must ensure the event was created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

• The destination memory will be unmodified if the event has not been signaled.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEvent

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == dstptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_NOT_READY

  • not signaled

zeCommandListAppendQueryKernelTimestamps

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendQueryKernelTimestamps(ze_command_list_handle_t hCommandList, uint32_t numEvents, ze_event_handle_t *phEvents, void *dstptr, const size_t *pOffsets, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Appends a query of an events’ timestamp value(s) into a command list.

Parameters

• hCommandList: [in] handle of the command list

• numEvents: [in] the number of timestamp events to query

• phEvents: [in][range(0, numEvents)] handles of timestamp events to query

• dstptr: [in,out] pointer to memory where ze_kernel_timestamp_result_t will be written; must be size-aligned.

• pOffsets: [in][optional][range(0, numEvents)] offset, in bytes, to write results; address must be 4byte-aligned and offsets must be size-aligned.

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before executing query; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing query

• The application must ensure the events are accessible by the device on which the command list was created.

• The application must ensure the events were created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

• The application must ensure the memory pointed to by both dstptr and pOffsets is accessible by the device on which the command list was created.

• The value(s) written to the destination buffer are undefined if any timestamp event has not been signaled.

• If pOffsets is nullptr, then multiple results will be appended sequentially into memory in the same order as phEvents.

• The application must ensure the command list and events were created, and the memory was allocated, on the same context.

• The application must not call this function from simultaneous threads with the same command list handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phEvents

  • nullptr == dstptr

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

Event Enums

ze_event_pool_flags_t

enum ze_event_pool_flag_t

Values:

ZE_EVENT_POOL_FLAG_HOST_VISIBLE = ZE_BIT(0)

signals and waits are also visible to host

ZE_EVENT_POOL_FLAG_IPC = ZE_BIT(1)

signals and waits may be shared across processes

ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP = ZE_BIT(2)

Indicates all events in pool will contain kernel timestamps; cannot be combined with ZE_EVENT_POOL_FLAG_IPC

ZE_EVENT_POOL_FLAG_FORCE_UINT32 = 0x7fffffff

ze_event_scope_flags_t

enum ze_event_scope_flag_t

Values:

ZE_EVENT_SCOPE_FLAG_SUBDEVICE = ZE_BIT(0)

cache hierarchies are flushed or invalidated sufficient for local sub-device access

ZE_EVENT_SCOPE_FLAG_DEVICE = ZE_BIT(1)

cache hierarchies are flushed or invalidated sufficient for global device access and peer device access

ZE_EVENT_SCOPE_FLAG_HOST = ZE_BIT(2)

cache hierarchies are flushed or invalidated sufficient for device and host access

ZE_EVENT_SCOPE_FLAG_FORCE_UINT32 = 0x7fffffff

Event Structures

ze_event_pool_desc_t

struct ze_event_pool_desc_t

Event pool descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_event_pool_flags_t flags

[in] creation flags. must be 0 (default) or a valid combination of ze_event_pool_flag_t; default behavior is signals and waits are visible to the entire device and peer devices.

uint32_t count

[in] number of events within the pool; must be greater than 0

ze_event_desc_t

struct ze_event_desc_t

Event descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

uint32_t index

[in] index of the event within the pool; must be less-than the count specified during pool creation

ze_event_scope_flags_t signal

[in] defines the scope of relevant cache hierarchies to flush on a signal action before the event is triggered. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are flushed.

ze_event_scope_flags_t wait

[in] defines the scope of relevant cache hierarchies to invalidate on a wait action after the event is complete. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are invalidated.

ze_kernel_timestamp_data_t

struct ze_kernel_timestamp_data_t

Kernel timestamp clock data.

• The timestamp frequency can be queried from ze_device_properties_t.timerResolution.

• The number of valid bits in the timestamp value can be queried from ze_device_properties_t.kernelTimestampValidBits.

Public Members

uint64_t kernelStart

[out] device clock at start of kernel execution

uint64_t kernelEnd

[out] device clock at end of kernel execution

ze_kernel_timestamp_result_t

struct ze_kernel_timestamp_result_t

Kernel timestamp result.

Public Members

ze_kernel_timestamp_data_t global

[out] wall-clock data

ze_kernel_timestamp_data_t context

[out] context-active data; only includes clocks while device context was actively executing.

Fence

• Functions

  • zeFenceCreate

  • zeFenceDestroy

  • zeFenceHostSynchronize

  • zeFenceQueryStatus

  • zeFenceReset

• Enumerations

  • ze_fence_flags_t

• Structures

  • ze_fence_desc_t

Fence Functions

zeFenceCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceCreate(ze_command_queue_handle_t hCommandQueue, const ze_fence_desc_t *desc, ze_fence_handle_t *phFence)

Creates a fence for the command queue.

Parameters

• hCommandQueue: [in] handle of command queue

• desc: [in] pointer to fence descriptor

• phFence: [out] pointer to handle of fence object created

• A fence is a heavyweight synchronization primitive used to communicate to the host that command list execution has completed.

• The application must only use the fence for the command queue which was provided during creation.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkCreateFence

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandQueue

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phFence

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < desc->flags

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeFenceDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceDestroy(ze_fence_handle_t hFence)

Deletes a fence object.

Parameters

• hFence: [in][release] handle of fence object to destroy

• The application must ensure the device is not currently referencing the fence before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this fence.

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

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

Remark

Analogues

• vkDestroyFence

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hFence

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeFenceHostSynchronize

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceHostSynchronize(ze_fence_handle_t hFence, uint64_t timeout)

The current host thread waits on a fence to be signaled.

Parameters

• hFence: [in] handle of the fence

• timeout: [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then operates exactly like zeFenceQueryStatus; if UINT64_MAX, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkWaitForFences

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hFence

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_NOT_READY

  • timeout expired

zeFenceQueryStatus

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceQueryStatus(ze_fence_handle_t hFence)

Queries a fence object’s status.

Parameters

• hFence: [in] handle of the fence

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkGetFenceStatus

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hFence

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_NOT_READY

  • not signaled

zeFenceReset

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceReset(ze_fence_handle_t hFence)

Reset a fence back to the not signaled state.

Parameters

• hFence: [in] handle of the fence

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• vkResetFences

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hFence

Fence Enums

ze_fence_flags_t

enum ze_fence_flag_t

Values:

ZE_FENCE_FLAG_SIGNALED = ZE_BIT(0)

fence is created in the signaled state, otherwise not signaled.

ZE_FENCE_FLAG_FORCE_UINT32 = 0x7fffffff

Fence Structures

ze_fence_desc_t

struct ze_fence_desc_t

Fence descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_fence_flags_t flags

[in] creation flags. must be 0 (default) or a valid combination of ze_fence_flag_t.

Image

• Functions

  • zeImageGetProperties

  • zeImageCreate

  • zeImageDestroy

• Enumerations

  • ze_image_flags_t

  • ze_image_type_t

  • ze_image_format_layout_t

  • ze_image_format_type_t

  • ze_image_format_swizzle_t

  • ze_image_sampler_filter_flags_t

• Structures

  • ze_image_format_t

  • ze_image_desc_t

  • ze_image_properties_t

Image Functions

zeImageGetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageGetProperties(ze_device_handle_t hDevice, const ze_image_desc_t *desc, ze_image_properties_t *pImageProperties)

Retrieves supported properties of an image.

Parameters

• hDevice: [in] handle of the device

• desc: [in] pointer to image descriptor

• pImageProperties: [out] pointer to image properties

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == pImageProperties

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < desc->flags

  • ZE_IMAGE_TYPE_BUFFER < desc->type

zeImageCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_image_desc_t *desc, ze_image_handle_t *phImage)

Creates an image on the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device

• desc: [in] pointer to image descriptor

• phImage: [out] pointer to handle of image object created

• The application must only use the image for the device, or its sub-devices, which was provided during creation.

• The application may call this function from simultaneous threads.

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

Remark

Analogues

• clCreateImage

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phImage

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < desc->flags

  • ZE_IMAGE_TYPE_BUFFER < desc->type

• ZE_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeImageDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageDestroy(ze_image_handle_t hImage)

Deletes an image object.

Parameters

• hImage: [in][release] handle of image object to destroy

• The application must ensure the device is not currently referencing the image before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this image.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hImage

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

Image Enums

ze_image_flags_t

enum ze_image_flag_t

Values:

ZE_IMAGE_FLAG_KERNEL_WRITE = ZE_BIT(0)

kernels will write contents

ZE_IMAGE_FLAG_BIAS_UNCACHED = ZE_BIT(1)

device should not cache contents

ZE_IMAGE_FLAG_FORCE_UINT32 = 0x7fffffff

ze_image_type_t

enum ze_image_type_t

Supported image types.

Values:

ZE_IMAGE_TYPE_1D = 0

1D

ZE_IMAGE_TYPE_1DARRAY = 1

1D array

ZE_IMAGE_TYPE_2D = 2

2D

ZE_IMAGE_TYPE_2DARRAY = 3

2D array

ZE_IMAGE_TYPE_3D = 4

3D

ZE_IMAGE_TYPE_BUFFER = 5

Buffer.

ZE_IMAGE_TYPE_FORCE_UINT32 = 0x7fffffff

ze_image_format_layout_t

enum ze_image_format_layout_t

Supported image format layouts.

Values:

ZE_IMAGE_FORMAT_LAYOUT_8 = 0

8-bit single component layout

ZE_IMAGE_FORMAT_LAYOUT_16 = 1

16-bit single component layout

ZE_IMAGE_FORMAT_LAYOUT_32 = 2

32-bit single component layout

ZE_IMAGE_FORMAT_LAYOUT_8_8 = 3

2-component 8-bit layout

ZE_IMAGE_FORMAT_LAYOUT_8_8_8_8 = 4

4-component 8-bit layout

ZE_IMAGE_FORMAT_LAYOUT_16_16 = 5

2-component 16-bit layout

ZE_IMAGE_FORMAT_LAYOUT_16_16_16_16 = 6

4-component 16-bit layout

ZE_IMAGE_FORMAT_LAYOUT_32_32 = 7

2-component 32-bit layout

ZE_IMAGE_FORMAT_LAYOUT_32_32_32_32 = 8

4-component 32-bit layout

ZE_IMAGE_FORMAT_LAYOUT_10_10_10_2 = 9

4-component 10_10_10_2 layout

ZE_IMAGE_FORMAT_LAYOUT_11_11_10 = 10

3-component 11_11_10 layout

ZE_IMAGE_FORMAT_LAYOUT_5_6_5 = 11

3-component 5_6_5 layout

ZE_IMAGE_FORMAT_LAYOUT_5_5_5_1 = 12

4-component 5_5_5_1 layout

ZE_IMAGE_FORMAT_LAYOUT_4_4_4_4 = 13

4-component 4_4_4_4 layout

ZE_IMAGE_FORMAT_LAYOUT_Y8 = 14

Media Format: Y8. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_NV12 = 15

Media Format: NV12. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_YUYV = 16

Media Format: YUYV. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_VYUY = 17

Media Format: VYUY. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_YVYU = 18

Media Format: YVYU. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_UYVY = 19

Media Format: UYVY. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_AYUV = 20

Media Format: AYUV. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_P010 = 21

Media Format: P010. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_Y410 = 22

Media Format: Y410. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_P012 = 23

Media Format: P012. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_Y16 = 24

Media Format: Y16. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_P016 = 25

Media Format: P016. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_Y216 = 26

Media Format: Y216. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_P216 = 27

Media Format: P216. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_P8 = 28

Media Format: P8. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_YUY2 = 29

Media Format: YUY2. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_A8P8 = 30

Media Format: A8P8. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_IA44 = 31

Media Format: IA44. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_AI44 = 32

Media Format: AI44. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_Y416 = 33

Media Format: Y416. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_Y210 = 34

Media Format: Y210. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_I420 = 35

Media Format: I420. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_YV12 = 36

Media Format: YV12. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_400P = 37

Media Format: 400P. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_422H = 38

Media Format: 422H. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_422V = 39

Media Format: 422V. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_444P = 40

Media Format: 444P. Format type and swizzle is ignored for this.

ZE_IMAGE_FORMAT_LAYOUT_FORCE_UINT32 = 0x7fffffff

ze_image_format_type_t

enum ze_image_format_type_t

Supported image format types.

Values:

ZE_IMAGE_FORMAT_TYPE_UINT = 0

Unsigned integer.

ZE_IMAGE_FORMAT_TYPE_SINT = 1

Signed integer.

ZE_IMAGE_FORMAT_TYPE_UNORM = 2

Unsigned normalized integer.

ZE_IMAGE_FORMAT_TYPE_SNORM = 3

Signed normalized integer.

ZE_IMAGE_FORMAT_TYPE_FLOAT = 4

Float.

ZE_IMAGE_FORMAT_TYPE_FORCE_UINT32 = 0x7fffffff

ze_image_format_swizzle_t

enum ze_image_format_swizzle_t

Supported image format component swizzle into channel.

Values:

ZE_IMAGE_FORMAT_SWIZZLE_R = 0

Red component.

ZE_IMAGE_FORMAT_SWIZZLE_G = 1

Green component.

ZE_IMAGE_FORMAT_SWIZZLE_B = 2

Blue component.

ZE_IMAGE_FORMAT_SWIZZLE_A = 3

Alpha component.

ZE_IMAGE_FORMAT_SWIZZLE_0 = 4

Zero.

ZE_IMAGE_FORMAT_SWIZZLE_1 = 5

One.

ZE_IMAGE_FORMAT_SWIZZLE_X = 6

Don’t care.

ZE_IMAGE_FORMAT_SWIZZLE_FORCE_UINT32 = 0x7fffffff

ze_image_sampler_filter_flags_t

enum ze_image_sampler_filter_flag_t

Values:

ZE_IMAGE_SAMPLER_FILTER_FLAG_POINT = ZE_BIT(0)

device supports point filtering

ZE_IMAGE_SAMPLER_FILTER_FLAG_LINEAR = ZE_BIT(1)

device supports linear filtering

ZE_IMAGE_SAMPLER_FILTER_FLAG_FORCE_UINT32 = 0x7fffffff

Image Structures

ze_image_format_t

struct ze_image_format_t

Image format.

Public Members

ze_image_format_layout_t layout

[in] image format component layout

ze_image_format_type_t type

[in] image format type. Media formats can’t be used for ZE_IMAGE_TYPE_BUFFER.

ze_image_format_swizzle_t x

[in] image component swizzle into channel x

ze_image_format_swizzle_t y

[in] image component swizzle into channel y

ze_image_format_swizzle_t z

[in] image component swizzle into channel z

ze_image_format_swizzle_t w

[in] image component swizzle into channel w

ze_image_desc_t

struct ze_image_desc_t

Image descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_image_flags_t flags

[in] creation flags. must be 0 (default) or a valid combination of ze_image_flag_t; default is read-only, cached access.

ze_image_type_t type

[in] image type

ze_image_format_t format

[in] image format

uint64_t width

[in] width dimension. ZE_IMAGE_TYPE_BUFFER: size in bytes; see ze_device_image_properties_t.maxImageBufferSize for limits. ZE_IMAGE_TYPE_1D, ZE_IMAGE_TYPE_1DARRAY: width in pixels; see ze_device_image_properties_t.maxImageDims1D for limits. ZE_IMAGE_TYPE_2D, ZE_IMAGE_TYPE_2DARRAY: width in pixels; see ze_device_image_properties_t.maxImageDims2D for limits. ZE_IMAGE_TYPE_3D: width in pixels; see ze_device_image_properties_t.maxImageDims3D for limits.

uint32_t height

[in] height dimension. ZE_IMAGE_TYPE_2D, ZE_IMAGE_TYPE_2DARRAY: height in pixels; see ze_device_image_properties_t.maxImageDims2D for limits. ZE_IMAGE_TYPE_3D: height in pixels; see ze_device_image_properties_t.maxImageDims3D for limits. other: ignored.

uint32_t depth

[in] depth dimension. ZE_IMAGE_TYPE_3D: depth in pixels; see ze_device_image_properties_t.maxImageDims3D for limits. other: ignored.

uint32_t arraylevels

[in] array levels. ZE_IMAGE_TYPE_1DARRAY, ZE_IMAGE_TYPE_2DARRAY: see ze_device_image_properties_t.maxImageArraySlices for limits. other: ignored.

uint32_t miplevels

[in] mipmap levels (must be 0)

ze_image_properties_t

struct ze_image_properties_t

Image properties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_image_sampler_filter_flags_t samplerFilterFlags

returns 0 (unsupported) or a combination of ze_image_sampler_filter_flag_t.

[out] supported sampler filtering.

Memory

• Functions

  • zeMemAllocShared

  • zeMemAllocDevice

  • zeMemAllocHost

  • zeMemFree

  • zeMemGetAllocProperties

  • zeMemGetAddressRange

  • zeMemGetIpcHandle

  • zeMemOpenIpcHandle

  • zeMemCloseIpcHandle

• Enumerations

  • ze_device_mem_alloc_flags_t

  • ze_host_mem_alloc_flags_t

  • ze_memory_type_t

  • ze_ipc_memory_flags_t

• Structures

  • ze_device_mem_alloc_desc_t

  • ze_host_mem_alloc_desc_t

  • ze_memory_allocation_properties_t

  • ze_external_memory_export_desc_t

  • ze_external_memory_import_fd_t

  • ze_external_memory_export_fd_t

Memory Functions

zeMemAllocShared

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.

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 ze_device_properties_t.maxMemAllocSize.

• 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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == device_desc

  • nullptr == host_desc

  • nullptr == pptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < device_desc->flags

  • 0x7 < host_desc->flags

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

  • Must be zero or a power-of-two

  • 0 != (alignment & (alignment - 1))

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeMemAllocDevice

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.

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 ze_device_properties_t.maxMemAllocSize.

• 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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == device_desc

  • nullptr == pptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < device_desc->flags

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

  • Must be zero or a power-of-two

  • 0 != (alignment & (alignment - 1))

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeMemAllocHost

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.

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 ze_device_properties_t.maxMemAllocSize.

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

• pptr: [out] pointer to host allocation

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == host_desc

  • nullptr == pptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7 < host_desc->flags

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

  • Must be zero or a power-of-two

  • 0 != (alignment & (alignment - 1))

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeMemFree

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.

Parameters

• hContext: [in] handle of the context object

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

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

• The implementation of this function may immediately free all Host and Device allocations associated with this memory

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

zeMemGetAllocProperties

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.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

  • nullptr == pMemAllocProperties

zeMemGetAddressRange

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.

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

• The application may call this function from simultaneous threads.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

zeMemGetIpcHandle

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.

Parameters

• hContext: [in] handle of the context object

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

• pIpcHandle: [out] Returned IPC memory handle

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

• The pointer must be base pointer of the device memory allocation; i.e. the value returned from zeMemAllocDevice.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

  • nullptr == pIpcHandle

zeMemOpenIpcHandle

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.

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

• Takes an IPC memory handle from a remote process and associates it with a device pointer usable in this 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 application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < flags

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pptr

zeMemCloseIpcHandle

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

Closes an IPC memory handle.

Parameters

• hContext: [in] handle of the context object

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

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

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

Memory Enums

ze_device_mem_alloc_flags_t

enum ze_device_mem_alloc_flag_t

Values:

ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_CACHED = ZE_BIT(0)

device should cache allocation

ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_UNCACHED = ZE_BIT(1)

device should not cache allocation (UC)

ZE_DEVICE_MEM_ALLOC_FLAG_FORCE_UINT32 = 0x7fffffff

ze_host_mem_alloc_flags_t

enum ze_host_mem_alloc_flag_t

Values:

ZE_HOST_MEM_ALLOC_FLAG_BIAS_CACHED = ZE_BIT(0)

host should cache allocation

ZE_HOST_MEM_ALLOC_FLAG_BIAS_UNCACHED = ZE_BIT(1)

host should not cache allocation (UC)

ZE_HOST_MEM_ALLOC_FLAG_BIAS_WRITE_COMBINED = ZE_BIT(2)

host memory should be allocated write-combined (WC)

ZE_HOST_MEM_ALLOC_FLAG_FORCE_UINT32 = 0x7fffffff

ze_memory_type_t

enum ze_memory_type_t

Memory allocation type.

Values:

ZE_MEMORY_TYPE_UNKNOWN = 0

the memory pointed to is of unknown type

ZE_MEMORY_TYPE_HOST = 1

the memory pointed to is a host allocation

ZE_MEMORY_TYPE_DEVICE = 2

the memory pointed to is a device allocation

ZE_MEMORY_TYPE_SHARED = 3

the memory pointed to is a shared ownership allocation

ZE_MEMORY_TYPE_FORCE_UINT32 = 0x7fffffff

ze_ipc_memory_flags_t

enum ze_ipc_memory_flag_t

Values:

ZE_IPC_MEMORY_FLAG_TBD = ZE_BIT(0)

reserved for future use

ZE_IPC_MEMORY_FLAG_FORCE_UINT32 = 0x7fffffff

Memory Structures

ze_device_mem_alloc_desc_t

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] pointer to extension-specific structure

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

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] pointer to extension-specific structure

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

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] pointer to extension-specific structure

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

struct ze_external_memory_export_desc_t

Additional allocation descriptor for exporting external memory.

• This structure may be passed to zeMemAllocDevice, via the pNext member of ze_device_mem_alloc_desc_t, to indicate an exportable memory allocation.

• This structure may be passed to zeImageCreate, via the pNext member of ze_image_desc_t, to indicate an exportable image.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

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

struct ze_external_memory_import_fd_t

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

• This structure may be passed to zeMemAllocDevice, via the pNext member of ze_device_mem_alloc_desc_t, to import memory from a file descriptor.

• This structure may be passed to zeImageCreate, via the pNext member of ze_image_desc_t, to import memory from a file descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

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

struct ze_external_memory_export_fd_t

Exports an allocation as a file descriptor.

• This structure may be passed to zeMemGetAllocProperties, via the pNext member of ze_memory_allocation_properties_t, to export a memory allocation as a file descriptor.

• This structure may be passed to zeImageGetProperties, via the pNext member of ze_image_properties_t, to export an image as a file descriptor.

• The requested memory export type must have been specified when the allocation was made.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

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.

Module

• Functions

  • zeModuleCreate

  • zeModuleDestroy

  • zeModuleDynamicLink

  • zeModuleBuildLogDestroy

  • zeModuleBuildLogGetString

  • zeModuleGetNativeBinary

  • zeModuleGetGlobalPointer

  • zeModuleGetKernelNames

  • zeModuleGetProperties

  • zeKernelCreate

  • zeKernelDestroy

  • zeModuleGetFunctionPointer

  • zeKernelSetGroupSize

  • zeKernelSuggestGroupSize

  • zeKernelSuggestMaxCooperativeGroupCount

  • zeKernelSetArgumentValue

  • zeKernelSetIndirectAccess

  • zeKernelGetIndirectAccess

  • zeKernelGetSourceAttributes

  • zeKernelSetCacheConfig

  • zeKernelGetProperties

  • zeKernelGetName

  • zeCommandListAppendLaunchKernel

  • zeCommandListAppendLaunchCooperativeKernel

  • zeCommandListAppendLaunchKernelIndirect

  • zeCommandListAppendLaunchMultipleKernelsIndirect

• Enumerations

  • ze_module_format_t

  • ze_module_property_flags_t

  • ze_kernel_flags_t

  • ze_kernel_indirect_access_flags_t

  • ze_cache_config_flags_t

• Structures

  • ze_module_constants_t

  • ze_module_desc_t

  • ze_module_properties_t

  • ze_kernel_desc_t

  • ze_kernel_uuid_t

  • ze_kernel_properties_t

  • ze_group_count_t

Module Functions

zeModuleCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_module_desc_t *desc, ze_module_handle_t *phModule, ze_module_build_log_handle_t *phBuildLog)

Creates a module on the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device

• desc: [in] pointer to module descriptor

• phModule: [out] pointer to handle of module object created

• phBuildLog: [out][optional] pointer to handle of module’s build log.

• Compiles the module for execution on the device.

• The application must only use the module for the device, or its sub-devices, which was provided during creation.

• The module can be copied to other devices and contexts within the same driver instance by using zeModuleGetNativeBinary.

• A build log can optionally be returned to the caller. The caller is responsible for destroying build log using zeModuleBuildLogDestroy.

• The module descriptor constants are only supported for SPIR-V specialization constants.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == desc->pInputModule

  • nullptr == phModule

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZE_MODULE_FORMAT_NATIVE < desc->format

• ZE_RESULT_ERROR_INVALID_NATIVE_BINARY

• ZE_RESULT_ERROR_INVALID_SIZE

  • 0 == desc->inputSize

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_MODULE_BUILD_FAILURE

zeModuleDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleDestroy(ze_module_handle_t hModule)

Destroys module.

Parameters

• hModule: [in][release] handle of the module

• The application must destroy all kernel and build log handles created from the module before destroying the module itself.

• The application must ensure the device is not currently referencing the module before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this module.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeModuleDynamicLink

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleDynamicLink(uint32_t numModules, ze_module_handle_t *phModules, ze_module_build_log_handle_t *phLinkLog)

Dynamically link modules together that share import/export linkage dependencies.

Parameters

• numModules: [in] number of modules to be linked pointed to by phModules.

• phModules: [in][range(0, numModules)] pointer to an array of modules to dynamically link together.

• phLinkLog: [out][optional] pointer to handle of dynamic link log.

• Modules support import and export linkage for functions and global variables.

• Modules that have imports can be dynamically linked to export modules that satisfy those import requirements.

• Modules can have both import and export linkages.

• Modules that do not have any imports or exports do not need to be linked.

• Modules cannot be partially linked. All modules needed to satisfy all import dependencies for a module must be passed in or ZE_RESULT_ERROR_MODULE_LINK_FAILURE will returned.

• Modules with imports need to be linked before kernel objects can be created from them.

• Modules will only be linked once. A module can be used in multiple link calls if it has exports but it’s imports will not be re-linked.

• Ambiguous dependencies, where multiple modules satisfy the import dependencies for another module, is not allowed.

• ModuleGetNativeBinary can be called on any module regardless of whether it is linked or not.

• A link log can optionally be returned to the caller. The caller is responsible for destroying build log using zeModuleBuildLogDestroy.

• See SPIR-V specification for linkage details.

• The application must ensure the modules being linked were created on the same context.

• The application may call this function from simultaneous threads as long as the import modules being linked are not the same.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phModules

• ZE_RESULT_ERROR_MODULE_LINK_FAILURE

zeModuleBuildLogDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleBuildLogDestroy(ze_module_build_log_handle_t hModuleBuildLog)

Destroys module build log object.

Parameters

• hModuleBuildLog: [in][release] handle of the module build log object.

• The implementation of this function may immediately free all Host allocations associated with this object.

• The application must not call this function from simultaneous threads with the same build log handle.

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

• This function can be called before or after zeModuleDestroy for the associated module.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModuleBuildLog

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeModuleBuildLogGetString

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleBuildLogGetString(ze_module_build_log_handle_t hModuleBuildLog, size_t *pSize, char *pBuildLog)

Retrieves text string for build log.

Parameters

• hModuleBuildLog: [in] handle of the module build log object.

• pSize: [in,out] size of build log string.

• pBuildLog: [in,out][optional] pointer to null-terminated string of the log.

• The caller can pass nullptr for pBuildLog when querying only for size.

• The caller must provide memory for build log.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModuleBuildLog

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pSize

zeModuleGetNativeBinary

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetNativeBinary(ze_module_handle_t hModule, size_t *pSize, uint8_t *pModuleNativeBinary)

Retrieve native binary from Module.

Parameters

• hModule: [in] handle of the module

• pSize: [in,out] size of native binary in bytes.

• pModuleNativeBinary: [in,out][optional] byte pointer to native binary

• The native binary output can be cached to disk and new modules can be later constructed from the cached copy.

• The native binary will retain debugging information that is associated with a module.

• The caller can pass nullptr for pModuleNativeBinary when querying only for size.

• The implementation will copy the native binary into a buffer supplied by the caller.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pSize

zeModuleGetGlobalPointer

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetGlobalPointer(ze_module_handle_t hModule, const char *pGlobalName, size_t *pSize, void **pptr)

Retrieve global variable pointer from Module.

Parameters

• hModule: [in] handle of the module

• pGlobalName: [in] name of global variable in module

• pSize: [in,out][optional] size of global variable

• pptr: [in,out][optional] device visible pointer

• The application may query global pointer from any module that either exports or imports it.

• The application must dynamically link a module that imports a global before the global pointer can be queried from it.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pGlobalName

• ZE_RESULT_ERROR_INVALID_GLOBAL_NAME

zeModuleGetKernelNames

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetKernelNames(ze_module_handle_t hModule, uint32_t *pCount, const char **pNames)

Retrieve all kernel names in the module.

Parameters

• hModule: [in] handle of the module

• pCount: [in,out] pointer to the number of names. if count is zero, then the driver shall update the value with the total number of names available. if count is greater than the number of names available, then the driver shall update the value with the correct number of names available.

• pNames: [in,out][optional][range(0, *pCount)] array of names of functions. if count is less than the number of names available, then driver shall only retrieve that number of names.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeModuleGetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetProperties(ze_module_handle_t hModule, ze_module_properties_t *pModuleProperties)

Retrieve module properties.

Parameters

• hModule: [in] handle of the module

• pModuleProperties: [in,out] query result for module properties.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pModuleProperties

zeKernelCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelCreate(ze_module_handle_t hModule, const ze_kernel_desc_t *desc, ze_kernel_handle_t *phKernel)

Create a kernel from the module.

Parameters

• hModule: [in] handle of the module

• desc: [in] pointer to kernel descriptor

• phKernel: [out] handle of the Function object

• Modules that have unresolved imports need to be dynamically linked before a kernel can be created from them. (See zeModuleDynamicLink)

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == desc->pKernelName

  • nullptr == phKernel

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < desc->flags

• ZE_RESULT_ERROR_INVALID_KERNEL_NAME

• ZE_RESULT_ERROR_INVALID_MODULE_UNLINKED

zeKernelDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelDestroy(ze_kernel_handle_t hKernel)

Destroys a kernel object.

Parameters

• hKernel: [in][release] handle of the kernel object

• The application must ensure the device is not currently referencing the kernel before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this kernel.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeModuleGetFunctionPointer

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetFunctionPointer(ze_module_handle_t hModule, const char *pFunctionName, void **pfnFunction)

Retrieve a function pointer from a module by name.

Parameters

• hModule: [in] handle of the module

• pFunctionName: [in] Name of function to retrieve function pointer for.

• pfnFunction: [out] pointer to function.

• The function pointer is unique for the device on which the module was created.

• The function pointer is no longer valid if module is destroyed.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hModule

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pFunctionName

  • nullptr == pfnFunction

• ZE_RESULT_ERROR_INVALID_FUNCTION_NAME

zeKernelSetGroupSize

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetGroupSize(ze_kernel_handle_t hKernel, uint32_t groupSizeX, uint32_t groupSizeY, uint32_t groupSizeZ)

Set group size for a kernel on the current Host thread.

Parameters

• hKernel: [in] handle of the kernel object

• groupSizeX: [in] group size for X dimension to use for this kernel

• groupSizeY: [in] group size for Y dimension to use for this kernel

• groupSizeZ: [in] group size for Z dimension to use for this kernel

• The group size will be used when a zeCommandListAppendLaunchKernel variant is called.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION

zeKernelSuggestGroupSize

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSuggestGroupSize(ze_kernel_handle_t hKernel, uint32_t globalSizeX, uint32_t globalSizeY, uint32_t globalSizeZ, uint32_t *groupSizeX, uint32_t *groupSizeY, uint32_t *groupSizeZ)

Query a suggested group size for a kernel given a global size for each dimension.

Parameters

• hKernel: [in] handle of the kernel object

• globalSizeX: [in] global width for X dimension

• globalSizeY: [in] global width for Y dimension

• globalSizeZ: [in] global width for Z dimension

• groupSizeX: [out] recommended size of group for X dimension

• groupSizeY: [out] recommended size of group for Y dimension

• groupSizeZ: [out] recommended size of group for Z dimension

• This function ignores the group size that is set using zeKernelSetGroupSize.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == groupSizeX

  • nullptr == groupSizeY

  • nullptr == groupSizeZ

• ZE_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION

zeKernelSuggestMaxCooperativeGroupCount

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSuggestMaxCooperativeGroupCount(ze_kernel_handle_t hKernel, uint32_t *totalGroupCount)

Query a suggested max group count for a cooperative kernel.

Parameters

• hKernel: [in] handle of the kernel object

• totalGroupCount: [out] recommended total group count.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == totalGroupCount

zeKernelSetArgumentValue

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetArgumentValue(ze_kernel_handle_t hKernel, uint32_t argIndex, size_t argSize, const void *pArgValue)

Set kernel argument for a kernel on the current Host thread.

Parameters

• hKernel: [in] handle of the kernel object

• argIndex: [in] argument index in range [0, num args - 1]

• argSize: [in] size of argument type

• pArgValue: [in][optional] argument value represented as matching arg type. If null then argument value is considered null.

• The argument values will be used when a zeCommandListAppendLaunchKernel variant is called.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX

• ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE

zeKernelSetIndirectAccess

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetIndirectAccess(ze_kernel_handle_t hKernel, ze_kernel_indirect_access_flags_t flags)

Sets kernel indirect access flags.

Parameters

• hKernel: [in] handle of the kernel object

• flags: [in] kernel indirect access flags

• The application should specify which allocations will be indirectly accessed by the kernel to allow driver to optimize which allocations are made resident

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7 < flags

zeKernelGetIndirectAccess

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetIndirectAccess(ze_kernel_handle_t hKernel, ze_kernel_indirect_access_flags_t *pFlags)

Retrieve kernel indirect access flags.

Parameters

• hKernel: [in] handle of the kernel object

• pFlags: [out] query result for kernel indirect access flags.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pFlags

zeKernelGetSourceAttributes

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetSourceAttributes(ze_kernel_handle_t hKernel, uint32_t *pSize, char **pString)

Retrieve all declared kernel attributes (i.e. can be specified with attribute in runtime language).

Parameters

• hKernel: [in] handle of the kernel object

• pSize: [in,out] pointer to size of string in bytes.

• pString: [in,out] pointer to null-terminated string, whose lifetime is tied to the kernel object, where kernel source attributes are separated by space.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pSize

  • nullptr == pString

zeKernelSetCacheConfig

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetCacheConfig(ze_kernel_handle_t hKernel, ze_cache_config_flags_t flags)

Sets the preferred cache configuration for a kernel on the current Host thread.

Parameters

• hKernel: [in] handle of the kernel object

• flags: [in] cache configuration. must be 0 (default configuration) or a valid combination of ze_cache_config_flag_t.

• The cache configuration will be used when a zeCommandListAppendLaunchKernel variant is called.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < flags

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

zeKernelGetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetProperties(ze_kernel_handle_t hKernel, ze_kernel_properties_t *pKernelProperties)

Retrieve kernel properties.

Parameters

• hKernel: [in] handle of the kernel object

• pKernelProperties: [in,out] query result for kernel properties.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pKernelProperties

zeKernelGetName

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetName(ze_kernel_handle_t hKernel, size_t *pSize, char *pName)

Retrieve kernel name from Kernel.

Parameters

• hKernel: [in] handle of the kernel object

• pSize: [in,out] size of kernel name string, including null terminator, in bytes.

• pName: [in,out][optional] char pointer to kernel name.

• The caller can pass nullptr for pName when querying only for size.

• The implementation will copy the kernel name into a buffer supplied by the caller.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pSize

zeCommandListAppendLaunchKernel

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchKernel(ze_command_list_handle_t hCommandList, ze_kernel_handle_t hKernel, const ze_group_count_t *pLaunchFuncArgs, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Launch kernel over one or more work groups.

Parameters

• hCommandList: [in] handle of the command list

• hKernel: [in] handle of the kernel object

• pLaunchFuncArgs: [in] thread group launch arguments

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the kernel and events are accessible by the device on which the command list was created.

• This may only be called for a command list created with command queue group ordinal that supports compute.

• The application must ensure the command list, kernel and events were created on the same context.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pLaunchFuncArgs

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendLaunchCooperativeKernel

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchCooperativeKernel(ze_command_list_handle_t hCommandList, ze_kernel_handle_t hKernel, const ze_group_count_t *pLaunchFuncArgs, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Launch kernel cooperatively over one or more work groups.

Parameters

• hCommandList: [in] handle of the command list

• hKernel: [in] handle of the kernel object

• pLaunchFuncArgs: [in] thread group launch arguments

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the kernel and events are accessible by the device on which the command list was created.

• This may only be called for a command list created with command queue group ordinal that supports compute.

• This may only be used for a command list that are submitted to command queue with cooperative flag set.

• The application must ensure the command list, kernel and events were created on the same context.

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

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

• Use zeKernelSuggestMaxCooperativeGroupCount to recommend max group count for device for cooperative functions that device supports.

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pLaunchFuncArgs

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendLaunchKernelIndirect

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchKernelIndirect(ze_command_list_handle_t hCommandList, ze_kernel_handle_t hKernel, const ze_group_count_t *pLaunchArgumentsBuffer, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Launch kernel over one or more work groups using indirect arguments.

Parameters

• hCommandList: [in] handle of the command list

• hKernel: [in] handle of the kernel object

• pLaunchArgumentsBuffer: [in] pointer to device buffer that will contain thread group launch arguments

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the kernel and events are accessible by the device on which the command list was created.

• The application must ensure the launch arguments are visible to the device on which the command list was created.

• The implementation must not access the contents of the launch arguments as they are free to be modified by either the Host or device up until execution.

• This may only be called for a command list created with command queue group ordinal that supports compute.

• The application must ensure the command list, kernel and events were created, and the memory was allocated, on the same context.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pLaunchArgumentsBuffer

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

zeCommandListAppendLaunchMultipleKernelsIndirect

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchMultipleKernelsIndirect(ze_command_list_handle_t hCommandList, uint32_t numKernels, ze_kernel_handle_t *phKernels, const uint32_t *pCountBuffer, const ze_group_count_t *pLaunchArgumentsBuffer, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Launch multiple kernels over one or more work groups using an array of indirect arguments.

Parameters

• hCommandList: [in] handle of the command list

• numKernels: [in] maximum number of kernels to launch

• phKernels: [in][range(0, numKernels)] handles of the kernel objects

• pCountBuffer: [in] pointer to device memory location that will contain the actual number of kernels to launch; value must be less-than or equal-to numKernels

• pLaunchArgumentsBuffer: [in][range(0, numKernels)] pointer to device buffer that will contain a contiguous array of thread group launch arguments

• hSignalEvent: [in][optional] handle of the event to signal on completion

• numWaitEvents: [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`

• phWaitEvents: [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

• The application must ensure the kernel and events are accessible by the device on which the command list was created.

• The application must ensure the array of launch arguments and count buffer are visible to the device on which the command list was created.

• The implementation must not access the contents of the array of launch arguments or count buffer as they are free to be modified by either the Host or device up until execution.

• This may only be called for a command list created with command queue group ordinal that supports compute.

• The application must enusre the command list, kernel and events were created, and the memory was allocated, on the same context.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hCommandList

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phKernels

  • nullptr == pCountBuffer

  • nullptr == pLaunchArgumentsBuffer

• ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

• ZE_RESULT_ERROR_INVALID_SIZE

  • (nullptr == phWaitEvents) && (0 < numWaitEvents)

Module Enums

ze_module_format_t

enum ze_module_format_t

Supported module creation input formats.

Values:

ZE_MODULE_FORMAT_IL_SPIRV = 0

Format is SPIRV IL format.

ZE_MODULE_FORMAT_NATIVE = 1

Format is device native format.

ZE_MODULE_FORMAT_FORCE_UINT32 = 0x7fffffff

ze_module_property_flags_t

enum ze_module_property_flag_t

Values:

ZE_MODULE_PROPERTY_FLAG_IMPORTS = ZE_BIT(0)

Module has imports (i.e. imported global variables and/or kernels). See zeModuleDynamicLink.

ZE_MODULE_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

ze_kernel_flags_t

enum ze_kernel_flag_t

Values:

ZE_KERNEL_FLAG_FORCE_RESIDENCY = ZE_BIT(0)

force all device allocations to be resident during execution

ZE_KERNEL_FLAG_EXPLICIT_RESIDENCY = ZE_BIT(1)

application is responsible for all residency of device allocations. driver may disable implicit residency management.

ZE_KERNEL_FLAG_FORCE_UINT32 = 0x7fffffff

ze_kernel_indirect_access_flags_t

enum ze_kernel_indirect_access_flag_t

Values:

ZE_KERNEL_INDIRECT_ACCESS_FLAG_HOST = ZE_BIT(0)

Indicates that the kernel accesses host allocations indirectly.

ZE_KERNEL_INDIRECT_ACCESS_FLAG_DEVICE = ZE_BIT(1)

Indicates that the kernel accesses device allocations indirectly.

ZE_KERNEL_INDIRECT_ACCESS_FLAG_SHARED = ZE_BIT(2)

Indicates that the kernel accesses shared allocations indirectly.

ZE_KERNEL_INDIRECT_ACCESS_FLAG_FORCE_UINT32 = 0x7fffffff

ze_cache_config_flags_t

enum ze_cache_config_flag_t

Values:

ZE_CACHE_CONFIG_FLAG_LARGE_SLM = ZE_BIT(0)

Large SLM size.

ZE_CACHE_CONFIG_FLAG_LARGE_DATA = ZE_BIT(1)

Large General Data size.

ZE_CACHE_CONFIG_FLAG_FORCE_UINT32 = 0x7fffffff

Module Structures

ze_module_constants_t

struct ze_module_constants_t

Specialization constants - User defined constants.

Public Members

uint32_t numConstants

[in] Number of specialization constants.

const uint32_t *pConstantIds

[in][range(0, numConstants)] Array of IDs that is sized to numConstants.

const void **pConstantValues

[in][range(0, numConstants)] Array of pointers to values that is sized to numConstants.

ze_module_desc_t

struct ze_module_desc_t

Module descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_module_format_t format

[in] Module format passed in with pInputModule

size_t inputSize

[in] size of input IL or ISA from pInputModule.

const uint8_t *pInputModule

[in] pointer to IL or ISA

const char *pBuildFlags

[in][optional] string containing compiler flags. Following options are supported.

• ”-ze-opt-disable”

  • Disable optimizations

• ”-ze-opt-greater-than-4GB-buffer-required”

  • Use 64-bit offset calculations for buffers.

• ”-ze-opt-large-register-file”

  • Increase number of registers available to threads.

• ”-ze-opt-has-buffer-offset-arg”

  • Extend stateless to stateful optimization to more cases with the use of additional offset (e.g. 64-bit pointer to binding table with 32-bit offset).

• ”-g”

  • Include debugging information.

const ze_module_constants_t *pConstants

[in][optional] pointer to specialization constants. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.

ze_module_properties_t

struct ze_module_properties_t

Module properties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_module_property_flags_t flags

[out] 0 (none) or a valid combination of ze_module_property_flag_t

ze_kernel_desc_t

struct ze_kernel_desc_t

Kernel descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_kernel_flags_t flags

[in] creation flags. must be 0 (default) or a valid combination of ze_kernel_flag_t; default behavior may use driver-based residency.

const char *pKernelName

[in] null-terminated name of kernel in module

ze_kernel_uuid_t

struct ze_kernel_uuid_t

Kernel universal unique id (UUID)

Public Members

uint8_t kid[ZE_MAX_KERNEL_UUID_SIZE]

[out] opaque data representing a kernel UUID

uint8_t mid[ZE_MAX_MODULE_UUID_SIZE]

[out] opaque data representing the kernel’s module UUID

ze_kernel_properties_t

struct ze_kernel_properties_t

Kernel properties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

uint32_t numKernelArgs

[out] number of kernel arguments.

uint32_t requiredGroupSizeX

[out] required group size in the X dimension, or zero if there is no required group size

uint32_t requiredGroupSizeY

[out] required group size in the Y dimension, or zero if there is no required group size

uint32_t requiredGroupSizeZ

[out] required group size in the Z dimension, or zero if there is no required group size

uint32_t requiredNumSubGroups

[out] required number of subgroups per thread group, or zero if there is no required number of subgroups

uint32_t requiredSubgroupSize

[out] required subgroup size, or zero if there is no required subgroup size

uint32_t maxSubgroupSize

[out] maximum subgroup size

uint32_t maxNumSubgroups

[out] maximum number of subgroups per thread group

uint32_t localMemSize

[out] local memory size used by each thread group

uint32_t privateMemSize

[out] private memory size allocated by compiler used by each thread

uint32_t spillMemSize

[out] spill memory size allocated by compiler

ze_kernel_uuid_t uuid

[out] universal unique identifier.

ze_group_count_t

struct ze_group_count_t

Kernel dispatch group count.

Public Members

uint32_t groupCountX

[in] number of thread groups in X dimension

uint32_t groupCountY

[in] number of thread groups in Y dimension

uint32_t groupCountZ

[in] number of thread groups in Z dimension

Program

• Enumerations

  • ze_module_program_exp_version_t

• Structures

  • ze_module_program_exp_desc_t

Program Enums

ze_module_program_exp_version_t

enum ze_module_program_exp_version_t

Module Program Extension Version(s)

Values:

ZE_MODULE_PROGRAM_EXP_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZE_MODULE_PROGRAM_EXP_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZE_MODULE_PROGRAM_EXP_VERSION_FORCE_UINT32 = 0x7fffffff

Program Structures

ze_module_program_exp_desc_t

struct ze_module_program_exp_desc_t

Module extended descriptor to support multiple input modules.

• Implementation must support ::ZE_experimental_module_program extension

• pInputModules, pBuildFlags, and pConstants from ze_module_desc_t is ignored.

• Format in ze_module_desc_t needs to be set to ZE_MODULE_FORMAT_IL_SPIRV.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

uint32_t count

[in] Count of input modules

const size_t *inputSizes

[in][range(0, count)] sizes of each input IL module in pInputModules.

const uint8_t **pInputModules

[in][range(0, count)] pointer to an array of IL (e.g. SPIR-V modules). Valid only for SPIR-V input.

const char **pBuildFlags

[in][optional][range(0, count)] array of strings containing build flags. See pBuildFlags in ze_module_desc_t.

const ze_module_constants_t **pConstants

[in][optional][range(0, count)] pointer to array of specialization constant strings. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.

Raytracing

• Enumerations

  • ze_raytracing_ext_version_t

  • ze_device_raytracing_ext_flags_t

  • ze_raytracing_mem_alloc_ext_flags_t

• Structures

  • ze_device_raytracing_ext_properties_t

  • ze_raytracing_mem_alloc_ext_desc_t

Raytracing Enums

ze_raytracing_ext_version_t

enum ze_raytracing_ext_version_t

Raytracing Extension Version(s)

Values:

ZE_RAYTRACING_EXT_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZE_RAYTRACING_EXT_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZE_RAYTRACING_EXT_VERSION_FORCE_UINT32 = 0x7fffffff

ze_device_raytracing_ext_flags_t

enum ze_device_raytracing_ext_flag_t

Values:

ZE_DEVICE_RAYTRACING_EXT_FLAG_RAYQUERY = ZE_BIT(0)

Supports rayquery.

ZE_DEVICE_RAYTRACING_EXT_FLAG_FORCE_UINT32 = 0x7fffffff

ze_raytracing_mem_alloc_ext_flags_t

enum ze_raytracing_mem_alloc_ext_flag_t

Values:

ZE_RAYTRACING_MEM_ALLOC_EXT_FLAG_TBD = ZE_BIT(0)

reserved for future use

ZE_RAYTRACING_MEM_ALLOC_EXT_FLAG_FORCE_UINT32 = 0x7fffffff

Raytracing Structures

ze_device_raytracing_ext_properties_t

struct ze_device_raytracing_ext_properties_t

Raytracing properties queried using zeDeviceGetModuleProperties.

• This structure may be returned from zeDeviceGetModuleProperties, via pNext member of ze_device_module_properties_t.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_device_raytracing_ext_flags_t flags

[out] 0 or a valid combination of ze_device_raytracing_ext_flags_t

uint32_t maxBVHLevels

[out] Maximum number of BVH levels supported

ze_raytracing_mem_alloc_ext_desc_t

struct ze_raytracing_mem_alloc_ext_desc_t

Raytracing memory allocation descriptor.

• This structure must be passed to zeMemAllocShared or zeMemAllocDevice, via pNext member of ze_device_mem_alloc_desc_t, for any memory allocation that is to be accessed by raytracing fixed-function of the device.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_raytracing_mem_alloc_ext_flags_t flags

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

Residency

• Functions

  • zeContextMakeMemoryResident

  • zeContextEvictMemory

  • zeContextMakeImageResident

  • zeContextEvictImage

Residency Functions

zeContextMakeMemoryResident

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextMakeMemoryResident(ze_context_handle_t hContext, ze_device_handle_t hDevice, void *ptr, size_t size)

Makes memory resident for the device.

Parameters

• hContext: [in] handle of context object

• hDevice: [in] handle of the device

• ptr: [in] pointer to memory to make resident

• size: [in] size in bytes to make resident

• The application must ensure the memory is resident before being referenced by the device

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeContextEvictMemory

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextEvictMemory(ze_context_handle_t hContext, ze_device_handle_t hDevice, void *ptr, size_t size)

Allows memory to be evicted from the device.

Parameters

• hContext: [in] handle of context object

• hDevice: [in] handle of the device

• ptr: [in] pointer to memory to evict

• size: [in] size in bytes to evict

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

• The application may free the memory without evicting; the memory is implicitly evicted when freed.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeContextMakeImageResident

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextMakeImageResident(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_image_handle_t hImage)

Makes image resident for the device.

Parameters

• hContext: [in] handle of context object

• hDevice: [in] handle of the device

• hImage: [in] handle of image to make resident

• The application must ensure the image is resident before being referenced by the device

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

  • nullptr == hImage

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeContextEvictImage

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextEvictImage(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_image_handle_t hImage)

Allows image to be evicted from the device.

Parameters

• hContext: [in] handle of context object

• hDevice: [in] handle of the device

• hImage: [in] handle of image to make evict

• The application must ensure the device is not currently referencing the image before it is evicted

• The application may destroy the image without evicting; the image is implicitly evicted when destroyed.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

  • nullptr == hImage

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

Sampler

• Functions

  • zeSamplerCreate

  • zeSamplerDestroy

• Enumerations

  • ze_sampler_address_mode_t

  • ze_sampler_filter_mode_t

• Structures

  • ze_sampler_desc_t

Sampler Functions

zeSamplerCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeSamplerCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_sampler_desc_t *desc, ze_sampler_handle_t *phSampler)

Creates sampler on the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device

• desc: [in] pointer to sampler descriptor

• phSampler: [out] handle of the sampler

• The application must only use the sampler for the device, or its sub-devices, which was provided during creation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phSampler

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZE_SAMPLER_ADDRESS_MODE_MIRROR < desc->addressMode

  • ZE_SAMPLER_FILTER_MODE_LINEAR < desc->filterMode

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

zeSamplerDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeSamplerDestroy(ze_sampler_handle_t hSampler)

Destroys sampler object.

Parameters

• hSampler: [in][release] handle of the sampler

• The application must ensure the device is not currently referencing the sampler before it is deleted.

• The implementation of this function may immediately free all Host and Device allocations associated with this sampler.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hSampler

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

Sampler Enums

ze_sampler_address_mode_t

enum ze_sampler_address_mode_t

Sampler addressing modes.

Values:

ZE_SAMPLER_ADDRESS_MODE_NONE = 0

No coordinate modifications for out-of-bounds image access.

ZE_SAMPLER_ADDRESS_MODE_REPEAT = 1

Out-of-bounds coordinates are wrapped back around.

ZE_SAMPLER_ADDRESS_MODE_CLAMP = 2

Out-of-bounds coordinates are clamped to edge.

ZE_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER = 3

Out-of-bounds coordinates are clamped to border color which is (0.0f, 0.0f, 0.0f, 0.0f) if image format swizzle contains alpha, otherwise (0.0f, 0.0f, 0.0f, 1.0f).

ZE_SAMPLER_ADDRESS_MODE_MIRROR = 4

Out-of-bounds coordinates are mirrored starting from edge.

ZE_SAMPLER_ADDRESS_MODE_FORCE_UINT32 = 0x7fffffff

ze_sampler_filter_mode_t

enum ze_sampler_filter_mode_t

Sampler filtering modes.

Values:

ZE_SAMPLER_FILTER_MODE_NEAREST = 0

No coordinate modifications for out of bounds image access.

ZE_SAMPLER_FILTER_MODE_LINEAR = 1

Out-of-bounds coordinates are wrapped back around.

ZE_SAMPLER_FILTER_MODE_FORCE_UINT32 = 0x7fffffff

Sampler Structures

ze_sampler_desc_t

struct ze_sampler_desc_t

Sampler descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_sampler_address_mode_t addressMode

[in] Sampler addressing mode to determine how out-of-bounds coordinates are handled.

ze_sampler_filter_mode_t filterMode

[in] Sampler filter mode to determine how samples are filtered.

ze_bool_t isNormalized

[in] Are coordinates normalized [0, 1] or not.

Virtual

• Functions

  • zeVirtualMemReserve

  • zeVirtualMemFree

  • zeVirtualMemQueryPageSize

  • zePhysicalMemCreate

  • zePhysicalMemDestroy

  • zeVirtualMemMap

  • zeVirtualMemUnmap

  • zeVirtualMemSetAccessAttribute

  • zeVirtualMemGetAccessAttribute

• Enumerations

  • ze_memory_access_attribute_t

  • ze_physical_mem_flags_t

• Structures

  • ze_physical_mem_desc_t

Virtual Functions

zeVirtualMemReserve

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemReserve(ze_context_handle_t hContext, const void *pStart, size_t size, void **pptr)

Reserves pages in virtual address space.

Parameters

• hContext: [in] handle of the context object

• pStart: [in] pointer to start of region to reserve. If nullptr then implementation will choose a start address.

• size: [in] size in bytes to reserve; must be page aligned.

• pptr: [out] pointer to virtual reservation.

• The application must only use the memory allocation on the context for which it was created.

• The starting address and size must be page aligned. See zeVirtualMemQueryPageSize.

• If pStart is not null then implementation will attempt to reserve starting from that address. If not available then will find another suitable starting address.

• The application may call this function from simultaneous threads.

• The access attributes will default to none to indicate reservation is inaccessible.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pStart

  • nullptr == pptr

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

zeVirtualMemFree

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemFree(ze_context_handle_t hContext, const void *ptr, size_t size)

Free pages in a reserved virtual address range.

Parameters

• hContext: [in] handle of the context object

• ptr: [in] pointer to start of region to free.

• size: [in] size in bytes to free; must be page aligned.

• Any existing virtual mappings for the range will be unmapped.

• Physical allocations objects that were mapped to this range will not be destroyed. These need to be destroyed explicitly.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

zeVirtualMemQueryPageSize

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemQueryPageSize(ze_context_handle_t hContext, ze_device_handle_t hDevice, size_t size, size_t *pagesize)

Queries page size to use for aligning virtual memory reservations and physical memory allocations.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device object

• size: [in] unaligned allocation size in bytes

• pagesize: [out] pointer to page size to use for start address and size alignments.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pagesize

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

zePhysicalMemCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zePhysicalMemCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_physical_mem_desc_t *desc, ze_physical_mem_handle_t *phPhysicalMemory)

Creates a physical memory object for the context.

Parameters

• hContext: [in] handle of the context object

• hDevice: [in] handle of the device object

• desc: [in] pointer to physical memory descriptor.

• phPhysicalMemory: [out] pointer to handle of physical memory object created

• The application must only use the physical memory object on the context for which it was created.

• The size must be page aligned. See zeVirtualMemQueryPageSize.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phPhysicalMemory

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x1 < desc->flags

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == desc->size

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

zePhysicalMemDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zePhysicalMemDestroy(ze_context_handle_t hContext, ze_physical_mem_handle_t hPhysicalMemory)

Destroys a physical memory object.

Parameters

• hContext: [in] handle of the context object

• hPhysicalMemory: [in][release] handle of physical memory object to destroy

• The application must ensure the device is not currently referencing the physical memory object before it is deleted

• The application must not call this function from simultaneous threads with the same physical memory handle.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hPhysicalMemory

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zeVirtualMemMap

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemMap(ze_context_handle_t hContext, const void *ptr, size_t size, ze_physical_mem_handle_t hPhysicalMemory, size_t offset, ze_memory_access_attribute_t access)

Maps pages in virtual address space to pages from physical memory object.

Parameters

• hContext: [in] handle of the context object

• ptr: [in] pointer to start of virtual address range to map.

• size: [in] size in bytes of virtual address range to map; must be page aligned.

• hPhysicalMemory: [in] handle to physical memory object.

• offset: [in] offset into physical memory allocation object; must be page aligned.

• access: [in] specifies page access attributes to apply to the virtual address range.

• The virtual address range must have been reserved using zeVirtualMemReserve.

• The application must only use the mapped memory allocation on the context for which it was created.

• The virtual start address and size must be page aligned. See zeVirtualMemQueryPageSize.

• The application should use, for the starting address and size, the same size alignment used for the physical allocation.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hPhysicalMemory

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY < access

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

zeVirtualMemUnmap

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemUnmap(ze_context_handle_t hContext, const void *ptr, size_t size)

Unmaps pages in virtual address space from pages from a physical memory object.

Parameters

• hContext: [in] handle of the context object

• ptr: [in] pointer to start of region to unmap.

• size: [in] size in bytes to unmap; must be page aligned.

• The page access attributes for virtual address range will revert back to none.

• The application may call this function from simultaneous threads.

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT - “Address must be page aligned”

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

  • Size must be page aligned

zeVirtualMemSetAccessAttribute

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemSetAccessAttribute(ze_context_handle_t hContext, const void *ptr, size_t size, ze_memory_access_attribute_t access)

Set memory access attributes for a virtual address range.

Parameters

• hContext: [in] handle of the context object

• ptr: [in] pointer to start of reserved virtual address region.

• size: [in] size in bytes; must be page aligned.

• access: [in] specifies page access attributes to apply to the virtual address range.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY < access

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT - “Address must be page aligned”

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

  • Size must be page aligned

zeVirtualMemGetAccessAttribute

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemGetAccessAttribute(ze_context_handle_t hContext, const void *ptr, size_t size, ze_memory_access_attribute_t *access, size_t *outSize)

Get memory access attribute for a virtual address range.

Parameters

• hContext: [in] handle of the context object

• ptr: [in] pointer to start of virtual address region for query.

• size: [in] size in bytes; must be page aligned.

• access: [out] query result for page access attribute.

• outSize: [out] query result for size of virtual address range, starting at ptr, that shares same access attribute.

• If size and outSize are equal then the pages in the specified virtual address range have the same access attributes.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == ptr

  • nullptr == access

  • nullptr == outSize

• ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT - “Address must be page aligned”

• ZE_RESULT_ERROR_UNSUPPORTED_SIZE

  • 0 == size

  • Size must be page aligned

Virtual Enums

ze_memory_access_attribute_t

enum ze_memory_access_attribute_t

Virtual memory page access attributes.

Values:

ZE_MEMORY_ACCESS_ATTRIBUTE_NONE = 0

Indicates the memory page is inaccessible.

ZE_MEMORY_ACCESS_ATTRIBUTE_READWRITE = 1

Indicates the memory page supports read write access.

ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY = 2

Indicates the memory page supports read-only access.

ZE_MEMORY_ACCESS_ATTRIBUTE_FORCE_UINT32 = 0x7fffffff

ze_physical_mem_flags_t

enum ze_physical_mem_flag_t

Values:

ZE_PHYSICAL_MEM_FLAG_TBD = ZE_BIT(0)

reserved for future use.

ZE_PHYSICAL_MEM_FLAG_FORCE_UINT32 = 0x7fffffff

Virtual Structures

ze_physical_mem_desc_t

struct ze_physical_mem_desc_t

Physical memory descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_physical_mem_flags_t flags

[in] creation flags. must be 0 (default) or a valid combination of ze_physical_mem_flag_t.

size_t size

[in] size in bytes to reserve; must be page aligned.

Floatatomics

• Enumerations

  • ze_float_atomics_ext_version_t

  • ze_device_fp_atomic_ext_flags_t

• Structures

  • ze_float_atomic_ext_properties_t

Floatatomics Enums

ze_float_atomics_ext_version_t

enum ze_float_atomics_ext_version_t

Floating-Point Atomics Extension Version(s)

Values:

ZE_FLOAT_ATOMICS_EXT_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZE_FLOAT_ATOMICS_EXT_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZE_FLOAT_ATOMICS_EXT_VERSION_FORCE_UINT32 = 0x7fffffff

ze_device_fp_atomic_ext_flags_t

enum ze_device_fp_atomic_ext_flag_t

Values:

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_GLOBAL_LOAD_STORE = ZE_BIT(0)

Supports atomic load, store, and exchange.

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_GLOBAL_ADD = ZE_BIT(1)

Supports atomic add and subtract.

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_GLOBAL_MIN_MAX = ZE_BIT(2)

Supports atomic min and max.

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_LOCAL_LOAD_STORE = ZE_BIT(16)

Supports atomic load, store, and exchange.

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_LOCAL_ADD = ZE_BIT(17)

Supports atomic add and subtract.

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_LOCAL_MIN_MAX = ZE_BIT(18)

Supports atomic min and max.

ZE_DEVICE_FP_ATOMIC_EXT_FLAG_FORCE_UINT32 = 0x7fffffff

Floatatomics Structures

ze_float_atomic_ext_properties_t

struct ze_float_atomic_ext_properties_t

Device floating-point atomic properties queried using zeDeviceGetModuleProperties.

• This structure may be returned from zeDeviceGetModuleProperties, via pNext member of ze_device_module_properties_t.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

ze_device_fp_atomic_ext_flags_t fp16Flags

[out] Capabilities for half-precision floating-point atomic operations

ze_device_fp_atomic_ext_flags_t fp32Flags

[out] Capabilities for single-precision floating-point atomic operations

ze_device_fp_atomic_ext_flags_t fp64Flags

[out] Capabilities for double-precision floating-point atomic operations

Globaloffset

• Functions

  • zeKernelSetGlobalOffsetExp

• Enumerations

  • ze_global_offset_exp_version_t

Globaloffset Functions

zeKernelSetGlobalOffsetExp

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetGlobalOffsetExp(ze_kernel_handle_t hKernel, uint32_t offsetX, uint32_t offsetY, uint32_t offsetZ)

Set global work offset for a kernel on the current Host thread.

Parameters

• hKernel: [in] handle of the kernel object

• offsetX: [in] global offset for X dimension to use for this kernel

• offsetY: [in] global offset for Y dimension to use for this kernel

• offsetZ: [in] global offset for Z dimension to use for this kernel

• The global work offset will be used when azeCommandListAppendLaunchKernel()variant is called.

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

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

Return

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

Globaloffset Enums

ze_global_offset_exp_version_t

enum ze_global_offset_exp_version_t

Global Offset Extension Version(s)

Values:

ZE_GLOBAL_OFFSET_EXP_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZE_GLOBAL_OFFSET_EXP_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZE_GLOBAL_OFFSET_EXP_VERSION_FORCE_UINT32 = 0x7fffffff

Relaxedalloclimits

• Enumerations

  • ze_relaxed_allocation_limits_exp_version_t

  • ze_relaxed_allocation_limits_exp_flags_t

• Structures

  • ze_relaxed_allocation_limits_exp_desc_t

Relaxedalloclimits Enums

ze_relaxed_allocation_limits_exp_version_t

enum ze_relaxed_allocation_limits_exp_version_t

Relaxed Allocation Limits Extension Version(s)

Values:

ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_FORCE_UINT32 = 0x7fffffff

ze_relaxed_allocation_limits_exp_flags_t

enum ze_relaxed_allocation_limits_exp_flag_t

Values:

ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_MAX_SIZE = ZE_BIT(0)

Allocation size may exceed ze_device_properties_t.maxMemAllocSize.

ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_FORCE_UINT32 = 0x7fffffff

Relaxedalloclimits Structures

ze_relaxed_allocation_limits_exp_desc_t

struct ze_relaxed_allocation_limits_exp_desc_t

Relaxed limits memory allocation descriptor.

• This structure may be passed to zeMemAllocShared or zeMemAllocDevice, via pNext member of ze_device_mem_alloc_desc_t.

• This structure may also be passed to zeMemAllocHost, via pNext member of ze_host_mem_alloc_desc_t.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

ze_relaxed_allocation_limits_exp_flags_t flags

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