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.

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.

# CMakeLists.txt
zephyr_linker_sources(DATA_SECTIONS iterables.ld)

# iterables.ld
ITERABLE_SECTION_RAM(my_data, 4)

The data can then be accessed using STRUCT_SECTION_FOREACH.

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

group iterable_section_apis

Iterable Sections APIs.

Defines

ITERABLE_SECTION_ROM(struct_type, subalign)

Define a read-only iterable section output.

Define an output section which will set up an iterable area of equally-sized data structures. For use with STRUCT_SECTION_ITERABLE(). Input sections will be sorted by name, per ld’s SORT_BY_NAME.

This macro should be used for read-only data.

Note that this keeps the symbols in the image even though they are not being directly referenced. Use this when symbols are indirectly referenced by iterating through the section.

ITERABLE_SECTION_ROM_NUMERIC(struct_type, subalign)

Define a read-only iterable section output, sorted numerically.

This version of ITERABLE_SECTION_ROM() sorts the entries numerically, that is, SECNAME_10 will come after SECNAME_2. _ separator is required, and up to 2 numeric digits are handled (0-99).

See also

ITERABLE_SECTION_ROM()

ITERABLE_SECTION_ROM_GC_ALLOWED(struct_type, subalign)

Define a garbage collectable read-only iterable section output.

Define an output section which will set up an iterable area of equally-sized data structures. For use with STRUCT_SECTION_ITERABLE(). Input sections will be sorted by name, per ld’s SORT_BY_NAME.

This macro should be used for read-only data.

Note that the symbols within the section can be garbage collected.

ITERABLE_SECTION_RAM(struct_type, subalign)

Define a read-write iterable section output.

Define an output section which will set up an iterable area of equally-sized data structures. For use with STRUCT_SECTION_ITERABLE(). Input sections will be sorted by name, per ld’s SORT_BY_NAME.

This macro should be used for read-write data that is modified at runtime.

Note that this keeps the symbols in the image even though they are not being directly referenced. Use this when symbols are indirectly referenced by iterating through the section.

ITERABLE_SECTION_RAM_NUMERIC(struct_type, subalign)

Define a read-write iterable section output, sorted numerically.

This version of ITERABLE_SECTION_RAM() sorts the entries numerically, that is, SECNAME10 will come after SECNAME2. Up to 2 numeric digits are handled (0-99).

See also

ITERABLE_SECTION_RAM()

ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign)

Define a garbage collectable read-write iterable section output.

Define an output section which will set up an iterable area of equally-sized data structures. For use with STRUCT_SECTION_ITERABLE(). Input sections will be sorted by name, per ld’s SORT_BY_NAME.

This macro should be used for read-write data that is modified at runtime.

Note that the symbols within the section can be garbage collected.

TYPE_SECTION_ITERABLE(type, varname, secname, section_postfix)

Defines a new element for an iterable section for a generic type.

Convenience helper combining __in_section() and Z_DECL_ALIGN(). The section name will be ‘.[SECNAME].static.[SECTION_POSTFIX]’

In the linker script, create output sections for these using ITERABLE_SECTION_ROM() or ITERABLE_SECTION_RAM().

Note

In order to store the element in ROM, a const specifier has to be added to the declaration: const TYPE_SECTION_ITERABLE(…);

Parameters:

type – [in] data type of variable
varname – [in] name of variable to place in section
secname – [in] type name of iterable section.
section_postfix – [in] postfix to use in section name

TYPE_SECTION_START(secname)

iterable section start symbol for a generic type

will return ‘_[OUT_TYPE]_list_start’.

Parameters:

secname – [in] type name of iterable section. For ‘struct foobar’ this would be TYPE_SECTION_START(foobar)

TYPE_SECTION_END(secname)

iterable section end symbol for a generic type

will return ‘_<SECNAME>_list_end’.

Parameters:

secname – [in] type name of iterable section. For ‘struct foobar’ this would be TYPE_SECTION_START(foobar)

TYPE_SECTION_START_EXTERN(type, secname)

iterable section extern for start symbol for a generic type

Helper macro to give extern for start of iterable section. The macro typically will be called TYPE_SECTION_START_EXTERN(struct foobar, foobar). This allows the macro to hand different types as well as cases where the type and section name may differ.

Parameters:

type – [in] data type of section
secname – [in] name of output section

TYPE_SECTION_END_EXTERN(type, secname)

iterable section extern for end symbol for a generic type

Helper macro to give extern for end of iterable section. The macro typically will be called TYPE_SECTION_END_EXTERN(struct foobar, foobar). This allows the macro to hand different types as well as cases where the type and section name may differ.

Parameters:

type – [in] data type of section
secname – [in] name of output section

TYPE_SECTION_FOREACH(type, secname, iterator)

Iterate over a specified iterable section for a generic type.

Iterator for structure instances gathered by TYPE_SECTION_ITERABLE(). The linker must provide a _<SECNAME>_list_start symbol and a _<SECNAME>_list_end symbol to mark the start and the end of the list of struct objects to iterate over. This is normally done using ITERABLE_SECTION_ROM() or ITERABLE_SECTION_RAM() in the linker script.

TYPE_SECTION_GET(type, secname, i, dst)

Get element from section for a generic type.

Note

There is no protection against reading beyond the section.

Parameters:

type – [in] type of element
secname – [in] name of output section
i – [in] Index.
dst – [out] Pointer to location where pointer to element is written.

TYPE_SECTION_COUNT(type, secname, dst)

Count elements in a section for a generic type.

Parameters:

type – [in] type of element
secname – [in] name of output section
dst – [out] Pointer to location where result is written.

STRUCT_SECTION_START(struct_type)

iterable section start symbol for a struct type

Parameters:

struct_type – [in] data type of section

STRUCT_SECTION_START_EXTERN(struct_type)

iterable section extern for start symbol for a struct

Helper macro to give extern for start of iterable section.

Parameters:

struct_type – [in] data type of section

STRUCT_SECTION_END(struct_type)

iterable section end symbol for a struct type

Parameters:

struct_type – [in] data type of section

STRUCT_SECTION_END_EXTERN(struct_type)

iterable section extern for end symbol for a struct

Helper macro to give extern for end of iterable section.

Parameters:

struct_type – [in] data type of section

STRUCT_SECTION_ITERABLE_ALTERNATE(secname, struct_type, varname)

Defines a new element of alternate data type for an iterable section.

Special variant of STRUCT_SECTION_ITERABLE(), for placing alternate data types within the iterable section of a specific data type. The data type sizes and semantics must be equivalent!

STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(secname, struct_type, varname, size)

Defines an array of elements of alternate data type for an iterable section.

See also

STRUCT_SECTION_ITERABLE_ALTERNATE

STRUCT_SECTION_ITERABLE(struct_type, varname)

Defines a new element for an iterable section.

Convenience helper combining __in_section() and Z_DECL_ALIGN(). The section name is the struct type prepended with an underscore. The subsection is “static” and the subsubsection is the variable name.

In the linker script, create output sections for these using ITERABLE_SECTION_ROM() or ITERABLE_SECTION_RAM().

Note

In order to store the element in ROM, a const specifier has to be added to the declaration: const STRUCT_SECTION_ITERABLE(…);

STRUCT_SECTION_ITERABLE_ARRAY(struct_type, varname, size)

Defines an array of elements for an iterable section.

See also

STRUCT_SECTION_ITERABLE

STRUCT_SECTION_ITERABLE_NAMED(struct_type, name, varname)

Defines a new element for an iterable section with a custom name.

The name can be used to customize how iterable section entries are sorted.

See also

STRUCT_SECTION_ITERABLE()

STRUCT_SECTION_ITERABLE_NAMED_ALTERNATE(struct_type, secname, name, varname)

Defines a new element for an iterable section with a custom name, placed in a custom section.

The name can be used to customize how iterable section entries are sorted.

See also

STRUCT_SECTION_ITERABLE_NAMED()

STRUCT_SECTION_FOREACH_ALTERNATE(secname, struct_type, iterator)

Iterate over a specified iterable section (alternate).

Iterator for structure instances gathered by STRUCT_SECTION_ITERABLE(). The linker must provide a _<SECNAME>_list_start symbol and a _<SECNAME>_list_end symbol to mark the start and the end of the list of struct objects to iterate over. This is normally done using ITERABLE_SECTION_ROM() or ITERABLE_SECTION_RAM() in the linker script.

STRUCT_SECTION_FOREACH(struct_type, iterator)

Iterate over a specified iterable section.

Iterator for structure instances gathered by STRUCT_SECTION_ITERABLE(). The linker must provide a _<struct_type>_list_start symbol and a _<struct_type>_list_end symbol to mark the start and the end of the list of struct objects to iterate over. This is normally done using ITERABLE_SECTION_ROM() or ITERABLE_SECTION_RAM() in the linker script.

STRUCT_SECTION_GET(struct_type, i, dst)

Get element from section.

Note

There is no protection against reading beyond the section.

Parameters:

struct_type – [in] Struct type.
i – [in] Index.
dst – [out] Pointer to location where pointer to element is written.

STRUCT_SECTION_COUNT(struct_type, dst)

Count elements in a section.

Parameters:

struct_type – [in] Struct type
dst – [out] Pointer to location where result is written.