# 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