Zephyr API Documentation 4.0.0-rc3
A Scalable Open Source RTOS
|
Macros | |
#define | POINTER_TO_UINT(x) |
Cast x , a pointer, to an unsigned integer. | |
#define | UINT_TO_POINTER(x) |
Cast x , an unsigned integer, to a void* . | |
#define | POINTER_TO_INT(x) |
Cast x , a pointer, to a signed integer. | |
#define | INT_TO_POINTER(x) |
Cast x , a signed integer, to a void* . | |
#define | BITS_PER_BYTE (__CHAR_BIT__) |
Number of bits in a byte. | |
#define | BITS_PER_NIBBLE (__CHAR_BIT__ / 2) |
Number of bits in a nibble. | |
#define | NIBBLES_PER_BYTE (BITS_PER_BYTE / BITS_PER_NIBBLE) |
Number of nibbles in a byte. | |
#define | BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__) |
Number of bits in a long int. | |
#define | BITS_PER_LONG_LONG (__CHAR_BIT__ * __SIZEOF_LONG_LONG__) |
Number of bits in a long long int. | |
#define | GENMASK(h, l) |
Create a contiguous bitmask starting at bit position l and ending at position h . | |
#define | GENMASK64(h, l) |
Create a contiguous 64-bit bitmask starting at bit position l and ending at position h . | |
#define | ZERO_OR_COMPILE_ERROR(cond) |
0 if cond is true-ish; causes a compile error otherwise. | |
#define | IS_ARRAY(array) |
Zero if array has an array type, a compile error otherwise. | |
#define | ARRAY_SIZE(array) |
Number of elements in the given array . | |
#define | FLEXIBLE_ARRAY_DECLARE(type, name) |
Declare a flexible array member. | |
#define | IS_ARRAY_ELEMENT(array, ptr) |
Whether ptr is an element of array . | |
#define | ARRAY_INDEX(array, ptr) |
Index of ptr within array . | |
#define | PART_OF_ARRAY(array, ptr) |
Check if a pointer ptr lies within array . | |
#define | ARRAY_INDEX_FLOOR(array, ptr) |
Array-index of ptr within array , rounded down. | |
#define | ARRAY_FOR_EACH(array, idx) |
Iterate over members of an array using an index variable. | |
#define | ARRAY_FOR_EACH_PTR(array, ptr) |
Iterate over members of an array using a pointer. | |
#define | SAME_TYPE(a, b) |
Validate if two entities have a compatible type. | |
#define | CONTAINER_OF_VALIDATE(ptr, type, field) |
Validate CONTAINER_OF parameters, only applies to C mode. | |
#define | CONTAINER_OF(ptr, type, field) |
Get a pointer to a structure containing the element. | |
#define | SIZEOF_FIELD(type, member) |
Report the size of a struct field in bytes. | |
#define | CONCAT(...) |
Concatenate input arguments. | |
#define | IS_ALIGNED(ptr, align) |
Check if ptr is aligned to align alignment. | |
#define | ROUND_UP(x, align) |
Value of x rounded up to the next multiple of align . | |
#define | ROUND_DOWN(x, align) |
Value of x rounded down to the previous multiple of align . | |
#define | WB_UP(x) |
Value of x rounded up to the next word boundary. | |
#define | WB_DN(x) |
Value of x rounded down to the previous word boundary. | |
#define | DIV_ROUND_UP(n, d) |
Divide and round up. | |
#define | DIV_ROUND_CLOSEST(n, d) |
Divide and round to the nearest integer. | |
#define | MAX(a, b) |
Obtain the maximum of two values. | |
#define | MIN(a, b) |
Obtain the minimum of two values. | |
#define | CLAMP(val, low, high) |
Clamp a value to a given range. | |
#define | IN_RANGE(val, min, max) |
Checks if a value is within range. | |
#define | LOG2(x) |
Compute log2(x) | |
#define | LOG2CEIL(x) |
Compute ceil(log2(x)) | |
#define | NHPOT(x) |
Compute next highest power of two. | |
#define | KB(x) |
Number of bytes in x kibibytes. | |
#define | MB(x) |
Number of bytes in x mebibytes. | |
#define | GB(x) |
Number of bytes in x gibibytes. | |
#define | KHZ(x) |
Number of Hz in x kHz. | |
#define | MHZ(x) |
Number of Hz in x MHz. | |
#define | WAIT_FOR(expr, timeout, delay_stmt) |
Wait for an expression to return true with a timeout. | |
#define | BIT(n) |
Unsigned integer with bit position n set (signed in assembly language). | |
#define | BIT64(_n) |
64-bit unsigned integer with bit position _n set. | |
#define | WRITE_BIT(var, bit, set) |
Set or clear a bit depending on a boolean value. | |
#define | BIT_MASK(n) |
Bit mask with bits 0 through n-1 (inclusive) set, or 0 if n is 0. | |
#define | BIT64_MASK(n) |
64-bit bit mask with bits 0 through n-1 (inclusive) set, or 0 if n is 0. | |
#define | IS_POWER_OF_TWO(x) |
Check if a x is a power of two. | |
#define | IS_SHIFTED_BIT_MASK(m, s) |
Check if bits are set continuously from the specified bit. | |
#define | IS_BIT_MASK(m) |
Check if bits are set continuously from the LSB. | |
#define | LSB_GET(value) |
Extract the Least Significant Bit from value . | |
#define | FIELD_GET(mask, value) |
Extract a bitfield element from value corresponding to the field mask mask . | |
#define | FIELD_PREP(mask, value) |
Prepare a bitfield element using value with mask representing its field position and width. | |
#define | IS_ENABLED(config_macro) |
Check for macro definition in compiler-visible expressions. | |
#define | COND_CODE_1(_flag, _if_1_code, _else_code) |
Insert code depending on whether _flag expands to 1 or not. | |
#define | COND_CODE_0(_flag, _if_0_code, _else_code) |
Like COND_CODE_1() except tests if _flag is 0. | |
#define | IF_ENABLED(_flag, _code) |
Insert code if _flag is defined and equals 1. | |
#define | IF_DISABLED(_flag, _code) |
Insert code if _flag is not defined as 1. | |
#define | IS_EMPTY(...) |
Check if a macro has a replacement expression. | |
#define | IS_EQ(a, b) |
Like a == b , but does evaluation and short-circuiting at C preprocessor time. | |
#define | LIST_DROP_EMPTY(...) |
Remove empty arguments from list. | |
#define | EMPTY |
Macro with an empty expansion. | |
#define | IDENTITY(V) |
Macro that expands to its argument. | |
#define | GET_ARG_N(N, ...) |
Get nth argument from argument list. | |
#define | GET_ARGS_LESS_N(N, ...) |
Strips n first arguments from the argument list. | |
#define | UTIL_OR(a, b) |
Like a || b , but does evaluation and short-circuiting at C preprocessor time. | |
#define | UTIL_AND(a, b) |
Like a && b , but does evaluation and short-circuiting at C preprocessor time. | |
#define | UTIL_INC(x) |
UTIL_INC(x) for an integer literal x from 0 to 4095 expands to an integer literal whose value is x+1. | |
#define | UTIL_DEC(x) |
UTIL_DEC(x) for an integer literal x from 0 to 4095 expands to an integer literal whose value is x-1. | |
#define | UTIL_X2(y) |
UTIL_X2(y) for an integer literal y from 0 to 4095 expands to an integer literal whose value is 2y. | |
#define | LISTIFY(LEN, F, sep, ...) |
Generates a sequence of code with configurable separator. | |
#define | FOR_EACH(F, sep, ...) |
Call a macro F on each provided argument with a given separator between each call. | |
#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. | |
#define | FOR_EACH_IDX(F, sep, ...) |
Call macro F on each provided argument, with the argument's index as an additional parameter. | |
#define | FOR_EACH_FIXED_ARG(F, sep, fixed_arg, ...) |
Call macro F on each provided argument, with an additional fixed argument as a parameter. | |
#define | FOR_EACH_IDX_FIXED_ARG(F, sep, fixed_arg, ...) |
Calls macro F for each variable argument with an index and fixed argument. | |
#define | REVERSE_ARGS(...) |
Reverse arguments order. | |
#define | NUM_VA_ARGS_LESS_1(...) |
Number of arguments in the variable arguments list minus one. | |
#define | NUM_VA_ARGS(...) |
Number of arguments in the variable arguments list. | |
#define | MACRO_MAP_CAT(...) |
Mapping macro that pastes results together. | |
#define | MACRO_MAP_CAT_N(N, ...) |
Mapping macro that pastes a fixed number of results together. | |
Functions | |
static bool | is_power_of_two (unsigned int x) |
Is x a power of two? | |
static ALWAYS_INLINE bool | is_null_no_warn (void *p) |
Is p equal to NULL ? | |
static int64_t | arithmetic_shift_right (int64_t value, uint8_t shift) |
Arithmetic shift right. | |
static void | bytecpy (void *dst, const void *src, size_t size) |
byte by byte memcpy. | |
static void | byteswp (void *a, void *b, size_t size) |
byte by byte swap. | |
int | char2hex (char c, uint8_t *x) |
Convert a single character into a hexadecimal nibble. | |
int | hex2char (uint8_t x, char *c) |
Convert a single hexadecimal nibble into a character. | |
size_t | bin2hex (const uint8_t *buf, size_t buflen, char *hex, size_t hexlen) |
Convert a binary array into string representation. | |
size_t | hex2bin (const char *hex, size_t hexlen, uint8_t *buf, size_t buflen) |
Convert a hexadecimal string into a binary array. | |
static uint8_t | bcd2bin (uint8_t bcd) |
Convert a binary coded decimal (BCD 8421) value to binary. | |
static uint8_t | bin2bcd (uint8_t bin) |
Convert a binary value to binary coded decimal (BCD 8421). | |
uint8_t | u8_to_dec (char *buf, uint8_t buflen, uint8_t value) |
Convert a uint8_t into a decimal string representation. | |
static int32_t | sign_extend (uint32_t value, uint8_t index) |
Sign extend an 8, 16 or 32 bit value using the index bit as sign bit. | |
static int64_t | sign_extend_64 (uint64_t value, uint8_t index) |
Sign extend a 64 bit value using the index bit as sign bit. | |
char * | utf8_trunc (char *utf8_str) |
Properly truncate a NULL-terminated UTF-8 string. | |
char * | utf8_lcpy (char *dst, const char *src, size_t n) |
Copies a UTF-8 encoded string from src to dst . | |
static void | mem_xor_n (uint8_t *dst, const uint8_t *src1, const uint8_t *src2, size_t len) |
XOR n bytes. | |
static void | mem_xor_32 (uint8_t dst[4], const uint8_t src1[4], const uint8_t src2[4]) |
XOR 32 bits. | |
static void | mem_xor_128 (uint8_t dst[16], const uint8_t src1[16], const uint8_t src2[16]) |
XOR 128 bits. | |
#define ARRAY_FOR_EACH | ( | array, | |
idx ) |
#include <zephyr/sys/util.h>
Iterate over members of an array using an index variable.
array | the array in question |
idx | name of array index variable |
#define ARRAY_FOR_EACH_PTR | ( | array, | |
ptr ) |
#include <zephyr/sys/util.h>
Iterate over members of an array using a pointer.
array | the array in question |
ptr | pointer to an element of array |
#define ARRAY_INDEX | ( | array, | |
ptr ) |
#include <zephyr/sys/util.h>
Index of ptr
within array
.
With CONFIG_ASSERT=y
, this macro will trigger a runtime assertion when ptr
does not fall into the range of array
or when ptr
is not aligned to an array-element boundary of array
.
In C, passing a pointer as array
causes a compile error.
array | the array in question |
ptr | pointer to an element of array |
ptr
within array
, on success #define ARRAY_INDEX_FLOOR | ( | array, | |
ptr ) |
#include <zephyr/sys/util.h>
Array-index of ptr
within array
, rounded down.
This macro behaves much like ARRAY_INDEX with the notable difference that it accepts any ptr
in the range of array
rather than exclusively a ptr
aligned to an array-element boundary of array
.
With CONFIG_ASSERT=y
, this macro will trigger a runtime assertion when ptr
does not fall into the range of array
.
In C, passing a pointer as array
causes a compile error.
array | the array in question |
ptr | pointer to an element of array |
ptr
within array
, on success #define ARRAY_SIZE | ( | array | ) |
#include <zephyr/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 particularly meaningful in this case.
In C, passing a pointer as array
causes a compile error.
#define BIT | ( | n | ) |
#include <zephyr/sys/util_macro.h>
Unsigned integer with bit position n
set (signed in assembly language).
#define BIT64 | ( | _n | ) |
#include <zephyr/sys/util_macro.h>
64-bit unsigned integer with bit position _n
set.
#define BIT64_MASK | ( | n | ) |
#include <zephyr/sys/util_macro.h>
64-bit bit mask with bits 0 through n-1
(inclusive) set, or 0 if n
is 0.
#define BIT_MASK | ( | n | ) |
#include <zephyr/sys/util_macro.h>
Bit mask with bits 0 through n-1
(inclusive) set, or 0 if n
is 0.
#define BITS_PER_BYTE (__CHAR_BIT__) |
#include <zephyr/sys/util.h>
Number of bits in a byte.
#define BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__) |
#include <zephyr/sys/util.h>
Number of bits in a long int.
#define BITS_PER_LONG_LONG (__CHAR_BIT__ * __SIZEOF_LONG_LONG__) |
#include <zephyr/sys/util.h>
Number of bits in a long long int.
#define BITS_PER_NIBBLE (__CHAR_BIT__ / 2) |
#include <zephyr/sys/util.h>
Number of bits in a nibble.
#define CLAMP | ( | val, | |
low, | |||
high ) |
#include <zephyr/sys/util.h>
Clamp a value to a given range.
val | Value to be clamped. |
low | Lowest allowed value (inclusive). |
high | Highest allowed value (inclusive). |
#define CONCAT | ( | ... | ) |
#include <zephyr/sys/util.h>
Concatenate input arguments.
Concatenate provided tokens into a combined token during the preprocessor pass. This can be used to, for ex., build an identifier out of multiple parts, where one of those parts may be, for ex, a number, another macro, or a macro argument.
... | Tokens to concatencate |
#define COND_CODE_0 | ( | _flag, | |
_if_0_code, | |||
_else_code ) |
#include <zephyr/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.
_flag | evaluated flag |
_if_0_code | result if _flag expands to 0; must be in parentheses |
_else_code | result otherwise; must be in parentheses |
#define COND_CODE_1 | ( | _flag, | |
_if_1_code, | |||
_else_code ) |
#include <zephyr/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.
_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._flag | evaluated flag |
_if_1_code | result if _flag expands to 1; must be in parentheses |
_else_code | result otherwise; must be in parentheses |
#define CONTAINER_OF | ( | ptr, | |
type, | |||
field ) |
#include <zephyr/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
.
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 |
ptr
#define CONTAINER_OF_VALIDATE | ( | ptr, | |
type, | |||
field ) |
#include <zephyr/sys/util.h>
Validate CONTAINER_OF parameters, only applies to C mode.
#define DIV_ROUND_CLOSEST | ( | n, | |
d ) |
#include <zephyr/sys/util.h>
Divide and round to the nearest integer.
Example:
n | Numerator. |
d | Denominator. |
n
/ d
, rounded to the nearest integer. #define DIV_ROUND_UP | ( | n, | |
d ) |
#include <zephyr/sys/util.h>
Divide and round up.
Example:
n | Numerator. |
d | Denominator. |
n
/ d
, rounded up. #define EMPTY |
#include <zephyr/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.
#define FIELD_GET | ( | mask, | |
value ) |
#include <zephyr/sys/util_macro.h>
Extract a bitfield element from value
corresponding to the field mask mask
.
#define FIELD_PREP | ( | mask, | |
value ) |
#include <zephyr/sys/util_macro.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.
#define FLEXIBLE_ARRAY_DECLARE | ( | type, | |
name ) |
#include <zephyr/sys/util.h>
Declare a flexible array member.
This macro declares a flexible array member in a struct. The member is named name
and has type type
.
Since C99, flexible arrays are part of the C standard, but for historical reasons many places still use an older GNU extension that is declare zero length arrays.
Although zero length arrays are flexible arrays, we can't blindly replace [0] with [] because of some syntax limitations. This macro workaround these limitations.
It is specially useful for cases where flexible arrays are used in unions or are not the last element in the struct.
#define FOR_EACH | ( | F, | |
sep, | |||
... ) |
#include <zephyr/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;
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. |
#define FOR_EACH_FIXED_ARG | ( | F, | |
sep, | |||
fixed_arg, | |||
... ) |
#include <zephyr/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);
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. |
#define FOR_EACH_IDX | ( | F, | |
sep, | |||
... ) |
#include <zephyr/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;
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. |
#define FOR_EACH_IDX_FIXED_ARG | ( | F, | |
sep, | |||
fixed_arg, | |||
... ) |
#include <zephyr/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;
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. |
#define FOR_EACH_NONEMPTY_TERM | ( | F, | |
term, | |||
... ) |
#include <zephyr/sys/util_macro.h>
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:
FOO
, BAR
, and BAZ
expansions are empty and adding a comma manually (or not) between FOR_EACH() callsFOO
expands to nothing)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. |
#define GB | ( | x | ) |
#include <zephyr/sys/util.h>
Number of bytes in x
gibibytes.
#define GENMASK | ( | h, | |
l ) |
#include <zephyr/sys/util.h>
Create a contiguous bitmask starting at bit position l
and ending at position h
.
#define GENMASK64 | ( | h, | |
l ) |
#include <zephyr/sys/util.h>
Create a contiguous 64-bit bitmask starting at bit position l
and ending at position h
.
#define GET_ARG_N | ( | N, | |
... ) |
#include <zephyr/sys/util_macro.h>
Get nth argument from argument list.
N | Argument index to fetch. Counter from 1. |
... | Variable list of arguments from which one argument is returned. |
#define GET_ARGS_LESS_N | ( | N, | |
... ) |
#include <zephyr/sys/util_macro.h>
Strips n first arguments from the argument list.
N | Number of arguments to discard. |
... | Variable list of arguments. |
#define IDENTITY | ( | V | ) |
#include <zephyr/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.
V | any value |
#define IF_DISABLED | ( | _flag, | |
_code ) |
#include <zephyr/sys/util_macro.h>
Insert code if _flag
is not defined as 1.
This expands to nothing if _flag
is defined and equal to 1; it expands to _code
otherwise.
Example:
IF_DISABLED(CONFIG_FLAG, (uint32_t foo;))
If CONFIG_FLAG
isn't defined or different than 1, this expands to:
uint32_t foo;
and to nothing otherwise.
IF_DISABLED does the opposite of IF_ENABLED.
_flag | evaluated flag |
_code | result if _flag does not expand to 1; must be in parentheses |
#define IF_ENABLED | ( | _flag, | |
_code ) |
#include <zephyr/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
_flag | evaluated flag |
_code | result if _flag expands to 1; must be in parentheses |
#define IN_RANGE | ( | val, | |
min, | |||
max ) |
#include <zephyr/sys/util.h>
Checks if a value is within range.
val
is evaluated twice.val | Value to be checked. |
min | Lower bound (inclusive). |
max | Upper bound (inclusive). |
true | If value is within range |
false | If the value is not within range |
#define INT_TO_POINTER | ( | x | ) |
#include <zephyr/sys/util.h>
Cast x
, a signed integer, to a void*
.
#define IS_ALIGNED | ( | ptr, | |
align ) |
#include <zephyr/sys/util.h>
Check if ptr
is aligned to align
alignment.
#define IS_ARRAY | ( | array | ) |
#include <zephyr/sys/util.h>
Zero if array
has an array type, a compile error otherwise.
This macro is available only from C, not C++.
#define IS_ARRAY_ELEMENT | ( | array, | |
ptr ) |
#include <zephyr/sys/util.h>
Whether ptr
is an element of array
.
This macro can be seen as a slightly stricter version of PART_OF_ARRAY in that it also ensures that ptr
is aligned to an array-element boundary of array
.
In C, passing a pointer as array
causes a compile error.
array | the array in question |
ptr | the pointer to check |
ptr
is part of array
, 0 otherwise #define IS_BIT_MASK | ( | m | ) |
#include <zephyr/sys/util_macro.h>
Check if bits are set continuously from the LSB.
m | Check whether the bits are set continuously from LSB. |
#define IS_EMPTY | ( | ... | ) |
#include <zephyr/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.
... | macro to check for emptiness (may be __VA_ARGS__ ) |
#define IS_ENABLED | ( | config_macro | ) |
#include <zephyr/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.
Note: Use of IS_ENABLED in a #if
statement is discouraged as it doesn't provide any benefit vs plain #if defined()
config_macro | Macro to check |
config_macro
is defined to 1, 0 otherwise (including if config_macro
is not defined) #define IS_EQ | ( | a, | |
b ) |
#include <zephyr/sys/util_macro.h>
Like a == b
, but does evaluation and short-circuiting at C preprocessor time.
This however only works for integer literal from 0 to 4095.
#define IS_POWER_OF_TWO | ( | x | ) |
#include <zephyr/sys/util_macro.h>
Check if a x
is a power of two.
#define IS_SHIFTED_BIT_MASK | ( | m, | |
s ) |
#include <zephyr/sys/util_macro.h>
Check if bits are set continuously from the specified bit.
The macro is not dependent on the bit-width.
m | Check whether the bits are set continuously or not. |
s | Specify the lowest bit for that is continuously set bits. |
#define KB | ( | x | ) |
#define KHZ | ( | x | ) |
#define LIST_DROP_EMPTY | ( | ... | ) |
#include <zephyr/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
... | list to be processed |
#define LISTIFY | ( | LEN, | |
F, | |||
sep, | |||
... ) |
#include <zephyr/sys/util_macro.h>
Generates a sequence of code with configurable separator.
Example:
#define FOO(i, _) MY_PWM ## i { LISTIFY(PWM_COUNT, FOO, (,)) }
The above two lines expand to:
{ MY_PWM0 , MY_PWM1 }
LEN | The length of the sequence. Must be an integer literal less than 4095. |
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 LISTIFY are passed through to F . |
sep | Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator. |
#define LOG2 | ( | x | ) |
#include <zephyr/sys/util.h>
Compute log2(x)
x | An unsigned integral value to compute logarithm of (positive only) |
#define LOG2CEIL | ( | x | ) |
#include <zephyr/sys/util.h>
Compute ceil(log2(x))
x | An unsigned integral value |
#define LSB_GET | ( | value | ) |
#include <zephyr/sys/util_macro.h>
Extract the Least Significant Bit from value
.
#define MACRO_MAP_CAT | ( | ... | ) |
#include <zephyr/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_
... | Macro to expand on each argument, followed by its arguments. (The macro should take exactly one argument.) |
#define MACRO_MAP_CAT_N | ( | N, | |
... ) |
#include <zephyr/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.
N | Number of arguments to map |
... | Macro to expand on each argument, followed by its arguments. (The macro should take exactly one argument.) |
#define MAX | ( | a, | |
b ) |
#include <zephyr/sys/util.h>
Obtain the maximum of two values.
a | First value. |
b | Second value. |
a
and b
. #define MB | ( | x | ) |
#include <zephyr/sys/util.h>
Number of bytes in x
mebibytes.
#define MHZ | ( | x | ) |
#include <zephyr/sys/util.h>
Number of Hz in x
MHz.
#define MIN | ( | a, | |
b ) |
#include <zephyr/sys/util.h>
Obtain the minimum of two values.
a | First value. |
b | Second value. |
a
and b
. #define NHPOT | ( | x | ) |
#include <zephyr/sys/util.h>
Compute next highest power of two.
Equivalent to 2^ceil(log2(x))
x | An unsigned integral value |
#define NIBBLES_PER_BYTE (BITS_PER_BYTE / BITS_PER_NIBBLE) |
#include <zephyr/sys/util.h>
Number of nibbles in a byte.
#define NUM_VA_ARGS | ( | ... | ) |
#include <zephyr/sys/util_macro.h>
Number of arguments in the variable arguments list.
... | List of arguments |
#define NUM_VA_ARGS_LESS_1 | ( | ... | ) |
#include <zephyr/sys/util_macro.h>
Number of arguments in the variable arguments list minus one.
... | List of arguments |
#define PART_OF_ARRAY | ( | array, | |
ptr ) |
#include <zephyr/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).
array | an array |
ptr | a pointer |
ptr
is part of array
, 0 otherwise #define POINTER_TO_INT | ( | x | ) |
#define POINTER_TO_UINT | ( | x | ) |
#define REVERSE_ARGS | ( | ... | ) |
#include <zephyr/sys/util_macro.h>
Reverse arguments order.
... | Variable argument list. |
#define ROUND_DOWN | ( | x, | |
align ) |
#include <zephyr/sys/util.h>
Value of x
rounded down to the previous multiple of align
.
#define ROUND_UP | ( | x, | |
align ) |
#include <zephyr/sys/util.h>
Value of x
rounded up to the next multiple of align
.
#define SAME_TYPE | ( | a, | |
b ) |
#include <zephyr/sys/util.h>
Validate if two entities have a compatible type.
a | the first entity to be compared |
b | the second entity to be compared |
#define SIZEOF_FIELD | ( | type, | |
member ) |
#include <zephyr/sys/util.h>
Report the size of a struct field in bytes.
type | The structure containing the field of interest. |
member | The field to return the size of. |
#define UINT_TO_POINTER | ( | x | ) |
#include <zephyr/sys/util.h>
Cast x
, an unsigned integer, to a void*
.
#define UTIL_AND | ( | a, | |
b ) |
#include <zephyr/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.
#define UTIL_DEC | ( | x | ) |
#include <zephyr/sys/util_macro.h>
UTIL_DEC(x) for an integer literal x from 0 to 4095 expands to an integer literal whose value is x-1.
#define UTIL_INC | ( | x | ) |
#include <zephyr/sys/util_macro.h>
UTIL_INC(x) for an integer literal x from 0 to 4095 expands to an integer literal whose value is x+1.
#define UTIL_OR | ( | a, | |
b ) |
#include <zephyr/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.
#define UTIL_X2 | ( | y | ) |
#include <zephyr/sys/util_macro.h>
UTIL_X2(y) for an integer literal y from 0 to 4095 expands to an integer literal whose value is 2y.
#define WAIT_FOR | ( | expr, | |
timeout, | |||
delay_stmt ) |
#include <zephyr/sys/util.h>
Wait for an expression to return true with a timeout.
Spin on an expression with a timeout and optional delay between iterations
Commonly needed when waiting on hardware to complete an asynchronous request to read/write/initialize/reset, but useful for any expression.
expr | Truth expression upon which to poll, e.g.: XYZREG & XYZREG_EN |
timeout | Timeout to wait for in microseconds, e.g.: 1000 (1ms) |
delay_stmt | Delay statement to perform each poll iteration e.g.: NULL, k_yield(), k_msleep(1) or k_busy_wait(1) |
expr | As a boolean return, if false then it has timed out. |
#define WB_DN | ( | x | ) |
#include <zephyr/sys/util.h>
Value of x
rounded down to the previous word boundary.
#define WB_UP | ( | x | ) |
#include <zephyr/sys/util.h>
Value of x
rounded up to the next word boundary.
#define WRITE_BIT | ( | var, | |
bit, | |||
set ) |
#include <zephyr/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.
var | Variable to be altered |
bit | Bit number |
set | if 0, clears bit in var ; any other value sets bit |
#define ZERO_OR_COMPILE_ERROR | ( | cond | ) |
#include <zephyr/sys/util.h>
0 if cond
is true-ish; causes a compile error otherwise.
#include <zephyr/sys/util.h>
Arithmetic shift right.
value | value to shift |
shift | number of bits to shift |
value
shifted right by shift
; opened bit positions are filled with the sign bit #include <zephyr/sys/util.h>
Convert a binary coded decimal (BCD 8421) value to binary.
bcd | BCD 8421 value to convert. |
#include <zephyr/sys/util.h>
Convert a binary value to binary coded decimal (BCD 8421).
bin | Binary value to convert. |
#include <zephyr/sys/util.h>
Convert a binary array into string representation.
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. |
|
inlinestatic |
#include <zephyr/sys/util.h>
byte by byte memcpy.
Copy size
bytes of src
into dest
. This is guaranteed to be done byte by byte.
dst | Pointer to the destination memory. |
src | Pointer to the source of the data. |
size | The number of bytes to copy. |
|
inlinestatic |
#include <zephyr/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.
a | Pointer to the first memory region. |
b | Pointer to the second memory region. |
size | The number of bytes to swap. |
int char2hex | ( | char | c, |
uint8_t * | x ) |
#include <zephyr/sys/util.h>
Convert a single character into a hexadecimal nibble.
c | The character to convert |
x | The address of storage for the converted number. |
#include <zephyr/sys/util.h>
Convert a hexadecimal string into a binary array.
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 |
int hex2char | ( | uint8_t | x, |
char * | c ) |
#include <zephyr/sys/util.h>
Convert a single hexadecimal nibble into a character.
c | The number to convert |
x | The address of storage for the converted character. |
|
static |
#include <zephyr/sys/util.h>
Is p
equal to NULL
?
Some macros may need to check their arguments against NULL to support multiple use-cases, but NULL checks can generate warnings if such a macro is used in contexts where that particular argument can never be NULL.
The warnings can be triggered if: a) all macros are expanded (e.g. when using CONFIG_COMPILER_SAVE_TEMPS=y) or b) tracking of macro expansions are turned off (-ftrack-macro-expansion=0)
The warnings can be circumvented by using this inline function for doing the NULL check within the macro. The compiler is still able to optimize the NULL check out at a later stage.
p | Pointer to check |
p
is equal to NULL
, false otherwise #include <zephyr/sys/util.h>
Is x
a power of two?
x | value to check |
x
is a power of two, false otherwise
|
inlinestatic |
#include <zephyr/sys/util.h>
XOR 128 bits.
dst | Destination of where to store result. Shall be 128 bits. |
src1 | First source. Shall be 128 bits. |
src2 | Second source. Shall be 128 bits. |
|
inlinestatic |
#include <zephyr/sys/util.h>
XOR 32 bits.
dst | Destination of where to store result. Shall be 32 bits. |
src1 | First source. Shall be 32 bits. |
src2 | Second source. Shall be 32 bits. |
|
inlinestatic |
#include <zephyr/sys/util.h>
XOR n bytes.
dst | Destination of where to store result. Shall be len bytes. |
src1 | First source. Shall be len bytes. |
src2 | Second source. Shall be len bytes. |
len | Number of bytes to XOR. |
#include <zephyr/sys/util.h>
Sign extend an 8, 16 or 32 bit value using the index bit as sign bit.
value | The value to sign expand. |
index | 0 based bit index to sign bit (0 to 31) |
#include <zephyr/sys/util.h>
Sign extend a 64 bit value using the index bit as sign bit.
value | The value to sign expand. |
index | 0 based bit index to sign bit (0 to 63) |
#include <zephyr/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.
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 |
char * utf8_lcpy | ( | char * | dst, |
const char * | src, | ||
size_t | n ) |
#include <zephyr/sys/util.h>
Copies a UTF-8 encoded string from src
to dst
.
The resulting dst
will always be NULL terminated if n
is larger than 0, and the dst
string will always be properly UTF-8 truncated.
dst | The destination of the UTF-8 string. |
src | The source string |
n | The size of the dst buffer. Maximum number of characters copied is n - 1. If 0 nothing will be done, and the dst will not be NULL terminated. |
dst
char * utf8_trunc | ( | char * | utf8_str | ) |
#include <zephyr/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); // €€
utf8_str | NULL-terminated string |
utf8_str