ASF-Nabd/ASF_01_sys_sw_arch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

cleanup sw req

Browse Source
This commit is contained in:
mahmamdouh
2026-02-01 19:47:53 +01:00
parent 0bdbcb1657
commit 304371c6b8
608 changed files with 47798 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

528
1 software design/components/event_system/COMPONENT.md Normal file
View File

@@ -0,0 +1,528 @@
# 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
```c
/**
* @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
```c
/**
* @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
```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);
/**
* @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
```c
/**
* @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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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
```c
// 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
```c
// 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
```c
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