Core API

oneAPI Level Zero Specification - Version 0.95.0

Common

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

[Core] insufficient host memory to satisfy call

ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

[Core] insufficient device memory to satisfy call

ZE_RESULT_ERROR_MODULE_BUILD_FAILURE

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

ZE_RESULT_ERROR_MODULE_LINK_FAILURE

[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

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

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

[Validation] generic error code for unsupported versions

ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

[Validation] generic error code for unsupported features

ZE_RESULT_ERROR_INVALID_ARGUMENT

[Validation] generic error code for invalid arguments

ZE_RESULT_ERROR_INVALID_NULL_HANDLE

[Validation] handle argument is not valid

ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

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

ZE_RESULT_ERROR_INVALID_NULL_POINTER

[Validation] pointer argument may not be nullptr

ZE_RESULT_ERROR_INVALID_SIZE

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

ZE_RESULT_ERROR_UNSUPPORTED_SIZE

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

ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT

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

ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT

[Validation] synchronization object in invalid state

ZE_RESULT_ERROR_INVALID_ENUMERATION

[Validation] enumerator argument is not valid

ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

[Validation] enumerator argument is not supported by the device

ZE_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT

[Validation] image format is not supported by the device

ZE_RESULT_ERROR_INVALID_NATIVE_BINARY

[Validation] native binary is not supported by the device

ZE_RESULT_ERROR_INVALID_GLOBAL_NAME

[Validation] global variable is not found in the module

ZE_RESULT_ERROR_INVALID_KERNEL_NAME

[Validation] kernel name is not found in the module

ZE_RESULT_ERROR_INVALID_FUNCTION_NAME

[Validation] function name is not found in the module

ZE_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION

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

ZE_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION

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

ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX

[Validation] kernel argument index is not valid for kernel

ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE

[Validation] kernel argument size does not match kernel

ZE_RESULT_ERROR_INVALID_KERNEL_ATTRIBUTE_VALUE

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

ZE_RESULT_ERROR_INVALID_COMMAND_LIST_TYPE

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

ZE_RESULT_ERROR_OVERLAPPING_REGIONS

[Validation] copy operations do not support overlapping regions of memory

ZE_RESULT_ERROR_UNKNOWN = 0x7fffffff

[Core] unknown or internal error

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

ze_driver_ipc_properties_t

ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES

ze_device_properties_t

ZE_STRUCTURE_TYPE_DEVICE_COMPUTE_PROPERTIES

ze_device_compute_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MODULE_PROPERTIES

ze_device_module_properties_t

ZE_STRUCTURE_TYPE_COMMAND_QUEUE_GROUP_PROPERTIES

ze_command_queue_group_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MEMORY_PROPERTIES

ze_device_memory_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MEMORY_ACCESS_PROPERTIES

ze_device_memory_access_properties_t

ZE_STRUCTURE_TYPE_DEVICE_CACHE_PROPERTIES

ze_device_cache_properties_t

ZE_STRUCTURE_TYPE_DEVICE_IMAGE_PROPERTIES

ze_device_image_properties_t

ZE_STRUCTURE_TYPE_DEVICE_P2P_PROPERTIES

ze_device_p2p_properties_t

ZE_STRUCTURE_TYPE_COMMAND_QUEUE_DESC

ze_command_queue_desc_t

ZE_STRUCTURE_TYPE_COMMAND_LIST_DESC

ze_command_list_desc_t

ZE_STRUCTURE_TYPE_EVENT_POOL_DESC

ze_event_pool_desc_t

ZE_STRUCTURE_TYPE_EVENT_DESC

ze_event_desc_t

ZE_STRUCTURE_TYPE_FENCE_DESC

ze_fence_desc_t

ZE_STRUCTURE_TYPE_IMAGE_DESC

ze_image_desc_t

ZE_STRUCTURE_TYPE_IMAGE_PROPERTIES

ze_image_properties_t

ZE_STRUCTURE_TYPE_DEVICE_MEM_ALLOC_DESC

ze_device_mem_alloc_desc_t

ZE_STRUCTURE_TYPE_HOST_MEM_ALLOC_DESC

ze_host_mem_alloc_desc_t

ZE_STRUCTURE_TYPE_MEMORY_ALLOCATION_PROPERTIES

ze_memory_allocation_properties_t

ZE_STRUCTURE_TYPE_MODULE_DESC

ze_module_desc_t

ZE_STRUCTURE_TYPE_KERNEL_DESC

ze_kernel_desc_t

ZE_STRUCTURE_TYPE_KERNEL_PROPERTIES

ze_kernel_properties_t

ZE_STRUCTURE_TYPE_SAMPLER_DESC

ze_sampler_desc_t

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

Driver Functions

zeInit

ZE_APIEXPORT ze_result_t ZE_APICALL zeInit(ze_init_flag_t flags)

Initialize the ‘oneAPI’ driver(s)

Parameters

  • flags: initialization flags

  • This function must be called before any other API 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.

  • This function is thread-safe for scenarios where multiple libraries may initialize the driver(s) simultaneously.

Return

zeDriverGet

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

Retrieves driver instances.

Parameters

  • pCount: pointer to the number of driver instances. if count is zero, then the loader will update the value with the total number of drivers available. if count is non-zero, then the loader will only retrieve that number of drivers. if count is larger than the number of drivers available, then the loader will update the value with the correct number of drivers available.

  • phDrivers: [optional][range(0, *pCount)] array of driver instance handles

  • A driver represents a collection of physical devices.

  • 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

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: handle of the driver instance

  • version: api version

  • The application may call this function from simultaneous threads.

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

Return

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: handle of the driver instance

  • pDriverProperties: 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

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: handle of the driver instance

  • pIpcProperties: query result for IPC properties

  • The application may call this function from simultaneous threads.

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

Return

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: handle of the driver instance

  • pCount: pointer to the number of extension properties. if count is zero, then the driver will update the value with the total number of extension properties available. if count is non-zero, then driver will only retrieve that number of extension properties. if count is larger than the number of extension properties available, then the driver will update the value with the correct number of extension properties available.

  • pExtensionProperties: [optional][range(0, *pCount)] array of query results for extension properties

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkEnumerateInstanceExtensionProperties

Return

Driver Enums

ze_init_flag_t

enum ze_init_flag_t

Supported initialization flags.

Values:

ZE_INIT_FLAG_NONE = 0

default behavior

ZE_INIT_FLAG_GPU_ONLY = ZE_BIT(0)

only initialize GPU drivers

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

1.0

ZE_API_VERSION_CURRENT = ZE_MAKE_VERSION(1, )

latest known version

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_bool_t memsSupported

[out] Supports passing memory allocations between processes. See ::zeDriverGetMemIpcHandle.

ze_bool_t eventsSupported

[out] Supports passing events between processes. See ::zeEventPoolGetIpcHandle.

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

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: handle of the driver instance

  • pCount: pointer to the number of devices. if count is zero, then the driver will update the value with the total number of devices available. if count is non-zero, then driver will only retrieve that number of devices. if count is larger than the number of devices available, then the driver will update the value with the correct number of devices available.

  • phDevices: [optional][range(0, *pCount)] array of handle of devices

  • 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

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: handle of the device object

  • pCount: pointer to the number of sub-devices. if count is zero, then the driver will update the value with the total number of sub-devices available. if count is non-zero, then driver will only retrieve that number of sub-devices. if count is larger than the number of sub-devices available, then the driver will update the value with the correct number of sub-devices available.

  • phSubdevices: [optional][range(0, *pCount)] array of handle of sub-devices

  • 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

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: handle of the device

  • pDeviceProperties: 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

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: handle of the device

  • pComputeProperties: 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

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: handle of the device

  • pModuleProperties: query result for module properties

  • The application may call this function from simultaneous threads.

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

Return

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: handle of the device

  • pCount: pointer to the number of command queue group properties. if count is zero, then the driver will update the value with the total number of command queue group properties available. if count is non-zero, then driver will only retrieve that number of command queue group properties. if count is larger than the number of command queue group properties available, then the driver will update the value with the correct number of command queue group properties available.

  • pCommandQueueGroupProperties: [optional][range(0, *pCount)] array of query results for command queue group properties

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkGetPhysicalDeviceQueueFamilyProperties

Return

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: handle of the device

  • pCount: pointer to the number of memory properties. if count is zero, then the driver will update the value with the total number of memory properties available. if count is non-zero, then driver will only retrieve that number of memory properties. if count is larger than the number of memory properties available, then the driver will update the value with the correct number of memory properties available.

  • pMemProperties: [optional][range(0, *pCount)] array of query results for memory properties

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Return

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: handle of the device

  • pMemAccessProperties: 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

zeDeviceGetCacheProperties

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

Retrieves cache properties of the device.

Parameters

  • hDevice: handle of the device

  • pCacheProperties: query result for cache properties

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Return

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: handle of the device

  • pImageProperties: query result for image properties

  • The application may call this function from simultaneous threads.

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

Return

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: handle of the device performing the access

  • hPeerDevice: handle of the peer device with the allocation

  • pP2PProperties: 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

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: handle of the device performing the access

  • hPeerDevice: handle of the peer device with the allocation

  • value: 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

zeDeviceSetLastLevelCacheConfig

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceSetLastLevelCacheConfig(ze_device_handle_t hDevice, ze_cache_config_t CacheConfig)

Sets the preferred Last Level cache configuration for a device.

Parameters

  • hDevice: handle of the device

  • CacheConfig: CacheConfig

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

Return

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_FPGA

Field Programmable Gate Array.

ze_fp_caps_t

enum ze_fp_caps_t

Floating-Point capabilities.

  • floating-point capabilities of the device.

Values:

ZE_FP_CAPS_NONE = 0

None.

ZE_FP_CAPS_DENORM = ZE_BIT(0)

Supports denorms.

ZE_FP_CAPS_INF_NAN = ZE_BIT(1)

Supports INF and quiet NaNs.

ZE_FP_CAPS_ROUND_TO_NEAREST = ZE_BIT(2)

Supports rounding to nearest even rounding mode.

ZE_FP_CAPS_ROUND_TO_ZERO = ZE_BIT(3)

Supports rounding to zero.

ZE_FP_CAPS_ROUND_TO_INF = ZE_BIT(4)

Supports rounding to both positive and negative INF.

ZE_FP_CAPS_FMA = ZE_BIT(5)

Supports IEEE754-2008 fused multiply-add.

ZE_FP_CAPS_ROUNDED_DIVIDE_SQRT = ZE_BIT(6)

Supports rounding as defined by IEEE754 for divide and sqrt operations.

ZE_FP_CAPS_SOFT_FLOAT = ZE_BIT(7)

Uses software implementation for basic floating-point operations.

ze_memory_access_caps_t

enum ze_memory_access_caps_t

Memory access capabilities.

  • Supported access capabilities for different types of memory allocations

Values:

ZE_MEMORY_ACCESS_CAPS_NONE = 0

Access not supported.

ZE_MEMORY_ACCESS_CAPS_RW = ZE_BIT(0)

Supports load/store access.

ZE_MEMORY_ACCESS_CAPS_ATOMIC = ZE_BIT(1)

Supports atomic access.

ZE_MEMORY_ACCESS_CAPS_CONCURRENT = ZE_BIT(2)

Supports concurrent access.

ZE_MEMORY_ACCESS_CAPS_CONCURRENT_ATOMIC = ZE_BIT(3)

Supports concurrent atomic access.

ze_cache_config_t

enum ze_cache_config_t

Supported Cache Config.

  • Supported Cache Config (Default, Large SLM, Large Data Cache)

Values:

ZE_CACHE_CONFIG_DEFAULT = ZE_BIT(0)

Default Config.

ZE_CACHE_CONFIG_LARGE_SLM = ZE_BIT(1)

Large SLM size.

ZE_CACHE_CONFIG_LARGE_DATA = ZE_BIT(2)

Large General Data size.

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_bool_t isSubdevice

[out] If the device handle used for query represents a sub-device.

uint32_t subdeviceId

[out] sub-device id. Only valid if isSubdevice is true.

uint32_t coreClockRate

[out] Clock rate for device core.

ze_bool_t unifiedMemorySupported

[out] Supports unified physical memory between Host and device.

ze_bool_t eccMemorySupported

[out] Supports error correction memory access.

ze_bool_t onDemandPageFaultsSupported

[out] Supports on-demand page-faulting.

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

char name[ZE_MAX_DEVICE_NAME]

[out] Device name

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. (maxGroupSizeX * maxGroupSizeY

  • maxGroupSizeZ) <= 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_bool_t fp16Supported

[out] Supports 16-bit floating-point operations

ze_bool_t fp64Supported

[out] Supports 64-bit floating-point operations

ze_bool_t int64AtomicsSupported

[out] Supports 64-bit atomic operations

ze_bool_t dp4aSupported

[out] Supports four component dot product and accumulate operations

ze_fp_caps_t fp16Capabilities

[out] Capabilities for half-precision floating-point operations.

ze_fp_caps_t fp32Capabilities

[out] Capabilities for single-precision floating-point operations.

ze_fp_caps_t fp64Capabilities

[out] Capabilities for double-precision floating-point operations.

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_bool_t computeSupported

[out] command queue group supports enqueing compute commands.

ze_bool_t copySupported

[out] command queue group supports enqueing copy commands.

ze_bool_t singleSliceSupported

[out] command queue group supports reserving a single slice. ‘slice’ size is reported by ze_device_properties_t.

ze_bool_t cooperativeKernelsSupported

[out] command queue group supports cooperative kernels. See zeCommandListAppendLaunchCooperativeKernel for more details.

ze_bool_t maxMemoryFillPatternSize

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

uint32_t numQueues

[out] the number of physical command queues 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

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.

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_caps_t hostAllocCapabilities

[out] Bitfield describing host memory capabilities

ze_memory_access_caps_t deviceAllocCapabilities

[out] Bitfield describing device memory capabilities

ze_memory_access_caps_t sharedSingleDeviceAllocCapabilities

[out] Bitfield describing shared (single-device) memory capabilities

ze_memory_access_caps_t sharedCrossDeviceAllocCapabilities

[out] Bitfield describing shared (cross-device) memory capabilities

ze_memory_access_caps_t sharedSystemAllocCapabilities

[out] Bitfield describing 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_bool_t intermediateCacheControlSupported

[out] Support User control on Intermediate Cache (i.e. Resize SLM section vs Generic Cache)

size_t intermediateCacheSize

[out] Per-cache Intermediate Cache (L1/L2) size, in bytes

uint32_t intermediateCachelineSize

[out] Cacheline size in bytes for intermediate cacheline (L1/L2).

ze_bool_t lastLevelCacheSizeControlSupported

[out] Support User control on Last Level Cache (i.e. Resize SLM section vs Generic Cache).

size_t lastLevelCacheSize

[out] Per-cache Last Level Cache (L3) size, in bytes

uint32_t lastLevelCachelineSize

[out] Cacheline size in bytes for last-level cacheline (L3).

ze_device_image_properties_t

struct ze_device_image_properties_t

Device image 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

ze_bool_t supported

[out] Supports reading and writing of images. See ::zeImageGetProperties for format-specific capabilities.

uint32_t maxImageDims1D

[out] Maximum image dimensions for 1D resources.

uint32_t maxImageDims2D

[out] Maximum image dimensions for 2D resources.

uint32_t maxImageDims3D

[out] Maximum image dimensions for 3D resources.

uint64_t maxImageBufferSize

[out] Maximum image buffer size in bytes.

uint32_t maxImageArraySlices

[out] Maximum image array slices

uint32_t maxSamplers

[out] Max samplers that can be used in kernel.

uint32_t maxReadImageArgs

[out] Returns the maximum number of simultaneous image objects that can be read from by a kernel.

uint32_t maxWriteImageArgs

[out] Returns the maximum number of simultaneous image objects that can be written to by a kernel.

ze_device_p2p_properties_t

struct ze_device_p2p_properties_t

Device 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_bool_t accessSupported

[out] Supports access between peer devices.

ze_bool_t atomicsSupported

[out] Supports atomics between peer devices.

Cmdqueue

Cmdqueue Functions

zeCommandQueueCreate

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

Creates a command queue on the device.

Parameters

  • hDevice: handle of the device object

  • desc: pointer to command queue descriptor

  • phCommandQueue: pointer to handle of command queue object created

  • The command queue can only be used on the device on which it was created.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clCreateCommandQueue

Return

zeCommandQueueDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueDestroy(ze_command_queue_handle_t hCommandQueue)

Destroys a command queue.

Parameters

  • hCommandQueue: [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 should be lock-free.

Remark

Analogues

  • clReleaseCommandQueue

Return

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: handle of the command queue

  • numCommandLists: number of command lists to execute

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkQueueSubmit

Return

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: handle of the command queue

  • timeout: 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

Cmdqueue Enums

ze_command_queue_flag_t

enum ze_command_queue_flag_t

Supported command queue flags.

Values:

ZE_COMMAND_QUEUE_FLAG_NONE = 0

default behavior

ZE_COMMAND_QUEUE_FLAG_SINGLE_SLICE_ONLY = ZE_BIT(0)

command queue reserves and cannot comsume more than a single slice.

ZE_COMMAND_QUEUE_FLAG_EXPLICIT_ONLY = ZE_BIT(1)

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_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

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

ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS

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

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_LOW

lower priority than normal

ZE_COMMAND_QUEUE_PRIORITY_HIGH

higher priority than normal

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 set

ze_command_queue_flag_t flags

[in] usage flags

ze_command_queue_mode_t mode

[in] operation mode

ze_command_queue_priority_t priority

[in] priority

Cmdlist

Cmdlist Functions

zeCommandListCreate

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

Creates a command list on the device for submitting commands to any command queue.

Parameters

  • hDevice: handle of the device object

  • desc: pointer to command list descriptor

  • phCommandList: pointer to handle of command list object created

  • The command list can only be used on the device on which it was created.

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

  • The application may call this function from simultaneous threads.

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

Return

zeCommandListCreateImmediate

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

Creates a command list on the device with an implicit command queue for immediate submission of commands.

Parameters

  • hDevice: handle of the device object

  • altdesc: pointer to command queue descriptor

  • phCommandList: pointer to handle of command list object created

  • The command list can only be used on the device on which it was created.

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

  • The application may call this function from simultaneous threads.

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

Return

zeCommandListDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListDestroy(ze_command_list_handle_t hCommandList)

Destroys a command list.

Parameters

  • hCommandList: [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 should be lock-free.

Return

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: 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

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: 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

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: handle of the command list

  • dstptr: pointer to memory where timestamp value will be written; must be 8byte-aligned.

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

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

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

  • The memory pointed to by dstptr must be accessible by the device on which the command list is 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 not call this function from simultaneous threads with the same command list handle.

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

Return

Cmdlist Enums

ze_command_list_flag_t

enum ze_command_list_flag_t

Supported command list creation flags.

Values:

ZE_COMMAND_LIST_FLAG_NONE = 0

default behavior

ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING = ZE_BIT(0)

driver may reorder programs and 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 dexecution 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.

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

[in] creation flags

Barrier

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: handle of the command list

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

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

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

  • 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 signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of the command list

  • numRanges: number of memory ranges

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

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

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

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

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

  • 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 signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

zeDeviceSystemBarrier

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceSystemBarrier(ze_device_handle_t hDevice)

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

Parameters

  • hDevice: 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

Copy

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: handle of command list

  • dstptr: pointer to destination memory to copy to

  • srcptr: pointer to source memory to copy from

  • size: size in bytes to copy

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

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

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

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

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • ptr: pointer to memory to initialize

  • pattern: pointer to value to initialize memory to

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

  • size: size in bytes to initialize

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

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

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

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

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

  • The pattern size must be a power of two.

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • dstptr: pointer to destination memory to copy to

  • dstRegion: pointer to destination region to copy to

  • dstPitch: destination pitch in bytes

  • dstSlicePitch: 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: pointer to source memory to copy from

  • srcRegion: pointer to source region to copy from

  • srcPitch: source pitch in bytes

  • srcSlicePitch: 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: [optional] handle of the event to signal on completion

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

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

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

  • 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 signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • hDstImage: handle of destination image to copy to

  • hSrcImage: handle of source image to copy from

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

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

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

  • Images format descriptors for both source and destination images must be the same.

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • hDstImage: handle of destination image to copy to

  • hSrcImage: handle of source image to copy from

  • pDstRegion: [optional] destination region descriptor

  • pSrcRegion: [optional] source region descriptor

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

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

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

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

  • Images format descriptors for both source and destination images must be the same.

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • dstptr: pointer to destination memory to copy to

  • hSrcImage: handle of source image to copy from

  • pSrcRegion: [optional] source region descriptor

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

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

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

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

  • Media formats are not supported for this function.

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • hDstImage: handle of destination image to copy to

  • srcptr: pointer to source memory to copy from

  • pDstRegion: [optional] destination region descriptor

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

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

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

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

  • Media formats are not supported for this function.

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of command list

  • ptr: pointer to start of the memory range to prefetch

  • size: 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 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

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: handle of command list

  • hDevice: device associated with the memory advice

  • ptr: Pointer to the start of the memory range

  • size: Size in bytes of the memory range

  • advice: 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 not call this function from simultaneous threads with the same command list handle.

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

Return

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

removes the affect of ZE_MEMORY_ADVICE_SET_READ_MOSTLY

ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION

hint that the preferred memory location is the specified device

ZE_MEMORY_ADVICE_CLEAR_PREFERRED_LOCATION

removes the affect of ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION

ZE_MEMORY_ADVICE_SET_ACCESSED_BY

hint that memory will be accessed by the specified device

ZE_MEMORY_ADVICE_CLEAR_ACCESSED_BY

removes the affect of ZE_MEMORY_ADVICE_SET_ACCESSED_BY

ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY

hints that memory will mostly be accessed non-atomically

ZE_MEMORY_ADVICE_CLEAR_NON_ATOMIC_MOSTLY

removes the affect of ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY

ZE_MEMORY_ADVICE_BIAS_CACHED

hints that memory should be cached

ZE_MEMORY_ADVICE_BIAS_UNCACHED

hints that memory should be not be cached

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

Event Functions

zeEventPoolCreate

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

Creates a pool for a set of event(s) for the driver.

Parameters

  • hDriver: handle of the driver instance

  • desc: pointer to event pool descriptor

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

  • phDevices: [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: pointer handle of event pool object created

  • The application may call this function from simultaneous threads.

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

Return

zeEventPoolDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolDestroy(ze_event_pool_handle_t hEventPool)

Deletes an event pool object.

Parameters

  • hEventPool: [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 should be lock-free.

Return

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 on the device.

Parameters

  • hEventPool: handle of the event pool

  • desc: pointer to event descriptor

  • phEvent: pointer to handle of event object created

  • Multiple events cannot be created using the same location within the same pool.

  • 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

zeEventDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventDestroy(ze_event_handle_t hEvent)

Deletes an event object.

Parameters

  • hEvent: [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

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: handle of event pool object

  • phIpc: 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

zeEventPoolOpenIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolOpenIpcHandle(ze_driver_handle_t hDriver, 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

  • hDriver: handle of the driver to associate with the IPC event pool handle

  • hIpc: IPC event handle

  • phEventPool: pointer handle of event pool object created

Return

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: [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

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: handle of the command list

  • hEvent: handle of the event

  • The event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • 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

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: handle of the command list

  • numEvents: number of events to wait on before continuing

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

  • 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

zeEventHostSignal

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostSignal(ze_event_handle_t hEvent)

Signals a event from host.

Parameters

  • hEvent: handle of the event

  • The event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clSetUserEventStatus

Return

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: handle of the event

  • timeout: 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

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: 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

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: handle of the command list

  • hEvent: handle of the event

  • 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

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: 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

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: handle of the event

  • dstptr: pointer to memory for where timestamp result will be written.

  • The event must have been 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

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: handle of the command list

  • numEvents: the number of timestamp events to query

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

  • dstptr: pointer to memory where ze_kernel_timestamp_result_t will be written; must be size-aligned.

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

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

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

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

  • The events must have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • The memory pointed to by both dstptr and pOffsets must be accessible by the device on which the command list is 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 not call this function from simultaneous threads with the same command list handle.

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

Return

Event Enums

ze_event_pool_flag_t

enum ze_event_pool_flag_t

Supported event pool creation flags.

Values:

ZE_EVENT_POOL_FLAG_DEFAULT = 0

signals and waits visible to the entire device and peer devices

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_scope_flag_t

enum ze_event_scope_flag_t

Supported event scope flags.

Values:

ZE_EVENT_SCOPE_FLAG_NONE = 0

execution synchronization only; no cache hierarchies are flushed or invalidated

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

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

[in] creation flags

uint32_t count

[in] number of events within the pool

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_flag_t signal

[in] defines the scope of relevant cache hierarchies to flush on a signal action before the event is triggered

ze_event_scope_flag_t wait

[in] defines the scope of relevant cache hierarchies to invalidate on a wait action after the event is complete

ze_kernel_timestamp_data_t

struct ze_kernel_timestamp_data_t

Kernel timestamp clock data.

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

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 object on the device’s command queue.

Parameters

  • hCommandQueue: handle of command queue

  • desc: pointer to fence descriptor

  • phFence: pointer to handle of fence object created

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkCreateFence

Return

zeFenceDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceDestroy(ze_fence_handle_t hFence)

Deletes a fence object.

Parameters

  • hFence: [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 should be lock-free.

Remark

Analogues

  • vkDestroyFence

Return

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: handle of the fence

  • timeout: 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

zeFenceQueryStatus

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceQueryStatus(ze_fence_handle_t hFence)

Queries a fence object’s status.

Parameters

  • hFence: 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

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: 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

Fence Enums

ze_fence_flag_t

enum ze_fence_flag_t

Supported fence creation flags.

Values:

ZE_FENCE_FLAG_NONE = 0

default behavior

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

[in] creation flags

Image

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: handle of the device

  • desc: pointer to image descriptor

  • pImageProperties: pointer to image properties

  • The application may call this function from simultaneous threads.

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

Return

zeImageCreate

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

Creates an image object on the device.

Parameters

  • hDevice: handle of the device

  • desc: pointer to image descriptor

  • phImage: pointer to handle of image object created

  • The image is only visible to the device on which it was created.

  • The image can be copied to another device using the ::zeCommandListAppendImageCopy functions.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clCreateImage

Return

zeImageDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageDestroy(ze_image_handle_t hImage)

Deletes an image object.

Parameters

  • hImage: [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 should be lock-free.

Return

Image Enums

ze_image_flag_t

enum ze_image_flag_t

Supported image creation flags.

Values:

ZE_IMAGE_FLAG_PROGRAM_READ = ZE_BIT(0)

programs will read contents

ZE_IMAGE_FLAG_PROGRAM_WRITE = ZE_BIT(1)

programs will write contents

ZE_IMAGE_FLAG_BIAS_CACHED = ZE_BIT(2)

device should cache contents

ZE_IMAGE_FLAG_BIAS_UNCACHED = ZE_BIT(3)

device should not cache contents

ze_image_type_t

enum ze_image_type_t

Supported image types.

Values:

ZE_IMAGE_TYPE_1D

1D

ZE_IMAGE_TYPE_1DARRAY

1D array

ZE_IMAGE_TYPE_2D

2D

ZE_IMAGE_TYPE_2DARRAY

2D array

ZE_IMAGE_TYPE_3D

3D

ZE_IMAGE_TYPE_BUFFER

Buffer.

ze_image_format_layout_t

enum ze_image_format_layout_t

Supported image format layouts.

Values:

ZE_IMAGE_FORMAT_LAYOUT_8

8-bit single component layout

ZE_IMAGE_FORMAT_LAYOUT_16

16-bit single component layout

ZE_IMAGE_FORMAT_LAYOUT_32

32-bit single component layout

ZE_IMAGE_FORMAT_LAYOUT_8_8

2-component 8-bit layout

ZE_IMAGE_FORMAT_LAYOUT_8_8_8_8

4-component 8-bit layout

ZE_IMAGE_FORMAT_LAYOUT_16_16

2-component 16-bit layout

ZE_IMAGE_FORMAT_LAYOUT_16_16_16_16

4-component 16-bit layout

ZE_IMAGE_FORMAT_LAYOUT_32_32

2-component 32-bit layout

ZE_IMAGE_FORMAT_LAYOUT_32_32_32_32

4-component 32-bit layout

ZE_IMAGE_FORMAT_LAYOUT_10_10_10_2

4-component 10_10_10_2 layout

ZE_IMAGE_FORMAT_LAYOUT_11_11_10

3-component 11_11_10 layout

ZE_IMAGE_FORMAT_LAYOUT_5_6_5

3-component 5_6_5 layout

ZE_IMAGE_FORMAT_LAYOUT_5_5_5_1

4-component 5_5_5_1 layout

ZE_IMAGE_FORMAT_LAYOUT_4_4_4_4

4-component 4_4_4_4 layout

ZE_IMAGE_FORMAT_LAYOUT_Y8

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

ZE_IMAGE_FORMAT_LAYOUT_NV12

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

ZE_IMAGE_FORMAT_LAYOUT_YUYV

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

ZE_IMAGE_FORMAT_LAYOUT_VYUY

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

ZE_IMAGE_FORMAT_LAYOUT_YVYU

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

ZE_IMAGE_FORMAT_LAYOUT_UYVY

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

ZE_IMAGE_FORMAT_LAYOUT_AYUV

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

ZE_IMAGE_FORMAT_LAYOUT_P010

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

ZE_IMAGE_FORMAT_LAYOUT_Y410

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

ZE_IMAGE_FORMAT_LAYOUT_P012

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

ZE_IMAGE_FORMAT_LAYOUT_Y16

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

ZE_IMAGE_FORMAT_LAYOUT_P016

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

ZE_IMAGE_FORMAT_LAYOUT_Y216

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

ZE_IMAGE_FORMAT_LAYOUT_P216

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

ze_image_format_type_t

enum ze_image_format_type_t

Supported image format types.

Values:

ZE_IMAGE_FORMAT_TYPE_UINT

Unsigned integer.

ZE_IMAGE_FORMAT_TYPE_SINT

Signed integer.

ZE_IMAGE_FORMAT_TYPE_UNORM

Unsigned normalized integer.

ZE_IMAGE_FORMAT_TYPE_SNORM

Signed normalized integer.

ZE_IMAGE_FORMAT_TYPE_FLOAT

Float.

ze_image_format_swizzle_t

enum ze_image_format_swizzle_t

Supported image format component swizzle into channel.

Values:

ZE_IMAGE_FORMAT_SWIZZLE_R

Red component.

ZE_IMAGE_FORMAT_SWIZZLE_G

Green component.

ZE_IMAGE_FORMAT_SWIZZLE_B

Blue component.

ZE_IMAGE_FORMAT_SWIZZLE_A

Alpha component.

ZE_IMAGE_FORMAT_SWIZZLE_0

Zero.

ZE_IMAGE_FORMAT_SWIZZLE_1

One.

ZE_IMAGE_FORMAT_SWIZZLE_X

Don’t care.

ze_image_sampler_filter_flags_t

enum ze_image_sampler_filter_flags_t

Supported sampler filtering flags.

Values:

ZE_IMAGE_SAMPLER_FILTER_FLAGS_NONE = 0

device does not support filtering

ZE_IMAGE_SAMPLER_FILTER_FLAGS_POINT = ZE_BIT(0)

device supports point filtering

ZE_IMAGE_SAMPLER_FILTER_FLAGS_LINEAR = ZE_BIT(1)

device supports linear filtering

Image Structures

ze_image_format_desc_t

struct ze_image_format_desc_t

Image format descriptor.

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

[in] creation flags

ze_image_type_t type

[in] image type

ze_image_format_desc_t format

[in] image format

uint64_t width

[in] width in pixels for ze_image_type_t::1D/2D/3D and bytes for Buffer, see ze_device_image_properties_t::maxImageDims1D/2D/3D and maxImageBufferSize.

uint32_t height

[in] height in pixels (2D or 3D only), see ze_device_image_properties_t::maxImageDims2D/3D

uint32_t depth

[in] depth in pixels (3D only), see ze_device_image_properties_t::maxImageDims3D

uint32_t arraylevels

[in] array levels (array types only), see ze_device_image_properties_t::maxImageArraySlices

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

const void *pNext

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

ze_image_sampler_filter_flags_t samplerFilterFlags

[out] supported sampler filtering

Memory

Memory Functions

zeDriverAllocSharedMem

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverAllocSharedMem(ze_driver_handle_t hDriver, 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 memory that is shared between the host and one or more devices.

Parameters

  • hDriver: handle of the driver instance

  • device_desc: pointer to device mem alloc descriptor

  • host_desc: pointer to host mem alloc descriptor

  • size: size in bytes to allocate

  • alignment: minimum alignment in bytes for the allocation

  • hDevice: [optional] device handle to associate with

  • pptr: 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 may call this function from simultaneous threads.

Return

zeDriverAllocDeviceMem

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverAllocDeviceMem(ze_driver_handle_t hDriver, const ze_device_mem_alloc_desc_t *device_desc, size_t size, size_t alignment, ze_device_handle_t hDevice, void **pptr)

Allocates memory specific to a device.

Parameters

  • hDriver: handle of the driver instance

  • device_desc: pointer to device mem alloc descriptor

  • size: size in bytes to allocate

  • alignment: minimum alignment in bytes for the allocation

  • hDevice: handle of the device

  • pptr: pointer to device allocation

  • A device allocation is owned by a specific device.

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

  • The application may call this function from simultaneous threads.

Return

zeDriverAllocHostMem

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverAllocHostMem(ze_driver_handle_t hDriver, const ze_host_mem_alloc_desc_t *host_desc, size_t size, size_t alignment, void **pptr)

Allocates host memory.

Parameters

  • hDriver: handle of the driver instance

  • host_desc: pointer to host mem alloc descriptor

  • size: size in bytes to allocate

  • alignment: minimum alignment in bytes for the allocation

  • pptr: pointer to host allocation

  • A host allocation is owned by the host process.

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

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

  • The application may call this function from simultaneous threads.

Return

zeDriverFreeMem

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverFreeMem(ze_driver_handle_t hDriver, void *ptr)

Frees allocated host memory, device memory, or shared memory.

Parameters

  • hDriver: handle of the driver instance

  • ptr: [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.

Return

zeDriverGetMemAllocProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetMemAllocProperties(ze_driver_handle_t hDriver, const void *ptr, ze_memory_allocation_properties_t *pMemAllocProperties, ze_device_handle_t *phDevice)

Retrieves attributes of a memory allocation.

Parameters

  • hDriver: handle of the driver instance

  • ptr: memory pointer to query

  • pMemAllocProperties: query result for memory allocation properties

  • phDevice: [optional] device associated with this allocation

  • The application may call this function from simultaneous threads.

Return

zeDriverGetMemAddressRange

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetMemAddressRange(ze_driver_handle_t hDriver, const void *ptr, void **pBase, size_t *pSize)

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

Parameters

  • hDriver: handle of the driver instance

  • ptr: memory pointer to query

  • pBase: [optional] base address of the allocation

  • pSize: [optional] size of the allocation

  • The application may call this function from simultaneous threads.

Return

zeDriverGetMemIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetMemIpcHandle(ze_driver_handle_t hDriver, const void *ptr, ze_ipc_mem_handle_t *pIpcHandle)

Creates an IPC memory handle for the specified allocation.

Parameters

  • hDriver: handle of the driver instance

  • ptr: pointer to the device memory allocation

  • pIpcHandle: Returned IPC memory handle

  • Takes a pointer to the base of a device memory allocation and exports it for use in another process.

  • The application may call this function from simultaneous threads.

Return

zeDriverOpenMemIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverOpenMemIpcHandle(ze_driver_handle_t hDriver, ze_device_handle_t hDevice, ze_ipc_mem_handle_t handle, ze_ipc_memory_flag_t flags, void **pptr)

Opens an IPC memory handle to retrieve a device pointer.

Parameters

  • hDriver: handle of the driver instance

  • hDevice: handle of the device to associate with the IPC memory handle

  • handle: IPC memory handle

  • flags: flags controlling the operation

  • pptr: 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 zeDriverFreeMem, but rather with zeDriverCloseMemIpcHandle.

  • The application may call this function from simultaneous threads.

Return

zeDriverCloseMemIpcHandle

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverCloseMemIpcHandle(ze_driver_handle_t hDriver, const void *ptr)

Closes an IPC memory handle.

Parameters

  • hDriver: handle of the driver instance

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

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

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

Return

Memory Enums

ze_device_mem_alloc_flag_t

enum ze_device_mem_alloc_flag_t

Supported memory allocation flags.

Values:

ZE_DEVICE_MEM_ALLOC_FLAG_DEFAULT = 0

implicit default behavior; uses driver-based heuristics

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_host_mem_alloc_flag_t

enum ze_host_mem_alloc_flag_t

Supported host memory allocation flags.

Values:

ZE_HOST_MEM_ALLOC_FLAG_DEFAULT = 0

implicit default behavior; uses driver-based heuristics

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_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

the memory pointed to is a host allocation

ZE_MEMORY_TYPE_DEVICE

the memory pointed to is a device allocation

ZE_MEMORY_TYPE_SHARED

the memory pointed to is a shared ownership allocation

ze_ipc_memory_flag_t

enum ze_ipc_memory_flag_t

Supported IPC memory flags.

Values:

ZE_IPC_MEMORY_FLAG_NONE = 0

No special flags.

Memory Structures

ze_device_mem_alloc_desc_t

struct ze_device_mem_alloc_desc_t

Device mem alloc 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_flag_t flags

[in] flags specifying additional allocation controls

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 mem alloc 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_flag_t flags

[in] flags specifying additional allocation controls

ze_memory_allocation_properties_t

struct ze_memory_allocation_properties_t

Memory allocation properties queried using zeDriverGetMemAllocProperties.

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

Module

Module Functions

zeModuleCreate

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

Creates module object from an input IL or native binary.

Parameters

  • hDevice: handle of the device

  • desc: pointer to module descriptor

  • phModule: pointer to handle of module object created

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

  • Compiles the module for execution on the device.

  • The module can only be used on the device on which it was created.

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

  • The following build 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.

  • 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 should be lock-free.

Return

zeModuleDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleDestroy(ze_module_handle_t hModule)

Destroys module.

Parameters

  • hModule: [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 should be lock-free.

Return

zeModuleBuildLogDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleBuildLogDestroy(ze_module_build_log_handle_t hModuleBuildLog)

Destroys module build log object.

Parameters

  • hModuleBuildLog: [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

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: handle of the module build log object.

  • pSize: size of build log string.

  • pBuildLog: [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

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: handle of the module

  • pSize: size of native binary in bytes.

  • pModuleNativeBinary: [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

zeModuleGetGlobalPointer

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

Retrieve global variable pointer from Module.

Parameters

  • hModule: handle of the module

  • pGlobalName: name of global variable in module

  • pptr: device visible pointer

  • The application may call this function from simultaneous threads.

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

Return

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: handle of the module

  • pCount: pointer to the number of names. if count is zero, then the driver will update the value with the total number of names available. if count is non-zero, then driver will only retrieve that number of names. if count is larger than the number of names available, then the driver will update the value with the correct number of names available.

  • pNames: [optional][range(0, *pCount)] array of names of functions

  • The application may call this function from simultaneous threads.

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

Return

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 object from a module by name.

Parameters

  • hModule: handle of the module

  • desc: pointer to kernel descriptor

  • phKernel: handle of the Function object

  • The application may call this function from simultaneous threads.

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

Return

zeKernelDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelDestroy(ze_kernel_handle_t hKernel)

Destroys a kernel object.

Parameters

  • hKernel: [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 should be lock-free.

Return

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: handle of the module

  • pFunctionName: Name of function to retrieve function pointer for.

  • pfnFunction: 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

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.

Parameters

  • hKernel: handle of the kernel object

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

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

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

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

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

  • The implementation will copy the group size information into a command list when the function is appended.

Return

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: handle of the kernel object

  • globalSizeX: global width for X dimension

  • globalSizeY: global width for Y dimension

  • globalSizeZ: global width for Z dimension

  • groupSizeX: recommended size of group for X dimension

  • groupSizeY: recommended size of group for Y dimension

  • groupSizeZ: recommended size of group for Z dimension

  • The application may call this function from simultaneous threads.

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

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

Return

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: handle of the kernel object

  • totalGroupCount: recommended total group count.

  • The application may call this function from simultaneous threads.

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

Return

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 used on kernel launch.

Parameters

  • hKernel: handle of the kernel object

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

  • argSize: size of argument type

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

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

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

  • The implementation will copy the arguments into a command list when the function is appended.

Return

zeKernelSetAttribute

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetAttribute(ze_kernel_handle_t hKernel, ze_kernel_attribute_t attr, uint32_t size, const void *pValue)

Sets a kernel attribute.

Parameters

  • hKernel: handle of the kernel object

  • attr: attribute to set

  • size: size in bytes of kernel attribute value.

  • pValue: [optional] pointer to attribute value.

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

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

Remark

Analogues

  • clSetKernelExecInfo

Return

zeKernelGetAttribute

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetAttribute(ze_kernel_handle_t hKernel, ze_kernel_attribute_t attr, uint32_t *pSize, void *pValue)

Gets a kernel attribute.

Parameters

  • hKernel: handle of the kernel object

  • attr: attribute to get. Documentation for ze_kernel_attribute_t for return type information for pValue.

  • pSize: size in bytes needed for kernel attribute value. If pValue is nullptr then the size needed for pValue memory will be written to pSize. Only need to query size for arbitrary sized attributes.

  • pValue: [optional] pointer to attribute value result.

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

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

  • The caller sets pValue to nullptr when querying only for size.

  • The caller must provide memory for pValue querying when querying size.

Return

zeKernelSetIntermediateCacheConfig

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetIntermediateCacheConfig(ze_kernel_handle_t hKernel, ze_cache_config_t CacheConfig)

Sets the preferred Intermediate cache configuration for a kernel.

Parameters

  • hKernel: handle of the kernel object

  • CacheConfig: CacheConfig

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

Return

zeKernelGetProperties

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

Retrieve kernel properties.

Parameters

  • hKernel: handle of the kernel object

  • pKernelProperties: query result for kernel properties.

  • The application may call this function from simultaneous threads.

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

Return

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: handle of the command list

  • hKernel: handle of the kernel object

  • pLaunchFuncArgs: thread group launch arguments

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

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

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

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

  • 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

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: handle of the command list

  • hKernel: handle of the kernel object

  • pLaunchFuncArgs: thread group launch arguments

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

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

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

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

  • 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

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: handle of the command list

  • hKernel: handle of the kernel object

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

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

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

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

  • The launch arguments need to be device visible.

  • The launch arguments buffer may not be reused until the function has completed on the device.

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

  • 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

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: handle of the command list

  • numKernels: maximum number of kernels to launch

  • phKernels: [range(0, numKernels)] handles of the kernel objects

  • pCountBuffer: 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: [range(0, numKernels)] pointer to device buffer that will contain a contiguous array of thread group launch arguments

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

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

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

  • The array of launch arguments need to be device visible.

  • The array of launch arguments buffer may not be reused until the kernel has completed on the device.

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

  • 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

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

Format is device native format.

ze_kernel_flag_t

enum ze_kernel_flag_t

Supported kernel creation flags.

Values:

ZE_KERNEL_FLAG_NONE = 0

default driver behavior

ZE_KERNEL_FLAG_FORCE_RESIDENCY

force all device allocations to be resident during execution

ze_kernel_attribute_t

enum ze_kernel_attribute_t

Kernel attributes.

Remark

Analogues

  • cl_kernel_exec_info

Values:

ZE_KERNEL_ATTRIBUTE_INDIRECT_HOST_ACCESS = 0

Indicates that the function accesses host allocations indirectly (default: false, type: bool_t)

ZE_KERNEL_ATTRIBUTE_INDIRECT_DEVICE_ACCESS

Indicates that the function accesses device allocations indirectly (default: false, type: bool_t)

ZE_KERNEL_ATTRIBUTE_INDIRECT_SHARED_ACCESS

Indicates that the function accesses shared allocations indirectly (default: false, type: bool_t)

ZE_KERNEL_ATTRIBUTE_SOURCE_ATTRIBUTE

Declared kernel attributes (i.e. can be specified with attribute in runtime language). (type: char[]) Returned as a null-terminated string and each attribute is separated by a space. zeKernelSetAttribute is not supported for this.

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] Pointer to array of IDs that is sized to numConstants.

const uint64_t *pConstantValues

[in] Pointer to array of 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. See programming guide for build flags.

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_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_flag_t flags

[in] creation flags

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.

char name[ZE_MAX_KERNEL_NAME]

[out] kernel name

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

Residency

Residency Functions

zeDeviceMakeMemoryResident

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceMakeMemoryResident(ze_device_handle_t hDevice, void *ptr, size_t size)

Makes memory resident for the device.

Parameters

  • hDevice: handle of the device

  • ptr: pointer to memory to make resident

  • size: 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

zeDeviceEvictMemory

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceEvictMemory(ze_device_handle_t hDevice, void *ptr, size_t size)

Allows memory to be evicted from the device.

Parameters

  • hDevice: handle of the device

  • ptr: pointer to memory to evict

  • size: 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

zeDeviceMakeImageResident

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceMakeImageResident(ze_device_handle_t hDevice, ze_image_handle_t hImage)

Makes image resident for the device.

Parameters

  • hDevice: handle of the device

  • hImage: 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

zeDeviceEvictImage

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceEvictImage(ze_device_handle_t hDevice, ze_image_handle_t hImage)

Allows image to be evicted from the device.

Parameters

  • hDevice: handle of the device

  • hImage: 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

Sampler

Sampler Functions

zeSamplerCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zeSamplerCreate(ze_device_handle_t hDevice, const ze_sampler_desc_t *desc, ze_sampler_handle_t *phSampler)

Creates sampler object.

Parameters

  • hDevice: handle of the device

  • desc: pointer to sampler descriptor

  • phSampler: handle of the sampler

  • The sampler can only be used on the device on which it was created.

  • The application may call this function from simultaneous threads.

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

Return

zeSamplerDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zeSamplerDestroy(ze_sampler_handle_t hSampler)

Destroys sampler object.

Parameters

  • hSampler: [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 module

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

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

Return

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

Out-of-bounds coordinates are wrapped back around.

ZE_SAMPLER_ADDRESS_MODE_CLAMP

Out-of-bounds coordinates are clamped to edge.

ZE_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

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

Out-of-bounds coordinates are mirrored starting from edge.

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

Out-of-bounds coordinates are wrapped back around.

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.