toolchain: redefine iterable section APIs as non internal

Redefine the APIs used to deal with iterable sections to an alias
without the Z_ prefix, so that they can be used by Zephyr applications.

Fix the associated comments so that they are handled correctly by
Doxygen.

Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>

include/linker/linker-defs.h

@@ -52,8 +52,12 @@
 	*(SORT_BY_NAME(._##struct_type.static.*)); \
 	_CONCAT(_##struct_type, _list_end) = .
 
-/* Define an output section which will set up an iterable area
+/**
- * of equally-sized data structures. For use with Z_STRUCT_SECTION_ITERABLE.
+ * @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.
@@ -62,28 +66,42 @@
  * 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) \
+	Z_ITERABLE_SECTION_ROM(struct_type, subalign)
+
 #define Z_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)
 
-/* Define an output section which will set up an iterable area
+/**
- * of equally-sized data structures. For use with Z_STRUCT_SECTION_ITERABLE.
+ * @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) \
+	Z_ITERABLE_SECTION_ROM_GC_ALLOWED(struct_type, subalign)
+
 #define Z_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)
 
-/* Define an output section which will set up an iterable area
+/**
- * of equally-sized data structures. For use with Z_STRUCT_SECTION_ITERABLE.
+ * @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.
@@ -92,6 +110,9 @@
  * 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) \
+	Z_ITERABLE_SECTION_RAM(struct_type, subalign)
+
 #define Z_ITERABLE_SECTION_RAM(struct_type, subalign) \
 	SECTION_DATA_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
 	{ \
@@ -99,14 +120,21 @@
 	} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)
 
 
-/* Define an output section which will set up an iterable area
+/**
- * of equally-sized data structures. For use with Z_STRUCT_SECTION_ITERABLE.
+ * @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) \
+	Z_ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign)
+
 #define Z_ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign) \
 	SECTION_DATA_PROLOGUE(struct_type##_area,,SUBALIGN(subalign)) \
 	{ \

include/toolchain/common.h

@@ -179,32 +179,52 @@
  */
 #define Z_DECL_ALIGN(type) __aligned(__alignof(type)) type
 
-/*
+/**
+ * @brief Defines a new 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
- * Z_ITERABLE_SECTION_ROM or Z_ITERABLE_SECTION_RAM.
+ * ITERABLE_SECTION_ROM() or ITERABLE_SECTION_RAM().
  */
+#define STRUCT_SECTION_ITERABLE(struct_type, name) \
+	Z_STRUCT_SECTION_ITERABLE(struct_type, name)
+
 #define Z_STRUCT_SECTION_ITERABLE(struct_type, name) \
 	Z_DECL_ALIGN(struct struct_type) name \
 	__in_section(_##struct_type, static, name) __used
 
-/* Special variant of Z_STRUCT_SECTION_ITERABLE, for placing alternate
+/**
+ * @brief Defines an alternate data type 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(out_type, struct_type, name) \
+	Z_STRUCT_SECTION_ITERABLE_ALTERNATE(out_type, struct_type, name)
+
 #define Z_STRUCT_SECTION_ITERABLE_ALTERNATE(out_type, struct_type, name) \
 	Z_DECL_ALIGN(struct struct_type) name \
 	__in_section(_##out_type, static, name) __used
 
-/*
+/**
- * Iterator for structure instances gathered by Z_STRUCT_SECTION_ITERABLE().
+ * @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.
+ * 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) \
+	Z_STRUCT_SECTION_FOREACH(struct_type, iterator)
+
 #define Z_STRUCT_SECTION_FOREACH(struct_type, iterator) \
 	extern struct struct_type _CONCAT(_##struct_type, _list_start)[]; \
 	extern struct struct_type _CONCAT(_##struct_type, _list_end)[]; \