BLIB Client Library

This BLIB library provides functions to control the boot process and update the firmware on supported Satlab products.

Client Interface

This file contains functions to configure the boot process.

The system uses two boot slots: slot 0 and slot 1. On system boot, a small bootloader application selects which of the two slots to boot based on a non-volatile state stored in FRAM.

Each boot slot has a set of properties:

status: either STABLE, TESTING, or DISABLED.
attempts: remaining boot attempts.
priority: higher priority number indicate higher preference to boot.

The current bootloader status can be queried using sl_blib_client_get_status or shown with the boot status shell command.

A firmware slot is bootable if status is not DISABLED and attempts > 0. The highest priority bootable slot is selected for boot.

If no bootable slot is found, e.g. because all slots have attempts = 0, attempts for all slots are reset to the default value (3) and another search for a bootable slot is performed. If a bootable slot is still not found, slot 0 is selected for boot.

Before booting the selected slot, the bootloader decrements remaining attempts for the slot. It is up to the booted firmware image to reset remaining attempts to indicate a successful boot. For slots where status is STABLE, the firmware will do so automatically after 120 seconds uptime upon successful boot. For slots where status is TESTING, the attempts must be reset using sl_blib_client_boot_success or alternatively using the boot success shell command.

Each firmware slot can be flashed from the other using the sl_blib_client_flash function or the boot flash shell command. During the firmware update, the slot being updated is automatically set to DISABLED to prevent it from being booted. If the update is completed successfully, the slot status is set to TESTING. The user can then change the preferred slot to the updated slot using sl_blib_client_set_preferred or the boot prefer shell command.

When successfully booted, the user can decide to keep the slot in TESTING and manually reset attempts as a safeguard, or mark the slot as STABLE using sl_blib_client_set_slot_status or the boot slot status shell command to enable automatic reset of remaining attempts.

Typedefs

typedef int (*sl_blib_client_progress_t)(uint8_t step, uint32_t completed, uint32_t total, void *prog_arg)

Progress callback function prototype.

A function matching this prototype can be passed to sl_blib_client_flash to be called periodically during the flash process.

Param step:: Currently executing SL_BLIB_STEP
Param completed:: Number of completed blocks in this step
Param total:: Total number of blocks in this step. 0 if the step has no blocks.
Param prog_arg:: Callback argument passed to sl_blib_client_flash.
Return:: 0 on success, negative error to abort.

Functions

static inline const char *sl_blib_progress_step_to_string(uint8_t step)

Convert progress step to string.

Convert a numerical progress step to a string representation.

Parameters:: step – The numerical progress step.
Returns:: pointer to constants string representation of step or “Unknown step” if the step is unknown.

int sl_blib_client_flash(uint8_t node, uint32_t timeout, uint8_t slot, const char *filename, sl_blib_client_progress_t prog_cb, void *prog_arg)

Flash image file to firmware slot.

This function flashes a firmware file to a firmware slot.

Flashing and verifying a firmware image typically takes 15-30 seconds, so ensure that the timeout is set sufficiently high.

It is not possible to flash the currently booted firmware slot.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.
slot – Firmware slot to flash (0 or 1).
filename – Filename of the remote file to flash.
prog_cb – Optional progress callback function.
prog_arg – Optional progress callback argument.

Returns:

0 on success, negative error code otherwise.

int sl_blib_client_get_status(uint8_t node, uint32_t timeout, struct sl_blib_client_status *status)

Get bootloader status.

This function reads the current bootloader status.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.
status – Status is returned in this structure.

Returns:

0 on success, negative error code otherwise.

int sl_blib_client_boot_success(uint8_t node, uint32_t timeout)

Mark boot successful.

This function marks the current boot successful and resets the boot attempts for the booted slot to the default value. For testing slots, this function needs to be called before attempts reaches 0, to keep the slot bootable.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.

Returns:

0 on success, negative error code otherwise.

int sl_blib_client_set_preferred(uint8_t node, uint32_t timeout, uint8_t slot)

Set the preferred boot slot.

This function is used to set the preferred slot to boot. It modifies the priorities of all boot slots to ensure the selected slot has the highest. If also reset the attempts of the preferred slot to the default value.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.
slot – Firmware slot to prefer (0 or 1).

Returns:

0 on success, negative error code otherwise.

int sl_blib_client_set_slot_status(uint8_t node, uint32_t timeout, uint8_t slot, uint8_t status)

Set slot status.

This function is used to set the status of a slot.

To prevent deadlock, it is not possible to set the status of the booted slot to DISABLED. Likewise, only the booted slot can be set to STABLE.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.
slot – Firmware slot to change status of (0 or 1).
status – New status for slot.

Returns:

0 on success, negative error code otherwise.

int sl_blib_client_set_slot_priority(uint8_t node, uint32_t timeout, uint8_t slot, uint8_t priority)

Set slot priority.

This function is used to set the priority of a slot. Bootable slots with higher priority are preferred.

It is usually not necessary to call this function directly. Use sl_blib_client_set_preferred instead.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.
slot – Firmware slot to change status of (0 or 1).
priority – New priority for slot.

Returns:

0 on success, negative error code otherwise.

int sl_blib_client_set_slot_attempts(uint8_t node, uint32_t timeout, uint8_t slot, uint8_t attempts)

Set slot attempts.

This function is used to set the remaining boot attempts of a slot.

It is usually not necessary to call this function directly. Use sl_blib_client_set_preferred and sl_blib_client_boot_success instead.

Parameters:

node – CSP address of the node.
timeout – Timeout of the command in milliseconds.
slot – Firmware slot to change status of (0 or 1).
attempts – New attempts for slot.

Returns:

0 on success, negative error code otherwise.

struct sl_blib_client_status

Public Members

uint8_t slot_booted: Booted slot.

uint8_t slot_preferred: Preferred slot.

uint8_t slot0_status: Slot 0 status.

uint8_t slot0_attempts: Slot 0 priority.

uint8_t slot0_priority: Slot 0 remaining boot attempts.

uint8_t slot0_valid: Slot 0 contents state.

uint8_t slot1_status: Slot 1 status.

uint8_t slot1_attempts: Slot 1 priority.

uint8_t slot1_priority: Slot 1 remaining boot attempts.

uint8_t slot1_valid: Slot 1 contents state.