Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
util.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2011-2014, Wind River Systems, Inc.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
13
14#ifndef ZEPHYR_INCLUDE_SYS_UTIL_H_
15#define ZEPHYR_INCLUDE_SYS_UTIL_H_
16
18#include <zephyr/toolchain.h>
19
20/* needs to be outside _ASMLANGUAGE so 'true' and 'false' can turn
21 * into '1' and '0' for asm or linker scripts
22 */
23#include <stdbool.h>
24
25#ifndef _ASMLANGUAGE
26
27#include <zephyr/sys/__assert.h>
28#include <zephyr/types.h>
29#include <stddef.h>
30#include <stdint.h>
31#include <string.h>
32
34#define NUM_BITS(t) (sizeof(t) * BITS_PER_BYTE)
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
47
49#define POINTER_TO_UINT(x) ((uintptr_t)(x))
51#define UINT_TO_POINTER(x) ((void *)(uintptr_t)(x))
53#define POINTER_TO_INT(x) ((intptr_t)(x))
55#define INT_TO_POINTER(x) ((void *)(intptr_t)(x))
56
57#if !(defined(__CHAR_BIT__) && defined(__SIZEOF_LONG__) && defined(__SIZEOF_LONG_LONG__))
58#error Missing required predefined macros for BITS_PER_LONG calculation
59#endif
60
62#define BITS_PER_BYTE (__CHAR_BIT__)
63
65#define BITS_PER_NIBBLE (__CHAR_BIT__ / 2)
66
68#define NIBBLES_PER_BYTE (BITS_PER_BYTE / BITS_PER_NIBBLE)
69
71#define BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__)
72
74#define BITS_PER_LONG_LONG (__CHAR_BIT__ * __SIZEOF_LONG_LONG__)
75
77#define ZERO_OR_COMPILE_ERROR(cond) ((int)sizeof(char[1 - (2 * !(cond))]) - 1)
78
79#if defined(__cplusplus)
80
81/* The built-in function used below for type checking in C is not
82 * supported by GNU C++.
83 */
84#define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
85
86#else /* __cplusplus */
87
93#define IS_ARRAY(array) \
94 ZERO_OR_COMPILE_ERROR( \
95 !__builtin_types_compatible_p(__typeof__(array), __typeof__(&(array)[0])))
96
106#define ARRAY_SIZE(array) ((size_t)(IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))
107
108#endif /* __cplusplus */
109
127#define FLEXIBLE_ARRAY_DECLARE(type, name) \
128 struct { \
129 struct { \
130 } __unused_##name; \
131 type name[]; \
132 }
133
148#define IS_ARRAY_ELEMENT(array, ptr) \
149 ((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) && \
150 POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]) && \
151 (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) % sizeof((array)[0]) == 0)
152
167#define ARRAY_INDEX(array, ptr) \
168 ({ \
169 __ASSERT_NO_MSG(IS_ARRAY_ELEMENT(array, ptr)); \
170 (__typeof__((array)[0]) *)(ptr) - (array); \
171 })
172
183#define PART_OF_ARRAY(array, ptr) \
184 ((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) && \
185 POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]))
186
204#define ARRAY_INDEX_FLOOR(array, ptr) \
205 ({ \
206 __ASSERT_NO_MSG(PART_OF_ARRAY(array, ptr)); \
207 (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) / sizeof((array)[0]); \
208 })
209
216#define ARRAY_FOR_EACH(array, idx) for (size_t idx = 0; (idx) < ARRAY_SIZE(array); ++(idx))
217
224#define ARRAY_FOR_EACH_PTR(array, ptr) \
225 for (__typeof__(*(array)) *ptr = (array); (size_t)((ptr) - (array)) < ARRAY_SIZE(array); \
226 ++(ptr))
227
235#define SAME_TYPE(a, b) __builtin_types_compatible_p(__typeof__(a), __typeof__(b))
236
240#ifndef __cplusplus
241#define CONTAINER_OF_VALIDATE(ptr, type, field) \
242 BUILD_ASSERT(SAME_TYPE(*(ptr), ((type *)0)->field) || SAME_TYPE(*(ptr), void), \
243 "pointer type mismatch in CONTAINER_OF");
244#else
245#define CONTAINER_OF_VALIDATE(ptr, type, field)
246#endif
247
269#define CONTAINER_OF(ptr, type, field) \
270 ({ \
271 CONTAINER_OF_VALIDATE(ptr, type, field) \
272 ((type *)(((char *)(ptr)) - offsetof(type, field))); \
273 })
274
283#define SIZEOF_FIELD(type, member) sizeof((((type *)0)->member))
284
296#define CONCAT(...) UTIL_CAT(_CONCAT_, NUM_VA_ARGS_LESS_1(__VA_ARGS__))(__VA_ARGS__)
297
301#define IS_ALIGNED(ptr, align) (((uintptr_t)(ptr)) % (align) == 0)
302
306#define ROUND_UP(x, align) \
307 ((((unsigned long)(x) + ((unsigned long)(align) - 1)) / (unsigned long)(align)) * \
308 (unsigned long)(align))
309
313#define ROUND_DOWN(x, align) \
314 (((unsigned long)(x) / (unsigned long)(align)) * (unsigned long)(align))
315
317#define WB_UP(x) ROUND_UP(x, sizeof(void *))
318
320#define WB_DN(x) ROUND_DOWN(x, sizeof(void *))
321
336#define DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))
337
353#define DIV_ROUND_CLOSEST(n, d) \
354 (((((__typeof__(n))-1) < 0) && (((__typeof__(d))-1) < 0) && ((n) < 0) ^ ((d) < 0)) \
355 ? ((n) - ((d) / 2)) / (d) \
356 : ((n) + ((d) / 2)) / (d))
357
361#define Z_INTERNAL_MAX(a, b) (((a) > (b)) ? (a) : (b))
362#define Z_INTERNAL_MIN(a, b) (((a) < (b)) ? (a) : (b))
366
367#ifndef MAX
379#define MAX(a, b) Z_INTERNAL_MAX(a, b)
380#endif
381
382#ifndef MIN
394#define MIN(a, b) Z_INTERNAL_MIN(a, b)
395#endif
396
397#ifndef MAX_FROM_LIST
403#define Z_MAX_1(a) a
404
414#define Z_MAX_2(a, b) ((a) > (b) ? (a) : (b))
415
424#define Z_MAX_3(a, b, c) Z_MAX_2(a, Z_MAX_2(b, c))
425
435#define Z_MAX_4(a, b, c, d) Z_MAX_2(Z_MAX_2(a, b), Z_MAX_2(c, d))
436
441#define Z_MAX_5(a, b, c, d, e) Z_MAX_2(Z_MAX_4(a, b, c, d), e)
442
447#define Z_MAX_6(a, b, c, d, e, f) Z_MAX_2(Z_MAX_5(a, b, c, d, e), f)
448
453#define Z_MAX_7(a, b, c, d, e, f, g) Z_MAX_2(Z_MAX_6(a, b, c, d, e, f), g)
454
459#define Z_MAX_8(a, b, c, d, e, f, g, h) Z_MAX_2(Z_MAX_7(a, b, c, d, e, f, g), h)
460
465#define Z_MAX_9(a, b, c, d, e, f, g, h, i) Z_MAX_2(Z_MAX_8(a, b, c, d, e, f, g, h), i)
466
471#define Z_MAX_10(a, b, c, d, e, f, g, h, i, j) Z_MAX_2(Z_MAX_9(a, b, c, d, e, f, g, h, i), j)
472
495#define Z_GET_MAX_MACRO(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10, NAME, ...) NAME
496
513#define MAX_FROM_LIST(...) \
514 Z_GET_MAX_MACRO(__VA_ARGS__, Z_MAX_10, Z_MAX_9, Z_MAX_8, Z_MAX_7, Z_MAX_6, Z_MAX_5, \
515 Z_MAX_4, Z_MAX_3, Z_MAX_2, Z_MAX_1)(__VA_ARGS__)
516#endif
517
518#ifndef CLAMP
531#define CLAMP(val, low, high) (((val) <= (low)) ? (low) : Z_INTERNAL_MIN(val, high))
532#endif
533
546#define IN_RANGE(val, min, max) ((val) >= (min) && (val) <= (max))
547
562int bitmask_find_gap(uint32_t mask, size_t num_bits, size_t total_bits, bool first_match);
563
569static inline bool is_power_of_two(unsigned int x)
570{
571 return IS_POWER_OF_TWO(x);
572}
573
593static ALWAYS_INLINE bool is_null_no_warn(void *p)
594{
595 return p == NULL;
596}
597
606{
607 int64_t sign_ext;
608
609 if (shift == 0U) {
610 return value;
611 }
612
613 /* extract sign bit */
614 sign_ext = (value >> 63) & 1;
615
616 /* make all bits of sign_ext be the same as the value's sign bit */
617 sign_ext = -sign_ext;
618
619 /* shift value and fill opened bit positions with sign bit */
620 return (value >> shift) | (sign_ext << (64 - shift));
621}
622
632static inline void bytecpy(void *dst, const void *src, size_t size)
633{
634 size_t i;
635
636 for (i = 0; i < size; ++i) {
637 ((volatile uint8_t *)dst)[i] = ((volatile const uint8_t *)src)[i];
638 }
639}
640
651static inline void byteswp(void *a, void *b, size_t size)
652{
653 uint8_t t;
654 uint8_t *aa = (uint8_t *)a;
655 uint8_t *bb = (uint8_t *)b;
656
657 for (; size > 0; --size) {
658 t = *aa;
659 *aa++ = *bb;
660 *bb++ = t;
661 }
662}
663
672int char2hex(char c, uint8_t *x);
673
682int hex2char(uint8_t x, char *c);
683
694size_t bin2hex(const uint8_t *buf, size_t buflen, char *hex, size_t hexlen);
695
706size_t hex2bin(const char *hex, size_t hexlen, uint8_t *buf, size_t buflen);
707
715static inline uint8_t bcd2bin(uint8_t bcd)
716{
717 return ((10 * (bcd >> 4)) + (bcd & 0x0F));
718}
719
727static inline uint8_t bin2bcd(uint8_t bin)
728{
729 return (((bin / 10) << 4) | (bin % 10));
730}
731
745uint8_t u8_to_dec(char *buf, uint8_t buflen, uint8_t value);
746
753static inline int32_t sign_extend(uint32_t value, uint8_t index)
754{
755 __ASSERT_NO_MSG(index <= 31);
756
757 uint8_t shift = 31 - index;
758
759 return (int32_t)(value << shift) >> shift;
760}
761
768static inline int64_t sign_extend_64(uint64_t value, uint8_t index)
769{
770 __ASSERT_NO_MSG(index <= 63);
771
772 uint8_t shift = 63 - index;
773
774 return (int64_t)(value << shift) >> shift;
775}
776
777#define __z_log2d(x) (32 - __builtin_clz(x) - 1)
778#define __z_log2q(x) (64 - __builtin_clzll(x) - 1)
779#define __z_log2(x) (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))
780
791#define LOG2(x) ((x) < 1 ? -1 : __z_log2(x))
792
803#define LOG2CEIL(x) ((x) <= 1 ? 0 : __z_log2((x) - 1) + 1)
804
817#define NHPOT(x) ((x) < 1 ? 1 : ((x) > (1ULL << 63) ? 0 : 1ULL << LOG2CEIL(x)))
818
831#define Z_DETECT_POINTER_OVERFLOW(addr, buflen) \
832 (((buflen) != 0) && ((UINTPTR_MAX - (uintptr_t)(addr)) <= ((uintptr_t)((buflen) - 1))))
833
842static inline void mem_xor_n(uint8_t *dst, const uint8_t *src1, const uint8_t *src2, size_t len)
843{
844 while (len--) {
845 *dst++ = *src1++ ^ *src2++;
846 }
847}
848
856static inline void mem_xor_32(uint8_t dst[4], const uint8_t src1[4], const uint8_t src2[4])
857{
858 mem_xor_n(dst, src1, src2, 4U);
859}
860
868static inline void mem_xor_128(uint8_t dst[16], const uint8_t src1[16], const uint8_t src2[16])
869{
870 mem_xor_n(dst, src1, src2, 16);
871}
872
884static inline bool util_memeq(const void *m1, const void *m2, size_t n)
885{
886 return memcmp(m1, m2, n) == 0;
887}
888
902static inline bool util_eq(const void *m1, size_t len1, const void *m2, size_t len2)
903{
904 return len1 == len2 && (m1 == m2 || util_memeq(m1, m2, len1));
905}
906
913static inline size_t sys_count_bits(const void *value, size_t len)
914{
915 size_t cnt = 0U;
916 size_t i = 0U;
917
918#ifdef POPCOUNT
919 for (; i < len / sizeof(unsigned int); i++) {
920 unsigned int val;
921 (void)memcpy(&val, (const uint8_t *)value + i * sizeof(unsigned int),
922 sizeof(unsigned int));
923
924 cnt += POPCOUNT(val);
925 }
926 i *= sizeof(unsigned int); /* convert to a uint8_t index for the remainder (if any) */
927#endif
928
929 for (; i < len; i++) {
930 uint8_t value_u8 = ((const uint8_t *)value)[i];
931
932 /* Implements Brian Kernighan’s Algorithm to count bits */
933 while (value_u8) {
934 value_u8 &= (value_u8 - 1);
935 cnt++;
936 }
937 }
938
939 return cnt;
940}
941
951#define SYS_SIGN(x) (((x) > 0) - ((x) < 0))
952
963#define sys_gcd(a, b) sys_gcd_s(a, b)
964
968static ALWAYS_INLINE uint32_t sys_gcd_u(uint32_t a, uint32_t b)
969{
970 uint32_t c;
971
972 if (a == 0) {
973 return b;
974 }
975
976 if (b == 0) {
977 return a;
978 }
979
980 c = a % b;
981 while (c != 0) {
982 a = b;
983 b = c;
984 c = a % b;
985 }
986
987 return b;
988}
989
990static ALWAYS_INLINE uint32_t sys_gcd_s(int64_t a, int64_t b)
991{
992 return sys_gcd_u(a < 0 ? -(uint32_t)a : (uint32_t)a, b < 0 ? -(uint32_t)b : (uint32_t)b);
993}
997
1007#define sys_lcm(a, b) sys_lcm_s(a, b)
1008
1012static ALWAYS_INLINE uint64_t sys_lcm_u(uint32_t a, uint32_t b)
1013{
1014 if (a == 0 || b == 0) {
1015 return 0;
1016 }
1017
1018 return (uint64_t)(a / sys_gcd_u(a, b)) * (uint64_t)b;
1019}
1020
1021static ALWAYS_INLINE uint64_t sys_lcm_s(int64_t a, int64_t b)
1022{
1023 return sys_lcm_u(a < 0 ? -(uint32_t)a : (uint32_t)a, b < 0 ? -(uint32_t)b : (uint32_t)b);
1024}
1028
1029#ifdef __cplusplus
1030}
1031#endif
1032
1033/* This file must be included at the end of the !_ASMLANGUAGE guard.
1034 * It depends on macros defined in this file above which cannot be forward declared.
1035 */
1036#include <zephyr/sys/time_units.h>
1037
1038#endif /* !_ASMLANGUAGE */
1039
1041#ifdef _LINKER
1042/* This is used in linker scripts so need to avoid type casting there */
1043#define KB(x) ((x) << 10)
1044#else
1045#define KB(x) (((size_t)(x)) << 10)
1046#endif
1048#define MB(x) (KB(x) << 10)
1050#define GB(x) (MB(x) << 10)
1051
1053#define KHZ(x) ((x) * 1000)
1055#define MHZ(x) (KHZ(x) * 1000)
1056
1069#if defined(CONFIG_ARCH_POSIX)
1070#define Z_SPIN_DELAY(t) k_busy_wait(t)
1071#else
1072#define Z_SPIN_DELAY(t)
1073#endif
1074
1090#define WAIT_FOR(expr, timeout, delay_stmt) \
1091 ({ \
1092 uint32_t _wf_cycle_count = k_us_to_cyc_ceil32(timeout); \
1093 uint32_t _wf_start = k_cycle_get_32(); \
1094 bool _wf_ret; \
1095 do { \
1096 bool _wf_timed_out = (_wf_cycle_count <= (k_cycle_get_32() - _wf_start)); \
1097 _wf_ret = (expr); \
1098 if (_wf_ret || _wf_timed_out) { \
1099 break; \
1100 } \
1101 ({ delay_stmt; }); \
1102 Z_SPIN_DELAY(10); \
1103 } while (true); \
1104 (_wf_ret); \
1105 })
1106
1114#ifdef CONFIG_ZTEST
1115#define ZTESTABLE_STATIC
1116#else
1117#define ZTESTABLE_STATIC static
1118#endif
1119
1123
1124#endif /* ZEPHYR_INCLUDE_SYS_UTIL_H_ */
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.
Definition util.h:768
static int64_t arithmetic_shift_right(int64_t value, uint8_t shift)
Arithmetic shift right.
Definition util.h:605
static size_t sys_count_bits(const void *value, size_t len)
Returns the number of bits set in a value.
Definition util.h:913
size_t hex2bin(const char *hex, size_t hexlen, uint8_t *buf, size_t buflen)
Convert a hexadecimal string into a binary array.
static void bytecpy(void *dst, const void *src, size_t size)
byte by byte memcpy.
Definition util.h:632
#define IS_POWER_OF_TWO(x)
Check if a x is a power of two.
Definition util_macro.h:95
static ALWAYS_INLINE bool is_null_no_warn(void *p)
Is p equal to NULL?
Definition util.h:593
static void mem_xor_128(uint8_t dst[16], const uint8_t src1[16], const uint8_t src2[16])
XOR 128 bits.
Definition util.h:868
static uint8_t bin2bcd(uint8_t bin)
Convert a binary value to binary coded decimal (BCD 8421).
Definition util.h:727
static void mem_xor_32(uint8_t dst[4], const uint8_t src1[4], const uint8_t src2[4])
XOR 32 bits.
Definition util.h:856
static void byteswp(void *a, void *b, size_t size)
byte by byte swap.
Definition util.h:651
static void mem_xor_n(uint8_t *dst, const uint8_t *src1, const uint8_t *src2, size_t len)
XOR n bytes.
Definition util.h:842
int hex2char(uint8_t x, char *c)
Convert a single hexadecimal nibble into a character.
static uint8_t bcd2bin(uint8_t bcd)
Convert a binary coded decimal (BCD 8421) value to binary.
Definition util.h:715
int char2hex(char c, uint8_t *x)
Convert a single character into a hexadecimal nibble.
int bitmask_find_gap(uint32_t mask, size_t num_bits, size_t total_bits, bool first_match)
Find number of contiguous bits which are not set in the bit mask (32 bits).
uint8_t u8_to_dec(char *buf, uint8_t buflen, uint8_t value)
Convert a uint8_t into a decimal string representation.
static bool util_eq(const void *m1, size_t len1, const void *m2, size_t len2)
Compare memory areas and their length.
Definition util.h:902
static bool util_memeq(const void *m1, const void *m2, size_t n)
Compare memory areas.
Definition util.h:884
static bool is_power_of_two(unsigned int x)
Is x a power of two?
Definition util.h:569
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.
Definition util.h:753
size_t bin2hex(const uint8_t *buf, size_t buflen, char *hex, size_t hexlen)
Convert a binary array into string representation.
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__INT32_TYPE__ int32_t
Definition stdint.h:74
__UINT64_TYPE__ uint64_t
Definition stdint.h:91
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__INT64_TYPE__ int64_t
Definition stdint.h:75
int memcmp(const void *m1, const void *m2, size_t n)
void * memcpy(void *ZRESTRICT d, const void *ZRESTRICT s, size_t n)
Macros to abstract toolchain specific capabilities.
Macro utilities.