2  * Copyright (c) 2011-2014, Wind River Systems, Inc.
4  * SPDX-License-Identifier: Apache-2.0
39  * @defgroup sys-util Utility Functions
44 /** @brief Cast @p x, a pointer, to an unsigned integer. */
45 #define POINTER_TO_UINT(x) ((uintptr_t) (x))  argument
46 /** @brief Cast @p x, an unsigned integer, to a <tt>void*</tt>. */
47 #define UINT_TO_POINTER(x) ((void *) (uintptr_t) (x))  argument
48 /** @brief Cast @p x, a pointer, to a signed integer. */
49 #define POINTER_TO_INT(x)  ((intptr_t) (x))  argument
50 /** @brief Cast @p x, a signed integer, to a <tt>void*</tt>. */
51 #define INT_TO_POINTER(x)  ((void *) (intptr_t) (x))  argument
68 	(((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
71  * @brief Create a contiguous 64-bit bitmask starting at bit position @p l
75 	(((~0ULL) - (1ULL << (l)) + 1) & (~0ULL >> (BITS_PER_LONG_LONG - 1 - (h))))
78 #define LSB_GET(value) ((value) & -(value))
93 /** @brief 0 if @p cond is true-ish; causes a compile error otherwise. */
94 #define ZERO_OR_COMPILE_ERROR(cond) ((int) sizeof(char[1 - 2 * !(cond)]) - 1)
98 /* The built-in function used below for type checking in C is not
133  * in that it also ensures that @p ptr is aligned to an array-element boundary
146 	 (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) % sizeof((array)[0]) == 0)
153  * is not aligned to an array-element boundary of @p array.
165 		(__typeof__((array)[0]) *)(ptr) - (array);                                         \
183  * @brief Array-index of @p ptr within @p array, rounded down
187  * exclusively a @p ptr aligned to an array-element boundary of @p array.
202 		(POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) / sizeof((array)[0]);              \
219 	BUILD_ASSERT(SAME_TYPE(*(ptr), ((type *)0)->field) || \
250 		((type *)(((char *)(ptr)) - offsetof(type, field))); \
254  * @brief Value of @p x rounded up to the next multiple of @p align.
256 #define ROUND_UP(x, align)                                   \  argument
257 	((((unsigned long)(x) + ((unsigned long)(align) - 1)) / \
261  * @brief Value of @p x rounded down to the previous multiple of @p align.
263 #define ROUND_DOWN(x, align)                                 \  argument
264 	(((unsigned long)(x) / (unsigned long)(align)) * (unsigned long)(align))
266 /** @brief Value of @p x rounded up to the next word boundary. */
267 #define WB_UP(x) ROUND_UP(x, sizeof(void *))  argument
269 /** @brief Value of @p x rounded down to the previous word boundary. */
270 #define WB_DN(x) ROUND_DOWN(x, sizeof(void *))  argument
286 #define DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))
294  * DIV_ROUND_CLOSEST(5, -2); // -3
304 	((((n) < 0) ^ ((d) < 0)) ? ((n) - ((d) / 2)) / (d) : \
314 #ifndef MAX
318  * @note Arguments are evaluated twice. Use Z_MAX for a GCC-only, single
326 #define MAX(a, b) (((a) > (b)) ? (a) : (b))  macro
333  * @note Arguments are evaluated twice. Use Z_MIN for a GCC-only, single
348  * @note Arguments are evaluated multiple times. Use Z_CLAMP for a GCC-only,
367  * @param max Upper bound (inclusive).
372 #define IN_RANGE(val, min, max) ((val) >= (min) && (val) <= (max))  argument
375  * @brief Is @p x a power of two?
376  * @param x value to check
377  * @return true if @p x is a power of two, false otherwise
379 static inline bool is_power_of_two(unsigned int x)  in is_power_of_two()  argument
381 	return IS_POWER_OF_TWO(x);  in is_power_of_two()
403 	sign_ext = -sign_ext;  in arithmetic_shift_right()
406 	return (value >> shift) | (sign_ext << (64 - shift));  in arithmetic_shift_right()
443 	for (; size > 0; --size) {  in byteswp()
454  * @param x     The address of storage for the converted number.
458 int char2hex(char c, uint8_t *x);
464  * @param x     The address of storage for the converted character.
468 int hex2char(uint8_t x, char *c);
534  * @brief Properly truncate a NULL-terminated UTF-8 string
536  * Take a NULL-terminated UTF-8 string and ensure that if the string has been
538  * the string ends with a properly formatted UTF-8 character (1-4 bytes).
547  *      trunc_utf8[sizeof(trunc_utf8) - 1] = '\0';
553  * @param utf8_str NULL-terminated string
560  * @brief Copies a UTF-8 encoded string from @p src to @p dst
563  * and the @p dst string will always be properly UTF-8 truncated.
565  * @param dst The destination of the UTF-8 string.
568  *            is @p n - 1. If 0 nothing will be done, and the @p dst will not be
575 #define __z_log2d(x) (32 - __builtin_clz(x) - 1)  argument
576 #define __z_log2q(x) (64 - __builtin_clzll(x) - 1)  argument
577 #define __z_log2(x) (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))  argument
580  * @brief Compute log2(x)
585  * @param x An unsigned integral value to compute logarithm of (positive only)
587  * @return log2(x) when 1 <= x <= max(x), -1 when x < 1
589 #define LOG2(x) ((x) < 1 ? -1 : __z_log2(x))  argument
592  * @brief Compute ceil(log2(x))
597  * @param x An unsigned integral value
599  * @return ceil(log2(x)) when 1 <= x <= max(type(x)), 0 when x < 1
601 #define LOG2CEIL(x) ((x) < 1 ?  0 : __z_log2((x)-1) + 1)  argument
606  * Equivalent to 2^ceil(log2(x))
611  * @param x An unsigned integral value
613  * @return 2^ceil(log2(x)) or 0 if 2^ceil(log2(x)) would saturate 64-bits
615 #define NHPOT(x) ((x) < 1 ? 1 : ((x) > (1ULL<<63) ? 0 : 1ULL << LOG2CEIL(x)))  argument
631 	((UINTPTR_MAX - (uintptr_t)(addr)) <= ((uintptr_t)((buflen) - 1))))
644 /** @brief Number of bytes in @p x kibibytes */
647 #define KB(x) ((x) << 10)  argument
649 #define KB(x) (((size_t)x) << 10)  argument
651 /** @brief Number of bytes in @p x mebibytes */
652 #define MB(x) (KB(x) << 10)  argument
653 /** @brief Number of bytes in @p x gibibytes */
654 #define GB(x) (MB(x) << 10)  argument
656 /** @brief Number of Hz in @p x kHz */
657 #define KHZ(x) ((x) * 1000)  argument
658 /** @brief Number of Hz in @p x MHz */
659 #define MHZ(x) (KHZ(x) * 1000)  argument
663  * For other architectures this is a no-op.
698 		while (!(expr) && (_wf_cycle_count > (k_cycle_get_32() - _wf_start))) {            \