Zephyr API Documentation  3.7.0-rc3
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
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
33#define NUM_BITS(t) (sizeof(t) * 8)
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
48#define POINTER_TO_UINT(x) ((uintptr_t) (x))
50#define UINT_TO_POINTER(x) ((void *) (uintptr_t) (x))
52#define POINTER_TO_INT(x) ((intptr_t) (x))
54#define INT_TO_POINTER(x) ((void *) (intptr_t) (x))
55
56#if !(defined(__CHAR_BIT__) && defined(__SIZEOF_LONG__) && defined(__SIZEOF_LONG_LONG__))
57# error Missing required predefined macros for BITS_PER_LONG calculation
58#endif
59
61#define BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__)
62
64#define BITS_PER_LONG_LONG (__CHAR_BIT__ * __SIZEOF_LONG_LONG__)
65
70#define GENMASK(h, l) \
71 (((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
72
77#define GENMASK64(h, l) \
78 (((~0ULL) - (1ULL << (l)) + 1) & (~0ULL >> (BITS_PER_LONG_LONG - 1 - (h))))
79
81#define LSB_GET(value) ((value) & -(value))
82
87#define FIELD_GET(mask, value) (((value) & (mask)) / LSB_GET(mask))
88
94#define FIELD_PREP(mask, value) (((value) * LSB_GET(mask)) & (mask))
95
97#define ZERO_OR_COMPILE_ERROR(cond) ((int) sizeof(char[1 - 2 * !(cond)]) - 1)
98
99#if defined(__cplusplus)
100
101/* The built-in function used below for type checking in C is not
102 * supported by GNU C++.
103 */
104#define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
105
106#else /* __cplusplus */
107
113#define IS_ARRAY(array) \
114 ZERO_OR_COMPILE_ERROR( \
115 !__builtin_types_compatible_p(__typeof__(array), \
116 __typeof__(&(array)[0])))
117
127#define ARRAY_SIZE(array) \
128 ((size_t) (IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))
129
130#endif /* __cplusplus */
131
146#define IS_ARRAY_ELEMENT(array, ptr) \
147 ((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) && \
148 POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]) && \
149 (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) % sizeof((array)[0]) == 0)
150
165#define ARRAY_INDEX(array, ptr) \
166 ({ \
167 __ASSERT_NO_MSG(IS_ARRAY_ELEMENT(array, ptr)); \
168 (__typeof__((array)[0]) *)(ptr) - (array); \
169 })
170
181#define PART_OF_ARRAY(array, ptr) \
182 ((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) && \
183 POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]))
184
202#define ARRAY_INDEX_FLOOR(array, ptr) \
203 ({ \
204 __ASSERT_NO_MSG(PART_OF_ARRAY(array, ptr)); \
205 (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) / sizeof((array)[0]); \
206 })
207
214#define ARRAY_FOR_EACH(array, idx) for (size_t idx = 0; (idx) < ARRAY_SIZE(array); ++(idx))
215
222#define ARRAY_FOR_EACH_PTR(array, ptr) \
223 for (__typeof__(*(array)) *ptr = (array); (size_t)((ptr) - (array)) < ARRAY_SIZE(array); \
224 ++(ptr))
225
233#define SAME_TYPE(a, b) __builtin_types_compatible_p(__typeof__(a), __typeof__(b))
234
238#ifndef __cplusplus
239#define CONTAINER_OF_VALIDATE(ptr, type, field) \
240 BUILD_ASSERT(SAME_TYPE(*(ptr), ((type *)0)->field) || \
241 SAME_TYPE(*(ptr), void), \
242 "pointer type mismatch in CONTAINER_OF");
243#else
244#define CONTAINER_OF_VALIDATE(ptr, type, field)
245#endif
246
268#define CONTAINER_OF(ptr, type, field) \
269 ({ \
270 CONTAINER_OF_VALIDATE(ptr, type, field) \
271 ((type *)(((char *)(ptr)) - offsetof(type, field))); \
272 })
273
282#define SIZEOF_FIELD(type, member) sizeof((((type *)0)->member))
283
295#define CONCAT(...) \
296 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)) / \
308 (unsigned long)(align)) * (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 ((((n) < 0) ^ ((d) < 0)) ? ((n) - ((d) / 2)) / (d) : \
355 ((n) + ((d) / 2)) / (d))
356
361#define ceiling_fraction(numerator, divider) __DEPRECATED_MACRO \
362 DIV_ROUND_UP(numerator, divider)
363
364#ifndef MAX
376#define MAX(a, b) (((a) > (b)) ? (a) : (b))
377#endif
378
379#ifndef MIN
391#define MIN(a, b) (((a) < (b)) ? (a) : (b))
392#endif
393
394#ifndef CLAMP
407#define CLAMP(val, low, high) (((val) <= (low)) ? (low) : MIN(val, high))
408#endif
409
422#define IN_RANGE(val, min, max) ((val) >= (min) && (val) <= (max))
423
429static inline bool is_power_of_two(unsigned int x)
430{
431 return IS_POWER_OF_TWO(x);
432}
433
453static ALWAYS_INLINE bool is_null_no_warn(void *p)
454{
455 return p == NULL;
456}
457
466{
467 int64_t sign_ext;
468
469 if (shift == 0U) {
470 return value;
471 }
472
473 /* extract sign bit */
474 sign_ext = (value >> 63) & 1;
475
476 /* make all bits of sign_ext be the same as the value's sign bit */
477 sign_ext = -sign_ext;
478
479 /* shift value and fill opened bit positions with sign bit */
480 return (value >> shift) | (sign_ext << (64 - shift));
481}
482
492static inline void bytecpy(void *dst, const void *src, size_t size)
493{
494 size_t i;
495
496 for (i = 0; i < size; ++i) {
497 ((volatile uint8_t *)dst)[i] = ((volatile const uint8_t *)src)[i];
498 }
499}
500
511static inline void byteswp(void *a, void *b, size_t size)
512{
513 uint8_t t;
514 uint8_t *aa = (uint8_t *)a;
515 uint8_t *bb = (uint8_t *)b;
516
517 for (; size > 0; --size) {
518 t = *aa;
519 *aa++ = *bb;
520 *bb++ = t;
521 }
522}
523
532int char2hex(char c, uint8_t *x);
533
542int hex2char(uint8_t x, char *c);
543
554size_t bin2hex(const uint8_t *buf, size_t buflen, char *hex, size_t hexlen);
555
566size_t hex2bin(const char *hex, size_t hexlen, uint8_t *buf, size_t buflen);
567
575static inline uint8_t bcd2bin(uint8_t bcd)
576{
577 return ((10 * (bcd >> 4)) + (bcd & 0x0F));
578}
579
587static inline uint8_t bin2bcd(uint8_t bin)
588{
589 return (((bin / 10) << 4) | (bin % 10));
590}
591
605uint8_t u8_to_dec(char *buf, uint8_t buflen, uint8_t value);
606
613static inline int32_t sign_extend(uint32_t value, uint8_t index)
614{
615 __ASSERT_NO_MSG(index <= 31);
616
617 uint8_t shift = 31 - index;
618
619 return (int32_t)(value << shift) >> shift;
620}
621
628static inline int64_t sign_extend_64(uint64_t value, uint8_t index)
629{
630 __ASSERT_NO_MSG(index <= 63);
631
632 uint8_t shift = 63 - index;
633
634 return (int64_t)(value << shift) >> shift;
635}
636
661char *utf8_trunc(char *utf8_str);
662
677char *utf8_lcpy(char *dst, const char *src, size_t n);
678
679#define __z_log2d(x) (32 - __builtin_clz(x) - 1)
680#define __z_log2q(x) (64 - __builtin_clzll(x) - 1)
681#define __z_log2(x) (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))
682
693#define LOG2(x) ((x) < 1 ? -1 : __z_log2(x))
694
705#define LOG2CEIL(x) ((x) < 1 ? 0 : __z_log2((x)-1) + 1)
706
719#define NHPOT(x) ((x) < 1 ? 1 : ((x) > (1ULL<<63) ? 0 : 1ULL << LOG2CEIL(x)))
720
733#define Z_DETECT_POINTER_OVERFLOW(addr, buflen) \
734 (((buflen) != 0) && \
735 ((UINTPTR_MAX - (uintptr_t)(addr)) <= ((uintptr_t)((buflen) - 1))))
736
745static inline void mem_xor_n(uint8_t *dst, const uint8_t *src1, const uint8_t *src2, size_t len)
746{
747 while (len--) {
748 *dst++ = *src1++ ^ *src2++;
749 }
750}
751
759static inline void mem_xor_32(uint8_t dst[4], const uint8_t src1[4], const uint8_t src2[4])
760{
761 mem_xor_n(dst, src1, src2, 4U);
762}
763
771static inline void mem_xor_128(uint8_t dst[16], const uint8_t src1[16], const uint8_t src2[16])
772{
773 mem_xor_n(dst, src1, src2, 16);
774}
775
776#ifdef __cplusplus
777}
778#endif
779
780/* This file must be included at the end of the !_ASMLANGUAGE guard.
781 * It depends on macros defined in this file above which cannot be forward declared.
782 */
784
785#endif /* !_ASMLANGUAGE */
786
788#ifdef _LINKER
789/* This is used in linker scripts so need to avoid type casting there */
790#define KB(x) ((x) << 10)
791#else
792#define KB(x) (((size_t)(x)) << 10)
793#endif
795#define MB(x) (KB(x) << 10)
797#define GB(x) (MB(x) << 10)
798
800#define KHZ(x) ((x) * 1000)
802#define MHZ(x) (KHZ(x) * 1000)
803
816#if defined(CONFIG_ARCH_POSIX)
817#define Z_SPIN_DELAY(t) k_busy_wait(t)
818#else
819#define Z_SPIN_DELAY(t)
820#endif
821
837#define WAIT_FOR(expr, timeout, delay_stmt) \
838 ({ \
839 uint32_t _wf_cycle_count = k_us_to_cyc_ceil32(timeout); \
840 uint32_t _wf_start = k_cycle_get_32(); \
841 while (!(expr) && (_wf_cycle_count > (k_cycle_get_32() - _wf_start))) { \
842 delay_stmt; \
843 Z_SPIN_DELAY(10); \
844 } \
845 (expr); \
846 })
847
852#endif /* ZEPHYR_INCLUDE_SYS_UTIL_H_ */
irp nz macro MOVR cc s mov cc s endm endr irp aa
Definition: asm-macro-32-bit-gnu.h:16
#define ALWAYS_INLINE
Definition: common.h:129
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:628
char * utf8_trunc(char *utf8_str)
Properly truncate a NULL-terminated UTF-8 string.
static int64_t arithmetic_shift_right(int64_t value, uint8_t shift)
Arithmetic shift right.
Definition: util.h:465
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:492
char * utf8_lcpy(char *dst, const char *src, size_t n)
Copies a UTF-8 encoded string from src to dst.
#define IS_POWER_OF_TWO(x)
Check if a x is a power of two.
Definition: util_macro.h:77
static ALWAYS_INLINE bool is_null_no_warn(void *p)
Is p equal to NULL?
Definition: util.h:453
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:771
static uint8_t bin2bcd(uint8_t bin)
Convert a binary value to binary coded decimal (BCD 8421).
Definition: util.h:587
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:759
static void byteswp(void *a, void *b, size_t size)
byte by byte swap.
Definition: util.h:511
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:745
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:575
int char2hex(char c, uint8_t *x)
Convert a single character into a hexadecimal nibble.
uint8_t u8_to_dec(char *buf, uint8_t buflen, uint8_t value)
Convert a uint8_t into a decimal string representation.
static bool is_power_of_two(unsigned int x)
Is x a power of two?
Definition: util.h:429
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:613
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
Macros to abstract toolchain specific capabilities.
Macro utilities.