Improve README and doxygen comments

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 <func_name>`: 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 `<sta/config.hpp>` 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 <tim_handle>`: 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.

include/sta/assert.hpp

@@ -1,17 +1,19 @@
 /**
  * @brief Assertion handling.
  *
- * Define **STA_ASSERT_ENABLE** in `<sta/config.hpp>` 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 `<sta/debug_serial.hpp> 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

include/sta/debug_serial.hpp

@@ -1,12 +1,13 @@
 /**
  * @brief Debug output via UART.
  *
- * Define **STA_DEBUG_SERIAL_ENABLE** in `<sta/config.hpp>` 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.

include/sta/endian.hpp

@@ -1,3 +1,6 @@
+/**
+ * @brief Helper macros for managing endian handling.
+ */
 #ifndef STA_ENDIAN_HPP
 #define STA_ENDIAN_HPP
 

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
 

include/sta/enum_flags.tpp

@@ -1,3 +1,6 @@
+/**
+ * @brief Template class implementation for `EnumFlags<T>`.
+ */
 #ifndef STA_ENUM_FLAGS_TPP
 #define STA_ENUM_FLAGS_TPP
 

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 <sta/config.hpp>
 #ifdef STA_HAL_DELAY_ENABLE
 
+#include <cstdint>
+
 
 namespace sta
 {

src/hal/delay.cpp

@@ -1,7 +1,10 @@
 #include <sta/hal/delay.hpp>
 #ifdef STA_HAL_DELAY_ENABLE
 
-#include <main.h>
+#include <sta/assert.hpp>
+#include <sta/hal.hpp>
+#include <sta/lang.hpp>
+#include <sta/hal/clocks.hpp>
 
 
 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