michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: settings: properly use C domain for cross referencing API

Browse source 
Use :c:func: to properly reference C domain functions
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2024-08-30 17:54:25 +02:00 • committed by Anas Nashif
commit cfeaf0c731
1 changed files with 24 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

48
doc/services/settings/index.rst
View file

@ -30,15 +30,15 @@ Handlers
******** ********
Settings handlers for subtree implement a set of handler functions. Settings handlers for subtree implement a set of handler functions.
These are registered using a call to ``settings_register()``. These are registered using a call to :c:func:`settings_register()`.
**h_get** **h_get**
This gets called when asking for a settings element value by its name using This gets called when asking for a settings element value by its name using
``settings_runtime_get()`` from the runtime backend. :c:func:`settings_runtime_get()` from the runtime backend.
**h_set** **h_set**
This gets called when the value is loaded from persisted storage with This gets called when the value is loaded from persisted storage with
``settings_load()``, or when using ``settings_runtime_set()`` from the :c:func:`settings_load()`, or when using :c:func:`settings_runtime_set()` from the
runtime backend. runtime backend.
**h_commit** **h_commit**
@ -49,7 +49,7 @@ These are registered using a call to ``settings_register()``.
**h_export** **h_export**
This gets called to write all current settings. This happens This gets called to write all current settings. This happens
when ``settings_save()`` tries to save the settings or transfer to any when :c:func:`settings_save()` tries to save the settings or transfer to any
user-implemented back-end. user-implemented back-end.
Backends Backends
@ -57,26 +57,26 @@ Backends
Backends are meant to load and save data to/from setting handlers, and Backends are meant to load and save data to/from setting handlers, and
implement a set of handler functions. These are registered using a call to implement a set of handler functions. These are registered using a call to
``settings_src_register()`` for backends that can load data, and/or :c:func:`settings_src_register()` for backends that can load data, and/or
``settings_dst_register()`` for backends that can save data. The current :c:func:`settings_dst_register()` for backends that can save data. The current
implementation allows for multiple source backends but only a single destination implementation allows for multiple source backends but only a single destination
backend. backend.
**csi_load** **csi_load**
This gets called when loading values from persistent storage using This gets called when loading values from persistent storage using
``settings_load()``. :c:func:`settings_load()`.
**csi_save** **csi_save**
This gets called when saving a single setting to persistent storage using This gets called when saving a single setting to persistent storage using
``settings_save_one()``. :c:func:`settings_save_one()`.
**csi_save_start** **csi_save_start**
This gets called when starting a save of all current settings using This gets called when starting a save of all current settings using
``settings_save()``. :c:func:`settings_save()`.
**csi_save_end** **csi_save_end**
This gets called after having saved of all current settings using This gets called after having saved of all current settings using
``settings_save()``. :c:func:`settings_save()`.
Zephyr Storage Backends Zephyr Storage Backends
*********************** ***********************
@ -87,19 +87,19 @@ Zephyr has three storage backends: a Flash Circular Buffer
(:kconfig:option:`CONFIG_SETTINGS_NVS`). (:kconfig:option:`CONFIG_SETTINGS_NVS`).
You can declare multiple sources for settings; settings from You can declare multiple sources for settings; settings from
all of these are restored when ``settings_load()`` is called. all of these are restored when :c:func:`settings_load()` is called.
There can be only one target for writing settings; this is where There can be only one target for writing settings; this is where
data is stored when you call ``settings_save()``, or ``settings_save_one()``. data is stored when you call :c:func:`settings_save()`, or :c:func:`settings_save_one()`.
FCB read target is registered using ``settings_fcb_src()``, and write target FCB read target is registered using :c:func:`settings_fcb_src()`, and write target
using ``settings_fcb_dst()``. As a side-effect, ``settings_fcb_src()`` using :c:func:`settings_fcb_dst()`. As a side-effect, :c:func:`settings_fcb_src()`
initializes the FCB area, so it must be called before calling initializes the FCB area, so it must be called before calling
``settings_fcb_dst()``. File read target is registered using :c:func:`settings_fcb_dst()`. File read target is registered using
``settings_file_src()``, and write target by using ``settings_file_dst()``. :c:func:`settings_file_src()`, and write target by using :c:func:`settings_file_dst()`.
Non-volatile storage read target is registered using Non-volatile storage read target is registered using
``settings_nvs_src()``, and write target by using :c:func:`settings_nvs_src()`, and write target by using
``settings_nvs_dst()``. :c:func:`settings_nvs_dst()`.
Storage Location Storage Location
**************** ****************
@ -115,7 +115,7 @@ option ``CONFIG_SETTINGS_FILE_PATH``.
Loading data from persisted storage Loading data from persisted storage
*********************************** ***********************************
A call to ``settings_load()`` uses an ``h_set`` implementation A call to :c:func:`settings_load()` uses an ``h_set`` implementation
to load settings data from storage to volatile memory. to load settings data from storage to volatile memory.
After all data is loaded, the ``h_commit`` handler is issued, After all data is loaded, the ``h_commit`` handler is issued,
signalling the application that the settings were successfully signalling the application that the settings were successfully
@ -130,12 +130,12 @@ call the callback with only the newest entity.
Storing data to persistent storage Storing data to persistent storage
********************************** **********************************
A call to ``settings_save_one()`` uses a backend implementation to store A call to :c:func:`settings_save_one()` uses a backend implementation to store
settings data to the storage medium. A call to ``settings_save()`` uses an settings data to the storage medium. A call to :c:func:`settings_save()` uses an
``h_export`` implementation to store different data in one operation using ``h_export`` implementation to store different data in one operation using
``settings_save_one()``. :c:func:`settings_save_one()`.
A key need to be covered by a ``h_export`` only if it is supposed to be stored A key need to be covered by a ``h_export`` only if it is supposed to be stored
by ``settings_save()`` call. by :c:func:`settings_save()` call.
For both FCB and file back-end only storage requests with data which For both FCB and file back-end only storage requests with data which
changes most actual key's value are stored, therefore there is no need to check changes most actual key's value are stored, therefore there is no need to check
@ -219,7 +219,7 @@ persisted storage.
In this example, the ``main`` function increments ``foo_val``, and then In this example, the ``main`` function increments ``foo_val``, and then
persists the latest number. When the system restarts, the application calls persists the latest number. When the system restarts, the application calls
``settings_load()`` while initializing, and ``foo_val`` will continue counting :c:func:`settings_load()` while initializing, and ``foo_val`` will continue counting
up from where it was before restart. up from where it was before restart.
.. code-block:: c .. code-block:: c