Migrate HAL to lib-board and add stack debug

Reorganize hardware abstraction by introducing lib-board and migrating many lib-hal components into it. Convert hal:: status/interfaces to board:: (notably statusled and reboot/init/run calls) and update includes accordingly across ArtNet, E1.31 and firmware mains. Move common headers (utc, global, firmwareversion) into common/include, simplify UTC API namespace and adjust Global to use utc:: helpers. Add stack usage debugging: implement debug_stack.h with runtime printing and a new stack_debug_init.cpp; wire it into GD32 firmware Rules.mk. Update Makefiles and library lists to use board instead of hal and add build metadata/config files for lib-board.

Author: vanvught

common/include/firmware/debug/debug_stack.h

@@ -2,14 +2,90 @@
  * @file debug_stack.h
  *
  */
+/* Copyright (C) 2026 by Arjan van Vught mailto:info@gd32-dmx.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 
 #ifndef FIRMWARE_DEBUG_DEBUG_STACK_H_
 #define FIRMWARE_DEBUG_DEBUG_STACK_H_
 
-namespace debug::stack
-{
-	void Print();
-	void Run();
+#include <cstdint>
+#include <cstdio>
+#include <cassert>
+
+#include "timing.h"
+
+extern unsigned char stack_low;
+extern unsigned char _sp; // NOLINT
+
+namespace debug::stack {
+inline static constexpr uint32_t kMagicWord = 0xABCDABCD;
+
+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);
+
+    auto* p = start;
+
+    while (p < end) {
+        if (*p != kMagicWord) {
+            break;
+        }
+        p++;
+    }
+
+    const auto kUsedBytes = static_cast<uint32_t>(4 * (end - p));
+    const auto kFreeBytes = static_cast<uint32_t>(4 * (p - start));
+    const auto kFreePct = (static_cast<uint32_t>(p - start) * 100U) / kSize;
+
+    if (s_used_bytes_previous != kUsedBytes) {
+        s_used_bytes_previous = kUsedBytes;
+
+        if (kFreePct == 0) {
+            printf("\x1b[31m");
+        } else if (kFreePct == 1) {
+            printf("\x1b[33m");
+        } else {
+            printf("\x1b[34m");
+        }
+
+#ifndef NDEBUG
+        printf("Stack: Size %uKB, [%p:%p:%p], Used: %u, Free: %u [%u]", kSize / (1024 / 4), start, p, end, kUsedBytes, kFreeBytes, kFreePct);
+#else
+        printf("Stack: Size %uKB, Used: %u, Free: %u", kSize / (1024 / 4), kUsedBytes, kFreeBytes);
+#endif
+        printf("\x1b[39m\n");
+    }
+}
+
+inline void Run() {
+	static uint32_t s_millis_previous;
+    const auto kMillis = timing::Millis();
+    if (kMillis - s_millis_previous >= 1000) {
+        s_millis_previous = kMillis;
+        Print();
+    }
 }
+} // namespace debug::stack
 
 #endif // FIRMWARE_DEBUG_DEBUG_STACK_H_

lib-hal/include/firmwareversion.h common/include/firmware/firmwareversion.hlib-hal/include/firmwareversion.h renamed to common/include/firmware/firmwareversion.h

@@ -6,7 +6,7 @@
  * which is used to get and set the current UTC offset. It also contains validation logic
  * for standard and non-standard UTC offsets.
  */
-/* Copyright (C) 2025 by Arjan van Vught mailto:info@gd32-dmx.org
+/* Copyright (C) 2025-2026 by Arjan van Vught mailto:info@gd32-dmx.org
  */
 
 #ifndef GLOBAL_H_
@@ -20,8 +20,7 @@
  * @namespace global
  * @brief Contains global variables related to time configuration.
  */
-namespace global
-{
+namespace global {
 extern int32_t g_utc_offset;
 }
 
@@ -32,15 +31,13 @@ extern int32_t g_utc_offset;
  * The Global class provides methods to set and get the UTC offset in seconds.
  * It also includes validation logic for standard UTC time zones.
  */
-class Global
-{
+class Global {
    public:
     /**
      * @brief Get the singleton instance of the Global class.
      * @return Reference to the singleton Global object.
      */
-    static Global& Instance()
-    {
+    static Global& Instance() {
         static Global instance;
         return instance;
     }
@@ -56,17 +53,15 @@ class Global
      * @param[out] hours Signed hour component.
      * @param[out] minutes Unsigned minute component.
      */
-    inline void GetUtcOffset(int32_t& hours, uint32_t& minutes) { hal::utc::SplitOffset(global::g_utc_offset, hours, minutes); }
+    inline void GetUtcOffset(int32_t& hours, uint32_t& minutes) { utc::SplitOffset(global::g_utc_offset, hours, minutes); }
 
     /**
      * @brief Sets the global UTC offset if the value is valid.
      * @param utc_offset_seconds Offset in seconds
      * @return true if successfully set; false otherwise
      */
-    inline bool SetUtcOffsetIfValid(int32_t utc_offset_seconds)
-    {
-        if (hal::utc::IsValidOffset(utc_offset_seconds))
-        {
+    inline bool SetUtcOffsetIfValid(int32_t utc_offset_seconds) {
+        if (utc::IsValidOffset(utc_offset_seconds)) {
             ::global::g_utc_offset = utc_offset_seconds;
             return true;
         }
@@ -79,11 +74,9 @@ class Global
      * @param minutes Unsigned minute component
      * @return true if valid and set; false otherwise
      */
-    inline bool SetUtcOffsetIfValid(int32_t hours, uint32_t minutes)
-    {
+    inline bool SetUtcOffsetIfValid(int32_t hours, uint32_t minutes) {
         int32_t offset_seconds;
-        if (hal::utc::ValidateOffset(hours, minutes, offset_seconds))
-        {
+        if (utc::ValidateOffset(hours, minutes, offset_seconds)) {
             return SetUtcOffsetIfValid(offset_seconds);
         }
         return false;
@@ -98,4 +91,4 @@ class Global
     Global& operator=(Global&&) = delete;
 };
 
-#endif  // GLOBAL_H_
+#endif // GLOBAL_H_

lib-hal/include/global.h common/include/global.hlib-hal/include/global.h renamed to common/include/global.h

@@ -3,7 +3,7 @@
  * @brief UTC offset handling utilities (validation, conversion, parsing).
  *
  */
-/* Copyright (C) 2019-2025 by Arjan van Vught mailto:info@gd32-dmx.org
+/* Copyright (C) 2019-2026 by Arjan van Vught mailto:info@gd32-dmx.org
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -32,16 +32,14 @@
  * @namespace global
  * @brief Holds global UTC offset variable used system-wide.
  */
-namespace global
-{
+namespace global {
 /**
  * @brief The current UTC offset in seconds.
  */
 extern int32_t g_utc_offset;
 } // namespace global
 
-namespace hal::utc
-{
+namespace utc {
 
 constexpr int32_t kUtcOffsetMin = -12; ///< Minimum valid UTC offset (hours)
 constexpr int32_t kUtcOffsetMax = 14;  ///< Maximum valid UTC offset (hours)
@@ -50,8 +48,7 @@ constexpr int32_t kUtcOffsetMax = 14;  ///< Maximum valid UTC offset (hours)
  * @struct Offset
  * @brief Represents a fractional UTC offset.
  */
-struct Offset
-{
+struct Offset {
     int32_t hours;    ///< Signed hour component
     uint32_t minutes; ///< Unsigned minute component
 };
@@ -68,19 +65,14 @@ constexpr Offset kValidOffsets[] = {{-9, 30}, {-3, 30}, {3, 30}, {4, 30}, {5, 30
  * @param[out] utc_offset_seconds Resulting offset in seconds
  * @return true if valid; false otherwise
  */
-inline bool ValidateOffset(int32_t hours, uint32_t minutes, int32_t& utc_offset_seconds)
-{
-    if (hours >= kUtcOffsetMin && hours <= kUtcOffsetMax)
-    {
-        if (minutes == 0)
-        {
+inline bool ValidateOffset(int32_t hours, uint32_t minutes, int32_t& utc_offset_seconds) {
+    if (hours >= kUtcOffsetMin && hours <= kUtcOffsetMax) {
+        if (minutes == 0) {
             utc_offset_seconds = hours * 3600;
             return true;
         }
-        for (const auto& offset : kValidOffsets)
-        {
-            if (offset.hours == hours && offset.minutes == minutes)
-            {
+        for (const auto& offset : kValidOffsets) {
+            if (offset.hours == hours && offset.minutes == minutes) {
                 utc_offset_seconds = (hours >= 0) ? (hours * 3600 + static_cast<int32_t>(minutes) * 60) : (hours * 3600 - static_cast<int32_t>(minutes) * 60);
                 return true;
             }
@@ -94,22 +86,17 @@ inline bool ValidateOffset(int32_t hours, uint32_t minutes, int32_t& utc_offset_
  * @param utc_offset_seconds UTC offset in seconds
  * @return true if offset is valid; false otherwise
  */
-inline bool IsValidOffset(int32_t utc_offset_seconds)
-{
+inline bool IsValidOffset(int32_t utc_offset_seconds) {
     if (utc_offset_seconds == 0) return true;
     int32_t hours = utc_offset_seconds / 3600;
-    uint32_t minutes = (utc_offset_seconds >= 0) ? static_cast<uint32_t>(utc_offset_seconds - hours * 3600) / 60
-                                                 : static_cast<uint32_t>((hours * 3600 - utc_offset_seconds)) / 60;
+    uint32_t minutes = (utc_offset_seconds >= 0) ? static_cast<uint32_t>(utc_offset_seconds - hours * 3600) / 60 : static_cast<uint32_t>((hours * 3600 - utc_offset_seconds)) / 60;
 
-    if (minutes == 0 && hours >= kUtcOffsetMin && hours <= kUtcOffsetMax)
-    {
+    if (minutes == 0 && hours >= kUtcOffsetMin && hours <= kUtcOffsetMax) {
         return true;
     }
 
-    for (const auto& offset : kValidOffsets)
-    {
-        int32_t offset_seconds = (offset.hours >= 0) ? offset.hours * 3600 + static_cast<int32_t>(offset.minutes * 60)
-                                                     : offset.hours * 3600 - static_cast<int32_t>(offset.minutes * 60);
+    for (const auto& offset : kValidOffsets) {
+        int32_t offset_seconds = (offset.hours >= 0) ? offset.hours * 3600 + static_cast<int32_t>(offset.minutes * 60) : offset.hours * 3600 - static_cast<int32_t>(offset.minutes * 60);
         if (utc_offset_seconds == offset_seconds) return true;
     }
     return false;
@@ -121,15 +108,11 @@ inline bool IsValidOffset(int32_t utc_offset_seconds)
  * @param[out] hours Signed hour component
  * @param[out] minutes Unsigned minute component
  */
-inline void SplitOffset(int32_t utc_offset_seconds, int32_t& hours, uint32_t& minutes)
-{
+inline void SplitOffset(int32_t utc_offset_seconds, int32_t& hours, uint32_t& minutes) {
     hours = utc_offset_seconds / 3600;
-    if (utc_offset_seconds >= 0)
-    {
+    if (utc_offset_seconds >= 0) {
         minutes = static_cast<uint32_t>((utc_offset_seconds - hours * 3600) / 60);
-    }
-    else
-    {
+    } else {
         minutes = static_cast<uint32_t>(((hours * 3600) - utc_offset_seconds) / 60);
     }
 }
@@ -142,15 +125,12 @@ inline void SplitOffset(int32_t utc_offset_seconds, int32_t& hours, uint32_t& mi
  * @param[out] minutes Unsigned minute component
  * @return true if parse was successful and valid; false otherwise
  */
-inline bool ParseOffset(const char* buffer, uint32_t buffer_length, int32_t& hours, uint32_t& minutes)
-{
+inline bool ParseOffset(const char* buffer, uint32_t buffer_length, int32_t& hours, uint32_t& minutes) {
     if (buffer == nullptr) return false;
 
-    if (buffer_length == 5)
-    {
+    if (buffer_length == 5) {
         static constexpr const char kZeroOffset[5] = {'0', '0', ':', '0', '0'};
-        if (memcmp(kZeroOffset, buffer, sizeof(kZeroOffset)) == 0)
-        {
+        if (memcmp(kZeroOffset, buffer, sizeof(kZeroOffset)) == 0) {
             hours = 0;
             minutes = 0;
             return true;
@@ -179,6 +159,6 @@ inline bool ParseOffset(const char* buffer, uint32_t buffer_length, int32_t& hou
     int32_t dummy;
     return ValidateOffset(hours, minutes, dummy);
 }
-} // namespace hal::utc
+} // namespace utc
 
 #endif // UTC_H_

lib-hal/include/utc.h common/include/utc.hlib-hal/include/utc.h renamed to common/include/utc.h

@@ -32,12 +32,10 @@ endif
 
 ifdef USB_HOST
 	INCLUDES+=-I../lib-gd32/device/usb
-	INCLUDES+=-I../lib-hal/device/usb/host/gd32
 endif
 
 ifdef USB_DEVICE
 	INCLUDES+=-I../lib-gd32/device/usb
-	INCLUDES+=-I../lib-hal/device/usb/device/gd32
 endif
 
 ifeq ($(findstring gd32f20x,$(FAMILY)), gd32f20x)

common/make/gd32/Includes.mk

@@ -127,8 +127,11 @@ $(BUILD)startup_$(LINE).o : $(FIRMWARE_DIR)/startup_$(LINE).S
 $(BUILD)hardfault_handler.o : $(FIRMWARE_DIR)/hardfault_handler.cpp	
 	$(CPP) $(COPS) $(CPPOPS) -c $(FIRMWARE_DIR)/hardfault_handler.cpp -o $(BUILD)hardfault_handler.o
 
-$(BUILD)main.elf: Makefile.GD32 $(LINKER) $(BUILD)startup_$(LINE).o $(BUILD)hardfault_handler.o $(OBJECTS) $(LIBDEP)
-	$(LD) $(BUILD)startup_$(LINE).o $(BUILD)hardfault_handler.o $(OBJECTS) -Map $(MAP) -T $(LINKER) $(LDOPS) -o $(BUILD)main.elf $(LIBGD32) $(LDLIBS) $(PLATFORM_LIBGCC) -lgcc
+$(BUILD)stack_debug_init.o : $(FIRMWARE_DIR)/stack_debug_init.cpp	
+	$(CPP) $(COPS) $(CPPOPS) -c $(FIRMWARE_DIR)/stack_debug_init.cpp -o $(BUILD)stack_debug_init.o
+
+$(BUILD)main.elf: Makefile.GD32 $(LINKER) $(BUILD)startup_$(LINE).o $(BUILD)hardfault_handler.o $(BUILD)stack_debug_init.o $(OBJECTS) $(LIBDEP)
+	$(LD) $(BUILD)startup_$(LINE).o $(BUILD)hardfault_handler.o $(OBJECTS) $(BUILD)stack_debug_init.o -Map $(MAP) -T $(LINKER) $(LDOPS) -o $(BUILD)main.elf $(LIBGD32) $(LDLIBS) $(PLATFORM_LIBGCC) -lgcc
 	$(PREFIX)objdump -D $(BUILD)main.elf | $(PREFIX)c++filt > $(LIST)
 	$(PREFIX)size -A -x $(BUILD)main.elf
 

firmware-template-gd32/Rules.mk

@@ -28,7 +28,7 @@ include ../common/make/gd32/Includes.mk
 include ../common/make/Artnet.mk
 include ../common/make/gd32/Validate.mk
 
-INCLUDES+=-I../lib-configstore/include -I../lib-device/include -I../lib-display/include -I../lib-flash/include -I../lib-flashcode/include -I../lib-hal/include -I../lib-network/include
+INCLUDES+=-I../lib-configstore/include -I../lib-device/include -I../lib-display/include -I../lib-flash/include -I../lib-flashcode/include -I../lib-board/include -I../lib-network/include
 
 COPS=-DGD32 -D$(FAMILY_UCA) -D$(LINE_UC) -D$(MCU) -D$(BOARD) -DPHY_TYPE=$(ENET_PHY)
 COPS+=$(strip $(DEFINES) $(MAKE_FLAGS) $(VALIDATE_FLAGS) $(INCLUDES))

firmware-template-gd32/lib/Rules.mk

@@ -0,0 +1,16 @@
+#include <stdint.h>
+
+#include "firmware/debug/debug_stack.h"
+
+extern unsigned char stack_low;
+extern unsigned char _sp; // NOLINT
+
+extern "C" void stack_debug_init() { // NOLINT
+    auto* start = reinterpret_cast<uint32_t*>(&stack_low);
+    auto* end = reinterpret_cast<uint32_t*>(&_sp);
+
+    while (start < end) {
+        *start = debug::stack::kMagicWord;
+        start++;
+    }
+}

firmware-template-gd32/stack_debug_init.cpp

@@ -71,6 +71,6 @@ ifeq ($(findstring DISPLAY_UDF,$(DEFINES)),DISPLAY_UDF)
 	LIBS+=displayudf
 endif
 
-LIBS+=flash display device superloop hal hwclock
+LIBS+=flash display device superloop board hwclock
 
 $(info $$LIBS [${LIBS}])