Ctrl+K

Core API

Contents

Core API#

oneAPI Level Zero Specification - Version 1.11

Common#

Common Enums#

ze_result_t#

enum ze_result_t#

Defines Return/Error codes.

Values:

enumerator ZE_RESULT_SUCCESS#

[Core] success

enumerator ZE_RESULT_NOT_READY#

[Core] synchronization primitive not signaled

enumerator ZE_RESULT_ERROR_DEVICE_LOST#

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

enumerator ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY#

[Core] insufficient host memory to satisfy call

enumerator ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY#

[Core] insufficient device memory to satisfy call

enumerator ZE_RESULT_ERROR_MODULE_BUILD_FAILURE#

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

enumerator ZE_RESULT_ERROR_MODULE_LINK_FAILURE#

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

enumerator ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET#

[Core] device requires a reset

enumerator ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE#

[Core] device currently in low power state

enumerator ZE_RESULT_EXP_ERROR_DEVICE_IS_NOT_VERTEX#

[Core, Experimental] device is not represented by a fabric vertex

enumerator ZE_RESULT_EXP_ERROR_VERTEX_IS_NOT_DEVICE#

[Core, Experimental] fabric vertex does not represent a device

enumerator ZE_RESULT_EXP_ERROR_REMOTE_DEVICE#

[Core, Experimental] fabric vertex represents a remote device or subdevice

enumerator ZE_RESULT_EXP_ERROR_OPERANDS_INCOMPATIBLE#

[Core, Experimental] operands of comparison are not compatible

enumerator ZE_RESULT_EXP_RTAS_BUILD_RETRY#

[Core, Experimental] ray tracing acceleration structure build operation failed due to insufficient resources, retry with a larger acceleration structure buffer allocation

enumerator ZE_RESULT_EXP_RTAS_BUILD_DEFERRED#

[Core, Experimental] ray tracing acceleration structure build operation deferred to parallel operation join

enumerator ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS#

[Sysman] access denied due to permission level

enumerator ZE_RESULT_ERROR_NOT_AVAILABLE#

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

enumerator ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE#

[Common] external required dependency is unavailable or missing

enumerator ZE_RESULT_WARNING_DROPPED_DATA#

[Tools] data may have been dropped

enumerator ZE_RESULT_ERROR_UNINITIALIZED#

[Validation] driver is not initialized

enumerator ZE_RESULT_ERROR_UNSUPPORTED_VERSION#

[Validation] generic error code for unsupported versions

enumerator ZE_RESULT_ERROR_UNSUPPORTED_FEATURE#

[Validation] generic error code for unsupported features

enumerator ZE_RESULT_ERROR_INVALID_ARGUMENT#

[Validation] generic error code for invalid arguments

enumerator ZE_RESULT_ERROR_INVALID_NULL_HANDLE#

[Validation] handle argument is not valid

enumerator ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE#

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

enumerator ZE_RESULT_ERROR_INVALID_NULL_POINTER#

[Validation] pointer argument may not be nullptr

enumerator ZE_RESULT_ERROR_INVALID_SIZE#

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

enumerator ZE_RESULT_ERROR_UNSUPPORTED_SIZE#

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

enumerator ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT#

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

enumerator ZE_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT#

[Validation] synchronization object in invalid state

enumerator ZE_RESULT_ERROR_INVALID_ENUMERATION#

[Validation] enumerator argument is not valid

enumerator ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION#

[Validation] enumerator argument is not supported by the device

enumerator ZE_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT#

[Validation] image format is not supported by the device

enumerator ZE_RESULT_ERROR_INVALID_NATIVE_BINARY#

[Validation] native binary is not supported by the device

enumerator ZE_RESULT_ERROR_INVALID_GLOBAL_NAME#

[Validation] global variable is not found in the module

enumerator ZE_RESULT_ERROR_INVALID_KERNEL_NAME#

[Validation] kernel name is not found in the module

enumerator ZE_RESULT_ERROR_INVALID_FUNCTION_NAME#

[Validation] function name is not found in the module

enumerator ZE_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION#

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

enumerator ZE_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION#

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

enumerator ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX#

[Validation] kernel argument index is not valid for kernel

enumerator ZE_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE#

[Validation] kernel argument size does not match kernel

enumerator ZE_RESULT_ERROR_INVALID_KERNEL_ATTRIBUTE_VALUE#

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

enumerator ZE_RESULT_ERROR_INVALID_MODULE_UNLINKED#

[Validation] module with imports needs to be linked before kernels can be created from it.

enumerator ZE_RESULT_ERROR_INVALID_COMMAND_LIST_TYPE#

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

enumerator ZE_RESULT_ERROR_OVERLAPPING_REGIONS#

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

enumerator ZE_RESULT_WARNING_ACTION_REQUIRED#

[Sysman] an action is required to complete the desired operation

enumerator ZE_RESULT_ERROR_INVALID_KERNEL_HANDLE#

[Core, Validation] kernel handle is invalid for the operation

enumerator ZE_RESULT_ERROR_UNKNOWN#

[Core] unknown or internal error

enumerator ZE_RESULT_FORCE_UINT32#

ze_structure_type_t#

enum ze_structure_type_t#

Defines structure types.

Values:

enumerator ZE_STRUCTURE_TYPE_DRIVER_PROPERTIES#

ze_driver_properties_t

enumerator ZE_STRUCTURE_TYPE_DRIVER_IPC_PROPERTIES#

ze_driver_ipc_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES#

ze_device_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_COMPUTE_PROPERTIES#

ze_device_compute_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_MODULE_PROPERTIES#

ze_device_module_properties_t

enumerator ZE_STRUCTURE_TYPE_COMMAND_QUEUE_GROUP_PROPERTIES#

ze_command_queue_group_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_MEMORY_PROPERTIES#

ze_device_memory_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_MEMORY_ACCESS_PROPERTIES#

ze_device_memory_access_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_CACHE_PROPERTIES#

ze_device_cache_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_IMAGE_PROPERTIES#

ze_device_image_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_P2P_PROPERTIES#

ze_device_p2p_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_EXTERNAL_MEMORY_PROPERTIES#

ze_device_external_memory_properties_t

enumerator ZE_STRUCTURE_TYPE_CONTEXT_DESC#

ze_context_desc_t

enumerator ZE_STRUCTURE_TYPE_COMMAND_QUEUE_DESC#

ze_command_queue_desc_t

enumerator ZE_STRUCTURE_TYPE_COMMAND_LIST_DESC#

ze_command_list_desc_t

enumerator ZE_STRUCTURE_TYPE_EVENT_POOL_DESC#

ze_event_pool_desc_t

enumerator ZE_STRUCTURE_TYPE_EVENT_DESC#

ze_event_desc_t

enumerator ZE_STRUCTURE_TYPE_FENCE_DESC#

ze_fence_desc_t

enumerator ZE_STRUCTURE_TYPE_IMAGE_DESC#

ze_image_desc_t

enumerator ZE_STRUCTURE_TYPE_IMAGE_PROPERTIES#

ze_image_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_MEM_ALLOC_DESC#

ze_device_mem_alloc_desc_t

enumerator ZE_STRUCTURE_TYPE_HOST_MEM_ALLOC_DESC#

ze_host_mem_alloc_desc_t

enumerator ZE_STRUCTURE_TYPE_MEMORY_ALLOCATION_PROPERTIES#

ze_memory_allocation_properties_t

enumerator ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_EXPORT_DESC#

ze_external_memory_export_desc_t

enumerator ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMPORT_FD#

ze_external_memory_import_fd_t

enumerator ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_EXPORT_FD#

ze_external_memory_export_fd_t

enumerator ZE_STRUCTURE_TYPE_MODULE_DESC#

ze_module_desc_t

enumerator ZE_STRUCTURE_TYPE_MODULE_PROPERTIES#

ze_module_properties_t

enumerator ZE_STRUCTURE_TYPE_KERNEL_DESC#

ze_kernel_desc_t

enumerator ZE_STRUCTURE_TYPE_KERNEL_PROPERTIES#

ze_kernel_properties_t

enumerator ZE_STRUCTURE_TYPE_SAMPLER_DESC#

ze_sampler_desc_t

enumerator ZE_STRUCTURE_TYPE_PHYSICAL_MEM_DESC#

ze_physical_mem_desc_t

enumerator ZE_STRUCTURE_TYPE_KERNEL_PREFERRED_GROUP_SIZE_PROPERTIES#

ze_kernel_preferred_group_size_properties_t

enumerator ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMPORT_WIN32#

ze_external_memory_import_win32_handle_t

enumerator ZE_STRUCTURE_TYPE_EXTERNAL_MEMORY_EXPORT_WIN32#

ze_external_memory_export_win32_handle_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_RAYTRACING_EXT_PROPERTIES#

ze_device_raytracing_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_RAYTRACING_MEM_ALLOC_EXT_DESC#

ze_raytracing_mem_alloc_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_FLOAT_ATOMIC_EXT_PROPERTIES#

ze_float_atomic_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_CACHE_RESERVATION_EXT_DESC#

ze_cache_reservation_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_EU_COUNT_EXT#

ze_eu_count_ext_t

enumerator ZE_STRUCTURE_TYPE_SRGB_EXT_DESC#

ze_srgb_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_LINKAGE_INSPECTION_EXT_DESC#

ze_linkage_inspection_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_PCI_EXT_PROPERTIES#

ze_pci_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_DRIVER_MEMORY_FREE_EXT_PROPERTIES#

ze_driver_memory_free_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_MEMORY_FREE_EXT_DESC#

ze_memory_free_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_MEMORY_COMPRESSION_HINTS_EXT_DESC#

ze_memory_compression_hints_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_IMAGE_ALLOCATION_EXT_PROPERTIES#

ze_image_allocation_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_LUID_EXT_PROPERTIES#

ze_device_luid_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_MEMORY_EXT_PROPERTIES#

ze_device_memory_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_IP_VERSION_EXT#

ze_device_ip_version_ext_t

enumerator ZE_STRUCTURE_TYPE_IMAGE_VIEW_PLANAR_EXT_DESC#

ze_image_view_planar_ext_desc_t

enumerator ZE_STRUCTURE_TYPE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_PROPERTIES#

ze_event_query_kernel_timestamps_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_EVENT_QUERY_KERNEL_TIMESTAMPS_RESULTS_EXT_PROPERTIES#

ze_event_query_kernel_timestamps_results_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_KERNEL_MAX_GROUP_SIZE_EXT_PROPERTIES#

ze_kernel_max_group_size_ext_properties_t

enumerator ZE_STRUCTURE_TYPE_RELAXED_ALLOCATION_LIMITS_EXP_DESC#

ze_relaxed_allocation_limits_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MODULE_PROGRAM_EXP_DESC#

ze_module_program_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_SCHEDULING_HINT_EXP_PROPERTIES#

ze_scheduling_hint_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_SCHEDULING_HINT_EXP_DESC#

ze_scheduling_hint_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_IMAGE_VIEW_PLANAR_EXP_DESC#

ze_image_view_planar_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2#

ze_device_properties_t

enumerator ZE_STRUCTURE_TYPE_IMAGE_MEMORY_EXP_PROPERTIES#

ze_image_memory_properties_exp_t

enumerator ZE_STRUCTURE_TYPE_POWER_SAVING_HINT_EXP_DESC#

ze_context_power_saving_hint_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_COPY_BANDWIDTH_EXP_PROPERTIES#

ze_copy_bandwidth_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_DEVICE_P2P_BANDWIDTH_EXP_PROPERTIES#

ze_device_p2p_bandwidth_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_FABRIC_VERTEX_EXP_PROPERTIES#

ze_fabric_vertex_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_FABRIC_EDGE_EXP_PROPERTIES#

ze_fabric_edge_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_MEMORY_SUB_ALLOCATIONS_EXP_PROPERTIES#

ze_memory_sub_allocations_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_RTAS_BUILDER_EXP_DESC#

ze_rtas_builder_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_RTAS_BUILDER_BUILD_OP_EXP_DESC#

ze_rtas_builder_build_op_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_RTAS_BUILDER_EXP_PROPERTIES#

ze_rtas_builder_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_RTAS_PARALLEL_OPERATION_EXP_PROPERTIES#

ze_rtas_parallel_operation_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_RTAS_DEVICE_EXP_PROPERTIES#

ze_rtas_device_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_RTAS_GEOMETRY_AABBS_EXP_CB_PARAMS#

ze_rtas_geometry_aabbs_exp_cb_params_t

enumerator ZE_STRUCTURE_TYPE_COUNTER_BASED_EVENT_POOL_EXP_DESC#

ze_event_pool_counter_based_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_COMMAND_LIST_EXP_PROPERTIES#

ze_mutable_command_list_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_COMMAND_LIST_EXP_DESC#

ze_mutable_command_list_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_COMMAND_ID_EXP_DESC#

ze_mutable_command_id_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_COMMANDS_EXP_DESC#

ze_mutable_commands_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC#

ze_mutable_kernel_argument_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_GROUP_COUNT_EXP_DESC#

ze_mutable_group_count_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_GROUP_SIZE_EXP_DESC#

ze_mutable_group_size_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_GLOBAL_OFFSET_EXP_DESC#

ze_mutable_global_offset_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_PITCHED_ALLOC_DEVICE_EXP_PROPERTIES#

ze_device_pitched_alloc_exp_properties_t

enumerator ZE_STRUCTURE_TYPE_BINDLESS_IMAGE_EXP_DESC#

ze_image_bindless_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_PITCHED_IMAGE_EXP_DESC#

ze_image_pitched_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_MUTABLE_GRAPH_ARGUMENT_EXP_DESC#

ze_mutable_graph_argument_exp_desc_t

enumerator ZE_STRUCTURE_TYPE_INIT_DRIVER_TYPE_DESC#

ze_init_driver_type_desc_t

enumerator ZE_STRUCTURE_TYPE_FORCE_UINT32#

ze_external_memory_type_flags_t#

enum ze_external_memory_type_flag_t#

Values:

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_OPAQUE_FD#

an opaque POSIX file descriptor handle

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_DMA_BUF#

a file descriptor handle for a Linux dma_buf

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_OPAQUE_WIN32#

an NT handle

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_OPAQUE_WIN32_KMT#

a global share (KMT) handle

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_D3D11_TEXTURE#

an NT handle referring to a Direct3D 10 or 11 texture resource

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_D3D11_TEXTURE_KMT#

a global share (KMT) handle referring to a Direct3D 10 or 11 texture resource

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_D3D12_HEAP#

an NT handle referring to a Direct3D 12 heap resource

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_D3D12_RESOURCE#

an NT handle referring to a Direct3D 12 committed resource

enumerator ZE_EXTERNAL_MEMORY_TYPE_FLAG_FORCE_UINT32#

ze_bandwidth_unit_t#

enum ze_bandwidth_unit_t#

Bandwidth unit.

Values:

enumerator ZE_BANDWIDTH_UNIT_UNKNOWN#

The unit used for bandwidth is unknown.

enumerator ZE_BANDWIDTH_UNIT_BYTES_PER_NANOSEC#

Bandwidth is provided in bytes/nanosec.

enumerator ZE_BANDWIDTH_UNIT_BYTES_PER_CLOCK#

Bandwidth is provided in bytes/clock.

enumerator ZE_BANDWIDTH_UNIT_FORCE_UINT32#

ze_latency_unit_t#

enum ze_latency_unit_t#

Latency unit.

Values:

enumerator ZE_LATENCY_UNIT_UNKNOWN#

The unit used for latency is unknown.

enumerator ZE_LATENCY_UNIT_NANOSEC#

Latency is provided in nanosecs.

enumerator ZE_LATENCY_UNIT_CLOCK#

Latency is provided in clocks.

enumerator ZE_LATENCY_UNIT_HOP#

Latency is provided in hops (normalized so that the lowest latency link has a latency of 1 hop)

enumerator ZE_LATENCY_UNIT_FORCE_UINT32#

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_uuid_t#

struct ze_uuid_t#

Universal unique id (UUID)

Public Members

uint8_t id[ZE_MAX_UUID_SIZE]#

[out] opaque data representing a UUID

ze_base_cb_params_t#

struct ze_base_cb_params_t#

Base for all callback function parameter types.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

Driver#

Driver Functions#

zeInit#

ZE_APIEXPORT ze_result_t ZE_APICALL zeInit(ze_init_flags_t flags)#

Initialize the ‘oneAPI’ driver(s)

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

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

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

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

  • The application must call this function after forking new processes. Each forked process must call this function.

  • The application may call this function from simultaneous threads.

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

Parameters:

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

Returns:

zeDriverGet#

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

Retrieves driver instances.

  • A driver represents a collection of physical devices.

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetPlatformIDs

Parameters:

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

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

Returns:

zeInitDrivers#

ZE_APIEXPORT ze_result_t ZE_APICALL zeInitDrivers(uint32_t *pCount, ze_driver_handle_t *phDrivers, ze_init_driver_type_desc_t *desc)#

Initialize the ‘oneAPI’ driver(s) based on the driver types requested and retrieve the driver handles.

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

  • The application can call InitDrivers or zeInit to init the drivers on the system.

  • Calls to zeInit or InitDrivers will not alter the drivers retrieved thru either api.

  • Drivers init thru zeInit or InitDrivers will not be reInitialized once init in an application. The Loader will determine if the already init driver needs to be delivered to the user thru the init type flags.

  • Already init Drivers will not be uninitialized if the call to InitDrivers does not include that driver’s type. Those init drivers which don’t match the init flags will not have their driver handles returned to the user in that InitDrivers call.

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

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

  • A driver represents a collection of physical devices.

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

  • The drivers returned to the caller will be based on the init types which state the drivers to be included.

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

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

  • The application must call this function after forking new processes. Each forked process must call this function.

  • The application may call this function from simultaneous threads.

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

Parameters:

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

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

  • desc – [in] descriptor containing the driver type initialization details including ze_init_driver_type_flag_t combinations.

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • version – [out] api version

Returns:

zeDriverGetProperties#

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

Retrieves properties of the driver.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetPlatformInfo

Parameters:

  • hDriver – [in] handle of the driver instance

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkEnumerateInstanceExtensionProperties

Parameters:

  • hDriver – [in] handle of the driver instance

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

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

Returns:

zeDriverGetExtensionFunctionAddress#

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

Retrieves function pointer for vendor-specific or experimental extensions.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • name – [in] extension function name

  • ppFunctionAddress – [out] pointer to function pointer

Returns:

zeDriverGetLastErrorDescription#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverGetLastErrorDescription(ze_driver_handle_t hDriver, const char **ppString)#

Retrieves a string describing the last error code returned by the driver in the current thread.

  • String returned is thread local.

  • String is only updated on calls returning an error, i.e., not on calls returning ZE_RESULT_SUCCESS.

  • String may be empty if driver considers error code is already explicit enough to describe cause.

  • Memory pointed to by ppString is owned by the driver.

  • String returned is null-terminated.

Parameters:

  • hDriver – [in] handle of the driver instance

  • ppString – [in,out] pointer to a null-terminated array of characters describing cause of error.

Returns:

Driver Enums#

ze_init_flags_t#

enum ze_init_flag_t#

Values:

enumerator ZE_INIT_FLAG_GPU_ONLY#

only initialize GPU drivers

enumerator ZE_INIT_FLAG_VPU_ONLY#

only initialize VPU drivers

enumerator ZE_INIT_FLAG_FORCE_UINT32#

ze_init_driver_type_flags_t#

enum ze_init_driver_type_flag_t#

Values:

enumerator ZE_INIT_DRIVER_TYPE_FLAG_GPU#

initialize and retrieve GPU drivers

enumerator ZE_INIT_DRIVER_TYPE_FLAG_NPU#

initialize and retrieve NPU drivers

enumerator ZE_INIT_DRIVER_TYPE_FLAG_FORCE_UINT32#

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:

enumerator ZE_API_VERSION_1_0#

version 1.0

enumerator ZE_API_VERSION_1_1#

version 1.1

enumerator ZE_API_VERSION_1_2#

version 1.2

enumerator ZE_API_VERSION_1_3#

version 1.3

enumerator ZE_API_VERSION_1_4#

version 1.4

enumerator ZE_API_VERSION_1_5#

version 1.5

enumerator ZE_API_VERSION_1_6#

version 1.6

enumerator ZE_API_VERSION_1_7#

version 1.7

enumerator ZE_API_VERSION_1_8#

version 1.8

enumerator ZE_API_VERSION_1_9#

version 1.9

enumerator ZE_API_VERSION_1_10#

version 1.10

enumerator ZE_API_VERSION_1_11#

version 1.11

enumerator ZE_API_VERSION_CURRENT#

latest known version

enumerator ZE_API_VERSION_FORCE_UINT32#

ze_ipc_property_flags_t#

enum ze_ipc_property_flag_t#

Values:

enumerator ZE_IPC_PROPERTY_FLAG_MEMORY#

Supports passing memory allocations between processes. See zeMemGetIpcHandle.

enumerator ZE_IPC_PROPERTY_FLAG_EVENT_POOL#

Supports passing event pools between processes. See zeEventPoolGetIpcHandle.

enumerator ZE_IPC_PROPERTY_FLAG_FORCE_UINT32#

Driver Structures#

ze_init_driver_type_desc_t#

struct ze_init_driver_type_desc_t#

Init Driver Type descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_init_driver_type_flags_t flags#

[in] driver type init flags. must be a valid combination of ze_init_driver_type_flag_t or UINT32_MAX; driver types are init and retrieved based on these init flags in zeInitDrivers().

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_ipc_property_flags_t flags#

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

ze_driver_extension_properties_t#

struct ze_driver_extension_properties_t#

Extension properties queried using zeDriverGetExtensionProperties.

Public Members

char name[ZE_MAX_EXTENSION_NAME]#

[out] extension name

uint32_t version#

[out] extension version using ZE_MAKE_VERSION

Device#

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.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

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

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

Returns:

zeDeviceGetRootDevice#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetRootDevice(ze_device_handle_t hDevice, ze_device_handle_t *phRootDevice)#

Retrieves the root-device of a device handle.

  • When the device handle passed does not belong to any root-device, nullptr is returned.

  • Multiple calls to this function will return the same device handle.

  • The root-device handle returned by this function does not have access automatically to the resources created with the associated sub-device, unless those resources have been created with a context explicitly containing both handles.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] handle of the device object

  • phRootDevice – [in,out] parent root device.

Returns:

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.

  • When the device handle passed does not contain any sub-device, a pCount of 0 is returned.

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clCreateSubDevices

Parameters:

  • hDevice – [in] handle of the device object

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

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

Returns:

zeDeviceGetProperties#

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

Retrieves properties of the device.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Parameters:

  • hDevice – [in] handle of the device

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Parameters:

  • hDevice – [in] handle of the device

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] handle of the device

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

Returns:

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.

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

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkGetPhysicalDeviceQueueFamilyProperties

Parameters:

  • hDevice – [in] handle of the device

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

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

Returns:

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.

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

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Parameters:

  • hDevice – [in] handle of the device

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

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Parameters:

  • hDevice – [in] handle of the device

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

Returns:

zeDeviceGetCacheProperties#

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

Retrieves cache properties of the device.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetDeviceInfo

Parameters:

  • hDevice – [in] handle of the device

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

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

Returns:

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.

  • See zeImageGetProperties for format-specific capabilities.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] handle of the device

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

Returns:

zeDeviceGetExternalMemoryProperties#

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

Retrieves external memory import and export of the device.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] handle of the device

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

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

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

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

Returns:

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.

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

Parameters:

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

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

  • value – [out] returned access capability

Returns:

zeDeviceGetStatus#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetStatus(ze_device_handle_t hDevice)#

Returns current status of the device.

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

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

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

Parameters:

hDevice – [in] handle of the device

Returns:

zeDeviceGetGlobalTimestamps#

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

Returns synchronized Host and device global timestamps.

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

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

Parameters:

  • hDevice – [in] handle of the device

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

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

Returns:

Device Enums#

ze_device_type_t#

enum ze_device_type_t#

Supported device types.

Values:

enumerator ZE_DEVICE_TYPE_GPU#

Graphics Processing Unit.

enumerator ZE_DEVICE_TYPE_CPU#

Central Processing Unit.

enumerator ZE_DEVICE_TYPE_FPGA#

Field Programmable Gate Array.

enumerator ZE_DEVICE_TYPE_MCA#

Memory Copy Accelerator.

enumerator ZE_DEVICE_TYPE_VPU#

Vision Processing Unit.

enumerator ZE_DEVICE_TYPE_FORCE_UINT32#

ze_device_property_flags_t#

enum ze_device_property_flag_t#

Values:

enumerator ZE_DEVICE_PROPERTY_FLAG_INTEGRATED#

Device is integrated with the Host.

enumerator ZE_DEVICE_PROPERTY_FLAG_SUBDEVICE#

Device handle used for query represents a sub-device.

enumerator ZE_DEVICE_PROPERTY_FLAG_ECC#

Device supports error correction memory access.

enumerator ZE_DEVICE_PROPERTY_FLAG_ONDEMANDPAGING#

Device supports on-demand page-faulting.

enumerator ZE_DEVICE_PROPERTY_FLAG_FORCE_UINT32#

ze_device_module_flags_t#

enum ze_device_module_flag_t#

Values:

enumerator ZE_DEVICE_MODULE_FLAG_FP16#

Device supports 16-bit floating-point operations.

enumerator ZE_DEVICE_MODULE_FLAG_FP64#

Device supports 64-bit floating-point operations.

enumerator ZE_DEVICE_MODULE_FLAG_INT64_ATOMICS#

Device supports 64-bit atomic operations.

enumerator ZE_DEVICE_MODULE_FLAG_DP4A#

Device supports four component dot product and accumulate operations.

enumerator ZE_DEVICE_MODULE_FLAG_FORCE_UINT32#

ze_device_fp_flags_t#

enum ze_device_fp_flag_t#

Values:

enumerator ZE_DEVICE_FP_FLAG_DENORM#

Supports denorms.

enumerator ZE_DEVICE_FP_FLAG_INF_NAN#

Supports INF and quiet NaNs.

enumerator ZE_DEVICE_FP_FLAG_ROUND_TO_NEAREST#

Supports rounding to nearest even rounding mode.

enumerator ZE_DEVICE_FP_FLAG_ROUND_TO_ZERO#

Supports rounding to zero.

enumerator ZE_DEVICE_FP_FLAG_ROUND_TO_INF#

Supports rounding to both positive and negative INF.

enumerator ZE_DEVICE_FP_FLAG_FMA#

Supports IEEE754-2008 fused multiply-add.

enumerator ZE_DEVICE_FP_FLAG_ROUNDED_DIVIDE_SQRT#

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

enumerator ZE_DEVICE_FP_FLAG_SOFT_FLOAT#

Uses software implementation for basic floating-point operations.

enumerator ZE_DEVICE_FP_FLAG_FORCE_UINT32#

ze_command_queue_group_property_flags_t#

enum ze_command_queue_group_property_flag_t#

Values:

enumerator ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_COMPUTE#

Command queue group supports enqueing compute commands.

enumerator ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_COPY#

Command queue group supports enqueing copy commands.

enumerator ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_COOPERATIVE_KERNELS#

Command queue group supports cooperative kernels. See zeCommandListAppendLaunchCooperativeKernel for more details.

enumerator ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_METRICS#

Command queue groups supports metric queries.

enumerator ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_FORCE_UINT32#

ze_device_memory_property_flags_t#

enum ze_device_memory_property_flag_t#

Values:

enumerator ZE_DEVICE_MEMORY_PROPERTY_FLAG_TBD#

reserved for future use

enumerator ZE_DEVICE_MEMORY_PROPERTY_FLAG_FORCE_UINT32#

ze_memory_access_cap_flags_t#

enum ze_memory_access_cap_flag_t#

Values:

enumerator ZE_MEMORY_ACCESS_CAP_FLAG_RW#

Supports load/store access.

enumerator ZE_MEMORY_ACCESS_CAP_FLAG_ATOMIC#

Supports atomic access.

enumerator ZE_MEMORY_ACCESS_CAP_FLAG_CONCURRENT#

Supports concurrent access.

enumerator ZE_MEMORY_ACCESS_CAP_FLAG_CONCURRENT_ATOMIC#

Supports concurrent atomic access.

enumerator ZE_MEMORY_ACCESS_CAP_FLAG_FORCE_UINT32#

ze_device_cache_property_flags_t#

enum ze_device_cache_property_flag_t#

Values:

enumerator ZE_DEVICE_CACHE_PROPERTY_FLAG_USER_CONTROL#

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

enumerator ZE_DEVICE_CACHE_PROPERTY_FLAG_FORCE_UINT32#

ze_device_p2p_property_flags_t#

enum ze_device_p2p_property_flag_t#

Values:

enumerator ZE_DEVICE_P2P_PROPERTY_FLAG_ACCESS#

Device supports access between peer devices.

enumerator ZE_DEVICE_P2P_PROPERTY_FLAG_ATOMICS#

Device supports atomics between peer devices.

enumerator ZE_DEVICE_P2P_PROPERTY_FLAG_FORCE_UINT32#

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

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. Note, the device id uses little-endian format.

ze_device_property_flags_t flags#

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

uint32_t subdeviceId#

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

uint32_t coreClockRate#

[out] Clock rate for device core.

uint64_t maxMemAllocSize#

[out] Maximum memory allocation size.

uint32_t maxHardwareContexts#

[out] Maximum number of logical hardware contexts.

uint32_t maxCommandQueuePriority#

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

uint32_t numThreadsPerEU#

[out] Maximum number of threads per EU.

uint32_t physicalEUSimdWidth#

[out] The physical EU simd width.

uint32_t numEUsPerSubslice#

[out] Maximum number of EUs per sub-slice.

uint32_t numSubslicesPerSlice#

[out] Maximum number of sub-slices per slice.

uint32_t numSlices#

[out] Maximum number of slices.

uint64_t timerResolution#

[out] Returns the resolution of device timer used for profiling, timestamps, etc. When stype==ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES the units are in nanoseconds. When stype==ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 units are in cycles/sec

uint32_t timestampValidBits#

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

uint32_t kernelTimestampValidBits#

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

ze_device_uuid_t uuid#

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

char name[ZE_MAX_DEVICE_NAME]#

[out] Device name

ze_device_thread_t#

struct ze_device_thread_t#

Device thread identifier.

Public Members

uint32_t slice#

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

uint32_t subslice#

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

uint32_t eu#

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

uint32_t thread#

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

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t maxTotalGroupSize#

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

uint32_t maxGroupSizeX#

[out] Maximum items for X dimension in group

uint32_t maxGroupSizeY#

[out] Maximum items for Y dimension in group

uint32_t maxGroupSizeZ#

[out] Maximum items for Z dimension in group

uint32_t maxGroupCountX#

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

uint32_t maxGroupCountY#

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

uint32_t maxGroupCountZ#

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

uint32_t maxSharedLocalMemory#

[out] Maximum shared local memory per group.

uint32_t numSubGroupSizes#

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

uint32_t subGroupSizes[ZE_SUBGROUPSIZE_COUNT]#

[out] Size group sizes supported.

ze_native_kernel_uuid_t#

struct ze_native_kernel_uuid_t#

Native kernel universal unique id (UUID)

Public Members

uint8_t id[ZE_MAX_NATIVE_KERNEL_UUID_SIZE]#

[out] opaque data representing a native kernel UUID

ze_device_module_properties_t#

struct ze_device_module_properties_t#

Device module properties queried using zeDeviceGetModuleProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

uint32_t spirvVersionSupported#

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

ze_device_module_flags_t flags#

[out] 0 or a valid combination of ze_device_module_flag_t

ze_device_fp_flags_t fp16flags#

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

ze_device_fp_flags_t fp32flags#

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

ze_device_fp_flags_t fp64flags#

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

uint32_t maxArgumentsSize#

[out] Maximum kernel argument size that is supported.

uint32_t printfBufferSize#

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

ze_native_kernel_uuid_t nativeKernelSupported#

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

ze_command_queue_group_properties_t#

struct ze_command_queue_group_properties_t#

Command queue group properties queried using zeDeviceGetCommandQueueGroupProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_command_queue_group_property_flags_t flags#

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

size_t maxMemoryFillPatternSize#

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

uint32_t numQueues#

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

ze_device_memory_properties_t#

struct ze_device_memory_properties_t#

Device local memory properties queried using zeDeviceGetMemoryProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_device_memory_property_flags_t flags#

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

uint32_t maxClockRate#

[out] Maximum clock rate for device memory.

uint32_t maxBusWidth#

[out] Maximum bus width between device and memory.

uint64_t totalSize#

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

char name[ZE_MAX_DEVICE_NAME]#

[out] Memory name

ze_device_memory_access_properties_t#

struct ze_device_memory_access_properties_t#

Device memory access properties queried using zeDeviceGetMemoryAccessProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_memory_access_cap_flags_t hostAllocCapabilities#

[out] host memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

ze_memory_access_cap_flags_t deviceAllocCapabilities#

[out] device memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

ze_memory_access_cap_flags_t sharedSingleDeviceAllocCapabilities#

[out] shared, single-device memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

ze_memory_access_cap_flags_t sharedCrossDeviceAllocCapabilities#

[out] shared, cross-device memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

ze_memory_access_cap_flags_t sharedSystemAllocCapabilities#

[out] shared, system memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_device_cache_property_flags_t flags#

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

size_t cacheSize#

[out] Per-cache size, in bytes

ze_device_image_properties_t#

struct ze_device_image_properties_t#

Device image properties queried using zeDeviceGetImageProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

uint32_t maxImageDims1D#

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

uint32_t maxImageDims2D#

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

uint32_t maxImageDims3D#

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

uint64_t maxImageBufferSize#

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

uint32_t maxImageArraySlices#

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

uint32_t maxSamplers#

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

uint32_t maxReadImageArgs#

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

uint32_t maxWriteImageArgs#

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

ze_device_external_memory_properties_t#

struct ze_device_external_memory_properties_t#

Device external memory import and export properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_external_memory_type_flags_t memoryAllocationImportTypes#

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

ze_external_memory_type_flags_t memoryAllocationExportTypes#

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

ze_external_memory_type_flags_t imageImportTypes#

[out] Supported external memory import types for images.

ze_external_memory_type_flags_t imageExportTypes#

[out] Supported external memory export types for images.

ze_device_p2p_properties_t#

struct ze_device_p2p_properties_t#

Device peer-to-peer properties queried using zeDeviceGetP2PProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_device_p2p_property_flags_t flags#

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

Context#

Context Functions#

zeContextCreate#

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

Creates a context for the driver.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver object

  • desc – [in] pointer to context descriptor

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

Returns:

zeContextCreateEx#

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

Creates a context for the driver.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver object

  • desc – [in] pointer to context descriptor

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

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

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

Returns:

zeContextDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextDestroy(ze_context_handle_t hContext)#

Destroys a context.

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

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

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

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

Parameters:

hContext – [in][release] handle of context object to destroy

Returns:

zeContextGetStatus#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextGetStatus(ze_context_handle_t hContext)#

Returns current status of the context.

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

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

Parameters:

hContext – [in] handle of context object

Returns:

Context Enums#

ze_context_flags_t#

enum ze_context_flag_t#

Values:

enumerator ZE_CONTEXT_FLAG_TBD#

reserved for future use

enumerator ZE_CONTEXT_FLAG_FORCE_UINT32#

Context Structures#

ze_context_desc_t#

struct ze_context_desc_t#

Context descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_context_flags_t flags#

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

Cmdqueue#

Cmdqueue Functions#

zeCommandQueueCreate#

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

Creates a command queue on the context.

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clCreateCommandQueue

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • desc – [in] pointer to command queue descriptor

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

Returns:

zeCommandQueueDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueDestroy(ze_command_queue_handle_t hCommandQueue)#

Destroys a command queue.

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

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

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

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

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

Remark

Analogues

  • clReleaseCommandQueue

Parameters:

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

Returns:

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.

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

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

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

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

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

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

  • The application must ensure the command lists being executed are not immediate command lists.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkQueueSubmit

Parameters:

  • hCommandQueue – [in] handle of the command queue

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

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

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandQueue – [in] handle of the command queue

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

Returns:

zeCommandQueueGetOrdinal#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetOrdinal(ze_command_queue_handle_t hCommandQueue, uint32_t *pOrdinal)#

Gets the command queue group ordinal.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • pOrdinal – [out] command queue group ordinal

Returns:

zeCommandQueueGetIndex#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetIndex(ze_command_queue_handle_t hCommandQueue, uint32_t *pIndex)#

Gets the command queue index within the group.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • pIndex – [out] command queue index within the group

Returns:

Cmdqueue Enums#

ze_command_queue_flags_t#

enum ze_command_queue_flag_t#

Values:

enumerator ZE_COMMAND_QUEUE_FLAG_EXPLICIT_ONLY#

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.

enumerator ZE_COMMAND_QUEUE_FLAG_IN_ORDER#

To be used only when creating immediate command lists. Commands appended to the immediate command list are executed in-order, with driver implementation enforcing dependencies between them. Application is not required to have the signal event of a given command being the wait event of the next to define an in-order list, and application is allowed to pass signal and wait events to each appended command to implement more complex dependency graphs.

enumerator ZE_COMMAND_QUEUE_FLAG_FORCE_UINT32#

ze_command_queue_mode_t#

enum ze_command_queue_mode_t#

Supported command queue modes.

Values:

enumerator ZE_COMMAND_QUEUE_MODE_DEFAULT#

implicit default behavior; uses driver-based heuristics

enumerator ZE_COMMAND_QUEUE_MODE_SYNCHRONOUS#

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

enumerator ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS#

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

enumerator ZE_COMMAND_QUEUE_MODE_FORCE_UINT32#

ze_command_queue_priority_t#

enum ze_command_queue_priority_t#

Supported command queue priorities.

Values:

enumerator ZE_COMMAND_QUEUE_PRIORITY_NORMAL#

[default] normal priority

enumerator ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_LOW#

lower priority than normal

enumerator ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH#

higher priority than normal

enumerator ZE_COMMAND_QUEUE_PRIORITY_FORCE_UINT32#

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t ordinal#

[in] command queue group ordinal

uint32_t index#

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

ze_command_queue_flags_t flags#

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

ze_command_queue_mode_t mode#

[in] operation mode

ze_command_queue_priority_t priority#

[in] priority

Cmdlist#

Cmdlist Functions#

zeCommandListCreate#

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

Creates a command list on the context.

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

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • desc – [in] pointer to command list descriptor

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

Returns:

zeCommandListCreateImmediate#

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

Creates an immediate command list on the context.

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

  • An immediate command list creates an implicit command queue.

  • Immediate command lists must not be passed to zeCommandQueueExecuteCommandLists.

  • Commands appended into an immediate command list may execute synchronously, by blocking until the command is complete.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • altdesc – [in] pointer to command queue descriptor

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

Returns:

zeCommandListDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListDestroy(ze_command_list_handle_t hCommandList)#

Destroys a command list.

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

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

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

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

Parameters:

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

Returns:

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.

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

Parameters:

hCommandList – [in] handle of command list object to close

Returns:

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.

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

Parameters:

hCommandList – [in] handle of command list object to reset

Returns:

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.

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

  • The timestamp frequency can be queried from the timerResolution member of ze_device_properties_t.

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

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

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

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

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

Returns:

zeCommandListHostSynchronize#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListHostSynchronize(ze_command_list_handle_t hCommandList, uint64_t timeout)#

Synchronizes an immediate command list by waiting on the host for the completion of all commands previously submitted to it.

  • The application must call this function only with command lists created with zeCommandListCreateImmediate.

  • Waiting on one immediate command list shall not block the concurrent execution of commands appended to other immediate command lists created with either a different ordinal or different index.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandList – [in] handle of the immediate command list

  • timeout – [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then immediately returns the status of the immediate command list; 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.

Returns:

zeCommandListGetDeviceHandle#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetDeviceHandle(ze_command_list_handle_t hCommandList, ze_device_handle_t *phDevice)#

Gets the handle of the device on which the command list was created.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • phDevice – [out] handle of the device on which the command list was created

Returns:

zeCommandListGetContextHandle#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetContextHandle(ze_command_list_handle_t hCommandList, ze_context_handle_t *phContext)#

Gets the handle of the context on which the command list was created.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • phContext – [out] handle of the context on which the command list was created

Returns:

zeCommandListGetOrdinal#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetOrdinal(ze_command_list_handle_t hCommandList, uint32_t *pOrdinal)#

Gets the command queue group ordinal to which the command list is submitted.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • pOrdinal – [out] command queue group ordinal to which command list is submitted

Returns:

zeCommandListImmediateGetIndex#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListImmediateGetIndex(ze_command_list_handle_t hCommandListImmediate, uint32_t *pIndex)#

Gets the command queue index within the group to which the immediate command list is submitted.

  • The application must call this function only with command lists created with zeCommandListCreateImmediate.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandListImmediate – [in] handle of the immediate command list

  • pIndex – [out] command queue index within the group to which the immediate command list is submitted

Returns:

zeCommandListIsImmediate#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListIsImmediate(ze_command_list_handle_t hCommandList, ze_bool_t *pIsImmediate)#

Query whether a command list is an immediate command list.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • pIsImmediate – [out] Boolean indicating whether the command list is an immediate command list (true) or not (false)

Returns:

Cmdlist Enums#

ze_command_list_flags_t#

enum ze_command_list_flag_t#

Values:

enumerator ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING#

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

enumerator ZE_COMMAND_LIST_FLAG_MAXIMIZE_THROUGHPUT#

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

enumerator ZE_COMMAND_LIST_FLAG_EXPLICIT_ONLY#

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.

enumerator ZE_COMMAND_LIST_FLAG_IN_ORDER#

commands appended to this command list are executed in-order, with driver implementation enforcing dependencies between them. Application is not required to have the signal event of a given command being the wait event of the next to define an in-order list, and application is allowed to pass signal and wait events to each appended command to implement more complex dependency graphs. Cannot be combined with ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING.

enumerator ZE_COMMAND_LIST_FLAG_EXP_CLONEABLE#

this command list may be cloned using zeCommandListCreateCloneExp after zeCommandListClose.

enumerator ZE_COMMAND_LIST_FLAG_FORCE_UINT32#

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t commandQueueGroupOrdinal#

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

ze_command_list_flags_t flags#

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

Barrier#

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.

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

  • If numWaitEvents is zero, then all previous commands, enqueued on same command queue, must complete prior to the execution of the barrier. This is not the case when numWaitEvents is non-zero.

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

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

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

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

Remark

Analogues

  • vkCmdPipelineBarrier

  • clEnqueueBarrierWithWaitList

Parameters:

  • hCommandList – [in] handle of the command list

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

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

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

Returns:

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.

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

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • numRanges – [in] number of memory ranges

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

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

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

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

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

Returns:

zeContextSystemBarrier#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextSystemBarrier(ze_context_handle_t hContext, ze_device_handle_t hDevice)#

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

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

Returns:

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.

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

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

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

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

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

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

Remark

Analogues

  • clEnqueueCopyBuffer

  • clEnqueueReadBuffer

  • clEnqueueWriteBuffer

  • clEnqueueSVMMemcpy

Parameters:

  • hCommandList – [in] handle of command list

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

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

  • size – [in] size in bytes to copy

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

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

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

Returns:

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.

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

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

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

  • The pattern size must be a power-of-two and less than or equal to the maxMemoryFillPatternSize member of ze_command_queue_group_properties_t.

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

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

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

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

Remark

Analogues

  • clEnqueueFillBuffer

  • clEnqueueSVMMemFill

Parameters:

  • hCommandList – [in] handle of command list

  • ptr – [in] pointer to memory to initialize

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

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

  • size – [in] size in bytes to initialize

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

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

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

Returns:

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.

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

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

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

  • The src and dst regions cannot be overlapping.

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

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

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

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

Parameters:

  • hCommandList – [in] handle of command list

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

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

  • dstPitch – [in] destination pitch in bytes

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

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

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

  • srcPitch – [in] source pitch in bytes

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

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

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

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

Returns:

zeCommandListAppendMemoryCopyFromContext#

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

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

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

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

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of command list

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

  • hContextSrc – [in] handle of source context object

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

  • size – [in] size in bytes to copy

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

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

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

Returns:

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.

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

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

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

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

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

Remark

Analogues

  • clEnqueueCopyImage

Parameters:

  • hCommandList – [in] handle of command list

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

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

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

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

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

Returns:

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.

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

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

  • The src and dst regions cannot be overlapping.

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

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

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

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

Parameters:

  • hCommandList – [in] handle of command list

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

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

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

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

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

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

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

Returns:

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.

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

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

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

  • The application must ensure the image format descriptor for the source image is a single-planar format.

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

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

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

Remark

Analogues

  • clEnqueueReadImage

Parameters:

  • hCommandList – [in] handle of command list

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

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

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

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

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

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

Returns:

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.

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

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

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

  • The application must ensure the image format descriptor for the destination image is a single-planar format.

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

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

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

Remark

Analogues

  • clEnqueueWriteImage

Parameters:

  • hCommandList – [in] handle of command list

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

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

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

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

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

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

Returns:

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.

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

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

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

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

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

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

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

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

Remark

Analogues

  • clEnqueueSVMMigrateMem

Parameters:

  • hCommandList – [in] handle of command list

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

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

Returns:

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.

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

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

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

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of command list

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

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

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

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

Returns:

Copy Enums#

ze_memory_advice_t#

enum ze_memory_advice_t#

Supported memory advice hints.

Values:

enumerator ZE_MEMORY_ADVICE_SET_READ_MOSTLY#

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

enumerator ZE_MEMORY_ADVICE_CLEAR_READ_MOSTLY#

removes the effect of ZE_MEMORY_ADVICE_SET_READ_MOSTLY

enumerator ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION#

hint that the preferred memory location is the specified device

enumerator ZE_MEMORY_ADVICE_CLEAR_PREFERRED_LOCATION#

removes the effect of ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION

enumerator ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY#

hints that memory will mostly be accessed non-atomically

enumerator ZE_MEMORY_ADVICE_CLEAR_NON_ATOMIC_MOSTLY#

removes the effect of ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY

enumerator ZE_MEMORY_ADVICE_BIAS_CACHED#

hints that memory should be cached

enumerator ZE_MEMORY_ADVICE_BIAS_UNCACHED#

hints that memory should be not be cached

enumerator ZE_MEMORY_ADVICE_SET_SYSTEM_MEMORY_PREFERRED_LOCATION#

hint that the preferred memory location is host memory

enumerator ZE_MEMORY_ADVICE_CLEAR_SYSTEM_MEMORY_PREFERRED_LOCATION#

removes the effect of ZE_MEMORY_ADVICE_SET_SYSTEM_MEMORY_PREFERRED_LOCATION

enumerator ZE_MEMORY_ADVICE_FORCE_UINT32#

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_context_handle_t hContext, const ze_event_pool_desc_t *desc, uint32_t numDevices, ze_device_handle_t *phDevices, ze_event_pool_handle_t *phEventPool)#

Creates a pool of events on the context.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • desc – [in] pointer to event pool descriptor

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

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

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

Returns:

zeEventPoolDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolDestroy(ze_event_pool_handle_t hEventPool)#

Deletes an event pool object.

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

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

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

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

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

Parameters:

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

Returns:

zeEventCreate#

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

Creates an event from the pool.

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

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

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

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

Remark

Analogues

  • clCreateUserEvent

  • vkCreateEvent

Parameters:

  • hEventPool – [in] handle of the event pool

  • desc – [in] pointer to event descriptor

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

Returns:

zeEventDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventDestroy(ze_event_handle_t hEvent)#

Deletes an event object.

  • 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

Parameters:

hEvent – [in][release] handle of event object to destroy

Returns:

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.

  • Event pool must have been created with ZE_EVENT_POOL_FLAG_IPC.

  • The application may call this function from simultaneous threads.

Parameters:

  • hEventPool – [in] handle of event pool object

  • phIpc – [out] Returned IPC event handle

Returns:

zeEventPoolPutIpcHandle#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolPutIpcHandle(ze_context_handle_t hContext, ze_ipc_event_pool_handle_t hIpc)#

Returns an IPC event pool handle to the driver.

  • This call must be used for IPC handles previously obtained with zeEventPoolGetIpcHandle.

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

  • This call does not destroy the original event pool for which the IPC handle was created.

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

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

Parameters:

  • hContext – [in] handle of the context object associated with the IPC event pool handle

  • hIpc – [in] IPC event pool handle

Returns:

zeEventPoolOpenIpcHandle#

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

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

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

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

  • If the original event pool has been created for a device containing a number of sub-devices, then the event pool returned by this call may be used on a device containing the same number of sub-devices, or on any of those sub-devices.

  • However, if the original event pool has been created for a sub-device, then the event pool returned by this call cannot be used on a device containing any number of sub-devices, and must be used only in a sub-device. This ensures functional correctness for any implementation or optimizations the underlying Level Zero driver may do on event pools and events.

  • The application may call this function from simultaneous threads.

Parameters:

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

  • hIpc – [in] IPC event pool handle

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

Returns:

zeEventPoolCloseIpcHandle#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolCloseIpcHandle(ze_event_pool_handle_t hEventPool)#

Closes an IPC event handle in the current process.

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

Parameters:

hEventPool – [in][release] handle of event pool object

Returns:

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.

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

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

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

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

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

Remark

Analogues

  • clSetUserEventStatus

  • vkCmdSetEvent

Parameters:

  • hCommandList – [in] handle of the command list

  • hEvent – [in] handle of the event

Returns:

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.

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

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

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

Returns:

zeEventHostSignal#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostSignal(ze_event_handle_t hEvent)#

Signals a event from host.

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clSetUserEventStatus

Parameters:

hEvent – [in] handle of the event

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clWaitForEvents

Parameters:

  • hEvent – [in] handle of the event

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

Returns:

zeEventQueryStatus#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryStatus(ze_event_handle_t hEvent)#

Queries an event object’s status on the host.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetEventInfo

  • vkGetEventStatus

Parameters:

hEvent – [in] handle of the event

Returns:

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.

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

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

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

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

Remark

Analogues

  • vkResetEvent

Parameters:

  • hCommandList – [in] handle of the command list

  • hEvent – [in] handle of the event

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkResetEvent

Parameters:

hEvent – [in] handle of the event

Returns:

zeEventQueryKernelTimestamp#

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

Queries an event’s timestamp value on the host.

Parameters:

  • hEvent – [in] handle of the event

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

Returns:

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.

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

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

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

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

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

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

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

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

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

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

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

Returns:

zeEventGetEventPool#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetEventPool(ze_event_handle_t hEvent, ze_event_pool_handle_t *phEventPool)#

Gets the handle of the event pool for the event.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEvent – [in] handle of the event

  • phEventPool – [out] handle of the event pool for the event

Returns:

zeEventGetSignalScope#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetSignalScope(ze_event_handle_t hEvent, ze_event_scope_flags_t *pSignalScope)#

Gets the signal event scope.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEvent – [in] handle of the event

  • pSignalScope – [out] signal event scope. This is the scope of relevant cache hierarchies that are flushed on a signal action before the event is triggered. May be 0 or a valid combination of ze_event_scope_flag_t.

Returns:

zeEventGetWaitScope#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetWaitScope(ze_event_handle_t hEvent, ze_event_scope_flags_t *pWaitScope)#

Gets the wait event scope.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEvent – [in] handle of the event

  • pWaitScope – [out] wait event scope. This is the scope of relevant cache hierarchies invalidated on a wait action after the event is complete. May be 0 or a valid combination of ze_event_scope_flag_t.

Returns:

zeEventPoolGetContextHandle#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolGetContextHandle(ze_event_pool_handle_t hEventPool, ze_context_handle_t *phContext)#

Gets the handle of the context on which the event pool was created.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEventPool – [in] handle of the event pool

  • phContext – [out] handle of the context on which the event pool was created

Returns:

zeEventPoolGetFlags#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolGetFlags(ze_event_pool_handle_t hEventPool, ze_event_pool_flags_t *pFlags)#

Gets the creation flags used to create the event pool.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEventPool – [in] handle of the event pool

  • pFlags – [out] creation flags used to create the event pool; may be 0 or a valid combination of ze_event_pool_flag_t

Returns:

Event Enums#

ze_event_pool_flags_t#

enum ze_event_pool_flag_t#

Values:

enumerator ZE_EVENT_POOL_FLAG_HOST_VISIBLE#

signals and waits are also visible to host

enumerator ZE_EVENT_POOL_FLAG_IPC#

signals and waits may be shared across processes

enumerator ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP#

Indicates all events in pool will contain kernel timestamps.

enumerator ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP#

Indicates all events in pool will contain kernel timestamps synchronized to host time domain; cannot be combined with ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP

enumerator ZE_EVENT_POOL_FLAG_FORCE_UINT32#

ze_event_scope_flags_t#

enum ze_event_scope_flag_t#

Values:

enumerator ZE_EVENT_SCOPE_FLAG_SUBDEVICE#

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

enumerator ZE_EVENT_SCOPE_FLAG_DEVICE#

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

enumerator ZE_EVENT_SCOPE_FLAG_HOST#

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

enumerator ZE_EVENT_SCOPE_FLAG_FORCE_UINT32#

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_event_pool_flags_t flags#

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

uint32_t count#

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

ze_event_desc_t#

struct ze_event_desc_t#

Event descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

uint32_t index#

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

ze_event_scope_flags_t signal#

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

ze_event_scope_flags_t wait#

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

ze_kernel_timestamp_data_t#

struct ze_kernel_timestamp_data_t#

Kernel timestamp clock data.

  • The timestamp frequency can be queried from the timerResolution member of ze_device_properties_t.

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

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 for the command queue.

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

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkCreateFence

Parameters:

  • hCommandQueue – [in] handle of command queue

  • desc – [in] pointer to fence descriptor

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

Returns:

zeFenceDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceDestroy(ze_fence_handle_t hFence)#

Deletes a fence object.

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

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

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

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

Remark

Analogues

  • vkDestroyFence

Parameters:

hFence – [in][release] handle of fence object to destroy

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkWaitForFences

Parameters:

  • hFence – [in] handle of the fence

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

Returns:

zeFenceQueryStatus#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceQueryStatus(ze_fence_handle_t hFence)#

Queries a fence object’s status.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkGetFenceStatus

Parameters:

hFence – [in] handle of the fence

Returns:

zeFenceReset#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFenceReset(ze_fence_handle_t hFence)#

Reset a fence back to the not signaled state.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkResetFences

Parameters:

hFence – [in] handle of the fence

Returns:

Fence Enums#

ze_fence_flags_t#

enum ze_fence_flag_t#

Values:

enumerator ZE_FENCE_FLAG_SIGNALED#

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

enumerator ZE_FENCE_FLAG_FORCE_UINT32#

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_fence_flags_t flags#

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

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] handle of the device

  • desc – [in] pointer to image descriptor

  • pImageProperties – [out] pointer to image properties

Returns:

zeImageCreate#

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

Creates an image on the context.

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

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clCreateImage

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • desc – [in] pointer to image descriptor

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

Returns:

zeImageDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageDestroy(ze_image_handle_t hImage)#

Deletes an image object.

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

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

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

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

Parameters:

hImage – [in][release] handle of image object to destroy

Returns:

Image Enums#

ze_image_flags_t#

enum ze_image_flag_t#

Values:

enumerator ZE_IMAGE_FLAG_KERNEL_WRITE#

kernels will write contents

enumerator ZE_IMAGE_FLAG_BIAS_UNCACHED#

device should not cache contents

enumerator ZE_IMAGE_FLAG_FORCE_UINT32#

ze_image_type_t#

enum ze_image_type_t#

Supported image types.

Values:

enumerator ZE_IMAGE_TYPE_1D#

1D

enumerator ZE_IMAGE_TYPE_1DARRAY#

1D array

enumerator ZE_IMAGE_TYPE_2D#

2D

enumerator ZE_IMAGE_TYPE_2DARRAY#

2D array

enumerator ZE_IMAGE_TYPE_3D#

3D

enumerator ZE_IMAGE_TYPE_BUFFER#

Buffer.

enumerator ZE_IMAGE_TYPE_FORCE_UINT32#

ze_image_format_layout_t#

enum ze_image_format_layout_t#

Supported image format layouts.

Values:

enumerator ZE_IMAGE_FORMAT_LAYOUT_8#

8-bit single component layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_16#

16-bit single component layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_32#

32-bit single component layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_8_8#

2-component 8-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_8_8_8_8#

4-component 8-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_16_16#

2-component 16-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_16_16_16_16#

4-component 16-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_32_32#

2-component 32-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_32_32_32_32#

4-component 32-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_10_10_10_2#

4-component 10_10_10_2 layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_11_11_10#

3-component 11_11_10 layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_5_6_5#

3-component 5_6_5 layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_5_5_5_1#

4-component 5_5_5_1 layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_4_4_4_4#

4-component 4_4_4_4 layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_Y8#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_NV12#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_YUYV#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_VYUY#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_YVYU#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_UYVY#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_AYUV#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_P010#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_Y410#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_P012#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_Y16#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_P016#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_Y216#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_P216#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_P8#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_YUY2#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_A8P8#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_IA44#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_AI44#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_Y416#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_Y210#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_I420#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_YV12#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_400P#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_422H#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_422V#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_444P#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_RGBP#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_BRGP#

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

enumerator ZE_IMAGE_FORMAT_LAYOUT_8_8_8#

3-component 8-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_16_16_16#

3-component 16-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_32_32_32#

3-component 32-bit layout

enumerator ZE_IMAGE_FORMAT_LAYOUT_FORCE_UINT32#

ze_image_format_type_t#

enum ze_image_format_type_t#

Supported image format types.

Values:

enumerator ZE_IMAGE_FORMAT_TYPE_UINT#

Unsigned integer.

enumerator ZE_IMAGE_FORMAT_TYPE_SINT#

Signed integer.

enumerator ZE_IMAGE_FORMAT_TYPE_UNORM#

Unsigned normalized integer.

enumerator ZE_IMAGE_FORMAT_TYPE_SNORM#

Signed normalized integer.

enumerator ZE_IMAGE_FORMAT_TYPE_FLOAT#

Float.

enumerator ZE_IMAGE_FORMAT_TYPE_FORCE_UINT32#

ze_image_format_swizzle_t#

enum ze_image_format_swizzle_t#

Supported image format component swizzle into channel.

Values:

enumerator ZE_IMAGE_FORMAT_SWIZZLE_R#

Red component.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_G#

Green component.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_B#

Blue component.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_A#

Alpha component.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_0#

Zero.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_1#

One.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_X#

Don’t care.

enumerator ZE_IMAGE_FORMAT_SWIZZLE_FORCE_UINT32#

ze_image_sampler_filter_flags_t#

enum ze_image_sampler_filter_flag_t#

Values:

enumerator ZE_IMAGE_SAMPLER_FILTER_FLAG_POINT#

device supports point filtering

enumerator ZE_IMAGE_SAMPLER_FILTER_FLAG_LINEAR#

device supports linear filtering

enumerator ZE_IMAGE_SAMPLER_FILTER_FLAG_FORCE_UINT32#

Image Structures#

ze_image_format_t#

struct ze_image_format_t#

Image format.

Public Members

ze_image_format_layout_t layout#

[in] image format component layout (e.g. N-component layouts and media formats)

ze_image_format_type_t type#

[in] image format type

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_image_flags_t flags#

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

ze_image_type_t type#

[in] image type. Media format layouts are unsupported for ZE_IMAGE_TYPE_BUFFER

ze_image_format_t format#

[in] image format

uint64_t width#

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

uint32_t height#

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

uint32_t depth#

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

uint32_t arraylevels#

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

uint32_t miplevels#

[in] mipmap levels (must be 0)

ze_image_properties_t#

struct ze_image_properties_t#

Image properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_image_sampler_filter_flags_t samplerFilterFlags#

[out] supported sampler filtering. returns 0 (unsupported) or a combination of ze_image_sampler_filter_flag_t.

Memory#

Memory Functions#

zeMemAllocShared#

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

Allocates shared memory on the context.

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

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

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

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

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

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

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

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

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

  • pptr – [out] pointer to shared allocation

Returns:

zeMemAllocDevice#

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

Allocates device memory on the context.

  • Device allocations are owned by a specific device.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

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

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

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

  • hDevice – [in] handle of the device

  • pptr – [out] pointer to device allocation

Returns:

zeMemAllocHost#

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

Allocates host memory on the context.

  • Host allocations are owned by the host process.

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

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

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

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

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

  • pptr – [out] pointer to host allocation

Returns:

zeMemFree#

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

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

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

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

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

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

Parameters:

  • hContext – [in] handle of the context object

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

Returns:

zeMemGetAllocProperties#

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

Retrieves attributes of a memory allocation.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] memory pointer to query

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

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

Returns:

zeMemGetAddressRange#

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

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

  • The application may call this function from simultaneous threads.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] memory pointer to query

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

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

Returns:

zeMemGetIpcHandle#

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

Creates an IPC memory handle for the specified allocation.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

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

  • pIpcHandle – [out] Returned IPC memory handle

Returns:

zeMemGetIpcHandleFromFileDescriptorExp#

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

Creates an IPC memory handle out of a file descriptor.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • handle – [in] file descriptor

  • pIpcHandle – [out] Returned IPC memory handle

Returns:

zeMemGetFileDescriptorFromIpcHandleExp#

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

Gets the file descriptor contained in an IPC memory handle.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • ipcHandle – [in] IPC memory handle

  • pHandle – [out] Returned file descriptor

Returns:

zeMemPutIpcHandle#

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

Returns an IPC memory handle to the driver.

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

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

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

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

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

Parameters:

  • hContext – [in] handle of the context object

  • handle – [in] IPC memory handle

Returns:

zeMemOpenIpcHandle#

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

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

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

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

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

  • handle – [in] IPC memory handle

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

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

Returns:

zeMemCloseIpcHandle#

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

Closes an IPC memory handle.

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

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

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

Parameters:

  • hContext – [in] handle of the context object

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

Returns:

zeMemSetAtomicAccessAttributeExp#

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

Sets atomic access attributes for a shared allocation.

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

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

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

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

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

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

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

Parameters:

  • hContext – [in] handle of context

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

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

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

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

Returns:

zeMemGetAtomicAccessAttributeExp#

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

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

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

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

Parameters:

  • hContext – [in] handle of context

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

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

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

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

Returns:

Memory Enums#

ze_device_mem_alloc_flags_t#

enum ze_device_mem_alloc_flag_t#

Values:

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_CACHED#

device should cache allocation

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_UNCACHED#

device should not cache allocation (UC)

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_BIAS_INITIAL_PLACEMENT#

optimize shared allocation for first access on the device

enumerator ZE_DEVICE_MEM_ALLOC_FLAG_FORCE_UINT32#

ze_host_mem_alloc_flags_t#

enum ze_host_mem_alloc_flag_t#

Values:

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_CACHED#

host should cache allocation

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_UNCACHED#

host should not cache allocation (UC)

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_WRITE_COMBINED#

host memory should be allocated write-combined (WC)

enumerator ZE_HOST_MEM_ALLOC_FLAG_BIAS_INITIAL_PLACEMENT#

optimize shared allocation for first access on the host

enumerator ZE_HOST_MEM_ALLOC_FLAG_FORCE_UINT32#

ze_memory_type_t#

enum ze_memory_type_t#

Memory allocation type.

Values:

enumerator ZE_MEMORY_TYPE_UNKNOWN#

the memory pointed to is of unknown type

enumerator ZE_MEMORY_TYPE_HOST#

the memory pointed to is a host allocation

enumerator ZE_MEMORY_TYPE_DEVICE#

the memory pointed to is a device allocation

enumerator ZE_MEMORY_TYPE_SHARED#

the memory pointed to is a shared ownership allocation

enumerator ZE_MEMORY_TYPE_FORCE_UINT32#

ze_ipc_memory_flags_t#

enum ze_ipc_memory_flag_t#

Values:

enumerator ZE_IPC_MEMORY_FLAG_BIAS_CACHED#

device should cache allocation

enumerator ZE_IPC_MEMORY_FLAG_BIAS_UNCACHED#

device should not cache allocation (UC)

enumerator ZE_IPC_MEMORY_FLAG_FORCE_UINT32#

ze_memory_atomic_attr_exp_flags_t#

enum ze_memory_atomic_attr_exp_flag_t#

Values:

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_ATOMICS#

Atomics on the pointer are not allowed.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_HOST_ATOMICS#

Host atomics on the pointer are not allowed.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_HOST_ATOMICS#

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

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_DEVICE_ATOMICS#

Device atomics on the pointer are not allowed.

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_DEVICE_ATOMICS#

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

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_NO_SYSTEM_ATOMICS#

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

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_SYSTEM_ATOMICS#

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

enumerator ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_FORCE_UINT32#

Memory Structures#

ze_device_mem_alloc_desc_t#

struct ze_device_mem_alloc_desc_t#

Device memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_device_mem_alloc_flags_t flags#

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

uint32_t ordinal#

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

ze_host_mem_alloc_desc_t#

struct ze_host_mem_alloc_desc_t#

Host memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_host_mem_alloc_flags_t flags#

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

ze_memory_allocation_properties_t#

struct ze_memory_allocation_properties_t#

Memory allocation properties queried using zeMemGetAllocProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_memory_type_t type#

[out] type of allocated memory

uint64_t id#

[out] identifier for this allocation

uint64_t pageSize#

[out] page size used for allocation

ze_external_memory_export_desc_t#

struct ze_external_memory_export_desc_t#

Additional allocation descriptor for exporting external memory.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_external_memory_type_flags_t flags#

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

ze_external_memory_import_fd_t#

struct ze_external_memory_import_fd_t#

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

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_external_memory_type_flags_t flags#

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

int fd#

[in] the file descriptor handle to import

ze_external_memory_export_fd_t#

struct ze_external_memory_export_fd_t#

Exports an allocation as a file descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_external_memory_type_flags_t flags#

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

int fd#

[out] the exported file descriptor handle representing the allocation.

ze_external_memory_import_win32_handle_t#

struct ze_external_memory_import_win32_handle_t#

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

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_external_memory_type_flags_t flags#

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

void *handle#

[in][optional] the Win32 handle to import

const void *name#

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

ze_external_memory_export_win32_handle_t#

struct ze_external_memory_export_win32_handle_t#

Exports an allocation as a Win32 handle.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_external_memory_type_flags_t flags#

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

void *handle#

[out] the exported Win32 handle representing the allocation.

Module#

Module Functions#

zeModuleCreate#

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

Creates a module on the context.

  • Compiles the module for execution on the device.

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

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

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • desc – [in] pointer to module descriptor

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

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

Returns:

zeModuleDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleDestroy(ze_module_handle_t hModule)#

Destroys module.

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

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

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

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

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

Parameters:

hModule – [in][release] handle of the module

Returns:

zeModuleBuildLogDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleBuildLogDestroy(ze_module_build_log_handle_t hModuleBuildLog)#

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

Parameters:

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

Returns:

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.

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

Parameters:

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

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

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

Returns:

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.

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

Parameters:

  • hModule – [in] handle of the module

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

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

Returns:

zeModuleGetGlobalPointer#

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

Retrieve global variable pointer from Module.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

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

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

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

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

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

Returns:

zeModuleGetProperties#

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

Retrieve module properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

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

Returns:

zeKernelCreate#

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

Create a kernel from the module.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

  • desc – [in] pointer to kernel descriptor

  • phKernel – [out] handle of the Function object

Returns:

zeKernelDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelDestroy(ze_kernel_handle_t hKernel)#

Destroys a kernel object.

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

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

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

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

Parameters:

hKernel – [in][release] handle of the kernel object

Returns:

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.

  • 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 function name should only refer to callable functions within the module.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

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

  • pfnFunction – [out] pointer to function.

Returns:

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.

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

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

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

Parameters:

  • hKernel – [in] handle of the kernel object

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

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

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

Returns:

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.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hKernel – [in] handle of the kernel object

  • globalSizeX – [in] global width for X dimension

  • globalSizeY – [in] global width for Y dimension

  • globalSizeZ – [in] global width for Z dimension

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

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

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

Returns:

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.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hKernel – [in] handle of the kernel object

  • totalGroupCount – [out] recommended total group count.

Returns:

zeKernelSetArgumentValue#

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

Set kernel argument for a kernel.

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

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

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

Parameters:

  • hKernel – [in] handle of the kernel object

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

  • argSize – [in] size of argument type

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

Returns:

zeKernelSetIndirectAccess#

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetIndirectAccess(ze_kernel_handle_t hKernel, ze_kernel_indirect_access_flags_t flags)#

Sets kernel indirect access flags.

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

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

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

Parameters:

  • hKernel – [in] handle of the kernel object

  • flags – [in] kernel indirect access flags

Returns:

zeKernelGetIndirectAccess#

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

Retrieve kernel indirect access flags.

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

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

Parameters:

  • hKernel – [in] handle of the kernel object

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

Returns:

zeKernelGetSourceAttributes#

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

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

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

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

Parameters:

  • hKernel – [in] handle of the kernel object

  • pSize – [in,out] pointer to size of string in bytes, including null-terminating character.

  • pString – [in,out][optional] pointer to application-managed character array (string data). If NULL, the string length of the kernel source attributes, including a null-terminating character, is returned in pSize. Otherwise, pString must point to valid application memory that is greater than or equal to *pSize bytes in length, and on return the pointed-to string will contain a space-separated list of kernel source attributes.

Returns:

zeKernelSetCacheConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetCacheConfig(ze_kernel_handle_t hKernel, ze_cache_config_flags_t flags)#

Sets the preferred cache configuration.

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

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

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

Parameters:

  • hKernel – [in] handle of the kernel object

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

Returns:

zeKernelGetProperties#

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

Retrieve kernel properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hKernel – [in] handle of the kernel object

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

Returns:

zeKernelGetName#

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

Retrieve kernel name from Kernel.

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

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hKernel – [in] handle of the kernel object

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

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

Returns:

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.

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • hKernel – [in] handle of the kernel object

  • pLaunchFuncArgs – [in] thread group launch arguments

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

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

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

Returns:

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.

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

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

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • hKernel – [in] handle of the kernel object

  • pLaunchFuncArgs – [in] thread group launch arguments

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

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

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

Returns:

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.

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

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

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • hKernel – [in] handle of the kernel object

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

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

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

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

Returns:

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.

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

  • The application must ensure the array of launch arguments and count buffer are visible to the device on which the command list was created.

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

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

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

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • numKernels – [in] maximum number of kernels to launch

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

  • pCountBuffer – [in] pointer to device memory location that will contain the actual number of kernels to launch; value must be less than or equal to numKernels

  • pLaunchArgumentsBuffer – [in][range(0, numKernels)] pointer to device buffer that will contain a contiguous array of thread group launch arguments

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

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

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

Returns:

Module Enums#

ze_module_format_t#

enum ze_module_format_t#

Supported module creation input formats.

Values:

enumerator ZE_MODULE_FORMAT_IL_SPIRV#

Format is SPIRV IL format.

enumerator ZE_MODULE_FORMAT_NATIVE#

Format is device native format.

enumerator ZE_MODULE_FORMAT_FORCE_UINT32#

ze_module_property_flags_t#

enum ze_module_property_flag_t#

Values:

enumerator ZE_MODULE_PROPERTY_FLAG_IMPORTS#

Module has imports (i.e. imported global variables and/or kernels). See zeModuleDynamicLink.

enumerator ZE_MODULE_PROPERTY_FLAG_FORCE_UINT32#

ze_kernel_flags_t#

enum ze_kernel_flag_t#

Values:

enumerator ZE_KERNEL_FLAG_FORCE_RESIDENCY#

force all device allocations to be resident during execution

enumerator ZE_KERNEL_FLAG_EXPLICIT_RESIDENCY#

application is responsible for all residency of device allocations. driver may disable implicit residency management.

enumerator ZE_KERNEL_FLAG_FORCE_UINT32#

ze_kernel_indirect_access_flags_t#

enum ze_kernel_indirect_access_flag_t#

Values:

enumerator ZE_KERNEL_INDIRECT_ACCESS_FLAG_HOST#

Indicates that the kernel accesses host allocations indirectly.

enumerator ZE_KERNEL_INDIRECT_ACCESS_FLAG_DEVICE#

Indicates that the kernel accesses device allocations indirectly.

enumerator ZE_KERNEL_INDIRECT_ACCESS_FLAG_SHARED#

Indicates that the kernel accesses shared allocations indirectly.

enumerator ZE_KERNEL_INDIRECT_ACCESS_FLAG_FORCE_UINT32#

ze_cache_config_flags_t#

enum ze_cache_config_flag_t#

Values:

enumerator ZE_CACHE_CONFIG_FLAG_LARGE_SLM#

Large SLM size.

enumerator ZE_CACHE_CONFIG_FLAG_LARGE_DATA#

Large General Data size.

enumerator ZE_CACHE_CONFIG_FLAG_FORCE_UINT32#

Module Structures#

ze_module_constants_t#

struct ze_module_constants_t#

Specialization constants - User defined constants.

Public Members

uint32_t numConstants#

[in] Number of specialization constants.

const uint32_t *pConstantIds#

[in][range(0, numConstants)] Array of IDs that is sized to numConstants.

const void **pConstantValues#

[in][range(0, numConstants)] Array of pointers to values that is sized to numConstants.

ze_module_desc_t#

struct ze_module_desc_t#

Module descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

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 one or more (comma-separated) compiler flags. If unsupported, flag is ignored with a warning.

  • ”-ze-opt-disable”

    • Disable optimizations

  • ”-ze-opt-level”

    • Specifies optimization level for compiler. Levels are implementation specific.

      • 0 is no optimizations (equivalent to -ze-opt-disable)

      • 1 is optimize minimally (may be the same as 2)

      • 2 is optimize more (default)

  • ”-ze-opt-greater-than-4GB-buffer-required”

    • Use 64-bit offset calculations for buffers.

  • ”-ze-opt-large-register-file”

    • Increase number of registers available to threads.

  • ”-ze-opt-has-buffer-offset-arg”

    • Extend stateless to stateful optimization to more cases with the use of additional offset (e.g. 64-bit pointer to binding table with 32-bit offset).

  • ”-g”

    • Include debugging information.

const ze_module_constants_t *pConstants#

[in][optional] pointer to specialization constants. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.

ze_module_properties_t#

struct ze_module_properties_t#

Module properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_module_property_flags_t flags#

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

ze_kernel_desc_t#

struct ze_kernel_desc_t#

Kernel descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_kernel_flags_t flags#

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

const char *pKernelName#

[in] null-terminated name of kernel in module

ze_kernel_uuid_t#

struct ze_kernel_uuid_t#

Kernel universal unique id (UUID)

Public Members

uint8_t kid[ZE_MAX_KERNEL_UUID_SIZE]#

[out] opaque data representing a kernel UUID

uint8_t mid[ZE_MAX_MODULE_UUID_SIZE]#

[out] opaque data representing the kernel’s module UUID

ze_kernel_properties_t#

struct ze_kernel_properties_t#

Kernel properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

uint32_t numKernelArgs#

[out] number of kernel arguments.

uint32_t requiredGroupSizeX#

[out] required group size in the X dimension, or zero if there is no required group size

uint32_t requiredGroupSizeY#

[out] required group size in the Y dimension, or zero if there is no required group size

uint32_t requiredGroupSizeZ#

[out] required group size in the Z dimension, or zero if there is no required group size

uint32_t requiredNumSubGroups#

[out] required number of subgroups per thread group, or zero if there is no required number of subgroups

uint32_t requiredSubgroupSize#

[out] required subgroup size, or zero if there is no required subgroup size

uint32_t maxSubgroupSize#

[out] maximum subgroup size

uint32_t maxNumSubgroups#

[out] maximum number of subgroups per thread group

uint32_t localMemSize#

[out] local memory size used by each thread group

uint32_t privateMemSize#

[out] private memory size allocated by compiler used by each thread

uint32_t spillMemSize#

[out] spill memory size allocated by compiler

ze_kernel_uuid_t uuid#

[out] universal unique identifier.

ze_kernel_preferred_group_size_properties_t#

struct ze_kernel_preferred_group_size_properties_t#

Additional kernel preferred group size properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

uint32_t preferredMultiple#

[out] preferred group size multiple

ze_group_count_t#

struct ze_group_count_t#

Kernel dispatch group count.

Public Members

uint32_t groupCountX#

[in] number of thread groups in X dimension

uint32_t groupCountY#

[in] number of thread groups in Y dimension

uint32_t groupCountZ#

[in] number of thread groups in Z dimension

Program#

Program Enums#

ze_module_program_exp_version_t#

enum ze_module_program_exp_version_t#

Module Program Extension Version(s)

Values:

enumerator ZE_MODULE_PROGRAM_EXP_VERSION_1_0#

version 1.0

enumerator ZE_MODULE_PROGRAM_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_MODULE_PROGRAM_EXP_VERSION_FORCE_UINT32#

Program Structures#

ze_module_program_exp_desc_t#

struct ze_module_program_exp_desc_t#

Module extended descriptor to support multiple input modules.

  • Implementation must support ::ZE_experimental_module_program extension

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

  • SPIR-V import and export linkage types are used. See SPIR-V specification for linkage details.

  • pInputModules, pBuildFlags, and pConstants from ze_module_desc_t is ignored.

  • Format in ze_module_desc_t needs to be set to ZE_MODULE_FORMAT_IL_SPIRV.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

uint32_t count#

[in] Count of input modules

const size_t *inputSizes#

[in][range(0, count)] sizes of each input IL module in pInputModules.

const uint8_t **pInputModules#

[in][range(0, count)] pointer to an array of IL (e.g. SPIR-V modules). Valid only for SPIR-V input.

const char **pBuildFlags#

[in][optional][range(0, count)] array of strings containing build flags. See pBuildFlags in ze_module_desc_t.

const ze_module_constants_t **pConstants#

[in][optional][range(0, count)] pointer to array of specialization constant strings. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.

Raytracing#

Raytracing Enums#

ze_raytracing_ext_version_t#

enum ze_raytracing_ext_version_t#

Raytracing Extension Version(s)

Values:

enumerator ZE_RAYTRACING_EXT_VERSION_1_0#

version 1.0

enumerator ZE_RAYTRACING_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_RAYTRACING_EXT_VERSION_FORCE_UINT32#

ze_device_raytracing_ext_flags_t#

enum ze_device_raytracing_ext_flag_t#

Values:

enumerator ZE_DEVICE_RAYTRACING_EXT_FLAG_RAYQUERY#

Supports rayquery.

enumerator ZE_DEVICE_RAYTRACING_EXT_FLAG_FORCE_UINT32#

ze_raytracing_mem_alloc_ext_flags_t#

enum ze_raytracing_mem_alloc_ext_flag_t#

Values:

enumerator ZE_RAYTRACING_MEM_ALLOC_EXT_FLAG_TBD#

reserved for future use

enumerator ZE_RAYTRACING_MEM_ALLOC_EXT_FLAG_FORCE_UINT32#

Raytracing Structures#

ze_device_raytracing_ext_properties_t#

struct ze_device_raytracing_ext_properties_t#

Raytracing properties queried using zeDeviceGetModuleProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_device_raytracing_ext_flags_t flags#

[out] 0 or a valid combination of ze_device_raytracing_ext_flags_t

uint32_t maxBVHLevels#

[out] Maximum number of BVH levels supported

ze_raytracing_mem_alloc_ext_desc_t#

struct ze_raytracing_mem_alloc_ext_desc_t#

Raytracing memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_raytracing_mem_alloc_ext_flags_t flags#

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

Residency#

Residency Functions#

zeContextMakeMemoryResident#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextMakeMemoryResident(ze_context_handle_t hContext, ze_device_handle_t hDevice, void *ptr, size_t size)#

Makes memory resident for the device.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • ptr – [in] pointer to memory to make resident

  • size – [in] size in bytes to make resident

Returns:

zeContextEvictMemory#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextEvictMemory(ze_context_handle_t hContext, ze_device_handle_t hDevice, void *ptr, size_t size)#

Allows memory to be evicted from the device.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • ptr – [in] pointer to memory to evict

  • size – [in] size in bytes to evict

Returns:

zeContextMakeImageResident#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextMakeImageResident(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_image_handle_t hImage)#

Makes image resident for the device.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • hImage – [in] handle of image to make resident

Returns:

zeContextEvictImage#

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextEvictImage(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_image_handle_t hImage)#

Allows image to be evicted from the device.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • hImage – [in] handle of image to make evict

Returns:

Sampler#

Sampler Functions#

zeSamplerCreate#

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

Creates sampler on the context.

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

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • desc – [in] pointer to sampler descriptor

  • phSampler – [out] handle of the sampler

Returns:

zeSamplerDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zeSamplerDestroy(ze_sampler_handle_t hSampler)#

Destroys sampler object.

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

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

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

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

Parameters:

hSampler – [in][release] handle of the sampler

Returns:

Sampler Enums#

ze_sampler_address_mode_t#

enum ze_sampler_address_mode_t#

Sampler addressing modes.

Values:

enumerator ZE_SAMPLER_ADDRESS_MODE_NONE#

No coordinate modifications for out-of-bounds image access.

enumerator ZE_SAMPLER_ADDRESS_MODE_REPEAT#

Out-of-bounds coordinates are wrapped back around.

enumerator ZE_SAMPLER_ADDRESS_MODE_CLAMP#

Out-of-bounds coordinates are clamped to edge.

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

enumerator ZE_SAMPLER_ADDRESS_MODE_MIRROR#

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

enumerator ZE_SAMPLER_ADDRESS_MODE_FORCE_UINT32#

ze_sampler_filter_mode_t#

enum ze_sampler_filter_mode_t#

Sampler filtering modes.

Values:

enumerator ZE_SAMPLER_FILTER_MODE_NEAREST#

No coordinate modifications for out of bounds image access.

enumerator ZE_SAMPLER_FILTER_MODE_LINEAR#

Out-of-bounds coordinates are wrapped back around.

enumerator ZE_SAMPLER_FILTER_MODE_FORCE_UINT32#

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_sampler_address_mode_t addressMode#

[in] Sampler addressing mode to determine how out-of-bounds coordinates are handled.

ze_sampler_filter_mode_t filterMode#

[in] Sampler filter mode to determine how samples are filtered.

ze_bool_t isNormalized#

[in] Are coordinates normalized [0, 1] or not.

Virtual#

Virtual Functions#

zeVirtualMemReserve#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemReserve(ze_context_handle_t hContext, const void *pStart, size_t size, void **pptr)#

Reserves pages in virtual address space.

  • The application must only use the memory allocation on the context for which it was created.

  • The starting address and size must be page aligned. See zeVirtualMemQueryPageSize.

  • If pStart is not null then implementation will attempt to reserve starting from that address. If not available then will find another suitable starting address.

  • The application may call this function from simultaneous threads.

  • The access attributes will default to none to indicate reservation is inaccessible.

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

Parameters:

  • hContext – [in] handle of the context object

  • pStart – [in][optional] pointer to start of region to reserve. If nullptr then implementation will choose a start address.

  • size – [in] size in bytes to reserve; must be page aligned.

  • pptr – [out] pointer to virtual reservation.

Returns:

zeVirtualMemFree#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemFree(ze_context_handle_t hContext, const void *ptr, size_t size)#

Free pages in a reserved virtual address range.

  • Any existing virtual mappings for the range will be unmapped.

  • Physical allocations objects that were mapped to this range will not be destroyed. These need to be destroyed explicitly.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of region to free.

  • size – [in] size in bytes to free; must be page aligned.

Returns:

zeVirtualMemQueryPageSize#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemQueryPageSize(ze_context_handle_t hContext, ze_device_handle_t hDevice, size_t size, size_t *pagesize)#

Queries page size to use for aligning virtual memory reservations and physical memory allocations.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • size – [in] unaligned allocation size in bytes

  • pagesize – [out] pointer to page size to use for start address and size alignments.

Returns:

zePhysicalMemCreate#

ZE_APIEXPORT ze_result_t ZE_APICALL zePhysicalMemCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_physical_mem_desc_t *desc, ze_physical_mem_handle_t *phPhysicalMemory)#

Creates a physical memory object for the context.

  • The application must only use the physical memory object on the context for which it was created.

  • The size must be page aligned. For host memory, the operating system page size should be used. For device memory, see zeVirtualMemQueryPageSize.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object, can be nullptr if creating physical host memory.

  • desc – [in] pointer to physical memory descriptor.

  • phPhysicalMemory – [out] pointer to handle of physical memory object created

Returns:

zePhysicalMemDestroy#

ZE_APIEXPORT ze_result_t ZE_APICALL zePhysicalMemDestroy(ze_context_handle_t hContext, ze_physical_mem_handle_t hPhysicalMemory)#

Destroys a physical memory object.

  • The application must ensure the device is not currently referencing the physical memory object before it is deleted

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

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

Parameters:

  • hContext – [in] handle of the context object

  • hPhysicalMemory – [in][release] handle of physical memory object to destroy

Returns:

zeVirtualMemMap#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemMap(ze_context_handle_t hContext, const void *ptr, size_t size, ze_physical_mem_handle_t hPhysicalMemory, size_t offset, ze_memory_access_attribute_t access)#

Maps pages in virtual address space to pages from physical memory object.

  • The virtual address range must have been reserved using zeVirtualMemReserve.

  • The application must only use the mapped memory allocation on the context for which it was created.

  • The virtual start address and size must be page aligned. See zeVirtualMemQueryPageSize.

  • The application should use, for the starting address and size, the same size alignment used for the physical allocation.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of virtual address range to map.

  • size – [in] size in bytes of virtual address range to map; must be page aligned.

  • hPhysicalMemory – [in] handle to physical memory object.

  • offset – [in] offset into physical memory allocation object; must be page aligned.

  • access – [in] specifies page access attributes to apply to the virtual address range.

Returns:

zeVirtualMemUnmap#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemUnmap(ze_context_handle_t hContext, const void *ptr, size_t size)#

Unmaps pages in virtual address space from pages from a physical memory object.

  • The page access attributes for virtual address range will revert back to none.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of region to unmap.

  • size – [in] size in bytes to unmap; must be page aligned.

Returns:

zeVirtualMemSetAccessAttribute#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemSetAccessAttribute(ze_context_handle_t hContext, const void *ptr, size_t size, ze_memory_access_attribute_t access)#

Set memory access attributes for a virtual address range.

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

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

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of reserved virtual address region.

  • size – [in] size in bytes; must be page aligned.

  • access – [in] specifies page access attributes to apply to the virtual address range.

Returns:

zeVirtualMemGetAccessAttribute#

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemGetAccessAttribute(ze_context_handle_t hContext, const void *ptr, size_t size, ze_memory_access_attribute_t *access, size_t *outSize)#

Get memory access attribute for a virtual address range.

  • If size and outSize are equal then the pages in the specified virtual address range have the same access attributes.

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

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

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of virtual address region for query.

  • size – [in] size in bytes; must be page aligned.

  • access – [out] query result for page access attribute.

  • outSize – [out] query result for size of virtual address range, starting at ptr, that shares same access attribute.

Returns:

Virtual Enums#

ze_memory_access_attribute_t#

enum ze_memory_access_attribute_t#

Virtual memory page access attributes.

Values:

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_NONE#

Indicates the memory page is inaccessible.

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_READWRITE#

Indicates the memory page supports read write access.

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY#

Indicates the memory page supports read-only access.

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_FORCE_UINT32#

ze_physical_mem_flags_t#

enum ze_physical_mem_flag_t#

Values:

enumerator ZE_PHYSICAL_MEM_FLAG_ALLOCATE_ON_DEVICE#

[default] allocate physical device memory.

enumerator ZE_PHYSICAL_MEM_FLAG_ALLOCATE_ON_HOST#

Allocate physical host memory instead.

enumerator ZE_PHYSICAL_MEM_FLAG_FORCE_UINT32#

Virtual Structures#

ze_physical_mem_desc_t#

struct ze_physical_mem_desc_t#

Physical memory descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

ze_physical_mem_flags_t flags#

[in] creation flags. must be 0 (default) or a valid combination of ze_physical_mem_flag_t; default is to create physical device memory.

size_t size#

[in] size in bytes to reserve; must be page aligned.

Floatatomics#

Floatatomics Enums#

ze_float_atomics_ext_version_t#

enum ze_float_atomics_ext_version_t#

Floating-Point Atomics Extension Version(s)

Values:

enumerator ZE_FLOAT_ATOMICS_EXT_VERSION_1_0#

version 1.0

enumerator ZE_FLOAT_ATOMICS_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_FLOAT_ATOMICS_EXT_VERSION_FORCE_UINT32#

ze_device_fp_atomic_ext_flags_t#

enum ze_device_fp_atomic_ext_flag_t#

Values:

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_GLOBAL_LOAD_STORE#

Supports atomic load, store, and exchange.

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_GLOBAL_ADD#

Supports atomic add and subtract.

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_GLOBAL_MIN_MAX#

Supports atomic min and max.

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_LOCAL_LOAD_STORE#

Supports atomic load, store, and exchange.

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_LOCAL_ADD#

Supports atomic add and subtract.

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_LOCAL_MIN_MAX#

Supports atomic min and max.

enumerator ZE_DEVICE_FP_ATOMIC_EXT_FLAG_FORCE_UINT32#

Floatatomics Structures#

ze_float_atomic_ext_properties_t#

struct ze_float_atomic_ext_properties_t#

Device floating-point atomic properties queried using zeDeviceGetModuleProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

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

ze_device_fp_atomic_ext_flags_t fp16Flags#

[out] Capabilities for half-precision floating-point atomic operations

ze_device_fp_atomic_ext_flags_t fp32Flags#

[out] Capabilities for single-precision floating-point atomic operations

ze_device_fp_atomic_ext_flags_t fp64Flags#

[out] Capabilities for double-precision floating-point atomic operations

Globaloffset#

Globaloffset Functions#

zeKernelSetGlobalOffsetExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetGlobalOffsetExp(ze_kernel_handle_t hKernel, uint32_t offsetX, uint32_t offsetY, uint32_t offsetZ)#

Set global work offset for a kernel.

  • The global work offset will be used when a zeCommandListAppendLaunchKernel() variant is called.

  • The application must not call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hKernel – [in] handle of the kernel object

  • offsetX – [in] global offset for X dimension to use for this kernel

  • offsetY – [in] global offset for Y dimension to use for this kernel

  • offsetZ – [in] global offset for Z dimension to use for this kernel

Returns:

Globaloffset Enums#

ze_global_offset_exp_version_t#

enum ze_global_offset_exp_version_t#

Global Offset Extension Version(s)

Values:

enumerator ZE_GLOBAL_OFFSET_EXP_VERSION_1_0#

version 1.0

enumerator ZE_GLOBAL_OFFSET_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_GLOBAL_OFFSET_EXP_VERSION_FORCE_UINT32#

Mutablecommandlist#

Mutablecommandlist Functions#

zeCommandListGetNextCommandIdExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetNextCommandIdExp(ze_command_list_handle_t hCommandList, const ze_mutable_command_id_exp_desc_t *desc, uint64_t *pCommandId)#

Returns a unique command identifier for the next command to be appended to a command list.

  • This function may only be called for a mutable command list.

  • This function may not be called on a closed command list.

  • This function may be called from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of the command list

  • desc – [in] pointer to mutable command identifier descriptor

  • pCommandId – [out] pointer to mutable command identifier to be written

Returns:

zeCommandListGetNextCommandIdWithKernelsExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetNextCommandIdWithKernelsExp(ze_command_list_handle_t hCommandList, const ze_mutable_command_id_exp_desc_t *desc, uint32_t numKernels, ze_kernel_handle_t *phKernels, uint64_t *pCommandId)#

Returns a unique command identifier for the next command to be appended to a command list. Provides possible kernel handles for kernel mutation when ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION flag is present.

  • This function may only be called for a mutable command list.

  • This function may not be called on a closed command list.

  • This function may be called from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of the command list

  • desc – [in][out] pointer to mutable command identifier descriptor

  • numKernels – [in][optional] number of entries on phKernels list

  • phKernels – [in][optional][range(0, numKernels)] list of kernels that user can switch between using zeCommandListUpdateMutableCommandKernelsExp call

  • pCommandId – [out] pointer to mutable command identifier to be written

Returns:

zeCommandListUpdateMutableCommandsExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandsExp(ze_command_list_handle_t hCommandList, const ze_mutable_commands_exp_desc_t *desc)#

Updates mutable commands.

  • This function may only be called for a mutable command list.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of the command list

  • desc – [in] pointer to mutable commands descriptor; multiple descriptors may be chained via pNext member

Returns:

zeCommandListUpdateMutableCommandSignalEventExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandSignalEventExp(ze_command_list_handle_t hCommandList, uint64_t commandId, ze_event_handle_t hSignalEvent)#

Updates the signal event for a mutable command in a mutable command list.

  • This function may only be called for a mutable command list.

  • The type, scope and flags of the signal event must match those of the source command.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of the command list

  • commandId – [in] command identifier

  • hSignalEvent – [in][optional] handle of the event to signal on completion

Returns:

zeCommandListUpdateMutableCommandWaitEventsExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandWaitEventsExp(ze_command_list_handle_t hCommandList, uint64_t commandId, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Updates the wait events for a mutable command in a mutable command list.

  • This function may only be called for a mutable command list.

  • The number of wait events must match that of the source command.

  • The type, scope and flags of the wait events must match those of the source command.

  • Passing nullptr as the wait events will update the command to not wait on any events prior to dispatch.

  • Passing nullptr as an event on event wait list will remove event dependency from this wait list slot.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of the command list

  • commandId – [in] command identifier

  • numWaitEvents – [in][optional] the number of wait events

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListUpdateMutableCommandKernelsExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandKernelsExp(ze_command_list_handle_t hCommandList, uint32_t numKernels, uint64_t *pCommandId, ze_kernel_handle_t *phKernels)#

Updates the kernel for a mutable command in a mutable command list.

  • This function may only be called for a mutable command list.

  • The kernel handle must be from the provided list for given command id.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

  • This function must be called before updating kernel arguments and dispatch parameters, when kernel is mutated.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of the command list

  • numKernels – [in] the number of kernels to update

  • pCommandId – [in][range(0, numKernels)] command identifier

  • phKernels – [in][range(0, numKernels)] handle of the kernel for a command identifier to switch to

Returns:

Mutablecommandlist Enums#

ze_mutable_command_list_exp_version_t#

enum ze_mutable_command_list_exp_version_t#

Mutable Command List Extension Version(s)

Values:

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_VERSION_1_0#

version 1.0

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_VERSION_1_1#

version 1.1

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_VERSION_FORCE_UINT32#

ze_mutable_command_exp_flags_t#

enum ze_mutable_command_exp_flag_t#

Values:

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_ARGUMENTS#

kernel arguments

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GROUP_COUNT#

kernel group count

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GROUP_SIZE#

kernel group size

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GLOBAL_OFFSET#

kernel global offset

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_SIGNAL_EVENT#

command signal event

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_WAIT_EVENTS#

command wait events

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION#

command kernel

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GRAPH_ARGUMENTS#

graph arguments

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_FORCE_UINT32#

ze_mutable_command_list_exp_flags_t#

enum ze_mutable_command_list_exp_flag_t#

Values:

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_FLAG_RESERVED#

reserved

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_FLAG_FORCE_UINT32#

Mutablecommandlist Structures#

ze_mutable_command_id_exp_desc_t#

struct ze_mutable_command_id_exp_desc_t#

Mutable command identifier descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_mutable_command_exp_flags_t flags#

[in] mutable command flags.

ze_mutable_command_list_exp_properties_t#

struct ze_mutable_command_list_exp_properties_t#

Mutable command list properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_mutable_command_list_exp_flags_t mutableCommandListFlags#

[out] mutable command list flags

ze_mutable_command_exp_flags_t mutableCommandFlags#

[out] mutable command flags

ze_mutable_command_list_exp_desc_t#

struct ze_mutable_command_list_exp_desc_t#

Mutable command list descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_mutable_command_list_exp_flags_t flags#

[in] mutable command list flags.

ze_mutable_commands_exp_desc_t#

struct ze_mutable_commands_exp_desc_t#

Mutable commands descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t flags#

[in] must be 0, this field is reserved for future use

ze_mutable_kernel_argument_exp_desc_t#

struct ze_mutable_kernel_argument_exp_desc_t#

Mutable kernel argument descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t commandId#

[in] command identifier

uint32_t argIndex#

[in] kernel argument index

size_t argSize#

[in] kernel argument size

const void *pArgValue#

[in] pointer to kernel argument value

ze_mutable_group_count_exp_desc_t#

struct ze_mutable_group_count_exp_desc_t#

Mutable kernel group count descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t commandId#

[in] command identifier

const ze_group_count_t *pGroupCount#

[in] pointer to group count

ze_mutable_group_size_exp_desc_t#

struct ze_mutable_group_size_exp_desc_t#

Mutable kernel group size descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t commandId#

[in] command identifier

uint32_t groupSizeX#

[in] group size for X dimension to use for the kernel

uint32_t groupSizeY#

[in] group size for Y dimension to use for the kernel

uint32_t groupSizeZ#

[in] group size for Z dimension to use for the kernel

ze_mutable_global_offset_exp_desc_t#

struct ze_mutable_global_offset_exp_desc_t#

Mutable kernel global offset descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t commandId#

[in] command identifier

uint32_t offsetX#

[in] global offset for X dimension to use for this kernel

uint32_t offsetY#

[in] global offset for Y dimension to use for this kernel

uint32_t offsetZ#

[in] global offset for Z dimension to use for this kernel

ze_mutable_graph_argument_exp_desc_t#

struct ze_mutable_graph_argument_exp_desc_t#

Mutable graph argument descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t commandId#

[in] command identifier

uint32_t argIndex#

[in] graph argument index

const void *pArgValue#

[in] pointer to graph argument value

Relaxedalloclimits#

Relaxedalloclimits Enums#

ze_relaxed_allocation_limits_exp_version_t#

enum ze_relaxed_allocation_limits_exp_version_t#

Relaxed Allocation Limits Extension Version(s)

Values:

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_1_0#

version 1.0

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_FORCE_UINT32#

ze_relaxed_allocation_limits_exp_flags_t#

enum ze_relaxed_allocation_limits_exp_flag_t#

Values:

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_MAX_SIZE#

Allocation size may exceed the maxMemAllocSize member of ze_device_properties_t.

enumerator ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_FORCE_UINT32#

Relaxedalloclimits Structures#

ze_relaxed_allocation_limits_exp_desc_t#

struct ze_relaxed_allocation_limits_exp_desc_t#

Relaxed limits memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_relaxed_allocation_limits_exp_flags_t flags#

[in] flags specifying allocation limits to relax. must be 0 (default) or a valid combination of ze_relaxed_allocation_limits_exp_flag_t;

Cachereservation#

Cachereservation Functions#

zeDeviceReserveCacheExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceReserveCacheExt(ze_device_handle_t hDevice, size_t cacheLevel, size_t cacheReservationSize)#

Reserve Cache on Device.

  • The application may call this function but may not be successful as some other application may have reserve prior

Remark

Analogues

  • None

Parameters:

  • hDevice – [in] handle of the device object

  • cacheLevel – [in] cache level where application want to reserve. If zero, then the driver shall default to last level of cache and attempt to reserve in that cache.

  • cacheReservationSize – [in] value for reserving size, in bytes. If zero, then the driver shall remove prior reservation

Returns:

zeDeviceSetCacheAdviceExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceSetCacheAdviceExt(ze_device_handle_t hDevice, void *ptr, size_t regionSize, ze_cache_ext_region_t cacheRegion)#

Assign VA section to use reserved section.

  • The application may call this function to assign VA to particular reservartion region

Parameters:

  • hDevice – [in] handle of the device object

  • ptr – [in] memory pointer to query

  • regionSize – [in] region size, in pages

  • cacheRegion – [in] reservation region

Returns:

Cachereservation Enums#

ze_cache_reservation_ext_version_t#

enum ze_cache_reservation_ext_version_t#

Cache_Reservation Extension Version(s)

Values:

enumerator ZE_CACHE_RESERVATION_EXT_VERSION_1_0#

version 1.0

enumerator ZE_CACHE_RESERVATION_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_CACHE_RESERVATION_EXT_VERSION_FORCE_UINT32#

ze_cache_ext_region_t#

enum ze_cache_ext_region_t#

Cache Reservation Region.

Values:

enumerator ZE_CACHE_EXT_REGION_ZE_CACHE_REGION_DEFAULT#

[DEPRECATED] utilize driver default scheme. Use ZE_CACHE_EXT_REGION_DEFAULT.

enumerator ZE_CACHE_EXT_REGION_ZE_CACHE_RESERVE_REGION#

[DEPRECATED] utilize reserved region. Use ZE_CACHE_EXT_REGION_RESERVED.

enumerator ZE_CACHE_EXT_REGION_ZE_CACHE_NON_RESERVED_REGION#

[DEPRECATED] utilize non-reserverd region. Use ZE_CACHE_EXT_REGION_NON_RESERVED.

enumerator ZE_CACHE_EXT_REGION_DEFAULT#

utilize driver default scheme

enumerator ZE_CACHE_EXT_REGION_RESERVED#

utilize reserved region

enumerator ZE_CACHE_EXT_REGION_NON_RESERVED#

utilize non-reserverd region

enumerator ZE_CACHE_EXT_REGION_FORCE_UINT32#

Cachereservation Structures#

ze_cache_reservation_ext_desc_t#

struct ze_cache_reservation_ext_desc_t#

CacheReservation structure.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

size_t maxCacheReservationSize#

[out] max cache reservation size

Eventquerytimestamps#

Eventquerytimestamps Functions#

zeEventQueryTimestampsExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryTimestampsExp(ze_event_handle_t hEvent, ze_device_handle_t hDevice, uint32_t *pCount, ze_kernel_timestamp_result_t *pTimestamps)#

Query event timestamps for a device or sub-device.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ::ZE_experimental_event_query_timestamps.

  • The implementation must return all timestamps for the specified event and device pair.

  • The implementation must return all timestamps for all sub-devices when device handle is parent device.

  • The implementation may return all timestamps for sub-devices when device handle is sub-device or may return 0 for count.

Remark

Analogues

  • None

Parameters:

  • hEvent – [in] handle of the event

  • hDevice – [in] handle of the device to query

  • pCount – [in,out] pointer to the number of timestamp results. if count is zero, then the driver shall update the value with the total number of timestamps available. if count is greater than the number of timestamps available, then the driver shall update the value with the correct number of timestamps available.

  • pTimestamps – [in,out][optional][range(0, *pCount)] array of timestamp results. if count is less than the number of timestamps available, then driver shall only retrieve that number of timestamps.

Returns:

Eventquerytimestamps Enums#

ze_event_query_timestamps_exp_version_t#

enum ze_event_query_timestamps_exp_version_t#

Event Query Timestamps Extension Version(s)

Values:

enumerator ZE_EVENT_QUERY_TIMESTAMPS_EXP_VERSION_1_0#

version 1.0

enumerator ZE_EVENT_QUERY_TIMESTAMPS_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_EVENT_QUERY_TIMESTAMPS_EXP_VERSION_FORCE_UINT32#

Imagememoryproperties#

Imagememoryproperties Functions#

zeImageGetMemoryPropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageGetMemoryPropertiesExp(ze_image_handle_t hImage, ze_image_memory_properties_exp_t *pMemoryProperties)#

Query image memory properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ::ZE_experimental_image_memory_properties extension.

Remark

Analogues

  • None

Parameters:

  • hImage – [in] handle of image object

  • pMemoryProperties – [in,out] query result for image memory properties.

Returns:

Imagememoryproperties Enums#

ze_image_memory_properties_exp_version_t#

enum ze_image_memory_properties_exp_version_t#

Image Memory Properties Extension Version(s)

Values:

enumerator ZE_IMAGE_MEMORY_PROPERTIES_EXP_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_MEMORY_PROPERTIES_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_MEMORY_PROPERTIES_EXP_VERSION_FORCE_UINT32#

Imagememoryproperties Structures#

ze_image_memory_properties_exp_t#

struct ze_image_memory_properties_exp_t#

Image memory properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t size#

[out] size of image allocation in bytes.

uint64_t rowPitch#

[out] size of image row in bytes.

uint64_t slicePitch#

[out] size of image slice in bytes.

Imageview#

Imageview Functions#

zeImageViewCreateExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageViewCreateExt(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_image_desc_t *desc, ze_image_handle_t hImage, ze_image_handle_t *phImageView)#

Create image view on the context.

  • The application must only use the image view for the device, or its sub-devices, which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ::ZE_extension_image_view extension.

  • Image views are treated as images from the API.

  • Image views provide a mechanism to redescribe how an image is interpreted (e.g. different format).

  • Image views become disabled when their corresponding image resource is destroyed.

  • Use zeImageDestroy to destroy image view objects.

Remark

Analogues

  • None

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • desc – [in] pointer to image descriptor

  • hImage – [in] handle of image object to create view from

  • phImageView – [out] pointer to handle of image object created for view

Returns:

zeImageViewCreateExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageViewCreateExp(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_image_desc_t *desc, ze_image_handle_t hImage, ze_image_handle_t *phImageView)#

Create image view on the context.

  • The application must only use the image view for the device, or its sub-devices, which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ::ZE_experimental_image_view extension.

  • Image views are treated as images from the API.

  • Image views provide a mechanism to redescribe how an image is interpreted (e.g. different format).

  • Image views become disabled when their corresponding image resource is destroyed.

  • Use zeImageDestroy to destroy image view objects.

  • Note: This function is deprecated and replaced by zeImageViewCreateExt.

Remark

Analogues

  • None

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • desc – [in] pointer to image descriptor

  • hImage – [in] handle of image object to create view from

  • phImageView – [out] pointer to handle of image object created for view

Returns:

Imageview Enums#

ze_image_view_ext_version_t#

enum ze_image_view_ext_version_t#

Image View Extension Version(s)

Values:

enumerator ZE_IMAGE_VIEW_EXT_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_VIEW_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_VIEW_EXT_VERSION_FORCE_UINT32#

ze_image_view_exp_version_t#

enum ze_image_view_exp_version_t#

Image View Extension Version(s)

Values:

enumerator ZE_IMAGE_VIEW_EXP_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_VIEW_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_VIEW_EXP_VERSION_FORCE_UINT32#

Imageviewplanar#

Imageviewplanar Enums#

ze_image_view_planar_ext_version_t#

enum ze_image_view_planar_ext_version_t#

Image View Planar Extension Version(s)

Values:

enumerator ZE_IMAGE_VIEW_PLANAR_EXT_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_VIEW_PLANAR_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_VIEW_PLANAR_EXT_VERSION_FORCE_UINT32#

ze_image_view_planar_exp_version_t#

enum ze_image_view_planar_exp_version_t#

Image View Planar Extension Version(s)

Values:

enumerator ZE_IMAGE_VIEW_PLANAR_EXP_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_VIEW_PLANAR_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_VIEW_PLANAR_EXP_VERSION_FORCE_UINT32#

Imageviewplanar Structures#

ze_image_view_planar_ext_desc_t#

struct ze_image_view_planar_ext_desc_t#

Image view planar descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t planeIndex#

[in] the 0-based plane index (e.g. NV12 is 0 = Y plane, 1 UV plane)

ze_image_view_planar_exp_desc_t#

struct ze_image_view_planar_exp_desc_t#

Image view planar descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t planeIndex#

[in] the 0-based plane index (e.g. NV12 is 0 = Y plane, 1 UV plane)

Kernelschedulinghints#

Kernelschedulinghints Functions#

zeKernelSchedulingHintExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSchedulingHintExp(ze_kernel_handle_t hKernel, ze_scheduling_hint_exp_desc_t *pHint)#

Provide kernel scheduling hints that may improve performance.

  • The scheduling hints may improve performance only and are not required for correctness.

  • If a specified scheduling hint is unsupported it will be silently ignored.

  • If two conflicting scheduling hints are specified there is no defined behavior; the hints may be ignored or one hint may be chosen arbitrarily.

  • The application must not call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hKernel – [in] handle of the kernel object

  • pHint – [in] pointer to kernel scheduling hint descriptor

Returns:

Kernelschedulinghints Enums#

ze_scheduling_hints_exp_version_t#

enum ze_scheduling_hints_exp_version_t#

Kernel Scheduling Hints Extension Version(s)

Values:

enumerator ZE_SCHEDULING_HINTS_EXP_VERSION_1_0#

version 1.0

enumerator ZE_SCHEDULING_HINTS_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_SCHEDULING_HINTS_EXP_VERSION_FORCE_UINT32#

ze_scheduling_hint_exp_flags_t#

enum ze_scheduling_hint_exp_flag_t#

Values:

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_OLDEST_FIRST#

Hint that the kernel prefers oldest-first scheduling.

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_ROUND_ROBIN#

Hint that the kernel prefers round-robin scheduling.

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_STALL_BASED_ROUND_ROBIN#

Hint that the kernel prefers stall-based round-robin scheduling.

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_FORCE_UINT32#

Kernelschedulinghints Structures#

ze_scheduling_hint_exp_properties_t#

struct ze_scheduling_hint_exp_properties_t#

Device kernel scheduling hint properties queried using zeDeviceGetModuleProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_scheduling_hint_exp_flags_t schedulingHintFlags#

[out] Supported kernel scheduling hints. May be 0 (none) or a valid combination of ze_scheduling_hint_exp_flag_t.

ze_scheduling_hint_exp_desc_t#

struct ze_scheduling_hint_exp_desc_t#

Kernel scheduling hint descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_scheduling_hint_exp_flags_t flags#

[in] flags specifying kernel scheduling hints. must be 0 (default) or a valid combination of ze_scheduling_hint_exp_flag_t.

Linkonceodr#

Linkonceodr Enums#

ze_linkonce_odr_ext_version_t#

enum ze_linkonce_odr_ext_version_t#

Linkonce ODR Extension Version(s)

Values:

enumerator ZE_LINKONCE_ODR_EXT_VERSION_1_0#

version 1.0

enumerator ZE_LINKONCE_ODR_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_LINKONCE_ODR_EXT_VERSION_FORCE_UINT32#

Powersavinghint#

Powersavinghint Enums#

ze_power_saving_hint_exp_version_t#

enum ze_power_saving_hint_exp_version_t#

Power Saving Hint Extension Version(s)

Values:

enumerator ZE_POWER_SAVING_HINT_EXP_VERSION_1_0#

version 1.0

enumerator ZE_POWER_SAVING_HINT_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_POWER_SAVING_HINT_EXP_VERSION_FORCE_UINT32#

ze_power_saving_hint_type_t#

enum ze_power_saving_hint_type_t#

Supported device types.

Values:

enumerator ZE_POWER_SAVING_HINT_TYPE_MIN#

Minumum power savings. The device will make no attempt to save power while executing work submitted to this context.

enumerator ZE_POWER_SAVING_HINT_TYPE_MAX#

Maximum power savings. The device will do everything to bring power to a minimum while executing work submitted to this context.

enumerator ZE_POWER_SAVING_HINT_TYPE_FORCE_UINT32#

Powersavinghint Structures#

ze_context_power_saving_hint_exp_desc_t#

struct ze_context_power_saving_hint_exp_desc_t#

Extended context descriptor containing power saving hint.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t hint#

[in] power saving hint (default value = 0). This is value from [0,100] and can use pre-defined settings from ze_power_saving_hint_type_t.

Subgroups#

Subgroups Enums#

ze_subgroup_ext_version_t#

enum ze_subgroup_ext_version_t#

Subgroups Extension Version(s)

Values:

enumerator ZE_SUBGROUP_EXT_VERSION_1_0#

version 1.0

enumerator ZE_SUBGROUP_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_SUBGROUP_EXT_VERSION_FORCE_UINT32#

Eucount#

Eucount Enums#

ze_eu_count_ext_version_t#

enum ze_eu_count_ext_version_t#

EU Count Extension Version(s)

Values:

enumerator ZE_EU_COUNT_EXT_VERSION_1_0#

version 1.0

enumerator ZE_EU_COUNT_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_EU_COUNT_EXT_VERSION_FORCE_UINT32#

Eucount Structures#

ze_eu_count_ext_t#

struct ze_eu_count_ext_t#

EU count queried using zeDeviceGetProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t numTotalEUs#

[out] Total number of EUs available

Pciproperties#

Pciproperties Functions#

zeDevicePciGetPropertiesExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDevicePciGetPropertiesExt(ze_device_handle_t hDevice, ze_pci_ext_properties_t *pPciProperties)#

Get PCI properties - address, max speed.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • None

Parameters:

  • hDevice – [in] handle of the device object.

  • pPciProperties – [in,out] returns the PCI properties of the device.

Returns:

Pciproperties Enums#

ze_pci_properties_ext_version_t#

enum ze_pci_properties_ext_version_t#

PCI Properties Extension Version(s)

Values:

enumerator ZE_PCI_PROPERTIES_EXT_VERSION_1_0#

version 1.0

enumerator ZE_PCI_PROPERTIES_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_PCI_PROPERTIES_EXT_VERSION_FORCE_UINT32#

Pciproperties Structures#

ze_pci_address_ext_t#

struct ze_pci_address_ext_t#

Device PCI address.

Public Members

uint32_t domain#

[out] PCI domain number

uint32_t bus#

[out] PCI BDF bus number

uint32_t device#

[out] PCI BDF device number

uint32_t function#

[out] PCI BDF function number

ze_pci_speed_ext_t#

struct ze_pci_speed_ext_t#

Device PCI speed.

Public Members

int32_t genVersion#

[out] The link generation. A value of -1 means that this property is unknown.

int32_t width#

[out] The number of lanes. A value of -1 means that this property is unknown.

int64_t maxBandwidth#

[out] The theoretical maximum bandwidth in bytes/sec (sum of all lanes). A value of -1 means that this property is unknown.

ze_pci_ext_properties_t#

struct ze_pci_ext_properties_t#

Static PCI properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_pci_address_ext_t address#

[out] The BDF address

ze_pci_speed_ext_t maxSpeed#

[out] Fastest port configuration supported by the device (sum of all lanes)

Srgb#

Srgb Enums#

ze_srgb_ext_version_t#

enum ze_srgb_ext_version_t#

sRGB Extension Version(s)

Values:

enumerator ZE_SRGB_EXT_VERSION_1_0#

version 1.0

enumerator ZE_SRGB_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_SRGB_EXT_VERSION_FORCE_UINT32#

Srgb Structures#

ze_srgb_ext_desc_t#

struct ze_srgb_ext_desc_t#

sRGB image descriptor

  • This structure may be passed to zeImageCreate via the pNext member of ze_image_desc_t

  • Used for specifying that the image is in sRGB format.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_bool_t sRGB#

[in] Is sRGB.

Imagecopy#

Imagecopy Functions#

zeCommandListAppendImageCopyToMemoryExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyToMemoryExt(ze_command_list_handle_t hCommandList, void *dstptr, ze_image_handle_t hSrcImage, const ze_image_region_t *pSrcRegion, uint32_t destRowPitch, uint32_t destSlicePitch, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies from an image to device or shared memory.

  • The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.

  • The application must ensure the image and events are accessible by the device on which the command list was created.

  • The application must ensure the image format descriptor for the source image is a single-planar format.

  • The application must ensure that the rowPitch is set to 0 if image is a 1D image. Otherwise the rowPitch must be greater than or equal to the element size in bytes x width.

  • If rowPitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width

  • The application must ensure that the slicePitch is set to 0 if image is a 1D or 2D image. Otherwise this value must be greater than or equal to rowPitch x height.

  • If slicePitch is set to 0, the appropriate slice pitch is calculated based on the rowPitch x height.

  • The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.

  • The application must not call this function from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clEnqueueReadImage

Parameters:

  • hCommandList – [in] handle of command list

  • dstptr – [in] pointer to destination memory to copy to

  • hSrcImage – [in] handle of source image to copy from

  • pSrcRegion – [in][optional] source region descriptor

  • destRowPitch – [in] size in bytes of the 1D slice of the 2D region of a 2D or 3D image or each image of a 1D or 2D image array being written

  • destSlicePitch – [in] size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being written

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendImageCopyFromMemoryExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyFromMemoryExt(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, const void *srcptr, const ze_image_region_t *pDstRegion, uint32_t srcRowPitch, uint32_t srcSlicePitch, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies to an image from device or shared memory.

  • The application must ensure the memory pointed to by srcptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by srcptr as it is free to be modified by either the Host or device up until execution.

  • The application must ensure the image and events are accessible by the device on which the command list was created.

  • The application must ensure the image format descriptor for the destination image is a single-planar format.

  • The application must ensure that the rowPitch is set to 0 if image is a 1D image. Otherwise the rowPitch must be greater than or equal to the element size in bytes x width.

  • If rowPitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width

  • The application must ensure that the slicePitch is set to 0 if image is a 1D or 2D image. Otherwise this value must be greater than or equal to rowPitch x height.

  • If slicePitch is set to 0, the appropriate slice pitch is calculated based on the rowPitch x height.

  • The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.

  • The application must not call this function from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clEnqueueWriteImage

Parameters:

  • hCommandList – [in] handle of command list

  • hDstImage – [in] handle of destination image to copy to

  • srcptr – [in] pointer to source memory to copy from

  • pDstRegion – [in][optional] destination region descriptor

  • srcRowPitch – [in] size in bytes of the 1D slice of the 2D region of a 2D or 3D image or each image of a 1D or 2D image array being read

  • srcSlicePitch – [in] size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being read

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

Imagecopy Enums#

ze_image_copy_ext_version_t#

enum ze_image_copy_ext_version_t#

Image Copy Extension Version(s)

Values:

enumerator ZE_IMAGE_COPY_EXT_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_COPY_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_COPY_EXT_VERSION_FORCE_UINT32#

Imagequeryallocproperties#

Imagequeryallocproperties Functions#

zeImageGetAllocPropertiesExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageGetAllocPropertiesExt(ze_context_handle_t hContext, ze_image_handle_t hImage, ze_image_allocation_ext_properties_t *pImageAllocProperties)#

Retrieves attributes of an image allocation.

  • The application may call this function from simultaneous threads.

Parameters:

  • hContext – [in] handle of the context object

  • hImage – [in] handle of image object to query

  • pImageAllocProperties – [in,out] query result for image allocation properties

Returns:

Imagequeryallocproperties Enums#

ze_image_query_alloc_properties_ext_version_t#

enum ze_image_query_alloc_properties_ext_version_t#

Image Query Allocation Properties Extension Version(s)

Values:

enumerator ZE_IMAGE_QUERY_ALLOC_PROPERTIES_EXT_VERSION_1_0#

version 1.0

enumerator ZE_IMAGE_QUERY_ALLOC_PROPERTIES_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_IMAGE_QUERY_ALLOC_PROPERTIES_EXT_VERSION_FORCE_UINT32#

Imagequeryallocproperties Structures#

ze_image_allocation_ext_properties_t#

struct ze_image_allocation_ext_properties_t#

Image allocation properties queried using zeImageGetAllocPropertiesExt.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t id#

[out] identifier for this allocation

Linkageinspection#

Linkageinspection Functions#

zeModuleInspectLinkageExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleInspectLinkageExt(ze_linkage_inspection_ext_desc_t *pInspectDesc, uint32_t numModules, ze_module_handle_t *phModules, ze_module_build_log_handle_t *phLog)#

List Imports & Exports.

  • List all the import & unresolveable import dependencies & exports of a set of modules

Remark

Analogues

  • None

Parameters:

  • pInspectDesc – [in] pointer to linkage inspection descriptor structure.

  • numModules – [in] number of modules to be inspected pointed to by phModules.

  • phModules – [in][range(0, numModules)] pointer to an array of modules to be inspected for import dependencies.

  • phLog – [out] pointer to handle of linkage inspection log. Log object will contain separate lists of imports, un-resolvable imports, and exports.

Returns:

Linkageinspection Enums#

ze_linkage_inspection_ext_version_t#

enum ze_linkage_inspection_ext_version_t#

Linkage Inspection Extension Version(s)

Values:

enumerator ZE_LINKAGE_INSPECTION_EXT_VERSION_1_0#

version 1.0

enumerator ZE_LINKAGE_INSPECTION_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_LINKAGE_INSPECTION_EXT_VERSION_FORCE_UINT32#

ze_linkage_inspection_ext_flags_t#

enum ze_linkage_inspection_ext_flag_t#

Values:

enumerator ZE_LINKAGE_INSPECTION_EXT_FLAG_IMPORTS#

List all imports of modules.

enumerator ZE_LINKAGE_INSPECTION_EXT_FLAG_UNRESOLVABLE_IMPORTS#

List all imports of modules that do not have a corresponding export.

enumerator ZE_LINKAGE_INSPECTION_EXT_FLAG_EXPORTS#

List all exports of modules.

enumerator ZE_LINKAGE_INSPECTION_EXT_FLAG_FORCE_UINT32#

Linkageinspection Structures#

ze_linkage_inspection_ext_desc_t#

struct ze_linkage_inspection_ext_desc_t#

Module linkage inspection descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_linkage_inspection_ext_flags_t flags#

[in] flags specifying module linkage inspection. must be 0 (default) or a valid combination of ze_linkage_inspection_ext_flag_t.

Memorycompressionhints#

Memorycompressionhints Enums#

ze_memory_compression_hints_ext_version_t#

enum ze_memory_compression_hints_ext_version_t#

Memory Compression Hints Extension Version(s)

Values:

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_VERSION_1_0#

version 1.0

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_VERSION_FORCE_UINT32#

ze_memory_compression_hints_ext_flags_t#

enum ze_memory_compression_hints_ext_flag_t#

Values:

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_COMPRESSED#

Hint Driver implementation to make allocation compressible.

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_UNCOMPRESSED#

Hint Driver implementation to make allocation not compressible.

enumerator ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_FORCE_UINT32#

Memorycompressionhints Structures#

ze_memory_compression_hints_ext_desc_t#

struct ze_memory_compression_hints_ext_desc_t#

Compression hints memory allocation descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_memory_compression_hints_ext_flags_t flags#

[in] flags specifying if allocation should be compressible or not. Must be set to one of the ze_memory_compression_hints_ext_flag_t;

Memoryfreepolicies#

Memoryfreepolicies Functions#

zeMemFreeExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemFreeExt(ze_context_handle_t hContext, const ze_memory_free_ext_desc_t *pMemFreeDesc, void *ptr)#

Frees allocated host memory, device memory, or shared memory using the specified free policy.

  • The memory free policy is specified by the memory free descriptor.

  • The application must not call this function from simultaneous threads with the same pointer.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • pMemFreeDesc – [in] pointer to memory free descriptor

  • ptr – [in][release] pointer to memory to free

Returns:

Memoryfreepolicies Enums#

ze_memory_free_policies_ext_version_t#

enum ze_memory_free_policies_ext_version_t#

Memory Free Policies Extension Version(s)

Values:

enumerator ZE_MEMORY_FREE_POLICIES_EXT_VERSION_1_0#

version 1.0

enumerator ZE_MEMORY_FREE_POLICIES_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_MEMORY_FREE_POLICIES_EXT_VERSION_FORCE_UINT32#

ze_driver_memory_free_policy_ext_flags_t#

enum ze_driver_memory_free_policy_ext_flag_t#

Values:

enumerator ZE_DRIVER_MEMORY_FREE_POLICY_EXT_FLAG_BLOCKING_FREE#

blocks until all commands using the memory are complete before freeing

enumerator ZE_DRIVER_MEMORY_FREE_POLICY_EXT_FLAG_DEFER_FREE#

schedules the memory to be freed but does not free immediately

enumerator ZE_DRIVER_MEMORY_FREE_POLICY_EXT_FLAG_FORCE_UINT32#

Memoryfreepolicies Structures#

ze_driver_memory_free_ext_properties_t#

struct ze_driver_memory_free_ext_properties_t#

Driver memory free properties queried using zeDriverGetProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_driver_memory_free_policy_ext_flags_t freePolicies#

[out] Supported memory free policies. must be 0 or a combination of ze_driver_memory_free_policy_ext_flag_t.

ze_memory_free_ext_desc_t#

struct ze_memory_free_ext_desc_t#

Memory free descriptor with free policy.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_driver_memory_free_policy_ext_flags_t freePolicy#

[in] flags specifying the memory free policy. must be 0 (default) or a supported ze_driver_memory_free_policy_ext_flag_t; default behavior is to free immediately.

Bandwidth#

Bandwidth Structures#

ze_device_p2p_bandwidth_exp_properties_t#

struct ze_device_p2p_bandwidth_exp_properties_t#

P2P Bandwidth Properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t logicalBandwidth#

[out] total logical design bandwidth for all links connecting the two devices

uint32_t physicalBandwidth#

[out] total physical design bandwidth for all links connecting the two devices

ze_bandwidth_unit_t bandwidthUnit#

[out] bandwidth unit

uint32_t logicalLatency#

[out] average logical design latency for all links connecting the two devices

uint32_t physicalLatency#

[out] average physical design latency for all links connecting the two devices

ze_latency_unit_t latencyUnit#

[out] latency unit

ze_copy_bandwidth_exp_properties_t#

struct ze_copy_bandwidth_exp_properties_t#

Copy Bandwidth Properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t copyBandwidth#

[out] design bandwidth supported by this engine type for copy operations

ze_bandwidth_unit_t copyBandwidthUnit#

[out] copy bandwidth unit

Deviceluid#

Deviceluid Enums#

ze_device_luid_ext_version_t#

enum ze_device_luid_ext_version_t#

Device Local Identifier (LUID) Extension Version(s)

Values:

enumerator ZE_DEVICE_LUID_EXT_VERSION_1_0#

version 1.0

enumerator ZE_DEVICE_LUID_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_DEVICE_LUID_EXT_VERSION_FORCE_UINT32#

Deviceluid Structures#

ze_device_luid_ext_t#

struct ze_device_luid_ext_t#

Device local identifier (LUID)

Public Members

uint8_t id[ZE_MAX_DEVICE_LUID_SIZE_EXT]#

[out] opaque data representing a device LUID

ze_device_luid_ext_properties_t#

struct ze_device_luid_ext_properties_t#

Device LUID properties queried using zeDeviceGetProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_device_luid_ext_t luid#

[out] locally unique identifier (LUID). The returned LUID can be cast to a LUID object and must be equal to the locally unique identifier of an IDXGIAdapter1 object that corresponds to the device.

uint32_t nodeMask#

[out] node mask. The returned node mask must contain exactly one bit. If the device is running on an operating system that supports the Direct3D 12 API and the device corresponds to an individual device in a linked device adapter, the returned node mask identifies the Direct3D 12 node corresponding to the device. Otherwise, the returned node mask must be 1.

Fabric#

Fabric Functions#

zeFabricVertexGetExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetExp(ze_driver_handle_t hDriver, uint32_t *pCount, ze_fabric_vertex_handle_t *phVertices)#

Retrieves fabric vertices within a driver.

  • A fabric vertex represents either a device or a switch connected to other fabric vertices.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hDriver – [in] handle of the driver instance

  • pCount – [in,out] pointer to the number of fabric vertices. if count is zero, then the driver shall update the value with the total number of fabric vertices available. if count is greater than the number of fabric vertices available, then the driver shall update the value with the correct number of fabric vertices available.

  • phVertices – [in,out][optional][range(0, *pCount)] array of handle of fabric vertices. if count is less than the number of fabric vertices available, then driver shall only retrieve that number of fabric vertices.

Returns:

zeFabricVertexGetSubVerticesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetSubVerticesExp(ze_fabric_vertex_handle_t hVertex, uint32_t *pCount, ze_fabric_vertex_handle_t *phSubvertices)#

Retrieves a fabric sub-vertex from a fabric vertex.

  • Multiple calls to this function will return identical fabric vertex handles, in the same order.

  • The number of handles returned from this function is affected by the ::ZE_AFFINITY_MASK environment variable.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hVertex – [in] handle of the fabric vertex object

  • pCount – [in,out] pointer to the number of sub-vertices. if count is zero, then the driver shall update the value with the total number of sub-vertices available. if count is greater than the number of sub-vertices available, then the driver shall update the value with the correct number of sub-vertices available.

  • phSubvertices – [in,out][optional][range(0, *pCount)] array of handle of sub-vertices. if count is less than the number of sub-vertices available, then driver shall only retrieve that number of sub-vertices.

Returns:

zeFabricVertexGetPropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetPropertiesExp(ze_fabric_vertex_handle_t hVertex, ze_fabric_vertex_exp_properties_t *pVertexProperties)#

Retrieves properties of the fabric vertex.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hVertex – [in] handle of the fabric vertex

  • pVertexProperties – [in,out] query result for fabric vertex properties

Returns:

zeFabricVertexGetDeviceExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetDeviceExp(ze_fabric_vertex_handle_t hVertex, ze_device_handle_t *phDevice)#

Returns device handle from fabric vertex handle.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hVertex – [in] handle of the fabric vertex

  • phDevice – [out] device handle corresponding to fabric vertex

Returns:

zeDeviceGetFabricVertexExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDeviceGetFabricVertexExp(ze_device_handle_t hDevice, ze_fabric_vertex_handle_t *phVertex)#

Returns fabric vertex handle from device handle.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDevice – [in] handle of the device

  • phVertex – [out] fabric vertex handle corresponding to device

Returns:

zeFabricEdgeGetExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricEdgeGetExp(ze_fabric_vertex_handle_t hVertexA, ze_fabric_vertex_handle_t hVertexB, uint32_t *pCount, ze_fabric_edge_handle_t *phEdges)#

Retrieves all fabric edges between provided pair of fabric vertices.

  • A fabric edge represents one or more physical links between two fabric vertices.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hVertexA – [in] handle of first fabric vertex instance

  • hVertexB – [in] handle of second fabric vertex instance

  • pCount – [in,out] pointer to the number of fabric edges. if count is zero, then the driver shall update the value with the total number of fabric edges available. if count is greater than the number of fabric edges available, then the driver shall update the value with the correct number of fabric edges available.

  • phEdges – [in,out][optional][range(0, *pCount)] array of handle of fabric edges. if count is less than the number of fabric edges available, then driver shall only retrieve that number of fabric edges.

Returns:

zeFabricEdgeGetVerticesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricEdgeGetVerticesExp(ze_fabric_edge_handle_t hEdge, ze_fabric_vertex_handle_t *phVertexA, ze_fabric_vertex_handle_t *phVertexB)#

Retrieves fabric vertices connected by a fabric edge.

  • A fabric vertex represents either a device or a switch connected to other fabric vertices via a fabric edge.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hEdge – [in] handle of the fabric edge instance

  • phVertexA – [out] fabric vertex connected to one end of the given fabric edge.

  • phVertexB – [out] fabric vertex connected to other end of the given fabric edge.

Returns:

zeFabricEdgeGetPropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricEdgeGetPropertiesExp(ze_fabric_edge_handle_t hEdge, ze_fabric_edge_exp_properties_t *pEdgeProperties)#

Retrieves properties of the fabric edge.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hEdge – [in] handle of the fabric edge

  • pEdgeProperties – [in,out] query result for fabric edge properties

Returns:

Fabric Enums#

ze_fabric_vertex_exp_type_t#

enum ze_fabric_vertex_exp_type_t#

Fabric Vertex types.

Values:

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_UNKNOWN#

Fabric vertex type is unknown.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_DEVICE#

Fabric vertex represents a device.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_SUBDEVICE#

Fabric vertex represents a subdevice.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_SWITCH#

Fabric vertex represents a switch.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_FORCE_UINT32#

ze_fabric_edge_exp_duplexity_t#

enum ze_fabric_edge_exp_duplexity_t#

Fabric edge duplexity.

Values:

enumerator ZE_FABRIC_EDGE_EXP_DUPLEXITY_UNKNOWN#

Fabric edge duplexity is unknown.

enumerator ZE_FABRIC_EDGE_EXP_DUPLEXITY_HALF_DUPLEX#

Fabric edge is half duplex, i.e. stated bandwidth is obtained in only one direction at time

enumerator ZE_FABRIC_EDGE_EXP_DUPLEXITY_FULL_DUPLEX#

Fabric edge is full duplex, i.e. stated bandwidth is supported in both directions simultaneously

enumerator ZE_FABRIC_EDGE_EXP_DUPLEXITY_FORCE_UINT32#

Fabric Structures#

ze_fabric_vertex_pci_exp_address_t#

struct ze_fabric_vertex_pci_exp_address_t#

PCI address.

  • A PCI BDF address is the bus:device:function address of the device and is useful for locating the device in the PCI switch fabric.

Public Members

uint32_t domain#

[out] PCI domain number

uint32_t bus#

[out] PCI BDF bus number

uint32_t device#

[out] PCI BDF device number

uint32_t function#

[out] PCI BDF function number

ze_fabric_vertex_exp_properties_t#

struct ze_fabric_vertex_exp_properties_t#

Fabric Vertex properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_uuid_t uuid#

[out] universal unique identifier. If the vertex is co-located with a device/subdevice, then this uuid will match that of the corresponding device/subdevice

ze_fabric_vertex_exp_type_t type#

[out] does the fabric vertex represent a device, subdevice, or switch?

ze_bool_t remote#

[out] does the fabric vertex live on the local node or on a remote node?

ze_fabric_vertex_pci_exp_address_t address#

[out] B/D/F address of fabric vertex & associated device/subdevice if available

ze_fabric_edge_exp_properties_t#

struct ze_fabric_edge_exp_properties_t#

Fabric Edge properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_uuid_t uuid#

[out] universal unique identifier.

char model[ZE_MAX_FABRIC_EDGE_MODEL_EXP_SIZE]#

[out] Description of fabric edge technology. Will be set to the string “unkown” if this cannot be determined for this edge

uint32_t bandwidth#

[out] design bandwidth

ze_bandwidth_unit_t bandwidthUnit#

[out] bandwidth unit

uint32_t latency#

[out] design latency

ze_latency_unit_t latencyUnit#

[out] latency unit

ze_fabric_edge_exp_duplexity_t duplexity#

[out] Duplexity of the fabric edge

Memoryproperties#

Memoryproperties Enums#

ze_device_memory_properties_ext_version_t#

enum ze_device_memory_properties_ext_version_t#

Device Memory Properties Extension Version(s)

Values:

enumerator ZE_DEVICE_MEMORY_PROPERTIES_EXT_VERSION_1_0#

version 1.0

enumerator ZE_DEVICE_MEMORY_PROPERTIES_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_DEVICE_MEMORY_PROPERTIES_EXT_VERSION_FORCE_UINT32#

ze_device_memory_ext_type_t#

enum ze_device_memory_ext_type_t#

Memory module types.

Values:

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_HBM#

HBM memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_HBM2#

HBM2 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_DDR#

DDR memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_DDR2#

DDR2 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_DDR3#

DDR3 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_DDR4#

DDR4 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_DDR5#

DDR5 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_LPDDR#

LPDDR memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_LPDDR3#

LPDDR3 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_LPDDR4#

LPDDR4 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_LPDDR5#

LPDDR5 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_SRAM#

SRAM memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_L1#

L1 cache.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_L3#

L3 cache.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GRF#

Execution unit register file.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_SLM#

Execution unit shared local memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GDDR4#

GDDR4 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GDDR5#

GDDR5 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GDDR5X#

GDDR5X memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GDDR6#

GDDR6 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GDDR6X#

GDDR6X memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_GDDR7#

GDDR7 memory.

enumerator ZE_DEVICE_MEMORY_EXT_TYPE_FORCE_UINT32#

Memoryproperties Structures#

ze_device_memory_ext_properties_t#

struct ze_device_memory_ext_properties_t#

Memory properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_device_memory_ext_type_t type#

[out] The memory type

uint64_t physicalSize#

[out] Physical memory size in bytes. A value of 0 indicates that this property is not known. However, a call to zesMemoryGetState() will correctly return the total size of usable memory.

uint32_t readBandwidth#

[out] Design bandwidth for reads

uint32_t writeBandwidth#

[out] Design bandwidth for writes

ze_bandwidth_unit_t bandwidthUnit#

[out] bandwidth unit

Bfloat16conversions#

Bfloat16conversions Enums#

ze_bfloat16_conversions_ext_version_t#

enum ze_bfloat16_conversions_ext_version_t#

Bfloat16 Conversions Extension Version(s)

Values:

enumerator ZE_BFLOAT16_CONVERSIONS_EXT_VERSION_1_0#

version 1.0

enumerator ZE_BFLOAT16_CONVERSIONS_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_BFLOAT16_CONVERSIONS_EXT_VERSION_FORCE_UINT32#

Deviceipversion#

Deviceipversion Enums#

ze_device_ip_version_version_t#

enum ze_device_ip_version_version_t#

Device IP Version Extension Version(s)

Values:

enumerator ZE_DEVICE_IP_VERSION_VERSION_1_0#

version 1.0

enumerator ZE_DEVICE_IP_VERSION_VERSION_CURRENT#

latest known version

enumerator ZE_DEVICE_IP_VERSION_VERSION_FORCE_UINT32#

Deviceipversion Structures#

ze_device_ip_version_ext_t#

struct ze_device_ip_version_ext_t#

Device IP version queried using zeDeviceGetProperties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t ipVersion#

[out] Device IP version. The meaning of the device IP version is implementation-defined, but newer devices should have a higher version than older devices.

Kernelmaxgroupsizeproperties#

Kernelmaxgroupsizeproperties Enums#

ze_kernel_max_group_size_properties_ext_version_t#

enum ze_kernel_max_group_size_properties_ext_version_t#

Kernel Max Group Size Properties Extension Version(s)

Values:

enumerator ZE_KERNEL_MAX_GROUP_SIZE_PROPERTIES_EXT_VERSION_1_0#

version 1.0

enumerator ZE_KERNEL_MAX_GROUP_SIZE_PROPERTIES_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_KERNEL_MAX_GROUP_SIZE_PROPERTIES_EXT_VERSION_FORCE_UINT32#

Kernelmaxgroupsizeproperties Structures#

ze_kernel_max_group_size_properties_ext_t#

struct ze_kernel_max_group_size_properties_ext_t#

Additional kernel max group size properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t maxGroupSize#

[out] maximum group size that can be used to execute the kernel. This value may be less than or equal to the maxTotalGroupSize member of ze_device_compute_properties_t.

Suballocationsproperties#

Suballocationsproperties Enums#

ze_sub_allocations_exp_version_t#

enum ze_sub_allocations_exp_version_t#

Sub-Allocations Properties Extension Version(s)

Values:

enumerator ZE_SUB_ALLOCATIONS_EXP_VERSION_1_0#

version 1.0

enumerator ZE_SUB_ALLOCATIONS_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_SUB_ALLOCATIONS_EXP_VERSION_FORCE_UINT32#

Suballocationsproperties Structures#

ze_sub_allocation_t#

struct ze_sub_allocation_t#

Properties returned for a sub-allocation.

Public Members

void *base#

[in,out][optional] base address of the sub-allocation

size_t size#

[in,out][optional] size of the allocation

ze_memory_sub_allocations_exp_properties_t#

struct ze_memory_sub_allocations_exp_properties_t#

Sub-Allocations Properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t *pCount#

[in,out] pointer to the number of sub-allocations. if count is zero, then the driver shall update the value with the total number of sub-allocations on which the allocation has been divided. if count is greater than the number of sub-allocations, then the driver shall update the value with the correct number of sub-allocations.

ze_sub_allocation_t *pSubAllocations#

[in,out][optional][range(0, *pCount)] array of properties for sub-allocations. if count is less than the number of sub-allocations available, then driver shall only retrieve properties for that number of sub-allocations.

Eventquerykerneltimestamps#

Eventquerykerneltimestamps Functions#

zeEventQueryKernelTimestampsExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryKernelTimestampsExt(ze_event_handle_t hEvent, ze_device_handle_t hDevice, uint32_t *pCount, ze_event_query_kernel_timestamps_results_ext_properties_t *pResults)#

Query an event’s timestamp value on the host, with domain preference.

  • For collecting only kernel timestamps, the application must ensure the event was created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

  • For collecting synchronized timestamps, the application must ensure the event was created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flag. Kernel timestamps are also available from this type of event pool, but there is a performance cost.

  • 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 must be thread-safe.

  • The implementation must support ::ZE_extension_event_query_kernel_timestamps.

  • The implementation must return all timestamps for the specified event and device pair.

  • The implementation must return all timestamps for all sub-devices when device handle is parent device.

  • The implementation may return all timestamps for sub-devices when device handle is sub-device or may return 0 for count.

Parameters:

  • hEvent – [in] handle of the event

  • hDevice – [in] handle of the device to query

  • pCount – [in,out] pointer to the number of event packets available.

    • This value is implementation specific.

    • if *pCount is zero, then the driver shall update the value with the total number of event packets available.

    • if *pCount is greater than the number of event packets available, the driver shall update the value with the correct value.

    • Buffer(s) for query results must be sized by the application to accommodate a minimum of *pCount elements.

  • pResults – [in,out][optional][range(0, *pCount)] pointer to event query properties structure(s).

    • This parameter may be null when *pCount is zero.

    • if *pCount is less than the number of event packets available, the driver may only update *pCount elements, starting at element zero.

    • if *pCount is greater than the number of event packets available, the driver may only update the valid elements.

Returns:

Eventquerykerneltimestamps Enums#

ze_event_query_kernel_timestamps_ext_version_t#

enum ze_event_query_kernel_timestamps_ext_version_t#

Event Query Kernel Timestamps Extension Version(s)

Values:

enumerator ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_VERSION_1_0#

version 1.0

enumerator ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_VERSION_CURRENT#

latest known version

enumerator ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_VERSION_FORCE_UINT32#

ze_event_query_kernel_timestamps_ext_flags_t#

enum ze_event_query_kernel_timestamps_ext_flag_t#

Values:

enumerator ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_FLAG_KERNEL#

Kernel timestamp results.

enumerator ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_FLAG_SYNCHRONIZED#

Device event timestamps synchronized to the host time domain.

enumerator ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_FLAG_FORCE_UINT32#

Eventquerykerneltimestamps Structures#

ze_event_query_kernel_timestamps_ext_properties_t#

struct ze_event_query_kernel_timestamps_ext_properties_t#

Event query kernel timestamps properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_event_query_kernel_timestamps_ext_flags_t flags#

[out] 0 or some combination of ze_event_query_kernel_timestamps_ext_flag_t flags

ze_synchronized_timestamp_data_ext_t#

struct ze_synchronized_timestamp_data_ext_t#

Kernel timestamp clock data synchronized to the host time domain.

Public Members

uint64_t kernelStart#

[out] synchronized clock at start of kernel execution

uint64_t kernelEnd#

[out] synchronized clock at end of kernel execution

ze_synchronized_timestamp_result_ext_t#

struct ze_synchronized_timestamp_result_ext_t#

Synchronized kernel timestamp result.

Public Members

ze_synchronized_timestamp_data_ext_t global#

[out] wall-clock data

ze_synchronized_timestamp_data_ext_t context#

[out] context-active data; only includes clocks while device context was actively executing.

ze_event_query_kernel_timestamps_results_ext_properties_t#

struct ze_event_query_kernel_timestamps_results_ext_properties_t#

Event query kernel timestamps results properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_kernel_timestamp_result_t *pKernelTimestampsBuffer#

[in,out][optional][range(0, *pCount)] pointer to destination buffer of kernel timestamp results

ze_synchronized_timestamp_result_ext_t *pSynchronizedTimestampsBuffer#

[in,out][optional][range(0, *pCount)] pointer to destination buffer of synchronized timestamp results

Rtasbuilder#

Rtasbuilder Functions#

zeRTASBuilderCreateExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderCreateExp(ze_driver_handle_t hDriver, const ze_rtas_builder_exp_desc_t *pDescriptor, ze_rtas_builder_exp_handle_t *phBuilder)#

Creates a ray tracing acceleration structure builder object.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ::ZE_experimental_rtas_builder extension.

Parameters:

  • hDriver – [in] handle of driver object

  • pDescriptor – [in] pointer to builder descriptor

  • phBuilder – [out] handle of builder object

Returns:

zeRTASBuilderGetBuildPropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderGetBuildPropertiesExp(ze_rtas_builder_exp_handle_t hBuilder, const ze_rtas_builder_build_op_exp_desc_t *pBuildOpDescriptor, ze_rtas_builder_exp_properties_t *pProperties)#

Retrieves ray tracing acceleration structure builder properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hBuilder – [in] handle of builder object

  • pBuildOpDescriptor – [in] pointer to build operation descriptor

  • pProperties – [in,out] query result for builder properties

Returns:

zeDriverRTASFormatCompatibilityCheckExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeDriverRTASFormatCompatibilityCheckExp(ze_driver_handle_t hDriver, ze_rtas_format_exp_t rtasFormatA, ze_rtas_format_exp_t rtasFormatB)#

Checks ray tracing acceleration structure format compatibility.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hDriver – [in] handle of driver object

  • rtasFormatA – [in] operand A

  • rtasFormatB – [in] operand B

Returns:

zeRTASBuilderBuildExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderBuildExp(ze_rtas_builder_exp_handle_t hBuilder, const ze_rtas_builder_build_op_exp_desc_t *pBuildOpDescriptor, void *pScratchBuffer, size_t scratchBufferSizeBytes, void *pRtasBuffer, size_t rtasBufferSizeBytes, ze_rtas_parallel_operation_exp_handle_t hParallelOperation, void *pBuildUserPtr, ze_rtas_aabb_exp_t *pBounds, size_t *pRtasBufferSizeBytes)#

Build ray tracing acceleration structure.

  • This function builds an acceleration structure of the scene consisting of the specified geometry information and writes the acceleration structure to the provided destination buffer. All types of geometries can get freely mixed inside a scene.

  • It is the user’s responsibility to manage the acceleration structure buffer allocation, de-allocation, and potential prefetching to the device memory. The required size of the acceleration structure buffer can be queried with the zeRTASBuilderGetBuildPropertiesExp function. The acceleration structure buffer must be a shared USM allocation and should be present on the host at build time. The referenced scene data (index- and vertex- buffers) can be standard host allocations, and will not be referenced into by the build acceleration structure.

  • Before an acceleration structure can be built, the user must allocate the memory for the acceleration structure buffer and scratch buffer using sizes based on a query for the estimated size properties.

  • When using the “worst-case” size for the acceleration structure buffer, the acceleration structure construction will never fail with ZE_RESULT_EXP_RTAS_BUILD_RETRY.

  • When using the “expected” size for the acceleration structure buffer, the acceleration structure construction may fail with ZE_RESULT_EXP_RTAS_BUILD_RETRY. If this happens, the user may resize their acceleration structure buffer using the returned *pRtasBufferSizeBytes value, which will be updated with an improved size estimate that will likely result in a successful build.

  • The acceleration structure construction is run on the host and is synchronous, thus after the function returns with a successful result, the acceleration structure may be used.

  • All provided data buffers must be host-accessible.

  • The acceleration structure buffer must be a USM allocation.

  • A successfully constructed acceleration structure is entirely self-contained. There is no requirement for input data to persist beyond build completion.

  • A successfully constructed acceleration structure is non-copyable.

  • Acceleration structure construction may be parallelized by passing a valid handle to a parallel operation object and joining that parallel operation using zeRTASParallelOperationJoinExp with user-provided worker threads.

  • Additional Notes

    • ”The geometry infos array, geometry infos, and scratch buffer must

      all be standard host memory allocations.”

    • ”A pointer to a geometry info can be a null pointer, in which case

      the geometry is treated as empty.”

    • ”If no parallel operation handle is provided, the build is run

      sequentially on the current thread.”

    • ”A parallel operation object may only be associated with a single

      acceleration structure build at a time.”

Parameters:

  • hBuilder – [in] handle of builder object

  • pBuildOpDescriptor – [in] pointer to build operation descriptor

  • pScratchBuffer – [in][range(0, scratchBufferSizeBytes)] scratch buffer to be used during acceleration structure construction

  • scratchBufferSizeBytes – [in] size of scratch buffer, in bytes

  • pRtasBuffer – [in] pointer to destination buffer

  • rtasBufferSizeBytes – [in] destination buffer size, in bytes

  • hParallelOperation – [in][optional] handle to parallel operation object

  • pBuildUserPtr – [in][optional] pointer passed to callbacks

  • pBounds – [in,out][optional] pointer to destination address for acceleration structure bounds

  • pRtasBufferSizeBytes – [out][optional] updated acceleration structure size requirement, in bytes

Returns:

zeRTASBuilderDestroyExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderDestroyExp(ze_rtas_builder_exp_handle_t hBuilder)#

Destroys a ray tracing acceleration structure builder object.

  • The implementation of this function may immediately release any internal Host and Device resources associated with this builder.

  • The application must not call this function from simultaneous threads with the same builder handle.

  • The implementation of this function must be thread-safe.

Parameters:

hBuilder – [in][release] handle of builder object to destroy

Returns:

zeRTASParallelOperationCreateExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASParallelOperationCreateExp(ze_driver_handle_t hDriver, ze_rtas_parallel_operation_exp_handle_t *phParallelOperation)#

Creates a ray tracing acceleration structure builder parallel operation object.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ::ZE_experimental_rtas_builder extension.

Parameters:

  • hDriver – [in] handle of driver object

  • phParallelOperation – [out] handle of parallel operation object

Returns:

zeRTASParallelOperationGetPropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASParallelOperationGetPropertiesExp(ze_rtas_parallel_operation_exp_handle_t hParallelOperation, ze_rtas_parallel_operation_exp_properties_t *pProperties)#

Retrieves ray tracing acceleration structure builder parallel operation properties.

  • The application must first bind the parallel operation object to a build operation before it may query the parallel operation properties. In other words, the application must first call zeRTASBuilderBuildExp with hParallelOperation before calling this function.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hParallelOperation – [in] handle of parallel operation object

  • pProperties – [in,out] query result for parallel operation properties

Returns:

zeRTASParallelOperationJoinExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASParallelOperationJoinExp(ze_rtas_parallel_operation_exp_handle_t hParallelOperation)#

Joins a parallel build operation.

  • All worker threads return the same error code for the parallel build operation upon build completion

Parameters:

hParallelOperation – [in] handle of parallel operation object

Returns:

zeRTASParallelOperationDestroyExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASParallelOperationDestroyExp(ze_rtas_parallel_operation_exp_handle_t hParallelOperation)#

Destroys a ray tracing acceleration structure builder parallel operation object.

  • The implementation of this function may immediately release any internal Host and Device resources associated with this parallel operation.

  • The application must not call this function from simultaneous threads with the same parallel operation handle.

  • The implementation of this function must be thread-safe.

Parameters:

hParallelOperation – [in][release] handle of parallel operation object to destroy

Returns:

Rtasbuilder Enums#

ze_rtas_builder_exp_version_t#

enum ze_rtas_builder_exp_version_t#

Ray Tracing Acceleration Structure Builder Extension Version(s)

Values:

enumerator ZE_RTAS_BUILDER_EXP_VERSION_1_0#

version 1.0

enumerator ZE_RTAS_BUILDER_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_RTAS_BUILDER_EXP_VERSION_FORCE_UINT32#

ze_rtas_device_exp_flags_t#

enum ze_rtas_device_exp_flag_t#

Values:

enumerator ZE_RTAS_DEVICE_EXP_FLAG_RESERVED#

reserved for future use

enumerator ZE_RTAS_DEVICE_EXP_FLAG_FORCE_UINT32#

ze_rtas_format_exp_t#

enum ze_rtas_format_exp_t#

Ray tracing acceleration structure format.

  • This is an opaque ray tracing acceleration structure format identifier.

Values:

enumerator ZE_RTAS_FORMAT_EXP_INVALID#

Invalid acceleration structure format.

enumerator ZE_RTAS_FORMAT_EXP_FORCE_UINT32#

ze_rtas_builder_exp_flags_t#

enum ze_rtas_builder_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_EXP_FLAG_RESERVED#

Reserved for future use.

enumerator ZE_RTAS_BUILDER_EXP_FLAG_FORCE_UINT32#

ze_rtas_parallel_operation_exp_flags_t#

enum ze_rtas_parallel_operation_exp_flag_t#

Values:

enumerator ZE_RTAS_PARALLEL_OPERATION_EXP_FLAG_RESERVED#

Reserved for future use.

enumerator ZE_RTAS_PARALLEL_OPERATION_EXP_FLAG_FORCE_UINT32#

ze_rtas_builder_geometry_exp_flags_t#

enum ze_rtas_builder_geometry_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_GEOMETRY_EXP_FLAG_NON_OPAQUE#

non-opaque geometries invoke an any-hit shader

enumerator ZE_RTAS_BUILDER_GEOMETRY_EXP_FLAG_FORCE_UINT32#

ze_rtas_builder_instance_exp_flags_t#

enum ze_rtas_builder_instance_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_CULL_DISABLE#

disables culling of front-facing and back-facing triangles

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_FRONT_COUNTERCLOCKWISE#

reverses front and back face of triangles

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_FORCE_OPAQUE#

forces instanced geometry to be opaque, unless ray flag forces it to be non-opaque

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_FORCE_NON_OPAQUE#

forces instanced geometry to be non-opaque, unless ray flag forces it to be opaque

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_FORCE_UINT32#

ze_rtas_builder_build_op_exp_flags_t#

enum ze_rtas_builder_build_op_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_COMPACT#

build more compact acceleration structure

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_NO_DUPLICATE_ANYHIT_INVOCATION#

guarantees single any-hit shader invocation per primitive

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_FORCE_UINT32#

ze_rtas_builder_build_quality_hint_exp_t#

enum ze_rtas_builder_build_quality_hint_exp_t#

Ray tracing acceleration structure builder build quality hint.

  • Depending on use case different quality modes for acceleration structure build are supported.

  • A low-quality build builds an acceleration structure fast, but at the cost of some reduction in ray tracing performance. This mode is recommended for dynamic content, such as animated characters.

  • A medium-quality build uses a compromise between build quality and ray tracing performance. This mode should be used by default.

  • Higher ray tracing performance can be achieved by using a high-quality build, but acceleration structure build performance might be significantly reduced.

Values:

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_LOW#

build low-quality acceleration structure (fast)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_MEDIUM#

build medium-quality acceleration structure (slower)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_HIGH#

build high-quality acceleration structure (slow)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_FORCE_UINT32#

ze_rtas_builder_geometry_type_exp_t#

enum ze_rtas_builder_geometry_type_exp_t#

Ray tracing acceleration structure builder geometry type.

Values:

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_TRIANGLES#

triangle mesh geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_QUADS#

quad mesh geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_PROCEDURAL#

procedural geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_INSTANCE#

instance geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_FORCE_UINT32#

ze_rtas_builder_input_data_format_exp_t#

enum ze_rtas_builder_input_data_format_exp_t#

Ray tracing acceleration structure data buffer element format.

  • Specifies the format of data buffer elements.

  • Data buffers may contain instancing transform matrices, triangle/quad vertex indices, etc…

Values:

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3#

3-component float vector (see ze_rtas_float3_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3X4_COLUMN_MAJOR#

3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_column_major_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3X4_ALIGNED_COLUMN_MAJOR#

3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_aligned_column_major_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3X4_ROW_MAJOR#

3x4 affine transformation in row-major format (see ze_rtas_transform_float3x4_row_major_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_AABB#

3-dimensional axis-aligned bounding-box (see ze_rtas_aabb_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_TRIANGLE_INDICES_UINT32#

Unsigned 32-bit triangle indices (see ze_rtas_triangle_indices_uint32_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_QUAD_INDICES_UINT32#

Unsigned 32-bit quad indices (see ze_rtas_quad_indices_uint32_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FORCE_UINT32#

Rtasbuilder Structures#

ze_rtas_builder_exp_desc_t#

struct ze_rtas_builder_exp_desc_t#

Ray tracing acceleration structure builder descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_builder_exp_version_t builderVersion#

[in] ray tracing acceleration structure builder version

ze_rtas_builder_exp_properties_t#

struct ze_rtas_builder_exp_properties_t#

Ray tracing acceleration structure builder properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_builder_exp_flags_t flags#

[out] ray tracing acceleration structure builder flags

size_t rtasBufferSizeBytesExpected#

[out] expected size (in bytes) required for acceleration structure buffer

  • When using an acceleration structure buffer of this size, the build is expected to succeed; however, it is possible that the build may fail with ZE_RESULT_EXP_RTAS_BUILD_RETRY

size_t rtasBufferSizeBytesMaxRequired#

[out] worst-case size (in bytes) required for acceleration structure buffer

  • When using an acceleration structure buffer of this size, the build is guaranteed to not run out of memory.

size_t scratchBufferSizeBytes#

[out] scratch buffer size (in bytes) required for acceleration structure build.

ze_rtas_parallel_operation_exp_properties_t#

struct ze_rtas_parallel_operation_exp_properties_t#

Ray tracing acceleration structure builder parallel operation properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_parallel_operation_exp_flags_t flags#

[out] ray tracing acceleration structure builder parallel operation flags

uint32_t maxConcurrency#

[out] maximum number of threads that may join the parallel operation

ze_rtas_device_exp_properties_t#

struct ze_rtas_device_exp_properties_t#

Ray tracing acceleration structure device properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_device_exp_flags_t flags#

[out] ray tracing acceleration structure device flags

ze_rtas_format_exp_t rtasFormat#

[out] ray tracing acceleration structure format

uint32_t rtasBufferAlignment#

[out] required alignment of acceleration structure buffer

ze_rtas_float3_exp_t#

struct ze_rtas_float3_exp_t#

A 3-component vector type.

Public Members

float x#

[in] x-coordinate of float3 vector

float y#

[in] y-coordinate of float3 vector

float z#

[in] z-coordinate of float3 vector

ze_rtas_transform_float3x4_column_major_exp_t#

struct ze_rtas_transform_float3x4_column_major_exp_t#

3x4 affine transformation in column-major layout

  • A 3x4 affine transformation in column major layout, consisting of vectors

    • vx=(vx_x, vx_y, vx_z),

    • vy=(vy_x, vy_y, vy_z),

    • vz=(vz_x, vz_y, vz_z), and

    • p=(p_x, p_y, p_z)

  • The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.

Public Members

float vx_x#

[in] element 0 of column 0 of 3x4 matrix

float vx_y#

[in] element 1 of column 0 of 3x4 matrix

float vx_z#

[in] element 2 of column 0 of 3x4 matrix

float vy_x#

[in] element 0 of column 1 of 3x4 matrix

float vy_y#

[in] element 1 of column 1 of 3x4 matrix

float vy_z#

[in] element 2 of column 1 of 3x4 matrix

float vz_x#

[in] element 0 of column 2 of 3x4 matrix

float vz_y#

[in] element 1 of column 2 of 3x4 matrix

float vz_z#

[in] element 2 of column 2 of 3x4 matrix

float p_x#

[in] element 0 of column 3 of 3x4 matrix

float p_y#

[in] element 1 of column 3 of 3x4 matrix

float p_z#

[in] element 2 of column 3 of 3x4 matrix

ze_rtas_transform_float3x4_aligned_column_major_exp_t#

struct ze_rtas_transform_float3x4_aligned_column_major_exp_t#

3x4 affine transformation in column-major layout with aligned column vectors

  • A 3x4 affine transformation in column major layout, consisting of vectors

    • vx=(vx_x, vx_y, vx_z),

    • vy=(vy_x, vy_y, vy_z),

    • vz=(vz_x, vz_y, vz_z), and

    • p=(p_x, p_y, p_z)

  • The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.

  • The column vectors are aligned to 16-bytes and pad members are ignored.

Public Members

float vx_x#

[in] element 0 of column 0 of 3x4 matrix

float vx_y#

[in] element 1 of column 0 of 3x4 matrix

float vx_z#

[in] element 2 of column 0 of 3x4 matrix

float pad0#

[in] ignored padding

float vy_x#

[in] element 0 of column 1 of 3x4 matrix

float vy_y#

[in] element 1 of column 1 of 3x4 matrix

float vy_z#

[in] element 2 of column 1 of 3x4 matrix

float pad1#

[in] ignored padding

float vz_x#

[in] element 0 of column 2 of 3x4 matrix

float vz_y#

[in] element 1 of column 2 of 3x4 matrix

float vz_z#

[in] element 2 of column 2 of 3x4 matrix

float pad2#

[in] ignored padding

float p_x#

[in] element 0 of column 3 of 3x4 matrix

float p_y#

[in] element 1 of column 3 of 3x4 matrix

float p_z#

[in] element 2 of column 3 of 3x4 matrix

float pad3#

[in] ignored padding

ze_rtas_transform_float3x4_row_major_exp_t#

struct ze_rtas_transform_float3x4_row_major_exp_t#

3x4 affine transformation in row-major layout

  • A 3x4 affine transformation in row-major layout, consisting of vectors

    • vx=(vx_x, vx_y, vx_z),

    • vy=(vy_x, vy_y, vy_z),

    • vz=(vz_x, vz_y, vz_z), and

    • p=(p_x, p_y, p_z)

  • The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.

Public Members

float vx_x#

[in] element 0 of row 0 of 3x4 matrix

float vy_x#

[in] element 1 of row 0 of 3x4 matrix

float vz_x#

[in] element 2 of row 0 of 3x4 matrix

float p_x#

[in] element 3 of row 0 of 3x4 matrix

float vx_y#

[in] element 0 of row 1 of 3x4 matrix

float vy_y#

[in] element 1 of row 1 of 3x4 matrix

float vz_y#

[in] element 2 of row 1 of 3x4 matrix

float p_y#

[in] element 3 of row 1 of 3x4 matrix

float vx_z#

[in] element 0 of row 2 of 3x4 matrix

float vy_z#

[in] element 1 of row 2 of 3x4 matrix

float vz_z#

[in] element 2 of row 2 of 3x4 matrix

float p_z#

[in] element 3 of row 2 of 3x4 matrix

ze_rtas_aabb_exp_t#

struct ze_rtas_aabb_exp_t#

A 3-dimensional axis-aligned bounding-box with lower and upper bounds in each dimension.

Public Members

ze_rtas_float3_exp_t lower#

[in] lower bounds of AABB

ze_rtas_float3_exp_t upper#

[in] upper bounds of AABB

ze_rtas_triangle_indices_uint32_exp_t#

struct ze_rtas_triangle_indices_uint32_exp_t#

Triangle represented using 3 vertex indices.

  • Represents a triangle using 3 vertex indices that index into a vertex array that needs to be provided together with the index array.

  • The linear barycentric u/v parametrization of the triangle is defined as:

    • (u=0, v=0) at v0,

    • (u=1, v=0) at v1, and

    • (u=0, v=1) at v2

Public Members

uint32_t v0#

[in] first index pointing to the first triangle vertex in vertex array

uint32_t v1#

[in] second index pointing to the second triangle vertex in vertex array

uint32_t v2#

[in] third index pointing to the third triangle vertex in vertex array

ze_rtas_quad_indices_uint32_exp_t#

struct ze_rtas_quad_indices_uint32_exp_t#

Quad represented using 4 vertex indices.

  • Represents a quad composed of 4 indices that index into a vertex array that needs to be provided together with the index array.

  • A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:

    • (u=0, v=0) at v0,

    • (u=1, v=0) at v1,

    • (u=0, v=1) at v3, and

    • (u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.

Public Members

uint32_t v0#

[in] first index pointing to the first quad vertex in vertex array

uint32_t v1#

[in] second index pointing to the second quad vertex in vertex array

uint32_t v2#

[in] third index pointing to the third quad vertex in vertex array

uint32_t v3#

[in] fourth index pointing to the fourth quad vertex in vertex array

ze_rtas_builder_geometry_info_exp_t#

struct ze_rtas_builder_geometry_info_exp_t#

Ray tracing acceleration structure builder geometry info.

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type

ze_rtas_builder_triangles_geometry_info_exp_t#

struct ze_rtas_builder_triangles_geometry_info_exp_t#

Ray tracing acceleration structure builder triangle mesh geometry info.

  • The linear barycentric u/v parametrization of the triangle is defined as:

    • (u=0, v=0) at v0,

    • (u=1, v=0) at v1, and

    • (u=0, v=1) at v2

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_TRIANGLES

ze_rtas_builder_packed_geometry_exp_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

ze_rtas_builder_packed_input_data_format_exp_t triangleFormat#

[in] format of triangle buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_TRIANGLE_INDICES_UINT32

ze_rtas_builder_packed_input_data_format_exp_t vertexFormat#

[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3

uint32_t triangleCount#

[in] number of triangles in triangle buffer

uint32_t vertexCount#

[in] number of vertices in vertex buffer

uint32_t triangleStride#

[in] stride (in bytes) of triangles in triangle buffer

uint32_t vertexStride#

[in] stride (in bytes) of vertices in vertex buffer

void *pTriangleBuffer#

[in] pointer to array of triangle indices in specified format

void *pVertexBuffer#

[in] pointer to array of triangle vertices in specified format

ze_rtas_builder_quads_geometry_info_exp_t#

struct ze_rtas_builder_quads_geometry_info_exp_t#

Ray tracing acceleration structure builder quad mesh geometry info.

  • A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:

    • (u=0, v=0) at v0,

    • (u=1, v=0) at v1,

    • (u=0, v=1) at v3, and

    • (u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_QUADS

ze_rtas_builder_packed_geometry_exp_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

ze_rtas_builder_packed_input_data_format_exp_t quadFormat#

[in] format of quad buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_QUAD_INDICES_UINT32

ze_rtas_builder_packed_input_data_format_exp_t vertexFormat#

[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3

uint32_t quadCount#

[in] number of quads in quad buffer

uint32_t vertexCount#

[in] number of vertices in vertex buffer

uint32_t quadStride#

[in] stride (in bytes) of quads in quad buffer

uint32_t vertexStride#

[in] stride (in bytes) of vertices in vertex buffer

void *pQuadBuffer#

[in] pointer to array of quad indices in specified format

void *pVertexBuffer#

[in] pointer to array of quad vertices in specified format

ze_rtas_geometry_aabbs_exp_cb_params_t#

struct ze_rtas_geometry_aabbs_exp_cb_params_t#

AABB callback function parameters.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t primID#

[in] first primitive to return bounds for

uint32_t primIDCount#

[in] number of primitives to return bounds for

void *pGeomUserPtr#

[in] pointer provided through geometry descriptor

void *pBuildUserPtr#

[in] pointer provided through zeRTASBuilderBuildExp function

ze_rtas_aabb_exp_t *pBoundsOut#

[out] destination buffer to write AABB bounds to

ze_rtas_builder_procedural_geometry_info_exp_t#

struct ze_rtas_builder_procedural_geometry_info_exp_t#

Ray tracing acceleration structure builder procedural primitives geometry info.

  • A host-side bounds callback function is invoked by the acceleration structure builder to query the bounds of procedural primitives on demand. The callback is passed some pGeomUserPtr that can point to an application-side representation of the procedural primitives. Further, a second pBuildUserPtr, which is set by a parameter to zeRTASBuilderBuildExp, is passed to the callback. This allows the build to change the bounds of the procedural geometry, for example, to build a BVH only over a short time range to implement multi-segment motion blur.

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_PROCEDURAL

ze_rtas_builder_packed_geometry_exp_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

uint8_t reserved#

[in] reserved for future use

uint32_t primCount#

[in] number of primitives in geometry

ze_rtas_geometry_aabbs_cb_exp_t pfnGetBoundsCb#

[in] pointer to callback function to get the axis-aligned bounding-box for a range of primitives

void *pGeomUserPtr#

[in] user data pointer passed to callback

ze_rtas_builder_instance_geometry_info_exp_t#

struct ze_rtas_builder_instance_geometry_info_exp_t#

Ray tracing acceleration structure builder instance geometry info.

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_INSTANCE

ze_rtas_builder_packed_instance_exp_flags_t instanceFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

ze_rtas_builder_packed_input_data_format_exp_t transformFormat#

[in] format of the specified transformation

uint32_t instanceUserID#

[in] user-specified identifier for the instance

void *pTransform#

[in] object-to-world instance transformation in specified format

ze_rtas_aabb_exp_t *pBounds#

[in] object-space axis-aligned bounding-box of the instanced acceleration structure

void *pAccelerationStructure#

[in] pointer to acceleration structure to instantiate

ze_rtas_builder_build_op_exp_desc_t#

struct ze_rtas_builder_build_op_exp_desc_t#

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_format_exp_t rtasFormat#

[in] ray tracing acceleration structure format

ze_rtas_builder_build_quality_hint_exp_t buildQuality#

[in] acceleration structure build quality hint

ze_rtas_builder_build_op_exp_flags_t buildFlags#

[in] 0 or some combination of ze_rtas_builder_build_op_exp_flag_t flags

const ze_rtas_builder_geometry_info_exp_t **ppGeometries#

[in][optional][range(0, numGeometries)] NULL or a valid array of pointers to geometry infos

uint32_t numGeometries#

[in] number of geometries in geometry infos array, can be zero when ppGeometries is NULL

Counterbasedeventpool#

Counterbasedeventpool Enums#

ze_event_pool_counter_based_exp_version_t#

enum ze_event_pool_counter_based_exp_version_t#

Counter-based Event Pools Extension Version(s)

Values:

enumerator ZE_EVENT_POOL_COUNTER_BASED_EXP_VERSION_1_0#

version 1.0

enumerator ZE_EVENT_POOL_COUNTER_BASED_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_EVENT_POOL_COUNTER_BASED_EXP_VERSION_FORCE_UINT32#

ze_event_pool_counter_based_exp_flags_t#

enum ze_event_pool_counter_based_exp_flag_t#

Values:

enumerator ZE_EVENT_POOL_COUNTER_BASED_EXP_FLAG_IMMEDIATE#

Counter-based event pool is used for immediate command lists (default)

enumerator ZE_EVENT_POOL_COUNTER_BASED_EXP_FLAG_NON_IMMEDIATE#

Counter-based event pool is for non-immediate command lists.

enumerator ZE_EVENT_POOL_COUNTER_BASED_EXP_FLAG_FORCE_UINT32#

Counterbasedeventpool Structures#

ze_event_pool_counter_based_exp_desc_t#

struct ze_event_pool_counter_based_exp_desc_t#

Event pool descriptor for counter-based events. This structure may be passed to zeEventPoolCreate as pNext member of ze_event_pool_desc_t.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_event_pool_counter_based_exp_flags_t flags#

[in] mode flags. must be 0 (default) or a valid value of ze_event_pool_counter_based_exp_flag_t default behavior is counter-based event pool is only used for immediate command lists.

Bindlessimages#

Bindlessimages Functions#

zeMemGetPitchFor2dImage#

ZE_APIEXPORT ze_result_t ZE_APICALL zeMemGetPitchFor2dImage(ze_context_handle_t hContext, ze_device_handle_t hDevice, size_t imageWidth, size_t imageHeight, unsigned int elementSizeInBytes, size_t *rowPitch)#

Allocate pitched USM memory for images.

  • Retrieves pitch for 2D image given the width, height and size in bytes

  • The memory is then allocated using zeMemAllocDevice by providing input size calculated as the returned pitch value multiplied by image height

  • The application may call this function from simultaneous threads

  • The implementation of this function must be thread-safe.

  • The implementation of this function should be lock-free.

  • The implementation must support ::ZE_experimental_bindless_image extension.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • imageWidth – [in] imageWidth

  • imageHeight – [in] imageHeight

  • elementSizeInBytes – [in] Element size in bytes

  • rowPitch – [out] rowPitch

Returns:

zeImageGetDeviceOffsetExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageGetDeviceOffsetExp(ze_image_handle_t hImage, uint64_t *pDeviceOffset)#

Get bindless device offset for image.

  • The application may call this function from simultaneous threads

  • The implementation of this function must be thread-safe.

  • The implementation of this function should be lock-free.

  • The implementation must support ::ZE_experimental_bindless_image extension.

Parameters:

  • hImage – [in] handle of the image

  • pDeviceOffset – [out] bindless device offset for image

Returns:

Bindlessimages Enums#

ze_bindless_image_exp_version_t#

enum ze_bindless_image_exp_version_t#

Bindless Image Extension Version(s)

Values:

enumerator ZE_BINDLESS_IMAGE_EXP_VERSION_1_0#

version 1.0

enumerator ZE_BINDLESS_IMAGE_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_BINDLESS_IMAGE_EXP_VERSION_FORCE_UINT32#

ze_image_bindless_exp_flags_t#

enum ze_image_bindless_exp_flag_t#

Values:

enumerator ZE_IMAGE_BINDLESS_EXP_FLAG_BINDLESS#

Bindless images are created with zeImageCreate. The image handle created with this flag is valid on both host and device.

enumerator ZE_IMAGE_BINDLESS_EXP_FLAG_SAMPLED_IMAGE#

Bindless sampled images are created with zeImageCreate by combining BINDLESS and SAMPLED_IMAGE. Create sampled image view from bindless unsampled image using SAMPLED_IMAGE.

enumerator ZE_IMAGE_BINDLESS_EXP_FLAG_FORCE_UINT32#

Bindlessimages Structures#

ze_image_bindless_exp_desc_t#

struct ze_image_bindless_exp_desc_t#

Image descriptor for bindless images. This structure may be passed to zeImageCreate via pNext member of ze_image_desc_t.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_image_bindless_exp_flags_t flags#

[in] image flags. must be 0 (default) or a valid value of ze_image_bindless_exp_flag_t default behavior is bindless images are not used when creating handles via zeImageCreate. When the flag is passed to zeImageCreate, then only the memory for the image is allocated. Additional image handles can be created with zeImageViewCreateExt. When ZE_IMAGE_BINDLESS_EXP_FLAG_SAMPLED_IMAGE flag is passed, ze_sampler_desc_t must be attached via pNext member of ze_image_bindless_exp_desc_t.

ze_image_pitched_exp_desc_t#

struct ze_image_pitched_exp_desc_t#

Image descriptor for bindless images created from pitched allocations. This structure may be passed to zeImageCreate via pNext member of ze_image_desc_t.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

void *ptr#

[in] pointer to pitched device allocation allocated using zeMemAllocDevice

ze_device_pitched_alloc_exp_properties_t#

struct ze_device_pitched_alloc_exp_properties_t#

Device specific properties for pitched allocations.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

size_t maxImageLinearWidth#

[out] Maximum image linear width.

size_t maxImageLinearHeight#

[out] Maximum image linear height.

Commandlistclone#

Commandlistclone Functions#

zeCommandListCreateCloneExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListCreateCloneExp(ze_command_list_handle_t hCommandList, ze_command_list_handle_t *phClonedCommandList)#

Creates a command list as the clone of another command list.

  • The source command list must be created with the ZE_COMMAND_LIST_FLAG_EXP_CLONEABLE flag.

  • The source command list must be closed prior to cloning.

  • The source command list may be cloned while it is running on the device.

  • The cloned command list inherits all properties of the source command list.

  • The cloned command list must be destroyed prior to the source command list.

  • The application must only use the command list for the device, or its sub-devices, which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hCommandList – [in] handle to source command list (the command list to clone)

  • phClonedCommandList – [out] pointer to handle of the cloned command list

Returns:

Commandlistclone Enums#

ze_command_list_clone_exp_version_t#

enum ze_command_list_clone_exp_version_t#

Command List Clone Extension Version(s)

Values:

enumerator ZE_COMMAND_LIST_CLONE_EXP_VERSION_1_0#

version 1.0

enumerator ZE_COMMAND_LIST_CLONE_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_COMMAND_LIST_CLONE_EXP_VERSION_FORCE_UINT32#

Immediatecommandlistappend#

Immediatecommandlistappend Functions#

zeCommandListImmediateAppendCommandListsExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListImmediateAppendCommandListsExp(ze_command_list_handle_t hCommandListImmediate, uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends command lists to dispatch from an immediate command list.

  • The application must call this function only with command lists created with zeCommandListCreateImmediate.

  • The command lists passed to this function in the phCommandLists argument must be regular command lists (i.e. not immediate command lists).

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandListImmediate – [in] handle of the immediate command list

  • numCommandLists – [in] number of command lists

  • phCommandLists – [in][range(0, numCommandLists)] handles of command lists

  • hSignalEvent – [in][optional] handle of the event to signal on completion

    • if not null, this event is signaled after the completion of all appended command lists

  • numWaitEvents – [in][optional] number of events to wait on before executing appended command lists; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing appended command lists.

    • if not null, all wait events must be satisfied prior to the start of any appended command list(s)

Returns:

Immediatecommandlistappend Enums#

ze_immediate_command_list_append_exp_version_t#

enum ze_immediate_command_list_append_exp_version_t#

Immediate Command List Append Extension Version(s)

Values:

enumerator ZE_IMMEDIATE_COMMAND_LIST_APPEND_EXP_VERSION_1_0#

version 1.0

enumerator ZE_IMMEDIATE_COMMAND_LIST_APPEND_EXP_VERSION_CURRENT#

latest known version

enumerator ZE_IMMEDIATE_COMMAND_LIST_APPEND_EXP_VERSION_FORCE_UINT32#
Contents