1.. _iterable_sections_api:
2
3Iterable Sections
4#################
5
6This page contains the reference documentation for the iterable sections APIs,
7which can be used for defining iterable areas of equally-sized data structures,
8that can be iterated on using :c:macro:`STRUCT_SECTION_FOREACH`.
9
10Usage
11*****
12
13Iterable section elements are typically used by defining the data structure and
14associated initializer in a common header file, so that they can be
15instantiated anywhere in the code base.
16
17.. code-block:: c
18
19    struct my_data {
20             int a, b;
21    };
22
23    #define DEFINE_DATA(name, _a, _b) \
24             STRUCT_SECTION_ITERABLE(my_data, name) = { \
25                     .a = _a, \
26                     .b = _b, \
27             }
28
29    ...
30
31    DEFINE_DATA(d1, 1, 2);
32    DEFINE_DATA(d2, 3, 4);
33    DEFINE_DATA(d3, 5, 6);
34
35Then the linker has to be setup to place the place the structure in a
36contiguous segment using one of the linker macros such as
37:c:macro:`ITERABLE_SECTION_RAM` or :c:macro:`ITERABLE_SECTION_ROM`. Custom
38linker snippets are normally declared using one of the
39``zephyr_linker_sources()`` CMake functions, using the appropriate section
40identifier, ``DATA_SECTIONS`` for RAM structures and ``SECTIONS`` for ROM ones.
41
42.. code-block:: cmake
43
44   # CMakeLists.txt
45   zephyr_linker_sources(DATA_SECTIONS iterables.ld)
46
47.. code-block:: c
48
49   # iterables.ld
50   ITERABLE_SECTION_RAM(my_data, 4)
51
52The data can then be accessed using :c:macro:`STRUCT_SECTION_FOREACH`.
53
54.. code-block:: c
55
56   STRUCT_SECTION_FOREACH(my_data, data) {
57           printk("%p: a: %d, b: %d\n", data, data->a, data->b);
58   }
59
60.. note::
61   The linker is going to place the entries sorted by name, so the example
62   above would visit ``d1``, ``d2`` and ``d3`` in that order, regardless of how
63   they were defined in the code.
64
65API Reference
66*************
67
68.. doxygengroup:: iterable_section_apis
69