software and system v1
This commit is contained in:
243
1 software design/components/osal/OSAL_OVERVIEW.md
Normal file
243
1 software design/components/osal/OSAL_OVERVIEW.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# OSAL (Operating System Abstraction Layer) Overview
|
||||
## ASF Sensor Hub (Sub-Hub) Embedded System
|
||||
|
||||
**Document ID:** COMP-OSAL-OVERVIEW-001
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Platform:** ESP32-S3, ESP-IDF v5.4
|
||||
**Standard:** ISO/IEC/IEEE 42010:2011
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
The OSAL (Operating System Abstraction Layer) provides a platform-independent abstraction over ESP-IDF v5.4 services, enabling application components to access hardware and system services without direct ESP-IDF dependencies. This layer ensures portability, testability, and maintainability.
|
||||
|
||||
**Primary Goal:** Isolate application logic from ESP-IDF framework specifics while maintaining full access to required functionality.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture Position
|
||||
|
||||
```
|
||||
Application Layer
|
||||
↓
|
||||
OSAL Wrappers (This Layer)
|
||||
↓
|
||||
ESP-IDF v5.4 Framework
|
||||
↓
|
||||
Hardware (ESP32-S3)
|
||||
```
|
||||
|
||||
**Dependency Rule:** Application components MUST access ESP-IDF services only through OSAL wrappers (CFC-ARCH-01).
|
||||
|
||||
---
|
||||
|
||||
## 3. OSAL Component Structure
|
||||
|
||||
### 3.1 Component List
|
||||
|
||||
| Component ID | Component Name | ESP-IDF Service | Purpose |
|
||||
|--------------|----------------|-----------------|---------|
|
||||
| C-OSAL-I2C | I2C Wrapper | `driver/i2c_master.h`, `driver/i2c_slave.h` | I2C bus abstraction |
|
||||
| C-OSAL-SPI | SPI Wrapper | `driver/spi_master.h`, `driver/spi_slave.h` | SPI bus abstraction |
|
||||
| C-OSAL-UART | UART Wrapper | `driver/uart.h` | UART serial communication |
|
||||
| C-OSAL-ADC | ADC Wrapper | `driver/adc.h` | Analog-to-digital conversion |
|
||||
| C-OSAL-GPIO | GPIO Wrapper | `driver/gpio.h` | General-purpose I/O |
|
||||
| C-OSAL-TIMER | Timer Wrapper | `driver/gptimer.h`, `hal/timer_hal.h` | Hardware timers |
|
||||
| C-OSAL-TASK | Task Wrapper | `freertos/FreeRTOS.h` | FreeRTOS task management |
|
||||
| C-OSAL-MUTEX | Mutex Wrapper | `freertos/FreeRTOS.h` | Mutual exclusion |
|
||||
| C-OSAL-QUEUE | Queue Wrapper | `freertos/FreeRTOS.h` | Inter-task communication |
|
||||
| C-OSAL-SEM | Semaphore Wrapper | `freertos/FreeRTOS.h` | Synchronization |
|
||||
|
||||
---
|
||||
|
||||
## 4. Design Principles
|
||||
|
||||
### 4.1 Abstraction Principles
|
||||
|
||||
1. **Platform Independence:** OSAL interfaces are platform-agnostic
|
||||
2. **Error Handling:** Consistent error code mapping from ESP-IDF to OSAL
|
||||
3. **Resource Management:** Explicit resource lifecycle (init/deinit)
|
||||
4. **Thread Safety:** All OSAL functions are thread-safe where applicable
|
||||
5. **Timeout Specification:** All blocking operations have explicit timeouts
|
||||
|
||||
### 4.2 ESP-IDF v5.4 Compliance
|
||||
|
||||
- Uses ESP-IDF v5.4 APIs exclusively
|
||||
- Respects ESP-IDF component model
|
||||
- Follows ESP-IDF coding conventions
|
||||
- Leverages ESP-IDF error handling patterns
|
||||
|
||||
---
|
||||
|
||||
## 5. Common Interface Patterns
|
||||
|
||||
### 5.1 Initialization Pattern
|
||||
|
||||
All OSAL components follow this initialization pattern:
|
||||
|
||||
```c
|
||||
// Initialization
|
||||
osal_result_t osal_component_init(osal_config_t* config);
|
||||
|
||||
// Deinitialization
|
||||
osal_result_t osal_component_deinit(void);
|
||||
|
||||
// Status check
|
||||
bool osal_component_is_initialized(void);
|
||||
```
|
||||
|
||||
### 5.2 Error Handling Pattern
|
||||
|
||||
All OSAL functions return `osal_result_t`:
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
OSAL_OK = 0,
|
||||
OSAL_ERR_INVALID_ARG,
|
||||
OSAL_ERR_NO_MEM,
|
||||
OSAL_ERR_TIMEOUT,
|
||||
OSAL_ERR_NOT_INITIALIZED,
|
||||
OSAL_ERR_HW_FAILURE,
|
||||
OSAL_ERR_BUSY
|
||||
} osal_result_t;
|
||||
```
|
||||
|
||||
### 5.3 Resource Lifecycle Pattern
|
||||
|
||||
- **Init:** Allocate resources, configure hardware
|
||||
- **Use:** Perform operations
|
||||
- **Deinit:** Release resources, reset hardware
|
||||
|
||||
---
|
||||
|
||||
## 6. Component Dependencies
|
||||
|
||||
### 6.1 OSAL Internal Dependencies
|
||||
|
||||
```
|
||||
OSAL-TASK (Base)
|
||||
├─> OSAL-MUTEX
|
||||
├─> OSAL-QUEUE
|
||||
└─> OSAL-SEM
|
||||
|
||||
OSAL-I2C ──> OSAL-GPIO
|
||||
OSAL-SPI ──> OSAL-GPIO
|
||||
OSAL-UART ──> OSAL-GPIO
|
||||
OSAL-ADC ──> OSAL-GPIO
|
||||
```
|
||||
|
||||
### 6.2 Application Dependencies
|
||||
|
||||
All application components depend on OSAL wrappers, not directly on ESP-IDF.
|
||||
|
||||
---
|
||||
|
||||
## 7. Configuration Management
|
||||
|
||||
### 7.1 Configuration Sources
|
||||
|
||||
- **Machine Constants:** System-wide configuration
|
||||
- **Runtime Configuration:** Component-specific settings
|
||||
- **Build-time Configuration:** Compile-time constants
|
||||
|
||||
### 7.2 Configuration Validation
|
||||
|
||||
All OSAL components validate configuration parameters:
|
||||
- Range checking
|
||||
- Resource availability
|
||||
- Conflict detection
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Handling and Diagnostics
|
||||
|
||||
### 8.1 Error Reporting
|
||||
|
||||
OSAL components report errors through:
|
||||
- Return codes (primary)
|
||||
- Diagnostic events (secondary)
|
||||
- Logging (tertiary)
|
||||
|
||||
### 8.2 Diagnostic Integration
|
||||
|
||||
OSAL errors are reported to Diagnostics Manager with:
|
||||
- Component identifier
|
||||
- Error code
|
||||
- Context information
|
||||
- Timestamp
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing Strategy
|
||||
|
||||
### 9.1 Unit Testing
|
||||
|
||||
- Mock ESP-IDF services for unit tests
|
||||
- Test error handling paths
|
||||
- Test resource management
|
||||
- Test timeout handling
|
||||
|
||||
### 9.2 Integration Testing
|
||||
|
||||
- Test with real ESP-IDF services
|
||||
- Test hardware interaction
|
||||
- Test concurrent access
|
||||
- Test resource conflicts
|
||||
|
||||
---
|
||||
|
||||
## 10. Implementation Notes
|
||||
|
||||
### 10.1 ESP-IDF v5.4 Specifics
|
||||
|
||||
- **I2C:** Uses `i2c_master_bus_handle_t` and `i2c_master_dev_handle_t`
|
||||
- **SPI:** Uses `spi_bus_handle_t` and `spi_device_handle_t`
|
||||
- **UART:** Uses `uart_port_t` and `uart_driver_install()`
|
||||
- **ADC:** Uses `adc_oneshot_unit_handle_t` for one-shot mode
|
||||
- **GPIO:** Uses `gpio_config_t` and `gpio_set_level()`
|
||||
- **Timer:** Uses `gptimer_handle_t` for general-purpose timers
|
||||
- **FreeRTOS:** Uses standard FreeRTOS APIs
|
||||
|
||||
### 10.2 Resource Constraints
|
||||
|
||||
- **I2C Buses:** Maximum 2 buses (I2C_NUM_0, I2C_NUM_1)
|
||||
- **SPI Buses:** Maximum 3 buses (SPI1_HOST, SPI2_HOST, SPI3_HOST)
|
||||
- **UART Ports:** Maximum 3 ports (UART_NUM_0, UART_NUM_1, UART_NUM_2)
|
||||
- **ADC Units:** ADC1 and ADC2 (ADC2 not available with Wi-Fi)
|
||||
- **GPIO Pins:** Limited by ESP32-S3 pinout
|
||||
- **Tasks:** Limited by FreeRTOS heap
|
||||
|
||||
---
|
||||
|
||||
## 11. Traceability
|
||||
|
||||
### 11.1 System Requirements
|
||||
|
||||
- **SR-HW-005:** System shall abstract all hardware interfaces through driver layers
|
||||
- **SR-HW-006:** System shall enforce GPIO discipline
|
||||
|
||||
### 11.2 Software Requirements
|
||||
|
||||
- **SWR-DESIGN-003:** Software shall access hardware only through driver and OSAL layers
|
||||
- **SWR-IF-002:** Software shall provide sensor interfaces supporting I2C, SPI, UART, and analog protocols
|
||||
|
||||
### 11.3 Cross-Feature Constraints
|
||||
|
||||
- **CFC-ARCH-01:** Application logic shall not access hardware directly
|
||||
|
||||
---
|
||||
|
||||
## 12. Related Documents
|
||||
|
||||
- Individual OSAL component specifications (C-OSAL-I2C, C-OSAL-SPI, etc.)
|
||||
- Hardware Abstraction Layer specification
|
||||
- GPIO Mapping Specification
|
||||
- ESP-IDF v5.4 Programming Guide
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
**Approval Required:** Software Architect
|
||||
123
1 software design/components/osal/gpio_wrapper/COMPONENT.md
Normal file
123
1 software design/components/osal/gpio_wrapper/COMPONENT.md
Normal file
@@ -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
|
||||
395
1 software design/components/osal/i2c_wrapper/COMPONENT.md
Normal file
395
1 software design/components/osal/i2c_wrapper/COMPONENT.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# I2C Wrapper Component
|
||||
## OSAL Layer - ESP-IDF v5.4 Abstraction
|
||||
|
||||
**Component ID:** C-OSAL-I2C
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Location:** `osal/i2c_wrapper/`
|
||||
**ESP-IDF Service:** `driver/i2c_master.h`, `driver/i2c_slave.h`
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Overview
|
||||
|
||||
The I2C Wrapper provides a platform-independent interface for I2C bus operations, abstracting ESP-IDF v5.4 I2C master and slave drivers. This component enables sensor drivers and other components to access I2C devices without direct ESP-IDF dependencies.
|
||||
|
||||
**Primary Purpose:** Abstract I2C bus operations for application components.
|
||||
|
||||
---
|
||||
|
||||
## 2. Responsibilities
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- I2C bus initialization and configuration
|
||||
- I2C device registration and management
|
||||
- I2C read/write operations (master mode)
|
||||
- I2C bus error handling and recovery
|
||||
- I2C bus resource management
|
||||
- I2C timeout handling
|
||||
- I2C bus status monitoring
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- I2C slave mode (not required for sensor hub)
|
||||
- I2C protocol-level error recovery (handled by ESP-IDF)
|
||||
- I2C bus arbitration (handled by ESP-IDF)
|
||||
- Device-specific I2C protocols (handled by sensor drivers)
|
||||
|
||||
---
|
||||
|
||||
## 3. Provided Interfaces
|
||||
|
||||
### 3.1 Bus Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Initialize I2C bus
|
||||
* @param bus_num I2C bus number (0 or 1)
|
||||
* @param config Bus configuration (clock speed, SDA/SCL pins)
|
||||
* @return OSAL_OK on success, error code on failure
|
||||
*/
|
||||
osal_result_t osal_i2c_bus_init(i2c_bus_num_t bus_num, const osal_i2c_bus_config_t* config);
|
||||
|
||||
/**
|
||||
* @brief Deinitialize I2C bus
|
||||
* @param bus_num I2C bus number
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_bus_deinit(i2c_bus_num_t bus_num);
|
||||
|
||||
/**
|
||||
* @brief Check if I2C bus is initialized
|
||||
* @param bus_num I2C bus number
|
||||
* @return true if initialized, false otherwise
|
||||
*/
|
||||
bool osal_i2c_bus_is_initialized(i2c_bus_num_t bus_num);
|
||||
```
|
||||
|
||||
### 3.2 Device Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Register I2C device on bus
|
||||
* @param bus_num I2C bus number
|
||||
* @param device_addr I2C device address (7-bit)
|
||||
* @param device_handle Output device handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_device_register(i2c_bus_num_t bus_num, uint8_t device_addr,
|
||||
osal_i2c_device_handle_t* device_handle);
|
||||
|
||||
/**
|
||||
* @brief Unregister I2C device
|
||||
* @param device_handle Device handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_device_unregister(osal_i2c_device_handle_t device_handle);
|
||||
```
|
||||
|
||||
### 3.3 Data Transfer Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Write data to I2C device
|
||||
* @param device_handle Device handle
|
||||
* @param reg_addr Register address (optional, 0 if not used)
|
||||
* @param data Data buffer
|
||||
* @param data_len Data length in bytes
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_write(osal_i2c_device_handle_t device_handle, uint8_t reg_addr,
|
||||
const uint8_t* data, size_t data_len, uint32_t timeout_ms);
|
||||
|
||||
/**
|
||||
* @brief Read data from I2C device
|
||||
* @param device_handle Device handle
|
||||
* @param reg_addr Register address (optional, 0 if not used)
|
||||
* @param data Output data buffer
|
||||
* @param data_len Data length in bytes
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_read(osal_i2c_device_handle_t device_handle, uint8_t reg_addr,
|
||||
uint8_t* data, size_t data_len, uint32_t timeout_ms);
|
||||
|
||||
/**
|
||||
* @brief Write then read (combined transaction)
|
||||
* @param device_handle Device handle
|
||||
* @param write_data Write data buffer
|
||||
* @param write_len Write data length
|
||||
* @param read_data Read data buffer
|
||||
* @param read_len Read data length
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_write_read(osal_i2c_device_handle_t device_handle,
|
||||
const uint8_t* write_data, size_t write_len,
|
||||
uint8_t* read_data, size_t read_len,
|
||||
uint32_t timeout_ms);
|
||||
```
|
||||
|
||||
### 3.4 Status and Diagnostics Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Get I2C bus status
|
||||
* @param bus_num I2C bus number
|
||||
* @param status Output status structure
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_get_bus_status(i2c_bus_num_t bus_num, osal_i2c_bus_status_t* status);
|
||||
|
||||
/**
|
||||
* @brief Reset I2C bus (recovery from error)
|
||||
* @param bus_num I2C bus number
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_bus_reset(i2c_bus_num_t bus_num);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Structures
|
||||
|
||||
### 4.1 Configuration Structures
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint32_t clock_speed_hz; // I2C clock speed (100kHz, 400kHz, 1MHz)
|
||||
gpio_num_t sda_pin; // SDA GPIO pin
|
||||
gpio_num_t scl_pin; // SCL GPIO pin
|
||||
bool sda_pullup_enable; // Enable SDA pull-up
|
||||
bool scl_pullup_enable; // Enable SCL pull-up
|
||||
uint32_t timeout_ms; // Default timeout
|
||||
} osal_i2c_bus_config_t;
|
||||
|
||||
typedef struct {
|
||||
bool is_initialized;
|
||||
uint32_t active_devices;
|
||||
uint32_t error_count;
|
||||
uint32_t transaction_count;
|
||||
} osal_i2c_bus_status_t;
|
||||
```
|
||||
|
||||
### 4.2 Handle Types
|
||||
|
||||
```c
|
||||
typedef void* osal_i2c_device_handle_t;
|
||||
typedef enum {
|
||||
I2C_BUS_0 = 0,
|
||||
I2C_BUS_1 = 1
|
||||
} i2c_bus_num_t;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Internal State Machine
|
||||
|
||||
```
|
||||
[UNINITIALIZED]
|
||||
↓ osal_i2c_bus_init()
|
||||
[INITIALIZED]
|
||||
↓ osal_i2c_device_register()
|
||||
[DEVICE_REGISTERED]
|
||||
↓ osal_i2c_write/read()
|
||||
[OPERATIONAL]
|
||||
↓ Error detected
|
||||
[ERROR_STATE]
|
||||
↓ osal_i2c_bus_reset()
|
||||
[INITIALIZED]
|
||||
↓ osal_i2c_bus_deinit()
|
||||
[UNINITIALIZED]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. ESP-IDF v5.4 Integration
|
||||
|
||||
### 6.1 ESP-IDF APIs Used
|
||||
|
||||
- `i2c_master_bus_config_t` - Bus configuration
|
||||
- `i2c_master_bus_handle_t` - Bus handle
|
||||
- `i2c_master_dev_handle_t` - Device handle
|
||||
- `i2c_master_bus_add_device()` - Device registration
|
||||
- `i2c_master_transmit_receive()` - Data transfer
|
||||
|
||||
### 6.2 ESP-IDF Error Mapping
|
||||
|
||||
| ESP-IDF Error | OSAL Error |
|
||||
|---------------|------------|
|
||||
| ESP_OK | OSAL_OK |
|
||||
| ESP_ERR_INVALID_ARG | OSAL_ERR_INVALID_ARG |
|
||||
| ESP_ERR_NO_MEM | OSAL_ERR_NO_MEM |
|
||||
| ESP_ERR_TIMEOUT | OSAL_ERR_TIMEOUT |
|
||||
| ESP_ERR_NOT_FOUND | OSAL_ERR_HW_FAILURE |
|
||||
|
||||
---
|
||||
|
||||
## 7. Error Handling
|
||||
|
||||
### 7.1 Error Detection
|
||||
|
||||
- I2C bus errors (NACK, arbitration loss)
|
||||
- Timeout errors
|
||||
- Invalid parameter errors
|
||||
- Resource exhaustion errors
|
||||
|
||||
### 7.2 Error Recovery
|
||||
|
||||
- Automatic bus reset on error
|
||||
- Retry mechanism (configurable)
|
||||
- Error reporting to Diagnostics Manager
|
||||
- Bus status monitoring
|
||||
|
||||
### 7.3 Diagnostic Events
|
||||
|
||||
- `DIAG-HW-I2C-0001`: I2C bus initialization failure
|
||||
- `DIAG-HW-I2C-0002`: I2C device registration failure
|
||||
- `DIAG-HW-I2C-0003`: I2C transaction timeout
|
||||
- `DIAG-HW-I2C-0004`: I2C bus error (NACK)
|
||||
- `DIAG-HW-I2C-0005`: I2C bus reset performed
|
||||
|
||||
---
|
||||
|
||||
## 8. Configuration Parameters
|
||||
|
||||
### 8.1 Build-time Configuration
|
||||
|
||||
- Maximum number of I2C buses: 2
|
||||
- Maximum devices per bus: 8
|
||||
- Default timeout: 1000ms
|
||||
- Retry count: 3
|
||||
|
||||
### 8.2 Runtime Configuration
|
||||
|
||||
- Clock speed (from Machine Constants)
|
||||
- GPIO pin assignments (from GPIO mapping)
|
||||
- Pull-up enable (from hardware design)
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependencies
|
||||
|
||||
### 9.1 OSAL Dependencies
|
||||
|
||||
- **OSAL-GPIO:** GPIO pin configuration
|
||||
|
||||
### 9.2 ESP-IDF Dependencies
|
||||
|
||||
- `driver/i2c_master.h`
|
||||
- `driver/gpio.h`
|
||||
- `esp_err.h`
|
||||
|
||||
### 9.3 Application Dependencies
|
||||
|
||||
- **Logger:** Error logging
|
||||
- **Diagnostics Manager:** Error reporting
|
||||
- **Time Utils:** Timeout handling
|
||||
|
||||
---
|
||||
|
||||
## 10. Thread Safety
|
||||
|
||||
### 10.1 Concurrent Access
|
||||
|
||||
- Bus operations are thread-safe
|
||||
- Device handles are thread-safe
|
||||
- Multiple devices on same bus can be accessed concurrently
|
||||
- Bus initialization/deinitialization requires synchronization
|
||||
|
||||
### 10.2 FreeRTOS Integration
|
||||
|
||||
- Uses FreeRTOS mutex for bus protection
|
||||
- Non-blocking operations preferred
|
||||
- Timeout handling uses FreeRTOS ticks
|
||||
|
||||
---
|
||||
|
||||
## 11. Performance Considerations
|
||||
|
||||
### 11.1 Timing Constraints
|
||||
|
||||
- I2C write operation: < 10ms (typical)
|
||||
- I2C read operation: < 10ms (typical)
|
||||
- Bus initialization: < 100ms
|
||||
- Device registration: < 10ms
|
||||
|
||||
### 11.2 Resource Usage
|
||||
|
||||
- Memory: ~2KB per bus (ESP-IDF overhead)
|
||||
- CPU: Minimal (hardware-assisted)
|
||||
- Interrupts: I2C interrupt handler
|
||||
|
||||
---
|
||||
|
||||
## 12. Testing Strategy
|
||||
|
||||
### 12.1 Unit Testing
|
||||
|
||||
- Mock ESP-IDF I2C functions
|
||||
- Test error handling paths
|
||||
- Test timeout handling
|
||||
- Test resource management
|
||||
|
||||
### 12.2 Integration Testing
|
||||
|
||||
- Test with real I2C devices
|
||||
- Test concurrent access
|
||||
- Test error recovery
|
||||
- Test bus reset functionality
|
||||
|
||||
### 12.3 Hardware Testing
|
||||
|
||||
- Test with actual sensors
|
||||
- Test I2C bus conflicts
|
||||
- Test pull-up resistor behavior
|
||||
- Test clock speed variations
|
||||
|
||||
---
|
||||
|
||||
## 13. Traceability
|
||||
|
||||
### 13.1 System Requirements
|
||||
|
||||
- **SR-HW-005:** System shall abstract all hardware interfaces through driver layers
|
||||
- **SR-SYS-015:** System shall ensure all shared I2C buses have appropriate physical pull-up resistors
|
||||
|
||||
### 13.2 Software Requirements
|
||||
|
||||
- **SWR-IF-002:** Software shall provide sensor interfaces supporting I2C protocol
|
||||
- **SWR-DESIGN-003:** Software shall access hardware only through driver and OSAL layers
|
||||
|
||||
### 13.3 Cross-Feature Constraints
|
||||
|
||||
- **CFC-ARCH-01:** Application logic shall not access hardware directly
|
||||
|
||||
---
|
||||
|
||||
## 14. Implementation Notes
|
||||
|
||||
### 14.1 ESP-IDF v5.4 Specifics
|
||||
|
||||
- Uses new I2C master driver API (not legacy)
|
||||
- Supports I2C_NUM_0 and I2C_NUM_1
|
||||
- Clock speed: 100kHz, 400kHz, 1MHz supported
|
||||
- Requires proper GPIO configuration
|
||||
|
||||
### 14.2 GPIO Requirements
|
||||
|
||||
- SDA and SCL pins must be configured via GPIO mapping
|
||||
- Physical pull-up resistors required (2.2kΩ - 4.7kΩ)
|
||||
- Software pull-ups can be enabled as backup
|
||||
|
||||
### 14.3 Known Limitations
|
||||
|
||||
- Maximum 8 devices per bus (ESP-IDF limitation)
|
||||
- Clock stretching not fully supported in all modes
|
||||
- Bus sharing requires careful synchronization
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
**Approval Required:** Software Architect
|
||||
120
1 software design/components/osal/spi_wrapper/COMPONENT.md
Normal file
120
1 software design/components/osal/spi_wrapper/COMPONENT.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# SPI Wrapper Component
|
||||
## OSAL Layer - ESP-IDF v5.4 Abstraction
|
||||
|
||||
**Component ID:** C-OSAL-SPI
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Location:** `osal/spi_wrapper/`
|
||||
**ESP-IDF Service:** `driver/spi_master.h`, `driver/spi_slave.h`
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Overview
|
||||
|
||||
The SPI Wrapper provides a platform-independent interface for SPI bus operations, abstracting ESP-IDF v5.4 SPI master and slave drivers. This component enables storage drivers and other components to access SPI devices (SD cards, flash chips) without direct ESP-IDF dependencies.
|
||||
|
||||
**Primary Purpose:** Abstract SPI bus operations for application components.
|
||||
|
||||
---
|
||||
|
||||
## 2. Responsibilities
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- SPI bus initialization and configuration
|
||||
- SPI device registration and management
|
||||
- SPI transaction operations (master mode)
|
||||
- SPI bus error handling and recovery
|
||||
- SPI bus resource management
|
||||
- SPI timeout handling
|
||||
- SPI bus status monitoring
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- SPI slave mode (not required for sensor hub)
|
||||
- SPI protocol-level error recovery (handled by ESP-IDF)
|
||||
- Device-specific SPI protocols (handled by storage drivers)
|
||||
|
||||
---
|
||||
|
||||
## 3. Provided Interfaces
|
||||
|
||||
### 3.1 Bus Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Initialize SPI bus
|
||||
* @param bus_num SPI bus number (SPI1_HOST, SPI2_HOST, SPI3_HOST)
|
||||
* @param config Bus configuration (clock speed, pins, mode)
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_spi_bus_init(spi_bus_num_t bus_num, const osal_spi_bus_config_t* config);
|
||||
|
||||
/**
|
||||
* @brief Deinitialize SPI bus
|
||||
* @param bus_num SPI bus number
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_spi_bus_deinit(spi_bus_num_t bus_num);
|
||||
```
|
||||
|
||||
### 3.2 Device Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Register SPI device on bus
|
||||
* @param bus_num SPI bus number
|
||||
* @param device_config Device configuration (CS pin, mode, clock speed)
|
||||
* @param device_handle Output device handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_spi_device_register(spi_bus_num_t bus_num,
|
||||
const osal_spi_device_config_t* device_config,
|
||||
osal_spi_device_handle_t* device_handle);
|
||||
|
||||
/**
|
||||
* @brief Unregister SPI device
|
||||
* @param device_handle Device handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_spi_device_unregister(osal_spi_device_handle_t device_handle);
|
||||
```
|
||||
|
||||
### 3.3 Transaction Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Perform SPI transaction
|
||||
* @param device_handle Device handle
|
||||
* @param tx_data Transmit data buffer (NULL if read-only)
|
||||
* @param rx_data Receive data buffer (NULL if write-only)
|
||||
* @param length Transaction length in bytes
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_spi_transaction(osal_spi_device_handle_t device_handle,
|
||||
const uint8_t* tx_data, uint8_t* rx_data,
|
||||
size_t length, uint32_t timeout_ms);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. ESP-IDF v5.4 Integration
|
||||
|
||||
- Uses `spi_bus_handle_t` and `spi_device_handle_t`
|
||||
- Supports SPI1_HOST, SPI2_HOST, SPI3_HOST
|
||||
- Clock speed: Up to 80MHz (ESP32-S3 limit)
|
||||
- SPI modes: 0, 1, 2, 3 supported
|
||||
|
||||
---
|
||||
|
||||
## 5. Traceability
|
||||
|
||||
- **SR-HW-005:** Hardware interface abstraction
|
||||
- **SWR-IF-002:** SPI protocol support
|
||||
- **SWR-DESIGN-003:** OSAL layer access
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
105
1 software design/components/osal/task_wrapper/COMPONENT.md
Normal file
105
1 software design/components/osal/task_wrapper/COMPONENT.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# Task Wrapper Component
|
||||
## OSAL Layer - FreeRTOS Abstraction
|
||||
|
||||
**Component ID:** C-OSAL-TASK
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Location:** `osal/task_wrapper/`
|
||||
**ESP-IDF Service:** `freertos/FreeRTOS.h`, `freertos/task.h`
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Overview
|
||||
|
||||
The Task Wrapper provides a platform-independent interface for FreeRTOS task management, abstracting ESP-IDF v5.4 FreeRTOS APIs. This component enables application components to create and manage tasks without direct FreeRTOS dependencies.
|
||||
|
||||
**Primary Purpose:** Abstract FreeRTOS task operations for application components.
|
||||
|
||||
---
|
||||
|
||||
## 2. Responsibilities
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- Task creation and deletion
|
||||
- Task priority management
|
||||
- Task state queries
|
||||
- Task synchronization
|
||||
- Task watchdog integration
|
||||
- Task resource monitoring
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- Task scheduling (handled by FreeRTOS)
|
||||
- Task preemption (handled by FreeRTOS)
|
||||
- Interrupt handling (handled by ESP-IDF)
|
||||
|
||||
---
|
||||
|
||||
## 3. Provided Interfaces
|
||||
|
||||
### 3.1 Task Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Create FreeRTOS task
|
||||
* @param task_name Task name (for debugging)
|
||||
* @param task_func Task function
|
||||
* @param task_args Task function arguments
|
||||
* @param stack_size Stack size in bytes
|
||||
* @param priority Task priority
|
||||
* @param core_id CPU core ID (-1 for any core)
|
||||
* @param task_handle Output task handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_task_create(const char* task_name, TaskFunction_t task_func, void* task_args,
|
||||
uint32_t stack_size, uint32_t priority, int core_id,
|
||||
osal_task_handle_t* task_handle);
|
||||
|
||||
/**
|
||||
* @brief Delete task
|
||||
* @param task_handle Task handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_task_delete(osal_task_handle_t task_handle);
|
||||
|
||||
/**
|
||||
* @brief Delay task execution
|
||||
* @param delay_ms Delay in milliseconds
|
||||
*/
|
||||
void osal_task_delay(uint32_t delay_ms);
|
||||
```
|
||||
|
||||
### 3.2 Task Status Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Get task status
|
||||
* @param task_handle Task handle
|
||||
* @param status Output status structure
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_task_get_status(osal_task_handle_t task_handle, osal_task_status_t* status);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. FreeRTOS Integration
|
||||
|
||||
- Uses `xTaskCreate()` for task creation
|
||||
- Supports dual-core (Core 0, Core 1, or any)
|
||||
- Priority range: 0-25 (configurable)
|
||||
- Stack monitoring and overflow detection
|
||||
|
||||
---
|
||||
|
||||
## 5. Traceability
|
||||
|
||||
- **SWR-DESIGN-002:** Non-blocking operations
|
||||
- **SWR-DIAG-012:** Task watchdog integration
|
||||
- **CFC-TIME-01:** Non-blocking operation support
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
Reference in New Issue
Block a user