Global

oneAPI Level Zero Specification - Version 1.18.31

Global Functions

zeInit

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeInit(ze_init_flags_t flags)

Initialize the ‘oneAPI’ driver(s)

• Deprecated:

  since 1.10. Please use zeInitDrivers()

Parameters:

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

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < flags

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

zeInitDrivers

Added in version 1.10

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. (zeInit is [Deprecated] and is replaced by zeInitDrivers)

• Calls to zeInit[Deprecated] or InitDrivers will not alter the drivers retrieved through either api.

• Drivers init through zeInit[Deprecated] 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 through 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[Deprecated] 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:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

  • nullptr == desc

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x0 == desc->flags

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

Global Enums

ze_init_flags_t

Added in version 1.0

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

Value marking end of ZE_INIT_FLAG_* ENUMs.

ze_init_driver_type_flags_t

Added in version 1.10

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

Value marking end of ZE_INIT_DRIVER_TYPE_FLAG_* ENUMs.

Global Structures

ze_init_driver_type_desc_t

Added in version 1.10

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