doc: iterable_sections: add an API example

Expand the iterable sections documentation by adding a usage example.

Signed-off-by: Fabio Baltieri <[email protected]>

Author: fabiobaltieri

doc/reference/iterable_sections/index.rst

@@ -7,4 +7,62 @@ This page contains the reference documentation for the iterable sections APIs,
 which can be used for defining iterable areas of equally-sized data structures,
 that can be iterated on using `STRUCT_SECTION_FOREACH()`.
 
+Usage
+*****
+
+Iterable section elements are typically used by defining the data structure and
+associated initializer in a common header file, so that they can be
+instantiated anywhere in the code base.
+
+.. code-block:: c
+
+    struct my_data {
+             int a, b;
+    };
+
+    #define DEFINE_DATA(name, _a, _b) \
+             STRUCT_SECTION_ITERABLE(my_data, name) = { \
+                     .a = _a, \
+                     .b = _b, \
+             }
+
+    ...
+
+    DEFINE_DATA(d1, 1, 2);
+    DEFINE_DATA(d2, 3, 4);
+    DEFINE_DATA(d3, 5, 6);
+
+Then the linker has to be setup to place the place the structure in a
+contiguous segment using one of the linker macros such as
+`ITERABLE_SECTION_RAM()` or `ITERABLE_SECTION_ROM()`. Custom linker snippets
+are normally declared using one of the ``zephyr_linker_sources()`` CMake
+functions, using the appropriate section identifier, ``DATA_SECTIONS`` for RAM
+structures and ``SECTIONS`` for ROM ones.
+
+.. code-block:: cmake
+
+   # CMakeLists.txt
+   zephyr_linker_sources(DATA_SECTIONS iterables.ld)
+
+.. code-block:: c
+
+   # iterables.ld
+   ITERABLE_SECTION_RAM(my_data, 4)
+
+The data can then be accessed using `STRUCT_SECTION_FOREACH()`.
+
+.. code-block:: c
+
+   STRUCT_SECTION_FOREACH(my_data, data) {
+           printk("%p: a: %d, b: %d\n", data, data->a, data->b);
+   }
+
+.. note::
+   The linker is going to place the entries sorted by name, so the example
+   above would visit ``d1``, ``d2`` and ``d3`` in that order, regardless of how
+   they were defined in the code.
+
+API Reference
+*************
+
 .. doxygengroup:: iterable_section_apis