diff --git a/README.md b/README.md index e1a78ac..f8a7754 100644 --- a/README.md +++ b/README.md @@ -104,8 +104,27 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ``` timpani/ ├── README.md # This file - main project overview +├── doc/ # 📚 Comprehensive documentation +│ ├── README.md # Documentation guide +│ ├── architecture/ # Architecture documentation +│ │ ├── HLD/ # High-Level Design +│ │ │ ├── timpani_system_design_document.md +│ │ │ └── timpani_rust_grpc_architecture.md +│ │ └── LLD/ # Low-Level Design +│ │ ├── timpani-o/ # Orchestrator components (10 docs) +│ │ └── timpani-n/ # Node executor components (10 docs) +│ ├── features/ # Feature & Requirements +│ │ ├── timpani_features.md +│ │ └── requirements/timpani_requirements.md +│ ├── docs/ # Implementation guides +│ │ ├── api.md +│ │ ├── getting-started.md +│ │ └── developments.md +│ └── contribution/ # Contribution guidelines +│ ├── coding-rule.md +│ └── guidelines-en.md ├── sample-apps/ -│ ├── README.md # Sample applications documentation +│ └── README.md # Sample applications documentation ├── timpani-n/ │ ├── README.md # C implementation: Node executor │ ├── README.CentOS.md # CentOS setup guide diff --git a/doc/README.md b/doc/README.md index e1b96b4..bcb1f8e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -8,7 +8,7 @@ **Document Information:** - **Issuing Author:** Eclipse timpani Team - **Configuration ID:** timpani-doc-index -- **Document Status:** Published +- **Document Status:** Draft - **Last Updated:** 2026-05-13 --- @@ -17,6 +17,7 @@ | Version | Date | Comment | Author | Approver | |---------|------|---------|--------|----------| +| 0.0b | 2026-05-13 | Added HLD section with system design and gRPC architecture | LGSI-KarumuriHari | - | | 0.0a | 2026-05-13 | Initial documentation guide | Eclipse timpani Team | - | --- @@ -38,10 +39,16 @@ This documentation provides a comprehensive guide to the timpani project's migra ### 1️⃣ **Architecture Documentation** 📁 [`architecture/`](architecture/) -System architecture, communication protocols, and high-level design documentation. +System architecture, communication protocols, and design documentation. -- [timpani Architecture](architecture/timpani_architecture.md) - Overall system architecture -- [gRPC Architecture](architecture/grpc_architecture.md) - Communication layer design +#### High-Level Design (HLD) Documents +📁 [`architecture/HLD/`](architecture/HLD/) + +System-level architecture and technology integration documentation. + +**System Architecture:** +- [timpani System Design Document](architecture/HLD/timpani_system_design_document.md) - Overall system architecture, components, deployment +- [timpani gRPC Integration Architecture](architecture/HLD/timpani_rust_grpc_architecture.md) - D-Bus → gRPC migration, communication flow, performance #### Low-Level Design (LLD) Documents 📁 [`architecture/LLD/`](architecture/LLD/) @@ -76,11 +83,25 @@ Component-level LLD documents comparing legacy C/C++ with Rust implementations. - 10: Data Structures - [README](architecture/LLD/timpani-n/README.md) - Component overview & migration status -**🔍 Focus:** Understand system architecture and component-level AS-IS vs WILL-BE comparisons +**🔍 Focus:** +- **HLD:** System-level architecture, technology stack, deployment patterns +- **LLD:** Component-level AS-IS vs WILL-BE comparisons, implementation details + +--- + +### 2️⃣ **Feature Specifications & Requirements** +📁 [`features/`](features/) + +System feature breakdown and requirements documentation. + +- [timpani Feature Specification](features/timpani_features.md) - Feature breakdown with mermaid diagrams, 3-level feature tables +- [timpani Requirements Specification](features/requirements/timpani_requirements.md) - Functional and non-functional requirements + +**🔍 Focus:** Understand system capabilities, feature mapping, and requirement traceability --- -### 2️⃣ **Implementation Documentation** +### 3️⃣ **Implementation Documentation** 📁 [`docs/`](docs/) Detailed developer guides, APIs, and development workflows. @@ -95,7 +116,7 @@ Detailed developer guides, APIs, and development workflows. --- -### 3️⃣ **Contribution Guidelines** +### 4️⃣ **Contribution Guidelines** 📁 [`contribution/`](contribution/) Development standards, coding rules, and workflow guidelines. @@ -111,39 +132,47 @@ Development standards, coding rules, and workflow guidelines. ```mermaid graph TD - subgraph "1. Architecture Phase" - A1[System Architecture
timpani_architecture.md] - A2[gRPC Architecture
grpc_architecture.md] + subgraph "1. Features & Requirements" + F1[Feature Specification
features/timpani_features.md] + F2[Requirements Specification
features/requirements/timpani_requirements.md] + end + + subgraph "2. High-Level Architecture" + HLD1[System Design Document
HLD/timpani_system_design_document.md] + HLD2[gRPC Integration Architecture
HLD/timpani_rust_grpc_architecture.md] end - subgraph "2. Component LLD" - H1[timpani-o LLD
10 Components] - H2[timpani-n LLD
10 Components] - H3[AS-IS vs WILL-BE
Comparisons] + subgraph "3. Component LLD" + LLD1[timpani-o LLD
10 Components] + LLD2[timpani-n LLD
10 Components] + LLD3[AS-IS vs WILL-BE
Comparisons] end - subgraph "3. Implementation Phase" + subgraph "4. Implementation Phase" I1[API Documentation] I2[Getting Started] I3[Development Guide] I4[Project Structure] end - subgraph "4. Quality Assurance" + subgraph "5. Quality Assurance" Q1[Coding Standards] Q2[Review Process] Q3[Release Guide] end - A1 --> H1 - A1 --> H2 - A2 --> H1 - A2 --> H2 + F1 --> F2 + F2 --> HLD1 + F2 --> HLD2 + HLD1 --> LLD1 + HLD2 --> LLD1 + HLD1 --> LLD2 + HLD2 --> LLD2 - H1 --> H3 - H2 --> H3 + LLD1 --> LLD3 + LLD2 --> LLD3 - H3 --> I1 + LLD3 --> I1 I1 --> I2 I2 --> I3 I3 --> I4 @@ -152,8 +181,9 @@ graph TD Q1 --> Q2 Q2 --> Q3 - style A1 fill:#e3f2fd - style H3 fill:#e8f5e8 + style F1 fill:#fff9c4 + style HLD1 fill:#e3f2fd + style LLD3 fill:#e8f5e8 style I1 fill:#fff3e0 style Q3 fill:#f3e5f5 ``` @@ -166,12 +196,17 @@ graph TD eclipse_timpani/ ├── doc/ # 📚 All documentation (YOU ARE HERE) │ ├── README.md # This file -│ ├── architecture/ # Architecture & LLD documentation -│ │ ├── timpani_architecture.md -│ │ ├── grpc_architecture.md +│ ├── architecture/ # Architecture documentation +│ │ ├── HLD/ # High-Level Design documents +│ │ │ ├── timpani_system_design_document.md +│ │ │ └── timpani_rust_grpc_architecture.md │ │ └── LLD/ # Low-Level Design documents -│ │ ├── timpani-o/ # timpani-o component LLDs -│ │ └── timpani-n/ # timpani-n component LLDs +│ │ ├── timpani-o/ # timpani-o component LLDs (10 docs) +│ │ └── timpani-n/ # timpani-n component LLDs (10 docs) +│ ├── features/ # Feature & Requirements +│ │ ├── timpani_features.md +│ │ └── requirements/ +│ │ └── timpani_requirements.md │ ├── docs/ # Implementation guides │ │ ├── api.md │ │ ├── getting-started.md @@ -196,10 +231,12 @@ eclipse_timpani/ ## 🔍 Development Checklist -### Step 1: Architecture Review -- [ ] System architecture documentation is complete and accurate -- [ ] gRPC architecture addresses all communication requirements -- [ ] Component boundaries are clearly defined +### Step 1: High-Level Architecture Review +- [ ] HLD: System design documentation is complete and accurate +- [ ] HLD: gRPC architecture addresses all communication requirements +- [ ] HLD: Technology stack and deployment patterns documented +- [ ] Feature specifications with mermaid diagrams reviewed +- [ ] Requirements (FR/NFR) traceability established ### Step 2: Component LLD Review - [ ] AS-IS architecture accurately reflects legacy implementation (C/C++) @@ -230,9 +267,9 @@ eclipse_timpani/ - Consult [GitHub Issues](https://github.com/eclipse-timpani/timpani/issues) ### For Architecture Clarifications -- Refer to [timpani Architecture](architecture/timpani_architecture.md) -- Review [gRPC Architecture](architecture/grpc_architecture.md) -- Check component LLDs in [LLD/timpani-o/](architecture/LLD/timpani-o/) or [LLD/timpani-n/](architecture/LLD/timpani-n/) +- **HLD:** Review [System Design Document](architecture/HLD/timpani_system_design_document.md) or [gRPC Architecture](architecture/HLD/timpani_rust_grpc_architecture.md) +- **Features:** Check [Feature Specification](features/timpani_features.md) or [Requirements](features/requirements/timpani_requirements.md) +- **LLD:** Check component LLDs in [LLD/timpani-o/](architecture/LLD/timpani-o/) or [LLD/timpani-n/](architecture/LLD/timpani-n/) ### For Development Queries - Review architecture documentation: `architecture/` → `LLD/` → `docs/` diff --git a/doc/architecture/timpani_rust_grpc_architecture.md b/doc/architecture/HLD/timpani_rust_grpc_architecture.md similarity index 80% rename from doc/architecture/timpani_rust_grpc_architecture.md rename to doc/architecture/HLD/timpani_rust_grpc_architecture.md index 968c016..f209f73 100644 --- a/doc/architecture/timpani_rust_grpc_architecture.md +++ b/doc/architecture/HLD/timpani_rust_grpc_architecture.md @@ -8,8 +8,8 @@ **Document Information:** - **Issuing Author:** Eclipse timpani Team - **Configuration ID:** timpani-arch-grpc -- **Document Status:** Published -- **Last Updated:** 2026-05-13 +- **Document Status:** Draft +- **Last Updated:** 2026-05-14 --- @@ -17,6 +17,8 @@ | Version | Date | Comment | Author | Approver | |---------|------|---------|--------|----------| +| 0.0c | 2026-05-14 | Updated legend color scheme: gRPC communication links styled with orange (#f57c00) | LGSI-KarumuriHari | - | +| 0.0b | 2026-05-13 | Added diagram legends highlighting timpani-o and timpani-n scope | LGSI-KarumuriHari | - | | 0.0a | 2026-05-13 | Initial gRPC architecture documentation | Eclipse timpani Team | - | --- @@ -110,11 +112,11 @@ graph TB TimpaniO <-->|"D-Bus libtrpc
(custom serialization)"| Node2 TimpaniO <-->|"D-Bus libtrpc
(custom serialization)"| NodeN - style Pullpiri fill:#e1f5ff - style TimpaniO fill:#ffe1e1 - style Node1 fill:#e1ffe1 - style Node2 fill:#e1ffe1 - style NodeN fill:#e1ffe1 + style Pullpiri fill:#f5f5f5,stroke:#757575,stroke-width:2px + style TimpaniO fill:#ffe1e1,stroke:#d32f2f,stroke-width:3px + style Node1 fill:#e1ffe1,stroke:#388e3c,stroke-width:3px + style Node2 fill:#e1ffe1,stroke:#388e3c,stroke-width:3px + style NodeN fill:#e1ffe1,stroke:#388e3c,stroke-width:3px ``` **Issues:** @@ -143,16 +145,29 @@ graph TB NodeN["Node N
timpani-n
(gRPC Client)"] end + subgraph Legend[" "] + L1["timpani-o (Our Scope)"] + L2["timpani-n (Our Scope)"] + L3["gRPC Communication (Our Scope)"] + L4["External Systems"] + end + Pullpiri <-->|"gRPC
SchedInfoService
FaultService"| TimpaniO TimpaniO <-->|"gRPC/HTTP2
NodeService"| Node1 TimpaniO <-->|"gRPC/HTTP2
NodeService"| Node2 TimpaniO <-->|"gRPC/HTTP2
NodeService"| NodeN - style Pullpiri fill:#e1f5ff - style TimpaniO fill:#ffd4a3 - style Node1 fill:#c8e6c9 - style Node2 fill:#c8e6c9 - style NodeN fill:#c8e6c9 + style Pullpiri fill:#f5f5f5,stroke:#757575,stroke-width:2px + style TimpaniO fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style Node1 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style Node2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style NodeN fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style L1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style L2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style L3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style L4 fill:#f5f5f5,stroke:#757575,stroke-width:2px + + linkStyle 0,1,2,3 stroke:#f57c00,stroke-width:3px,color:#f57c00 ``` **Improvements:** @@ -210,6 +225,13 @@ graph TB SchedLoopN --> BPFN end + subgraph Legend[" "] + L1["timpani-o (Our Scope)"] + L2["timpani-n (Our Scope)"] + L3["gRPC Communication (Our Scope)"] + L4["External Systems"] + end + SchedInfoClient -->|"gRPC :50051
AddSchedInfo"| SchedInfoSvc FaultServer <-->|"gRPC :50052
NotifyFault"| TimpaniO @@ -217,11 +239,31 @@ graph TB NodeClient2 <-->|"gRPC :50051
NodeService"| NodeSvc NodeClientN <-->|"gRPC :50051
NodeService"| NodeSvc - style PullpiriSystem fill:#e1f5ff - style TimpaniO fill:#ffd4a3 - style Node1 fill:#c8e6c9 - style Node2 fill:#c8e6c9 - style NodeN fill:#c8e6c9 + style PullpiriSystem fill:#f5f5f5,stroke:#757575,stroke-width:2px + style SchedInfoClient fill:#f5f5f5,stroke:#757575,stroke-width:2px + style FaultServer fill:#f5f5f5,stroke:#757575,stroke-width:2px + style TimpaniO fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style SchedInfoSvc fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style GlobalSched fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style NodeSvc fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style Node1 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style Node2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style NodeN fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style NodeClient1 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style SchedLoop1 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style BPF1 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style NodeClient2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style SchedLoop2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style BPF2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style NodeClientN fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style SchedLoopN fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style BPFN fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style L1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style L2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style L3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style L4 fill:#f5f5f5,stroke:#757575,stroke-width:2px + + linkStyle 8,9,10,11,12 stroke:#f57c00,stroke-width:3px,color:#f57c00 ``` ### Layer Diagram @@ -250,6 +292,13 @@ graph TD Kernel["Linux Kernel
• sched_setscheduler
• sched_setaffinity
• eBPF subsystem
• POSIX timers"] end + subgraph Legend[" "] + L1["timpani-o (Our Scope)"] + L2["timpani-n (Our Scope)"] + L3["gRPC Communication (Our Scope)"] + L4["External Systems"] + end + Pullpiri --> Services HTTP2 --> TimpaniO HTTP2 --> TimpaniN @@ -257,10 +306,24 @@ graph TD TimpaniN --> Kernel WorkloadApps -.->|scheduled by| TimpaniN - style AppLayer fill:#e3f2fd - style gRPCLayer fill:#fff3e0 - style BusinessLayer fill:#f1f8e9 - style OSLayer fill:#fce4ec + style AppLayer fill:#f5f5f5,stroke:#757575,stroke-width:2px + style Pullpiri fill:#f5f5f5,stroke:#757575,stroke-width:2px + style WorkloadApps fill:#f5f5f5,stroke:#757575,stroke-width:2px + style gRPCLayer fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style Services fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style Tonic fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style HTTP2 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style BusinessLayer fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style TimpaniO fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style TimpaniN fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style OSLayer fill:#fce4ec,stroke:#c2185b,stroke-width:2px + style Kernel fill:#fce4ec,stroke:#c2185b,stroke-width:2px + style L1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style L2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style L3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style L4 fill:#f5f5f5,stroke:#757575,stroke-width:2px + + linkStyle 0,1,2,3,4 stroke:#f57c00,stroke-width:3px,color:#f57c00 ``` --- diff --git a/doc/architecture/timpani_architecture.md b/doc/architecture/HLD/timpani_system_design_document.md similarity index 73% rename from doc/architecture/timpani_architecture.md rename to doc/architecture/HLD/timpani_system_design_document.md index d9c9251..b9f8d63 100644 --- a/doc/architecture/timpani_architecture.md +++ b/doc/architecture/HLD/timpani_system_design_document.md @@ -3,13 +3,13 @@ * SPDX-License-Identifier: MIT --> -# timpani System Architecture +# timpani System Design Document **Document Information:** - **Issuing Author:** Eclipse timpani Team - **Configuration ID:** timpani-arch-system -- **Document Status:** Published -- **Last Updated:** 2026-05-13 +- **Document Status:** Draft +- **Last Updated:** 2026-05-14 --- @@ -17,15 +17,13 @@ | Version | Date | Comment | Author | Approver | |---------|------|---------|--------|----------| +| 0.0c | 2026-05-14 | Updated diagram legends with consistent color scheme across all diagrams | LGSI-KarumuriHari | - | +| 0.0b | 2026-05-13 | Added diagram legends highlighting timpani-o and timpani-n scope | LGSI-KarumuriHari | - | | 0.0a | 2026-05-13 | Initial system architecture documentation | Eclipse timpani Team | - | --- -**Document Version:** 1.0 -**Last Updated:** May 12, 2026 -**Status:** Living Document ---- ## System Overview @@ -63,6 +61,13 @@ graph TB E2[Fault Manager] end + subgraph Legend[" "] + L1["timpani-o (Our Scope)"] + L2["timpani-n (Our Scope)"] + L3["Communication Layer"] + L4["External Systems"] + end + O1 --> O2 O1 --> O3 O4 --> O1 @@ -78,10 +83,24 @@ graph TB N2 --> E1 N4 --> O6 - style O1 fill:#e3f2fd - style N1 fill:#e8f5e9 - style O6 fill:#fff3e0 - style N6 fill:#fff3e0 + style O1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style O2 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style O3 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style O4 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style O5 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style N1 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style N2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style N3 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style N4 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style N5 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style O6 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style N6 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style E1 fill:#f5f5f5,stroke:#757575,stroke-width:2px + style E2 fill:#f5f5f5,stroke:#757575,stroke-width:2px + style L1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style L2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style L3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style L4 fill:#f5f5f5,stroke:#757575,stroke-width:2px ``` --- @@ -197,13 +216,25 @@ graph LR FM[Fault Manager] end + subgraph Legend[" "] + L1["timpani-o (Our Scope)"] + L2["timpani-n (Our Scope)"] + L3["External Systems"] + end + N1 <-->|gRPC
:50054| TO N2 <-->|gRPC
:50054| TO TO <-->|gRPC| FM - style TO fill:#e3f2fd - style N1 fill:#e8f5e9 - style N2 fill:#e8f5e9 + style TO fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style N1 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style N2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style A1 fill:#f5f5f5,stroke:#757575,stroke-width:2px + style A2 fill:#f5f5f5,stroke:#757575,stroke-width:2px + style FM fill:#f5f5f5,stroke:#757575,stroke-width:2px + style L1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style L2 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px + style L3 fill:#f5f5f5,stroke:#757575,stroke-width:2px ``` --- diff --git a/doc/docs/structure.md b/doc/docs/structure.md index 5b39d9b..87fe499 100644 --- a/doc/docs/structure.md +++ b/doc/docs/structure.md @@ -9,7 +9,7 @@ **Document Information:** - **Issuing Author:** Eclipse timpani Team - **Configuration ID:** timpani-doc-structure -- **Document Status:** Published +- **Document Status:** Draft - **Last Updated:** 2026-05-13 --- @@ -18,6 +18,7 @@ | Version | Date | Comment | Author | Approver | |---------|------|---------|--------|----------| +| 0.0b | 2026-05-13 | Added HLD section and features/requirements documentation | LGSI-KarumuriHari | - | | 0.0a | 2026-05-13 | Initial structure documentation | Eclipse timpani Team | - | --- @@ -39,11 +40,16 @@ timpani/ ├── doc/ │ ├── README.md # Documentation guide │ ├── architecture/ -│ │ ├── timpani_architecture.md # System architecture -│ │ ├── grpc_architecture.md # gRPC design +│ │ ├── HLD/ # High-Level Design documents +│ │ │ ├── timpani_system_design_document.md +│ │ │ └── timpani_rust_grpc_architecture.md │ │ └── LLD/ # Low-Level Design documents │ │ ├── timpani-o/ # timpani-o component LLDs (10 docs) │ │ └── timpani-n/ # timpani-n component LLDs (10 docs) +│ ├── features/ +│ │ ├── timpani_features.md # Feature specification +│ │ └── requirements/ +│ │ └── timpani_requirements.md # FR/NFR requirements │ ├── contribution/ │ │ ├── coding-rule.md │ │ └── guidelines-en.md @@ -171,11 +177,17 @@ timpani_rust/ The `doc/` directory contains all project documentation: -- **architecture/**: System architecture and LLD component documents - - `timpani_architecture.md`: Overall system design - - `grpc_architecture.md`: Communication layer design - - `LLD/timpani-o/`: 10 component LLD documents (AS-IS vs WILL-BE) - - `LLD/timpani-n/`: 10 component LLD documents (AS-IS vs WILL-BE) +- **architecture/**: System architecture documentation + - **HLD/**: High-Level Design documents + - `timpani_system_design_document.md`: Overall system architecture, components, deployment + - `timpani_rust_grpc_architecture.md`: D-Bus → gRPC migration, communication flow, performance + - **LLD/**: Low-Level Design component documents + - `timpani-o/`: 10 component LLD documents (AS-IS vs WILL-BE) + - `timpani-n/`: 10 component LLD documents (AS-IS vs WILL-BE) + +- **features/**: Feature specifications and requirements + - `timpani_features.md`: Feature breakdown with mermaid diagrams, 3-level feature tables + - `requirements/timpani_requirements.md`: Functional and non-functional requirements (FR/NFR) - **docs/**: Implementation and developer guides - `api.md`: gRPC services and Rust APIs @@ -194,9 +206,9 @@ The `doc/` directory contains all project documentation: | Component | Legacy | Rust | Status | Documentation | |-----------|--------|------|--------|---------------| -| **timpani-o** | C++ | Rust | ✅ Complete | [LLD/timpani-o/](../architecture/LLD/timpani-o/) | -| **timpani-n** | C | Rust | 🔄 Partial | [LLD/timpani-n/](../architecture/LLD/timpani-n/) | -| **Communication** | D-Bus | gRPC | ✅ timpani-o, ⏸️ timpani-n | [grpc_architecture.md](../architecture/grpc_architecture.md) | +| **timpani-o** | C++ | Rust | ✅ Complete | [HLD](../architecture/HLD/timpani_system_design_document.md), [LLD/timpani-o/](../architecture/LLD/timpani-o/) | +| **timpani-n** | C | Rust | 🔄 Partial | [HLD](../architecture/HLD/timpani_system_design_document.md), [LLD/timpani-n/](../architecture/LLD/timpani-n/) | +| **Communication** | D-Bus | gRPC | ✅ timpani-o, ⏸️ timpani-n | [gRPC Architecture](../architecture/HLD/timpani_rust_grpc_architecture.md) | --- diff --git a/doc/features/requirements/timpani_requirements.md b/doc/features/requirements/timpani_requirements.md new file mode 100644 index 0000000..e2887d9 --- /dev/null +++ b/doc/features/requirements/timpani_requirements.md @@ -0,0 +1,631 @@ + + +# timpani System Requirements Specification + +**Document Information:** +- **Issuing Author:** LGSI-KarumuriHari(Eclipse timpani Team) +- **Configuration ID:** timpani-req-spec +- **Document Status:** Draft +- **Last Updated:** 2026-05-14 + +--- + +## Revision History + +| Version | Date | Comment | Author | Approver | +|---------|------|---------|--------|----------| +| 0.0c | 2026-05-14 | Added gPTP time synchronization requirement (Milestone 3) | LGSI-KarumuriHari | - | +| 0.0b | 2026-05-13 | Expanded functional and non-functional requirements | LGSI-KarumuriHari | - | +| 0.0a | 2026-02-24 | Initial requirements specification | Eclipse timpani Team | - | + +--- + +## Table of Contents + +1. [Introduction](#introduction) +2. [Functional Requirements](#functional-requirements) +3. [Non-Functional Requirements](#non-functional-requirements) +4. [Requirements Traceability Matrix](#requirements-traceability-matrix) + +--- + +## Introduction + +This document specifies the functional and non-functional requirements for the Eclipse timpani distributed real-time task orchestration framework. timpani consists of two primary components: timpani-o (global orchestrator) and timpani-n (node executor), designed to provide deterministic real-time task execution across distributed systems. + +### Scope + +This requirements specification covers: +- Real-time task scheduling and execution +- Distributed node coordination and communication +- Fault detection and recovery mechanisms +- System monitoring and observability +- Configuration and deployment management + +--- + +## Functional Requirements + +### FR-1: Real-Time Scheduling + +#### FR-1.1: Task Scheduling Algorithms +**Requirement:** The system SHALL support multiple real-time scheduling algorithms. +- **FR-1.1.1:** Support Rate Monotonic (RM) priority assignment +- **FR-1.1.2:** Support Earliest Deadline First (EDF) scheduling +- **FR-1.1.3:** Support SCHED_DEADLINE Linux scheduling policy +- **FR-1.1.4:** Provide schedulability analysis using Liu & Layland bounds + +**Priority:** High +**Component:** timpani-o (Global Scheduler) + +#### FR-1.2: Hyperperiod Calculation +**Requirement:** The system SHALL calculate hyperperiod for periodic task sets. +- **FR-1.2.1:** Compute Least Common Multiple (LCM) of all task periods +- **FR-1.2.2:** Validate hyperperiod against maximum supported value +- **FR-1.2.3:** Store hyperperiod information for schedule validation + +**Priority:** High +**Component:** timpani-o (Hyperperiod Manager) + +#### FR-1.3: CPU Utilization Analysis +**Requirement:** The system SHALL analyze CPU utilization for schedulability. +- **FR-1.3.1:** Calculate per-task CPU utilization (WCET/Period) +- **FR-1.3.2:** Compute total system utilization +- **FR-1.3.3:** Verify utilization against schedulability bounds +- **FR-1.3.4:** Reject schedules exceeding utilization limits + +**Priority:** High +**Component:** timpani-o (Scheduler Utilities) + +--- + +### FR-2: Task Management + +#### FR-2.1: Task Definition +**Requirement:** The system SHALL support comprehensive task specification. +- **FR-2.1.1:** Define task period (minimum 1ms, maximum 10s) +- **FR-2.1.2:** Define task deadline (≤ period) +- **FR-2.1.3:** Define worst-case execution time (WCET) +- **FR-2.1.4:** Define task priority (1-99 for SCHED_DEADLINE) +- **FR-2.1.5:** Define CPU affinity constraints + +**Priority:** High +**Component:** timpani-o (Data Structures), timpani-n (Task Manager) + +#### FR-2.2: Task Lifecycle Management +**Requirement:** The system SHALL manage complete task lifecycle. +- **FR-2.2.1:** Initialize tasks with specified parameters +- **FR-2.2.2:** Activate tasks at scheduled release times +- **FR-2.2.3:** Track task execution state (ready, running, completed, missed) +- **FR-2.2.4:** Terminate tasks on completion or system shutdown +- **FR-2.2.5:** Handle task preemption and context switching + +**Priority:** High +**Component:** timpani-n (Task Manager, RT Scheduler) + +#### FR-2.3: Task Isolation +**Requirement:** The system SHALL provide task isolation mechanisms. +- **FR-2.3.1:** Assign tasks to specific CPU cores via affinity masks +- **FR-2.3.2:** Prevent interference between tasks on different cores +- **FR-2.3.3:** Support mixed-criticality task sets + +**Priority:** Medium +**Component:** timpani-n (RT Scheduler) + +--- + +### FR-3: Communication + +#### FR-3.1: gRPC Communication +**Requirement:** The system SHALL implement gRPC-based communication. +- **FR-3.1.1:** Provide SchedInfoService for workload submission (timpani-o) +- **FR-3.1.2:** Provide NodeService for schedule distribution (timpani-o) +- **FR-3.1.3:** Implement gRPC client for schedule retrieval (timpani-n) +- **FR-3.1.4:** Use Protocol Buffers for message serialization +- **FR-3.1.5:** Support asynchronous RPC calls using Tokio runtime + +**Priority:** High +**Component:** timpani-o (gRPC Server), timpani-n (gRPC Client) + +#### FR-3.2: Legacy D-Bus Support +**Requirement:** The C implementation SHALL support D-Bus communication (replaced in Rust). +- **FR-3.2.1:** Provide libtrpc interface for C-based timpani-n +- **FR-3.2.2:** Support D-Bus method calls for schedule retrieval +- **FR-3.2.3:** Maintain backward compatibility with C implementation + +**Priority:** Low (Legacy) +**Component:** timpani-n (libtrpc Client) + +#### FR-3.3: Fault Reporting +**Requirement:** The system SHALL report fault events to orchestrator. +- **FR-3.3.1:** Detect deadline miss events +- **FR-3.3.2:** Report deadline misses to Pullpiri via gRPC FaultService +- **FR-3.3.3:** Include task ID, node ID, timestamp, and miss count +- **FR-3.3.4:** Support batch reporting for multiple faults + +**Priority:** High +**Component:** timpani-o (Fault Client) + +--- + +### FR-4: Node Management + +#### FR-4.1: Node Configuration +**Requirement:** The system SHALL manage node hardware specifications. +- **FR-4.1.1:** Load node configurations from YAML files +- **FR-4.1.2:** Specify CPU count, memory, and architecture per node +- **FR-4.1.3:** Validate node configuration against hardware capabilities +- **FR-4.1.4:** Support dynamic node addition (hot-plug) + +**Priority:** High +**Component:** timpani-o (NodeConfigManager) + +#### FR-4.2: Schedule Distribution +**Requirement:** The system SHALL distribute schedules to execution nodes. +- **FR-4.2.1:** Send computed schedules to timpani-n nodes via gRPC +- **FR-4.2.2:** Include task parameters, release times, and affinity +- **FR-4.2.3:** Support incremental schedule updates +- **FR-4.2.4:** Confirm schedule receipt and activation + +**Priority:** High +**Component:** timpani-o (Node Service), timpani-n (Schedule Receiver) + +#### FR-4.3: Node Synchronization +**Requirement:** The system SHALL synchronize execution across nodes. +- **FR-4.3.1:** Coordinate simultaneous schedule activation +- **FR-4.3.2:** Provide synchronization barriers for distributed tasks +- **FR-4.3.3:** Handle clock skew between nodes (< 1ms tolerance) + +**Priority:** Medium +**Component:** timpani-o (Node Service), timpani-n (Main Controller) + +--- + +### FR-5: Monitoring and Observability + +#### FR-5.1: eBPF Monitoring +**Requirement:** The system SHALL provide kernel-level monitoring via eBPF. +- **FR-5.1.1:** Monitor scheduler events using tracepoints (schedstat.bpf.c) +- **FR-5.1.2:** Monitor signal delivery timing (sigwait.bpf.c) +- **FR-5.1.3:** Collect scheduling latency and context switch data +- **FR-5.1.4:** Transfer monitoring data via BPF ring buffers + +**Priority:** Medium +**Component:** timpani-n (BPF Monitoring) + +#### FR-5.2: Deadline Miss Detection +**Requirement:** The system SHALL detect and report deadline violations. +- **FR-5.2.1:** Monitor task completion times against deadlines +- **FR-5.2.2:** Generate deadline miss events with timestamp and task ID +- **FR-5.2.3:** Log deadline misses for post-mortem analysis +- **FR-5.2.4:** Trigger fault recovery mechanisms on repeated misses + +**Priority:** High +**Component:** timpani-n (Signal Handler, BPF Monitoring) + +#### FR-5.3: Performance Metrics +**Requirement:** The system SHALL collect performance metrics. +- **FR-5.3.1:** Measure end-to-end schedule activation latency +- **FR-5.3.2:** Track CPU utilization per task and per core +- **FR-5.3.3:** Measure communication latency (gRPC call duration) +- **FR-5.3.4:** Export metrics in Prometheus format (future) + +**Priority:** Low +**Component:** timpani-o, timpani-n (Monitoring Layer) + +--- + +### FR-6: Configuration Management + +#### FR-6.1: Command-Line Interface +**Requirement:** The system SHALL provide CLI configuration. +- **FR-6.1.1:** Parse command-line arguments using Clap (Rust) or getopt (C) +- **FR-6.1.2:** Support configuration file path specification +- **FR-6.1.3:** Provide --help and --version options +- **FR-6.1.4:** Validate all configuration parameters + +**Priority:** Medium +**Component:** timpani-o, timpani-n (Configuration Manager) + +#### FR-6.2: YAML Configuration +**Requirement:** The system SHALL support YAML-based configuration. +- **FR-6.2.1:** Parse YAML files using serde_yaml (Rust) +- **FR-6.2.2:** Define node hardware specifications in YAML +- **FR-6.2.3:** Define default task parameters in YAML +- **FR-6.2.4:** Support environment variable substitution + +**Priority:** Medium +**Component:** timpani-o (NodeConfigManager) + +#### FR-6.3: Configuration Validation +**Requirement:** The system SHALL validate all configuration inputs. +- **FR-6.3.1:** Verify parameter ranges (period, deadline, WCET) +- **FR-6.3.2:** Check for conflicting settings +- **FR-6.3.3:** Provide meaningful error messages for invalid config +- **FR-6.3.4:** Apply default values for optional parameters + +**Priority:** Medium +**Component:** timpani-o, timpani-n (Configuration Manager) + +--- + +### FR-7: Fault Tolerance + +#### FR-7.1: Error Handling +**Requirement:** The system SHALL implement structured error handling. +- **FR-7.1.1:** Use Result types for error propagation (Rust) +- **FR-7.1.2:** Define specific error types for each failure mode +- **FR-7.1.3:** Log errors with context and stack traces +- **FR-7.1.4:** Provide recovery hints in error messages + +**Priority:** High +**Component:** timpani-o (Error Handling) + +#### FR-7.2: Graceful Degradation +**Requirement:** The system SHALL degrade gracefully under failure. +- **FR-7.2.1:** Continue operation with reduced node count +- **FR-7.2.2:** Reschedule tasks from failed nodes +- **FR-7.2.3:** Maintain critical task execution during partial failures +- **FR-7.2.4:** Retry failed gRPC calls with exponential backoff + +**Priority:** Medium +**Component:** timpani-o (Global Scheduler, Node Service) + +#### FR-7.3: Shutdown Handling +**Requirement:** The system SHALL support graceful shutdown. +- **FR-7.3.1:** Handle SIGTERM and SIGINT signals +- **FR-7.3.2:** Complete in-flight tasks before shutdown +- **FR-7.3.3:** Clean up system resources (timers, file descriptors) +- **FR-7.3.4:** Notify connected nodes of shutdown + +**Priority:** Medium +**Component:** timpani-o, timpani-n (Signal Handler, Main Controller) + +--- + +### FR-8: Timer Management + +#### FR-8.1: POSIX Timers +**Requirement:** The system SHALL use POSIX timers for periodic activation. +- **FR-8.1.1:** Create timers using timer_create() with CLOCK_MONOTONIC +- **FR-8.1.2:** Configure timer periods using timer_settime() +- **FR-8.1.3:** Deliver timer signals (SIGALRM) for task activation +- **FR-8.1.4:** Support timer resolution ≤ 1ms + +**Priority:** High +**Component:** timpani-n (Timer Manager) + +#### FR-8.2: Timer Synchronization +**Requirement:** The system SHALL synchronize timers across tasks. +- **FR-8.2.1:** Align task release times to hyperperiod boundaries +- **FR-8.2.2:** Minimize jitter in timer delivery (< 100μs) +- **FR-8.2.3:** Handle timer overruns gracefully + +**Priority:** Medium +**Component:** timpani-n (Timer Manager) + +--- + +### FR-9: Time Synchronization (gPTP) + +#### FR-9.1: IEEE 802.1AS Protocol Support +**Requirement:** The system SHALL support gPTP (generalized Precision Time Protocol) for distributed time synchronization. +- **FR-9.1.1:** Implement IEEE 802.1AS-2020 time synchronization protocol +- **FR-9.1.2:** Support both grandmaster and slave clock roles +- **FR-9.1.3:** Synchronize system clocks across all timpani-n nodes +- **FR-9.1.4:** Maintain time synchronization accuracy ≤ 1 microsecond +- **FR-9.1.5:** Support PTP over Ethernet (Layer 2) + +**Priority:** High (Milestone 3) +**Component:** timpani-n (Time Sync Manager), timpani-o (Clock Coordinator) + +#### FR-9.2: Clock Synchronization +**Requirement:** The system SHALL maintain synchronized clocks across distributed nodes. +- **FR-9.2.1:** Synchronize CLOCK_REALTIME across all nodes +- **FR-9.2.2:** Compensate for network propagation delays +- **FR-9.2.3:** Handle clock drift correction automatically +- **FR-9.2.4:** Detect and report synchronization failures +- **FR-9.2.5:** Support fallback to NTP when gPTP unavailable + +**Priority:** High (Milestone 3) +**Component:** timpani-n (Time Sync Manager) + +#### FR-9.3: Synchronized Task Activation +**Requirement:** The system SHALL coordinate task activation using synchronized time. +- **FR-9.3.1:** Use gPTP-synchronized time for schedule activation +- **FR-9.3.2:** Align task release times across nodes within 10 microseconds +- **FR-9.3.3:** Validate time synchronization before schedule execution +- **FR-9.3.4:** Reject schedules if synchronization quality insufficient + +**Priority:** High (Milestone 3) +**Component:** timpani-n (RT Scheduler, Time Sync Manager) + +#### FR-9.4: Time Synchronization Monitoring +**Requirement:** The system SHALL monitor time synchronization quality. +- **FR-9.4.1:** Measure clock offset between nodes +- **FR-9.4.2:** Track synchronization accuracy over time +- **FR-9.4.3:** Report synchronization degradation events +- **FR-9.4.4:** Provide time synchronization status via gRPC API + +**Priority:** Medium (Milestone 3) +**Component:** timpani-o (Monitoring), timpani-n (Time Sync Manager) + +--- + +## Non-Functional Requirements + +### NFR-1: Performance + +#### NFR-1.1: Latency +**Requirement:** The system SHALL meet strict latency requirements. +- **NFR-1.1.1:** Schedule computation latency < 100ms for 100-task workload +- **NFR-1.1.2:** gRPC call latency < 10ms (median), < 50ms (p99) +- **NFR-1.1.3:** Task activation jitter < 100μs +- **NFR-1.1.4:** Deadline miss detection latency < 1ms + +**Measurement:** Benchmark testing, production monitoring +**Priority:** High + +#### NFR-1.2: Throughput +**Requirement:** The system SHALL support high workload throughput. +- **NFR-1.2.1:** Handle ≥ 1000 tasks per hyperperiod +- **NFR-1.2.2:** Support ≥ 100 concurrent gRPC connections +- **NFR-1.2.3:** Process ≥ 10 schedule updates per second + +**Measurement:** Load testing +**Priority:** Medium + +#### NFR-1.3: Resource Efficiency +**Requirement:** The system SHALL minimize resource consumption. +- **NFR-1.3.1:** timpani-o memory usage < 100MB for 1000-task workload +- **NFR-1.3.2:** timpani-n memory usage < 50MB baseline +- **NFR-1.3.3:** CPU overhead < 5% during steady-state execution +- **NFR-1.3.4:** Binary size < 10MB (stripped, release build) + +**Measurement:** Resource profiling +**Priority:** Medium + +--- + +### NFR-2: Scalability + +#### NFR-2.1: Node Scalability +**Requirement:** The system SHALL scale to multiple execution nodes. +- **NFR-2.1.1:** Support ≥ 10 timpani-n nodes per timpani-o instance +- **NFR-2.1.2:** Support ≥ 32 CPU cores per node +- **NFR-2.1.3:** Maintain sub-100ms scheduling latency with 10 nodes +- **NFR-2.1.4:** Support dynamic node addition/removal + +**Measurement:** Scalability testing +**Priority:** High + +#### NFR-2.2: Task Scalability +**Requirement:** The system SHALL scale to large task sets. +- **NFR-2.2.1:** Support ≥ 1000 tasks per node +- **NFR-2.2.2:** Support ≥ 10,000 tasks across distributed system +- **NFR-2.2.3:** Maintain O(n log n) scheduling complexity +- **NFR-2.2.4:** Support task periods from 1ms to 10s + +**Measurement:** Benchmark testing +**Priority:** Medium + +--- + +### NFR-3: Reliability + +#### NFR-3.1: Availability +**Requirement:** The system SHALL provide high availability. +- **NFR-3.1.1:** Target 99.9% uptime for timpani-o (< 9 hours downtime/year) +- **NFR-3.1.2:** Recover from transient failures within 5 seconds +- **NFR-3.1.3:** Continue operation with up to 30% node failures +- **NFR-3.1.4:** Provide health check endpoints (gRPC health checking) + +**Measurement:** Availability monitoring +**Priority:** High + +#### NFR-3.2: Fault Tolerance +**Requirement:** The system SHALL tolerate common failure modes. +- **NFR-3.2.1:** Handle network partition without data loss +- **NFR-3.2.2:** Recover from crashed gRPC connections automatically +- **NFR-3.2.3:** Detect and report node failures within 5 seconds +- **NFR-3.2.4:** Maintain schedule consistency during failures + +**Measurement:** Chaos engineering, fault injection testing +**Priority:** High + +#### NFR-3.3: Data Integrity +**Requirement:** The system SHALL ensure data correctness. +- **NFR-3.3.1:** Validate all Protocol Buffer messages +- **NFR-3.3.2:** Verify schedule consistency across nodes +- **NFR-3.3.3:** Detect and reject corrupted configurations +- **NFR-3.3.4:** Use checksums for critical data structures + +**Measurement:** Data validation testing +**Priority:** High + +--- + +### NFR-4: Maintainability + +#### NFR-4.1: Code Quality +**Requirement:** The system SHALL maintain high code quality. +- **NFR-4.1.1:** Achieve ≥ 80% code coverage for unit tests +- **NFR-4.1.2:** Pass all Clippy lints (Rust) with zero warnings +- **NFR-4.1.3:** Follow Eclipse timpani coding standards +- **NFR-4.1.4:** Document all public APIs with rustdoc/doxygen + +**Measurement:** Static analysis, test coverage reports +**Priority:** Medium + +#### NFR-4.2: Logging and Debugging +**Requirement:** The system SHALL provide comprehensive logging. +- **NFR-4.2.1:** Use structured logging (tracing crate for Rust) +- **NFR-4.2.2:** Support configurable log levels (ERROR, WARN, INFO, DEBUG, TRACE) +- **NFR-4.2.3:** Include timestamps, component names, and context in logs +- **NFR-4.2.4:** Rotate log files to prevent disk exhaustion + +**Measurement:** Log quality review +**Priority:** Medium + +#### NFR-4.3: Modularity +**Requirement:** The system SHALL maintain modular architecture. +- **NFR-4.3.1:** Separate concerns into distinct layers (Interface, Core, Data, Storage) +- **NFR-4.3.2:** Use dependency injection for component coupling +- **NFR-4.3.3:** Minimize circular dependencies +- **NFR-4.3.4:** Support component replacement without system redesign + +**Measurement:** Architecture review, dependency analysis +**Priority:** Medium + +--- + +### NFR-5: Portability + +#### NFR-5.1: Platform Support +**Requirement:** The system SHALL support multiple platforms. +- **NFR-5.1.1:** Support x86_64, aarch64, and armhf architectures +- **NFR-5.1.2:** Support Ubuntu 20.04+, CentOS 8+, and Fedora 35+ +- **NFR-5.1.3:** Require Linux kernel ≥ 5.10 for eBPF support +- **NFR-5.1.4:** Support RT_PREEMPT and PREEMPT_RT kernel patches + +**Measurement:** Cross-platform testing +**Priority:** High + +#### NFR-5.2: Build System +**Requirement:** The system SHALL support reproducible builds. +- **NFR-5.2.1:** Use Cargo for Rust components (Cargo.toml, Cargo.lock) +- **NFR-5.2.2:** Use CMake for C components with version ≥ 3.16 +- **NFR-5.2.3:** Provide Docker-based build environments +- **NFR-5.2.4:** Support cross-compilation for target architectures + +**Measurement:** Build verification +**Priority:** Medium + +--- + +### NFR-6: Security + +#### NFR-6.1: Authentication +**Requirement:** The system SHALL support secure authentication (future). +- **NFR-6.1.1:** Support TLS for gRPC connections +- **NFR-6.1.2:** Validate client certificates +- **NFR-6.1.3:** Implement token-based authentication +- **NFR-6.1.4:** Rotate credentials periodically + +**Measurement:** Security audit +**Priority:** Low (Future Enhancement) + +#### NFR-6.2: Input Validation +**Requirement:** The system SHALL validate all external inputs. +- **NFR-6.2.1:** Sanitize all configuration file inputs +- **NFR-6.2.2:** Validate Protocol Buffer message contents +- **NFR-6.2.3:** Reject malformed gRPC requests +- **NFR-6.2.4:** Limit input sizes to prevent DoS + +**Measurement:** Fuzz testing +**Priority:** Medium + +--- + +### NFR-7: Compliance + +#### NFR-7.1: Licensing +**Requirement:** The system SHALL comply with open-source licensing. +- **NFR-7.1.1:** Use MIT license for all Eclipse timpani code +- **NFR-7.1.2:** Include SPDX headers in all source files +- **NFR-7.1.3:** Document third-party dependencies and licenses +- **NFR-7.1.4:** Use cargo-deny for license compliance checking + +**Measurement:** License audit +**Priority:** High + +#### NFR-7.2: Documentation +**Requirement:** The system SHALL provide comprehensive documentation. +- **NFR-7.2.1:** Maintain architecture documentation +- **NFR-7.2.2:** Provide LLD documents for all components +- **NFR-7.2.3:** Include API reference documentation +- **NFR-7.2.4:** Provide user guides and tutorials + +**Measurement:** Documentation review +**Priority:** Medium + +--- + +## Requirements Traceability Matrix + +### timpani-o Requirements Mapping + +| Requirement ID | Feature (Level 2) | Component (Level 3) | Verification Method | +|----------------|-------------------|---------------------|---------------------| +| FR-1.1 - FR-1.3 | Core Processing Layer | Global Scheduler, Scheduler Utils | Unit tests, benchmarks | +| FR-1.2 | Core Processing Layer | Hyperperiod Manager | Unit tests | +| FR-2.1 | Data Management Layer | Task Converter | Unit tests | +| FR-3.1 | Interface Layer | gRPC Server | Integration tests | +| FR-3.3 | Interface Layer | Fault Client | Integration tests | +| FR-4.1 | Core Processing Layer | NodeConfigManager | Unit tests | +| FR-4.2 | Interface Layer | gRPC Server (NodeService) | Integration tests | +| FR-6.2 | Data Management Layer | Configuration Loader | Unit tests | +| FR-7.1 | Core Processing Layer | Error Handling | Unit tests | +| NFR-1.1 - NFR-1.3 | All layers | All components | Performance tests | +| NFR-3.1 - NFR-3.3 | All layers | All components | Reliability tests | + +### timpani-n Requirements Mapping + +| Requirement ID | Feature (Level 2) | Component (Level 3) | Verification Method | +|----------------|-------------------|---------------------|---------------------| +| FR-2.1 - FR-2.3 | Execution Layer | Task Manager, RT Scheduler | Unit tests, integration tests | +| FR-3.1 | Communication Layer | gRPC Client | Integration tests | +| FR-3.2 | Communication Layer | libtrpc Client | Integration tests (C) | +| FR-4.2 | Communication Layer | Schedule Receiver | Integration tests | +| FR-5.1 | BPF Monitoring | Scheduler Monitoring, Signal Monitoring | System tests | +| FR-5.2 | Execution Layer | Signal Handler | System tests | +| FR-6.1 | Core Layer | Configuration Manager | Unit tests | +| FR-7.3 | Core Layer | Main Controller, Signal Handler | System tests | +| FR-8.1 - FR-8.2 | Execution Layer | Timer Manager | Unit tests, timing tests | +| FR-9.1 - FR-9.4 | Time Synchronization | Time Sync Manager, Clock Coordinator | System tests, timing tests | +| NFR-1.1 | All layers | All components | Latency benchmarks | +| NFR-5.1 | All layers | All components | Cross-platform tests | + +--- + +## Verification and Validation + +### Test Coverage Requirements + +- **Unit Tests:** ≥ 80% code coverage for all Rust modules +- **Integration Tests:** Cover all gRPC service interfaces +- **System Tests:** Validate end-to-end workflows +- **Performance Tests:** Verify NFR-1 (latency, throughput, resource usage) +- **Reliability Tests:** Verify NFR-3 (fault injection, chaos testing) +- **Portability Tests:** Verify NFR-5 (multi-platform builds) + +### Acceptance Criteria + +A release is considered acceptable when: +1. All priority=High functional requirements are implemented and verified +2. All priority=High non-functional requirements meet specified targets +3. Test coverage ≥ 80% for Rust code +4. Zero critical or high-severity bugs remain open +5. All documentation is up-to-date + +--- + +## Related Documentation + +- [timpani Feature Specification](../timpani_features.md) +- [timpani Architecture](../../architecture/timpani_architecture.md) +- [timpani-o LLD Documents](../../architecture/LLD/timpani-o/) +- [timpani-n LLD Documents](../../architecture/LLD/timpani-n/) + +--- + +## References + +1. Eclipse timpani Project Documentation +2. IEEE 830-1998: Software Requirements Specification +3. Real-Time Systems Design and Analysis (Klein et al.) +4. Liu & Layland: Scheduling Algorithms for Multiprogramming in a Hard-Real-Time Environment +5. gRPC Best Practices and Performance Guidelines diff --git a/doc/features/timpani_features.md b/doc/features/timpani_features.md new file mode 100644 index 0000000..ad2706e --- /dev/null +++ b/doc/features/timpani_features.md @@ -0,0 +1,229 @@ + + +# timpani Feature Specification + +**Document Information:** +- **Issuing Author:** LGSI-KarumuriHari(Eclipse timpani Team) +- **Configuration ID:** timpani-feature-spec +- **Document Status:** Draft +- **Last Updated:** 2026-05-14 + +--- + +## Revision History + +| Version | Date | Comment | Author | Approver | +|---------|------|---------|--------|----------| +| 0.0c | 2026-05-14 | Removed implementation status section | LGSI-KarumuriHari | - | +| 0.0b | 2026-05-13 | Added system block diagram and feature breakdown table | LGSI-KarumuriHari | - | +| 0.0a | 2026-02-24 | Initial feature specification | Eclipse timpani Team | - | + +--- + +## Table of Contents + +1. [System Overview](#system-overview) +2. [Feature Breakdown Table](#feature-breakdown-table) +3. [Feature Descriptions](#feature-descriptions) + +--- + +## System Overview + +Eclipse timpani is a distributed real-time task orchestration framework consisting of three main components: + +- **timpani-o (Orchestrator):** Global scheduler that manages workloads across multiple nodes +- **timpani-n (Node Executor):** Local executor that runs time-triggered tasks with real-time guarantees +- **sample-apps:** Sample applications and workload generators for testing and demonstration + +**Note:** For detailed system block diagrams and component architecture, please refer to the [High-Level Design (HLD) documents](../architecture/HLD/). + +--- + +## Feature Breakdown Table + +The following table shows the 3-level feature breakdown for Eclipse timpani system components. + +### Table 1: timpani System Features + +| Level 1 | Level 2 | Level 3 | Descriptions | +|---------|---------|---------|--------------| +| **timpani-o**
(Global Orchestrator) | **Interface Layer** | D-Bus Server (replaced) | Legacy D-Bus interface replaced by gRPC for node communication | +| | | gRPC Server | Modern gRPC service endpoint on port 50054 for Pullpiri and node communication | +| | | Fault Client | gRPC client for reporting deadline misses and fault events to Pullpiri orchestrator | +| | **Core Processing Layer** | SchedInfoService impl | Implementation of gRPC SchedInfo service for receiving and processing workload schedules | +| | | Hyperperiod Manager | Calculates LCM of task periods for hyperperiod determination and schedule validation | +| | | Global Scheduler | Allocates tasks to nodes and CPUs using real-time scheduling algorithms (Rate Monotonic, EDF) | +| | | NodeConfigManager | Loads and manages node hardware specifications from YAML configuration files | +| | **Data Management Layer** | Task Converter | Converts between Protocol Buffer task representations and internal scheduling data structures | +| | | SchedInfo Map | Manages mapping and storage of scheduling information for active workload sets | +| | | Scheduler Utils | Provides feasibility checks, Liu & Layland bounds, and CPU utilization calculations | +| | **Storage Layer** | Schedule State | Maintains current scheduling state and task allocations across nodes | +| | | HyperPeriod Info | Stores calculated hyperperiod information for periodic task sets | +| | | Node Config Files | YAML configuration files containing node hardware specifications and capabilities | +| **timpani-n**
(Node Executor) | **BPF Monitoring** | Scheduler Monitoring | eBPF program (schedstat.bpf.c) tracks scheduler events via tracepoints | +| | | Signal Monitoring | eBPF program (sigwait.bpf.c) monitors signal delivery and deadlines | +| | | BPF Ring Buffer | Kernel-to-userspace data transfer for monitoring statistics | +| | **Core Layer** | Main Controller | Program entry point, coordinates initialization and main execution loop | +| | | Configuration Manager | CLI parsing with Clap, configuration validation, defaults management | +| | | Context Structure | Global runtime state management (internal.h) | +| | **Execution Layer** | Task Manager | Task list management, activation scheduling, state tracking | +| | | RT Scheduler | CPU affinity assignment, RT priority configuration, sched_setattr() syscalls | +| | | Timer Manager | POSIX timer management, periodic activation timing | +| | | Signal Handler | SIGALRM handling, task signal delivery, shutdown signal processing | +| | **Communication Layer** | libtrpc Client | Legacy D-Bus communication client for timpani-o integration | +| | | gRPC Client (Rust) | Modern gRPC client implementation for schedule retrieval and sync | +| | | Schedule Receiver | Receives workload schedules from timpani-o orchestrator | +| | **System Interface** | Linux Scheduler | Integration with SCHED_DEADLINE real-time scheduling policy | +| | | CPU Affinity Control | CPU core assignment and affinity management for tasks | +| | | POSIX Timers | Timer_create, timer_settime for periodic task activation | +| **sample-apps**
(Workload Generator) | **Workload Library** | libttsched | Time-triggered scheduling library for sample applications | +| | | Task Primitives | Task initialization, execution, and termination functions | +| | **Sample Applications** | Periodic Tasks | Configurable periodic workload generators with CPU burn loops | +| | | Aperiodic Tasks | Event-driven workload generators for mixed-criticality testing | +| | | Multi-threaded Apps | Parallel execution workloads for multi-core testing | +| | **Testing Tools** | WCET Analyzer | Worst-Case Execution Time measurement and analysis tools | +| | | Workload Profiler | CPU utilization and response time profiling utilities | +| | | Deadline Monitor | Deadline miss detection and reporting for validation | +| | **Build System** | CMake Configuration | Cross-compilation support for x86_64, aarch64, armhf | +| | | Docker Support | Containerized build environments (Ubuntu, CentOS) | +| | | Integration Scripts | Automated build and test execution scripts | + +--- + +## Feature Descriptions + +### timpani-o (Global Orchestrator) + +#### Interface Layer +The interface layer provides external communication endpoints for the global orchestrator. The legacy D-Bus protocol has been replaced by modern gRPC for improved performance and type safety. + +**Key Features:** +- **D-Bus Server (replaced)**: Legacy interface that has been replaced by gRPC in the Rust implementation +- **gRPC Server**: Modern high-performance RPC server on port 50054 using Tonic framework +- **Fault Client**: Reports deadline misses and fault events to Pullpiri orchestrator + +#### Core Processing Layer +The core processing layer implements the main scheduling logic and workload management functionality. + +**Key Features:** +- **SchedInfoService impl**: Implements gRPC service for receiving workload schedules from Pullpiri +- **Hyperperiod Manager**: LCM calculation for periodic task sets and schedule validation +- **Global Scheduler**: Rate Monotonic (RM) and Earliest Deadline First (EDF) task allocation algorithms +- **NodeConfigManager**: YAML-based node specification loading and hardware capability management + +#### Data Management Layer +Handles data transformation, mapping, and utility functions for scheduling operations. + +**Key Features:** +- **Task Converter**: Protocol Buffer to internal data structure conversion and validation +- **SchedInfo Map**: Efficient mapping and lookup of scheduling information for active workloads +- **Scheduler Utils**: Liu & Layland schedulability bounds, feasibility analysis, and utilization calculations + +#### Storage Layer +Manages persistent and runtime state storage for scheduling information. + +**Key Features:** +- **Schedule State**: Current task allocations, node assignments, and execution state +- **HyperPeriod Info**: Calculated LCM values and hyperperiod metadata for task sets +- **Node Config Files**: YAML configuration files with node hardware specifications (CPU, memory, architecture) + +### timpani-n (Node Executor) + +#### BPF Monitoring +Provides kernel-level monitoring of scheduler events and signal delivery using eBPF technology. + +**Key Features:** +- **Scheduler Monitoring**: Tracks scheduling latency and context switches +- **Signal Monitoring**: Monitors signal delivery timing for deadline detection +- **BPF Ring Buffer**: High-performance kernel-to-userspace data transfer + +#### Core Layer +Central coordination and configuration management for the node executor. + +**Key Features:** +- **Main Controller**: Initialization, event loop, shutdown coordination +- **Configuration Manager**: Command-line parsing, validation, defaults +- **Context Structure**: Global state, task lists, runtime information + +#### Execution Layer +Manages task lifecycle, real-time scheduling, and timer-based activation. + +**Key Features:** +- **Task Manager**: Task creation, activation, completion tracking +- **RT Scheduler**: SCHED_DEADLINE policy, CPU affinity, priority assignment +- **Timer Manager**: POSIX timer management for periodic activation +- **Signal Handler**: SIGALRM processing, graceful shutdown + +#### Communication Layer +Handles communication with timpani-o orchestrator. + +**Key Features:** +- **libtrpc Client** (Legacy): D-Bus-based RPC client +- **gRPC Client** (Rust): Modern gRPC implementation +- **Schedule Receiver**: Workload schedule retrieval and parsing + +#### System Interface +Low-level integration with Linux kernel scheduling and timing facilities. + +**Key Features:** +- **Linux Scheduler**: SCHED_DEADLINE integration for real-time guarantees +- **CPU Affinity**: Core assignment for task isolation +- **POSIX Timers**: Timer_create/timer_settime for periodic activation + +### sample-apps (Workload Generator) + +#### Workload Library +Provides reusable components for creating test workloads. + +**Key Features:** +- **libttsched**: Time-triggered scheduling primitives +- **Task API**: Initialization, execution, cleanup interfaces +- **Configuration**: Period, deadline, WCET specification + +#### Sample Applications +Pre-built workload generators for testing and demonstration. + +**Key Features:** +- **Periodic Tasks**: Fixed-period CPU-bound workloads +- **Aperiodic Tasks**: Event-driven sporadic workloads +- **Multi-threaded**: Parallel execution patterns + +#### Testing Tools +Analysis and validation utilities for real-time performance. + +**Key Features:** +- **WCET Analyzer**: Execution time measurement and statistics +- **Workload Profiler**: CPU usage and timing analysis +- **Deadline Monitor**: Deadline miss detection and logging + +#### Build System +Cross-platform build and deployment infrastructure. + +**Key Features:** +- **CMake**: Multi-architecture build configuration +- **Docker**: Reproducible build environments +- **CI/CD Integration**: Automated testing and validation + +--- + +## Related Documentation + +- [timpani Architecture](../architecture/timpani_architecture.md) +- [timpani-o LLD Documents](../architecture/LLD/timpani-o/) +- [timpani-n LLD Documents](../architecture/LLD/timpani-n/) +- [timpani Requirements](requirements/timpani_requirements.md) +- [API Documentation](../docs/api.md) + +--- + +## References + +1. Eclipse timpani Project Documentation +2. Real-Time Systems Design Patterns +3. Liu & Layland Schedulability Analysis +4. eBPF Programming Guide +5. gRPC Protocol Documentation