firmware_status(3)

📦
version 1.3.1 · 3 versions
, in epel 10

💖 NAME 💖

okay so this is firmware_status(3) from the Library Functions Manual, and the page is all about firmware_status — yes bestie, that's the name, and it's serving main-character energy. 🎀 This page is long, so it comes in three parts, and this is part 1.

✨ SYNOPSIS ✨

The synopsis is giving “lots of functions,” and we are not skipping a single one. No cap. 💅

🦋 Topics

  • Oprom
  • Enumeration
  • Ifr

🦋 Data Structures

  • struct igsc_fw_update_flags

🦋 Macros

  • #define IGSC_MAX_FW_STATUS_INDEX 5

🦋 Typedefs

  • typedef void(* igsc_log_func_t) (enum igsc_log_level_type log_level, const char *fmt,...) — Callback function template for printing igsc log messages. 💬
  • typedef void(* igsc_progress_func_t) (uint32_t sent, uint32_t total, void *ctx) — Callback function template for monitor firmware update progress. 📈

🦋 Functions

  • IGSC_EXPORT uint32_t igsc_get_last_firmware_status (IN struct igsc_device_handle *handle) — Return the last firmware status code. 🔎
  • IGSC_EXPORT const char * igsc_translate_firmware_status (IN uint32_t firmware_status) — Return the firmware status message corresponding to the code. 🗣️
  • IGSC_EXPORT int igsc_read_fw_status_reg (IN struct igsc_device_handle *handle, IN uint32_t fwsts_index, OUT uint32_t *fwsts_value) — Read firmware status register. 📖
  • IGSC_EXPORT void igsc_set_log_callback_func (IN igsc_log_func_t log_callback_f) — Sets log callback function. This interface is not thread-aware, Changes here may lead to crashes in multi-thread app when the thread setting callback exists without setting this call-back function to NULL while other thread from same app continues to run. ⚠️
  • IGSC_EXPORT igsc_log_func_t igsc_get_log_callback_func (void) — Retrieves log callback function pointer. 🪝
  • IGSC_EXPORT int igsc_device_init_by_device (IN OUT struct igsc_device_handle *handle, IN const char *device_path) — Initializes a GSC Firmware Update device. 🛠️
  • int igsc_device_init_by_handle (IN OUT struct igsc_device_handle *handle, IN igsc_handle_t dev_handle) — Initializes a GSC Firmware Update device. 🛠️
  • IGSC_EXPORT int igsc_device_init_by_device_info (IN OUT struct igsc_device_handle *handle, IN const struct igsc_device_info *dev_info) — Initializes a GSC Firmware Update device. 🛠️
  • IGSC_EXPORT int igsc_device_get_device_info (IN struct igsc_device_handle *handle, OUT struct igsc_device_info *dev_info) — Retrieve device information from the system. 💾
  • IGSC_EXPORT int igsc_device_update_device_info (IN struct igsc_device_handle *handle, OUT struct igsc_device_info *dev_info) — Update device information from the firmware The subsystem device id and the subsystem vendor id, reported by the PCI system, may be different from the ones reported by the firmware and so the device information should be updated by with the values received from the firmware. 🔄
  • IGSC_EXPORT int igsc_device_close (IN OUT struct igsc_device_handle *handle) — Closes a GSC Firmware Update device. 🚪
  • IGSC_EXPORT int igsc_device_fw_version (IN struct igsc_device_handle *handle, OUT struct igsc_fw_version *version) — Retrieves the GSC Firmware Version from the device. 🏷️
  • IGSC_EXPORT int igsc_image_fw_version (IN const uint8_t *buffer, IN uint32_t buffer_len, OUT struct igsc_fw_version *version) — Retrieves the Firmware Version from the provided firmware update image. 🖼️
  • IGSC_EXPORT int igsc_device_hw_config (IN struct igsc_device_handle *handle, OUT struct igsc_hw_config *hw_config) — Retrieves the hw configuration from the device. ⚙️
  • IGSC_EXPORT int igsc_device_subsystem_ids (IN struct igsc_device_handle *handle, OUT struct igsc_subsystem_ids *ssids) — Retrieves the subsystem ids (vid/did) from the device. 🆔
  • IGSC_EXPORT int igsc_image_hw_config (IN const uint8_t *buffer, IN uint32_t buffer_len, OUT struct igsc_hw_config *hw_config) — Retrieves the hw configurations from the provided firmware update image. ⚙️
  • IGSC_EXPORT int igsc_hw_config_compatible (IN const struct igsc_hw_config *image_hw_config, IN const struct igsc_hw_config *device_hw_config) — Check whether image hardware configuration compatible with device hardware configuration. ✅
  • IGSC_EXPORT int igsc_hw_config_to_string (IN const struct igsc_hw_config *hw_config, IN char *buf, IN size_t length) — express hw configuration in a string. 🧵
  • IGSC_EXPORT int igsc_device_fw_update (IN struct igsc_device_handle *handle, IN const uint8_t *buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void *ctx) — Perform the firmware update from the provided firmware update image. 🚀
  • IGSC_EXPORT int igsc_device_fw_update_ex (IN struct igsc_device_handle *handle, IN const uint8_t *buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void *ctx, IN struct igsc_fw_update_flags flags) — Perform the firmware update with flags from the provided firmware update image. 🚀
  • IGSC_EXPORT int igsc_iaf_psc_update (IN struct igsc_device_handle *handle, IN const uint8_t *buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void *ctx) — Perform Intel Accelerator Fabric Platform Specific Configuration (PSC) update from the provided update data image. 🧠
  • IGSC_EXPORT int igsc_device_fwdata_update (IN struct igsc_device_handle *handle, IN const uint8_t *buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void *ctx) — Perform the GSC firmware in-field data update from the provided firmware update image. 📦
  • IGSC_EXPORT int igsc_device_fwdata_image_update (IN struct igsc_device_handle *handle, IN struct igsc_fwdata_image *img, IN igsc_progress_func_t progress_f, IN void *ctx) — Perform the GSC firmware in-field data update from the provided firmware update image. 📦
  • IGSC_EXPORT int igsc_image_fwdata_init (IN OUT struct igsc_fwdata_image **img, IN const uint8_t *buffer, IN uint32_t buffer_len) — initializes firmware data image handle from the supplied firmware data update image. 🧰
  • IGSC_EXPORT int igsc_device_fwdata_version (IN struct igsc_device_handle *handle, OUT struct igsc_fwdata_version *version) — Retrieves the GSC in-field data Firmware Version from the device. 🏷️
  • IGSC_EXPORT int igsc_device_fwdata_version2 (IN struct igsc_device_handle *handle, OUT struct igsc_fwdata_version2 *version) — Retrieves the GSC in-field data Firmware Version from the device With ability to return FW Data version in second version format. 🏷️
  • IGSC_EXPORT int igsc_image_fwdata_version (IN struct igsc_fwdata_image *img, OUT struct igsc_fwdata_version *version) — Retrieves the GSC in-field data Firmware version from the supplied GSC in-field data Firmware update image. 🖼️
  • IGSC_EXPORT int igsc_image_fwdata_version2 (IN struct igsc_fwdata_image *img, OUT struct igsc_fwdata_version2 *version) — Retrieves the GSC in-field data Firmware version from the supplied GSC in-field data Firmware update image. With ability to return FW Data version in second version format. 🖼️
  • IGSC_EXPORT uint8_t igsc_fwdata_version_compare (IN struct igsc_fwdata_version *image_ver, IN struct igsc_fwdata_version *device_ver) — Compares input GSC in-field data firmware update version to the flash one With ability to compare FW Data version in second version format. ⚖️
  • IGSC_EXPORT uint8_t igsc_fwdata_version_compare2 (IN struct igsc_fwdata_version2 *image_ver, IN struct igsc_fwdata_version2 *device_ver) — Compares input GSC in-field data firmware update version to the flash one. ⚖️
  • IGSC_EXPORT int igsc_image_fwdata_count_devices (IN struct igsc_fwdata_image *img, OUT uint32_t *count) — Retrieves a count of of different devices supported by the GSC in-field data firmware update image associated with the handle. 🔢
  • IGSC_EXPORT int igsc_image_fwdata_supported_devices (IN struct igsc_fwdata_image *img, OUT struct igsc_fwdata_device_info *devices, IN OUT uint32_t *count) — Retrieves a list of supported devices by the GSC in-field data firmware update image associated with the handle. The caller supplies allocated buffer devices of count size. The function returns count filled with actually returned devices. 📋
  • IGSC_EXPORT int igsc_image_fwdata_match_device (IN struct igsc_fwdata_image *img, IN struct igsc_device_info *device) — check if GSC in-field data firmware image can be applied on the device. 🎯
  • IGSC_EXPORT int igsc_image_fwdata_iterator_reset (IN struct igsc_fwdata_image *img) — reset the iterator over supported devices. 🔁
  • IGSC_EXPORT int igsc_image_fwdata_iterator_next (IN struct igsc_fwdata_image *img, OUT struct igsc_fwdata_device_info *device) — progress the supported device iterator and return the GSC in-field data firmware device info. ➡️
  • IGSC_EXPORT int igsc_image_fwdata_release (IN struct igsc_fwdata_image *img) — release the fwdata image handle. 🧹
  • IGSC_EXPORT uint8_t igsc_fw_version_compare (IN struct igsc_fw_version *image_ver, IN struct igsc_fw_version *device_ver) — Compares input fw version to the flash one. ⚖️
  • IGSC_EXPORT int igsc_device_oprom_version (IN struct igsc_device_handle *handle, IN uint32_t oprom_type, OUT struct igsc_oprom_version *version) — Retrieves the GSC OPROM version from the device. 🏷️
  • IGSC_EXPORT int igsc_device_oprom_update (IN struct igsc_device_handle *handle, IN uint32_t oprom_type, IN struct igsc_oprom_image *img, IN igsc_progress_func_t progress_f, IN void *ctx) — Perform the OPROM update from the provided image. 🚀

🌸 DETAILED DESCRIPTION 🌸

The original page doesn't drop extra prose in this section, so we're sliding straight into the data structure docs. 💅

🎀 DATA STRUCTURE DOCUMENTATION 🎀

🌟 struct igsc_fw_update_flags

Definition at line 647 of file igsc_lib.h. 📍

Data Fields:

  • uint32_t force_update: 1
  • uint32_t reserved: 31

🍓 MACRO DEFINITION DOCUMENTATION 🍓

🌸 #define IGSC_MAX_FW_STATUS_INDEX 5

Definition at line 404 of file igsc_lib.h. 📍

🧚 TYPEDEF DOCUMENTATION 🧚

💫 igsc_log_func_t

typedef void(* igsc_log_func_t) (enum igsc_log_level_type log_level, const char *fmt,...) — Callback function template for printing igsc log messages. 💬

Parameters:

  • log_level — log level of the error message.
  • fmt — log message format.
  • ... — variadic parameters.

Definition at line 427 of file igsc_lib.h. 📍

💫 igsc_progress_func_t

typedef void(* igsc_progress_func_t) (uint32_t sent, uint32_t total, void *ctx) — Callback function template for monitor firmware update progress. 📈

Parameters:

  • sent — Number of bytes sent to the firmware.
  • total — Total number of bytes in firmware update image.
  • ctx — Context provided by caller.

Definition at line 625 of file igsc_lib.h. 📍

👑 FUNCTION DOCUMENTATION 👑

This part only has one function documented in detail, bestie — yes, just igsc_device_close in this chunk. The rest of the synopsis is above. 🌈

💅 igsc_device_close

IGSC_EXPORT int igsc_device_close (IN OUT struct igsc_device_handle *
       handle)

Closes a GSC Firmware Update device. 🫶

Parameters:

  • handle — A handle to the device.

Returns:

  • IGSC_SUCCESS if successful, otherwise error code.

igsc_device_fw_update

IGSC_EXPORT int igsc_device_fw_update (IN struct igsc_device_handle * handle, IN const uint8_t * buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void * ctx)

Okay so this is the classic “push the firmware update image onto the device” move. 💖 It performs the firmware update from the provided firmware update image.

Parameters:

  • handle — a handle to the device.
  • buffer — a pointer to the buffer with the firmware update image.
  • buffer_len — length of the buffer with the firmware update image.
  • progress_f — pointer to the callback function for firmware update progress monitor.
  • ctx — context passed to the progress_f function.

Returns: <pink>IGSC_SUCCESS</pink> if successful, otherwise error code. ✨

igsc_device_fw_update_ex

IGSC_EXPORT int igsc_device_fw_update_ex (IN struct igsc_device_handle * handle, IN const uint8_t * buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void * ctx, IN struct igsc_fw_update_flags flags)

This one is the firmware update with flags — same firmware update image energy, but with flags deciding how the update should be performed. 🎀

Parameters:

  • handle — a handle to the device.
  • buffer — a pointer to the buffer with the firmware update image.
  • buffer_len — length of the buffer with the firmware update image.
  • progress_f — pointer to the callback function for firmware update progress monitor.
  • ctx — context passed to the progress_f function.
  • flags — flags with which the update should be performed.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🫶

igsc_device_fw_version

IGSC_EXPORT int igsc_device_fw_version (IN struct igsc_device_handle * handle, OUT struct igsc_fw_version * version)

Retrieves the GSC Firmware Version from the device. 👑

Parameters:

  • handle — a handle to the device.
  • version — the memory to store the obtained firmware version.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🌸

igsc_device_fwdata_image_update

IGSC_EXPORT int igsc_device_fwdata_image_update (IN struct igsc_device_handle * handle, IN struct igsc_fwdata_image * img, IN igsc_progress_func_t progress_f, IN void * ctx)

Performs the GSC firmware in-field data update from the provided firmware update image. 🦋

Parameters:

  • handle — a handle to the device.
  • img — a pointer to the parsed firmware data image structure.
  • progress_f — pointer to the callback function for firmware update progress monitor.
  • ctx — context passed to the progress_f function.

Returns: IGSC_SUCCESS if successful, otherwise error code. ⭐

igsc_device_fwdata_update

IGSC_EXPORT int igsc_device_fwdata_update (IN struct igsc_device_handle * handle, IN const uint8_t * buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void * ctx)

Performs the GSC firmware in-field data update from the provided firmware update image — this time you’re handing over the raw buffer. 💅

Parameters:

  • handle — a handle to the device.
  • buffer — a pointer to the buffer with the firmware in-field data update image.
  • buffer_len — length of the buffer with the firmware in-field data update image.
  • progress_f — pointer to the callback function for firmware update progress monitor.
  • ctx — context passed to the progress_f function.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🍓

igsc_device_fwdata_version

IGSC_EXPORT int igsc_device_fwdata_version (IN struct igsc_device_handle * handle, OUT struct igsc_fwdata_version * version)

Retrieves the GSC in-field data Firmware Version from the device. 🧚

Parameters:

  • handle — a handle to the device.
  • version — the memory to store the obtained firmware version.

Returns: IGSC_SUCCESS if successful, otherwise error code. 💜

igsc_device_fwdata_version2

IGSC_EXPORT int igsc_device_fwdata_version2 (IN struct igsc_device_handle * handle, OUT struct igsc_fwdata_version2 * version)

Retrieves the GSC in-field data Firmware Version from the device, with the ability to return FW Data version in second version format. ✨

Parameters:

  • handle — a handle to the device.
  • version — the memory to store the obtained firmware version.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🌈

igsc_device_get_device_info

IGSC_EXPORT int igsc_device_get_device_info (IN struct igsc_device_handle * handle, OUT struct igsc_device_info * dev_info)

Retrieves device information from the system. 🎀

Parameters:

  • handle — an initialized handle to the device.
  • dev_info — a device info structure.

Returns: IGSC_SUCCESS if successful, otherwise error code. 💖

igsc_device_hw_config

IGSC_EXPORT int igsc_device_hw_config (IN struct igsc_device_handle * handle, OUT struct igsc_hw_config * hw_config)

Retrieves the hw configuration from the device. 🔥

Parameters:

  • handle — a handle to the device.
  • hw_config — the memory to store the obtained hardware configuration.

Returns:

  • IGSC_SUCCESS if successful, otherwise error code.
  • IGSC_ERROR_NOT_SUPPORTED if feature is not supported.

igsc_device_init_by_device

IGSC_EXPORT int igsc_device_init_by_device (IN OUT struct igsc_device_handle * handle, IN const char * device_path)

Initializes a GSC Firmware Update device. 👑

Parameters:

  • handle — a handle to the device. All subsequent calls to the lib’s functions must be with this handle.
  • device_path — a path to the device.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🌟

igsc_device_init_by_device_info

IGSC_EXPORT int igsc_device_init_by_device_info (IN OUT struct igsc_device_handle * handle, IN const struct igsc_device_info * dev_info)

Also initializes a GSC Firmware Update device — this time using device info. 🦋

Parameters:

  • handle — a handle to the device. All subsequent calls to the lib’s functions must be with this handle.
  • dev_info — a device info structure.

Returns: IGSC_SUCCESS if successful, otherwise error code. 💜

igsc_device_init_by_handle

int igsc_device_init_by_handle (IN OUT struct igsc_device_handle * handle, IN igsc_handle_t dev_handle)

Initializes a GSC Firmware Update device from an already-open device handle. 💅

Parameters:

  • handle — a handle to the device. All subsequent calls to the lib’s functions must be with this handle.
  • dev_handle — an open device handle.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🫶

igsc_device_oprom_update

IGSC_EXPORT int igsc_device_oprom_update (IN struct igsc_device_handle * handle, IN uint32_t oprom_type, IN struct igsc_oprom_image * img, IN igsc_progress_func_t progress_f, IN void * ctx)

Performs the OPROM update from the provided image. 🔥

Parameters:

  • handle — a handle to the device.
  • oprom_type — OPROM part to update.
  • See also: igsc_oprom_type
  • img — a pointer to the parsed oprom image structure.
  • progress_f — pointer to the callback function for OPROM update progress monitor.
  • ctx — context passed to the progress_f function.

Returns: IGSC_SUCCESS if successful, otherwise error code. ⭐

igsc_device_oprom_version

IGSC_EXPORT int igsc_device_oprom_version (IN struct igsc_device_handle * handle, IN uint32_t oprom_type, OUT struct igsc_oprom_version * version)

Retrieves the GSC OPROM version from the device. 🧚

Parameters:

  • handle — a handle to the device.
  • oprom_type — an OPROM type requested.
  • See also: enum igsc_oprom_type
  • version — the memory to store the obtained OPROM version.

Returns: IGSC_SUCCESS if successful, otherwise error code. 🌸

igsc_device_subsystem_ids

IGSC_EXPORT int igsc_device_subsystem_ids (IN struct igsc_device_handle * handle, OUT struct igsc_subsystem_ids * ssids)

Retrieves the subsystem ids (vid/did) from the device. 🎀

Parameters:

  • handle — a handle to the device.
  • ssids — the memory to store the obtained subsystem ids.

Returns:

  • IGSC_SUCCESS if successful, otherwise error code.
  • IGSC_ERROR_NOT_SUPPORTED if feature is not supported.

igsc_device_update_device_info

IGSC_EXPORT int igsc_device_update_device_info (IN struct igsc_device_handle * handle, OUT struct igsc_device_info * dev_info)

Updates device information from the firmware. 👑 The subsystem device id and the subsystem vendor id reported by the PCI system may be different from the ones reported by the firmware, so the device information should be updated with the values received from the firmware.

Parameters:

  • handle — an initialized handle to the device.
  • dev_info — a device info structure.

Returns: IGSC_SUCCESS if successful, otherwise error code. 💖

igsc_fw_version_compare

IGSC_EXPORT uint8_t igsc_fw_version_compare (IN struct igsc_fw_version * image_ver, IN struct igsc_fw_version * device_ver)

Compares input fw version to the flash one. 🦋

Parameters:

  • image_ver — pointer to the update image version.
  • device_ver — pointer to the device version.

Returns:

  • IGSC_VERSION_NOT_COMPATIBLE if update image is for a different platform.
  • IGSC_VERSION_NEWER if update image version is newer than the one on the device.
  • IGSC_VERSION_EQUAL if update image version is equal to the one on the device.
  • IGSC_VERSION_OLDER if update image version is older than the one on the device.
  • IGSC_VERSION_ERROR if NULL parameters were provided.

igsc_fwdata_version_compare

IGSC_EXPORT uint8_t igsc_fwdata_version_compare (IN struct igsc_fwdata_version * image_ver, IN struct igsc_fwdata_version * device_ver)

Compares input GSC in-field data firmware update version to the flash one, with the ability to compare FW Data version in second version format. 💅

Parameters:

  • image_ver — pointer to the GSC in-field data firmware update image version.
  • device_ver — pointer to the device GSC data firmware version.

Returns:

  • IGSC_FWDATA_VERSION_REJECT_VCN if image VCN version is bigger than device VCN.
  • IGSC_FWDATA_VERSION_REJECT_OEM_MANUF_DATA_VERSION if OEM manufacturing data version is not bigger than device OEM version.
  • IGSC_FWDATA_VERSION_REJECT_DIFFERENT_PROJECT if major version is different from device major version.
  • IGSC_FWDATA_VERSION_ACCEPT if VCN version is equal to the device’s one, and OEM is bigger.
  • IGSC_FWDATA_VERSION_OLDER_VCN if VCN version is smaller than the one on the device.

igsc_fwdata_version_compare2

IGSC_EXPORT uint8_t igsc_fwdata_version_compare2 (IN struct igsc_fwdata_version2 * image_ver, IN struct igsc_fwdata_version2 * device_ver)

Compares input GSC in-field data firmware update version to the flash one. 🔥

Parameters:

  • image_ver — pointer to the GSC in-field data firmware update image version.
  • device_ver — pointer to the device GSC data firmware version.

Returns:

  • IGSC_FWDATA_VERSION_REJECT_VCN if image VCN version is bigger than device VCN.
  • IGSC_FWDATA_VERSION_REJECT_OEM_MANUF_DATA_VERSION if OEM manufacturing data version is not bigger than device OEM version or equal in ver2 comparison.
  • IGSC_FWDATA_VERSION_REJECT_DIFFERENT_PROJECT if major version is different from device major version.
  • IGSC_FWDATA_VERSION_ACCEPT if VCN version is equal to the device’s one, and OEM is bigger.
  • IGSC_FWDATA_VERSION_OLDER_VCN if VCN version is smaller than the one on the device.
  • IGSC_FWDATA_VERSION_REJECT_WRONG_FORMAT — if the version format is the wrong one or, like, straight-up incompatible 😬
  • IGSC_FWDATA_VERSION_REJECT_ARB_SVN — if the update image's SVN version is smaller than the one already chilling on the device (no downgrades, bestie 💅)

igsc_get_last_firmware_status()

IGSC_EXPORT uint32_t igsc_get_last_firmware_status (IN struct igsc_device_handle * handle)

Returns the last firmware status code, bestie. That's it, that's the whole vibe.

Parameters

  • handle — a handle to the device ✨

Returns

The last firmware status code.

igsc_get_log_callback_func()

IGSC_EXPORT igsc_log_func_t igsc_get_log_callback_func (void )

Grabs you the log callback function pointer, no cap.

Returns

The log callback function pointer 🌸

igsc_hw_config_compatible()

IGSC_EXPORT int igsc_hw_config_compatible (IN const struct igsc_hw_config * image_hw_config, IN const struct igsc_hw_config * device_hw_config)

The vibe check for hardware: is the image's hardware config compatible with the device's hardware config? 👑

Parameters

  • image_hw_config — stores the image hardware configuration
  • device_hw_config — stores the device hardware configuration

Returns

IGSC_SUCCESS if the image hardware configuration is compatible with the device 🫶

igsc_hw_config_to_string()

IGSC_EXPORT int igsc_hw_config_to_string (IN const struct igsc_hw_config * hw_config, IN char * buf, IN size_t length)

Expresses the hw configuration as a string — turning hardware tea into readable tea ☕✨

Parameters

  • hw_config — stores the hardware configuration
  • buf — where you want the hw configuration stored as a printable, null-terminated string
  • length — the length of the supplied buffer

Returns

The number of bytes in the buffer, excluding the null terminator — or < 0 on error 😭

igsc_iaf_psc_update()

IGSC_EXPORT int igsc_iaf_psc_update (IN struct igsc_device_handle * handle, IN const uint8_t * buffer, IN const uint32_t buffer_len, IN igsc_progress_func_t progress_f, IN void * ctx)

Performs an Intel Accelerator Fabric Platform Specific Configuration (PSC) update from the update data image you hand it 🔥

Parameters

  • handle — a handle to the device
  • buffer — pointer to the buffer holding the PSC data update image
  • buffer_len — length of the buffer with the PSC data update image
  • progress_f — pointer to the callback function that monitors data update progress 👀
  • ctx — context passed along to the progress_f function

Returns

  • IGSC_SUCCESS if it worked
  • otherwise, an error code 💀

igsc_image_fw_version()

IGSC_EXPORT int igsc_image_fw_version (IN const uint8_t * buffer, IN uint32_t buffer_len, OUT struct igsc_fw_version * version)

Pulls the Firmware Version out of the firmware update image you gave it. Detective work, but make it firmware 🕵️‍♀️💖

Parameters

  • buffer — pointer to the buffer with the firmware update image
  • buffer_len — length of the buffer with the firmware update image
  • version — the memory where the obtained firmware version gets stored

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_count_devices()

IGSC_EXPORT int igsc_image_fwdata_count_devices (IN struct igsc_fwdata_image * img, OUT uint32_t * count)

Gets you a count of the different devices supported by the GSC in-field data firmware update image tied to the handle. Headcount, but for hardware 🧮✨

Parameters

  • img — GSC in-field data firmware image handle
  • count — the number of devices

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_init()

IGSC_EXPORT int igsc_image_fwdata_init (IN OUT struct igsc_fwdata_image ** img, IN const uint8_t * buffer, IN uint32_t buffer_len)

Initializes a firmware data image handle from the firmware data update image you supply. Glow-up for your pointer, honestly 🦋

Parameters

  • img — firmware data image handle allocated by the function (yes, it allocates it for you 👑)
  • buffer — pointer to the buffer with the firmware data update image
  • buffer_len — length of the buffer with the firmware data update image

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_iterator_next()

IGSC_EXPORT int igsc_image_fwdata_iterator_next (IN struct igsc_fwdata_image * img, OUT struct igsc_fwdata_device_info * device)

Advances the supported-device iterator and hands back the GSC in-field data firmware device info. Next, please 💅

Parameters

  • img — GSC in-field data firmware image handle
  • device — GSC in-field data firmware device information

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_iterator_reset()

IGSC_EXPORT int igsc_image_fwdata_iterator_reset (IN struct igsc_fwdata_image * img)

Resets the iterator over supported devices. Rewind era 🔁🎀

Parameters

  • img — GSC in-field data firmware image handle

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_match_device()

IGSC_EXPORT int igsc_image_fwdata_match_device (IN struct igsc_fwdata_image * img, IN struct igsc_device_info * device)

Checks whether the GSC in-field data firmware image can actually be applied on the device. Compatibility check, but make it official ✅

Parameters

  • img — GSC in-field data firmware image handle
  • device — physical device info

Returns

  • IGSC_SUCCESS if the device is on the list of supported devices
  • IGSC_ERROR_DEVICE_NOT_FOUND otherwise 🙈

igsc_image_fwdata_release()

IGSC_EXPORT int igsc_image_fwdata_release (IN struct igsc_fwdata_image * img)

Releases the fwdata image handle. Cleanup era, we love to see it 🧹💖

Parameters

  • img — fwdata image handle

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_supported_devices()

IGSC_EXPORT int igsc_image_fwdata_supported_devices (IN struct igsc_fwdata_image * img, OUT struct igsc_fwdata_device_info * devices, IN OUT uint32_t * count)

Retrieves the list of devices supported by the GSC in-field data firmware update image tied to the handle. You (the caller) bring a pre-allocated devices buffer of count size, and the function returns count filled with the devices it actually returned. So it's an in-out situation, very main character of it 🫶

Parameters

  • img — GSC in-field data firmware image handle
  • devices — list of devices supported by the GSC in-field data firmware image
  • count — in: the number of devices allocated

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_version()

IGSC_EXPORT int igsc_image_fwdata_version (IN struct igsc_fwdata_image * img, OUT struct igsc_fwdata_version * version)

Pulls the GSC in-field data Firmware version from the supplied GSC in-field data Firmware update image 🌟

Parameters

  • img — GSC in-field data Firmware image handle
  • version — the memory where the obtained GSC in-field data Firmware version gets stored

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_fwdata_version2()

IGSC_EXPORT int igsc_image_fwdata_version2 (IN struct igsc_fwdata_image * img, OUT struct igsc_fwdata_version2 * version)

Same idea as above — grabs the GSC in-field data Firmware version from the supplied GSC in-field data Firmware update image — except this one can return the FW Data version in the second version format 🔥✨

Parameters

  • img — GSC in-field data Firmware image handle
  • version — the memory where the obtained GSC in-field data Firmware version gets stored

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_image_hw_config()

IGSC_EXPORT int igsc_image_hw_config (IN const uint8_t * buffer, IN uint32_t buffer_len, OUT struct igsc_hw_config * hw_config)

Retrieves the hw configurations from the firmware update image you provided 🎀

Parameters

  • buffer — pointer to the buffer with the firmware update image
  • buffer_len — length of the buffer with the firmware update image
  • hw_config — the memory where the obtained hardware configuration gets stored

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_read_fw_status_reg()

IGSC_EXPORT int igsc_read_fw_status_reg (IN struct igsc_device_handle * handle, IN uint32_t fwsts_index, OUT uint32_t * fwsts_value)

Reads the firmware status register. Peeking behind the curtain, but legally 👀💜

Parameters

  • handle — a handle to the device
  • fwsts_index — index of the firmware status register, (0..IGSC_MAX_FW_STATUS_INDEX)
  • fwsts_value — the returned firmware status values

Returns

IGSC_SUCCESS if successful, otherwise an error code.

igsc_set_log_callback_func()

IGSC_EXPORT void igsc_set_log_callback_func (IN igsc_log_func_t log_callback_f)

Sets the log callback function.

⚠️ Okay bestie, listen. This interface is not thread-aware. Changing stuff here can legitimately crash a multi-threaded app — specifically when the thread that sets the callback exits without setting this call-back function to NULL while another thread from the same app keeps running. So like... be careful, fr fr 😭💀

Parameters

  • log_callback_f — pointer to the callback function for igsc library log messages. Passing NULL to this disables the logging callback function 🙅‍♀️

Returns

void.

igsc_translate_firmware_status()

IGSC_EXPORT const char * igsc_translate_firmware_status (IN uint32_t firmware_status)

Returns the firmware status message that corresponds to the code. Translating firmware feelings into words 🗣️💬

Parameters

  • firmware_status — code of firmware status

Returns

The firmware status message corresponding to the code.

📜 Author

Generated automatically by Doxygen for the Intel Graphics System Controller Firmware Update Library, straight from the source code. So no human wrote the original — it's giving "the compiler wrote my essay" energy 🤖✨

And that's a wrap on firmware_status(3), bestie!! 🎀 The footer down at the bottom of the real page is just the source/version and date line — the Intel Graphics System Controller Firmware Update library, page firmware_status(3) — so I'm tipping my crown to it here instead of copy-pasting the whole thing. Go forth and update that firmware responsibly 💅🔥🦋

📦 where this page comes from