From ecfad2e7680ae8286d008fd6a80d2c9c4892abdb Mon Sep 17 00:00:00 2001 From: Henrik Stickann <4376396-Mithradir@users.noreply.gitlab.com> Date: Sun, 24 Apr 2022 13:42:34 +0200 Subject: [PATCH] Improve README and doxygen comments --- README.md | 79 ++++++++++++++++++++++++++++++++++-- include/sta/assert.hpp | 20 +++++---- include/sta/debug_serial.hpp | 11 ++--- include/sta/endian.hpp | 3 ++ include/sta/enum_flags.hpp | 3 ++ include/sta/enum_flags.tpp | 3 ++ include/sta/hal/delay.hpp | 8 ++-- src/hal/delay.cpp | 35 +++++++++++++++- 8 files changed, 141 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index a9f1e12..e273c9a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,81 @@ -# Helpers +# STA Core library Collection of useful stuff. -## lang.hpp -Macros related to compiler features. Not actually part of the language so renaming would be advised. +# Modules + + +## Assert + +Assertion handling. + +Configuration: +* `#define STA_ASSERT_ENABLE`: Enable module +* `#define STA_ASSERT_DISABLE`: Forces module off when defined +* `#define 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. + + +## Debug Serial + +Debug serial output macros. + +Configuration: +* `#define STA_DEBUG_SERIAL_ENABLE`: Enable module +* `#define STA_DEBUG_SERIAL_DISABLE`: Forces module off when defined +* `DEBUG`: Automatically enables module when defined +* `NDEBUG`: Forces module off when defined + +The `sta::DebugSerial` instance must be provided. + + +## Endian + +Endian-ness conversion for multi-byte types. + + +## Enum Flags + +Type for using enum values as combinable flags. + + +## Lang + +Macros related to compiler features. Not actually part of the C/C++ language. + + +## MCU + +Defines specific to different MCUs. Include the appropriate header from `sta/mcu` +for the MCU used by the application in the `` header. + + +## Printf + +Choose which `printf` implementation is used by STA libraries. + +Configuration: +* `#define STA_PRINTF_USE_STDLIB`: Use the stdlib implementation +* `#define STA_PRINTF_USE_MPALAND`: Use the implementation by Marco Paland (thread safe & reentrant) + + +## HAL Delay + +HAL based delay functions. + +Configuration: +* `#define STA_HAL_DELAY_ENABLE`: Enable module +* `#define STA_HAL_DELAY_US_TIM `: 1 MHz TIM instance used by `sta::delayUs` + +TIM time base must be started before using `sta::delayUs` by calling `sta::initHAL`. +When using the startup system task this is handled automatically. \ No newline at end of file diff --git a/include/sta/assert.hpp b/include/sta/assert.hpp index 9974f11..40f5886 100644 --- a/include/sta/assert.hpp +++ b/include/sta/assert.hpp @@ -1,17 +1,19 @@ /** * @brief Assertion handling. * - * Define **STA_ASSERT_ENABLE** in `` to enable module. + * 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 * - * When **DEBUG** is defined the module will be enabled automatically. - * Defining **NDEBUG** or **STA_ASSERT_DISABLE** always overrides enabling the module. + * 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. * - * Both `assert_failed` and `assert_halt` provide weak definitions and - * can be overridden by the application. `assert_halt` is only called - * via the STA_HALT macro which can also be provided by the application. - * - * The default implementation of `assert_failed` uses **STA_DEBUG_PRINT** internally - * and will not generate any output if ` is disabled. + * 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 diff --git a/include/sta/debug_serial.hpp b/include/sta/debug_serial.hpp index a42e736..8bf151e 100644 --- a/include/sta/debug_serial.hpp +++ b/include/sta/debug_serial.hpp @@ -1,12 +1,13 @@ /** * @brief Debug output via UART. * - * Define **STA_DEBUG_SERIAL_ENABLE** in `` to enable module. + * Configuration: + * STA_DEBUG_SERIAL_ENABLE: Enable module + * STA_DEBUG_SERIAL_DISABLE: Forces module off when defined + * DEBUG: Automatically enables module when defined + * NDEBUG: Forces module off when defined * - * When **DEBUG** is defined the module will be enabled automatically. - * Defining **NDEBUG** or **STA_DEBUG_SERIAL_DISABLE** always overrides enabling the module. - * - * The sta::DebugSerial instance must be provided. + * The `sta::DebugSerial` instance must be provided. * NOTE: Include this header before the definition because * the default internal linkage of const namespace variables * will cause undefined reference errors otherwise. diff --git a/include/sta/endian.hpp b/include/sta/endian.hpp index 9f721d9..cdec661 100644 --- a/include/sta/endian.hpp +++ b/include/sta/endian.hpp @@ -1,3 +1,6 @@ +/** + * @brief Helper macros for managing endian handling. + */ #ifndef STA_ENDIAN_HPP #define STA_ENDIAN_HPP diff --git a/include/sta/enum_flags.hpp b/include/sta/enum_flags.hpp index dcd999b..0ef7101 100644 --- a/include/sta/enum_flags.hpp +++ b/include/sta/enum_flags.hpp @@ -1,3 +1,6 @@ +/** + * @brief Helper for using enum values as flags. + */ #ifndef STA_ENUM_FLAGS_HPP #define STA_ENUM_FLAGS_HPP diff --git a/include/sta/enum_flags.tpp b/include/sta/enum_flags.tpp index 89107e4..3321973 100644 --- a/include/sta/enum_flags.tpp +++ b/include/sta/enum_flags.tpp @@ -1,3 +1,6 @@ +/** + * @brief Template class implementation for `EnumFlags`. + */ #ifndef STA_ENUM_FLAGS_TPP #define STA_ENUM_FLAGS_TPP diff --git a/include/sta/hal/delay.hpp b/include/sta/hal/delay.hpp index afb2b5f..c547b50 100644 --- a/include/sta/hal/delay.hpp +++ b/include/sta/hal/delay.hpp @@ -3,10 +3,10 @@ * * Configuration: * STA_HAL_DELAY_ENABLE: Enable module - * STA_HAL_DELAY_US_TIM: HAL TIM instance for `delayUs()` + * STA_HAL_DELAY_US_TIM: 1 MHz TIM instance used by `sta::delayUs` * - * NOTE: Don't forget to start TIM. When using startup system task this - * is automatically handled. + * NOTE: TIM time base must be started before use of `sta::delayUs` by calling `sta::initHAL`. + * When using startup system task this is handled automatically. */ #ifndef STA_HAL_DELAY_HPP #define STA_HAL_DELAY_HPP @@ -14,6 +14,8 @@ #include #ifdef STA_HAL_DELAY_ENABLE +#include + namespace sta { diff --git a/src/hal/delay.cpp b/src/hal/delay.cpp index 9e4a0d0..a0d2724 100644 --- a/src/hal/delay.cpp +++ b/src/hal/delay.cpp @@ -1,7 +1,10 @@ #include #ifdef STA_HAL_DELAY_ENABLE -#include +#include +#include +#include +#include namespace sta @@ -24,6 +27,36 @@ namespace sta __HAL_TIM_SET_COUNTER(&STA_HAL_DELAY_US_TIM, 0); while (__HAL_TIM_GET_COUNTER(&STA_HAL_DELAY_US_TIM) < us); } + + + bool isValidDelayUsTIM() + { + // Get PCLK multiplier for TIM clock + uint32_t pclkMul = 1; + switch (STA_HAL_DELAY_US_TIM.Init.ClockDivision) + { + case TIM_CLOCKDIVISION_DIV1: + pclkMul = 1; + break; + case TIM_CLOCKDIVISION_DIV2: + pclkMul = 2; + break; + case TIM_CLOCKDIVISION_DIV4: + pclkMul = 4; + break; + default: + STA_ASSERT(false); + STA_UNREACHABLE(); + } + + // Calculate TIM clock frequency + uint32_t clkFreq = pclkMul * STA_HAL_GET_HANDLE_PCLK_FREQ_FN(STA_HAL_DELAY_US_TIM)(); + // Calculate update frequency based on prescaler value + uint32_t updateFreq = clkFreq / STA_HAL_DELAY_US_TIM.Init.Prescaler; + + // TIM must have at least microsecond precision (>= 1 MHz frequency) + return (updateFreq == 1000000); + } } // namespace sta #endif // STA_HAL_DELAY_US_TIM