Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Iterable Sections APIs

Iterable Sections APIs. More...

Macros

#define ITERABLE_SECTION_ROM(struct_type, subalign)
 Define a read-only iterable section output.
 
#define ITERABLE_SECTION_ROM_NUMERIC(struct_type, subalign)
 Define a read-only iterable section output, sorted numerically.
 
#define ITERABLE_SECTION_ROM_GC_ALLOWED(struct_type, subalign)
 Define a garbage collectable read-only iterable section output.
 
#define ITERABLE_SECTION_RAM(struct_type, subalign)
 Define a read-write iterable section output.
 
#define ITERABLE_SECTION_RAM_NUMERIC(struct_type, subalign)
 Define a read-write iterable section output, sorted numerically.
 
#define ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign)
 Define a garbage collectable read-write iterable section output.
 
#define TYPE_SECTION_ITERABLE(type, varname, secname, section_postfix)
 Defines a new element for an iterable section for a generic type.
 
#define TYPE_SECTION_START(secname)   _CONCAT(_##secname, _list_start)
 iterable section start symbol for a generic type
 
#define TYPE_SECTION_END(secname)   _CONCAT(_##secname, _list_end)
 iterable section end symbol for a generic type
 
#define TYPE_SECTION_START_EXTERN(type, secname)    extern type TYPE_SECTION_START(secname)[]
 iterable section extern for start symbol for a generic type
 
#define TYPE_SECTION_END_EXTERN(type, secname)    extern type TYPE_SECTION_END(secname)[]
 iterable section extern for end symbol for a generic type
 
#define TYPE_SECTION_FOREACH(type, secname, iterator)
 Iterate over a specified iterable section for a generic type.
 
#define TYPE_SECTION_GET(type, secname, i, dst)
 Get element from section for a generic type.
 
#define TYPE_SECTION_COUNT(type, secname, dst)
 Count elements in a section for a generic type.
 
#define STRUCT_SECTION_START(struct_type)    TYPE_SECTION_START(struct_type)
 iterable section start symbol for a struct type
 
#define STRUCT_SECTION_START_EXTERN(struct_type)    TYPE_SECTION_START_EXTERN(struct struct_type, struct_type)
 iterable section extern for start symbol for a struct
 
#define STRUCT_SECTION_END(struct_type)    TYPE_SECTION_END(struct_type)
 iterable section end symbol for a struct type
 
#define STRUCT_SECTION_END_EXTERN(struct_type)    TYPE_SECTION_END_EXTERN(struct struct_type, struct_type)
 iterable section extern for end symbol for a struct
 
#define STRUCT_SECTION_ITERABLE_ALTERNATE(secname, struct_type, varname)    TYPE_SECTION_ITERABLE(struct struct_type, varname, secname, varname)
 Defines a new element of alternate data type for an iterable section.
 
#define STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(secname, struct_type, varname, size)
 Defines an array of elements of alternate data type for an iterable section.
 
#define STRUCT_SECTION_ITERABLE(struct_type, varname)    STRUCT_SECTION_ITERABLE_ALTERNATE(struct_type, struct_type, varname)
 Defines a new element for an iterable section.
 
#define STRUCT_SECTION_ITERABLE_ARRAY(struct_type, varname, size)
 Defines an array of elements for an iterable section.
 
#define STRUCT_SECTION_ITERABLE_NAMED(struct_type, name, varname)    TYPE_SECTION_ITERABLE(struct struct_type, varname, struct_type, name)
 Defines a new element for an iterable section with a custom name.
 
#define STRUCT_SECTION_ITERABLE_NAMED_ALTERNATE(struct_type, secname, name, varname)    TYPE_SECTION_ITERABLE(struct struct_type, varname, secname, name)
 Defines a new element for an iterable section with a custom name, placed in a custom section.
 
#define STRUCT_SECTION_FOREACH_ALTERNATE(secname, struct_type, iterator)    TYPE_SECTION_FOREACH(struct struct_type, secname, iterator)
 Iterate over a specified iterable section (alternate).
 
#define STRUCT_SECTION_FOREACH(struct_type, iterator)    STRUCT_SECTION_FOREACH_ALTERNATE(struct_type, struct_type, iterator)
 Iterate over a specified iterable section.
 
#define STRUCT_SECTION_GET(struct_type, i, dst)    TYPE_SECTION_GET(struct struct_type, struct_type, i, dst)
 Get element from section.
 
#define STRUCT_SECTION_COUNT(struct_type, dst)    TYPE_SECTION_COUNT(struct struct_type, struct_type, dst);
 Count elements in a section.
 

Detailed Description

Iterable Sections APIs.

Macro Definition Documentation

◆ ITERABLE_SECTION_RAM

#define ITERABLE_SECTION_RAM (   struct_type,
  subalign 
)

#include <zephyr/linker/iterable_sections.h>

Value:
SECTION_DATA_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
{ \
Z_LINK_ITERABLE(struct_type); \
} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)
#define SECTION_DATA_PROLOGUE(name, options, align)
Same as for SECTION_PROLOGUE(), except that this one must be used for data sections which on XIP plat...
Definition: linker-tool-gcc.h:205
#define GROUP_DATA_LINK_IN(vregion, lregion)
Route memory for read-write sections that are loaded.
Definition: linker-tool-gcc.h:139
#define SUBALIGN(x)
Definition: linker-tool-mwdt.h:22

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_GC_ALLOWED

#define ITERABLE_SECTION_RAM_GC_ALLOWED (   struct_type,
  subalign 
)

#include <zephyr/linker/iterable_sections.h>

Value:
SECTION_DATA_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
{ \
Z_LINK_ITERABLE_GC_ALLOWED(struct_type); \
} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)

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.

◆ ITERABLE_SECTION_RAM_NUMERIC

#define ITERABLE_SECTION_RAM_NUMERIC (   struct_type,
  subalign 
)

#include <zephyr/linker/iterable_sections.h>

Value:
SECTION_PROLOGUE(struct_type##_area, EMPTY, SUBALIGN(subalign)) \
{ \
Z_LINK_ITERABLE_NUMERIC(struct_type); \
} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)
#define EMPTY
Macro with an empty expansion.
Definition: util_macro.h:335
#define SECTION_PROLOGUE(name, options, align)
The SECTION_PROLOGUE() macro is used to define the beginning of a section.
Definition: linker-tool-gcc.h:180

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_ROM

#define ITERABLE_SECTION_ROM (   struct_type,
  subalign 
)

#include <zephyr/linker/iterable_sections.h>

Value:
SECTION_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
{ \
Z_LINK_ITERABLE(struct_type); \
} GROUP_ROM_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)
#define GROUP_ROM_LINK_IN(vregion, lregion)
Route memory for a read-only section.
Definition: linker-tool-gcc.h:119

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_GC_ALLOWED

#define ITERABLE_SECTION_ROM_GC_ALLOWED (   struct_type,
  subalign 
)

#include <zephyr/linker/iterable_sections.h>

Value:
SECTION_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
{ \
Z_LINK_ITERABLE_GC_ALLOWED(struct_type); \
} GROUP_LINK_IN(ROMABLE_REGION)
#define GROUP_LINK_IN(where)
Route memory to a specified memory area.
Definition: linker-tool-gcc.h:93

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_ROM_NUMERIC

#define ITERABLE_SECTION_ROM_NUMERIC (   struct_type,
  subalign 
)

#include <zephyr/linker/iterable_sections.h>

Value:
SECTION_PROLOGUE(struct_type##_area, EMPTY, SUBALIGN(subalign)) \
{ \
Z_LINK_ITERABLE_NUMERIC(struct_type); \
} GROUP_ROM_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)

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()

◆ STRUCT_SECTION_COUNT

#define STRUCT_SECTION_COUNT (   struct_type,
  dst 
)     TYPE_SECTION_COUNT(struct struct_type, struct_type, dst);

#include <zephyr/sys/iterable_sections.h>

Count elements in a section.

Parameters
[in]struct_typeStruct type
[out]dstPointer to location where result is written.

◆ STRUCT_SECTION_END

#define STRUCT_SECTION_END (   struct_type)     TYPE_SECTION_END(struct_type)

#include <zephyr/sys/iterable_sections.h>

iterable section end symbol for a struct type

Parameters
[in]struct_typedata type of section

◆ STRUCT_SECTION_END_EXTERN

#define STRUCT_SECTION_END_EXTERN (   struct_type)     TYPE_SECTION_END_EXTERN(struct struct_type, struct_type)

#include <zephyr/sys/iterable_sections.h>

iterable section extern for end symbol for a struct

Helper macro to give extern for end of iterable section.

Parameters
[in]struct_typedata type of section

◆ STRUCT_SECTION_FOREACH

#define STRUCT_SECTION_FOREACH (   struct_type,
  iterator 
)     STRUCT_SECTION_FOREACH_ALTERNATE(struct_type, struct_type, iterator)

#include <zephyr/sys/iterable_sections.h>

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_FOREACH_ALTERNATE

#define STRUCT_SECTION_FOREACH_ALTERNATE (   secname,
  struct_type,
  iterator 
)     TYPE_SECTION_FOREACH(struct struct_type, secname, iterator)

#include <zephyr/sys/iterable_sections.h>

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_GET

#define STRUCT_SECTION_GET (   struct_type,
  i,
  dst 
)     TYPE_SECTION_GET(struct struct_type, struct_type, i, dst)

#include <zephyr/sys/iterable_sections.h>

Get element from section.

Note
There is no protection against reading beyond the section.
Parameters
[in]struct_typeStruct type.
[in]iIndex.
[out]dstPointer to location where pointer to element is written.

◆ STRUCT_SECTION_ITERABLE

#define STRUCT_SECTION_ITERABLE (   struct_type,
  varname 
)     STRUCT_SECTION_ITERABLE_ALTERNATE(struct_type, struct_type, varname)

#include <zephyr/sys/iterable_sections.h>

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_ALTERNATE

#define STRUCT_SECTION_ITERABLE_ALTERNATE (   secname,
  struct_type,
  varname 
)     TYPE_SECTION_ITERABLE(struct struct_type, varname, secname, varname)

#include <zephyr/sys/iterable_sections.h>

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

#define STRUCT_SECTION_ITERABLE_ARRAY (   struct_type,
  varname,
  size 
)

#include <zephyr/sys/iterable_sections.h>

Value:
STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(struct_type, struct_type, \
varname, size)
#define STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(secname, struct_type, varname, size)
Defines an array of elements of alternate data type for an iterable section.
Definition: iterable_sections.h:197

Defines an array of elements for an iterable section.

See also
STRUCT_SECTION_ITERABLE

◆ STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE

#define STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE (   secname,
  struct_type,
  varname,
  size 
)

#include <zephyr/sys/iterable_sections.h>

Value:
TYPE_SECTION_ITERABLE(struct struct_type, varname[size], secname, \
varname)
#define TYPE_SECTION_ITERABLE(type, varname, secname, section_postfix)
Defines a new element for an iterable section for a generic type.
Definition: iterable_sections.h:42

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

See also
STRUCT_SECTION_ITERABLE_ALTERNATE

◆ STRUCT_SECTION_ITERABLE_NAMED

#define STRUCT_SECTION_ITERABLE_NAMED (   struct_type,
  name,
  varname 
)     TYPE_SECTION_ITERABLE(struct struct_type, varname, struct_type, name)

#include <zephyr/sys/iterable_sections.h>

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

#define STRUCT_SECTION_ITERABLE_NAMED_ALTERNATE (   struct_type,
  secname,
  name,
  varname 
)     TYPE_SECTION_ITERABLE(struct struct_type, varname, secname, name)

#include <zephyr/sys/iterable_sections.h>

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_START

#define STRUCT_SECTION_START (   struct_type)     TYPE_SECTION_START(struct_type)

#include <zephyr/sys/iterable_sections.h>

iterable section start symbol for a struct type

Parameters
[in]struct_typedata type of section

◆ STRUCT_SECTION_START_EXTERN

#define STRUCT_SECTION_START_EXTERN (   struct_type)     TYPE_SECTION_START_EXTERN(struct struct_type, struct_type)

#include <zephyr/sys/iterable_sections.h>

iterable section extern for start symbol for a struct

Helper macro to give extern for start of iterable section.

Parameters
[in]struct_typedata type of section

◆ TYPE_SECTION_COUNT

#define TYPE_SECTION_COUNT (   type,
  secname,
  dst 
)

#include <zephyr/sys/iterable_sections.h>

Value:
do { \
TYPE_SECTION_START_EXTERN(type, secname); \
TYPE_SECTION_END_EXTERN(type, secname); \
*(dst) = ((uintptr_t)TYPE_SECTION_END(secname) - \
(uintptr_t)TYPE_SECTION_START(secname)) / sizeof(type); \
} while (0)
#define TYPE_SECTION_END(secname)
iterable section end symbol for a generic type
Definition: iterable_sections.h:65
#define TYPE_SECTION_START(secname)
iterable section start symbol for a generic type
Definition: iterable_sections.h:55
__UINTPTR_TYPE__ uintptr_t
Definition: stdint.h:105

Count elements in a section for a generic type.

Parameters
[in]typetype of element
[in]secnamename of output section
[out]dstPointer to location where result is written.

◆ TYPE_SECTION_END

#define TYPE_SECTION_END (   secname)    _CONCAT(_##secname, _list_end)

#include <zephyr/sys/iterable_sections.h>

iterable section end symbol for a generic type

will return '_<SECNAME>_list_end'.

Parameters
[in]secnametype name of iterable section. For 'struct foobar' this would be TYPE_SECTION_START(foobar)

◆ TYPE_SECTION_END_EXTERN

#define TYPE_SECTION_END_EXTERN (   type,
  secname 
)     extern type TYPE_SECTION_END(secname)[]

#include <zephyr/sys/iterable_sections.h>

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
[in]typedata type of section
[in]secnamename of output section

◆ TYPE_SECTION_FOREACH

#define TYPE_SECTION_FOREACH (   type,
  secname,
  iterator 
)

#include <zephyr/sys/iterable_sections.h>

Value:
TYPE_SECTION_START_EXTERN(type, secname); \
TYPE_SECTION_END_EXTERN(type, secname); \
for (type * iterator = TYPE_SECTION_START(secname); ({ \
__ASSERT(iterator <= TYPE_SECTION_END(secname),\
"unexpected list end location"); \
iterator < TYPE_SECTION_END(secname); \
}); \
iterator++)
#define TYPE_SECTION_START_EXTERN(type, secname)
iterable section extern for start symbol for a generic type
Definition: iterable_sections.h:78

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

#define TYPE_SECTION_GET (   type,
  secname,
  i,
  dst 
)

#include <zephyr/sys/iterable_sections.h>

Value:
do { \
TYPE_SECTION_START_EXTERN(type, secname); \
*(dst) = &TYPE_SECTION_START(secname)[i]; \
} while (0)

Get element from section for a generic type.

Note
There is no protection against reading beyond the section.
Parameters
[in]typetype of element
[in]secnamename of output section
[in]iIndex.
[out]dstPointer to location where pointer to element is written.

◆ TYPE_SECTION_ITERABLE

#define TYPE_SECTION_ITERABLE (   type,
  varname,
  secname,
  section_postfix 
)

#include <zephyr/sys/iterable_sections.h>

Value:
Z_DECL_ALIGN(type) varname \
__in_section(_##secname, static, _CONCAT(section_postfix, _)) __used __noasan

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
[in]typedata type of variable
[in]varnamename of variable to place in section
[in]secnametype name of iterable section.
[in]section_postfixpostfix to use in section name

◆ TYPE_SECTION_START

#define TYPE_SECTION_START (   secname)    _CONCAT(_##secname, _list_start)

#include <zephyr/sys/iterable_sections.h>

iterable section start symbol for a generic type

will return '_[OUT_TYPE]_list_start'.

Parameters
[in]secnametype name of iterable section. For 'struct foobar' this would be TYPE_SECTION_START(foobar)

◆ TYPE_SECTION_START_EXTERN

#define TYPE_SECTION_START_EXTERN (   type,
  secname 
)     extern type TYPE_SECTION_START(secname)[]

#include <zephyr/sys/iterable_sections.h>

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
[in]typedata type of section
[in]secnamename of output section