ALPAKA/sta-core
1
0
Fork 0
mirror of https://git.intern.spaceteamaachen.de/ALPAKA/sta-core.git synced 2025-06-10 16:55:58 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add doxygen docs

Browse Source
This commit is contained in:
Henrik Stickann 2022-05-10 15:36:48 +02:00
parent 8efed8802d
commit f4e3a0ae1c
8 changed files with 339 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
include/sta/assert.hpp
View File

@ -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 <sta/config.hpp>
#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 <cstdint>
@ -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

77
include/sta/debug_serial.hpp
View File

@ -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 <sta/config.hpp>
// 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

186
include/sta/endian.hpp
View File

@ -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 <sta/config.hpp>
#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

9
include/sta/enum_flags.hpp
View File

@ -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 <typename F>
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<enumType> 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<enumType>
@ -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 \

6
include/sta/fifo_buffer.hpp
View File

@ -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 <typename Size, Size N>
class FifoBuffer

67
include/sta/lang.hpp
View File

@ -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

4
include/sta/printable_uart.hpp
View File

@ -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
{

22
include/sta/printf.hpp
View File

@ -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 <sta/config.hpp>
#if !defined(STA_PRINTF_USE_STDLIB) && !defined(STA_PRINTF_USE_MPALAND)