util.h

Go to the documentation of this file.

/*
 * Copyright (c) 2011-2014, Wind River Systems, Inc.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_SYS_UTIL_H_
#define ZEPHYR_INCLUDE_SYS_UTIL_H_
 
#include <zephyr/sys/util_macro.h>
#include <zephyr/toolchain.h>
 
/* needs to be outside _ASMLANGUAGE so 'true' and 'false' can turn
 * into '1' and '0' for asm or linker scripts
 */
#include <stdbool.h>
 
#ifndef _ASMLANGUAGE
 
#include <zephyr/sys/__assert.h>
#include <zephyr/types.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>

#define NUM_BITS(t) (sizeof(t) * BITS_PER_BYTE)
 
#ifdef __cplusplus
extern "C" {
#endif


#define POINTER_TO_UINT(x) ((uintptr_t)(x))
#define UINT_TO_POINTER(x) ((void *)(uintptr_t)(x))
#define POINTER_TO_INT(x)  ((intptr_t)(x))
#define INT_TO_POINTER(x)  ((void *)(intptr_t)(x))
 
#if !(defined(__CHAR_BIT__) && defined(__SIZEOF_LONG__) && defined(__SIZEOF_LONG_LONG__))
#error Missing required predefined macros for BITS_PER_LONG calculation
#endif

#define BITS_PER_BYTE (__CHAR_BIT__)

#define BITS_PER_NIBBLE (__CHAR_BIT__ / 2)

#define NIBBLES_PER_BYTE (BITS_PER_BYTE / BITS_PER_NIBBLE)

#define BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__)

#define BITS_PER_LONG_LONG (__CHAR_BIT__ * __SIZEOF_LONG_LONG__)

#define GENMASK(h, l) (((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))

#define GENMASK64(h, l) (((~0ULL) - (1ULL << (l)) + 1) & (~0ULL >> (BITS_PER_LONG_LONG - 1 - (h))))

#define ZERO_OR_COMPILE_ERROR(cond) ((int)sizeof(char[1 - (2 * !(cond))]) - 1)
 
#if defined(__cplusplus)
 
/* The built-in function used below for type checking in C is not
 * supported by GNU C++.
 */
#define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
 
#else /* __cplusplus */

#define IS_ARRAY(array)                                                                            \
        ZERO_OR_COMPILE_ERROR(                                                                     \
                !__builtin_types_compatible_p(__typeof__(array), __typeof__(&(array)[0])))

#define ARRAY_SIZE(array) ((size_t)(IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))
 
#endif /* __cplusplus */

#define FLEXIBLE_ARRAY_DECLARE(type, name)                                                         \
        struct {                                                                                   \
                struct {                                                                           \
                } __unused_##name;                                                                 \
                type name[];                                                                       \
        }

#define IS_ARRAY_ELEMENT(array, ptr)                                                               \
        ((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) &&                                \
         POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]) &&                    \
         (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) % sizeof((array)[0]) == 0)

#define ARRAY_INDEX(array, ptr)                                                                    \
        ({                                                                                         \
                __ASSERT_NO_MSG(IS_ARRAY_ELEMENT(array, ptr));                                     \
                (__typeof__((array)[0]) *)(ptr) - (array);                                         \
        })

#define PART_OF_ARRAY(array, ptr)                                                                  \
        ((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) &&                                \
         POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]))

#define ARRAY_INDEX_FLOOR(array, ptr)                                                              \
        ({                                                                                         \
                __ASSERT_NO_MSG(PART_OF_ARRAY(array, ptr));                                        \
                (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) / sizeof((array)[0]);              \
        })

#define ARRAY_FOR_EACH(array, idx) for (size_t idx = 0; (idx) < ARRAY_SIZE(array); ++(idx))

#define ARRAY_FOR_EACH_PTR(array, ptr)                                                             \
        for (__typeof__(*(array)) *ptr = (array); (size_t)((ptr) - (array)) < ARRAY_SIZE(array);   \
             ++(ptr))

#define SAME_TYPE(a, b) __builtin_types_compatible_p(__typeof__(a), __typeof__(b))

#ifndef __cplusplus
#define CONTAINER_OF_VALIDATE(ptr, type, field)                                                    \
        BUILD_ASSERT(SAME_TYPE(*(ptr), ((type *)0)->field) || SAME_TYPE(*(ptr), void),             \
                     "pointer type mismatch in CONTAINER_OF");
#else
#define CONTAINER_OF_VALIDATE(ptr, type, field)
#endif

#define CONTAINER_OF(ptr, type, field)                                                             \
        ({                                                                                         \
                CONTAINER_OF_VALIDATE(ptr, type, field)                                            \
                ((type *)(((char *)(ptr)) - offsetof(type, field)));                               \
        })

#define SIZEOF_FIELD(type, member) sizeof((((type *)0)->member))

#define CONCAT(...) UTIL_CAT(_CONCAT_, NUM_VA_ARGS_LESS_1(__VA_ARGS__))(__VA_ARGS__)

#define IS_ALIGNED(ptr, align) (((uintptr_t)(ptr)) % (align) == 0)

#define ROUND_UP(x, align)                                                                         \
        ((((unsigned long)(x) + ((unsigned long)(align) - 1)) / (unsigned long)(align)) *          \
         (unsigned long)(align))

#define ROUND_DOWN(x, align)                                                                       \
        (((unsigned long)(x) / (unsigned long)(align)) * (unsigned long)(align))

#define WB_UP(x) ROUND_UP(x, sizeof(void *))

#define WB_DN(x) ROUND_DOWN(x, sizeof(void *))

#define DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))

#define DIV_ROUND_CLOSEST(n, d)                                                                    \
        (((((__typeof__(n))-1) < 0) && (((__typeof__(d))-1) < 0) && ((n) < 0) ^ ((d) < 0))         \
                 ? ((n) - ((d) / 2)) / (d)                                                         \
                 : ((n) + ((d) / 2)) / (d))

#define Z_INTERNAL_MAX(a, b) (((a) > (b)) ? (a) : (b))
#define Z_INTERNAL_MIN(a, b) (((a) < (b)) ? (a) : (b))
 
#ifndef MAX
#define MAX(a, b) Z_INTERNAL_MAX(a, b)
#endif
 
#ifndef MIN
#define MIN(a, b) Z_INTERNAL_MIN(a, b)
#endif
 
#ifndef MAX_FROM_LIST
#define Z_MAX_1(a) a

#define Z_MAX_2(a, b) ((a) > (b) ? (a) : (b))

#define Z_MAX_3(a, b, c) Z_MAX_2(a, Z_MAX_2(b, c))

#define Z_MAX_4(a, b, c, d) Z_MAX_2(Z_MAX_2(a, b), Z_MAX_2(c, d))

#define Z_MAX_5(a, b, c, d, e) Z_MAX_2(Z_MAX_4(a, b, c, d), e)

#define Z_MAX_6(a, b, c, d, e, f) Z_MAX_2(Z_MAX_5(a, b, c, d, e), f)

#define Z_MAX_7(a, b, c, d, e, f, g) Z_MAX_2(Z_MAX_6(a, b, c, d, e, f), g)

#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)

#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)

#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)

#define Z_GET_MAX_MACRO(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10, NAME, ...) NAME

#define MAX_FROM_LIST(...)                                                                         \
        Z_GET_MAX_MACRO(__VA_ARGS__, Z_MAX_10, Z_MAX_9, Z_MAX_8, Z_MAX_7, Z_MAX_6, Z_MAX_5,        \
                        Z_MAX_4, Z_MAX_3, Z_MAX_2, Z_MAX_1)(__VA_ARGS__)
#endif
 
#ifndef CLAMP
#define CLAMP(val, low, high) (((val) <= (low)) ? (low) : Z_INTERNAL_MIN(val, high))
#endif

#define IN_RANGE(val, min, max) ((val) >= (min) && (val) <= (max))

int bitmask_find_gap(uint32_t mask, size_t num_bits, size_t total_bits, bool first_match);

static inline bool is_power_of_two(unsigned int x)
{
        return IS_POWER_OF_TWO(x);
}

static ALWAYS_INLINE bool is_null_no_warn(void *p)
{
        return p == NULL;
}

static inline int64_t arithmetic_shift_right(int64_t value, uint8_t shift)
{
        int64_t sign_ext;
 
        if (shift == 0U) {
                return value;
        }
 
        /* extract sign bit */
        sign_ext = (value >> 63) & 1;
 
        /* make all bits of sign_ext be the same as the value's sign bit */
        sign_ext = -sign_ext;
 
        /* shift value and fill opened bit positions with sign bit */
        return (value >> shift) | (sign_ext << (64 - shift));
}

static inline void bytecpy(void *dst, const void *src, size_t size)
{
        size_t i;
 
        for (i = 0; i < size; ++i) {
                ((volatile uint8_t *)dst)[i] = ((volatile const uint8_t *)src)[i];
        }
}

static inline void byteswp(void *a, void *b, size_t size)
{
        uint8_t t;
        uint8_t *aa = (uint8_t *)a;
        uint8_t *bb = (uint8_t *)b;
 
        for (; size > 0; --size) {
                t = *aa;
                *aa++ = *bb;
                *bb++ = t;
        }
}

int char2hex(char c, uint8_t *x);

int hex2char(uint8_t x, char *c);

size_t bin2hex(const uint8_t *buf, size_t buflen, char *hex, size_t hexlen);

size_t hex2bin(const char *hex, size_t hexlen, uint8_t *buf, size_t buflen);

static inline uint8_t bcd2bin(uint8_t bcd)
{
        return ((10 * (bcd >> 4)) + (bcd & 0x0F));
}

static inline uint8_t bin2bcd(uint8_t bin)
{
        return (((bin / 10) << 4) | (bin % 10));
}

uint8_t u8_to_dec(char *buf, uint8_t buflen, uint8_t value);

static inline int32_t sign_extend(uint32_t value, uint8_t index)
{
        __ASSERT_NO_MSG(index <= 31);
 
        uint8_t shift = 31 - index;
 
        return (int32_t)(value << shift) >> shift;
}

static inline int64_t sign_extend_64(uint64_t value, uint8_t index)
{
        __ASSERT_NO_MSG(index <= 63);
 
        uint8_t shift = 63 - index;
 
        return (int64_t)(value << shift) >> shift;
}
 
#define __z_log2d(x) (32 - __builtin_clz(x) - 1)
#define __z_log2q(x) (64 - __builtin_clzll(x) - 1)
#define __z_log2(x)  (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))

#define LOG2(x) ((x) < 1 ? -1 : __z_log2(x))

#define LOG2CEIL(x) ((x) <= 1 ? 0 : __z_log2((x) - 1) + 1)

#define NHPOT(x) ((x) < 1 ? 1 : ((x) > (1ULL << 63) ? 0 : 1ULL << LOG2CEIL(x)))

#define Z_DETECT_POINTER_OVERFLOW(addr, buflen)                                                    \
        (((buflen) != 0) && ((UINTPTR_MAX - (uintptr_t)(addr)) <= ((uintptr_t)((buflen) - 1))))

static inline void mem_xor_n(uint8_t *dst, const uint8_t *src1, const uint8_t *src2, size_t len)
{
        while (len--) {
                *dst++ = *src1++ ^ *src2++;
        }
}

static inline void mem_xor_32(uint8_t dst[4], const uint8_t src1[4], const uint8_t src2[4])
{
        mem_xor_n(dst, src1, src2, 4U);
}

static inline void mem_xor_128(uint8_t dst[16], const uint8_t src1[16], const uint8_t src2[16])
{
        mem_xor_n(dst, src1, src2, 16);
}

static inline bool util_memeq(const void *m1, const void *m2, size_t n)
{
        return memcmp(m1, m2, n) == 0;
}

static inline bool util_eq(const void *m1, size_t len1, const void *m2, size_t len2)
{
        return len1 == len2 && (m1 == m2 || util_memeq(m1, m2, len1));
}

static inline size_t sys_count_bits(const void *value, size_t len)
{
        size_t cnt = 0U;
        size_t i = 0U;
 
#ifdef POPCOUNT
        for (; i < len / sizeof(unsigned int); i++) {
                unsigned int val;
                (void)memcpy(&val, (const uint8_t *)value + i * sizeof(unsigned int),
                             sizeof(unsigned int));
 
                cnt += POPCOUNT(val);
        }
        i *= sizeof(unsigned int); /* convert to a uint8_t index for the remainder (if any) */
#endif
 
        for (; i < len; i++) {
                uint8_t value_u8 = ((const uint8_t *)value)[i];
 
                /* Implements Brian Kernighan’s Algorithm to count bits */
                while (value_u8) {
                        value_u8 &= (value_u8 - 1);
                        cnt++;
                }
        }
 
        return cnt;
}

#define SYS_SIGN(x) (((x) > 0) - ((x) < 0))

#define sys_gcd(a, b) ((((__typeof__(a))-1) < 0) ? sys_gcd_s(a, b) : sys_gcd_u(a, b))

static ALWAYS_INLINE uint32_t sys_gcd_u(uint32_t a, uint32_t b)
{
        uint32_t c;
 
        if (a == 0) {
                return b;
        }
 
        if (b == 0) {
                return a;
        }
 
        c = a % b;
        while (c != 0) {
                a = b;
                b = c;
                c = a % b;
        }
 
        return b;
}
 
static ALWAYS_INLINE uint32_t sys_gcd_s(int32_t a, int32_t b)
{
        return sys_gcd_u(a < 0 ? -(uint32_t)a : (uint32_t)a, b < 0 ? -(uint32_t)b : (uint32_t)b);
}

#define sys_lcm(a, b) ((((__typeof__(a))-1) < 0) ? sys_lcm_s(a, b) : sys_lcm_u(a, b))

static ALWAYS_INLINE uint64_t sys_lcm_u(uint32_t a, uint32_t b)
{
        if (a == 0 || b == 0) {
                return 0;
        }
 
        return (uint64_t)(a / sys_gcd_u(a, b)) * (uint64_t)b;
}
 
static ALWAYS_INLINE uint64_t sys_lcm_s(int32_t a, int32_t b)
{
        return sys_lcm_u(a < 0 ? -(uint32_t)a : (uint32_t)a, b < 0 ? -(uint32_t)b : (uint32_t)b);
}
 
#ifdef __cplusplus
}
#endif
 
/* This file must be included at the end of the !_ASMLANGUAGE guard.
 * It depends on macros defined in this file above which cannot be forward declared.
 */
#include <zephyr/sys/time_units.h>
 
#endif /* !_ASMLANGUAGE */

#ifdef _LINKER
/* This is used in linker scripts so need to avoid type casting there */
#define KB(x) ((x) << 10)
#else
#define KB(x) (((size_t)(x)) << 10)
#endif
#define MB(x) (KB(x) << 10)
#define GB(x) (MB(x) << 10)

#define KHZ(x) ((x) * 1000)
#define MHZ(x) (KHZ(x) * 1000)

#if defined(CONFIG_ARCH_POSIX)
#define Z_SPIN_DELAY(t) k_busy_wait(t)
#else
#define Z_SPIN_DELAY(t)
#endif

#define WAIT_FOR(expr, timeout, delay_stmt)                                                        \
        ({                                                                                         \
                uint32_t _wf_cycle_count = k_us_to_cyc_ceil32(timeout);                            \
                uint32_t _wf_start = k_cycle_get_32();                                             \
                bool _wf_ret;                                                                      \
                while (!(_wf_ret = (expr)) &&                                                      \
                       (_wf_cycle_count > (k_cycle_get_32() - _wf_start))) {                       \
                        delay_stmt;                                                                \
                        Z_SPIN_DELAY(10);                                                          \
                }                                                                                  \
                (_wf_ret);                                                                         \
        })

#ifdef CONFIG_ZTEST
#define ZTESTABLE_STATIC
#else
#define ZTESTABLE_STATIC static
#endif

 
#endif /* ZEPHYR_INCLUDE_SYS_UTIL_H_ */