6.3. 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.3.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.3.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
Defines
-
SETTINGS_AREA_CRC_OFFSET
¶
Enums
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
¶
-