Refactor debug infrastructure with module-specific macros

Replace the global `NDEBUG`-based debug toggle with a per-module debug header system. Each library (board, configstore, display, dmx, pixel, rdm, hwclock, etc.) now gets its own `*_debug.h` header with `MODULE_DEBUG_ENTRY/EXIT/PRINTF/PUTS` macros controlled by `DEBUG_<MODULE>` defines.

Key changes:
- Refactor `debug_config.h` into `debug::config` namespace with granular flags for assertions, trace, dump, and stack monitoring
- `DEBUG_ENTRY/EXIT/PRINTF/PUTS` now use `if constexpr` on `kTraceEnabled` instead of `#ifdef NDEBUG` guards
- Remove `#undef NDEBUG` hacks from source files
- Rename `DEBUG_STACK` to `CONFIG_DEBUG_STACK` for consistency
- Add `cerrno` C++ wrapper header
- Improve `cctype` and `cstdlib` wrappers with proper `std::` namespace exports
- Add ANSI color output to error messages in malloc and softwaretimers
- Add `[[nodiscard]]` attributes to various getter methods

Author: vanvught

common/include/firmware/debug/debug_config.h

@@ -26,12 +26,30 @@
 #ifndef FIRMWARE_DEBUG_DEBUG_CONFIG_H_
 #define FIRMWARE_DEBUG_DEBUG_CONFIG_H_
 
-namespace debug {
-#ifdef NDEBUG
-constexpr bool kIsDebug = false;
+namespace debug::config {
+#if defined(NDEBUG)
+inline constexpr bool kAssertionsEnabled = false;
 #else
-constexpr bool kIsDebug = true;
+inline constexpr bool kAssertionsEnabled = true;
 #endif
-} // namespace debug
+
+#if defined(CONFIG_DEBUG_TRACE) // DEBUG_ENTRY, DEBUG_EXIT, DEBUG_PRINTF
+inline constexpr bool kTraceEnabled = true;
+#else
+inline constexpr bool kTraceEnabled = false;
+#endif
+
+#if defined(CONFIG_DEBUG_DUMP) // Dump(), PrintBits()
+inline constexpr bool kDumpEnabled = true;
+#else
+inline constexpr bool kDumpnabled = false;
+#endif
+
+#if defined(CONFIG_DEBUG_STACK) // Stack monitoring
+inline constexpr bool kStackMonitoringEnabled = true;
+#else
+inline constexpr bool kStackMonitoringEnabled = false;
+#endif
+} // namespace debug::config
 
 #endif // FIRMWARE_DEBUG_DEBUG_CONFIG_H_

common/include/firmware/debug/debug_debug.h

@@ -26,51 +26,47 @@
 #ifndef FIRMWARE_DEBUG_DEBUG_H_
 #define FIRMWARE_DEBUG_DEBUG_H_
 
-#if !defined(NDEBUG)
 #include <cstdio>
 #include <source_location>
 
-#define DEBUG_ENTRY()                                                                                      \
-    do {                                                                                                   \
-        const std::source_location loc = std::source_location::current();                                  \
-        printf("-> %s(%u):%s\n", loc.file_name(), static_cast<unsigned>(loc.line()), loc.function_name()); \
-    } while (0)
+#include "firmware/debug/debug_config.h"
 
-#define DEBUG_EXIT()                                                                                       \
-    do {                                                                                                   \
-        const std::source_location loc = std::source_location::current();                                  \
-        printf("<- %s(%u):%s\n", loc.file_name(), static_cast<unsigned>(loc.line()), loc.function_name()); \
-    } while (0)
+#define DEBUG_ENTRY()                                                          \
+    do {                                                                       \
+        if constexpr (::debug::config::kTraceEnabled) {                        \
+            const auto location = std::source_location::current();             \
+            printf("-> %s(%u):%s\n",                                           \
+                   location.file_name(),                                       \
+                   static_cast<unsigned>(location.line()),                     \
+                   location.function_name());                                  \
+        }                                                                      \
+    } while (false)
 
-#define DEBUG_PRINTF(fmt, ...)                                                                                                                 \
-    do {                                                                                                                                       \
-        const std::source_location loc = std::source_location::current();                                                                      \
-        printf("   %s(%u):%s: " fmt "\n", loc.file_name(), static_cast<unsigned>(loc.line()), loc.function_name() __VA_OPT__(, ) __VA_ARGS__); \
-    } while (0)
+#define DEBUG_EXIT()                                                           \
+    do {                                                                       \
+        if constexpr (::debug::config::kTraceEnabled) {                        \
+            const auto location = std::source_location::current();             \
+            printf("<- %s(%u):%s\n",                                           \
+                   location.file_name(),                                       \
+                   static_cast<unsigned>(location.line()),                     \
+                   location.function_name());                                  \
+        }                                                                      \
+    } while (false)
 
-#define DEBUG_PUTS(msg)            \
-    do {                           \
-        DEBUG_PRINTF("%s", (msg)); \
-    } while (0)
+#define DEBUG_PRINTF(format, ...)                                              \
+    do {                                                                       \
+        if constexpr (::debug::config::kTraceEnabled) {                        \
+            const auto location = std::source_location::current();             \
+            printf("   %s(%u):%s: " format "\n",                               \
+                   location.file_name(),                                       \
+                   static_cast<unsigned>(location.line()),                     \
+                   location.function_name() __VA_OPT__(, ) __VA_ARGS__);       \
+        }                                                                      \
+    } while (false)
 
-#else
-
-#define DEBUG_ENTRY() \
-    do {              \
-    } while (0)
-
-#define DEBUG_EXIT() \
-    do {             \
-    } while (0)
-
-#define DEBUG_PRINTF(...) \
-    do {                  \
-    } while (0)
-
-#define DEBUG_PUTS(...) \
-    do {                \
-    } while (0)
-
-#endif
+#define DEBUG_PUTS(message)                                                    \
+    do {                                                                       \
+        DEBUG_PRINTF("%s", (message));                                         \
+    } while (false)
 
 #endif // FIRMWARE_DEBUG_DEBUG_H_

common/include/firmware/debug/debug_dump.h

@@ -34,64 +34,76 @@
 
 namespace debug {
 inline void Dump([[maybe_unused]] const void* data, [[maybe_unused]] uint32_t size) {
-    if constexpr (kIsDebug) {
-        constexpr uint32_t kCharsPerLine = 16;
-        constexpr uint32_t kBytesPerGroup = 8; // Visual separator every 8 bytes
-        const auto* ptr = reinterpret_cast<const uint8_t*>(data);
-        uint32_t chars = 0;
+    if constexpr (!config::kDumpnabled) {
+        return;
+    }
 
-        printf("%p:%u\n", data, static_cast<unsigned>(size));
+    if (size == 0) {
+        puts("<empty>");
+        return;
+    }
 
-        do {
-            printf("%04x ", static_cast<unsigned>(chars));
+    if (data == nullptr) {
+        puts("<null>");
+        return;
+    }
+    constexpr uint32_t kCharsPerLine = 16;
+    constexpr uint32_t kBytesPerGroup = 8; // Visual separator every 8 bytes
+    const auto* ptr = reinterpret_cast<const uint8_t*>(data);
+    uint32_t chars = 0;
 
-            uint32_t chars_this_line = 0;
-            const auto* line_start_ptr = ptr;
+    printf("%p:%u\n", data, static_cast<unsigned>(size));
 
-            while ((chars_this_line < kCharsPerLine) && (chars < size)) {
-                if (chars_this_line % kBytesPerGroup == 0) {
-                    printf(" ");
-                }
+    do {
+        printf("%04x ", static_cast<unsigned>(chars));
 
-                printf("%02x ", *ptr);
+        uint32_t chars_this_line = 0;
+        const auto* line_start_ptr = ptr;
 
-                chars_this_line++;
-                chars++;
-                ptr++;
+        while ((chars_this_line < kCharsPerLine) && (chars < size)) {
+            if (chars_this_line % kBytesPerGroup == 0) {
+                printf(" ");
             }
 
-            auto chars_dot_line = chars_this_line;
+            printf("%02x ", *ptr);
+
+            chars_this_line++;
+            chars++;
+            ptr++;
+        }
 
-            for (; chars_this_line < kCharsPerLine; chars_this_line++) {
-                if (chars_this_line % kBytesPerGroup == 0) {
-                    printf(" ");
-                }
-                printf("   ");
+        auto chars_dot_line = chars_this_line;
+
+        for (; chars_this_line < kCharsPerLine; chars_this_line++) {
+            if (chars_this_line % kBytesPerGroup == 0) {
+                printf(" ");
             }
+            printf("   ");
+        }
 
-            chars_this_line = 0;
+        chars_this_line = 0;
 
-            while (chars_this_line < chars_dot_line) {
-                if (chars_this_line % kBytesPerGroup == 0) {
-                    printf(" ");
-                }
+        while (chars_this_line < chars_dot_line) {
+            if (chars_this_line % kBytesPerGroup == 0) {
+                printf(" ");
+            }
 
-                int character = *line_start_ptr;
-                if (0 != isprint(character)) {
-                    printf("%c", character);
-                } else {
-                    printf(".");
-                }
+            const auto kCharacter = static_cast<unsigned char>(*line_start_ptr);
 
-                chars_this_line++;
-                line_start_ptr++;
+            if (std::isprint(kCharacter) != 0) {
+                printf("%c", static_cast<int>(kCharacter));
+            } else {
+                putchar('.');
             }
 
-            puts("");
+            chars_this_line++;
+            line_start_ptr++;
+        }
 
-        } while (chars < size);
-    }
+        puts("");
+
+    } while (chars < size);
 }
 } // namespace debug
 
-#endif /* COMMON_DEBUG_DEBUG_DUMP_H_ */
+#endif // COMMON_DEBUG_DEBUG_DUMP_H_

common/include/firmware/debug/debug_printbits.h

@@ -32,21 +32,22 @@
 #include "firmware/debug/debug_config.h"
 
 namespace debug {
-inline void PrintBits([[maybe_unused]] uint32_t u) {
-    if constexpr (kIsDebug) {
-        printf("%.8x ", static_cast<unsigned>(u));
-        uint32_t bit = 1U << 31;
-
-        for (uint32_t i = 0; i < 32; i++) {
-            if ((bit & u) == bit) {
-                uint32_t bit_number = 31 - i;
-                printf("%-2u ", static_cast<unsigned>(bit_number));
-            }
-            bit = bit >> 1;
-        }
+inline void PrintBits([[maybe_unused]] uint32_t value) {
+    if constexpr (!config::kTraceEnabled) {
+        return;
+    }
+
+    printf("%.8x ", static_cast<unsigned>(value));
 
-        puts("");
+    for (int bit_number = 31; bit_number >= 0; --bit_number) {
+        const auto kMask = uint32_t{1} << bit_number;
+
+        if ((value & kMask) != 0U) {
+            printf("%d ", bit_number);
+        }
     }
+
+    putchar('\n');
 }
 } // namespace debug
 

common/include/firmware/debug/debug_stack.h

@@ -31,70 +31,93 @@
 #include <cassert>
 
 #include "timing.h"
+#include "firmware/debug/debug_config.h"
 
 extern unsigned char stack_low;
 extern unsigned char _sp; // NOLINT
 
 namespace debug::stack {
-inline static constexpr uint32_t kMagicWord = 0xABCDABCD;
+constexpr uint32_t kMagicWord = 0xABCDABCD;
+namespace implementation {
 
 inline void Print() {
-    static uint32_t s_used_bytes_previous;
-    const auto* start = reinterpret_cast<uint32_t*>(&stack_low);
-    const auto* end = reinterpret_cast<uint32_t*>(&_sp);
-    assert(end > start);
-    const auto kSize = static_cast<uint32_t>(end - start);
-
-    const auto* ptr = start;
+    if constexpr (!config::kStackMonitoringEnabled) {
+        return;
+    }
 
-    while (ptr < end) {
+    static uint32_t s_used_bytes_previous;
+    const auto* start_address = reinterpret_cast<uint32_t*>(&stack_low);
+    const auto* end_address = reinterpret_cast<uint32_t*>(&_sp);
+    assert(end_address > start_address);
+    const auto kSizeWords = static_cast<uint32_t>(end_address - start_address);
+    const auto kSizeBytes = kSizeWords * sizeof(uint32_t);
+    const auto* ptr = start_address;
+
+    while (ptr < end_address) {
         if (*ptr != kMagicWord) {
             break;
         }
         ptr++;
     }
 
-    const auto kUsedBytes = static_cast<uint32_t>(4 * (end - ptr));
-    const auto kFreeBytes = static_cast<uint32_t>(4 * (ptr - start));
-    const auto kFreePct = (static_cast<uint32_t>(ptr - start) * 100U) / kSize;
+    const auto kUsedBytes = static_cast<uint32_t>(end_address - ptr) * sizeof(uint32_t);
+    const auto kFreeBytes = static_cast<uint32_t>(ptr - start_address) * sizeof(uint32_t);
+    const auto kFreePct = static_cast<uint32_t>((static_cast<uint64_t>(ptr - start_address) * 100U) / kSizeWords);
 
     if (s_used_bytes_previous != kUsedBytes) {
         s_used_bytes_previous = kUsedBytes;
 
-        if (kFreePct == 0) {
+        constexpr uint32_t kCriticalFreePercent = 5;
+        constexpr uint32_t kWarningFreePercent = 15;
+
+        if (kFreePct <= kCriticalFreePercent) {
             printf("\x1b[31m");
-        } else if (kFreePct == 1) {
+        } else if (kFreePct <= kWarningFreePercent) {
             printf("\x1b[33m");
         } else {
             printf("\x1b[34m");
         }
 
-#ifndef NDEBUG
-        printf("Stack: Size %uKB, [%p:%p:%p], Used: %u, Free: %u [%u]", 
-			static_cast<unsigned>(kSize / (1024 / 4)), 
-			reinterpret_cast<const void*>(start), 
-			reinterpret_cast<const void*>(ptr), 
-			reinterpret_cast<const void*>(end),
-			static_cast<unsigned>(kUsedBytes), 
-			static_cast<unsigned>(kFreeBytes), 
-			static_cast<unsigned>(kFreePct));
-#else
-        printf("Stack: Size %uKB, Used: %u, Free: %u", static_cast<unsigned>(kSize / (1024 / 4)), 
-			static_cast<unsigned>(kUsedBytes), 
-			static_cast<unsigned>(kFreeBytes));
-#endif
+        if constexpr (!config::kAssertionsEnabled) {
+            printf("Stack: Size %uKB, [%p:%p:%p], Used: %u, Free: %u [%u]", 
+				static_cast<unsigned>(kSizeBytes / 1024U), 
+				reinterpret_cast<const void*>(start_address), 
+				reinterpret_cast<const void*>(ptr),
+                reinterpret_cast<const void*>(end_address), 
+				static_cast<unsigned>(kUsedBytes),
+				 static_cast<unsigned>(kFreeBytes), 
+				 static_cast<unsigned>(kFreePct));
+        } else {
+            printf("Stack: Size %uKB, Used: %u, Free: %u", static_cast<unsigned>(kSizeBytes / 1024U), static_cast<unsigned>(kUsedBytes), static_cast<unsigned>(kFreeBytes));
+        }
         printf("\x1b[39m\n");
     }
 }
 
 inline void Run() {
+    if constexpr (!config::kStackMonitoringEnabled) {
+        return;
+    }
+
     static uint32_t s_millis_previous;
     const auto kMillis = timing::Millis();
     if (kMillis - s_millis_previous >= 1000U) {
         s_millis_previous = kMillis;
         Print();
     }
 }
+} // namespace implementation
+inline void Print() {
+    if constexpr (debug::config::kStackMonitoringEnabled) {
+        implementation::Print();
+    }
+}
+
+inline void Run() {
+    if constexpr (debug::config::kStackMonitoringEnabled) {
+        implementation::Run();
+    }
+}
 } // namespace debug::stack
 
 #endif // FIRMWARE_DEBUG_DEBUG_STACK_H_