492 lines
13 KiB
C
492 lines
13 KiB
C
|
// SPDX-License-Identifier: LGPL-3.0-or-later
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \file xpt.h
|
||
|
|
*
|
||
|
|
* Cross platform types and definitions.
|
||
|
|
*
|
||
|
|
* \copyright The DoubleFourteen Code Forge (C) All Rights Reserved
|
||
|
|
* \author Lorenzo Cogotti
|
||
|
|
*
|
||
|
|
* Defines fixed-size integer types and other general utility types and
|
||
|
|
* other macros that are ought to be available and equivalent across any
|
||
|
|
* supported platform.
|
||
|
|
*
|
||
|
|
* This header keeps its dependencies at a bare minimum, and **MUST NOT**
|
||
|
|
* excessively pollute the namespace.
|
||
|
|
*
|
||
|
|
* Including this header makes symbols from `stddef.h` and `stdint.h` visible.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef DF_XPT_H_
|
||
|
|
#define DF_XPT_H_
|
||
|
|
|
||
|
|
#include <stddef.h>
|
||
|
|
#include <stdint.h>
|
||
|
|
|
||
|
|
// Extern function declarations for inline functions on header
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def EXTERNC
|
||
|
|
*
|
||
|
|
* Expands to `extern` or `extern "C"` depending on whether or not the compiler
|
||
|
|
* supports C++.
|
||
|
|
*
|
||
|
|
* This is useful to declare `extern` C functions inside inline functions
|
||
|
|
* code within .h files, in order to avoid a full fledged `#include`.
|
||
|
|
*/
|
||
|
|
#ifdef __cplusplus
|
||
|
|
#define EXTERNC extern "C"
|
||
|
|
#else
|
||
|
|
#define EXTERNC extern
|
||
|
|
#endif
|
||
|
|
|
||
|
|
// Boolean and fixed size types
|
||
|
|
|
||
|
|
typedef int Boolean; ///< A boolean value, legal values are `TRUE` or `FALSE`
|
||
|
|
typedef int ToggleState; ///< Switch toggle state, legal values are `ON` or `OFF`
|
||
|
|
typedef int Judgement; ///< Operation result outcome, legal values are `OK` or `NG`
|
||
|
|
|
||
|
|
/// Boolean values (`true`, `false`).
|
||
|
|
enum BooleanLogic {
|
||
|
|
FALSE = 0, ///< `false` boolean value, guaranteed to be 0.
|
||
|
|
TRUE = 1 ///< `true` boolean value, guaranteed to be 1.
|
||
|
|
};
|
||
|
|
|
||
|
|
/// Switch toggle states (`on`, `off`).
|
||
|
|
enum BooleanSwitch {
|
||
|
|
OFF = 0, ///< `off` value, guaranteed to be 0.
|
||
|
|
ON = 1 ///< `on` value, guaranteed to be 1.
|
||
|
|
};
|
||
|
|
|
||
|
|
/// Operation success states (success, failure).
|
||
|
|
enum BooleanJudgement {
|
||
|
|
OK = 0, ///< Success state, guaranteed to be 0 (no errors).
|
||
|
|
NG = -1 ///< Failure state, negative value, equals to -1 (no-good).
|
||
|
|
};
|
||
|
|
|
||
|
|
typedef char Boolean8; ///< Packed boolean type, may hold the same values as `Boolean`
|
||
|
|
|
||
|
|
typedef int8_t Sint8; ///< Fixed-size signed 8-bits integer type
|
||
|
|
typedef uint8_t Uint8; ///< Fixed-size unsigned 8-bits integer type
|
||
|
|
typedef int16_t Sint16; ///< Fixed-size signed 16-bits integer type
|
||
|
|
typedef uint16_t Uint16; ///< Fixed-size unsigned 16-bits integer type
|
||
|
|
typedef int32_t Sint32; ///< Fixed-size signed 32-bits integer type
|
||
|
|
typedef uint32_t Uint32; ///< Fixed-size unsigned 32-bits integer type
|
||
|
|
typedef int64_t Sint64; ///< Fixed-size signed 64-bits integer type
|
||
|
|
typedef uint64_t Uint64; ///< Fixed-size unsigned 64-bits integer type
|
||
|
|
typedef intptr_t Sintptr; ///< Fixed-size signed type large enough to store a pointer
|
||
|
|
typedef uintptr_t Uintptr; ///< Fixed-size unsigned type large enough to store a pointer
|
||
|
|
|
||
|
|
// Fixed size compile time constants
|
||
|
|
|
||
|
|
#define S8_C(c) INT8_C(c) ///< Expands constant `c` to a signed 8 bit integer literal
|
||
|
|
#define U8_C(c) UINT8_C(c) ///< Expands constant `c` to an unsigned 8 bit integer literal
|
||
|
|
#define S16_C(c) INT16_C(c) ///< Expands constant `c` to a signed 16 bit integer literal
|
||
|
|
#define U16_C(c) UINT16_C(c) ///< Expands constant `c` to an unsigned 16 bit integer literal
|
||
|
|
#define S32_C(c) INT32_C(c) ///< Expands constant `c` to a signed 32 bit integer literal
|
||
|
|
#define U32_C(c) UINT32_C(c) ///< Expands constant `c` to an unsigned 32 bit integer literal
|
||
|
|
#define S64_C(c) INT64_C(c) ///< Expands constant `c` to a signed 64 bit integer literal
|
||
|
|
#define U64_C(c) UINT64_C(c) ///< Expands constant `c` to an unsigned 64 bit integer literal
|
||
|
|
|
||
|
|
// Compiler support for thread-locals, over/under-alignment,
|
||
|
|
// inline and no-return functions
|
||
|
|
|
||
|
|
// NOTE: we don't support TinyCC because there's no TLS support there
|
||
|
|
|
||
|
|
#ifdef __TINYC__
|
||
|
|
#error "Sorry, no TLS support available on Tiny C Compiler"
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def THREAD_LOCAL
|
||
|
|
*
|
||
|
|
* \brief Declares a static variable as thread local.
|
||
|
|
*
|
||
|
|
* \def ALIGNED(a, what)
|
||
|
|
*
|
||
|
|
* \brief Force type, variable, or member alignment.
|
||
|
|
*
|
||
|
|
* \param a Required alignment, must be a positive power of two and a compile-time integer literal.
|
||
|
|
* \param what What should be aligned, a variable, type or member
|
||
|
|
*
|
||
|
|
* \def NORETURN
|
||
|
|
*
|
||
|
|
* \brief Declare a function shall never return to its caller (like `exit()`).
|
||
|
|
*
|
||
|
|
* \warning Behavior is undefined if function does return.
|
||
|
|
*
|
||
|
|
* \def UNREACHABLE
|
||
|
|
*
|
||
|
|
* \brief Mark code as unreachable.
|
||
|
|
*
|
||
|
|
* \warning Behavior is undefined if code is actually reached during execution.
|
||
|
|
*
|
||
|
|
* \def FORCE_INLINE
|
||
|
|
*
|
||
|
|
* \brief Require function inlining, regardless of compiler policy.
|
||
|
|
*
|
||
|
|
* \note Function may be inlined even in debug builds.
|
||
|
|
*
|
||
|
|
* \def INLINE
|
||
|
|
*
|
||
|
|
* \brief Suggest a function should be inlined, compiler may still choose not to.
|
||
|
|
*
|
||
|
|
* \def NOINLINE
|
||
|
|
*
|
||
|
|
* \brief Force the compiler **not** to inline a function,
|
||
|
|
* regardless of its own policy.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#define THREAD_LOCAL __declspec(thread)
|
||
|
|
#else
|
||
|
|
#define THREAD_LOCAL __thread
|
||
|
|
#endif
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#define ALIGNED(a, what) __declspec(align(a)) what
|
||
|
|
#else
|
||
|
|
#define ALIGNED(a, what) what __attribute__((__aligned__(a)))
|
||
|
|
#endif
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#define NORETURN __declspec(noreturn)
|
||
|
|
#else
|
||
|
|
#define NORETURN __attribute__((__noreturn__))
|
||
|
|
#endif
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#define UNREACHABLE __assume(0)
|
||
|
|
#elif defined(__GNUC__)
|
||
|
|
#define UNREACHABLE __builtin_unreachable()
|
||
|
|
#else
|
||
|
|
#define UNREACHABLE ((void) 0) /*NOTREACHED*/
|
||
|
|
#endif
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#define FORCE_INLINE __forceinline
|
||
|
|
#define INLINE __inline
|
||
|
|
#define NOINLINE __declspec(noinline)
|
||
|
|
#elif defined(__GNUC__)
|
||
|
|
#define FORCE_INLINE static __inline__ __attribute__((__always_inline__, __unused__))
|
||
|
|
#define INLINE static __inline__ __attribute__((__unused__))
|
||
|
|
#define NOINLINE __attribute__((__noinline__))
|
||
|
|
#else
|
||
|
|
// this is a crude fallback and actually loses quite a bit of the intended semantics...
|
||
|
|
#if 0
|
||
|
|
#error "No FORCE_INLINE and NOINLINE for this platform"
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#define FORCE_INLINE static inline
|
||
|
|
#define INLINE static inline
|
||
|
|
#define NOINLINE
|
||
|
|
#endif
|
||
|
|
|
||
|
|
// Compiler checks
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def CHECK_PRINTF
|
||
|
|
*
|
||
|
|
* \brief Compiler check on `printf()`-like function arguments.
|
||
|
|
*
|
||
|
|
* If compiler supports it, check at compile-time that `printf()` and `vprintf()`
|
||
|
|
* like formatted message arguments are valid.
|
||
|
|
*
|
||
|
|
* \param f `const char *` message template argument index (1 is first argument)
|
||
|
|
* \param a Variadic arguments start (`...` argument index), use 0 if function takes a `va_list` (1 is first argument)
|
||
|
|
*
|
||
|
|
* \def STATIC_ASSERT
|
||
|
|
*
|
||
|
|
* \brief Compile time assertion.
|
||
|
|
*
|
||
|
|
* If compiler supports it, test a condition at compile time, aborting
|
||
|
|
* compilation on failure.
|
||
|
|
*
|
||
|
|
* \param what Expression to be evaluated at compile time
|
||
|
|
* \param msg Failure message
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifdef __GNUC__
|
||
|
|
#define CHECK_PRINTF(f, a) __attribute__((__format__(__printf__, f, a)))
|
||
|
|
#else
|
||
|
|
#define CHECK_PRINTF(f, a)
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#ifndef __cplusplus
|
||
|
|
#define STATIC_ASSERT(what, msg) _Static_assert(what, msg)
|
||
|
|
#else
|
||
|
|
#define STATIC_ASSERT(what, msg) static_assert(what, msg)
|
||
|
|
#endif
|
||
|
|
|
||
|
|
// NOTE: if we ever need packing just use the MSVC style #pragma pack(push, N)
|
||
|
|
// + #pragma pack(pop), it's pretty much universal.
|
||
|
|
|
||
|
|
// Platform suitable memory alignment type
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def ALIGNMENT
|
||
|
|
*
|
||
|
|
* \brief Platform memory alignment required for primitive types.
|
||
|
|
*
|
||
|
|
* \note This alignment is only safe for primitive and trivial struct types,
|
||
|
|
* but may be insufficient for SIMD types or overaligned types.
|
||
|
|
*/
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#ifdef _WIN32
|
||
|
|
#define ALIGNMENT 4
|
||
|
|
#else
|
||
|
|
#define ALIGNMENT 8
|
||
|
|
#endif
|
||
|
|
#elif defined(__GNUC__)
|
||
|
|
#define ALIGNMENT __BIGGEST_ALIGNMENT__
|
||
|
|
#else
|
||
|
|
// conservative guess
|
||
|
|
#define ALIGNMENT 16
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Perform or test alignment of size `x` or pointer `p` to `align` bytes.
|
||
|
|
*
|
||
|
|
* \param x Unsigned integral size in bytes
|
||
|
|
* \param p A pointer
|
||
|
|
* \param align Unsigned integral power of two specifying alignment
|
||
|
|
*
|
||
|
|
* \warning `align` must be a power of 2, macro arguments are evaluated more
|
||
|
|
* than once.
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
* \def ALIGN
|
||
|
|
* \def ALIGN_DOWN
|
||
|
|
* \def ALIGN_PTR
|
||
|
|
* \def ALIGN_PTR_DOWN
|
||
|
|
*
|
||
|
|
* \def IS_ALIGNED
|
||
|
|
* \def IS_PTR_ALIGNED
|
||
|
|
* @}
|
||
|
|
*/
|
||
|
|
#define ALIGN(x, align) \
|
||
|
|
(((x) + ((align) - 1)) & ~((align) - 1))
|
||
|
|
#define ALIGN_DOWN(x, align) \
|
||
|
|
ALIGN((x) - ((align) - 1), align)
|
||
|
|
#define ALIGN_PTR(p, align) \
|
||
|
|
((void *) ALIGN((uintptr_t) (p), align))
|
||
|
|
#define ALIGN_PTR_DOWN(p, align) \
|
||
|
|
((void *) ALIGN_DOWN((uintptr_t) (p), align))
|
||
|
|
|
||
|
|
#define IS_ALIGNED(x, align) (((x) & ((align) - 1)) == 0)
|
||
|
|
#define IS_PTR_ALIGNED(p, align) IS_ALIGNED((Uintptr) p, align)
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def alloca
|
||
|
|
*
|
||
|
|
* \brief Dynamic memory allocation on stack.
|
||
|
|
*
|
||
|
|
* \param size Size to be allocated, in bytes, unsigned integral value
|
||
|
|
*
|
||
|
|
* \warning Allocating large chunks of memory on stack is a sure one-way ticket
|
||
|
|
* to a stack overflow, there is no way to indicate memory allocation
|
||
|
|
* failures for `alloca()`.
|
||
|
|
*/
|
||
|
|
#ifdef _MSC_VER
|
||
|
|
#define alloca(size) _alloca(size)
|
||
|
|
#else
|
||
|
|
#define alloca(size) __builtin_alloca(size)
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def ARRAY_SIZE
|
||
|
|
*
|
||
|
|
* \brief Array element count.
|
||
|
|
*
|
||
|
|
* \param array Array to be sized
|
||
|
|
*/
|
||
|
|
#ifndef ARRAY_SIZE
|
||
|
|
#define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
|
||
|
|
#endif
|
||
|
|
/**
|
||
|
|
* \def BIT
|
||
|
|
*
|
||
|
|
* \brief Return unsigned integer constant with a single bit set.
|
||
|
|
*
|
||
|
|
* \param idx Bit index to be set (0 is LSB)
|
||
|
|
*/
|
||
|
|
#ifndef BIT
|
||
|
|
#define BIT(idx) (1uLL << (idx))
|
||
|
|
#endif
|
||
|
|
/**
|
||
|
|
* \def USED
|
||
|
|
*
|
||
|
|
* Suppress unused variable warnings for `x`.
|
||
|
|
*
|
||
|
|
* \param x Identifier to mark as used
|
||
|
|
*/
|
||
|
|
#ifndef USED
|
||
|
|
#define USED(x) ((void) (x))
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def EDN_LE
|
||
|
|
*
|
||
|
|
* \brief Constant identifying little-endian byte ordering (LSB first).
|
||
|
|
*
|
||
|
|
* \def EDN_BE
|
||
|
|
*
|
||
|
|
* \brief Constant identifying big-endian byte ordering (MSB first).
|
||
|
|
*
|
||
|
|
* \def EDN_NATIVE
|
||
|
|
*
|
||
|
|
* \brief Constant identifying native byte ordering,
|
||
|
|
* equals either `EDN_BE` or `EDN_LE`.
|
||
|
|
*/
|
||
|
|
#ifdef _WIN32
|
||
|
|
|
||
|
|
#define EDN_LE 0
|
||
|
|
#define EDN_BE 1
|
||
|
|
#define EDN_NATIVE EDN_LE
|
||
|
|
|
||
|
|
#else
|
||
|
|
|
||
|
|
#define EDN_LE __ORDER_LITTLE_ENDIAN__
|
||
|
|
#define EDN_BE __ORDER_BIG_ENDIAN__
|
||
|
|
#define EDN_NATIVE __BYTE_ORDER__
|
||
|
|
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#if EDN_NATIVE != EDN_LE && EDN_NATIVE != EDN_BE
|
||
|
|
#error "Unsupported platform endianness"
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Swaps bytes inside 16, 32 and 64 bits unsigned integers.
|
||
|
|
*
|
||
|
|
* Truncates `x` to the required amount of bytes, if necessary,
|
||
|
|
* and reverses each byte around. The value is then returned.
|
||
|
|
* If `x` is a compile-time constant the result is also a constant.
|
||
|
|
*
|
||
|
|
* \param x Unsigned integer value to be byte-swapped
|
||
|
|
*
|
||
|
|
* \warning `x` is evaluated multiple times.
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
* \def BSWAP16
|
||
|
|
* \def BSWAP32
|
||
|
|
* \def BSWAP64
|
||
|
|
* @}
|
||
|
|
*/
|
||
|
|
#ifndef BSWAP16
|
||
|
|
#define BSWAP16(x) ((Uint16) ( \
|
||
|
|
(((x) & 0xff00u) >> 8) | (((x) & 0x00ffu) << 8) \
|
||
|
|
))
|
||
|
|
#endif
|
||
|
|
#ifndef BSWAP32
|
||
|
|
#define BSWAP32(x) ((Uint32) ( \
|
||
|
|
(((x) & 0xff000000u) >> 24) | (((x) & 0x00ff0000u) >> 8) | \
|
||
|
|
(((x) & 0x0000ff00u) << 8) | (((x) & 0x000000ffu) << 24) \
|
||
|
|
))
|
||
|
|
#endif
|
||
|
|
#ifndef BSWAP64
|
||
|
|
#define BSWAP64(x) ((Uint64) ( \
|
||
|
|
(((x) & 0xff00000000000000uLL) >> 56) | \
|
||
|
|
(((x) & 0x00ff000000000000uLL) >> 40) | \
|
||
|
|
(((x) & 0x0000ff0000000000uLL) >> 24) | \
|
||
|
|
(((x) & 0x000000ff00000000uLL) >> 8) | \
|
||
|
|
(((x) & 0x00000000ff000000uLL) << 8) | \
|
||
|
|
(((x) & 0x0000000000ff0000uLL) << 24) | \
|
||
|
|
(((x) & 0x000000000000ff00uLL) << 40) | \
|
||
|
|
(((x) & 0x00000000000000ffuLL) << 56) \
|
||
|
|
))
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Declare a fixed-size big or little endian constant.
|
||
|
|
*
|
||
|
|
* Following macros may be used to declare fixed size
|
||
|
|
* constant of a specific endianness at compile time.
|
||
|
|
* Original value is swapped if destination endianness
|
||
|
|
* is not match the host endianness. These macros are usable for
|
||
|
|
* variables as well, but functions declared in `sys/endian.h` should
|
||
|
|
* be preferred whenever possible (i.e. use these macros on variables
|
||
|
|
* only inside headers to reduce `#include`s).
|
||
|
|
*
|
||
|
|
* \param x Constant or variable, which is truncated to the required size.
|
||
|
|
*
|
||
|
|
* \return `x` as a constant or variable byte-swapped as needed.
|
||
|
|
*
|
||
|
|
* \warning `x` is evaluated multiple times.
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
* \def BE16
|
||
|
|
* \def BE32
|
||
|
|
* \def BE64
|
||
|
|
* \def LE16
|
||
|
|
* \def LE32
|
||
|
|
* \def LE64
|
||
|
|
* @}
|
||
|
|
*/
|
||
|
|
#if EDN_NATIVE == EDN_LE
|
||
|
|
#define BE16(x) BSWAP16(x)
|
||
|
|
#define BE32(x) BSWAP32(x)
|
||
|
|
#define BE64(x) BSWAP64(x)
|
||
|
|
#define LE16(x) ((Uint16) (x))
|
||
|
|
#define LE32(x) ((Uint32) (x))
|
||
|
|
#define LE64(x) ((Uint64) (x))
|
||
|
|
#else
|
||
|
|
#define BE16(x) ((Uint16) (x))
|
||
|
|
#define BE32(x) ((Uint32) (x))
|
||
|
|
#define BE64(x) ((Uint64) (x))
|
||
|
|
#define LE16(x) BSWAP16(x)
|
||
|
|
#define LE32(x) BSWAP32(x)
|
||
|
|
#define LE64(x) BSWAP64(x)
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Minimum, maximum and clamped to range values.
|
||
|
|
*
|
||
|
|
* \param x, y Generic comparable values
|
||
|
|
* \param a, b Clamping range, inclusive, `a` must be less than or equal to `b`
|
||
|
|
*
|
||
|
|
* \warning Arguments are evaluated more than once.
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
* \def MIN
|
||
|
|
* \def MAX
|
||
|
|
* \def CLAMP
|
||
|
|
* @}
|
||
|
|
*/
|
||
|
|
#ifndef MIN
|
||
|
|
#define MIN(x, y) (((x) < (y)) ? (x) : (y))
|
||
|
|
#endif
|
||
|
|
#ifndef MAX
|
||
|
|
#define MAX(x, y) (((x) < (y)) ? (y) : (x))
|
||
|
|
#endif
|
||
|
|
#ifndef CLAMP
|
||
|
|
#define CLAMP(x, a, b) MAX(a, MIN(x, b))
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def ABS
|
||
|
|
*
|
||
|
|
* \brief Absolute value of `x` using ternary `?:` operator.
|
||
|
|
*
|
||
|
|
* \param x An expression comparable with 0
|
||
|
|
*
|
||
|
|
* \warning `x` is evaluated more than once.
|
||
|
|
*/
|
||
|
|
#ifndef ABS
|
||
|
|
#define ABS(x) (((x) >= 0) ? (x) : -(x))
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \def FLEX_ARRAY
|
||
|
|
*
|
||
|
|
* \brief Clarity macro to convey that a trailing array member inside
|
||
|
|
* a `struct` is an array of arbitrary size.
|
||
|
|
*/
|
||
|
|
#ifdef __cplusplus
|
||
|
|
#define FLEX_ARRAY 1
|
||
|
|
#elif defined(_MSC_VER) || defined(__GNUC__)
|
||
|
|
#define FLEX_ARRAY
|
||
|
|
#else
|
||
|
|
#define FLEX_ARRAY 1
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif
|
||
|
|
|