Firmware

oneAPI Level Zero Specification - Version 1.18.31

Firmware Functions

zesFirmwareGetProperties

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetProperties(zes_firmware_handle_t hFirmware, zes_firmware_properties_t *pProperties)

Get firmware properties.

• The application may call this function from simultaneous threads.

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

Parameters:

• hFirmware – [in] Handle for the component.

• pProperties – [in,out] Pointer to an array that will hold the properties of the firmware

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_HANDLE

  • nullptr == hFirmware

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pProperties

zesFirmwareFlash

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareFlash(zes_firmware_handle_t hFirmware, void *pImage, uint32_t size)

Flash a new firmware image.

• Any running workload must be gracefully closed before invoking this function.

• The application may call this function from simultaneous threads.

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

• This is a non-blocking call. Application may call zesFirmwareGetFlashProgress to get completion status.

Parameters:

• hFirmware – [in] Handle for the component.

• pImage – [in] Image of the new firmware to flash.

• size – [in] Size of the flash image.

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

  • nullptr == hFirmware

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pImage

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to perform this operation.

zesFirmwareGetFlashProgress

Added in version 1.8

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetFlashProgress(zes_firmware_handle_t hFirmware, uint32_t *pCompletionPercent)

Get Firmware Flash Progress.

• The application may call this function from simultaneous threads.

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

Parameters:

• hFirmware – [in] Handle for the component.

• pCompletionPercent – [in,out] Pointer to the Completion Percentage of Firmware Update

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_HANDLE

  • nullptr == hFirmware

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCompletionPercent

zesFirmwareGetConsoleLogs

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetConsoleLogs(zes_firmware_handle_t hFirmware, size_t *pSize, char *pFirmwareLog)

Get Firmware Console Logs.

• The caller may pass nullptr for pFirmwareLog and set pSize to zero when querying only for size.

• The caller must provide memory for Firmware log.

• The application may call this function from simultaneous threads.

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

Parameters:

• hFirmware – [in] Handle for the component.

• pSize – [in,out] size of firmware log

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

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_HANDLE

  • nullptr == hFirmware

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pSize

Firmware Structures

zes_firmware_properties_t

Added in version 1.0

struct zes_firmware_properties_t

Firmware properties.

Public Members

zes_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_bool_t onSubdevice

[out] True if the resource is located on a sub-device; false means that the resource is on the device of the calling Sysman handle

uint32_t subdeviceId

[out] If onSubdevice is true, this gives the ID of the sub-device

ze_bool_t canControl

[out] Indicates if software can flash the firmware assuming the user has permissions

char name[ZES_STRING_PROPERTY_SIZE]

[out] NULL terminated string value. The string “unknown” will be returned if this property cannot be determined.

char version[ZES_STRING_PROPERTY_SIZE]

[out] NULL terminated string value. The string “unknown” will be returned if this property cannot be determined.