Common macros and compiler attributes/pragmas configuration. More...

Detailed Description

Common macros and compiler attributes/pragmas configuration.

Author: René Kijewski rene..nosp@m.kije.nosp@m.wski@.nosp@m.fu-b.nosp@m.erlin.nosp@m..de; Michel Rottleuthner miche.nosp@m.l.ro.nosp@m.ttleu.nosp@m.thne.nosp@m.r@haw.nosp@m.-ham.nosp@m.burg..nosp@m.de

Definition in file kernel_defines.h.

#include <stddef.h>
#include <stdint.h>

Include dependency graph for kernel_defines.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define	container_of(PTR, TYPE, MEMBER) ((TYPE ) ((char ) (PTR) - offsetof(TYPE, MEMBER)))
	Returns the container of a pointer to a member. More...

#define	index_of(ARRAY, ELEMENT) (((uintptr_t)(ELEMENT) - (uintptr_t)(ARRAY)) / sizeof((ARRAY)[0]))
	Returns the index of a pointer to an array element. More...

#define	NORETURN
	The NORETURN keyword tells the compiler to assume that the function cannot return.

#define	PURE
	The function has no effects except the return value and its return value depends only on the parameters and/or global variables. More...

#define	UNREACHABLE() do { /* nothing */ } while (1)
	Tell the compiler that this line of code cannot be reached. More...

#define	ARRAY_SIZE(a) (sizeof((a)) / sizeof((a)[0]))
	Calculate the number of elements in a static array. More...

#define	IS_ACTIVE(macro) __is_active(macro)
	Allows to verify a macro definition outside the preprocessor. More...

#define	IS_USED(module) IS_ACTIVE(module)
	Checks whether a module is being used or not. More...

#define	RIOT_VERSION_NUM(major, minor, patch, extra)
	Generates a 64 bit variable of a release version. More...

#define	WITHOUT_PEDANTIC(...)
	Disable -Wpedantic for the argument, but restore diagnostic settings afterwards. More...

#define	DECLARE_CONSTANT(identifier, const_expr) WITHOUT_PEDANTIC(enum { identifier = const_expr };)
	Declare a constant named `identifier` as anonymous `enum` that has the value `const_expr`. More...

#define	IS_CT_CONSTANT(expr) <IMPLEMENTATION>
	Check if given variable / expression is detected as compile time constant. More...

Macro Definition Documentation

◆ ARRAY_SIZE

#define ARRAY_SIZE ( a ) (sizeof((a)) / sizeof((a)[0]))

Calculate the number of elements in a static array.

Parameters

[in] a Array to examine

Returns: The number of elements in the array a.

Definition at line 120 of file kernel_defines.h.

◆ container_of

#define container_of	(	PTR,
		TYPE,
		MEMBER
	)	((TYPE ) ((char ) (PTR) - offsetof(TYPE, MEMBER)))

Returns the container of a pointer to a member.

For a struct TYPE with a member MEMBER, given a pointer PTR to TYPE::MEMBER this function returns a pointer to the instance of TYPE.

E.g. for struct my_struct_t { ...; something_t n; ... } my_struct;, &my_struct == container_of(&my_struct.n, struct my_struct_t, n).

Parameters

[in]	PTR	pointer to a member
[in]	TYPE	a type name (a struct or union), container of PTR
[in]	MEMBER	name of the member of TYPE which PTR points to

Returns: Pointer to the container of PTR.

Definition at line 62 of file kernel_defines.h.

◆ DECLARE_CONSTANT

#define DECLARE_CONSTANT	(	identifier,
		const_expr
	)	WITHOUT_PEDANTIC(enum { identifier = const_expr };)

Declare a constant named identifier as anonymous enum that has the value const_expr.

Warning: This is intended for internal use only

This turns any expression that is constant and known at compile time into a formal compile time constant. This allows e.g. using non-formally but still constant expressions in static_assert().

Definition at line 224 of file kernel_defines.h.

◆ index_of

#define index_of	(	ARRAY,
		ELEMENT
	)	(((uintptr_t)(ELEMENT) - (uintptr_t)(ARRAY)) / sizeof((ARRAY)[0]))

Returns the index of a pointer to an array element.

Parameters

[in]	ARRAY	an array
[in]	ELEMENT	pointer to an array element

Returns: Index of the element in the array

Definition at line 74 of file kernel_defines.h.

◆ IS_ACTIVE

#define IS_ACTIVE ( macro ) __is_active(macro)

Allows to verify a macro definition outside the preprocessor.

This macro is based on Linux's clever 'IS_BUILTIN' (https://github.com/torvalds/linux/blob/master/include/linux/kconfig.h). It takes a macro value that may be defined to 1 or not even defined (e.g. FEATURE_FOO) and then expands it to an expression that can be used in C code, either 1 or 0.

The advantage of using this is that the compiler sees all the code, so checks can be performed, sections that would not be executed are removed during optimization. For example:

if (IS_ACTIVE(FEATURE_FOO)) {
     do_something();
}

Parameters

[in] macro Macro to evaluate

Returns: 1 if the macro is defined to 1; 0 if the macro is not defined, of if it is defined to something else than 1.

Note: This should only be used when macros are defined as 1, it will not work if the macro value is, for example, (1) or 1U.; Although this may seem to work similarly to the preprocessor's 'defined', it is not entirely equal. If the given macro has been defined with no value, this will expand to 0. Also note that this is intended to be used with 'boolean' macros that act as switches, and usually will be defined as 1 or not defined.

Definition at line 155 of file kernel_defines.h.

◆ IS_CT_CONSTANT

#define IS_CT_CONSTANT ( expr ) <IMPLEMENTATION>

Check if given variable / expression is detected as compile time constant.

Note: This might return 0 on compile time constant expressions if the compiler is not able to prove the constness at the given level of optimization.

This will return 0 if the used compiler does not support this

Warning: This is intended for internal use only

This allows providing two different implementations in C, with one being more efficient if constant folding is used.

Definition at line 240 of file kernel_defines.h.

◆ IS_USED

#define IS_USED ( module ) IS_ACTIVE(module)

Checks whether a module is being used or not.

Can be used in C conditionals.

Parameters

[in] module Module to check

Returns: 1 if the module is being used; 0 if the module is not being used

Definition at line 166 of file kernel_defines.h.

◆ PURE

#define PURE

The function has no effects except the return value and its return value depends only on the parameters and/or global variables.

Such a function can be subject to common subexpression elimination and loop optimization just as an arithmetic operator would be.

Definition at line 97 of file kernel_defines.h.

◆ RIOT_VERSION_NUM

#define RIOT_VERSION_NUM	(	major,
		minor,
		patch,
		extra
	)

Value:

(((0ULL + major) << 48) + ((0ULL + minor) << 32) + \

((0ULL + patch) << 16) + (extra))

Generates a 64 bit variable of a release version.

Comparisons to this only apply to released branches

To define extra add a file EXTRAVERSION to the RIOT root with the content

RIOT_EXTRAVERSION = <extra>

with <extra> being the number of your local version. This can be useful if you are maintaining a downstream release to base further work on.

Warning: This is only intended to be used with external boards or modules. In-tree code must not make use of this macro.

Parameters

[in]	major	Mayor version of the release
[in]	minor	Minor version of the release
[in]	patch	Patch level of the release
[in]	extra	Extra version, user defined

Returns: A machine readable version variable

Definition at line 193 of file kernel_defines.h.

◆ UNREACHABLE

#define UNREACHABLE ( ) do { /* nothing */ } while (1)

Tell the compiler that this line of code cannot be reached.

Most useful in junction with NORETURN. Use this if the compiler cannot tell that e.g. an assembler instruction causes a longjmp, or a write causes a reboot.

Definition at line 110 of file kernel_defines.h.

◆ WITHOUT_PEDANTIC

#define WITHOUT_PEDANTIC ( ... )

Value:

    _Pragma("GCC diagnostic push") \
    _Pragma("GCC diagnostic ignored \"-Wpedantic\"") \
    __VA_ARGS__ \
    _Pragma("GCC diagnostic pop")

Disable -Wpedantic for the argument, but restore diagnostic settings afterwards.

Parameters

...	The expression that -Wpendantic should not apply to

Warning: This is intended for internal use only

This is particularly useful when declaring non-strictly conforming preprocessor macros, as the diagnostics need to be disabled where the macro is evaluated, not where the macro is declared.

Definition at line 208 of file kernel_defines.h.