6.2. 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:

  • int8_t An 8 bits signed integer.
  • int16_t A 16 bits signed integer.
  • int32_t A 32 bits signed integer.
  • string An ASCII string.

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. Set this variable to the path of yours application ini-file and run make settings-generate to generate four files; settings.h, settings.c, settings.little-endian.bin and settings.big-endian.bin.

Also add this to the Makefile: SRC += settings.c and include settings.h in the source files that accesses the settings.

6.2.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 Overwrite the current settings values with 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               int8_t      1  1
value_1               int16_t     2  24567
value_2               int32_t     4  -57
value_3               string     16  foobar
$ oam/settings/read value_1
24567
$ oam/settings/write value_1 -5
$ oam/settings/read value_1
-5
$ oam/settings/reset
$ oam/settings/list
NAME                  TYPE     SIZE  VALUE
version               int8_t      1  1
value_1               int16_t     2  24567
value_2               int32_t     4  -57
value_3               string     16  foobar

6.2.2. Example

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

[types]
foo = int8_t

[addresses]
foo = 0x00

[sizes]
foo = 1

[values]
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()
{
    int8_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


Version
7.0.0

Defines

SETTINGS_AREA_CRC_OFFSET

Enums

enum setting_type_t

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

Values:

setting_type_int8_t = 0
setting_type_int16_t
setting_type_int32_t
setting_type_string_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.

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(void)

Overwrite all settings with 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