155 lines
4.6 KiB
ReStructuredText
155 lines
4.6 KiB
ReStructuredText
.. _settings:
|
|
|
|
Settings subsystem with non-volatile storage
|
|
############################################
|
|
|
|
The settings subsystem gives modules a way to store persistent
|
|
per-device configuration and runtime state.
|
|
|
|
Settings items are stored as key-value pair strings. By convention,
|
|
the keys can be organized by the package and subtree defining the key,
|
|
for example the key ``id/serial`` would define the ``serial`` configuration
|
|
element for the package ``id``.
|
|
|
|
Convenience routines are provided for converting a key value to
|
|
and from a string type.
|
|
|
|
Handlers
|
|
********
|
|
|
|
Settings handlers for subtree implement a set of handler functions.
|
|
These are registered using a call to ``settings_register()``.
|
|
|
|
**h_get**
|
|
This gets called when asking for a settings element value
|
|
by its name using ``settings_get_value()``.
|
|
|
|
**h_set**
|
|
This gets called when the value is being set using ``settings_set_value()``,
|
|
and also when setting is loaded from persisted storage with
|
|
``settings_load()``.
|
|
|
|
**h_commit**
|
|
This gets called after the settings have been loaded in full.
|
|
Sometimes you don't want an individual setting value to take
|
|
effect right away, for example if there are multiple settings
|
|
which are interdependent.
|
|
|
|
**h_export**
|
|
This gets called to write all current settings. This happens
|
|
when ``settings_save()`` tries to save the settings or transfer to any
|
|
user-implemented back-end.
|
|
|
|
Persistence
|
|
***********
|
|
|
|
Backend storage for the settings can be either FCB, a file in the filesystem,
|
|
or both.
|
|
|
|
You can declare multiple sources for settings; settings from
|
|
all of these are restored when ``settings_load()`` is called.
|
|
|
|
There can be only one target for writing settings; this is where
|
|
data is stored when you call ``settings_save()``, or ``settings_save_one()``.
|
|
|
|
FCB read target is registered using ``settings_fcb_src()``, and write target
|
|
using ``settings_fcb_dst()``. As a side-effect, ``settings_fcb_src()``
|
|
initializes the FCB area, so it must be called before calling
|
|
``settings_fcb_dst()``. File read target is registered using
|
|
``settings_file_src()``, and write target by using ``settings_file_dst()``.
|
|
|
|
Example: Device Configuration
|
|
*****************************
|
|
|
|
This is a simple example, where the settings handler only implements ``h_set``
|
|
and ``h_export``. ``h_set`` is called when the value is restored from storage
|
|
(or when set initially), and ``h_export`` is used to write the value to
|
|
storage thanks to ``storage_func()``. The user can also implement some other
|
|
export functionality, for example, writing to the shell console).
|
|
|
|
.. code-block:: c
|
|
|
|
static int8 foo_val;
|
|
|
|
struct settings_handler my_conf = {
|
|
.h_name = "foo",
|
|
.h_set = foo_settings_set,
|
|
.h_export = foo_settings_export
|
|
}
|
|
|
|
static int foo_settings_set(int argc, char **argv, char *val)
|
|
{
|
|
if (argc == 1) {
|
|
if (!strcmp(argv[0], "bar")) {
|
|
return SETTINGS_VALUE_SET(val, SETTINGS_INT8, foo_val);
|
|
}
|
|
}
|
|
|
|
return -ENOENT;
|
|
}
|
|
|
|
static int foo_settings_export(void (*storage_func)(char *name, char *val),
|
|
enum settings_export_tgt tgt)
|
|
{
|
|
char buf[4];
|
|
|
|
settings_str_from_value(SETTINGS_INT8, &foo_val, buf, sizeof(buf));
|
|
storage_func("foo/bar", buf)
|
|
|
|
return 0;
|
|
}
|
|
|
|
Example: Persist Runtime State
|
|
******************************
|
|
|
|
This is a simple example showing how to persist runtime state. In this example,
|
|
only ``h_set`` is defined, which is used when restoring value from
|
|
persisted storage.
|
|
|
|
In this example, the ``foo_callout`` function increments ``foo_val``, and then
|
|
persists the latest number. When the system restarts, the application calls
|
|
``settings_load()`` while initializing, and ``foo_val`` will continue counting
|
|
up from where it was before restart.
|
|
|
|
.. code-block:: c
|
|
|
|
static int8 foo_val;
|
|
|
|
struct settings_handler my_conf = {
|
|
.h_name = "foo",
|
|
.h_set = foo_settings_set
|
|
}
|
|
|
|
static int foo_settings_set(int argc, char **argv, char *val)
|
|
{
|
|
if (argc == 1) {
|
|
if (!strcmp(argv[0], "bar")) {
|
|
return SETTINGS_VALUE_SET(val, SETTINGS_INT8, foo_val);
|
|
}
|
|
}
|
|
|
|
return -ENOENT;
|
|
}
|
|
|
|
static void foo_callout(struct os_event *ev)
|
|
{
|
|
struct os_callout *c = (struct os_callout *)ev;
|
|
char buf[4];
|
|
|
|
foo_val++;
|
|
settings_str_from_value(SETTINGS_INT8, &foo_val, buf, sizeof(buf));
|
|
settings_save_one("foo/bar", bar);
|
|
|
|
k_sleep(1000);
|
|
sys_reboot(SYS_REBOOT_COLD);
|
|
}
|
|
|
|
API
|
|
***
|
|
|
|
The Settings subsystem APIs are provided by ``settings.h``:
|
|
|
|
.. doxygengroup:: settings
|
|
:project: Zephyr
|
|
|