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,
			y
	)		(*(x *)y)

Dereferences input pointer y as a type x .

Parameters

[in]	x	type name.
[in]	y	pointer 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_type	name of the parent structure
[in]	field_name	name of the structure field
[in]	field_pointer	pointer to the structure field

Return values

Pointer

to the parent structure which includes the field.

#define IMP	(		x,
			y
	)		( !(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,
			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.

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]	result	variable, where result is store to.
[in]	x	input value.
[in]	sign_pos	an 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]	result	variable, where result is store to.
[in]	x	input value.
[in]	sign_pos	an 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 )

inline static

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

Parameters

[in]	p_bitmap	Pointer to bitmap.
[in]	bitmap_size	Number of bits in the bitmap.
[in]	bit_value	The bit value to find (one or zero).

Return values

Bit	position 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 )

inline static

Swaps values of two double words (DWORD).

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

inline static

Swaps values of two bytes.

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

inline static

Swaps values of two arrays.

Parameters

[in,out]	x	array pointer
[in,out]	y	array pointer
[in]	length	amount of bytes to swap