Iterable Sections APIs

Iterable Sections APIs. More...

Macros
#define	ITERABLE_SECTION_ROM(struct_type, subalign)
	Define a read-only iterable section output. More...
#define	ITERABLE_SECTION_ROM_GC_ALLOWED(struct_type, subalign)
	Define a garbage collectable read-only iterable section output. More...
#define	ITERABLE_SECTION_RAM(struct_type, subalign)
	Define a read-write iterable section output. More...
#define	ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign)
	Define a garbage collectable read-write iterable section output. More...
#define	STRUCT_SECTION_ITERABLE(struct_type, name)
	Defines a new element for an iterable section. More...
#define	STRUCT_SECTION_ITERABLE_ALTERNATE(out_type, struct_type, name)
	Defines a new element of alternate data type for an iterable section. More...
#define	STRUCT_SECTION_FOREACH(struct_type, iterator)
	Iterate over a specified iterable section. More...
#define	STRUCT_SECTION_GET(struct_type, i, dst)
	Get element from section. More...
#define	STRUCT_SECTION_COUNT(struct_type, dst)
	Count elements in a section. More...

Detailed Description

Iterable Sections APIs.

Macro Definition Documentation

ITERABLE_SECTION_RAM

#define ITERABLE_SECTION_RAM	(		struct_type,
			subalign
	)

#include <include/zephyr/linker/linker-defs.h>

Value:

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

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 <include/zephyr/linker/linker-defs.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_ROM

#define ITERABLE_SECTION_ROM	(		struct_type,
			subalign
	)

#include <include/zephyr/linker/linker-defs.h>

Value:

        SECTION_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
        { \
                Z_LINK_ITERABLE(struct_type); \
        } GROUP_ROM_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)

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 <include/zephyr/linker/linker-defs.h>

Value:

        SECTION_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
        { \
                Z_LINK_ITERABLE_GC_ALLOWED(struct_type); \
        } GROUP_LINK_IN(ROMABLE_REGION)

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.

STRUCT_SECTION_COUNT

#define STRUCT_SECTION_COUNT	(		struct_type,
			dst
	)

#include <include/zephyr/toolchain/common.h>

Value:

        do { \
        extern struct struct_type _CONCAT(_##struct_type, _list_start)[]; \
        extern struct struct_type _CONCAT(_##struct_type, _list_end)[]; \
        *(dst) = ((uintptr_t)_CONCAT(_##struct_type, _list_end) - \
                  (uintptr_t)_CONCAT(_##struct_type, _list_start)) / sizeof(struct struct_type); \
} while (0)

Count elements in a section.

Parameters

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

STRUCT_SECTION_FOREACH

#define STRUCT_SECTION_FOREACH	(		struct_type,
			iterator
	)

#include <include/zephyr/toolchain/common.h>

Value:

        extern struct struct_type _CONCAT(_##struct_type, _list_start)[]; \
        extern struct struct_type _CONCAT(_##struct_type, _list_end)[]; \
        for (struct struct_type *iterator = \
                        _CONCAT(_##struct_type, _list_start); \
             ({ __ASSERT(iterator <= _CONCAT(_##struct_type, _list_end), \
                         "unexpected list end location"); \
                iterator < _CONCAT(_##struct_type, _list_end); }); \
             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

#define STRUCT_SECTION_GET	(		struct_type,
			i,
			dst
	)

#include <include/zephyr/toolchain/common.h>

Value:

        do { \
        extern struct struct_type _CONCAT(_##struct_type, _list_start)[]; \
        *(dst) = &_CONCAT(_##struct_type, _list_start)[i]; \
} while (0)

Get element from section.

Note

There is no protection against reading beyond the section.

Parameters

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

STRUCT_SECTION_ITERABLE

#define STRUCT_SECTION_ITERABLE	(		struct_type,
			name
	)

#include <include/zephyr/toolchain/common.h>

Value:

        Z_DECL_ALIGN(struct struct_type) name \
        __in_section(_##struct_type, static, name) __used __noasan

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	(		out_type,
			struct_type,
			name
	)

#include <include/zephyr/toolchain/common.h>

Value:

        Z_DECL_ALIGN(struct struct_type) name \
        __in_section(_##out_type, static, name) __used __noasan

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!