devicetree: document limitations related to for-each macros
Document a C preprocessor limitation that prevents "nested" use of for-each style devicetree macros in the way users sometimes expect. Put this in the devicetree.h header where it will show up in the detailed doxygen description in our HTML documentation, in addition to being in the sources themselves for people who prefer to look for docstrings there. Signed-off-by: Martí Bolívar <marti.bolivar@oss.qualcomm.com>
This commit is contained in:
parent
e4b04b41c0
commit
73903389bf
1 changed files with 30 additions and 0 deletions
|
@ -2929,6 +2929,36 @@
|
|||
* @defgroup devicetree-generic-foreach "For-each" macros
|
||||
* @ingroup devicetree
|
||||
* @{
|
||||
*
|
||||
* IMPORTANT: you can't use the DT for-each macros in their own expansions.
|
||||
*
|
||||
* For example, something like this won't work the way you might expect:
|
||||
*
|
||||
* @code{.c}
|
||||
* #define FOO(node_id) [...] DT_FOREACH_NODE(...) [...]
|
||||
* DT_FOREACH_NODE(FOO)
|
||||
* @endcode
|
||||
*
|
||||
* In this example, the C preprocessor won't expand the
|
||||
* DT_FOREACH_NODE() macro inside of FOO() while it's already
|
||||
* expanding DT_FOREACH_NODE() at the top level of the file.
|
||||
*
|
||||
* This is true of any macro, not just DT_FOREACH_NODE(). The C
|
||||
* language works this way to avoid infinite recursions inside of
|
||||
* macro expansions.
|
||||
*
|
||||
* If you need to "nest" calls to one of these macros, you can work
|
||||
* around this preprocessor limitation by using a different, related
|
||||
* macro instead, like this:
|
||||
*
|
||||
* @code{.c}
|
||||
* #define BAR(node_id) [...] DT_FOREACH_NODE_VARGS(...) [...]
|
||||
* DT_FOREACH_NODE(BAR)
|
||||
* @endcode
|
||||
*
|
||||
* Here, we use DT_FOREACH_NODE_VARGS() "inside" BAR() "inside"
|
||||
* DT_FOREACH_NODE(). Because of this, the preprocessor will expand
|
||||
* both DT_FOREACH_NODE_VARGS() and DT_FOREACH_NODE() as expected.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue