diff --git a/include/sta/assert.hpp b/include/sta/assert.hpp index 40f5886..c695d3b 100644 --- a/include/sta/assert.hpp +++ b/include/sta/assert.hpp @@ -1,23 +1,51 @@ /** + * @file * @brief Assertion handling. - * - * Configuration: - * STA_ASSERT_ENABLE: Enable module - * STA_ASSERT_DISABLE: Forces module off when defined - * STA_HALT: Override function called after failed asserts - * DEBUG: Automatically enables module when defined - * NDEBUG: Forces module off when defined - * - * Both `sta::assert_failed` and `sta::assert_halt` provide weak definitions and - * can be overridden by the application. `sta::assert_halt` is only called - * via the **STA_HALT** macro which can also be provided by the application. - * - * The default implementation of `sta::assert_failed` uses **STA_DEBUG_PRINT** internally - * and will not generate any output if the **DEBUG_SERIAL** module is disabled. */ #ifndef STA_ASSERT_HPP #define STA_ASSERT_HPP +/** + * @defgroup staCore Core + * @brief STA Core library + */ + +/** + * @defgroup staCoreBuildConfig Build Config + * @ingroup staCore + * @brief Build configuration options + */ + +/** + * @defgroup staCoreAssert Assert + * @ingroup staCore + * @brief Assertion handling. + */ + +#ifdef DOXYGEN +/** + * @def STA_ASSERT_ENABLE + * @brief Enable module. + * + * Automatically defined if DEBUG is defined. + * Automatically disabled if NDEBUG is defined. + * + * @ingroup staCoreBuildConfig + */ +# define STA_ASSERT_ENABLE + +/** + * @def STA_ASSERT_DISABLE + * @brief Force disable module. + * + * Overrides STA_ASSERT_ENABLE option. + * + * @ingroup staCoreBuildConfig + */ +# define STA_ASSERT_DISABLE +#endif // DOXYGEN + + #include #ifdef DEBUG @@ -33,6 +61,12 @@ #endif // NDEBUG || STA_ASSERT_DISABLE +// Show enabled module in doxygen output +#ifdef DOXYGEN +# define STA_ASSERT_ENABLE +#endif // DOXYGEN + + #ifdef STA_ASSERT_ENABLE #include @@ -43,19 +77,36 @@ namespace sta /** * @brief Handle failed assertions. * + * The default implementation uses **STA_DEBUG_PRINT** and will not + * generate any output if the **DEBUG_SERIAL** module is disabled. + * + * Weak implementation can be overridden. + * * @param expr Asserted expression or message * @param file File name * @param line Line number + * + * @ingroup staCoreAssert */ void assert_failed(const char * expr, const char * file, uint32_t line); + /** * @brief Stop execution. + * + * Weak implementation can be overridden. + * + * @ingroup staCoreAssert */ void assert_halt(); } // namespace sta -// Use assert_halt if STA_HALT is not defined +/** + * @def STA_HALT + * @brief Set function called after failed asserts. + * + * @ingroup staCoreBuildConfig + */ # ifndef STA_HALT # define STA_HALT() sta::assert_halt() # endif // !STA_HALT @@ -65,62 +116,47 @@ namespace sta * @brief Assert expression. * * @param expr Expression + * + * @ingroup staCoreAssert */ -# define STA_ASSERT(expr) ((void)(!(expr) && (sta::assert_failed(#expr, __FILE__, __LINE__), 1) && (STA_HALT(), 1))) +# define STA_ASSERT(expr) ( (void)( !(expr) && ( sta::assert_failed(#expr, __FILE__, __LINE__), 1 ) && ( STA_HALT(), 1 ) ) ) /** * @brief Assert expression. * * @param expr Expression * @param msg Message shown on failure + * + * @ingroup staCoreAssert */ -# define STA_ASSERT_MSG(expr, msg) ((void)(!(expr) && (sta::assert_failed(msg, __FILE__, __LINE__), 1) && (STA_HALT(), 1))) +# define STA_ASSERT_MSG(expr, msg) ( (void)( !(expr) && ( sta::assert_failed(msg, __FILE__, __LINE__), 1 ) && ( STA_HALT(), 1 ) ) ) /** * @brief Assert expression if condition is true. * * @param cond Condition * @param expr Expression + * + * @ingroup staCoreAssert */ -# define STA_ASSERT_COND(cond, expr) ((void)((cond) ? STA_ASSERT(expr) : 1)) +# define STA_ASSERT_COND(cond, expr) ( (void)( (cond) ? STA_ASSERT(expr) : 1 ) ) /** * @brief Assert expression if condition is true. * * @param cond Condition * @param expr Expression * @param msg Message shown on failure + * + * @ingroup staCoreAssert */ -# define STA_ASSERT_COND_MSG(cond, expr, msg) ((void)((cond) ? STA_ASSERT_MSG(expr, msg))) +# define STA_ASSERT_COND_MSG(cond, expr, msg) ( (void)( (cond) ? STA_ASSERT_MSG(expr, msg) ) ) #else // !STA_ASSERT_ENABLE -/** - * @brief Assert expression. - * - * @param expr Expression - */ -# define STA_ASSERT(expr, msg) ((void)0) -/** - * @brief Assert expression. - * - * @param expr Expression - * @param msg Message shown on failure - */ -# define STA_ASSERT_MSG(expr, msg) ((void)0) -/** - * @brief Assert expression if condition is true. - * - * @param cond Condition - * @param expr Expression - */ -# define STA_ASSERT_COND(cond, expr) ((void)0) -/** - * @brief Assert expression if condition is true. - * - * @param cond Condition - * @param expr Expression - * @param msg Message shown on failure - */ +# define STA_ASSERT(expr) ((void)0) +# define STA_ASSERT_MSG(expr, msg) ((void)0) +# define STA_ASSERT_COND(cond, expr) ((void)0) # define STA_ASSERT_COND_MSG(cond, expr, msg) ((void)0) #endif // !STA_ASSERT_ENABLE + #endif // STA_ASSERT_HPP diff --git a/include/sta/debug_serial.hpp b/include/sta/debug_serial.hpp index c997e23..6a2b964 100644 --- a/include/sta/debug_serial.hpp +++ b/include/sta/debug_serial.hpp @@ -1,4 +1,5 @@ /** + * @file * @brief Debug output via UART. * * Configuration: @@ -15,17 +16,55 @@ #ifndef STA_DEBUG_SERIAL_HPP #define STA_DEBUG_SERIAL_HPP +/** + * @defgroup staCoreDebug Debug Serial + * @ingroup staCore + * @brief Debug serial output. + */ + +#ifdef DOXYGEN +/** + * @def STA_DEBUG_SERIAL_ENABLE + * @brief Enable module. + * + * Automatically defined if DEBUG is defined. + * Automatically disabled if NDEBUG is defined. + * + * @ingroup staCoreBuildConfig + */ +# define STA_DEBUG_SERIAL_ENABLE + +/** + * @def STA_DEBUG_SERIAL_DISABLE + * @brief Force disable module. + * + * Overrides STA_DEBUG_SERIAL_ENABLE option. + * + * @ingroup staCoreBuildConfig + */ +# define STA_DEBUG_SERIAL_DISABLE +#endif // DOXYGEN + + #include -// Check only if STA_DEBUG_SERIAL_FORCE is not defined -#ifndef STA_DEBUG_SERIAL_FORCE -// Disable module if NDEBUG is defined or DEBUG is not -# if defined(NDEBUG) || !defined(DEBUG) -# ifdef STA_DEBUG_SERIAL_ENABLE -# undef STA_DEBUG_SERIAL_ENABLE -# endif // STA_DEBUG_SERIAL_ENABLE -# endif // NDEBUG || !DEBUG -#endif // !STA_DEBUG_SERIAL_FORCE +#ifdef DEBUG +# ifndef STA_DEBUG_SERIAL_ENABLE +# define STA_DEBUG_SERIAL_ENABLE +# endif // !STA_DEBUG_SERIAL_ENABLE +#endif // DEBUG + +#if defined(NDEBUG) || defined(STA_DEBUG_SERIAL_DISABLE) +# ifdef STA_DEBUG_SERIAL_ENABLE +# undef STA_DEBUG_SERIAL_ENABLE +# endif // STA_DEBUG_SERIAL_ENABLE +#endif // NDEBUG || STA_DEBUG_SERIAL_DISABLE + + +// Show enabled module in doxygen output +#ifdef DOXYGEN +# define STA_DEBUG_SERIAL_ENABLE +#endif // DOXYGEN #ifdef STA_DEBUG_SERIAL_ENABLE @@ -35,15 +74,35 @@ namespace sta { + /** + * @brief %UART print object for debug serial output. + * + * @ingroup staCoreDebug + */ extern PrintableUART DebugSerial; } // namespace sta +/** + * @brief Print debug output to UART. + * + * @param ... See @ref sta::PrintableUART::print + * + * @ingroup staCoreDebug + */ # define STA_DEBUG_PRINT(...) sta::DebugSerial.print(__VA_ARGS__) +/** + * @brief Print debug output followed by new-line to UART. + * + * @param ... See @ref sta::PrintableUART::println + * + * @ingroup staCoreDebug + */ # define STA_DEBUG_PRINTLN(...) sta::DebugSerial.println(__VA_ARGS__) #else // !STA_DEBUG_SERIAL_ENABLE # define STA_DEBUG_PRINT(...) ((void)0) # define STA_DEBUG_PRINTLN(...) ((void)0) #endif // !STA_DEBUG_SERIAL_ENABLE + #endif // STA_DEBUG_SERIAL_HPP diff --git a/include/sta/endian.hpp b/include/sta/endian.hpp index cdec661..41abaa2 100644 --- a/include/sta/endian.hpp +++ b/include/sta/endian.hpp @@ -1,9 +1,16 @@ /** + * @file * @brief Helper macros for managing endian handling. */ #ifndef STA_ENDIAN_HPP #define STA_ENDIAN_HPP +/** + * @defgroup staCoreEndian Endian + * @ingroup staCore + * @brief Endian handling. + */ + #include #if !defined(STA_MCU_BIG_ENDIAN) && !defined(STA_MCU_LITTLE_ENDIAN) @@ -16,6 +23,8 @@ * * @param u16 16-bit input value * @return 16-bit value w/ swapped byte order + * + * @ingroup staCoreEndian */ #define STA_UINT16_SWAP_BYTE_ORDER(u16) \ ( \ @@ -28,6 +37,8 @@ * * @param u32 32-bit input value * @return 32-bit value w/ swapped byte order + * + * @ingroup staCoreEndian */ #define STA_UINT32_SWAP_BYTE_ORDER(u32) \ ( \ @@ -42,6 +53,8 @@ * * @param u16 16-bit input value * @return Initializer list for uint8_t[2] + * + * @ingroup staCoreEndian */ #define STA_UINT16_TO_BYTES_BE(u16) \ { \ @@ -54,6 +67,8 @@ * * @param u16 16-bit input value * @return Initializer list for uint8_t[2] + * + * @ingroup staCoreEndian */ #define STA_UINT16_TO_BYTES_LE(u16) \ { \ @@ -66,6 +81,8 @@ * * @param u32 32-bit input value * @return Initializer list for uint8_t[4] + * + * @ingroup staCoreEndian */ #define STA_UINT32_TO_BYTES_BE(u32) \ { \ @@ -80,6 +97,8 @@ * * @param u32 32-bit input value * @return Initializer list for uint8_t[4] + * + * @ingroup staCoreEndian */ #define STA_UINT32_TO_BYTES_LE(u32) \ { \ @@ -90,132 +109,95 @@ } +/** + * @defe STA_UINT16_TO_BE(u16) + * @brief Convert 16-bit value to big-endian byte order. + * + * @param u16 16-bit input value + * @return 16-bit value w/ big-endian byte order + */ + +/** + * @def STA_UINT16_TO_LE(u16) + * @brief Convert 16-bit value to little-endian byte order. + * + * @param u16 16-bit input value + * @return 16-bit value w/ little-endian byte order + */ + +/** + * @def STA_UINT16_TO_BYTES(u16) + * @brief Get initializer list for byte array w/ MCU byte order from 16-bit value. + * + * @param u16 16-bit input value + * @return Initializer list for uint8_t[2] + */ + +/** + * @def STA_UINT16_TO_BYTES_SWAP(u16) + * @brief Get initializer list for byte array w/ swapped MCU byte order from 16-bit value. + * + * @param u16 16-bit input value + * @return Initializer list for uint8_t[2] + */ + +/** + * @def STA_UINT32_TO_BE(u32) + * @brief Convert 32-bit value to big-endian byte order. + * + * @param u32 32-bit input value + * @return 32-bit value w/ big-endian byte order + */ + +/** + * @def STA_UINT32_TO_LE(u32) + * @brief Convert 32-bit value to little-endian byte order. + * + * @param u32 32-bit input value + * @return 32-bit value w/ little-endian byte order + */ + +/** + * @def STA_UINT32_TO_BYTES(u32) + * @brief Get initializer list for byte array from 32-bit value. + * + * @param u32 32-bit input value + * @return Initializer list for uint8_t[4] + */ + +/** + * @def STA_UINT32_TO_BYTES_SWAP(u32) + * @brief Get initializer list for byte array w/ swapped byte order from 32-bit value. + * + * @param u32 32-bit input value + * @return Initializer list for uint8_t[4] + */ + #ifdef STA_MCU_LITTLE_ENDIAN - -/** - * @brief Convert 16-bit value to big-endian byte order. - * - * @param u16 16-bit input value - * @return 16-bit value w/ big-endian byte order - */ # define STA_UINT16_TO_BE(u16) STA_UINT16_SWAP_BYTE_ORDER(u16) -/** - * @brief Convert 16-bit value to little-endian byte order. - * - * @param u16 16-bit input value - * @return 16-bit value w/ little-endian byte order - */ # define STA_UINT16_TO_LE(u16) (u16) -/** - * @brief Get initializer list for byte array w/ MCU byte order from 16-bit value. - * - * @param u16 16-bit input value - * @return Initializer list for uint8_t[2] - */ # define STA_UINT16_TO_BYTES(u16) STA_UINT16_TO_BYTES_LE(u16) -/** - * @brief Get initializer list for byte array w/ swapped MCU byte order from 16-bit value. - * - * @param u16 16-bit input value - * @return Initializer list for uint8_t[2] - */ -# define STA_UINT16_TO_BYTES_SWAP(u16) STA_UINT16_TO_BYTES_BE(u16) +# define STA_UINT16_TO_BYTES_SWAP(u16) STA_UINT16_TO_BYTES_BE(u16) -/** - * @brief Convert 32-bit value to big-endian byte order. - * - * @param u32 32-bit input value - * @return 32-bit value w/ big-endian byte order - */ # define STA_UINT32_TO_BE(u32) STA_UINT32_SWAP_BYTE_ORDER(u32) -/** - * @brief Convert 32-bit value to little-endian byte order. - * - * @param u32 32-bit input value - * @return 32-bit value w/ little-endian byte order - */ # define STA_UINT32_TO_LE(u32) (u32) -/** - * @brief Get initializer list for byte array from 32-bit value. - * - * @param u32 32-bit input value - * @return Initializer list for uint8_t[4] - */ # define STA_UINT32_TO_BYTES(u32) STA_UINT32_TO_BYTES_LE(u32) -/** - * @brief Get initializer list for byte array w/ swapped byte order from 32-bit value. - * - * @param u32 32-bit input value - * @return Initializer list for uint8_t[4] - */ # define STA_UINT32_TO_BYTES_SWAP(u32) STA_UINT32_TO_BYTES_BE(u32) - #elif STA_MCU_BIG_ENDIAN - -/** - * @brief Convert 16-bit value to big-endian byte order. - * - * @param u16 16-bit input value - * @return 16-bit value w/ big-endian byte order - */ # define STA_UINT16_TO_BE(u16) (u16) -/** - * @brief Convert 16-bit value to little-endian byte order. - * - * @param u16 16-bit input value - * @return 16-bit value w/ little-endian byte order - */ # define STA_UINT16_TO_LE(u16) STA_UINT16_SWAP_BYTE_ORDER(u16) -/** - * @brief Get initializer list for byte array w/ MCU byte order from 16-bit value. - * - * @param u16 16-bit input value - * @return Initializer list for uint8_t[2] - */ # define STA_UINT16_TO_BYTES(u16) STA_UINT16_TO_BYTES_BE(u16) -/** - * @brief Get initializer list for byte array w/ swapped MCU byte order from 16-bit value. - * - * @param u16 16-bit input value - * @return Initializer list for uint8_t[2] - */ # define STA_UINT16_TO_BYTES_SWAP(u16) STA_UINT16_TO_BYTES_LE(u16) - -/** - * @brief Convert 32-bit value to big-endian byte order. - * - * @param u32 32-bit input value - * @return 32-bit value w/ big-endian byte order - */ # define STA_UINT32_TO_BE(u32) (u32) -/** - * @brief Convert 32-bit value to little-endian byte order. - * - * @param u32 32-bit input value - * @return 32-bit value w/ little-endian byte order - */ # define STA_UINT32_TO_LE(u32) STA_UINT32_SWAP_BYTE_ORDER(u32) -/** - * @brief Get initializer list for byte array from 32-bit value. - * - * @param u32 32-bit input value - * @return Initializer list for uint8_t[4] - */ # define STA_UINT32_TO_BYTES(u32) STA_UINT32_TO_BYTES_BE(u32) -/** - * @brief Get initializer list for byte array w/ swapped byte order from 32-bit value. - * - * @param u32 32-bit input value - * @return Initializer list for uint8_t[4] - */ # define STA_UINT32_TO_BYTES_SWAP(u32) STA_UINT32_TO_BYTES_LE(u32) - #endif // STA_MCU_BIG_ENDIAN diff --git a/include/sta/enum_flags.hpp b/include/sta/enum_flags.hpp index c480698..f848487 100644 --- a/include/sta/enum_flags.hpp +++ b/include/sta/enum_flags.hpp @@ -1,4 +1,5 @@ /** + * @file * @brief Helper for using enum values as flags. */ #ifndef STA_ENUM_FLAGS_HPP @@ -13,6 +14,8 @@ namespace sta * @brief 32-bit flag register with enum type representing single flag bits. * * @tparam F Enum type used for flag bits + * + * @ingroup staCore */ template class EnumFlags @@ -151,6 +154,8 @@ namespace sta * @brief Provide overload for operator | to combine enum values. * * @param enumType Enum type to overload + * + * @ingroup staCore */ #define STA_ENUM_FLAGS_OVERLOAD(enumType) \ sta::EnumFlags operator |(enumType lhs, enumType rhs) \ @@ -162,6 +167,8 @@ namespace sta * @brief Declare alias for sta::EnumFlags specialization. * * @param enumType Enum type for specialization + * + * @ingroup staCore */ #define STA_ENUM_FLAGS_ALIAS(enumType) \ using enumType ## Flags = sta::EnumFlags @@ -172,6 +179,8 @@ namespace sta * @param enumType Name of new enum class * @param value1 First enum value * @param ... Enum values 2 - 32 + * + * @ingroup staCore */ #define STA_ENUM_FLAGS_DECL(enumType, value1, ...) \ enum class enumType \ diff --git a/include/sta/fifo_buffer.hpp b/include/sta/fifo_buffer.hpp index e9fc768..2971712 100644 --- a/include/sta/fifo_buffer.hpp +++ b/include/sta/fifo_buffer.hpp @@ -1,3 +1,7 @@ +/** + * @file + * @brief FIFO buffer type. + */ #ifndef STA_FIFO_BUFFER_HPP #define STA_FIFO_BUFFER_HPP @@ -9,6 +13,8 @@ namespace sta * * @tparam Size Size type * @tparam N Buffer size + * + * @ingroup staCore */ template class FifoBuffer diff --git a/include/sta/lang.hpp b/include/sta/lang.hpp index 02b8046..a09b2ba 100644 --- a/include/sta/lang.hpp +++ b/include/sta/lang.hpp @@ -1,34 +1,66 @@ /** + * @file * @brief Helper for useful compiler features. */ #ifndef STA_LANG_HPP #define STA_LANG_HPP +/** + * @defgroup staCoreLang Lang + * @ingroup staCore + * @brief Compiler instructions. + * @{ + */ + +/** + * @brief Assembler instruction. + */ #ifndef STA_ASM # define STA_ASM __asm #endif // STA_ASM +/** + * @brief Mark as deprecated. + */ #ifndef STA_DEPRECATED # define STA_DEPRECATED __attribute__((deprecated)) #endif // STA_DEPRECATED +/** + * @brief Mark as weak definition. + */ #ifndef STA_WEAK # define STA_WEAK __attribute__((weak)) #endif // STA_WEAK + +/** + * @brief Mark as field w/o added padding. + */ #ifndef STA_PACKED # define STA_PACKED __attribute__((packed)) #endif // STA_PACKED +/** + * @brief Mark as struct w/o added padding. + */ #ifndef STA_PACKED_STRUCT # define STA_PACKED_STRUCT struct STA_PACKED #endif // STA_PACKED_STRUCT +/** + * @brief Mark as union w/o added padding. + */ #ifndef STA_PACKED_UNION # define STA_PACKED_UNION union STA_PACKED #endif // STA_PACKED_UNION +/** + * @brief Add breakpoint. + * + * @param value Additional uint16_t data for debugger + */ #ifndef STA_BKPT # define STA_BKPT(value) STA_ASM volatile ("bkpt "#value) #endif // STA_BKPT @@ -37,17 +69,48 @@ // TODO Check for GCC /** - * @brief Helper for silencing compiler warnings in unreachable code locations. + * @brief Silencing compiler warnings in unreachable code locations. * - * Example: Default of switch handling all cases of enum class + * Example: + * @code + * enum class E { A }; + * + * E val = A; + * + * switch (val) + * { + * case E::A: + * break; + * + * default: + * // All enum values already handled + * STA_UNREACHABLE(); + * } + * @endcode */ #ifndef STA_UNREACHABLE # define STA_UNREACHABLE() __builtin_unreachable() #endif // !STA_UNREACHABLE +/** + * @brief Silencing compiler warnings for intended switch case fallthrough. + * + * Example: + * @code + * switch (val) + * { + * case A: STA_FALLTHROUGH(); + * case B: + * do(); + * break; + * } + * @endcode + */ #ifndef STA_FALLTRHOUGH # define STA_FALLTHROUGH() __attribute__((fallthrough)) #endif // !STA_FALLTRHOUGH +/** @} */ + #endif // STA_LANG_HPP diff --git a/include/sta/printable_uart.hpp b/include/sta/printable_uart.hpp index 38c2912..35e62eb 100644 --- a/include/sta/printable_uart.hpp +++ b/include/sta/printable_uart.hpp @@ -15,6 +15,8 @@ namespace sta { /** * @brief Integer representation. + * + * @ingroup staCore */ enum class IntegerBase { @@ -25,6 +27,8 @@ namespace sta /** * @brief Printable interface for UART. + * + * @ingroup staCore */ class PrintableUART { diff --git a/include/sta/printf.hpp b/include/sta/printf.hpp index 7074460..a48de80 100644 --- a/include/sta/printf.hpp +++ b/include/sta/printf.hpp @@ -1,9 +1,29 @@ /** - * @brief Compatibility layer for different `printf` implementations. + * @file + * @brief Compatibility layer for different printf implementations. */ #ifndef STA_PRINTF_HPP #define STA_PRINTF_HPP +#ifdef DOXYGEN +/** + * @def STA_PRINTF_USE_STDLIB + * @brief Use printf implementation from STD library. + * + * @ingroup staCoreBuildConfig + */ +# define STA_PRINTF_USE_STDLIB + +/** + * @def STA_PRINTF_USE_MPALAND + * @brief Use printf implementation from Marco Paland. + * + * @ingroup staCoreBuildConfig + */ +# define STA_PRINTF_USE_MPALAND +#endif // DOXYGEN + + #include #if !defined(STA_PRINTF_USE_STDLIB) && !defined(STA_PRINTF_USE_MPALAND)