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