# Event System Component Specification

**Component ID:** COMP-EVENT  
**Version:** 1.0  
**Date:** 2025-01-19  
**Location:** `application_layer/business_stack/event_system/`

## 1. Purpose

The Event System provides a publish/subscribe event bus for cross-component communication. It decouples components, enables asynchronous event delivery, and ensures non-blocking operation.

## 2. Responsibilities

### 2.1 Primary Responsibilities

- Provide publish/subscribe event bus
- Decouple components via events
- Ensure non-blocking event delivery
- Support multiple subscribers per event type
- Queue management for event delivery

### 2.2 Non-Responsibilities

- Business logic (components handle events)
- Event payload validation (components validate)
- Event ordering guarantees (best-effort)

## 3. Public API

### 3.1 Event Publishing

```c
/**
 * @brief Publish an event
 * @param type Event type
 * @param payload Event payload (may be NULL)
 * @param payload_size Payload size in bytes (0 if payload is NULL)
 * @return true if published, false on error
 */
bool event_publish(event_type_t type, const void* payload, size_t payload_size);

/**
 * @brief Publish an event with timestamp
 * @param type Event type
 * @param payload Event payload
 * @param payload_size Payload size
 * @param timestamp Event timestamp
 * @return true if published, false on error
 */
bool event_publishWithTimestamp(event_type_t type, const void* payload, size_t payload_size, uint64_t timestamp);
```

### 3.2 Event Subscription

```c
/**
 * @brief Event handler callback type
 * @param type Event type
 * @param payload Event payload
 * @param payload_size Payload size
 * @param timestamp Event timestamp
 */
typedef void (*event_handler_t)(event_type_t type, const void* payload, size_t payload_size, uint64_t timestamp);

/**
 * @brief Subscribe to an event type
 * @param type Event type to subscribe to
 * @param handler Callback function
 * @return true if subscribed, false on error
 */
bool event_subscribe(event_type_t type, event_handler_t handler);

/**
 * @brief Unsubscribe from an event type
 * @param type Event type to unsubscribe from
 * @param handler Callback function to remove
 * @return true if unsubscribed, false if not found
 */
bool event_unsubscribe(event_type_t type, event_handler_t handler);
```

### 3.3 Event Queue Management

```c
/**
 * @brief Get number of pending events
 * @param type Event type (EVENT_TYPE_ALL for all types)
 * @return Number of pending events
 */
size_t event_getPendingCount(event_type_t type);

/**
 * @brief Clear pending events
 * @param type Event type (EVENT_TYPE_ALL for all types)
 * @return Number of events cleared
 */
size_t event_clearPending(event_type_t type);
```

## 4. Data Types

### 4.1 Event Types

```c
typedef enum {
    EVENT_SENSOR_DATA_UPDATE = 0,
    EVENT_DIAGNOSTIC_EVENT,
    EVENT_STATE_CHANGED,
    EVENT_OTA_REQUEST,
    EVENT_OTA_STATUS,
    EVENT_MC_UPDATE_REQUEST,
    EVENT_COMMUNICATION_LINK_STATUS,
    EVENT_STORAGE_STATUS,
    EVENT_SYSTEM_HEALTH_UPDATE,
    EVENT_TYPE_ALL = 0xFF,
    EVENT_TYPE_COUNT
} event_type_t;
```

### 4.2 Event Structure

```c
typedef struct {
    event_type_t type;
    uint64_t timestamp;
    size_t payload_size;
    uint8_t payload[];  // Variable-length payload
} event_t;
```

## 5. Threading Model

- **Owner Task:** Event System Task (MEDIUM priority) or shared with components
- **Thread Safety:** Thread-safe (lock-free queue for publishing, mutex for subscription management)
- **Blocking Operations:** None (all operations are non-blocking)
- **ISR Access:** Publish allowed from ISR (lock-free queue)

## 6. Resource Ownership

- **Event Queue:** Owned by Event System (lock-free ring buffer)
- **Subscriber List:** Protected by mutex
- **Event Buffers:** Pre-allocated static buffers (no dynamic allocation)

## 7. Error Model

### 7.1 Error Conditions

| Error | Condition | Response |
|-------|-----------|----------|
| `EVENT_ERR_QUEUE_FULL` | Event queue full | Drop oldest event, log warning |
| `EVENT_ERR_INVALID_TYPE` | Invalid event type | Return false, log warning |
| `EVENT_ERR_PAYLOAD_TOO_LARGE` | Payload exceeds maximum | Return false, log error |
| `EVENT_ERR_SUBSCRIBER_FULL` | Too many subscribers | Return false, log error |

### 7.2 Diagnostics Emitted

- `DIAG-SY-EVENT-0001`: Event queue full (WARNING)
- `DIAG-SY-EVENT-0002`: Event dropped due to queue full (WARNING)
- `DIAG-SY-EVENT-0003`: Subscriber callback failure (ERROR)

## 8. State-Dependent Behavior

- **All States:** Event System operates in all states
- **TEARDOWN State:** Event publishing limited to teardown-related events
- **FAULT State:** Event publishing limited to diagnostic events

## 9. Dependencies

### 9.1 Required Components

- **Logger:** For diagnostic logging
- **Time Utils:** For timestamp generation

### 9.2 Required Interfaces

- Logger interface
- Time Utils interface

## 10. Acceptance Tests

- **T-EVENT-001:** Events are published successfully
- **T-EVENT-002:** Subscribers receive events
- **T-EVENT-003:** Multiple subscribers receive same event
- **T-EVENT-004:** Event publishing is non-blocking
- **T-EVENT-005:** Event queue overflow handling
- **T-EVENT-006:** Event unsubscription works correctly

## 11. Traceability

- **SWR-DESIGN-006:** Event System for cross-component communication
- **CFC-TIME-01:** Non-blocking operation
- **Architecture Requirement:** Event-driven communication

## 12. Implementation Notes

- Event queue SHALL be implemented as lock-free ring buffer
- Maximum queue size: 100 events
- Maximum payload size: 256 bytes
- Maximum subscribers per event type: 10
- Event handlers SHALL be called synchronously (in publisher's context) or asynchronously (in event task context) based on configuration
