Runtime API

oneAPI Level Zero Specification - Version 1.14.33

Common

• Functions

  • zerGetLastErrorDescription

  • zerTranslateDeviceHandleToIdentifier

  • zerTranslateIdentifierToDeviceHandle

  • zerGetDefaultContext

Common Functions

zerGetLastErrorDescription

ZE_APIEXPORT ze_result_t ZE_APICALL zerGetLastErrorDescription(const char **ppString)

Retrieves a string describing the last error code returned by the default 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 default driver.

• String returned is null-terminated.

Parameters:

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

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_NULL_POINTER

  • nullptr == ppString

zerTranslateDeviceHandleToIdentifier

ZE_APIEXPORT uint32_t ZE_APICALL zerTranslateDeviceHandleToIdentifier(ze_device_handle_t hDevice)

Translates device handle to integer identifier.

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

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

• In case of failure, this function returns UINT32_MAX.

Parameters:

hDevice – [in] handle of the device

Returns:

• integer identifier for the device

• UINT32_MAX

zerTranslateIdentifierToDeviceHandle

ZE_APIEXPORT ze_device_handle_t ZE_APICALL zerTranslateIdentifierToDeviceHandle(uint32_t identifier)

Translates to integer identifier to a device handle.

• The driver must be initialized before calling this function.

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

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

• In case of failure, this function returns null.

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

Parameters:

identifier – [in] integer identifier of the device

Returns:

• handle of the device with the given identifier

• nullptr

zerGetDefaultContext

ZE_APIEXPORT ze_context_handle_t ZE_APICALL zerGetDefaultContext(void)

Retrieves handle to default context from the default driver.

• The driver must be initialized before calling this function.

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

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

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

• In case of failure, this function returns null.

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

Returns:

• handle of the default context

• nullptr