Experimental: FStorage

FStorage is a module for storing and erasing data in persistent flash storage. The module accepts requests to store and erase data and queues them up for asynchronous handling. The application is notified of the operation results through callbacks to registered event handlers.

The advantage of FStorage, when compared to Persistent Storage Manager, is that FStorage automatically splits up large writes and erases into smaller operations, thus enabling the SoftDevice to more easily handle these requests in between radio operations.

Experimental: Flash Data Storage internally uses FStorage. It can be used directly as well.

Registering usage

The FStorage module can be used by different applications or different parts of an application at the same time. Each user of flash storage must register with the module to request a number of pages of storage. The module then grants access to these registered pages only; it is not possible to access the flash using addresses outside of the registered pages. All registered users use their own callback handler and receive updates for the pages that they are registered to use.

Usage registration is done at compile time through the use of Experimental: Section variables. You must provide a function pointer to use for event callbacks, the number of pages to reserve, and the order with which they will be positioned in flash. These parameters are specified at compile time and cannot be changed during run time.

The following example code shows the signature of the event handler:

static void fs_callback(uint8_t op_code,
 uint32_t result,
 uint32_t const * p_data,
 fs_length_t length)
{
 // Insert handling code here
}

The order of a page specifies the position that page will have in flash, the page with the lowest order will be assigned to the lowest memory address. Order zero is reserved for the Experimental: Peer Manager. A page order must be unique.

To register usage in FStorage, you must use the FS_SECTION_VARS_ADD macro that is defined in fstorage.h. Place code similar to the following example code in the application:

#include fstorage.h
FS_SECTION_VARS_ADD( fs_config_t fs_config ) = { .cb = &fs_callback, .num_pages = 2, .page_order = 1 };

Initializing

The following code example shows how to initialize FStorage:

ret_code_t retval = fs_init();
if (retval != NRF_SUCCESS)
{
 // fs_init() failed, propagate the error.
 return retval;
}

Storing and erasing data

FStorage queues requests for flash operations and interfaces with the SoftDevice to get timeslots for handling these operations in a timely manner. Large store requests are split up to better negotiate with the SoftDevice to get the wanted timeslots. Requests to erase multiple pages are split up into individual page erases. If the SoftDevice is busy with time critical radio requests, FStorage will retry the queued operations. When the operation completes, the registered user is notified by an event callback.

The following code example shows how to erase all pages that have been registered:

ret_code_t retval;
retval = fs_erase(&fs_config, fs_config.p_start_addr, fs_config.num_pages * FS_PAGE_SIZE_WORDS);
return retval;

Note that the registered section variable must be provided as input. Success or failure of the operation is indicated through event callbacks.