ASF_01_sys_sw_arch/1 software design/components/event_system/COMPONENT.md

Event System Component Specification

Component ID: C-EVENT-001
Version: 1.0
Date: 2025-02-01
Location: application_layer/business_stack/event_system/

1. Component Overview and Scope

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

Primary Purpose: Provide event-driven communication infrastructure for loose coupling between system components.

Scope: System-wide event publishing, subscription management, event queuing, and asynchronous event delivery.

2. Responsibilities and Functions

2.1 Primary Responsibilities

• Event Publishing: Accept and queue events from any system component
• Subscription Management: Maintain subscriber lists for each event type
• Event Delivery: Deliver events to all registered subscribers
• Queue Management: Manage event queues with overflow handling
• Non-Blocking Operation: Ensure all operations are non-blocking
• Event Filtering: Support event filtering based on criteria

2.2 Non-Responsibilities

• Event Payload Validation: Components are responsible for payload validation
• Event Ordering: No guaranteed ordering between different event types
• Event Persistence: Events are not persisted (in-memory only)
• Business Logic: Does not implement application-specific logic

3. Provided Interfaces

3.1 Event Publishing Interface

/**
 * @brief Publish an event
 * @param type Event type identifier
 * @param payload Event payload (may be NULL)
 * @param payload_size Payload size in bytes (0 if payload is NULL)
 * @return true if published successfully, 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 identifier
 * @param payload Event payload
 * @param payload_size Payload size
 * @param timestamp Event timestamp
 * @return true if published successfully, false on error
 */
bool event_publishWithTimestamp(event_type_t type, const void* payload, size_t payload_size, uint64_t timestamp);

/**
 * @brief Publish an event from ISR context
 * @param type Event type identifier
 * @param payload Event payload
 * @param payload_size Payload size
 * @return true if published successfully, false on error
 */
bool event_publishFromISR(event_type_t type, const void* payload, size_t payload_size);

3.2 Event Subscription Interface

/**
 * @brief Subscribe to an event type
 * @param type Event type to subscribe to
 * @param handler Callback function for event handling
 * @param priority Subscriber priority (higher values processed first)
 * @return true if subscribed successfully, false on error
 */
bool event_subscribe(event_type_t type, event_handler_t handler, uint8_t priority);

/**
 * @brief Subscribe with filter criteria
 * @param type Event type to subscribe to
 * @param handler Callback function
 * @param filter Filter function (NULL for no filtering)
 * @param priority Subscriber priority
 * @return true if subscribed successfully, false on error
 */
bool event_subscribeWithFilter(event_type_t type, event_handler_t handler, event_filter_t filter, uint8_t priority);

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

/**
 * @brief Unsubscribe from all event types
 * @param handler Callback function to remove from all subscriptions
 * @return Number of subscriptions removed
 */
size_t event_unsubscribeAll(event_handler_t handler);

3.3 Event Queue Management Interface

/**
 * @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);

/**
 * @brief Get event queue statistics
 * @param stats Output buffer for statistics
 * @return true if statistics retrieved successfully
 */
bool event_getQueueStatistics(event_queue_stats_t* stats);

/**
 * @brief Reset event queue statistics
 * @return true if statistics reset successfully
 */
bool event_resetStatistics(void);

3.4 System Control Interface

/**
 * @brief Initialize Event System
 * @return true if initialization successful, false otherwise
 */
bool event_initialize(void);

/**
 * @brief Shutdown Event System
 * @return true if shutdown successful, false otherwise
 */
bool event_shutdown(void);

/**
 * @brief Process pending events (call from event task)
 * @param max_events Maximum number of events to process
 * @return Number of events processed
 */
size_t event_processPending(size_t max_events);

/**
 * @brief Enable/disable event processing
 * @param enabled true to enable, false to disable
 * @return Previous enabled state
 */
bool event_setProcessingEnabled(bool enabled);

4. Required Interfaces

4.1 Time Utils Interface

• Interface: Timestamp generation interface
• Provider: Time Utils component
• Usage: Generate timestamps for events when not provided
• Data Types: uint64_t timestamp in milliseconds

4.2 Logger Interface

• Interface: Logging interface
• Provider: Logger component
• Usage: Log event system diagnostics and errors
• Data Types: Log level, message strings

4.3 RTOS Interface

• Interface: Task synchronization interface
• Provider: OSAL layer
• Usage: Mutex for subscription management, queues for event delivery
• Data Types: Mutex handles, queue handles

5. External Interfaces

5.1 All System Components Interface

• Interface: Event publishing and subscription
• Consumers: All system components
• Usage: Cross-component communication
• Protocol: Function calls with event data structures

6. Internal Interfaces

6.1 Event Queue Manager Interface

• Interface: Internal queue management
• Usage: Queue operations, overflow handling
• Implementation: Private to Event System

6.2 Subscriber Manager Interface

• Interface: Internal subscription management
• Usage: Maintain subscriber lists, priority ordering
• Implementation: Private to Event System

7. Static View

7.1 Component Structure

graph TB
    subgraph EventSystem["Event System"]
        Publisher[Event Publisher]
        SubscriberMgr[Subscriber Manager]
        QueueMgr[Event Queue Manager]
        EventProcessor[Event Processor]
        FilterEngine[Filter Engine]
    end
    
    subgraph Storage["Internal Storage"]
        EventQueue[Event Queue<br/>Lock-Free Ring Buffer]
        SubscriberLists[Subscriber Lists<br/>Per Event Type]
        Statistics[Queue Statistics]
    end
    
    subgraph External["External Components"]
        Components[System Components]
        TimeUtils[Time Utils]
        Logger[Logger]
        RTOS[RTOS/OSAL]
    end
    
    Publisher --> QueueMgr
    QueueMgr --> EventQueue
    SubscriberMgr --> SubscriberLists
    EventProcessor --> QueueMgr
    EventProcessor --> SubscriberMgr
    EventProcessor --> FilterEngine
    
    Components --> Publisher
    Components --> SubscriberMgr
    Publisher --> TimeUtils
    EventProcessor --> Logger
    QueueMgr --> RTOS

7.2 Event Flow Architecture

graph LR
    subgraph Publishers["Event Publishers"]
        SensorMgr[Sensor Manager]
        STM[State Manager]
        CommMgr[Communication Manager]
        OTAMgr[OTA Manager]
    end
    
    subgraph EventSystem["Event System"]
        EventBus[Event Bus<br/>Publish/Subscribe]
    end
    
    subgraph Subscribers["Event Subscribers"]
        DataPool[Data Pool]
        Persistence[Persistence]
        Diagnostics[Diagnostics]
        HMI[HMI]
        MainHubAPI[Main Hub APIs]
    end
    
    SensorMgr --> EventBus
    STM --> EventBus
    CommMgr --> EventBus
    OTAMgr --> EventBus
    
    EventBus --> DataPool
    EventBus --> Persistence
    EventBus --> Diagnostics
    EventBus --> HMI
    EventBus --> MainHubAPI

8. Dynamic View

8.1 Event Publishing and Delivery Sequence

sequenceDiagram
    participant Publisher as Publishing Component
    participant EventSys as Event System
    participant QueueMgr as Queue Manager
    participant EventProc as Event Processor
    participant Subscriber1 as Subscriber 1
    participant Subscriber2 as Subscriber 2
    
    Publisher->>EventSys: event_publish(type, payload, size)
    EventSys->>QueueMgr: enqueue(event)
    QueueMgr->>QueueMgr: add_to_ring_buffer()
    EventSys-->>Publisher: true (success)
    
    Note over EventProc: Event Processing Task
    EventProc->>QueueMgr: dequeue_next_event()
    QueueMgr-->>EventProc: event
    EventProc->>EventProc: get_subscribers(event.type)
    
    par Parallel Delivery
        EventProc->>Subscriber1: handler(type, payload, size, timestamp)
        Subscriber1-->>EventProc: (callback complete)
    and
        EventProc->>Subscriber2: handler(type, payload, size, timestamp)
        Subscriber2-->>EventProc: (callback complete)
    end
    
    EventProc->>EventProc: update_statistics()

8.2 Subscription Management Sequence

sequenceDiagram
    participant Component as Component
    participant EventSys as Event System
    participant SubMgr as Subscriber Manager
    participant SubList as Subscriber List
    
    Component->>EventSys: event_subscribe(type, handler, priority)
    EventSys->>SubMgr: add_subscriber(type, handler, priority)
    SubMgr->>SubList: insert_by_priority(handler, priority)
    SubList-->>SubMgr: success
    SubMgr-->>EventSys: success
    EventSys-->>Component: true
    
    Note over Component,SubList: Later: Unsubscribe
    Component->>EventSys: event_unsubscribe(type, handler)
    EventSys->>SubMgr: remove_subscriber(type, handler)
    SubMgr->>SubList: find_and_remove(handler)
    SubList-->>SubMgr: success
    SubMgr-->>EventSys: success
    EventSys-->>Component: true

8.3 Queue Overflow Handling

sequenceDiagram
    participant Publisher as Publisher
    participant EventSys as Event System
    participant QueueMgr as Queue Manager
    participant Logger as Logger
    
    Publisher->>EventSys: event_publish(type, payload, size)
    EventSys->>QueueMgr: enqueue(event)
    QueueMgr->>QueueMgr: check_queue_full()
    
    alt Queue Full
        QueueMgr->>QueueMgr: drop_oldest_event()
        QueueMgr->>Logger: log_warning("Event queue full, dropping oldest")
        QueueMgr->>QueueMgr: add_new_event()
        QueueMgr-->>EventSys: true (with warning)
    else Queue Available
        QueueMgr->>QueueMgr: add_new_event()
        QueueMgr-->>EventSys: true
    end
    
    EventSys-->>Publisher: result

9. Interface Definitions

9.1 Data Types

// Event Types
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_TEARDOWN_INITIATED,
    EVENT_TEARDOWN_COMPLETE,
    EVENT_SENSOR_FAULT_DETECTED,
    EVENT_SENSOR_STATE_CHANGED,
    EVENT_TYPE_ALL = 0xFF,
    EVENT_TYPE_COUNT
} event_type_t;

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

// Event Handler Callback
typedef void (*event_handler_t)(event_type_t type, const void* payload, size_t payload_size, uint64_t timestamp);

// Event Filter Callback
typedef bool (*event_filter_t)(event_type_t type, const void* payload, size_t payload_size);

// Subscriber Information
typedef struct {
    event_handler_t handler;
    event_filter_t filter;
    uint8_t priority;
    uint32_t call_count;
    uint32_t last_call_time;
} subscriber_info_t;

// Queue Statistics
typedef struct {
    size_t total_events_published;
    size_t total_events_processed;
    size_t total_events_dropped;
    size_t current_queue_size;
    size_t max_queue_size;
    size_t queue_overflows;
    uint32_t avg_processing_time_us;
    uint32_t max_processing_time_us;
    uint32_t total_subscribers;
} event_queue_stats_t;

// Event Priorities
typedef enum {
    EVENT_PRIORITY_LOW = 0,
    EVENT_PRIORITY_NORMAL = 50,
    EVENT_PRIORITY_HIGH = 100,
    EVENT_PRIORITY_CRITICAL = 200
} event_priority_t;

9.2 Configuration Constants

// Queue Configuration
#define EVENT_QUEUE_SIZE            100     // Maximum events in queue
#define EVENT_MAX_PAYLOAD_SIZE      256     // Maximum payload size in bytes
#define EVENT_MAX_SUBSCRIBERS       10      // Maximum subscribers per event type
#define EVENT_PROCESSING_BATCH_SIZE 5       // Events processed per batch

// Timing Configuration
#define EVENT_PROCESSING_TIMEOUT_MS 10      // Maximum time for event processing
#define EVENT_HANDLER_TIMEOUT_MS    5       // Maximum time for single handler

// Memory Configuration
#define EVENT_BUFFER_POOL_SIZE      (EVENT_QUEUE_SIZE * (sizeof(event_t) + EVENT_MAX_PAYLOAD_SIZE))

9.3 Error Codes

typedef enum {
    EVENT_SUCCESS = 0,
    EVENT_ERR_INVALID_PARAMETER,
    EVENT_ERR_QUEUE_FULL,
    EVENT_ERR_PAYLOAD_TOO_LARGE,
    EVENT_ERR_SUBSCRIBER_FULL,
    EVENT_ERR_SUBSCRIBER_NOT_FOUND,
    EVENT_ERR_MEMORY_ALLOCATION,
    EVENT_ERR_SYSTEM_NOT_INITIALIZED,
    EVENT_ERR_PROCESSING_TIMEOUT
} event_error_t;

10. Assumptions and Constraints

10.1 Assumptions

• Event Handlers are Fast: Event handlers complete within 5ms
• Memory Availability: Sufficient memory for event queue and subscriber lists
• RTOS Availability: RTOS primitives (mutex, queues) are available
• Component Cooperation: Components properly unsubscribe during shutdown

10.2 Constraints

• Non-Blocking Publishing: Event publishing must never block
• Memory Limits: Total memory usage limited to 16KB
• Queue Size: Maximum 100 events in queue at any time
• Payload Size: Maximum 256 bytes per event payload
• Subscriber Limit: Maximum 10 subscribers per event type

10.3 Design Constraints

• No Dynamic Memory: Use pre-allocated memory pools
• Thread Safety: All operations must be thread-safe
• ISR Safety: Publishing from ISR context must be supported
• State Independence: Event System operates in all system states

11. Traceability

11.1 Software Requirements

• SWR-DESIGN-006: Event System for cross-component communication
• SWR-DAQ-014: Publish sensor data updates via Event System
• SWR-SYS-004: Notify components of state transitions via Event System

11.2 Features

• F-SYS-01: System State Management (state change notifications)
• F-DAQ-01: Multi-Sensor Data Acquisition (sensor data events)
• F-DIAG-01: Diagnostic Code Management (diagnostic events)

11.3 Cross-Feature Constraints

• CFC-TIME-01: Non-blocking operation
• CFC-ARCH-02: State-aware execution (operates in all states)

11.4 Architecture Requirements

• Event-Driven Architecture: Primary mechanism for component decoupling
• Asynchronous Communication: Enables non-blocking inter-component communication

---

Document Status: Final for Implementation
Dependencies: Time Utils, Logger, OSAL
Next Review: After component implementation and performance testing