Firmware Fallback A and B#
Introduction#
The Firmware Fallback feature provides mechanisms for managing A/B firmware upgrades and fallback operations in Si91x devices. It ensures system reliability by maintaining two firmware slots and enabling fallback to a stable firmware version in case of an upgrade failure Additionally, this functionality requires a specific MBR configuration to work.
Features#
A/B Slot Management: Maintains two firmware slots (Slot A and Slot B) for active and backup firmware.
Integrity Checks: Verifies firmware integrity using CRC and magic word validation.
Fallback Mechanism: Switches to a backup firmware slot in case of failure.
OTA Support: Supports Over-The-Air (OTA) firmware upgrades with slot management.
Usage#
The following steps outline the typical usage of the Firmware Fallback feature, providing clear guidance on how and when to use each API in the firmware update process:
At OTA initiation:
Use sl_si91x_ab_upgrade_get_rps_configs to parse the incoming firmware image header. This step extracts critical metadata, such as image size and type, and is typically performed when the first chunk of OTA data arrives. This information helps determine the type of update being performed and allocate the necessary resources for the update process.Preparing the inactive slot for new firmware:
Before writing the new firmware, use sl_si91x_flash_erase to clear the inactive slot. This ensures the slot is ready to receive the new firmware image and prevents flash corruption. The inactive slot can be identified using sl_si91x_ab_get_slot_info, which retrieves the current slot configuration.Writing firmware during OTA download:
Use sl_si91x_flash_write to store the received firmware chunks in the inactive slot as they arrive from the OTA source. This function should be called for each chunk of data received during the OTA session, ensuring proper addressing and offset management. This step ensures that the new firmware is written correctly to the designated slot.Validating the downloaded firmware:
After the firmware download is complete, use sl_si91x_verify_image to validate the integrity of the downloaded firmware image. This step ensures that only properly formed and uncorrupted firmware is considered for activation.Updating slot metadata after successful validation:
Once the new firmware is verified, use sl_si91x_ab_upgrade_set_slot_info to update the slot metadata with information about the new firmware. This prepares the slot for activation and ensures the slot information accurately reflects the valid firmware version. This step is essential to mark the new firmware as ready for execution.Retrieving current slot information:
Use sl_si91x_ab_get_slot_info to determine which slot (A or B) is currently active for both M4 and NWP processors. This function also retrieves information about firmware locations and sizes in flash memory. It is typically called before performing any operation that depends on knowing the current slot configuration. This step is useful for diagnostics and ensuring the correct slot is being used.Switching slots manually or for recovery:
Use sl_si91x_toggle_slot_info only in specific scenarios, such as recovering from a failed firmware update by switching back to the previously working slot or manually switching between existing firmware versions. After calling this function, the system must be reset to load the newly activated firmware. This function should not be part of the regular update process and should only be used when both slots contain valid firmware images.Burning NWP security version:
Use sl_si91x_burn_nwp_security_version to burn the NWP security version to OTP memory. This step is critical for enforcing firmware security on the NWP (Network Wireless Processor). Burning the security version to OTP (One-Time Programmable) memory ensures that only firmware images with a security version equal to or greater than the burned value can be executed. This mechanism prevents rollback attacks by disallowing the loading of older, potentially vulnerable firmware versions. This operation is irreversible and should be performed with caution, typically after a successful firmware update or when upgrading the device's security requirements.Loading QSPI keys for inline decryption:
Use sl_si91x_fallback_load_qspi_keys to load the QSPI keys for enabling inline decryption for M4 slot applications during fallback. This function is essential when firmware images are stored in encrypted form in QSPI flash. Loading the QSPI keys allows the hardware to transparently decrypt firmware as it is read and executed, ensuring both security and performance. This step should be performed before attempting to boot or validate encrypted firmware images, and the keys must be securely provisioned and managed.Soft reset for NWP firmware:
Use sl_si91x_nwp_soft_reset_from_updater to perform a soft reset of the NWP firmware for fallback and keep the NWP firmware in boot mode. This function is typically used after updating or recovering the NWP firmware, ensuring that the NWP restarts cleanly and enters a known state. Keeping the NWP in boot mode allows for further maintenance operations, such as additional firmware updates, diagnostics, or recovery actions, before normal operation resumes. This step is important for robust fallback and recovery workflows.Default NWP firmware selection:
Use sl_si91x_select_default_nwp_fw to select the default NWP firmware image to load. This API allows you to specify which NWP (Network Wireless Processor) firmware slot (A or B) should be used as the default on the next boot. The function takes a firmware image number as input (0 for slot A, 1 for slot B) and updates the boot configuration accordingly. This is particularly useful for scenarios where you want to manually control which firmware version is active, such as after a successful OTA update, for testing a new firmware image, or for recovery purposes if the current firmware is not functioning as expected. The function returns 0 on success, a negative value if the command fails.Executing the firmware from the active slot:
Use sl_si91x_jump_to_m4_application to execute the firmware from the currently active slot. This function is primarily used by the M4 Updater to branch to the appropriate application after reading slot information. It transfers control from the updater to the main application, completing the boot process. This step ensures the system boots into the correct firmware version.
The following three APIs are required only when full encryption is enabled:
By following these steps, the Firmware Fallback feature ensures a seamless and reliable firmware update process, with mechanisms for recovery and fallback in case of failures. This design minimizes downtime and ensures the device remains operational even in the event of update issues.
Benefits#
Ensures system reliability with robust fallback mechanisms.
Simplifies OTA firmware upgrades with A/B slot management.
Eliminates the need to transfer the image from the download region to the execution region, enabling faster updates.
Provides APIs for seamless integration into application firmware.
Optimizes flash memory usage for firmware storage.
Modules#
sl_si91x_fw_fallback_request_t
sl_si91x_fw_ab_slot_management_t
Enumerations#
Enum for A/B OTA image types.
Enum for A/B chunk types(Payload / Header).
SI91x-specific A/B fallback command types.
Functions#
Retrieves A/B fallback OTA image configuration from the provided image buffer. This function checks the magic number in the image buffer to validate the firmware header. If valid, it populates the ota_image_info_t structure with the image offset and size from the firmware header.
Write data to flash memory. This function writes data to the specified flash memory address. This function will work for A/B firmware only.
Unified flash write function for OTA firmware updates. This function handles all flash write operations for OTA firmware updates using the provided configuration structure and data buffer. This function will work for A/B firmware only.
Read data from flash memory. This function reads data from the specified flash memory address. This function will work for A/B firmware only.
Updates slot information and switches active slots on OTA updates. This function updates the slot information and switches the active slots based on the provided parameters. This function will work for A/B firmware only.
Erases data from flash memory sector-wise.
Retrieves the current slot information. This function reads the current slot information from flash memory. This function will work for A/B firmware only.
Toggles the active slot information for M4 or NWP. This function retrieves the current slot information, checks which slot is active, and switches to the other slot by calling the sl_si91x_set_slot_info API.
Retrieves the M4 application address from the active firmware slot. This function reads firmware slot information from flash memory, verifies its integrity using a magic word and CRC check, and determines the application address for the currently active M4 slot. This function will work for A/B firmware only.
Jumps to the M4 application.
Checks the integrity of the firmware for Fallback. This function sends a command to check the integrity of the firmware at the specified flash memory address. It populates the request structure with the necessary parameters and sends the command to the firmware. This function will work for A/B firmware only.
Selects the default NWP firmware image to load. This function sends the appropriate command to select which firmware image (0 for slot A, 1 for slot B) should be loaded on boot.
Burns the NWP security version to OTP memory. This function reads the security version from the NWP firmware at the specified flash address and burns it into the One-Time Programmable (OTP) memory. This function will work for A/B fallback feature only and only for NWP Firmware.
Requests to load QSPI keys. This function requests to load QSPI keys for to enable the inline decryption for M4 slot firmware for fallback. This function will work for A/B firmware only.
Performs a soft reset of the NWP firmware.
Macros#
Magic number located in RPS Header.
Firmware header size in bytes.
Flash memory chunk size for erase operations.
Base address of M4 and NWP flash memory.
NWP flash base address.
Slot information flash offsets.
Backup slot offset.
Image type identifiers in RPS.
NWP RPS image type.
OTA image chunk size.
Timeout for NWP responses.
Timeout for selecting default firmware.
Magic word to verify slot information integrity.
CRC polynomial for slot information.
Memory value to check for memory match.
M4 updater OTA flag.
A/B fallback: Flash read operation failed.
A/B fallback: Flash verification failure.
A/B fallback: Backup slot read failure.
A/B fallback: CRC verification failed in backup slot.
A/B fallback: CRC mismatch detected.
A/B fallback: Magic number mismatch error.
A/B fallback: Unknown image type.
A/B fallback: Invalid slot info.
A/B fallback: Invalid slot info.
Enumeration Documentation#
sl_si91x_ab_image_type_t#
sl_si91x_ab_image_type_t
Enum for A/B OTA image types.
| Enumerator | |
|---|---|
| SL_SI91X_AB_OTA_IMAGE_TYPE_M4 | Image for M4 processor. |
| SL_SI91X_AB_OTA_IMAGE_TYPE_NWP | Image for NWP processor. |
| SL_SI91X_AB_OTA_IMAGE_TYPE_MAX | Maximum image type value. |
sl_si91x_ab_slot_t#
sl_si91x_ab_slot_t
Enum for AB slot identifiers.
| Enumerator | |
|---|---|
| SLOT_A | Primary slot (typically the active firmware slot) |
| SLOT_B | Secondary slot (used for updates or fallback) |
| SLOT_MAX | Maximum number of slots (used for validation) |
sl_si91x_chunk_type_t#
sl_si91x_chunk_type_t
Enum for A/B chunk types(Payload / Header).
| Enumerator | |
|---|---|
| SL_SI91X_DATA_PACKET | Chunk type for Data packet. |
| SL_SI91X_HEADER_PACKET | Chunk type for Header packet. |
sl_si91x_ab_fallback_cmd_t#
sl_si91x_ab_fallback_cmd_t
SI91x-specific A/B fallback command types.
| Enumerator | |
|---|---|
| SL_SI91X_AB_FALLBACK_WRITE_CMD | Write firmware data for fallback. |
| SL_SI91X_AB_FALLBACK_READ_CMD | Read firmware data for verification. |
| SL_SI91X_AB_FALLBACK_ERASE_CMD | Erase fallback firmware slot. |
| SL_SI91X_AB_FALLBACK_INTEGRITY_CHECK_CMD | Perform integrity check before fallback. |
| SL_SI91X_AB_FALLBACK_BURN_SECURITY_VERSION | Burn security version. |
| SL_SI91X_AB_FALLBACK_LOAD_QSPI_KEYS | Load QSPI keys. |
| SL_SI91X_AB_FALLBACK_SOFT_RESET | NWP Soft reset for fallback. |
| SL_SI91X_AB_FALLBACK_MAX_CMD | Maximum fallback command value (for validation) |
Function Documentation#
sl_si91x_ab_upgrade_get_rps_configs#
sl_status_t sl_si91x_ab_upgrade_get_rps_configs (const uint8_t * image_buffer, ota_image_info_t * ota_st)
Retrieves A/B fallback OTA image configuration from the provided image buffer. This function checks the magic number in the image buffer to validate the firmware header. If valid, it populates the ota_image_info_t structure with the image offset and size from the firmware header.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const uint8_t * | [in] | image_buffer | Pointer to the buffer containing the firmware image. |
| ota_image_info_t * | [out] | ota_st | Pointer to the ota_image_info_t structure to be populated. |
None
Returns
sl_status_t SL_STATUS_OK on success, or SL_STATUS_FAIL on failure. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_flash_write#
sl_status_t sl_si91x_flash_write (uint32_t address, const uint8_t * buffer, uint32_t length)
Write data to flash memory. This function writes data to the specified flash memory address. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | address | Flash memory address to write to. |
| const uint8_t * | [in] | buffer | Pointer to the data buffer. |
| uint32_t | [in] | length | Number of bytes to write (min 0 max 4096). |
None
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_fw_fallback_ota_flash_write#
sl_status_t sl_si91x_fw_fallback_ota_flash_write (const sl_si91x_fw_fallback_config_t * config, const uint8_t * data_buffer)
Unified flash write function for OTA firmware updates. This function handles all flash write operations for OTA firmware updates using the provided configuration structure and data buffer. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const sl_si91x_fw_fallback_config_t * | [in] | config | Pointer to the firmware fallback configuration structure. |
| const uint8_t * | [in] | data_buffer | Pointer to the data buffer to write. |
None
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_flash_read#
sl_status_t sl_si91x_flash_read (uint32_t address, uint8_t * buffer, uint32_t length)
Read data from flash memory. This function reads data from the specified flash memory address. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | address | Flash memory address to read from M4. |
| uint8_t * | [in] | buffer | Pointer to the buffer to store read data. |
| uint32_t | [in] | length | Number of bytes to read. |
None
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_ab_upgrade_set_slot_info#
sl_status_t sl_si91x_ab_upgrade_set_slot_info (uint32_t new_image_offset, uint32_t new_image_size, sl_si91x_ab_image_type_t image_type)
Updates slot information and switches active slots on OTA updates. This function updates the slot information and switches the active slots based on the provided parameters. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | new_image_offset | New image base address (used only during OTA update). |
| uint32_t | [in] | new_image_size | New image size (used only during OTA update). |
| sl_si91x_ab_image_type_t | [in] | image_type | Type of the image (M4 or NWP). |
None
Returns
sl_status_t SL_STATUS_OK if successful, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_flash_erase#
sl_status_t sl_si91x_flash_erase (uint32_t address, uint32_t length)
Erases data from flash memory sector-wise.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | address | Starting flash memory address to erase (must be sector-aligned). |
| uint32_t | [in] | length | Number of bytes to erase (will be rounded up to sector size). |
None
This function erases data from the specified flash memory address in sector-sized blocks. The erase operation will only work for A/B firmware slots and ensures that no partial sector erases occur.
Note
The erase operation is performed in full sectors. If the provided address or length does not align with sector boundaries, the function will round to the nearest sector boundary.
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_ab_get_slot_info#
sl_status_t sl_si91x_ab_get_slot_info (sl_si91x_fw_ab_slot_management_t * slot_info_t)
Retrieves the current slot information. This function reads the current slot information from flash memory. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_si91x_fw_ab_slot_management_t * | [out] | slot_info_t | Pointer to the sl_si91x_fw_ab_slot_management_t structure to store the slot information. |
None
Returns
sl_status_t SL_STATUS_OK if successful, error code otherwise.
sl_si91x_toggle_slot_info#
sl_status_t sl_si91x_toggle_slot_info (bool toggle_m4_image, bool toggle_nwp_image)
Toggles the active slot information for M4 or NWP. This function retrieves the current slot information, checks which slot is active, and switches to the other slot by calling the sl_si91x_set_slot_info API.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | [in] | toggle_m4_image | Set to 1 to toggle M4 slot, 0 otherwise. |
| bool | [in] | toggle_nwp_image | Set to 1 to toggle NWP slot, 0 otherwise. |
None
Returns
sl_status_t SL_STATUS_OK if successful, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_get_m4_app_addr#
sl_status_t sl_si91x_get_m4_app_addr (uint32_t * app_addr)
Retrieves the M4 application address from the active firmware slot. This function reads firmware slot information from flash memory, verifies its integrity using a magic word and CRC check, and determines the application address for the currently active M4 slot. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t * | [out] | app_addr | Pointer to store the retrieved application address. |
None
If a CRC failure is detected in the primary slot information,
the function attempts to retrieve the slot information from a backup slot. Returns
SL_STATUS_OK If the operation is successful.
SL_SI91X_AB_ERR_FLASH_READ If reading slot information from flash fails.
SL_SI91X_AB_ERR_MAGIC_NUMBER If the magic word does not match the expected value.
SL_SI91X_AB_ERR_CRC_MISMATCH If the CRC verification fails.
SL_STATUS_INVALID_PARAMETER If the active slot is invalid. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_jump_to_m4_application#
void sl_si91x_jump_to_m4_application (uint32_t app_addr)
Jumps to the M4 application.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | app_addr | Address of the application to jump to. |
This function disables interrupts, fetches the stack pointer and reset handler from the application's vector table, sets the VTOR to point to the new application vector table, and branches to the reset handler. This function will work for A/B firmware only.
sl_si91x_verify_image#
sl_status_t sl_si91x_verify_image (uint32_t address)
Checks the integrity of the firmware for Fallback. This function sends a command to check the integrity of the firmware at the specified flash memory address. It populates the request structure with the necessary parameters and sends the command to the firmware. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | address | Flash memory address to check integrity. |
None
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_select_default_nwp_fw#
int16_t sl_si91x_select_default_nwp_fw (const uint8_t fw_image_number)
Selects the default NWP firmware image to load. This function sends the appropriate command to select which firmware image (0 for slot A, 1 for slot B) should be loaded on boot.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const uint8_t | [in] | fw_image_number | Firmware image number to select (0 for slot A, 1 for slot B) |
None
Returns
int16_t - Error code
0 : SUCCESS
< 0 : Command issue failed
-14 : Valid Firmware not present
-15 : Invalid Option/Command not supported For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_burn_nwp_security_version#
sl_status_t sl_si91x_burn_nwp_security_version (uint32_t flash_address)
Burns the NWP security version to OTP memory. This function reads the security version from the NWP firmware at the specified flash address and burns it into the One-Time Programmable (OTP) memory. This function will work for A/B fallback feature only and only for NWP Firmware.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | flash_address | Flash address of the NWP firmware to extract security version. |
None
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_fallback_load_qspi_keys#
sl_status_t sl_si91x_fallback_load_qspi_keys (uint32_t image_offset)
Requests to load QSPI keys. This function requests to load QSPI keys for to enable the inline decryption for M4 slot firmware for fallback. This function will work for A/B firmware only.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | image_offset | Offset of the image to load the QSPI keys to enable inline decryption for M4 slot firmware for fallback. |
None
Returns
sl_status_t SL_STATUS_OK on success, error code otherwise. For more information on status codes, refer to SL STATUS DOCUMENTATION.
sl_si91x_nwp_soft_reset_from_updater#
void sl_si91x_nwp_soft_reset_from_updater (const uint32_t m4_slot_image_offset)
Performs a soft reset of the NWP firmware.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const uint32_t | [in] | m4_slot_image_offset | Offset of the M4 slot image for fallback |
This function sends a soft reset command to the NWP firmware for fallback and keep the NWP firmware in the boot mode. This function will work for A/B firmware only.