6.4. settings — Persistent application settings

Settings are stored in a non-volatile memory (NVM). In other words, settings are perserved after a board reset or power cycle.

Application settings are defined in an ini-file that is used to generate the c source code. A setting has a type, a size, an address and a default value, all defined in the ini-file.

Supported types are:

  • int32_t A 32 bits signed integer.
  • string An ASCII string.
  • blob A chunk of data.

The size is the number of bytes of the value. For the standard integer types the size must be the value returned by sizeof(). For strings it is the length of the string, including null termination.

The address for each setting is defined by the user, starting at address 0 and increasing from there.

The build system variable SETTINGS_INI contains the path to the ini-file used by the build system.

6.4.1. Debug file system commands

Four debug file system commands are available, all located in the directory oam/settings/.

Command Description
list Print a list of the current settings.
reset [<name>] Reset one or all settings to their default
values (the values defined in the ini-file values).
read <name> Read the value of setting <name>.
write <name> <value> Write <value> to setting <name>.

Example output from the shell:

$ oam/settings/list
NAME                  TYPE      SIZE  VALUE
version               int32_t      4  1
value_1               int32_t      4  24567
value_2               blob_t       4  cafebabe
value_3               string_t    16  foobar
OK
$ oam/settings/read value_1
24567
OK
$ oam/settings/write value_1 -5
OK
$ oam/settings/read value_1
-5
OK
$ oam/settings/reset value_1
OK
$ oam/settings/read value_1
24567
OK
$ oam/settings/reset
OK
$ oam/settings/list
NAME                  TYPE      SIZE  VALUE
version               int32_t      4  1
value_1               int32_t      4  24567
value_2               blob_t       4  cafebabe
value_3               string_t    16  foobar
OK

6.4.2. Example

In this example the ini-file has one setting defined, foo. The type is int32_t, the address is 0x00, the size is 4 and the default value is -4.

[values]
foo = -4

[types]
foo = int32_t

[addresses]
foo = 0x00

[sizes]
foo = 4

The settings can be read and written with the functions settings_read() and settings_write(). Give the generated defines SETTING_FOO_ADDR and SETTING_FOO_SIZE as arguments to those functions.

int my_read_write_foo()
{
    int32_t foo;

    /* Read the foo setting. */
    if (settings_read(&foo,
                      SETTING_FOO_ADDR,
                      SETTING_FOO_SIZE) != 0) {
        return (-1);
    }

    foo -= 1;

    /* Write the foo setting. */
    if (settings_write(SETTING_FOO_ADDR,
                       &foo,
                       SETTING_FOO_SIZE) != 0) {
        return (-1);
    }

    return (0);
}

Source code: src/oam/settings.h, src/oam/settings.c

Test code: tst/oam/settings/main.c

Test coverage: src/oam/settings.c


Defines

SETTINGS_AREA_CRC_OFFSET

Enums

enum setting_type_t

Settings types. Each setting must have be one of these types.

Values:

setting_type_int32_t = 0
setting_type_string_t
setting_type_blob_t

Functions

int settings_module_init(void)

Initialize the settings module. This function must be called before calling any other function in this module.

The module will only be initialized once even if this function is called multiple times.

Return
zero(0) or negative error code.

ssize_t settings_read(void *dst_p, size_t src, size_t size)

Read the value of given setting by address.

Return
Number of words read or negative error code.
Parameters
  • dst_p: The read value.
  • src: Setting source address.
  • size: Number of words to read.

ssize_t settings_write(size_t dst, const void *src_p, size_t size)

Write given value to given setting by address.

Return
Number of words written or negative error code.
Parameters
  • dst: Destination setting address.
  • src_p: Value to write.
  • size: Number of bytes to write.

int settings_reset(size_t address, size_t size)

Reset given setting to its default value.

Return
zero(0) or negative error code.
Parameters
  • address: Setting address.
  • size: Number of bytes to reset.

ssize_t settings_read_by_name(const char *name_p, void *dst_p, size_t size)

Read the value of given setting by name.

Return
Number of words read or negative error code.
Parameters
  • name_p: Setting name.
  • dst_p: The read value.
  • size: Size of the destination buffer.

ssize_t settings_write_by_name(const char *name_p, const void *src_p, size_t size)

Write given value to given setting by name.

Return
Number of words read or negative error code.
Parameters
  • name_p: Setting name.
  • src_p: Value to write.
  • size: Number of bytes to write.

int settings_reset_by_name(const char *name_p, size_t size)

Reset given setting to its default value.

Return
zero(0) or negative error code.
Parameters
  • name_p: Setting name.
  • size: Number of bytes to reset.

int settings_reset_all(void)

Reset all settings to their default values.

Return
zero(0) or negative error code.

struct setting_t

Public Members

FAR const char* setting_t::name_p
setting_type_t type
uint32_t address
size_t size