software and system v1

2026-02-02 00:49:50 +01:00
parent 9c5082cd9e
commit a23dbf0828
21 changed files with 4400 additions and 137 deletions
--- a/design/components/osal/gpio_wrapper/COMPONENT.md
+++ b/design/components/osal/gpio_wrapper/COMPONENT.md
@@ -0,0 +1,123 @@
+# GPIO Wrapper Component
+## OSAL Layer - ESP-IDF v5.4 Abstraction
+
+**Component ID:** C-OSAL-GPIO  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+**Location:** `osal/gpio_wrapper/`  
+**ESP-IDF Service:** `driver/gpio.h`
+
+---
+
+## 1. Component Overview
+
+The GPIO Wrapper provides a platform-independent interface for GPIO operations, abstracting ESP-IDF v5.4 GPIO driver. This component enforces GPIO discipline and provides centralized GPIO management.
+
+**Primary Purpose:** Abstract GPIO operations with discipline enforcement.
+
+---
+
+## 2. Responsibilities
+
+### 2.1 In-Scope
+
+- GPIO pin configuration
+- GPIO input/output operations
+- GPIO interrupt handling
+- GPIO resource conflict detection
+- GPIO mapping validation
+- Strapping pin protection
+
+### 2.2 Out-of-Scope
+
+- GPIO pin assignment (handled by GPIO mapping specification)
+- Hardware pull-up/pull-down (handled by hardware design)
+
+---
+
+## 3. Provided Interfaces
+
+### 3.1 Pin Configuration Interface
+
+```c
+/**
+ * @brief Configure GPIO pin
+ * @param pin GPIO pin number
+ * @param config Pin configuration (direction, pull, interrupt)
+ * @return OSAL_OK on success
+ */
+osal_result_t osal_gpio_config(gpio_num_t pin, const osal_gpio_config_t* config);
+
+/**
+ * @brief Validate GPIO pin usage (check conflicts, strapping pins)
+ * @param pin GPIO pin number
+ * @param purpose Pin purpose description
+ * @return OSAL_OK if valid, error if conflict
+ */
+osal_result_t osal_gpio_validate(gpio_num_t pin, const char* purpose);
+```
+
+### 3.2 Pin Operations Interface
+
+```c
+/**
+ * @brief Set GPIO pin level
+ * @param pin GPIO pin number
+ * @param level High (1) or Low (0)
+ * @return OSAL_OK on success
+ */
+osal_result_t osal_gpio_set_level(gpio_num_t pin, uint32_t level);
+
+/**
+ * @brief Get GPIO pin level
+ * @param pin GPIO pin number
+ * @param level Output level
+ * @return OSAL_OK on success
+ */
+osal_result_t osal_gpio_get_level(gpio_num_t pin, uint32_t* level);
+```
+
+### 3.3 Interrupt Interface
+
+```c
+/**
+ * @brief Install GPIO interrupt service
+ * @param pin GPIO pin number
+ * @param intr_type Interrupt type (edge, level)
+ * @param isr_handler ISR handler function
+ * @param args ISR handler arguments
+ * @return OSAL_OK on success
+ */
+osal_result_t osal_gpio_install_isr(gpio_num_t pin, gpio_int_type_t intr_type,
+                                     void (*isr_handler)(void*), void* args);
+```
+
+---
+
+## 4. GPIO Discipline Enforcement
+
+### 4.1 Strapping Pin Protection
+
+- GPIO 0, 3, 45, 46 are protected
+- Attempts to use strapping pins are rejected
+- Diagnostic event generated on violation
+
+### 4.2 Conflict Detection
+
+- Tracks GPIO pin usage
+- Detects multiple registrations
+- Reports conflicts to Diagnostics Manager
+
+---
+
+## 5. Traceability
+
+- **SR-HW-006:** GPIO discipline enforcement
+- **SR-SYS-014:** Avoid strapping pins
+- **SR-SYS-015:** I2C pull-up requirements
+- **SR-SYS-016:** ADC1/ADC2 separation
+
+---
+
+**Document Status:** Complete  
+**Next Review:** Before implementation