Browse Source
Until now iterable sections APIs have been part of the toolchain (common) headers. They are not strictly related to a toolchain, they just rely on linker providing support for sections. Most files relied on indirect includes to access the API, now, it is included as needed. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>pull/58130/head
Gerard Marull-Paretas
2 years ago
committed by
Carles Cufí
133 changed files with 599 additions and 430 deletions
@ -0,0 +1,145 @@ |
|||||||
|
/*
|
||||||
|
* Copyright (C) 2020, Intel Corporation |
||||||
|
* Copyright (C) 2023, Nordic Semiconductor ASA |
||||||
|
* SPDX-License-Identifier: Apache-2.0 |
||||||
|
*/ |
||||||
|
|
||||||
|
#ifndef INCLUDE_ZEPHYR_LINKER_ITERABLE_SECTIONS_H_ |
||||||
|
#define INCLUDE_ZEPHYR_LINKER_ITERABLE_SECTIONS_H_ |
||||||
|
|
||||||
|
/**
|
||||||
|
* @addtogroup iterable_section_apis |
||||||
|
* @{ |
||||||
|
*/ |
||||||
|
|
||||||
|
#define Z_LINK_ITERABLE(struct_type) \ |
||||||
|
_CONCAT(_##struct_type, _list_start) = .; \ |
||||||
|
KEEP(*(SORT_BY_NAME(._##struct_type.static.*))); \ |
||||||
|
_CONCAT(_##struct_type, _list_end) = . |
||||||
|
|
||||||
|
#define Z_LINK_ITERABLE_NUMERIC(struct_type) \ |
||||||
|
_CONCAT(_##struct_type, _list_start) = .; \ |
||||||
|
KEEP(*(SORT(._##struct_type.static.*_?_*))); \ |
||||||
|
KEEP(*(SORT(._##struct_type.static.*_??_*))); \ |
||||||
|
_CONCAT(_##struct_type, _list_end) = . |
||||||
|
|
||||||
|
#define Z_LINK_ITERABLE_ALIGNED(struct_type, align) \ |
||||||
|
. = ALIGN(align); \ |
||||||
|
Z_LINK_ITERABLE(struct_type); |
||||||
|
|
||||||
|
#define Z_LINK_ITERABLE_GC_ALLOWED(struct_type) \ |
||||||
|
_CONCAT(_##struct_type, _list_start) = .; \ |
||||||
|
*(SORT_BY_NAME(._##struct_type.static.*)); \ |
||||||
|
_CONCAT(_##struct_type, _list_end) = . |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Define a read-only iterable section output. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define ITERABLE_SECTION_ROM(struct_type, subalign) \ |
||||||
|
SECTION_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \ |
||||||
|
{ \ |
||||||
|
Z_LINK_ITERABLE(struct_type); \ |
||||||
|
} GROUP_ROM_LINK_IN(RAMABLE_REGION, ROMABLE_REGION) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief 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 ITERABLE_SECTION_ROM() |
||||||
|
*/ |
||||||
|
#define ITERABLE_SECTION_ROM_NUMERIC(struct_type, subalign) \ |
||||||
|
SECTION_PROLOGUE(struct_type##_area, EMPTY, SUBALIGN(subalign)) \ |
||||||
|
{ \ |
||||||
|
Z_LINK_ITERABLE_NUMERIC(struct_type); \ |
||||||
|
} GROUP_ROM_LINK_IN(RAMABLE_REGION, ROMABLE_REGION) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Define a garbage collectable read-only iterable section output. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define ITERABLE_SECTION_ROM_GC_ALLOWED(struct_type, subalign) \ |
||||||
|
SECTION_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \ |
||||||
|
{ \ |
||||||
|
Z_LINK_ITERABLE_GC_ALLOWED(struct_type); \ |
||||||
|
} GROUP_LINK_IN(ROMABLE_REGION) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Define a read-write iterable section output. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define ITERABLE_SECTION_RAM(struct_type, subalign) \ |
||||||
|
SECTION_DATA_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \ |
||||||
|
{ \ |
||||||
|
Z_LINK_ITERABLE(struct_type); \ |
||||||
|
} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief 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 ITERABLE_SECTION_RAM() |
||||||
|
*/ |
||||||
|
#define ITERABLE_SECTION_RAM_NUMERIC(struct_type, subalign) \ |
||||||
|
SECTION_PROLOGUE(struct_type##_area, EMPTY, SUBALIGN(subalign)) \ |
||||||
|
{ \ |
||||||
|
Z_LINK_ITERABLE_NUMERIC(struct_type); \ |
||||||
|
} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Define a garbage collectable read-write iterable section output. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign) \ |
||||||
|
SECTION_DATA_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \ |
||||||
|
{ \ |
||||||
|
Z_LINK_ITERABLE_GC_ALLOWED(struct_type); \ |
||||||
|
} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @} |
||||||
|
*/ /* end of struct_section_apis */ |
||||||
|
|
||||||
|
#endif /* INCLUDE_ZEPHYR_LINKER_ITERABLE_SECTIONS_H_ */ |
||||||
@ -0,0 +1,291 @@ |
|||||||
|
/*
|
||||||
|
* Copyright (C) 2020, Intel Corporation |
||||||
|
* Copyright (C) 2023, Nordic Semiconductor ASA |
||||||
|
* SPDX-License-Identifier: Apache-2.0 |
||||||
|
*/ |
||||||
|
|
||||||
|
#ifndef INCLUDE_ZEPHYR_SYS_ITERABLE_SECTIONS_H_ |
||||||
|
#define INCLUDE_ZEPHYR_SYS_ITERABLE_SECTIONS_H_ |
||||||
|
|
||||||
|
#include <zephyr/sys/__assert.h> |
||||||
|
#include <zephyr/toolchain.h> |
||||||
|
|
||||||
|
#ifdef __cplusplus |
||||||
|
extern "C" { |
||||||
|
#endif |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Iterable Sections APIs |
||||||
|
* @defgroup iterable_section_apis Iterable Sections APIs |
||||||
|
* @{ |
||||||
|
*/ |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Defines a new element for an iterable section for a generic type. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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(...); |
||||||
|
* |
||||||
|
* @param[in] type data type of variable |
||||||
|
* @param[in] varname name of variable to place in section |
||||||
|
* @param[in] secname type name of iterable section. |
||||||
|
* @param[in] section_postfix postfix to use in section name |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_ITERABLE(type, varname, secname, section_postfix) \ |
||||||
|
Z_DECL_ALIGN(type) varname \ |
||||||
|
__in_section(_##secname, static, _CONCAT(section_postfix, _)) __used __noasan |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief iterable section start symbol for a generic type |
||||||
|
* |
||||||
|
* will return '_[OUT_TYPE]_list_start'. |
||||||
|
* |
||||||
|
* @param[in] secname type name of iterable section. For 'struct foobar' this |
||||||
|
* would be TYPE_SECTION_START(foobar) |
||||||
|
* |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_START(secname) _CONCAT(_##secname, _list_start) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief iterable section end symbol for a generic type |
||||||
|
* |
||||||
|
* will return '_<SECNAME>_list_end'. |
||||||
|
* |
||||||
|
* @param[in] secname type name of iterable section. For 'struct foobar' this |
||||||
|
* would be TYPE_SECTION_START(foobar) |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_END(secname) _CONCAT(_##secname, _list_end) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief 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. |
||||||
|
* |
||||||
|
* @param[in] type data type of section |
||||||
|
* @param[in] secname name of output section |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_START_EXTERN(type, secname) \ |
||||||
|
extern type TYPE_SECTION_START(secname)[] |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief 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. |
||||||
|
* |
||||||
|
* @param[in] type data type of section |
||||||
|
* @param[in] secname name of output section |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_END_EXTERN(type, secname) \ |
||||||
|
extern type TYPE_SECTION_END(secname)[] |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Iterate over a specified iterable section for a generic type |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_FOREACH(type, secname, iterator) \ |
||||||
|
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++) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Get element from section for a generic type. |
||||||
|
* |
||||||
|
* @note There is no protection against reading beyond the section. |
||||||
|
* |
||||||
|
* @param[in] type type of element |
||||||
|
* @param[in] secname name of output section |
||||||
|
* @param[in] i Index. |
||||||
|
* @param[out] dst Pointer to location where pointer to element is written. |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_GET(type, secname, i, dst) do { \ |
||||||
|
TYPE_SECTION_START_EXTERN(type, secname); \ |
||||||
|
*(dst) = &TYPE_SECTION_START(secname)[i]; \ |
||||||
|
} while (0) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Count elements in a section for a generic type. |
||||||
|
* |
||||||
|
* @param[in] type type of element |
||||||
|
* @param[in] secname name of output section |
||||||
|
* @param[out] dst Pointer to location where result is written. |
||||||
|
*/ |
||||||
|
#define TYPE_SECTION_COUNT(type, secname, dst) 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) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief iterable section start symbol for a struct type |
||||||
|
* |
||||||
|
* @param[in] struct_type data type of section |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_START(struct_type) \ |
||||||
|
TYPE_SECTION_START(struct_type) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief iterable section extern for start symbol for a struct |
||||||
|
* |
||||||
|
* Helper macro to give extern for start of iterable section. |
||||||
|
* |
||||||
|
* @param[in] struct_type data type of section |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_START_EXTERN(struct_type) \ |
||||||
|
TYPE_SECTION_START_EXTERN(struct struct_type, struct_type) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief iterable section end symbol for a struct type |
||||||
|
* |
||||||
|
* @param[in] struct_type data type of section |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_END(struct_type) \ |
||||||
|
TYPE_SECTION_END(struct_type) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief iterable section extern for end symbol for a struct |
||||||
|
* |
||||||
|
* Helper macro to give extern for end of iterable section. |
||||||
|
* |
||||||
|
* @param[in] struct_type data type of section |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_END_EXTERN(struct_type) \ |
||||||
|
TYPE_SECTION_END_EXTERN(struct struct_type, struct_type) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Defines a new element of alternate data type for an iterable section. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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! |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_ITERABLE_ALTERNATE(secname, struct_type, varname) \ |
||||||
|
TYPE_SECTION_ITERABLE(struct struct_type, varname, secname, varname) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Defines an array of elements of alternate data type for an iterable |
||||||
|
* section. |
||||||
|
* |
||||||
|
* @see STRUCT_SECTION_ITERABLE_ALTERNATE |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(secname, struct_type, varname, \ |
||||||
|
size) \ |
||||||
|
TYPE_SECTION_ITERABLE(struct struct_type, varname[size], secname, \ |
||||||
|
varname) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Defines a new element for an iterable section. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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(...); |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_ITERABLE(struct_type, varname) \ |
||||||
|
STRUCT_SECTION_ITERABLE_ALTERNATE(struct_type, struct_type, varname) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Defines an array of elements for an iterable section. |
||||||
|
* |
||||||
|
* @see STRUCT_SECTION_ITERABLE |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_ITERABLE_ARRAY(struct_type, varname, size) \ |
||||||
|
STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(struct_type, struct_type, \ |
||||||
|
varname, size) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief 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 STRUCT_SECTION_ITERABLE() |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_ITERABLE_NAMED(struct_type, name, varname) \ |
||||||
|
TYPE_SECTION_ITERABLE(struct struct_type, varname, struct_type, name) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Iterate over a specified iterable section (alternate). |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_FOREACH_ALTERNATE(secname, struct_type, iterator) \ |
||||||
|
TYPE_SECTION_FOREACH(struct struct_type, secname, iterator) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Iterate over a specified iterable section. |
||||||
|
* |
||||||
|
* @details |
||||||
|
* 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. |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_FOREACH(struct_type, iterator) \ |
||||||
|
STRUCT_SECTION_FOREACH_ALTERNATE(struct_type, struct_type, iterator) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Get element from section. |
||||||
|
* |
||||||
|
* @note There is no protection against reading beyond the section. |
||||||
|
* |
||||||
|
* @param[in] struct_type Struct type. |
||||||
|
* @param[in] i Index. |
||||||
|
* @param[out] dst Pointer to location where pointer to element is written. |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_GET(struct_type, i, dst) \ |
||||||
|
TYPE_SECTION_GET(struct struct_type, struct_type, i, dst) |
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Count elements in a section. |
||||||
|
* |
||||||
|
* @param[in] struct_type Struct type |
||||||
|
* @param[out] dst Pointer to location where result is written. |
||||||
|
*/ |
||||||
|
#define STRUCT_SECTION_COUNT(struct_type, dst) \ |
||||||
|
TYPE_SECTION_COUNT(struct struct_type, struct_type, dst); |
||||||
|
|
||||||
|
/**
|
||||||
|
* @} |
||||||
|
*/ /* end of struct_section_apis */ |
||||||
|
|
||||||
|
#ifdef __cplusplus |
||||||
|
} |
||||||
|
#endif |
||||||
|
|
||||||
|
#endif /* INCLUDE_ZEPHYR_SYS_ITERABLE_SECTIONS_H_ */ |
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue