software and system v1

1 software design/components/watchdog_manager/COMPONENT.md

@@ -0,0 +1,192 @@
+# Watchdog Manager Component
+## ASF Sensor Hub (Sub-Hub) Embedded System
+
+**Component ID:** C-WATCHDOG-001  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+**Location:** `application_layer/services/watchdog_manager/`  
+**Platform:** ESP32-S3, ESP-IDF v5.4
+
+---
+
+## 1. Component Overview
+
+The Watchdog Manager implements a layered watchdog system providing task-level, interrupt-level, and system-level watchdog protection. This component ensures system reliability by detecting deadlocks, hangs, and system freezes.
+
+**Primary Purpose:** Provide multi-level watchdog protection for system reliability.
+
+---
+
+## 2. Responsibilities
+
+### 2.1 In-Scope
+
+- Task Watchdog (Task WDT) management
+- Interrupt Watchdog (Interrupt WDT) management
+- RTC Watchdog (RTC WDT) management
+- Watchdog timeout configuration
+- Watchdog feeding coordination
+- Watchdog event reporting
+
+### 2.2 Out-of-Scope
+
+- Watchdog hardware management (handled by ESP-IDF)
+- Watchdog reset handling (handled by System State Manager)
+
+---
+
+## 3. Layered Watchdog Architecture
+
+```
+┌─────────────────────────────────────┐
+│   RTC Watchdog (30s)                │  System-level protection
+│   └─> Detects total system freeze   │
+├─────────────────────────────────────┤
+│   Interrupt Watchdog (3s)            │  Interrupt-level protection
+│   └─> Detects ISR hangs             │
+├─────────────────────────────────────┤
+│   Task Watchdog (10s)                │  Task-level protection
+│   └─> Detects task deadlocks         │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 4. Provided Interfaces
+
+### 4.1 Task Watchdog Interface
+
+```c
+/**
+ * @brief Register task with Task Watchdog
+ * @param task_handle Task handle
+ * @param timeout_ms Timeout in milliseconds
+ * @return true on success
+ */
+bool watchdog_task_register(osal_task_handle_t task_handle, uint32_t timeout_ms);
+
+/**
+ * @brief Feed Task Watchdog
+ * @param task_handle Task handle
+ * @return true on success
+ */
+bool watchdog_task_feed(osal_task_handle_t task_handle);
+
+/**
+ * @brief Unregister task from Task Watchdog
+ * @param task_handle Task handle
+ * @return true on success
+ */
+bool watchdog_task_unregister(osal_task_handle_t task_handle);
+```
+
+### 4.2 Interrupt Watchdog Interface
+
+```c
+/**
+ * @brief Feed Interrupt Watchdog
+ * @return true on success
+ */
+bool watchdog_interrupt_feed(void);
+```
+
+### 4.3 RTC Watchdog Interface
+
+```c
+/**
+ * @brief Feed RTC Watchdog
+ * @return true on success
+ */
+bool watchdog_rtc_feed(void);
+
+/**
+ * @brief Initialize RTC Watchdog
+ * @param timeout_ms Timeout in milliseconds
+ * @return true on success
+ */
+bool watchdog_rtc_init(uint32_t timeout_ms);
+```
+
+---
+
+## 5. Watchdog Configuration
+
+### 5.1 Default Timeouts
+
+- **Task Watchdog:** 10 seconds (baseline)
+- **Interrupt Watchdog:** 3 seconds (baseline)
+- **RTC Watchdog:** 30 seconds (baseline)
+
+### 5.2 Configurable Timeouts
+
+- Task-specific timeouts (from Machine Constants)
+- Interrupt watchdog timeout (system-wide)
+- RTC watchdog timeout (system-wide)
+
+---
+
+## 6. ESP-IDF Integration
+
+### 6.1 ESP-IDF Services Used
+
+- `esp_task_wdt.h` - Task Watchdog
+- `esp_intr_wdt.h` - Interrupt Watchdog
+- `esp_system.h` - RTC Watchdog
+
+### 6.2 Watchdog Behavior
+
+- Task Watchdog: Resets system on timeout
+- Interrupt Watchdog: Resets system on timeout
+- RTC Watchdog: Resets system on timeout (final safety net)
+
+---
+
+## 7. Error Handling
+
+### 7.1 Watchdog Timeout Handling
+
+- Log timeout event to Diagnostics Manager
+- Generate diagnostic event (FATAL severity)
+- Trigger system reset (handled by ESP-IDF)
+- State transition to FAULT (if possible before reset)
+
+### 7.2 Diagnostic Events
+
+- `DIAG-DIAG-WDT-0001`: Task Watchdog timeout
+- `DIAG-DIAG-WDT-0002`: Interrupt Watchdog timeout
+- `DIAG-DIAG-WDT-0003`: RTC Watchdog timeout
+
+---
+
+## 8. Dependencies
+
+### 8.1 OSAL Dependencies
+
+- **OSAL-TASK:** Task handle management
+
+### 8.2 Application Dependencies
+
+- **Logger:** Watchdog event logging
+- **Diagnostics Manager:** Error reporting
+- **System State Manager:** State transition on timeout
+
+---
+
+## 9. Traceability
+
+### 9.1 System Requirements
+
+- **SR-DIAG-012:** Task Watchdog implementation
+- **SR-DIAG-013:** Interrupt Watchdog implementation
+- **SR-DIAG-014:** RTC Watchdog implementation
+
+### 9.2 Software Requirements
+
+- **SWR-DIAG-012:** Task Watchdog with 10-second timeout
+- **SWR-DIAG-013:** Interrupt Watchdog with 3-second timeout
+- **SWR-DIAG-014:** RTC Watchdog with 30-second timeout
+
+---
+
+**Document Status:** Complete  
+**Next Review:** Before implementation