kernel_defines.h File Reference

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 CONST
 A function declared as CONST is PURE and also not allowed to examine global memory. More...
 
#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]aArray to examine
Returns
The number of elements in the array a.

Definition at line 132 of file kernel_defines.h.

◆ CONST

#define CONST

A function declared as CONST is PURE and also not allowed to examine global memory.

I.e. a CONST function cannot even dereference a pointer parameter.

Definition at line 96 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]PTRpointer to a member
[in]TYPEa type name (a struct or union), container of PTR
[in]MEMBERname 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 236 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]ARRAYan array
[in]ELEMENTpointer 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();
}
#define IS_ACTIVE(macro)
Allows to verify a macro definition outside the preprocessor.
Parameters
[in]macroMacro 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 167 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 252 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]moduleModule to check
Returns
1 if the module is being used
0 if the module is not being used

Definition at line 178 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 109 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]majorMayor version of the release
[in]minorMinor version of the release
[in]patchPatch level of the release
[in]extraExtra version, user defined
Returns
A machine readable version variable

Definition at line 205 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 122 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 220 of file kernel_defines.h.