Line data Source code
1 1 : /*
2 : * Copyright (c) 2011-2014, Wind River Systems, Inc.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Macro utilities
10 : *
11 : * Macro utilities are the public interface for C/C++ code and device tree
12 : * related implementation. In general, C/C++ will include <sys/util.h>
13 : * instead this file directly. For device tree implementation, this file
14 : * should be include instead <sys/util_internal.h>
15 : */
16 :
17 : #ifndef ZEPHYR_INCLUDE_SYS_UTIL_MACROS_H_
18 : #define ZEPHYR_INCLUDE_SYS_UTIL_MACROS_H_
19 :
20 : #ifdef __cplusplus
21 : extern "C" {
22 : #endif
23 :
24 : /**
25 : * @addtogroup sys-util
26 : * @{
27 : */
28 :
29 : /*
30 : * Most of the eldritch implementation details for all the macrobatics
31 : * below (APIs like IS_ENABLED(), COND_CODE_1(), etc.) are hidden away
32 : * in this file.
33 : */
34 : #include <zephyr/sys/util_internal.h>
35 :
36 : #ifndef BIT
37 : #if defined(_ASMLANGUAGE)
38 : #define BIT(n) (1 << (n))
39 : #else
40 : /**
41 : * @brief Unsigned integer with bit position @p n set (signed in
42 : * assembly language).
43 : */
44 1 : #define BIT(n) (1UL << (n))
45 : #endif
46 : #endif
47 :
48 : /** @brief 64-bit unsigned integer with bit position @p _n set. */
49 1 : #define BIT64(_n) (1ULL << (_n))
50 :
51 : /**
52 : * @brief Set or clear a bit depending on a boolean value
53 : *
54 : * The argument @p var is a variable whose value is written to as a
55 : * side effect.
56 : *
57 : * @param var Variable to be altered
58 : * @param bit Bit number
59 : * @param set if 0, clears @p bit in @p var; any other value sets @p bit
60 : */
61 1 : #define WRITE_BIT(var, bit, set) \
62 : ((var) = (set) ? ((var) | BIT(bit)) : ((var) & ~BIT(bit)))
63 :
64 : /**
65 : * @brief Bit mask with bits 0 through <tt>n-1</tt> (inclusive) set,
66 : * or 0 if @p n is 0.
67 : */
68 1 : #define BIT_MASK(n) (BIT(n) - 1UL)
69 :
70 : /**
71 : * @brief 64-bit bit mask with bits 0 through <tt>n-1</tt> (inclusive) set,
72 : * or 0 if @p n is 0.
73 : */
74 1 : #define BIT64_MASK(n) (BIT64(n) - 1ULL)
75 :
76 : /** @brief Check if a @p x is a power of two */
77 1 : #define IS_POWER_OF_TWO(x) (((x) != 0U) && (((x) & ((x) - 1U)) == 0U))
78 :
79 : /**
80 : * @brief Check if bits are set continuously from the specified bit
81 : *
82 : * The macro is not dependent on the bit-width.
83 : *
84 : * @param m Check whether the bits are set continuously or not.
85 : * @param s Specify the lowest bit for that is continuously set bits.
86 : */
87 1 : #define IS_SHIFTED_BIT_MASK(m, s) (!(((m) >> (s)) & (((m) >> (s)) + 1U)))
88 :
89 : /**
90 : * @brief Check if bits are set continuously from the LSB.
91 : *
92 : * @param m Check whether the bits are set continuously from LSB.
93 : */
94 1 : #define IS_BIT_MASK(m) IS_SHIFTED_BIT_MASK(m, 0)
95 :
96 : /** @brief Extract the Least Significant Bit from @p value. */
97 1 : #define LSB_GET(value) ((value) & -(value))
98 :
99 : /**
100 : * @brief Extract a bitfield element from @p value corresponding to
101 : * the field mask @p mask.
102 : */
103 1 : #define FIELD_GET(mask, value) (((value) & (mask)) / LSB_GET(mask))
104 :
105 : /**
106 : * @brief Prepare a bitfield element using @p value with @p mask representing
107 : * its field position and width. The result should be combined
108 : * with other fields using a logical OR.
109 : */
110 1 : #define FIELD_PREP(mask, value) (((value) * LSB_GET(mask)) & (mask))
111 :
112 : /**
113 : * @brief Check for macro definition in compiler-visible expressions
114 : *
115 : * This trick was pioneered in Linux as the config_enabled() macro. It
116 : * has the effect of taking a macro value that may be defined to "1"
117 : * or may not be defined at all and turning it into a literal
118 : * expression that can be handled by the C compiler instead of just
119 : * the preprocessor. It is often used with a @p CONFIG_FOO macro which
120 : * may be defined to 1 via Kconfig, or left undefined.
121 : *
122 : * That is, it works similarly to <tt>\#if defined(CONFIG_FOO)</tt>
123 : * except that its expansion is a C expression. Thus, much <tt>\#ifdef</tt>
124 : * usage can be replaced with equivalents like:
125 : *
126 : * if (IS_ENABLED(CONFIG_FOO)) {
127 : * do_something_with_foo
128 : * }
129 : *
130 : * This is cleaner since the compiler can generate errors and warnings
131 : * for @p do_something_with_foo even when @p CONFIG_FOO is undefined.
132 : *
133 : * Note: Use of IS_ENABLED in a <tt>\#if</tt> statement is discouraged
134 : * as it doesn't provide any benefit vs plain <tt>\#if defined()</tt>
135 : *
136 : * @param config_macro Macro to check
137 : * @return 1 if @p config_macro is defined to 1, 0 otherwise (including
138 : * if @p config_macro is not defined)
139 : */
140 1 : #define IS_ENABLED(config_macro) Z_IS_ENABLED1(config_macro)
141 : /* INTERNAL: the first pass above is just to expand any existing
142 : * macros, we need the macro value to be e.g. a literal "1" at
143 : * expansion time in the next macro, not "(1)", etc... Standard
144 : * recursive expansion does not work.
145 : */
146 :
147 : /**
148 : * @brief Insert code depending on whether @p _flag expands to 1 or not.
149 : *
150 : * This relies on similar tricks as IS_ENABLED(), but as the result of
151 : * @p _flag expansion, results in either @p _if_1_code or @p
152 : * _else_code is expanded.
153 : *
154 : * To prevent the preprocessor from treating commas as argument
155 : * separators, the @p _if_1_code and @p _else_code expressions must be
156 : * inside brackets/parentheses: <tt>()</tt>. These are stripped away
157 : * during macro expansion.
158 : *
159 : * Example:
160 : *
161 : * COND_CODE_1(CONFIG_FLAG, (uint32_t x;), (there_is_no_flag();))
162 : *
163 : * If @p CONFIG_FLAG is defined to 1, this expands to:
164 : *
165 : * uint32_t x;
166 : *
167 : * It expands to <tt>there_is_no_flag();</tt> otherwise.
168 : *
169 : * This could be used as an alternative to:
170 : *
171 : * #if defined(CONFIG_FLAG) && (CONFIG_FLAG == 1)
172 : * #define MAYBE_DECLARE(x) uint32_t x
173 : * #else
174 : * #define MAYBE_DECLARE(x) there_is_no_flag()
175 : * #endif
176 : *
177 : * MAYBE_DECLARE(x);
178 : *
179 : * However, the advantage of COND_CODE_1() is that code is resolved in
180 : * place where it is used, while the @p \#if method defines @p
181 : * MAYBE_DECLARE on two lines and requires it to be invoked again on a
182 : * separate line. This makes COND_CODE_1() more concise and also
183 : * sometimes more useful when used within another macro's expansion.
184 : *
185 : * @note @p _flag can be the result of preprocessor expansion, e.g.
186 : * an expression involving <tt>NUM_VA_ARGS_LESS_1(...)</tt>.
187 : * However, @p _if_1_code is only expanded if @p _flag expands
188 : * to the integer literal 1. Integer expressions that evaluate
189 : * to 1, e.g. after doing some arithmetic, will not work.
190 : *
191 : * @param _flag evaluated flag
192 : * @param _if_1_code result if @p _flag expands to 1; must be in parentheses
193 : * @param _else_code result otherwise; must be in parentheses
194 : */
195 1 : #define COND_CODE_1(_flag, _if_1_code, _else_code) \
196 : Z_COND_CODE_1(_flag, _if_1_code, _else_code)
197 :
198 : /**
199 : * @brief Like COND_CODE_1() except tests if @p _flag is 0.
200 : *
201 : * This is like COND_CODE_1(), except that it tests whether @p _flag
202 : * expands to the integer literal 0. It expands to @p _if_0_code if
203 : * so, and @p _else_code otherwise; both of these must be enclosed in
204 : * parentheses.
205 : *
206 : * @param _flag evaluated flag
207 : * @param _if_0_code result if @p _flag expands to 0; must be in parentheses
208 : * @param _else_code result otherwise; must be in parentheses
209 : * @see COND_CODE_1()
210 : */
211 1 : #define COND_CODE_0(_flag, _if_0_code, _else_code) \
212 : Z_COND_CODE_0(_flag, _if_0_code, _else_code)
213 :
214 : /**
215 : * @brief Insert code if @p _flag is defined and equals 1.
216 : *
217 : * Like COND_CODE_1(), this expands to @p _code if @p _flag is defined to 1;
218 : * it expands to nothing otherwise.
219 : *
220 : * Example:
221 : *
222 : * IF_ENABLED(CONFIG_FLAG, (uint32_t foo;))
223 : *
224 : * If @p CONFIG_FLAG is defined to 1, this expands to:
225 : *
226 : * uint32_t foo;
227 : *
228 : * and to nothing otherwise.
229 : *
230 : * It can be considered as a more compact alternative to:
231 : *
232 : * #if defined(CONFIG_FLAG) && (CONFIG_FLAG == 1)
233 : * uint32_t foo;
234 : * #endif
235 : *
236 : * @param _flag evaluated flag
237 : * @param _code result if @p _flag expands to 1; must be in parentheses
238 : */
239 1 : #define IF_ENABLED(_flag, _code) \
240 : COND_CODE_1(_flag, _code, ())
241 :
242 : /**
243 : * @brief Insert code if @p _flag is not defined as 1.
244 : *
245 : * This expands to nothing if @p _flag is defined and equal to 1;
246 : * it expands to @p _code otherwise.
247 : *
248 : * Example:
249 : *
250 : * IF_DISABLED(CONFIG_FLAG, (uint32_t foo;))
251 : *
252 : * If @p CONFIG_FLAG isn't defined or different than 1, this expands to:
253 : *
254 : * uint32_t foo;
255 : *
256 : * and to nothing otherwise.
257 : *
258 : * IF_DISABLED does the opposite of IF_ENABLED.
259 : *
260 : * @param _flag evaluated flag
261 : * @param _code result if @p _flag does not expand to 1; must be in parentheses
262 : */
263 1 : #define IF_DISABLED(_flag, _code) \
264 : COND_CODE_1(_flag, (), _code)
265 :
266 : /**
267 : * @brief Check if a macro has a replacement expression
268 : *
269 : * If @p a is a macro defined to a nonempty value, this will return
270 : * true, otherwise it will return false. It only works with defined
271 : * macros, so an additional @p \#ifdef test may be needed in some cases.
272 : *
273 : * This macro may be used with COND_CODE_1() and COND_CODE_0() while
274 : * processing `__VA_ARGS__` to avoid processing empty arguments.
275 : *
276 : * Example:
277 : *
278 : * #define EMPTY
279 : * #define NON_EMPTY 1
280 : * #undef UNDEFINED
281 : * IS_EMPTY(EMPTY)
282 : * IS_EMPTY(NON_EMPTY)
283 : * IS_EMPTY(UNDEFINED)
284 : * #if defined(EMPTY) && IS_EMPTY(EMPTY) == true
285 : * some_conditional_code
286 : * #endif
287 : *
288 : * In above examples, the invocations of IS_EMPTY(...) return @p true,
289 : * @p false, and @p true; @p some_conditional_code is included.
290 : *
291 : * @param ... macro to check for emptiness (may be `__VA_ARGS__`)
292 : */
293 1 : #define IS_EMPTY(...) Z_IS_EMPTY_(__VA_ARGS__)
294 :
295 : /**
296 : * @brief Like <tt>a == b</tt>, but does evaluation and
297 : * short-circuiting at C preprocessor time.
298 : *
299 : * This however only works for integer literal from 0 to 4096 (literals with U suffix,
300 : * e.g. 0U are also included).
301 : *
302 : * Examples:
303 : *
304 : * IS_EQ(1, 1) -> 1
305 : * IS_EQ(1U, 1U) -> 1
306 : * IS_EQ(1U, 1) -> 1
307 : * IS_EQ(1, 1U) -> 1
308 : * IS_EQ(1, 0) -> 0
309 : *
310 : * @param a Integer literal (can be with U suffix)
311 : * @param b Integer literal
312 : *
313 : */
314 1 : #define IS_EQ(a, b) Z_IS_EQ(a, b)
315 :
316 : /**
317 : * @brief Remove empty arguments from list.
318 : *
319 : * During macro expansion, `__VA_ARGS__` and other preprocessor
320 : * generated lists may contain empty elements, e.g.:
321 : *
322 : * #define LIST ,a,b,,d,
323 : *
324 : * Using EMPTY to show each empty element, LIST contains:
325 : *
326 : * EMPTY, a, b, EMPTY, d
327 : *
328 : * When processing such lists, e.g. using FOR_EACH(), all empty elements
329 : * will be processed, and may require filtering out.
330 : * To make that process easier, it is enough to invoke LIST_DROP_EMPTY
331 : * which will remove all empty elements.
332 : *
333 : * Example:
334 : *
335 : * LIST_DROP_EMPTY(LIST)
336 : *
337 : * expands to:
338 : *
339 : * a, b, d
340 : *
341 : * @param ... list to be processed
342 : */
343 1 : #define LIST_DROP_EMPTY(...) \
344 : Z_LIST_DROP_FIRST(FOR_EACH(Z_LIST_NO_EMPTIES, (), __VA_ARGS__))
345 :
346 : /**
347 : * @brief Macro with an empty expansion
348 : *
349 : * This trivial definition is provided for readability when a macro
350 : * should expand to an empty result, which e.g. is sometimes needed to
351 : * silence checkpatch.
352 : *
353 : * Example:
354 : *
355 : * #define LIST_ITEM(n) , item##n
356 : *
357 : * The above would cause checkpatch to complain, but:
358 : *
359 : * #define LIST_ITEM(n) EMPTY, item##n
360 : *
361 : * would not.
362 : */
363 1 : #define EMPTY
364 :
365 : /**
366 : * @brief Macro that expands to its argument
367 : *
368 : * This is useful in macros like @c FOR_EACH() when there is no
369 : * transformation required on the list elements.
370 : *
371 : * @param V any value
372 : */
373 1 : #define IDENTITY(V) V
374 :
375 : /**
376 : * @brief Get nth argument from argument list.
377 : *
378 : * @param N Argument index to fetch. Counter from 1.
379 : * @param ... Variable list of arguments from which one argument is returned.
380 : *
381 : * @return Nth argument.
382 : */
383 1 : #define GET_ARG_N(N, ...) Z_GET_ARG_##N(__VA_ARGS__)
384 :
385 : /**
386 : * @brief Strips n first arguments from the argument list.
387 : *
388 : * @param N Number of arguments to discard.
389 : * @param ... Variable list of arguments.
390 : *
391 : * @return argument list without N first arguments.
392 : */
393 1 : #define GET_ARGS_LESS_N(N, ...) Z_GET_ARGS_LESS_##N(__VA_ARGS__)
394 :
395 : /**
396 : * @brief Like <tt>a || b</tt>, but does evaluation and
397 : * short-circuiting at C preprocessor time.
398 : *
399 : * This is not the same as the binary @p || operator; in particular,
400 : * @p a should expand to an integer literal 0 or 1. However, @p b
401 : * can be any value.
402 : *
403 : * This can be useful when @p b is an expression that would cause a
404 : * build error when @p a is 1.
405 : */
406 1 : #define UTIL_OR(a, b) COND_CODE_1(UTIL_BOOL(a), (a), (b))
407 :
408 : /**
409 : * @brief Like <tt>a && b</tt>, but does evaluation and
410 : * short-circuiting at C preprocessor time.
411 : *
412 : * This is not the same as the binary @p &&, however; in particular,
413 : * @p a should expand to an integer literal 0 or 1. However, @p b
414 : * can be any value.
415 : *
416 : * This can be useful when @p b is an expression that would cause a
417 : * build error when @p a is 0.
418 : */
419 1 : #define UTIL_AND(a, b) COND_CODE_1(UTIL_BOOL(a), (b), (0))
420 :
421 : /**
422 : * @brief UTIL_INC(x) for an integer literal x from 0 to 4095 expands to an
423 : * integer literal whose value is x+1.
424 : *
425 : * @see UTIL_DEC(x)
426 : */
427 1 : #define UTIL_INC(x) UTIL_PRIMITIVE_CAT(Z_UTIL_INC_, x)
428 :
429 : /**
430 : * @brief UTIL_DEC(x) for an integer literal x from 0 to 4095 expands to an
431 : * integer literal whose value is x-1.
432 : *
433 : * @see UTIL_INC(x)
434 : */
435 1 : #define UTIL_DEC(x) UTIL_PRIMITIVE_CAT(Z_UTIL_DEC_, x)
436 :
437 : /**
438 : * @brief UTIL_X2(y) for an integer literal y from 0 to 4095 expands to an
439 : * integer literal whose value is 2y.
440 : */
441 1 : #define UTIL_X2(y) UTIL_PRIMITIVE_CAT(Z_UTIL_X2_, y)
442 :
443 :
444 : /**
445 : * @brief Generates a sequence of code with configurable separator.
446 : *
447 : * Example:
448 : *
449 : * #define FOO(i, _) MY_PWM ## i
450 : * { LISTIFY(PWM_COUNT, FOO, (,)) }
451 : *
452 : * The above two lines expand to:
453 : *
454 : * { MY_PWM0 , MY_PWM1 }
455 : *
456 : * @param LEN The length of the sequence. Must be an integer literal less
457 : * than 4095.
458 : * @param F A macro function that accepts at least two arguments:
459 : * <tt>F(i, ...)</tt>. @p F is called repeatedly in the expansion.
460 : * Its first argument @p i is the index in the sequence, and
461 : * the variable list of arguments passed to LISTIFY are passed
462 : * through to @p F.
463 : *
464 : * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
465 : * this is required to enable providing a comma as separator.
466 : *
467 : * @note Calling LISTIFY with undefined arguments has undefined
468 : * behavior.
469 : */
470 1 : #define LISTIFY(LEN, F, sep, ...) UTIL_CAT(Z_UTIL_LISTIFY_, LEN)(F, sep, __VA_ARGS__)
471 :
472 : /**
473 : * @brief Call a macro @p F on each provided argument with a given
474 : * separator between each call.
475 : *
476 : * Example:
477 : *
478 : * #define F(x) int a##x
479 : * FOR_EACH(F, (;), 4, 5, 6);
480 : *
481 : * This expands to:
482 : *
483 : * int a4;
484 : * int a5;
485 : * int a6;
486 : *
487 : * @param F Macro to invoke
488 : * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
489 : * this is required to enable providing a comma as separator.
490 : * @param ... Variable argument list. The macro @p F is invoked as
491 : * <tt>F(element)</tt> for each element in the list.
492 : */
493 1 : #define FOR_EACH(F, sep, ...) \
494 : Z_FOR_EACH(F, sep, REVERSE_ARGS(__VA_ARGS__))
495 :
496 : /**
497 : * @brief Like FOR_EACH(), but with a terminator instead of a separator,
498 : * and drops empty elements from the argument list
499 : *
500 : * The @p sep argument to <tt>FOR_EACH(F, (sep), a, b)</tt> is a
501 : * separator which is placed between calls to @p F, like this:
502 : *
503 : * FOR_EACH(F, (sep), a, b) // F(a) sep F(b)
504 : * // ^^^ no sep here!
505 : *
506 : * By contrast, the @p term argument to <tt>FOR_EACH_NONEMPTY_TERM(F, (term),
507 : * a, b)</tt> is added after each time @p F appears in the expansion:
508 : *
509 : * FOR_EACH_NONEMPTY_TERM(F, (term), a, b) // F(a) term F(b) term
510 : * // ^^^^
511 : *
512 : * Further, any empty elements are dropped:
513 : *
514 : * FOR_EACH_NONEMPTY_TERM(F, (term), a, EMPTY, b) // F(a) term F(b) term
515 : *
516 : * This is more convenient in some cases, because FOR_EACH_NONEMPTY_TERM()
517 : * expands to nothing when given an empty argument list, and it's
518 : * often cumbersome to write a macro @p F that does the right thing
519 : * even when given an empty argument.
520 : *
521 : * One example is when `__VA_ARGS__` may or may not be empty,
522 : * and the results are embedded in a larger initializer:
523 : *
524 : * #define SQUARE(x) ((x)*(x))
525 : *
526 : * int my_array[] = {
527 : * FOR_EACH_NONEMPTY_TERM(SQUARE, (,), FOO(...))
528 : * FOR_EACH_NONEMPTY_TERM(SQUARE, (,), BAR(...))
529 : * FOR_EACH_NONEMPTY_TERM(SQUARE, (,), BAZ(...))
530 : * };
531 : *
532 : * This is more convenient than:
533 : *
534 : * 1. figuring out whether the @p FOO, @p BAR, and @p BAZ expansions
535 : * are empty and adding a comma manually (or not) between FOR_EACH()
536 : * calls
537 : * 2. rewriting SQUARE so it reacts appropriately when "x" is empty
538 : * (which would be necessary if e.g. @p FOO expands to nothing)
539 : *
540 : * @param F Macro to invoke on each nonempty element of the variable
541 : * arguments
542 : * @param term Terminator (e.g. comma or semicolon) placed after each
543 : * invocation of F. Must be in parentheses; this is required
544 : * to enable providing a comma as separator.
545 : * @param ... Variable argument list. The macro @p F is invoked as
546 : * <tt>F(element)</tt> for each nonempty element in the list.
547 : */
548 1 : #define FOR_EACH_NONEMPTY_TERM(F, term, ...) \
549 : COND_CODE_0( \
550 : /* are there zero non-empty arguments ? */ \
551 : NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
552 : /* if so, expand to nothing */ \
553 : (), \
554 : /* otherwise, expand to: */ \
555 : (/* FOR_EACH() on nonempty elements, */ \
556 : FOR_EACH(F, term, LIST_DROP_EMPTY(__VA_ARGS__)) \
557 : /* plus a final terminator */ \
558 : __DEBRACKET term \
559 : ))
560 :
561 : /**
562 : * @brief Call macro @p F on each provided argument, with the argument's index
563 : * as an additional parameter.
564 : *
565 : * This is like FOR_EACH(), except @p F should be a macro which takes two
566 : * arguments: <tt>F(index, variable_arg)</tt>.
567 : *
568 : * Example:
569 : *
570 : * #define F(idx, x) int a##idx = x
571 : * FOR_EACH_IDX(F, (;), 4, 5, 6);
572 : *
573 : * This expands to:
574 : *
575 : * int a0 = 4;
576 : * int a1 = 5;
577 : * int a2 = 6;
578 : *
579 : * @param F Macro to invoke
580 : * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
581 : * this is required to enable providing a comma as separator.
582 : * @param ... Variable argument list. The macro @p F is invoked as
583 : * <tt>F(index, element)</tt> for each element in the list.
584 : */
585 1 : #define FOR_EACH_IDX(F, sep, ...) \
586 : Z_FOR_EACH_IDX(F, sep, REVERSE_ARGS(__VA_ARGS__))
587 :
588 : /**
589 : * @brief Call macro @p F on each provided argument, with an additional fixed
590 : * argument as a parameter.
591 : *
592 : * This is like FOR_EACH(), except @p F should be a macro which takes two
593 : * arguments: <tt>F(variable_arg, fixed_arg)</tt>.
594 : *
595 : * Example:
596 : *
597 : * static void func(int val, void *dev);
598 : * FOR_EACH_FIXED_ARG(func, (;), dev, 4, 5, 6);
599 : *
600 : * This expands to:
601 : *
602 : * func(4, dev);
603 : * func(5, dev);
604 : * func(6, dev);
605 : *
606 : * @param F Macro to invoke
607 : * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
608 : * this is required to enable providing a comma as separator.
609 : * @param fixed_arg Fixed argument passed to @p F as the second macro parameter.
610 : * @param ... Variable argument list. The macro @p F is invoked as
611 : * <tt>F(element, fixed_arg)</tt> for each element in the list.
612 : */
613 1 : #define FOR_EACH_FIXED_ARG(F, sep, fixed_arg, ...) \
614 : Z_FOR_EACH_FIXED_ARG(F, sep, fixed_arg, REVERSE_ARGS(__VA_ARGS__))
615 :
616 : /**
617 : * @brief Calls macro @p F for each variable argument with an index and fixed
618 : * argument
619 : *
620 : * This is like the combination of FOR_EACH_IDX() with FOR_EACH_FIXED_ARG().
621 : *
622 : * Example:
623 : *
624 : * #define F(idx, x, fixed_arg) int fixed_arg##idx = x
625 : * FOR_EACH_IDX_FIXED_ARG(F, (;), a, 4, 5, 6);
626 : *
627 : * This expands to:
628 : *
629 : * int a0 = 4;
630 : * int a1 = 5;
631 : * int a2 = 6;
632 : *
633 : * @param F Macro to invoke
634 : * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
635 : * This is required to enable providing a comma as separator.
636 : * @param fixed_arg Fixed argument passed to @p F as the third macro parameter.
637 : * @param ... Variable list of arguments. The macro @p F is invoked as
638 : * <tt>F(index, element, fixed_arg)</tt> for each element in
639 : * the list.
640 : */
641 1 : #define FOR_EACH_IDX_FIXED_ARG(F, sep, fixed_arg, ...) \
642 : Z_FOR_EACH_IDX_FIXED_ARG(F, sep, fixed_arg, REVERSE_ARGS(__VA_ARGS__))
643 :
644 : /** @brief Reverse arguments order.
645 : *
646 : * @param ... Variable argument list.
647 : */
648 1 : #define REVERSE_ARGS(...) \
649 : Z_FOR_EACH_ENGINE(Z_FOR_EACH_EXEC, (,), Z_BYPASS, _, __VA_ARGS__)
650 :
651 : /**
652 : * @brief Number of arguments in the variable arguments list minus one.
653 : *
654 : * @note Supports up to 64 arguments.
655 : *
656 : * @param ... List of arguments
657 : * @return Number of variadic arguments in the argument list, minus one
658 : */
659 1 : #define NUM_VA_ARGS_LESS_1(...) \
660 : NUM_VA_ARGS_LESS_1_IMPL(__VA_ARGS__, 63, 62, 61, \
661 : 60, 59, 58, 57, 56, 55, 54, 53, 52, 51, \
662 : 50, 49, 48, 47, 46, 45, 44, 43, 42, 41, \
663 : 40, 39, 38, 37, 36, 35, 34, 33, 32, 31, \
664 : 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, \
665 : 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, \
666 : 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, ~)
667 :
668 : /**
669 : * @brief Number of arguments in the variable arguments list.
670 : *
671 : * @note Supports up to 63 arguments.
672 : *
673 : * @param ... List of arguments
674 : * @return Number of variadic arguments in the argument list
675 : */
676 1 : #define NUM_VA_ARGS(...) \
677 : COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (UTIL_INC(NUM_VA_ARGS_LESS_1(__VA_ARGS__))))
678 :
679 : /**
680 : * @brief Mapping macro that pastes results together
681 : *
682 : * This is similar to FOR_EACH() in that it invokes a macro repeatedly
683 : * on each element of `__VA_ARGS__`. However, unlike FOR_EACH(),
684 : * MACRO_MAP_CAT() pastes the results together into a single token.
685 : *
686 : * For example, with this macro FOO:
687 : *
688 : * #define FOO(x) item_##x##_
689 : *
690 : * <tt>MACRO_MAP_CAT(FOO, a, b, c),</tt> expands to the token:
691 : *
692 : * item_a_item_b_item_c_
693 : *
694 : * @param ... Macro to expand on each argument, followed by its
695 : * arguments. (The macro should take exactly one argument.)
696 : * @return The results of expanding the macro on each argument, all pasted
697 : * together
698 : */
699 1 : #define MACRO_MAP_CAT(...) MACRO_MAP_CAT_(__VA_ARGS__)
700 :
701 : /**
702 : * @brief Mapping macro that pastes a fixed number of results together
703 : *
704 : * Similar to @ref MACRO_MAP_CAT(), but expects a fixed number of
705 : * arguments. If more arguments are given than are expected, the rest
706 : * are ignored.
707 : *
708 : * @param N Number of arguments to map
709 : * @param ... Macro to expand on each argument, followed by its
710 : * arguments. (The macro should take exactly one argument.)
711 : * @return The results of expanding the macro on each argument, all pasted
712 : * together
713 : */
714 1 : #define MACRO_MAP_CAT_N(N, ...) MACRO_MAP_CAT_N_(N, __VA_ARGS__)
715 :
716 : /**
717 : * @}
718 : */
719 :
720 : #ifdef __cplusplus
721 : }
722 : #endif
723 :
724 : #endif /* ZEPHYR_INCLUDE_SYS_UTIL_MACROS_H_ */
|
