Driver

Driver#

oneAPI Level Zero Specification - Version 1.18.31

Driver Functions#

zeDriverGet#

Added in version 1.0

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

Retrieves driver instances.

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:

zeDriverGetApiVersion#

Added in version 1.0

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.

  • Starting from API version 1.17, any driver reporting version 1.17 or later is assumed to support the ZE_DRIVER_DDI_HANDLES_EXT_NAME extension; see ze_driver_ddi_handles_ext_properties_t for details.

Parameters:

  • hDriver – [in] handle of the driver instance

  • version – [out] api version

Returns:

zeDriverGetProperties#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.1

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#

Added in version 1.6

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:

zeDriverGetDefaultContext#

Added in version 1.14

ZE_APIEXPORT ze_context_handle_t ZE_APICALL zeDriverGetDefaultContext(ze_driver_handle_t hDriver)#

Retrieves handle to default context from the driver.

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

  • This returned context contains all the devices available in the driver.

  • This function does not return error code, to get info about failure user may use zeDriverGetLastErrorDescription function.

  • In case of failure, this function returns null.

  • Details on the error can be retrieved using zeDriverGetLastErrorDescription function.

Parameters:

hDriver – [in] handle of the driver instance

Returns:

  • handle of the default context

  • nullptr

Driver Enums#

ze_api_version_t#

Added in version 1.0

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 (since v1.1)

enumerator ZE_API_VERSION_1_2#

version 1.2 (since v1.2)

enumerator ZE_API_VERSION_1_3#

version 1.3 (since v1.3)

enumerator ZE_API_VERSION_1_4#

version 1.4 (since v1.4)

enumerator ZE_API_VERSION_1_5#

version 1.5 (since v1.5)

enumerator ZE_API_VERSION_1_6#

version 1.6 (since v1.6)

enumerator ZE_API_VERSION_1_7#

version 1.7 (since v1.7)

enumerator ZE_API_VERSION_1_8#

version 1.8 (since v1.8)

enumerator ZE_API_VERSION_1_9#

version 1.9 (since v1.9)

enumerator ZE_API_VERSION_1_10#

version 1.10 (since v1.10)

enumerator ZE_API_VERSION_1_11#

version 1.11 (since v1.11)

enumerator ZE_API_VERSION_1_12#

version 1.12 (since v1.12)

enumerator ZE_API_VERSION_1_13#

version 1.13 (since v1.13)

enumerator ZE_API_VERSION_1_14#

version 1.14 (since v1.14)

enumerator ZE_API_VERSION_1_15#

version 1.15 (since v1.15)

enumerator ZE_API_VERSION_1_16#

version 1.16 (since v1.16)

enumerator ZE_API_VERSION_1_17#

version 1.17 (since v1.17)

enumerator ZE_API_VERSION_1_18#

version 1.18 (since v1.18)

enumerator ZE_API_VERSION_CURRENT#

latest known version

enumerator ZE_API_VERSION_FORCE_UINT32#

Value marking end of ZE_API_VERSION_* ENUMs.

ze_ipc_property_flags_t#

Added in version 1.0

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

Supports creating a handle type for memory allocations and event pools between processes on different physical devices connected through a fabric interconnect. See ze_ipc_mem_handle_type_ext_desc_t. (since v1.16)

enumerator ZE_IPC_PROPERTY_FLAG_FORCE_UINT32#

Value marking end of ZE_IPC_PROPERTY_FLAG_* ENUMs.

Driver Structures#

ze_driver_properties_t#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.0

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