Files

mahmamdouh a23dbf0828 software and system v1

2026-02-02 00:49:50 +01:00

6.4 KiB

Raw Permalink Blame History

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

Platform Independence: OSAL interfaces are platform-agnostic
Error Handling: Consistent error code mapping from ESP-IDF to OSAL
Resource Management: Explicit resource lifecycle (init/deinit)
Thread Safety: All OSAL functions are thread-safe where applicable
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:

// 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:

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

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

6.4 KiB Raw Permalink Blame History