nRF5 SDK v13.0.0
Macros | Functions
System Utilities API

Module to declare System Utilities API. More...

Macros

#define GET_PARENT_BY_FIELD(struct_type, field_name, field_pointer)   ((struct_type*)(void*)(((uint8_t*)field_pointer) - offsetof(struct_type, field_name)))
 Returns the pointer to the data structure. More...
 
#define IMP(x, y)   ( !(x) || (y) )
 Returns the implication of two given expressions x and y. More...
 
#define LL_MIN(x, y)   ( ((x) < (y)) ? (x) : (y) )
 Returns the minimum of two given expressions x and y.
 
#define LL_MAX(x, y)   ( ((x) > (y)) ? (x) : (y) )
 Returns the maximum of two given expressions x and y.
 
#define CEIL(a, b)   ((a) ? (((a) - 1U) / (b) + 1U) : 0U)
 Returns the quotient of a divided by b rounded upwards to the nearest integer.
 
#define ROUND(a, b)   ( ((a) + ((b) >> 1)) / (b) )
 Returns the quotient of a divided by b rounded to the nearest integer according to the standard arithmetic rules: if the fractional part of (a/b) is greater or equal to 0.5 then the result is rounded upwards; if the fractional part of (a/b) is less then 0.5 the result is rounded downwards. More...
 
#define BITMAP_DECLARE(name, size)   uint8_t name[CEIL(size, 8)]
 Declares a long bitmap named name of size bits. The size is rounded upwards to come a multiple of 8.
 
#define BITMAP_RESET(name)   memset((name), 0U, sizeof(name))
 Clears all bits in given bitmap.
 
#define BITMAP_ISSET(name, bit)   ( 0 != ((name)[(bit) >> 3] & (1 << ((bit) & 0x7))) )
 Returns the value of a bit at position bit in the long bitmap named name.
 
#define BITMAP_SET(name, bit)   (name)[(bit) >> 3] |= (1 << ((bit) & 0x7))
 Sets the bit at position bit in the long bitmap named name.
 
#define BITMAP_CLR(name, bit)   (name)[(bit) >> 3] &= ~(1 << ((bit) & 0x7))
 Clears the bit at position bit in the long bitmap named name.
 
#define BITMAP_ASSIGN(nameDst, nameSrc)   memcpy((nameDst), (nameSrc), sizeof(nameDst))
 Assigns the given bitmap with the second bitmap.
 
#define BITMAP_EQUAL(name1, name2)
 Compares two bitmaps and returns zero if they are equal. More...
 
#define LL_IS_POWER_OF_TWO(name)   ((0 != (name)) && (0 == ((name)&(name - 1))))
 Checks number. Return true if number is power of two.
 
#define IS_SUBSET_OF(mask, set)   ((mask) == ((set) & (mask)))
 Return True if mask is fully included into a given set and False otherwise.
 
#define BIT(pos)   (1UL << (pos))
 Creates a bit mask with single set bit on the specified position.
 
#define BIT_GET(val, pos)   ((((uint32_t)val) & BIT(pos)) != 0)
 Gets the given bit in the given value.
 
#define BIT_SET(val, pos, bit)
 Sets or clears the given bit in the given value. More...
 
#define POWER2(n)   (1ULL << (n))
 Returns two to the income power.
 
#define BIT_MASK(len)   (BIT(len) - 1UL)
 Creates a bit mask of specified length.
 
#define BIT_FIELD_MASK(start, len)   (BIT_MASK(len) << (start))
 Creates a bit field mask of specified length and start position.
 
#define BIT_FIELD_VALUE(value, start, len)   (((value) & BIT_MASK(len)) << (start))
 Creates a bit field mask of specified length, start position and value.
 
#define GET_BITFIELD_VALUE(bitmask, start, len)   (((bitmask) >> (start)) & BIT_MASK(len))
 Extracts a bit field value of specified start position and length.
 
#define SET_BITFIELD_VALUE(bitmask, start, len, value)   (bitmask = (bitmask & ~BIT_FIELD_MASK(start, len)) | BIT_FIELD_VALUE(value, start, len))
 Inserts a bit field value with specified start position and length.
 
#define BITMAP_MASK_GET(bitmap, bit, len)   GET_BITFIELD_VALUE(((uint32_t*)(bitmap))[(bit) >> 5], (bit) & 0x1F, len)
 Extracts a mask from a BITMAP. BITMAP MUST be aligned and mask length MUST be one of 2, 4, 8, 16, 32.
 
#define BITMAP_MASK_SET(bitmap, bit, len, value)   SET_BITFIELD_VALUE(((uint32_t*)(bitmap))[(bit) >> 5], (bit) & 0x1F, len, value)
 Sets up a mask to a BITMAP. BITMAP MUST be aligned and mask length MUST be one of 2, 4, 8, 16, 32.
 
#define VA_NARGS(...)   VA_NARGS_EVAL(__VA_ARGS__)
 Gets amount of the arguments.
 
#define VA_NARGS_EVAL(...)
 
#define VA_NARGS_IMPL(_________1,_2,_3,_4,_5,_6,_7, _8,_9,_10,_11,_12,_13,_14,_15, __16,_17,_18,_19,_20,_21,_22,_23, _24,_25,_26,_27,_28,_29,_30,_31, __32,_33,_34,_35,_36,_37,_38,_39, _40,_41,_42,_43,_44,_45,_46,_47, __48,_49,_50,_51,_52,_53,_54,_55, _56,_57,_58,_59,_60,_61,_62,_63, __64,_65,_66,_67,_68,_69,_70,_71, _72,_73,_74,_75,_76,_77,_78,_79, __80,_81,_82,_83,_84,_85,_86,_87, _88,_89,_90,_91,_92,_93,_94,_95, __96,_97,_98,_99, _100, _101, _102, _103, _104, _105, _106, _107, _108, _109, _110, _111, _112, _113, _114, _115, _116, _117, _118, _119, _120, _121, _122, _123, _124, _125, _126, _127, _128, _129, _130, _131, _132, _133, _134, _135, _136, _137, _138, _139, _140, _141, _142, _143, _144, _145, _146, _147, _148, _149, _150, _151, _152, _153, _154, _155, _156, _157, _158, _159, _160, _161, _162, _163, _164, _165, _166, _167, _168, _169, _170, _171, _172, _173, _174, _175, _176, _177, _178, _179, _180, _181, _182, _183, _184, _185, _186, _187, _188, _189, _190, _191, _192, _193, _194, _195, _196, _197, _198, _199, _200, _201, _202, _203, _204, _205, _206, _207, _208, _209, _210, _211, _212, _213, _214, _215, _216, _217, _218, _219, _220, _221, _222, _223, _224, _225, _226, _227, _228, _229, _230, _231, _232, _233, _234, _235, _236, _237, _238, _239, _240, _241, _242, _243, _244, _245, _246, _247, _248, _249, _250, _251, _252, _253, N,...)   N
 Helper macro. Gets amount of the arguments.
 
#define VA_NARGS_COMPILE_TIME(...)   ((uint8_t)(sizeof((uint8_t[]){ __VA_ARGS__ })/sizeof(uint8_t)))
 Gets amount of the arguments. Execute by compiler.
 
#define SWAP_XOR(a, b)   (((a) ^ (b)) && ((b) ^= (a) ^= (b), (a) ^= (b)))
 Swaps values.
 
#define COMPARE_WITH_THRESHOLD(a, b, threshold)   (((LL_MAX((a), (b)) - LL_MIN((a), (b))) < (threshold)) ? ((a) >= (b) ? 1 : 0) : ((a) > (b) ? 0 : 1))
 Compare two number and take care of overflow threshold limit.
 
#define ROUND_MASK(a)   ((a) - 1)
 
#define ROUND_UP(x, a)   (((x) + ROUND_MASK(a)) & ~ROUND_MASK(a))
 
#define ROUND_DOWN(x, a)   ((x) & ~ROUND_MASK(a))
 
#define DEREF_VOID_PTR_AS(x, y)   (*(x *)y)
 Dereferences input pointer y as a type x. More...
 
#define SIGN_EXTENSION(result, x, sign_pos)
 Extends some bit value to the left extending 2's complement value to 8-bit length. More...
 
#define SIGN_COMPRESSION(result, x, sign_pos)
 Clears some most significant bits of integer value reducing it precision. Name and interface of the macro emphasizes complementary action to SIGN_EXTENSION. More...
 
#define LSB_WORD(x)   ((uint8_t)(x & 0xFF))
 Returns least significant byte of word.
 
#define LSB_HWORD(x)   LSB_WORD(x)
 Returns least significant byte of halfword.
 
#define MSB_HWORD(x)   ((uint8_t)(x >> 8))
 Returns most significant byte of halfword.
 
#define ALIGN_VALUE   (sizeof(size_t))
 
#define __WEAK   __weak
 Compiler-independent definitions.
 
#define PACK   __attribute__ ((packed))
 
#define BEGIN_PACK
 
#define END_PACK
 
#define __ALIGN(n)   __align(n)
 

Functions

static void SWAP8 (uint8_t *const x, uint8_t *const y)
 Swaps values of two bytes. More...
 
static void SWAP32 (uint32_t *const x, uint32_t *const y)
 Swaps values of two double words (DWORD). More...
 
static void SWAP_ARRAYS (void *x, void *y, uint32_t length)
 Swaps values of two arrays. More...
 
static size_t bitmap_find_bit (uint8_t *p_bitmap, size_t bitmap_size, uint8_t bit_value)
 Find the first bit of the bitmap with the given value (one or zero, as specified). More...
 

Detailed Description

Module to declare System Utilities API.

The System Utilities module implements multiple useful macros and inlines for the whole stack. Including this header you will get access to GET_PARENT_BY_FIELD(), FIELD_SIZE() to work with complex structures, ARRAY_SIZE() for arrays, mathematics macros like IMP(), LL_MIN(), LL_MAX(), CEIL(), ROUND(), Bitmap helpers and many others. The variable arguments support macros are also defined here. Some SWAP routines are implemented by this module as well.

Macro Definition Documentation

#define BIT_SET (   val,
  pos,
  bit 
)
Value:
{ \
if (bit) \
{ \
val |= BIT(pos); \
} \
else \
{ \
val &= ~BIT(pos); \
} \
}

Sets or clears the given bit in the given value.

#define BITMAP_EQUAL (   name1,
  name2 
)
Value:
((sizeof(name1) == sizeof(name2)) && \
(memcmp((name1), (name2), sizeof(name1)) == 0))

Compares two bitmaps and returns zero if they are equal.

#define DEREF_VOID_PTR_AS (   x,
 
)    (*(x *)y)

Dereferences input pointer y as a type x.

Parameters
[in]xtype name.
[in]ypointer name.
#define GET_PARENT_BY_FIELD (   struct_type,
  field_name,
  field_pointer 
)    ((struct_type*)(void*)(((uint8_t*)field_pointer) - offsetof(struct_type, field_name)))

Returns the pointer to the data structure.

Parameters
[in]struct_typename of the parent structure
[in]field_namename of the structure field
[in]field_pointerpointer to the structure field
Return values
Pointerto the parent structure which includes the field.
#define IMP (   x,
 
)    ( !(x) || (y) )

Returns the implication of two given expressions x and y.

The implication means: if X==TRUE then Y==TRUE. The formula is: (X imp Y) = ((not X) or Y)

#define ROUND (   a,
 
)    ( ((a) + ((b) >> 1)) / (b) )

Returns the quotient of a divided by b rounded to the nearest integer according to the standard arithmetic rules: if the fractional part of (a/b) is greater or equal to 0.5 then the result is rounded upwards; if the fractional part of (a/b) is less then 0.5 the result is rounded downwards.

Note
Use this formula only for unsigned arguments. The formula is not compatible with the signed arguments: when a and b have different signs it gives incorrect result.
#define SIGN_COMPRESSION (   result,
  x,
  sign_pos 
)
Value:
do \
{ \
result = x & ((1 << (sign_pos + 1)) - 1); \
} while (0)

Clears some most significant bits of integer value reducing it precision. Name and interface of the macro emphasizes complementary action to SIGN_EXTENSION.

Parameters
[out]resultvariable, where result is store to.
[in]xinput value.
[in]sign_posan integer in range 2..6 specifying bit position of sign bit.
#define SIGN_EXTENSION (   result,
  x,
  sign_pos 
)
Value:
do \
{ \
result = x & (1 << sign_pos) ? \
x | (~((1 << (sign_pos + 1)) - 1)) : \
x & ((1 << (sign_pos + 1)) - 1); \
} while (0)

Extends some bit value to the left extending 2's complement value to 8-bit length.

Parameters
[out]resultvariable, where result is store to.
[in]xinput value.
[in]sign_posan integer in range 2..6 specifying bit position of sign bit.
#define VA_NARGS_EVAL (   ...)
Value:
VA_NARGS_IMPL(__VA_ARGS__, \
/* 255, 254, */ 253, 252, 251, 250, 249, 248, 247, 246, 245, 244, 243, 242, 241, 240, \
239, 238, 237, 236, 235, 234, 233, 232, 231, 230, 229, 228, 227, 226, 225, 224, \
223, 222, 221, 220, 219, 218, 217, 216, 215, 214, 213, 212, 211, 210, 209, 208, \
207, 206, 205, 204, 203, 202, 201, 200, 199, 198, 197, 196, 195, 194, 193, 192, \
191, 190, 189, 188, 187, 186, 185, 184, 183, 182, 181, 180, 179, 178, 177, 176, \
175, 174, 173, 172, 171, 170, 169, 168, 167, 166, 165, 164, 163, 162, 161, 160, \
159, 158, 157, 156, 155, 154, 153, 152, 151, 150, 149, 148, 147, 146, 145, 144, \
143, 142, 141, 140, 139, 138, 137, 136, 135, 134, 133, 132, 131, 130, 129, 128, \
127, 126, 125, 124, 123, 122, 121, 120, 119, 118, 117, 116, 115, 114, 113, 112, \
111, 110, 109, 108, 107, 106, 105, 104, 103, 102, 101, 100, 99, 98, 97, 96, \
095, 94, 93, 92, 91, 90, 89, 88, 87, 86, 85, 84, 83, 82, 81, 80, \
079, 78, 77, 76, 75, 74, 73, 72, 71, 70, 69, 68, 67, 66, 65, 64, \
063, 62, 61, 60, 59, 58, 57, 56, 55, 54, 53, 52, 51, 50, 49, 48, \
047, 46, 45, 44, 43, 42, 41, 40, 39, 38, 37, 36, 35, 34, 33, 32, \
031, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, \
015, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0)

Function Documentation

static size_t bitmap_find_bit ( uint8_t *  p_bitmap,
size_t  bitmap_size,
uint8_t  bit_value 
)
inlinestatic

Find the first bit of the bitmap with the given value (one or zero, as specified).

Parameters
[in]p_bitmapPointer to bitmap.
[in]bitmap_sizeNumber of bits in the bitmap.
[in]bit_valueThe bit value to find (one or zero).
Return values
Bitposition of the bit with specified value, or bitmap_size if no such bit was found.
static void SWAP32 ( uint32_t *const  x,
uint32_t *const  y 
)
inlinestatic

Swaps values of two double words (DWORD).

static void SWAP8 ( uint8_t *const  x,
uint8_t *const  y 
)
inlinestatic

Swaps values of two bytes.

static void SWAP_ARRAYS ( void *  x,
void *  y,
uint32_t  length 
)
inlinestatic

Swaps values of two arrays.

Parameters
[in,out]xarray pointer
[in,out]yarray pointer
[in]lengthamount of bytes to swap

Documentation feedback | Developer Zone | Subscribe | Updated