# Data Pool Component Specification

**Component ID:** COMP-DATA-POOL  
**Version:** 1.0  
**Date:** 2025-01-19  
**Location:** `application_layer/DP_stack/data_pool/`

## 1. Purpose

The Data Pool component provides centralized, thread-safe storage for runtime system data including latest sensor values, system state, diagnostic information, and configuration data. It serves as the single source of truth for all runtime data and provides fast access for components that need current system information.

## 2. Responsibilities

### 2.1 Primary Responsibilities

- **Runtime Data Storage:** Maintain latest sensor data, system state, and diagnostic information
- **Thread-Safe Access:** Provide concurrent read/write access with appropriate synchronization
- **Data Consistency:** Ensure data integrity across multiple readers and writers
- **Fast Data Access:** Provide low-latency access to frequently accessed data
- **Data Validation:** Validate data integrity and consistency on updates
- **Memory Management:** Efficient memory usage with bounded storage requirements

### 2.2 Non-Responsibilities

- **Data Persistence:** Delegated to Persistence component (long-term storage)
- **Data Processing:** Components handle their own data processing logic
- **Network Communication:** Delegated to Communication components
- **Hardware Access:** No direct hardware interface

## 3. Public API

### 3.1 Sensor Data Management

```c
/**
 * @brief Update sensor data record
 * @param sensor_id Sensor identifier (0-6)
 * @param record Sensor data record to store
 * @return true if update successful, false on error
 */
bool dataPool_updateSensorData(uint8_t sensor_id, const sensor_data_record_t* record);

/**
 * @brief Get latest sensor data record
 * @param sensor_id Sensor identifier (0-6)
 * @param record Output buffer for sensor data record
 * @return true if data retrieved, false on error
 */
bool dataPool_getSensorData(uint8_t sensor_id, sensor_data_record_t* record);

/**
 * @brief Get all sensor data records
 * @param records Output buffer for sensor data records
 * @param count Input: buffer size, Output: number of records filled
 * @return true if data retrieved, false on error
 */
bool dataPool_getAllSensorData(sensor_data_record_t* records, size_t* count);

/**
 * @brief Check if sensor data is available and valid
 * @param sensor_id Sensor identifier (0-6)
 * @return true if valid data available, false otherwise
 */
bool dataPool_isSensorDataValid(uint8_t sensor_id);

/**
 * @brief Get timestamp of last sensor data update
 * @param sensor_id Sensor identifier (0-6)
 * @return Timestamp of last update, 0 if no data available
 */
uint64_t dataPool_getSensorDataTimestamp(uint8_t sensor_id);
```

### 3.2 System State Management

```c
/**
 * @brief Update system state information
 * @param state_info System state information structure
 * @return true if update successful, false on error
 */
bool dataPool_updateSystemState(const system_state_info_t* state_info);

/**
 * @brief Get current system state information
 * @param state_info Output buffer for system state information
 * @return true if data retrieved, false on error
 */
bool dataPool_getSystemState(system_state_info_t* state_info);

/**
 * @brief Update system health metrics
 * @param health_metrics System health metrics structure
 * @return true if update successful, false on error
 */
bool dataPool_updateHealthMetrics(const system_health_metrics_t* health_metrics);

/**
 * @brief Get system health metrics
 * @param health_metrics Output buffer for health metrics
 * @return true if data retrieved, false on error
 */
bool dataPool_getHealthMetrics(system_health_metrics_t* health_metrics);
```

### 3.3 Diagnostic Data Management

```c
/**
 * @brief Add diagnostic event to pool
 * @param event Diagnostic event structure
 * @return true if event added, false on error
 */
bool dataPool_addDiagnosticEvent(const diagnostic_event_t* event);

/**
 * @brief Get recent diagnostic events
 * @param events Output buffer for diagnostic events
 * @param count Input: buffer size, Output: number of events filled
 * @return true if events retrieved, false on error
 */
bool dataPool_getRecentDiagnostics(diagnostic_event_t* events, size_t* count);

/**
 * @brief Get diagnostic summary (counts by severity)
 * @param summary Output buffer for diagnostic summary
 * @return true if summary retrieved, false on error
 */
bool dataPool_getDiagnosticSummary(diagnostic_summary_t* summary);

/**
 * @brief Clear diagnostic events from pool
 * @param severity Severity level to clear (DIAG_SEVERITY_ALL for all)
 * @return Number of events cleared
 */
size_t dataPool_clearDiagnostics(diagnostic_severity_t severity);
```

### 3.4 Communication Status Management

```c
/**
 * @brief Update communication link status
 * @param link_type Communication link type
 * @param status Link status information
 * @return true if update successful, false on error
 */
bool dataPool_updateLinkStatus(comm_link_type_t link_type, const comm_link_status_t* status);

/**
 * @brief Get communication link status
 * @param link_type Communication link type
 * @param status Output buffer for link status
 * @return true if status retrieved, false on error
 */
bool dataPool_getLinkStatus(comm_link_type_t link_type, comm_link_status_t* status);

/**
 * @brief Get overall communication status
 * @param comm_status Output buffer for communication status
 * @return true if status retrieved, false on error
 */
bool dataPool_getCommunicationStatus(communication_status_t* comm_status);
```

### 3.5 Configuration Data Management

```c
/**
 * @brief Update runtime configuration
 * @param config_type Configuration type
 * @param config_data Configuration data
 * @param data_size Size of configuration data
 * @return true if update successful, false on error
 */
bool dataPool_updateConfiguration(config_type_t config_type, const void* config_data, size_t data_size);

/**
 * @brief Get runtime configuration
 * @param config_type Configuration type
 * @param config_data Output buffer for configuration data
 * @param data_size Input: buffer size, Output: actual data size
 * @return true if configuration retrieved, false on error
 */
bool dataPool_getConfiguration(config_type_t config_type, void* config_data, size_t* data_size);

/**
 * @brief Check if configuration is valid
 * @param config_type Configuration type
 * @return true if configuration is valid, false otherwise
 */
bool dataPool_isConfigurationValid(config_type_t config_type);
```

### 3.6 Data Pool Management

```c
/**
 * @brief Initialize Data Pool component
 * @return true if initialization successful, false otherwise
 */
bool dataPool_initialize(void);

/**
 * @brief Get Data Pool statistics
 * @param stats Output buffer for statistics
 * @return true if statistics retrieved, false on error
 */
bool dataPool_getStatistics(data_pool_stats_t* stats);

/**
 * @brief Reset Data Pool statistics
 * @return true if statistics reset, false on error
 */
bool dataPool_resetStatistics(void);

/**
 * @brief Validate Data Pool integrity
 * @return true if integrity check passed, false if corruption detected
 */
bool dataPool_validateIntegrity(void);

/**
 * @brief Create snapshot of current data pool state
 * @param snapshot Output buffer for snapshot
 * @return true if snapshot created, false on error
 */
bool dataPool_createSnapshot(data_pool_snapshot_t* snapshot);
```

## 4. Data Types

### 4.1 Sensor Data Record (Extended)

```c
typedef struct {
    uint8_t sensor_id;              // Sensor identifier (0-6)
    sensor_type_t sensor_type;      // Type of sensor
    float filtered_value;           // Processed sensor value
    char unit[8];                   // Unit of measurement
    uint64_t timestamp_ms;          // Timestamp in milliseconds
    data_validity_t validity;       // Data validity status
    uint16_t sample_count;          // Number of samples used
    float raw_min, raw_max;         // Min/max of raw samples
    float raw_stddev;               // Standard deviation
    uint32_t acquisition_time_us;   // Acquisition time
    uint32_t sequence_number;       // Monotonic sequence number
    uint16_t checksum;              // Data integrity checksum
} sensor_data_record_t;
```

### 4.2 System State Information

```c
typedef struct {
    system_state_t current_state;   // Current system state
    system_state_t previous_state;  // Previous system state
    transition_reason_t last_reason; // Last transition reason
    uint64_t state_entry_time;      // Time when current state was entered
    uint64_t state_duration_ms;     // Duration in current state
    uint32_t state_transition_count; // Total number of state transitions
    bool teardown_in_progress;      // Teardown sequence active
    uint8_t teardown_progress;      // Teardown progress (0-100%)
} system_state_info_t;
```

### 4.3 System Health Metrics

```c
typedef struct {
    // CPU and Memory
    float cpu_usage_percent;        // Current CPU usage
    uint32_t free_heap_bytes;       // Available heap memory
    uint32_t min_free_heap_bytes;   // Minimum free heap recorded
    uint32_t heap_fragmentation;    // Heap fragmentation percentage
    
    // Task Information
    uint32_t task_count;            // Number of active tasks
    uint32_t stack_high_water_mark; // Minimum remaining stack
    
    // System Uptime
    uint64_t uptime_ms;             // System uptime in milliseconds
    uint32_t boot_count;            // Number of system boots
    
    // Storage
    uint64_t sd_free_bytes;         // SD card free space
    uint64_t sd_total_bytes;        // SD card total space
    uint32_t nvm_free_entries;      // NVM free entries
    
    // Communication
    uint32_t wifi_rssi;             // WiFi signal strength
    uint32_t packets_sent;          // Total packets sent
    uint32_t packets_received;      // Total packets received
    uint32_t communication_errors;  // Communication error count
    
    // Sensors
    uint8_t sensors_active;         // Number of active sensors
    uint8_t sensors_faulty;         // Number of faulty sensors
    uint32_t total_acquisitions;    // Total sensor acquisitions
    
    // Diagnostics
    uint32_t warning_count;         // Active warning count
    uint32_t error_count;           // Active error count
    uint32_t fatal_count;           // Fatal error count
    
    uint64_t last_update_time;      // Last metrics update time
} system_health_metrics_t;
```

### 4.4 Diagnostic Event

```c
typedef struct {
    uint16_t diagnostic_code;       // Diagnostic code (0xSCCC format)
    diagnostic_severity_t severity; // Severity level
    uint64_t timestamp_ms;          // Event timestamp
    uint32_t occurrence_count;      // Number of occurrences
    char description[64];           // Human-readable description
    uint8_t context_data[32];       // Context-specific data
    uint32_t sequence_number;       // Event sequence number
} diagnostic_event_t;

typedef struct {
    uint32_t info_count;            // Number of INFO events
    uint32_t warning_count;         // Number of WARNING events
    uint32_t error_count;           // Number of ERROR events
    uint32_t fatal_count;           // Number of FATAL events
    uint64_t last_event_time;       // Timestamp of last event
    uint16_t most_recent_code;      // Most recent diagnostic code
} diagnostic_summary_t;
```

### 4.5 Communication Status

```c
typedef enum {
    COMM_LINK_MAIN_HUB = 0,         // Main Hub communication
    COMM_LINK_PEER_HUB,             // Peer Hub communication
    COMM_LINK_DIAGNOSTIC,           // Diagnostic communication
    COMM_LINK_COUNT
} comm_link_type_t;

typedef struct {
    bool is_connected;              // Connection status
    uint64_t last_activity_time;    // Last communication activity
    uint32_t bytes_sent;            // Bytes sent
    uint32_t bytes_received;        // Bytes received
    uint32_t error_count;           // Communication errors
    int32_t signal_strength;        // Signal strength (RSSI)
    uint32_t round_trip_time_ms;    // Average round-trip time
} comm_link_status_t;

typedef struct {
    comm_link_status_t links[COMM_LINK_COUNT]; // Individual link status
    bool overall_connectivity;      // Overall connectivity status
    uint64_t last_successful_comm;  // Last successful communication
    uint32_t total_comm_failures;   // Total communication failures
} communication_status_t;
```

### 4.6 Data Pool Statistics

```c
typedef struct {
    // Access Statistics
    uint64_t total_reads;           // Total read operations
    uint64_t total_writes;          // Total write operations
    uint64_t read_errors;           // Read operation errors
    uint64_t write_errors;          // Write operation errors
    
    // Performance Metrics
    uint32_t avg_read_time_us;      // Average read time
    uint32_t avg_write_time_us;     // Average write time
    uint32_t max_read_time_us;      // Maximum read time
    uint32_t max_write_time_us;     // Maximum write time
    
    // Memory Usage
    uint32_t memory_used_bytes;     // Current memory usage
    uint32_t max_memory_used_bytes; // Peak memory usage
    
    // Data Integrity
    uint32_t checksum_failures;    // Checksum validation failures
    uint32_t integrity_checks;     // Total integrity checks performed
    
    // Concurrency
    uint32_t concurrent_readers;    // Current concurrent readers
    uint32_t max_concurrent_readers; // Maximum concurrent readers
    uint32_t lock_contentions;      // Lock contention events
    
    uint64_t statistics_reset_time; // Last statistics reset time
} data_pool_stats_t;
```

## 5. Internal Architecture

### 5.1 Data Pool Structure

```mermaid
graph TB
    subgraph "Data Pool Component"
        subgraph "Sensor Data Storage"
            SD0[Sensor 0 Data]
            SD1[Sensor 1 Data]
            SD2[Sensor 2 Data]
            SD3[Sensor 3 Data]
            SD4[Sensor 4 Data]
            SD5[Sensor 5 Data]
            SD6[Sensor 6 Data]
        end
        
        subgraph "System Data Storage"
            SS[System State Info]
            HM[Health Metrics]
            CS[Communication Status]
            CF[Configuration Data]
        end
        
        subgraph "Diagnostic Data Storage"
            DE[Diagnostic Events]
            DS[Diagnostic Summary]
        end
        
        subgraph "Access Control"
            RM[Reader-Writer Mutex]
            IC[Integrity Checker]
            ST[Statistics Tracker]
        end
    end
    
    subgraph "External Components"
        SM[Sensor Manager]
        STM[State Manager]
        COMM[Communication]
        DIAG[Diagnostics]
        HMI[HMI]
    end
    
    SM -->|Update| SD0
    SM -->|Update| SD1
    STM -->|Update| SS
    COMM -->|Update| CS
    DIAG -->|Update| DE
    
    HMI -->|Read| SS
    HMI -->|Read| HM
    COMM -->|Read| SD0
    COMM -->|Read| SD1
    
    RM -.->|Protects| SD0
    RM -.->|Protects| SS
    IC -.->|Validates| DE
    ST -.->|Tracks| RM
```

### 5.2 Thread Safety Model

```mermaid
sequenceDiagram
    participant W1 as Writer 1
    participant W2 as Writer 2
    participant R1 as Reader 1
    participant R2 as Reader 2
    participant DP as Data Pool
    participant Mutex as RW Mutex
    
    Note over W1,Mutex: Concurrent Access Scenario
    
    W1->>Mutex: acquireWriteLock()
    Mutex-->>W1: lockAcquired
    W1->>DP: updateSensorData()
    
    R1->>Mutex: acquireReadLock()
    Note over R1,Mutex: Blocked until write complete
    
    W2->>Mutex: acquireWriteLock()
    Note over W2,Mutex: Blocked until write complete
    
    W1->>DP: dataUpdateComplete
    W1->>Mutex: releaseWriteLock()
    
    Mutex-->>R1: readLockAcquired
    R1->>DP: getSensorData()
    DP-->>R1: sensorData
    
    R2->>Mutex: acquireReadLock()
    Mutex-->>R2: readLockAcquired
    R2->>DP: getSensorData()
    DP-->>R2: sensorData
    
    R1->>Mutex: releaseReadLock()
    R2->>Mutex: releaseReadLock()
    
    Mutex-->>W2: writeLockAcquired
    W2->>DP: updateSystemState()
    W2->>Mutex: releaseWriteLock()
```

## 6. Threading Model

- **Access Model:** Multi-reader, single-writer with reader-writer mutex
- **Thread Safety:** Fully thread-safe for all operations
- **Blocking Operations:** Read operations may block on write operations (bounded)
- **ISR Access:** Limited read-only access for critical data (lock-free atomic reads)
- **Priority Inheritance:** Mutex supports priority inheritance to prevent priority inversion

## 7. Resource Ownership

- **Data Storage:** All runtime data owned exclusively by Data Pool
- **Access Control:** Reader-writer mutex owned by Data Pool
- **Memory Management:** Static allocation for all data structures (no dynamic allocation)
- **Integrity Checking:** Checksum validation owned by Data Pool

## 8. Error Model

### 8.1 Error Conditions

| Error | Condition | Response |
|-------|-----------|----------|
| `DATAPOOL_ERR_INVALID_SENSOR_ID` | Invalid sensor ID (>6) | Return false, log warning |
| `DATAPOOL_ERR_NULL_POINTER` | NULL pointer parameter | Return false, log error |
| `DATAPOOL_ERR_BUFFER_TOO_SMALL` | Output buffer too small | Return false, set required size |
| `DATAPOOL_ERR_DATA_STALE` | Data older than threshold | Return false, log info |
| `DATAPOOL_ERR_CHECKSUM_FAILURE` | Data integrity check failed | Return false, log error |
| `DATAPOOL_ERR_LOCK_TIMEOUT` | Failed to acquire lock | Return false, log warning |
| `DATAPOOL_ERR_MEMORY_FULL` | Storage capacity exceeded | Overwrite oldest, log warning |

### 8.2 Diagnostics Emitted

- `DIAG-DP-POOL-0001`: Data integrity check failed (ERROR)
- `DIAG-DP-POOL-0002`: Lock contention detected (WARNING)
- `DIAG-DP-POOL-0003`: Memory usage high (WARNING)
- `DIAG-DP-POOL-0004`: Stale data detected (INFO)

## 9. State-Dependent Behavior

| System State | Data Pool Behavior |
|-------------|-------------------|
| **INIT** | Initialize data structures, clear all data |
| **RUNNING** | Normal operation, full read/write access |
| **WARNING** | Continue operation, enhanced integrity checking |
| **FAULT** | Read-only mode, preserve data integrity |
| **OTA_UPDATE** | Read-only mode, prepare for snapshot |
| **MC_UPDATE** | Limited updates, configuration reload |
| **TEARDOWN** | Read-only mode, prepare for shutdown |
| **SERVICE** | Full access, enhanced diagnostics |
| **SD_DEGRADED** | Normal operation, no persistence coordination |

## 10. Dependencies

### 10.1 Required Components

- **Logger:** Debug and diagnostic logging
- **Time Utils:** Timestamp generation for data records
- **Error Handler:** Error reporting and escalation

### 10.2 Required Interfaces

- Logger interface for diagnostic output
- Time Utils interface for timestamp generation
- Error Handler interface for fault reporting

## 11. Performance Requirements

### 11.1 Access Performance

- **Read Operations:** Maximum 10μs for single sensor data read
- **Write Operations:** Maximum 50μs for single sensor data write
- **Bulk Operations:** Maximum 500μs for all sensor data read
- **Lock Acquisition:** Maximum 1ms timeout for lock acquisition

### 11.2 Memory Requirements

- **Static Memory:** Maximum 64KB for all data structures
- **Per-Sensor Data:** Maximum 1KB per sensor (including history)
- **Diagnostic Storage:** Maximum 8KB for recent diagnostic events
- **Configuration Storage:** Maximum 4KB for runtime configuration

## 12. Acceptance Tests

### 12.1 Functional Tests

- **T-DATAPOOL-001:** Sensor data storage and retrieval works correctly
- **T-DATAPOOL-002:** System state information maintained accurately
- **T-DATAPOOL-003:** Diagnostic events stored and retrieved correctly
- **T-DATAPOOL-004:** Communication status tracking works
- **T-DATAPOOL-005:** Configuration data management works

### 12.2 Concurrency Tests

- **T-DATAPOOL-006:** Multiple readers can access data simultaneously
- **T-DATAPOOL-007:** Writers have exclusive access during updates
- **T-DATAPOOL-008:** Reader-writer priority handling works correctly
- **T-DATAPOOL-009:** Lock contention handled gracefully

### 12.3 Performance Tests

- **T-DATAPOOL-010:** Read operations complete within 10μs
- **T-DATAPOOL-011:** Write operations complete within 50μs
- **T-DATAPOOL-012:** Memory usage stays within 64KB limit
- **T-DATAPOOL-013:** No memory leaks during continuous operation

### 12.4 Integrity Tests

- **T-DATAPOOL-014:** Data integrity checks detect corruption
- **T-DATAPOOL-015:** Checksum validation works correctly
- **T-DATAPOOL-016:** Stale data detection works
- **T-DATAPOOL-017:** Statistics tracking is accurate

## 13. Traceability

### 13.1 System Requirements

- **SR-DATA-002:** Data Persistence Abstraction (runtime data management)
- **SR-PERF-003:** Memory usage constraints
- **SR-REL-004:** Data integrity requirements

### 13.2 Software Requirements

- **SWR-DATA-004:** DP component API definition
- **SWR-DATA-005:** Storage media abstraction
- **SWR-DATA-006:** Unified data access interface
- **SWR-REL-010:** Error detection implementation

### 13.3 Features

- **F-DATA-002:** Data Persistence Abstraction (runtime component)
- **F-DIAG-002:** Diagnostic Data Storage (runtime component)

## 14. Implementation Notes

### 14.1 Design Patterns

- **Singleton Pattern:** Single Data Pool instance per system
- **Reader-Writer Lock Pattern:** Concurrent access control
- **Observer Pattern:** Data change notifications (via Event System)
- **Template Method Pattern:** Generic data access operations

### 14.2 Key Implementation Details

- All data structures SHALL use static allocation (no malloc/free)
- Reader-writer mutex SHALL support priority inheritance
- Data integrity SHALL be verified using checksums
- Access statistics SHALL be maintained for performance monitoring
- Atomic operations SHALL be used for lock-free ISR access

### 14.3 Memory Layout

```c
// Static memory allocation structure
typedef struct {
    sensor_data_record_t sensor_data[SENSOR_TYPE_COUNT];
    system_state_info_t system_state;
    system_health_metrics_t health_metrics;
    diagnostic_event_t diagnostic_events[MAX_DIAGNOSTIC_EVENTS];
    comm_link_status_t comm_links[COMM_LINK_COUNT];
    uint8_t configuration_data[MAX_CONFIG_SIZE];
    data_pool_stats_t statistics;
    pthread_rwlock_t access_lock;
} data_pool_storage_t;
```

---

**Document Status:** Final for Implementation Phase  
**Component Dependencies:** Verified against architecture  
**Requirements Traceability:** Complete (SR-DATA, SWR-DATA)  
**Next Review:** After implementation and testing