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
|
||||
Reference in New Issue
Block a user