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 iterable section. More...
#define	STRUCT_SECTION_ITERABLE_ALTERNATE(out_type, struct_type, name)
	Defines an alternate data type iterable section. More...
#define	STRUCT_SECTION_FOREACH(struct_type, iterator)
	Iterate over a specified iterable section. More...

Detailed Description

Iterable Sections APIs.

Macro Definition Documentation

ITERABLE_SECTION_RAM

#define ITERABLE_SECTION_RAM	(		struct_type,
			subalign
	)

#include <include/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/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/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/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_FOREACH

#define STRUCT_SECTION_FOREACH	(		struct_type,
			iterator
	)

#include <include/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_ITERABLE

#define STRUCT_SECTION_ITERABLE	(		struct_type,
			name
	)

#include <include/toolchain/common.h>

Value:

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

Defines a new 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().

STRUCT_SECTION_ITERABLE_ALTERNATE

#define STRUCT_SECTION_ITERABLE_ALTERNATE	(		out_type,
			struct_type,
			name
	)

#include <include/toolchain/common.h>

Value:

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

Defines an alternate data type 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!