Macros
#define	POINTER_TO_UINT(x) ((uintptr_t) (x))
	Cast `x`, a pointer, to an unsigned integer. More...

#define	UINT_TO_POINTER(x) ((void *) (uintptr_t) (x))
	Cast `x`, an unsigned integer, to a `void*`. More...

#define	POINTER_TO_INT(x) ((intptr_t) (x))
	Cast `x`, a pointer, to a signed integer. More...

#define	INT_TO_POINTER(x) ((void *) (intptr_t) (x))
	Cast `x`, a signed integer, to a `void*`. More...

#define	BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__)

#define	GENMASK(h, l) (((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
	Create a contiguous bitmask starting at bit position `l` and ending at position `h`. More...

#define	LSB_GET(value) ((value) & -(value))
	Extract the Least Significant Bit from `value`. More...

#define	FIELD_GET(mask, value) (((value) & (mask)) / LSB_GET(mask))
	Extract a bitfield element from `value` corresponding to the field mask `mask`. More...

#define	FIELD_PREP(mask, value) (((value) * LSB_GET(mask)) & (mask))
	Prepare a bitfield element using `value` with `mask` representing its field position and width. The result should be combined with other fields using a logical OR. More...

#define	ZERO_OR_COMPILE_ERROR(cond) ((int) sizeof(char[1 - 2 * !(cond)]) - 1)
	0 if `cond` is true-ish; causes a compile error otherwise. More...

#define	IS_ARRAY(array)
	Zero if `array` has an array type, a compile error otherwise. More...

#define	ARRAY_SIZE(array) ((long) (IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))
	Number of elements in the given `array`. More...

#define	PART_OF_ARRAY(array, ptr) ((ptr) && ((ptr) >= &array[0] && (ptr) < &array[ARRAY_SIZE(array)]))
	Check if a pointer `ptr` lies within `array`. More...

#define	CONTAINER_OF(ptr, type, field) ((type )(((char )(ptr)) - offsetof(type, field)))
	Get a pointer to a structure containing the element. More...

#define	ROUND_UP(x, align)
	Value of `x` rounded up to the next multiple of `align`, which must be a power of 2. More...

#define	ROUND_DOWN(x, align) ((unsigned long)(x) & ~((unsigned long)(align) - 1))
	Value of `x` rounded down to the previous multiple of `align`, which must be a power of 2. More...

#define	WB_UP(x) ROUND_UP(x, sizeof(void *))
	Value of `x` rounded up to the next word boundary. More...

#define	WB_DN(x) ROUND_DOWN(x, sizeof(void *))
	Value of `x` rounded down to the previous word boundary. More...

#define	ceiling_fraction(numerator, divider) (((numerator) + ((divider) - 1)) / (divider))
	Ceiling function applied to `numerator` / `divider` as a fraction. More...

#define	MAX(a, b) (((a) > (b)) ? (a) : (b))
	The larger value between `a` and `b`. More...

#define	MIN(a, b) (((a) < (b)) ? (a) : (b))
	The smaller value between `a` and `b`. More...

#define	CLAMP(val, low, high) (((val) <= (low)) ? (low) : MIN(val, high))
	Clamp a value to a given range. More...

#define	KB(x) ((x) << 10)
	Number of bytes in `x` kibibytes. More...

#define	MB(x) (KB(x) << 10)
	Number of bytes in `x` mebibytes. More...

#define	GB(x) (MB(x) << 10)
	Number of bytes in `x` gibibytes. More...

#define	KHZ(x) ((x) * 1000)
	Number of Hz in `x` kHz. More...

#define	MHZ(x) (KHZ(x) * 1000)
	Number of Hz in `x` MHz. More...

#define	BIT(n) (1UL << (n))
	Unsigned integer with bit position `n` set (signed in assembly language). More...

#define	BIT64(_n) (1ULL << (_n))
	64-bit unsigned integer with bit position `_n` set. More...

#define	WRITE_BIT(var, bit, set) ((var) = (set) ? ((var) \| BIT(bit)) : ((var) & ~BIT(bit)))
	Set or clear a bit depending on a boolean value. More...

#define	BIT_MASK(n) (BIT(n) - 1UL)
	Bit mask with bits 0 through `n-1` (inclusive) set, or 0 if `n` is 0. More...

#define	BIT64_MASK(n) (BIT64(n) - 1ULL)
	64-bit bit mask with bits 0 through `n-1` (inclusive) set, or 0 if `n` is 0. More...

#define	IS_ENABLED(config_macro) Z_IS_ENABLED1(config_macro)
	Check for macro definition in compiler-visible expressions. More...

#define	COND_CODE_1(_flag, _if_1_code, _else_code) Z_COND_CODE_1(_flag, _if_1_code, _else_code)
	Insert code depending on whether `_flag` expands to 1 or not. More...

#define	COND_CODE_0(_flag, _if_0_code, _else_code) Z_COND_CODE_0(_flag, _if_0_code, _else_code)
	Like COND_CODE_1() except tests if `_flag` is 0. More...

#define	IF_ENABLED(_flag, _code) COND_CODE_1(_flag, _code, ())
	Insert code if `_flag` is defined and equals 1. More...

#define	IS_EMPTY(...) Z_IS_EMPTY_(__VA_ARGS__)
	Check if a macro has a replacement expression. More...

#define	LIST_DROP_EMPTY(...) Z_LIST_DROP_FIRST(FOR_EACH(Z_LIST_NO_EMPTIES, (), __VA_ARGS__))
	Remove empty arguments from list. More...

#define	EMPTY
	Macro with an empty expansion. More...

#define	IDENTITY(V) V
	Macro that expands to its argument. More...

#define	GET_ARG_N(N, ...) Z_GET_ARG_##N(__VA_ARGS__)
	Get nth argument from argument list. More...

#define	GET_ARGS_LESS_N(N, ...) Z_GET_ARGS_LESS_##N(__VA_ARGS__)
	Strips n first arguments from the argument list. More...

#define	UTIL_OR(a, b) COND_CODE_1(UTIL_BOOL(a), (a), (b))
	Like `a \|\| b`, but does evaluation and short-circuiting at C preprocessor time. More...

#define	UTIL_AND(a, b) COND_CODE_1(UTIL_BOOL(a), (b), (0))
	Like `a && b`, but does evaluation and short-circuiting at C preprocessor time. More...

#define	UTIL_LISTIFY(LEN, F, ...) UTIL_CAT(Z_UTIL_LISTIFY_, LEN)(F, __VA_ARGS__)
	Generates a sequence of code. More...

#define	FOR_EACH(F, sep, ...) Z_FOR_EACH(F, sep, REVERSE_ARGS(__VA_ARGS__))
	Call a macro `F` on each provided argument with a given separator between each call. More...

#define	FOR_EACH_NONEMPTY_TERM(F, term, ...)
	Like FOR_EACH(), but with a terminator instead of a separator, and drops empty elements from the argument list. More...

#define	FOR_EACH_IDX(F, sep, ...) Z_FOR_EACH_IDX(F, sep, REVERSE_ARGS(__VA_ARGS__))
	Call macro `F` on each provided argument, with the argument's index as an additional parameter. More...

#define	FOR_EACH_FIXED_ARG(F, sep, fixed_arg, ...) Z_FOR_EACH_FIXED_ARG(F, sep, fixed_arg, REVERSE_ARGS(__VA_ARGS__))
	Call macro `F` on each provided argument, with an additional fixed argument as a parameter. More...

#define	FOR_EACH_IDX_FIXED_ARG(F, sep, fixed_arg, ...) Z_FOR_EACH_IDX_FIXED_ARG(F, sep, fixed_arg, REVERSE_ARGS(__VA_ARGS__))
	Calls macro `F` for each variable argument with an index and fixed argument. More...

#define	REVERSE_ARGS(...) Z_FOR_EACH_ENGINE(Z_FOR_EACH_EXEC, (,), Z_BYPASS, _, __VA_ARGS__)
	Reverse arguments order. More...

#define	NUM_VA_ARGS_LESS_1(...)
	Number of arguments in the variable arguments list minus one. More...

#define	MACRO_MAP_CAT(...) MACRO_MAP_CAT_(__VA_ARGS__)
	Mapping macro that pastes results together. More...

#define	MACRO_MAP_CAT_N(N, ...) MACRO_MAP_CAT_N_(N, __VA_ARGS__)
	Mapping macro that pastes a fixed number of results together. More...

Functions
static bool	is_power_of_two (unsigned int x)
	Is `x` a power of two? More...

static int64_t	arithmetic_shift_right (int64_t value, uint8_t shift)
	Arithmetic shift right. More...

static void	bytecpy (void dst, const void src, size_t size)
	byte by byte memcpy. More...

static void	byteswp (void a, void b, size_t size)
	byte by byte swap. More...

int	char2hex (char c, uint8_t *x)
	Convert a single character into a hexadecimal nibble. More...

int	hex2char (uint8_t x, char *c)
	Convert a single hexadecimal nibble into a character. More...

size_t	bin2hex (const uint8_t buf, size_t buflen, char hex, size_t hexlen)
	Convert a binary array into string representation. More...

size_t	hex2bin (const char hex, size_t hexlen, uint8_t buf, size_t buflen)
	Convert a hexadecimal string into a binary array. More...

static uint8_t	bcd2bin (uint8_t bcd)
	Convert a binary coded decimal (BCD 8421) value to binary. More...

static uint8_t	bin2bcd (uint8_t bin)
	Convert a binary value to binary coded decimal (BCD 8421). More...

uint8_t	u8_to_dec (char *buf, uint8_t buflen, uint8_t value)
	Convert a uint8_t into a decimal string representation. More...

char *	utf8_trunc (char *utf8_str)
	Properly truncate a NULL-terminated UTF-8 string. More...

char *	utf8_lcpy (char dst, const char src, size_t n)
	Copies a UTF-8 encoded string from `src` to `dst`. More...

Detailed Description

Macro Definition Documentation

◆ ARRAY_SIZE

#define ARRAY_SIZE ( array ) ((long) (IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))

#include <include/sys/util.h>

Number of elements in the given array.

In C++, due to language limitations, this will accept as array any type that implements operator[]. The results may not be particulary meaningful in this case.

In C, passing a pointer as array causes a compile error.

◆ BIT

#define BIT ( n ) (1UL << (n))

#include <include/sys/util_macro.h>

Unsigned integer with bit position n set (signed in assembly language).

◆ BIT64

#define BIT64 ( _n ) (1ULL << (_n))

#include <include/sys/util_macro.h>

64-bit unsigned integer with bit position _n set.

◆ BIT64_MASK

#define BIT64_MASK ( n ) (BIT64(n) - 1ULL)

#include <include/sys/util_macro.h>

64-bit bit mask with bits 0 through n-1 (inclusive) set, or 0 if n is 0.

◆ BIT_MASK

#define BIT_MASK ( n ) (BIT(n) - 1UL)

#include <include/sys/util_macro.h>

Bit mask with bits 0 through n-1 (inclusive) set, or 0 if n is 0.

◆ BITS_PER_LONG

#define BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__)

#include <include/sys/util.h>

Number of bits in a long int.

◆ ceiling_fraction

#define ceiling_fraction	(	numerator,
		divider
	)	(((numerator) + ((divider) - 1)) / (divider))

#include <include/sys/util.h>

Ceiling function applied to numerator / divider as a fraction.

◆ CLAMP

#define CLAMP	(	val,
		low,
		high
	)	(((val) <= (low)) ? (low) : MIN(val, high))

#include <include/sys/util.h>

Clamp a value to a given range.

Note: Arguments are evaluated multiple times.

◆ COND_CODE_0

#define COND_CODE_0	(	_flag,
		_if_0_code,
		_else_code
	)	Z_COND_CODE_0(_flag, _if_0_code, _else_code)

#include <include/sys/util_macro.h>

Like COND_CODE_1() except tests if _flag is 0.

This is like COND_CODE_1(), except that it tests whether _flag expands to the integer literal 0. It expands to _if_0_code if so, and _else_code otherwise; both of these must be enclosed in parentheses.

Parameters

_flag	evaluated flag
_if_0_code	result if `_flag` expands to 0; must be in parentheses
_else_code	result otherwise; must be in parentheses

See also: COND_CODE_1()

◆ COND_CODE_1

#define COND_CODE_1	(	_flag,
		_if_1_code,
		_else_code
	)	Z_COND_CODE_1(_flag, _if_1_code, _else_code)

#include <include/sys/util_macro.h>

Insert code depending on whether _flag expands to 1 or not.

This relies on similar tricks as IS_ENABLED(), but as the result of _flag expansion, results in either _if_1_code or _else_code is expanded.

To prevent the preprocessor from treating commas as argument separators, the _if_1_code and _else_code expressions must be inside brackets/parentheses: (). These are stripped away during macro expansion.

Example:

COND_CODE_1(CONFIG_FLAG, (uint32_t x;), (there_is_no_flag();))

If CONFIG_FLAG is defined to 1, this expands to:

uint32_t x;

It expands to there_is_no_flag(); otherwise.

This could be used as an alternative to:

#if defined(CONFIG_FLAG) && (CONFIG_FLAG == 1)
#define MAYBE_DECLARE(x) uint32_t x
#else
#define MAYBE_DECLARE(x) there_is_no_flag()
#endif

MAYBE_DECLARE(x);

However, the advantage of COND_CODE_1() is that code is resolved in place where it is used, while the #if method defines MAYBE_DECLARE on two lines and requires it to be invoked again on a separate line. This makes COND_CODE_1() more concise and also sometimes more useful when used within another macro's expansion.

Note: _flag can be the result of preprocessor expansion, e.g. an expression involving NUM_VA_ARGS_LESS_1(...). However, _if_1_code is only expanded if _flag expands to the integer literal 1. Integer expressions that evaluate to 1, e.g. after doing some arithmetic, will not work.

Parameters

_flag	evaluated flag
_if_1_code	result if `_flag` expands to 1; must be in parentheses
_else_code	result otherwise; must be in parentheses

◆ CONTAINER_OF

#define CONTAINER_OF	(	ptr,
		type,
		field
	)	((type )(((char )(ptr)) - offsetof(type, field)))

#include <include/sys/util.h>

Get a pointer to a structure containing the element.

Example:

 struct foo {
    int bar;
 };

 struct foo my_foo;
 int *ptr = &my_foo.bar;

 struct foo *container = CONTAINER_OF(ptr, struct foo, bar);

Above, container points at my_foo.

Parameters

ptr	pointer to a structure element
type	name of the type that `ptr` is an element of
field	the name of the field within the struct `ptr` points to

Returns: a pointer to the structure that contains ptr

◆ EMPTY

#define EMPTY

#include <include/sys/util_macro.h>

Macro with an empty expansion.

This trivial definition is provided for readability when a macro should expand to an empty result, which e.g. is sometimes needed to silence checkpatch.

Example:

 #define LIST_ITEM(n) , item##n

The above would cause checkpatch to complain, but:

 #define LIST_ITEM(n) EMPTY, item##n

would not.

◆ FIELD_GET

#define FIELD_GET	(	mask,
		value
	)	(((value) & (mask)) / LSB_GET(mask))

#include <include/sys/util.h>

Extract a bitfield element from value corresponding to the field mask mask.

◆ FIELD_PREP

#define FIELD_PREP	(	mask,
		value
	)	(((value) * LSB_GET(mask)) & (mask))

#include <include/sys/util.h>

Prepare a bitfield element using value with mask representing its field position and width. The result should be combined with other fields using a logical OR.

◆ FOR_EACH

#define FOR_EACH	(	F,
		sep,
		...
	)	Z_FOR_EACH(F, sep, REVERSE_ARGS(__VA_ARGS__))

#include <include/sys/util_macro.h>

Call a macro F on each provided argument with a given separator between each call.

Example:

#define F(x) int a##x
FOR_EACH(F, (;), 4, 5, 6);

This expands to:

int a4;
int a5;
int a6;

Parameters

F	Macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.
...	Variable argument list. The macro `F` is invoked as `F(element)` for each element in the list.

◆ FOR_EACH_FIXED_ARG

#define FOR_EACH_FIXED_ARG	(	F,
		sep,
		fixed_arg,
		...
	)	Z_FOR_EACH_FIXED_ARG(F, sep, fixed_arg, REVERSE_ARGS(__VA_ARGS__))

#include <include/sys/util_macro.h>

Call macro F on each provided argument, with an additional fixed argument as a parameter.

This is like FOR_EACH(), except F should be a macro which takes two arguments: F(variable_arg, fixed_arg).

Example:

static void func(int val, void *dev);
FOR_EACH_FIXED_ARG(func, (;), dev, 4, 5, 6);

This expands to:

func(4, dev);
func(5, dev);
func(6, dev);

Parameters

F	Macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.
fixed_arg	Fixed argument passed to `F` as the second macro parameter.
...	Variable argument list. The macro `F` is invoked as `F(element, fixed_arg)` for each element in the list.

◆ FOR_EACH_IDX

#define FOR_EACH_IDX	(	F,
		sep,
		...
	)	Z_FOR_EACH_IDX(F, sep, REVERSE_ARGS(__VA_ARGS__))

#include <include/sys/util_macro.h>

Call macro F on each provided argument, with the argument's index as an additional parameter.

This is like FOR_EACH(), except F should be a macro which takes two arguments: F(index, variable_arg).

Example:

#define F(idx, x) int a##idx = x
FOR_EACH_IDX(F, (;), 4, 5, 6);

This expands to:

int a0 = 4;
int a1 = 5;
int a2 = 6;

Parameters

F	Macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.
...	Variable argument list. The macro `F` is invoked as `F(index, element)` for each element in the list.

◆ FOR_EACH_IDX_FIXED_ARG

#define FOR_EACH_IDX_FIXED_ARG	(	F,
		sep,
		fixed_arg,
		...
	)	Z_FOR_EACH_IDX_FIXED_ARG(F, sep, fixed_arg, REVERSE_ARGS(__VA_ARGS__))

#include <include/sys/util_macro.h>

Calls macro F for each variable argument with an index and fixed argument.

This is like the combination of FOR_EACH_IDX() with FOR_EACH_FIXED_ARG().

Example:

#define F(idx, x, fixed_arg) int fixed_arg##idx = x
FOR_EACH_IDX_FIXED_ARG(F, (;), a, 4, 5, 6);

This expands to:

int a0 = 4;
int a1 = 5;
int a2 = 6;

Parameters

F	Macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; This is required to enable providing a comma as separator.
fixed_arg	Fixed argument passed to `F` as the third macro parameter.
...	Variable list of arguments. The macro `F` is invoked as `F(index, element, fixed_arg)` for each element in the list.

◆ FOR_EACH_NONEMPTY_TERM

#define FOR_EACH_NONEMPTY_TERM	(	F,
		term,
		...
	)

#include <include/sys/util_macro.h>

Value:

        COND_CODE_0(                                                    \
                /* are there zero non-empty arguments ? */              \
                NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)),    \
                /* if so, expand to nothing */                          \
                (),                                                     \
                /* otherwise, expand to: */                             \
                (/* FOR_EACH() on nonempty elements, */         \
                        FOR_EACH(F, term, LIST_DROP_EMPTY(__VA_ARGS__)) \
                        /* plus a final terminator */                   \
                        __DEBRACKET term                                \
                ))

Like FOR_EACH(), but with a terminator instead of a separator, and drops empty elements from the argument list.

The sep argument to FOR_EACH(F, (sep), a, b) is a separator which is placed between calls to F, like this:

FOR_EACH(F, (sep), a, b) // F(a) sep F(b)
                         //               ^^^ no sep here!

By contrast, the term argument to FOR_EACH_NONEMPTY_TERM(F, (term), a, b) is added after each time F appears in the expansion:

FOR_EACH_NONEMPTY_TERM(F, (term), a, b) // F(a) term F(b) term
                                        //                ^^^^

Further, any empty elements are dropped:

FOR_EACH_NONEMPTY_TERM(F, (term), a, EMPTY, b) // F(a) term F(b) term

This is more convenient in some cases, because FOR_EACH_NONEMPTY_TERM() expands to nothing when given an empty argument list, and it's often cumbersome to write a macro F that does the right thing even when given an empty argument.

One example is when VA_ARGS may or may not be empty, and the results are embedded in a larger initializer:

#define SQUARE(x) ((x)*(x))

int my_array[] = {
        FOR_EACH_NONEMPTY_TERM(SQUARE, (,), FOO(...))
        FOR_EACH_NONEMPTY_TERM(SQUARE, (,), BAR(...))
        FOR_EACH_NONEMPTY_TERM(SQUARE, (,), BAZ(...))
};

This is more convenient than:

figuring out whether the FOO, BAR, and BAZ expansions are empty and adding a comma manually (or not) between FOR_EACH() calls
rewriting SQUARE so it reacts appropriately when "x" is empty (which would be necessary if e.g. FOO expands to nothing)

Parameters

F	Macro to invoke on each nonempty element of the variable arguments
term	Terminator (e.g. comma or semicolon) placed after each invocation of F. Must be in parentheses; this is required to enable providing a comma as separator.
...	Variable argument list. The macro `F` is invoked as `F(element)` for each nonempty element in the list.

◆ GB

#define GB ( x ) (MB(x) << 10)

#include <include/sys/util.h>

Number of bytes in x gibibytes.

◆ GENMASK

#define GENMASK	(	h,
		l
	)	(((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))

#include <include/sys/util.h>

Create a contiguous bitmask starting at bit position l and ending at position h.

◆ GET_ARG_N

#define GET_ARG_N	(	N,
		...
	)	Z_GET_ARG_##N(__VA_ARGS__)

#include <include/sys/util_macro.h>

Get nth argument from argument list.

Parameters

N	Argument index to fetch. Counter from 1.
...	Variable list of argments from which one argument is returned.

Returns: Nth argument.

◆ GET_ARGS_LESS_N

#define GET_ARGS_LESS_N	(	N,
		...
	)	Z_GET_ARGS_LESS_##N(__VA_ARGS__)

#include <include/sys/util_macro.h>

Strips n first arguments from the argument list.

Parameters

N	Number of arguments to discard.
...	Variable list of argments.

Returns: argument list without N first arguments.

◆ IDENTITY

#define IDENTITY ( V ) V

#include <include/sys/util_macro.h>

Macro that expands to its argument.

This is useful in macros like FOR_EACH() when there is no transformation required on the list elements.

Parameters

V any value

◆ IF_ENABLED

#define IF_ENABLED	(	_flag,
		_code
	)	COND_CODE_1(_flag, _code, ())

#include <include/sys/util_macro.h>

Insert code if _flag is defined and equals 1.

Like COND_CODE_1(), this expands to _code if _flag is defined to 1; it expands to nothing otherwise.

Example:

IF_ENABLED(CONFIG_FLAG, (uint32_t foo;))

If CONFIG_FLAG is defined to 1, this expands to:

uint32_t foo;

and to nothing otherwise.

It can be considered as a more compact alternative to:

#if defined(CONFIG_FLAG) && (CONFIG_FLAG == 1)
uint32_t foo;
#endif

Parameters

_flag	evaluated flag
_code	result if `_flag` expands to 1; must be in parentheses

◆ INT_TO_POINTER

#define INT_TO_POINTER ( x ) ((void *) (intptr_t) (x))

#include <include/sys/util.h>

Cast x, a signed integer, to a void*.

◆ IS_ARRAY

#define IS_ARRAY ( array )

#include <include/sys/util.h>

Value:

        ZERO_OR_COMPILE_ERROR( \
                !__builtin_types_compatible_p(__typeof__(array), \
                                              __typeof__(&(array)[0])))

Zero if array has an array type, a compile error otherwise.

This macro is available only from C, not C++.

◆ IS_EMPTY

#define IS_EMPTY ( ... ) Z_IS_EMPTY_(__VA_ARGS__)

#include <include/sys/util_macro.h>

Check if a macro has a replacement expression.

If a is a macro defined to a nonempty value, this will return true, otherwise it will return false. It only works with defined macros, so an additional #ifdef test may be needed in some cases.

This macro may be used with COND_CODE_1() and COND_CODE_0() while processing VA_ARGS to avoid processing empty arguments.

Example:

 #define EMPTY
 #define NON_EMPTY  1
 #undef  UNDEFINED
 IS_EMPTY(EMPTY)
 IS_EMPTY(NON_EMPTY)
 IS_EMPTY(UNDEFINED)
 #if defined(EMPTY) && IS_EMPTY(EMPTY) == true
 some_conditional_code
 #endif

In above examples, the invocations of IS_EMPTY(...) return true, false, and true; some_conditional_code is included.

Parameters

...	macro to check for emptiness (may be `VA_ARGS`)

◆ IS_ENABLED

#define IS_ENABLED ( config_macro ) Z_IS_ENABLED1(config_macro)

#include <include/sys/util_macro.h>

Check for macro definition in compiler-visible expressions.

This trick was pioneered in Linux as the config_enabled() macro. It has the effect of taking a macro value that may be defined to "1" or may not be defined at all and turning it into a literal expression that can be handled by the C compiler instead of just the preprocessor. It is often used with a CONFIG_FOO macro which may be defined to 1 via Kconfig, or left undefined.

That is, it works similarly to #if defined(CONFIG_FOO) except that its expansion is a C expression. Thus, much #ifdef usage can be replaced with equivalents like:

if (IS_ENABLED(CONFIG_FOO)) {
        do_something_with_foo
}

This is cleaner since the compiler can generate errors and warnings for do_something_with_foo even when CONFIG_FOO is undefined.

Parameters

config_macro Macro to check

Returns: 1 if config_macro is defined to 1, 0 otherwise (including if config_macro is not defined)

◆ KB

#define KB ( x ) ((x) << 10)

#include <include/sys/util.h>

Number of bytes in x kibibytes.

◆ KHZ

#define KHZ ( x ) ((x) * 1000)

#include <include/sys/util.h>

Number of Hz in x kHz.

◆ LIST_DROP_EMPTY

#define LIST_DROP_EMPTY ( ... ) Z_LIST_DROP_FIRST(FOR_EACH(Z_LIST_NO_EMPTIES, (), __VA_ARGS__))

#include <include/sys/util_macro.h>

Remove empty arguments from list.

During macro expansion, VA_ARGS and other preprocessor generated lists may contain empty elements, e.g.:

 #define LIST ,a,b,,d,

Using EMPTY to show each empty element, LIST contains:

 EMPTY, a, b, EMPTY, d

When processing such lists, e.g. using FOR_EACH(), all empty elements will be processed, and may require filtering out. To make that process easier, it is enough to invoke LIST_DROP_EMPTY which will remove all empty elements.

Example:

 LIST_DROP_EMPTY(LIST)

expands to:

 a, b, d

Parameters

...	list to be processed

◆ LSB_GET

#define LSB_GET ( value ) ((value) & -(value))

#include <include/sys/util.h>

Extract the Least Significant Bit from value.

◆ MACRO_MAP_CAT

#define MACRO_MAP_CAT ( ... ) MACRO_MAP_CAT_(__VA_ARGS__)

#include <include/sys/util_macro.h>

Mapping macro that pastes results together.

This is similar to FOR_EACH() in that it invokes a macro repeatedly on each element of VA_ARGS. However, unlike FOR_EACH(), MACRO_MAP_CAT() pastes the results together into a single token.

For example, with this macro FOO:

#define FOO(x) item_##x##_

MACRO_MAP_CAT(FOO, a, b, c), expands to the token:

item_a_item_b_item_c_

Parameters

...	Macro to expand on each argument, followed by its arguments. (The macro should take exactly one argument.)

Returns: The results of expanding the macro on each argument, all pasted together

◆ MACRO_MAP_CAT_N

#define MACRO_MAP_CAT_N	(	N,
		...
	)	MACRO_MAP_CAT_N_(N, __VA_ARGS__)

#include <include/sys/util_macro.h>

Mapping macro that pastes a fixed number of results together.

Similar to MACRO_MAP_CAT(), but expects a fixed number of arguments. If more arguments are given than are expected, the rest are ignored.

Parameters

N	Number of arguments to map
...	Macro to expand on each argument, followed by its arguments. (The macro should take exactly one argument.)

Returns: The results of expanding the macro on each argument, all pasted together

◆ MAX

#define MAX	(	a,
		b
	)	(((a) > (b)) ? (a) : (b))

#include <include/sys/util.h>

The larger value between a and b.

Note: Arguments are evaluated twice.

◆ MB

#define MB ( x ) (KB(x) << 10)

#include <include/sys/util.h>

Number of bytes in x mebibytes.

◆ MHZ

#define MHZ ( x ) (KHZ(x) * 1000)

#include <include/sys/util.h>

Number of Hz in x MHz.

◆ MIN

#define MIN	(	a,
		b
	)	(((a) < (b)) ? (a) : (b))

#include <include/sys/util.h>

The smaller value between a and b.

Note: Arguments are evaluated twice.

◆ NUM_VA_ARGS_LESS_1

#define NUM_VA_ARGS_LESS_1 ( ... )

#include <include/sys/util_macro.h>

Value:

        NUM_VA_ARGS_LESS_1_IMPL(__VA_ARGS__, 63, 62, 61, \
        60, 59, 58, 57, 56, 55, 54, 53, 52, 51,          \
        50, 49, 48, 47, 46, 45, 44, 43, 42, 41,          \
        40, 39, 38, 37, 36, 35, 34, 33, 32, 31,          \
        30, 29, 28, 27, 26, 25, 24, 23, 22, 21,          \
        20, 19, 18, 17, 16, 15, 14, 13, 12, 11,          \
        10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, ~)

Number of arguments in the variable arguments list minus one.

Parameters

...	List of arguments

Returns: Number of variadic arguments in the argument list, minus one

◆ PART_OF_ARRAY

#define PART_OF_ARRAY	(	array,
		ptr
	)	((ptr) && ((ptr) >= &array[0] && (ptr) < &array[ARRAY_SIZE(array)]))

#include <include/sys/util.h>

Check if a pointer ptr lies within array.

In C but not C++, this causes a compile error if array is not an array (e.g. if ptr and array are mixed up).

Parameters

ptr	a pointer
array	an array

Returns: 1 if ptr is part of array, 0 otherwise

◆ POINTER_TO_INT

#define POINTER_TO_INT ( x ) ((intptr_t) (x))

#include <include/sys/util.h>

Cast x, a pointer, to a signed integer.

◆ POINTER_TO_UINT

#define POINTER_TO_UINT ( x ) ((uintptr_t) (x))

#include <include/sys/util.h>

Cast x, a pointer, to an unsigned integer.

◆ REVERSE_ARGS

#define REVERSE_ARGS ( ... ) Z_FOR_EACH_ENGINE(Z_FOR_EACH_EXEC, (,), Z_BYPASS, _, __VA_ARGS__)

#include <include/sys/util_macro.h>

Reverse arguments order.

Parameters

...	Variable argument list.

◆ ROUND_DOWN

#define ROUND_DOWN	(	x,
		align
	)	((unsigned long)(x) & ~((unsigned long)(align) - 1))

#include <include/sys/util.h>

Value of x rounded down to the previous multiple of align, which must be a power of 2.

◆ ROUND_UP

#define ROUND_UP	(	x,
		align
	)

#include <include/sys/util.h>

Value:

(((unsigned long)(x) + ((unsigned long)(align) - 1)) & \

~((unsigned long)(align) - 1))

Value of x rounded up to the next multiple of align, which must be a power of 2.

◆ UINT_TO_POINTER

#define UINT_TO_POINTER ( x ) ((void *) (uintptr_t) (x))

#include <include/sys/util.h>

Cast x, an unsigned integer, to a void*.

◆ UTIL_AND

#define UTIL_AND	(	a,
		b
	)	COND_CODE_1(UTIL_BOOL(a), (b), (0))

#include <include/sys/util_macro.h>

Like a && b, but does evaluation and short-circuiting at C preprocessor time.

This is not the same as the binary &&, however; in particular, a should expand to an integer literal 0 or 1. However, b can be any value.

This can be useful when b is an expression that would cause a build error when a is 0.

◆ UTIL_LISTIFY

#define UTIL_LISTIFY	(	LEN,
		F,
		...
	)	UTIL_CAT(Z_UTIL_LISTIFY_, LEN)(F, __VA_ARGS__)

#include <include/sys/util_macro.h>

Generates a sequence of code.

Example:

#define FOO(i, _) MY_PWM ## i ,
{ UTIL_LISTIFY(PWM_COUNT, FOO) }

The above two lines expand to:

{ MY_PWM0 , MY_PWM1 , }

Parameters

LEN	The length of the sequence. Must be an integer literal less than 255.
F	A macro function that accepts at least two arguments: `F(i, ...)`. `F` is called repeatedly in the expansion. Its first argument `i` is the index in the sequence, and the variable list of arguments passed to UTIL_LISTIFY are passed through to `F`.

Note: Calling UTIL_LISTIFY with undefined arguments has undefined behavior.

◆ UTIL_OR

#define UTIL_OR	(	a,
		b
	)	COND_CODE_1(UTIL_BOOL(a), (a), (b))

#include <include/sys/util_macro.h>

Like a || b, but does evaluation and short-circuiting at C preprocessor time.

This is not the same as the binary || operator; in particular, a should expand to an integer literal 0 or 1. However, b can be any value.

This can be useful when b is an expression that would cause a build error when a is 1.

◆ WB_DN

#define WB_DN ( x ) ROUND_DOWN(x, sizeof(void *))

#include <include/sys/util.h>

Value of x rounded down to the previous word boundary.

◆ WB_UP

#define WB_UP ( x ) ROUND_UP(x, sizeof(void *))

#include <include/sys/util.h>

Value of x rounded up to the next word boundary.

◆ WRITE_BIT

#define WRITE_BIT	(	var,
		bit,
		set
	)	((var) = (set) ? ((var) \| BIT(bit)) : ((var) & ~BIT(bit)))

#include <include/sys/util_macro.h>

Set or clear a bit depending on a boolean value.

The argument var is a variable whose value is written to as a side effect.

Parameters

var	Variable to be altered
bit	Bit number
set	if 0, clears `bit` in `var`; any other value sets `bit`

◆ ZERO_OR_COMPILE_ERROR

#define ZERO_OR_COMPILE_ERROR ( cond ) ((int) sizeof(char[1 - 2 * !(cond)]) - 1)

#include <include/sys/util.h>

0 if cond is true-ish; causes a compile error otherwise.

Function Documentation

◆ arithmetic_shift_right()

static int64_t arithmetic_shift_right	(	int64_t	value,
		uint8_t	shift
	)

inlinestatic

#include <include/sys/util.h>

Arithmetic shift right.

Parameters

value	value to shift
shift	number of bits to shift

Returns: value shifted right by shift; opened bit positions are filled with the sign bit

◆ bcd2bin()

static uint8_t bcd2bin ( uint8_t bcd )

inlinestatic

#include <include/sys/util.h>

Convert a binary coded decimal (BCD 8421) value to binary.

Parameters

bcd	BCD 8421 value to convert.

Returns: Binary representation of input value.

◆ bin2bcd()

static uint8_t bin2bcd ( uint8_t bin )

inlinestatic

#include <include/sys/util.h>

Convert a binary value to binary coded decimal (BCD 8421).

Parameters

bin	Binary value to convert.

Returns: BCD 8421 representation of input value.

◆ bin2hex()

size_t bin2hex	(	const uint8_t *	buf,
		size_t	buflen,
		char *	hex,
		size_t	hexlen
	)

#include <include/sys/util.h>

Convert a binary array into string representation.

Parameters

buf	The binary array to convert
buflen	The length of the binary array to convert
hex	Address of where to store the string representation.
hexlen	Size of the storage area for string representation.

Returns: The length of the converted string, or 0 if an error occurred.

◆ bytecpy()

static void bytecpy	(	void *	dst,
		const void *	src,
		size_t	size
	)

inlinestatic

#include <include/sys/util.h>

byte by byte memcpy.

Copy size bytes of src into dest. This is guaranteed to be done byte by byte.

Parameters

dst	Pointer to the destination memory.
src	Pointer to the source of the data.
size	The number of bytes to copy.

◆ byteswp()

static void byteswp	(	void *	a,
		void *	b,
		size_t	size
	)

inlinestatic

#include <include/sys/util.h>

byte by byte swap.

Swap size bytes between memory regions a and b. This is guaranteed to be done byte by byte.

Parameters

a	Pointer to the the first memory region.
b	Pointer to the the second memory region.
size	The number of bytes to swap.

◆ char2hex()

int char2hex	(	char	c,
		uint8_t *	x
	)

#include <include/sys/util.h>

Convert a single character into a hexadecimal nibble.

Parameters

c	The character to convert
x	The address of storage for the converted number.

Returns: Zero on success or (negative) error code otherwise.

◆ hex2bin()

size_t hex2bin	(	const char *	hex,
		size_t	hexlen,
		uint8_t *	buf,
		size_t	buflen
	)

#include <include/sys/util.h>

Convert a hexadecimal string into a binary array.

Parameters

hex	The hexadecimal string to convert
hexlen	The length of the hexadecimal string to convert.
buf	Address of where to store the binary data
buflen	Size of the storage area for binary data

Returns: The length of the binary array, or 0 if an error occurred.

◆ hex2char()

int hex2char	(	uint8_t	x,
		char *	c
	)

#include <include/sys/util.h>

Convert a single hexadecimal nibble into a character.

Parameters

c	The number to convert
x	The address of storage for the converted character.

Returns: Zero on success or (negative) error code otherwise.

◆ is_power_of_two()

static bool is_power_of_two ( unsigned int x )

inlinestatic

#include <include/sys/util.h>

Is x a power of two?

Parameters

x	value to check

Returns: true if x is a power of two, false otherwise

◆ u8_to_dec()

uint8_t u8_to_dec	(	char *	buf,
		uint8_t	buflen,
		uint8_t	value
	)

#include <include/sys/util.h>

Convert a uint8_t into a decimal string representation.

Convert a uint8_t value into its ASCII decimal string representation. The string is terminated if there is enough space in buf.

Parameters

buf	Address of where to store the string representation.
buflen	Size of the storage area for string representation.
value	The value to convert to decimal string

Returns: The length of the converted string (excluding terminator if any), or 0 if an error occurred.

◆ utf8_lcpy()

char * utf8_lcpy	(	char *	dst,
		const char *	src,
		size_t	n
	)

#include <include/sys/util.h>

Copies a UTF-8 encoded string from src to dst.

The resulting dst will always be NULL terminated, and the dst string will always be properly UTF-8 truncated.

Parameters

dst	The destination of the UTF-8 string.
src	The source string
n	The size of the `dst` buffer. Shall not be 0.

return Pointer to the dst

◆ utf8_trunc()

char * utf8_trunc ( char * utf8_str )

#include <include/sys/util.h>

Properly truncate a NULL-terminated UTF-8 string.

Take a NULL-terminated UTF-8 string and ensure that if the string has been truncated (by setting the NULL terminator) earlier by other means, that the string ends with a properly formatted UTF-8 character (1-4 bytes).

Example: char test_str[] = "€€€"; char trunc_utf8[8]; printf("Original : %s\n", test_str); // €€€ strncpy(trunc_utf8, test_str, sizeof(trunc_utf8)); trunc_utf8[sizeof(trunc_utf8) - 1] = '\0'; printf("Bad : %s\n", trunc_utf8); // €€� utf8_trunc(trunc_utf8); printf("Truncated: %s\n", trunc_utf8); // €€

Parameters

utf8_str NULL-terminated string

Returns: Pointer to the utf8_str

	Zephyr API Documentation 3.0.0 A Scalable Open Source RTOS
3.0.0

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ARRAY_SIZE

◆ BIT

◆ BIT64

◆ BIT64_MASK

◆ BIT_MASK

◆ BITS_PER_LONG

◆ ceiling_fraction

◆ CLAMP

◆ COND_CODE_0

◆ COND_CODE_1

◆ CONTAINER_OF

◆ EMPTY

◆ FIELD_GET

◆ FIELD_PREP

◆ FOR_EACH

◆ FOR_EACH_FIXED_ARG

◆ FOR_EACH_IDX

◆ FOR_EACH_IDX_FIXED_ARG

◆ FOR_EACH_NONEMPTY_TERM

◆ GB

◆ GENMASK

◆ GET_ARG_N

◆ GET_ARGS_LESS_N

◆ IDENTITY

◆ IF_ENABLED

◆ INT_TO_POINTER

◆ IS_ARRAY

◆ IS_EMPTY

◆ IS_ENABLED

◆ KB

◆ KHZ

◆ LIST_DROP_EMPTY

◆ LSB_GET

◆ MACRO_MAP_CAT

◆ MACRO_MAP_CAT_N

◆ MAX

◆ MB

◆ MHZ

◆ MIN

◆ NUM_VA_ARGS_LESS_1

◆ PART_OF_ARRAY

◆ POINTER_TO_INT

◆ POINTER_TO_UINT

◆ REVERSE_ARGS

◆ ROUND_DOWN

◆ ROUND_UP

◆ UINT_TO_POINTER

◆ UTIL_AND

◆ UTIL_LISTIFY

◆ UTIL_OR

◆ WB_DN

◆ WB_UP

◆ WRITE_BIT

◆ ZERO_OR_COMPILE_ERROR

Function Documentation

◆ arithmetic_shift_right()

◆ bcd2bin()

◆ bin2bcd()

◆ bin2hex()

◆ bytecpy()

◆ byteswp()

◆ char2hex()

◆ hex2bin()

◆ hex2char()

◆ is_power_of_two()

◆ u8_to_dec()

◆ utf8_lcpy()

◆ utf8_trunc()