BLOB Storage#

sl_btmesh_blob_storage_status_e#

sl_btmesh_blob_storage_status_e

sl_btmesh_blob_storage_delete_state_e#

sl_btmesh_blob_storage_delete_state_e

sl_btmesh_blob_storage_status_t#

typedef enum sl_btmesh_blob_storage_status_e sl_btmesh_blob_storage_status_t

sl_btmesh_blob_storage_delete_state_t#

typedef enum sl_btmesh_blob_storage_delete_state_e sl_btmesh_blob_storage_delete_state_t

sl_btmesh_blob_storage_init#

void sl_btmesh_blob_storage_init (void )

Initializes the storage wrapper

sl_btmesh_blob_storage_deinit#

void sl_btmesh_blob_storage_deinit (void )

Deinitializes the storage wrapper

sl_btmesh_blob_storage_read#

sl_status_t sl_btmesh_blob_storage_read (sl_bt_uuid_64_t const * blob_id, uint32_t offset, uint32_t * len, void * buffer)

Reads data from the identified BLOB into a buffer

Returns

• Status code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: In case BLOB isn't found

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_write_start#

sl_status_t sl_btmesh_blob_storage_write_start (sl_bt_uuid_64_t const * blob_id, uint32_t size)

Starts writing procedure

Sets internal state variables to correspond to writing a BLOB. Returns

• Status code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_ALREADY_EXISTS: In case BLOB ID already exists in storage

• SL_STATUS_WOULD_OVERFLOW: In case BLOB is too big to fit

• SL_STATUS_NO_MORE_RESOURCE: In case no slot is available

• SL_STATUS_BUSY: In case BLOB Storage is processing an async. request

sl_btmesh_blob_storage_write#

sl_status_t sl_btmesh_blob_storage_write (uint32_t offset, uint32_t len, void * data)

Writes data into storage.

• sl_btmesh_blob_storage_write_start must be called first.

Returns

• Result of write operation

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_FLASH_WRITE_INHIBITED: In case of non-word aligned offset

• SL_STATUS_FLASH_PROGRAM_FAILED: In case storage programming failed

sl_btmesh_blob_storage_get_cache#

void sl_btmesh_blob_storage_get_cache (sl_btmesh_blob_storage_slot_metadata_cache_t const ** cache, uint32_t * len)

Retrieves a pointer to the cache

sl_btmesh_blob_storage_any_blob_corrupted#

bool sl_btmesh_blob_storage_any_blob_corrupted (void )

Returns if any BLOB is corrupted

Returns

Return values

• true: If at least one BLOB is corrupted

• false: If no BLOB is corrupted

sl_btmesh_blob_storage_verify#

sl_status_t sl_btmesh_blob_storage_verify (void )

Verifies the BLOB to be considered consistent

Returns

• Verification result

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_INVALID_STATE: In case less data has been written than indicated with

• SL_STATUS_FAIL: In case of internal API error

• SL_STATUS_FLASH_PROGRAM_FAILED: In case writing validity info into storage has failed

sl_btmesh_blob_storage_invalidate#

sl_status_t sl_btmesh_blob_storage_invalidate (sl_bt_uuid_64_t const * blob_id)

Invalidates BLOB footer

Returns

• Result code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: In case BLOB identifier is not found

• SL_STATUS_FAIL: In case of internal API error

• SL_STATUS_FLASH_PROGRAM_FAILED: In case storage writing has failed

• SL_STATUS_BUSY: In case BLOB Storage is processing an async. request

sl_btmesh_blob_storage_invalidate_by_owner#

sl_status_t sl_btmesh_blob_storage_invalidate_by_owner (uint16_t owner_id)

Invalidates all valid BLOB footer which belongs to a specific owner

See Also

• sl_btmesh_blob_storage_set_managed

Returns

• Result code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_FAIL: In case of internal API error

• SL_STATUS_FLASH_PROGRAM_FAILED: In case storage writing has failed

• SL_STATUS_BUSY: In case BLOB Storage is processing an async. request

sl_btmesh_blob_storage_invalidate_all#

sl_status_t sl_btmesh_blob_storage_invalidate_all (void )

Invalidates all valid BLOB footer

Returns

• Result code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_FAIL: In case of internal API error

• SL_STATUS_FLASH_PROGRAM_FAILED: In case storage writing has failed

• SL_STATUS_BUSY: In case BLOB Storage is processing an async. request

sl_btmesh_blob_storage_delete#

sl_status_t sl_btmesh_blob_storage_delete (sl_bt_uuid_64_t const * blob_id)

Deletes a BLOB from storage

Returns

• Result of erase

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: In case no BLOB has been identified in storage

• SL_STATUS_FLASH_ERASE_FAILED: In case erase has failed

sl_btmesh_blob_storage_delete_start#

sl_status_t sl_btmesh_blob_storage_delete_start (sl_bt_uuid_64_t const * blob_id)

Start asynchronous delete of a BLOB

See Also

• sl_btmesh_blob_storage_get_erase_error_code

Returns

• Request status

Return values

• SL_BTMESH_OK: Request successful

• SL_BTMESH_BUSY: Erase handler busy

sl_btmesh_blob_storage_delete_managed_by_owner#

sl_status_t sl_btmesh_blob_storage_delete_managed_by_owner (uint16_t owner_id)

Deletes all BLOB from storage which belongs to a specific owner

See Also

• sl_btmesh_blob_storage_set_managed

Returns

• Result of erase

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: No managed slot was found which belongs to the owner

• SL_STATUS_FLASH_ERASE_FAILED: In case erase has failed

sl_btmesh_blob_storage_delete_managed_by_owner_start#

sl_status_t sl_btmesh_blob_storage_delete_managed_by_owner_start (uint16_t owner_id)

Start asynchronous delete of BLOBs that are unmanaged

See Also

• sl_btmesh_blob_storage_get_erase_error_code

• sl_btmesh_blob_storage_set_managed

Returns

• Request status

Return values

• SL_BTMESH_OK: Request successful

• SL_BTMESH_BUSY: Erase handler busy

sl_btmesh_blob_storage_delete_all#

sl_status_t sl_btmesh_blob_storage_delete_all (void )

Deletes all BLOBs from storage

Returns

• Result of erase

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_FLASH_ERASE_FAILED: In case erase has failed

sl_btmesh_blob_storage_delete_all_start#

sl_status_t sl_btmesh_blob_storage_delete_all_start (void )

Start asynchronous delete of all BLOBs

See Also

• sl_btmesh_blob_storage_get_erase_error_code

Returns

• Request status

Return values

• SL_BTMESH_OK: Request successful

• SL_BTMESH_BUSY: Erase handler busy

sl_btmesh_blob_storage_delete_invalid_slots#

sl_status_t sl_btmesh_blob_storage_delete_invalid_slots (void )

Clear slots with invalid data

Returns

• Result of erase

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: No invalid slot was found

• SL_STATUS_FLASH_ERASE_FAILED: In case erase has failed

sl_btmesh_blob_storage_delete_invalid_slots_start#

sl_status_t sl_btmesh_blob_storage_delete_invalid_slots_start (void )

Start asynchronous delete of invalid BLOBs

See Also

• sl_btmesh_blob_storage_get_erase_error_code

Returns

• Request status

Return values

• SL_BTMESH_OK: Request successful

• SL_BTMESH_BUSY: Erase handler busy

sl_btmesh_blob_storage_delete_unmanaged_slots#

sl_status_t sl_btmesh_blob_storage_delete_unmanaged_slots (void )

Clear slots that are unmanaged

See Also

• sl_btmesh_blob_storage_set_managed

Returns

• Result of erase

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: No unmanaged slot was found

• SL_STATUS_FLASH_ERASE_FAILED: In case erase has failed

sl_btmesh_blob_storage_delete_unmanaged_slots_start#

sl_status_t sl_btmesh_blob_storage_delete_unmanaged_slots_start (void )

Start asynchronous delete of BLOBs that are unmanaged

See Also

• sl_btmesh_blob_storage_get_erase_error_code

• sl_btmesh_blob_storage_set_managed

Returns

• Request status

Return values

• SL_BTMESH_OK: Request successful

• SL_BTMESH_BUSY: Erase handler busy

sl_btmesh_blob_storage_set_delete_separation_time#

sl_status_t sl_btmesh_blob_storage_set_delete_separation_time (uint16_t separation_time_ms)

Set asynchronous delete separation time

Asynchronous delete separation time is measured in milliseconds between two asynchronous delete steps. The BLOB storage async delete is performed in multiple steps and each delete step blocks the code execution. If delete steps are executed too often then it could starve other timing sensitive SW components so delete separation time feature can be used to prevent this scenario.

Returns

• Request status

Return values

• SL_STATUS_OK: In case of success

sl_btmesh_blob_storage_is_present#

bool sl_btmesh_blob_storage_is_present (sl_bt_uuid_64_t const * blob_id)

Checks whether BLOB identified is present in storage

Returns

• Boolean value

Return values

• true: BLOB is present

• false: BLOB is not present

sl_btmesh_blob_storage_get_blob_size#

sl_status_t sl_btmesh_blob_storage_get_blob_size (sl_bt_uuid_64_t const * blob_id, uint32_t * blob_size)

Queries the BLOB size

Returns

• Status code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: In case no BLOB has been identified

sl_btmesh_blob_storage_calc_app_footer_size#

uint32_t sl_btmesh_blob_storage_calc_app_footer_size (uint16_t footer_data_length)

Calculates the size of application specific footer on BLOB storage medium.

Note

• BLOB storage stores some additional metadata (id, length) with the footer data and it takes into consideration the alignment requirements of the underlying medium.

Returns

• Size of application specific footer on BLOB storage medium.

sl_btmesh_blob_storage_write_app_footer#

sl_status_t sl_btmesh_blob_storage_write_app_footer (sl_bt_uuid_64_t const * blob_id, void const * footer, uint16_t app_id, uint16_t length)

Writes application specific footer into storage belonging to identified the BLOB and application

Returns

• Result of app footer write

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_INVALID_PARAMETER: If app_id or length is invalid

• SL_STATUS_FLASH_PROGRAM_FAILED: In case write failed

• SL_STATUS_FULL: If there is no free space for app footer

• SL_STATUS_NOT_FOUND: If blob_id doesn't identify any footer

• SL_STATUS_INVALID_SIGNATURE: If any footer is corrupted during search for empty space to write new app footer

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_get_app_footer_length#

sl_status_t sl_btmesh_blob_storage_get_app_footer_length (sl_bt_uuid_64_t const * blob_id, uint16_t app_id, uint16_t * length)

Queries footer information length assigned to a given BLOB, belonging to an application identifier.

Returns

• Status code

Return values

• SL_STATUS_OK: In case of successful query

• SL_STATUS_NOT_FOUND: If app_id and blob_id don't identify a footer

• SL_STATUS_INVALID_SIGNATURE: In case of corrupted app footer metadata

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_get_app_footer#

sl_status_t sl_btmesh_blob_storage_get_app_footer (sl_bt_uuid_64_t const * blob_id, uint16_t app_id, void * buffer, uint16_t * length)

Extracts footer information assigned to a given BLOB, belonging to an application identifier.

Returns

• Status code

Return values

• SL_STATUS_OK: In case of successful reading

• SL_STATUS_NOT_FOUND: If app_id and blob_id don't identify a footer

• SL_STATUS_INVALID_SIGNATURE: In case of corrupted app footer metadata

• SL_STATUS_INVALID_PARAMETER: If buffer is too short

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_set_managed#

sl_status_t sl_btmesh_blob_storage_set_managed (sl_bt_uuid_64_t const * blob_id, uint16_t owner_id)

Set BLOB to be managed, meaning it won't be deleted.

Each managed BLOB is managed by a specific owner which is stored with BLOB. Unmanaged BLOBs will be deleted when out of available space.

Returns

• Status code

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_FLASH_PROGRAM_FAILED: In case write failed

• SL_STATUS_FULL: If there is no free space to store owner_id

• SL_STATUS_NOT_FOUND: If blob_id doesn't identify any footer

• SL_STATUS_INVALID_SIGNATURE: If any footer is corrupted during search for empty space to write new app footer

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_is_managed#

bool sl_btmesh_blob_storage_is_managed (sl_bt_uuid_64_t const * blob_id)

Check if BLOB is managed.

See Also

• sl_btmesh_blob_storage_set_managed

Returns

• Boolean value

Return values

• true: BLOB is managed

• false: BLOB isn't managed or BLOB does not exist

sl_btmesh_blob_storage_is_managed_by_owner#

bool sl_btmesh_blob_storage_is_managed_by_owner (sl_bt_uuid_64_t const * blob_id, uint16_t owner_id)

Check if BLOB is managed by a specific owner.

See Also

• sl_btmesh_blob_storage_set_managed

Returns

• Boolean value

Return values

• true: BLOB belongs to the specified owner

• false: BLOB belongs to another owner or BLOB is not managed or BLOB does not exist

sl_btmesh_blob_storage_get_managed_flag_size#

uint32_t sl_btmesh_blob_storage_get_managed_flag_size (void )

Return the size of managed flag on BLOB storage medium.

BLOB storage needs to distinguish managed and unmanaged BLOBs so it marks managed BLOBs as such which requires some space on the medium.

Returns

• Size of managed flag on BLOB storage medium

sl_btmesh_blob_storage_get_blob_id_by_owner#

sl_status_t sl_btmesh_blob_storage_get_blob_id_by_owner (uint16_t owner_id, uint32_t occurrence_idx, sl_bt_uuid_64_t * blob_id)

Searches BLOBs managed by a specific owner and provides the BLOB ID of the requested occurrence.

The search order for managed BLOBs of an owner is not specified but it is guaranteed that the order does not change unless new BLOB is added or an existing BLOB of the same owner is removed (delete, invalidate) from the BLOB storage.

When a managed BLOB belonging to an owner is removed from BLOB storage then occurrence_idx of BLOBs with same owner is decremented if the occurrence_idx of the BLOB was greater than the occurrence_idx of the removed BLOB otherwise the occurrence_idx does not change. In other words the BLOBs are shifted to lower indexes.

If a new managed BLOB is added by an owner to the BLOB storage then the search order of BLOBs with the same owner may change arbitrarily because it is not guaranteed which occurrence_idx the added BLOB is assigned to.

See Also

• sl_btmesh_blob_storage_set_managed

Returns

• Result of managed BLOB ID get operation

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: If no BLOBs are found with owner_id or the occurrence_idx is greater or equal to the number of BLOBs managed by owner

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_get_blob_id_by_footer#

sl_status_t sl_btmesh_blob_storage_get_blob_id_by_footer (uint16_t app_id, const void * expected_footer, uint16_t length, sl_bt_uuid_64_t * blob_id)

Searches for a specific app_id and data in the footer of each valid BLOB and returns the BLOB ID of the first match

Returns

• Result of footer based BLOB ID query (propagates other internal errors)

Return values

• SL_STATUS_OK: In case of success

• SL_STATUS_NOT_FOUND: If app_id is not found or the data is different

• SL_STATUS_FAIL: In case of internal API error

sl_btmesh_blob_storage_get_total_space#

uint32_t sl_btmesh_blob_storage_get_total_space (void )

Queries total space for BLOB data storage in bytes (used + empty)

Returns

• Total space in bytes

sl_btmesh_blob_storage_get_remaining_space#

uint32_t sl_btmesh_blob_storage_get_remaining_space (bool include_unmanaged_blobs)

Queries remaining empty bytes in the BLOB storage

Returns

• Remaining empty bytes

sl_btmesh_blob_storage_get_max_blob_size#

uint32_t sl_btmesh_blob_storage_get_max_blob_size (void )

Queries maximum BLOB size which can be stored if the whole BLOB storage is empty

Note

• This might not be available even if one BLOB is stored

Returns

• Maximum BLOB size

sl_btmesh_blob_storage_get_max_blob_size_free#

uint32_t sl_btmesh_blob_storage_get_max_blob_size_free (bool include_unmanaged_blobs)

Queries maximum BLOB size which can be stored in the free space of BLOB storage

Returns

• Maximum supported BLOB size in free part of the BLOB storage

sl_btmesh_blob_storage_get_max_blob_count#

uint32_t sl_btmesh_blob_storage_get_max_blob_count (void )

Queries maximum number of BLOBs which can be stored

Returns

• Maximum number of BLOBs

sl_btmesh_blob_storage_get_alignment#

uint8_t sl_btmesh_blob_storage_get_alignment (void )

Queries the BLOB storage alignment

Writes to the BLOB storage must have an offset that is aligned to this value. Apart from the last write of a writing procedure, the length of the data must be a multiple of this value. The last write can be of any length.

Returns

• The BLOB storage alignment

sl_btmesh_blob_storage_get_erase_error_code#

sl_btmesh_blob_storage_delete_state_t sl_btmesh_blob_storage_get_erase_error_code (void )

Queries the error code/state of the asynchronous erase

Returns

• State of asynchronous erase

Return values

• SL_BTMESH_BLOB_STORAGE_DELETE_INACTIVE: If erase is inactive

• SL_BTMESH_BLOB_STORAGE_DELETE_BUSY: If erase is ongoing

• SL_BTMESH_BLOB_STORAGE_DELETE_FAILED: If erase has failed

• SL_BTMESH_BLOB_STORAGE_DELETE_SUCCESS: If erase is successful

sl_btmesh_blob_storage_delete_step_handle#

void sl_btmesh_blob_storage_delete_step_handle (void )

Handles the asynchronous erase state machine

sl_btmesh_blob_storage_is_ok_to_sleep#

bool sl_btmesh_blob_storage_is_ok_to_sleep ()

Check if BLOB Storage allows the system to sleep

Returns

• If it is ok to sleep

Return values

• true: The system is allowed to sleep

• false: The system shall be kept awake

Asynchronous erase requires the device to stay awake to finish.

sl_btmesh_blob_storage_calculate_checksum#

uint32_t sl_btmesh_blob_storage_calculate_checksum (const uint8_t * data, uint16_t length, uint32_t initial_value)

Called when app footer is written to BLOB storage to calculate the checksum over app footer data

This is a callback which can be implemented in the application. Note

• If no implementation is provided in the application, then the default weak implementation calculates Berger code.

Returns

• Checksum calculated from app footer data