.. _iterable_sections_api:

Iterable Sections
#################

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