From c0fe3e08e38c2ec2f774e2623bf6613f220eab93 Mon Sep 17 00:00:00 2001 From: Armin Bartsch Date: Mon, 2 Jun 2025 20:49:23 +0200 Subject: [PATCH] Adding FEO component architecture Change-Id: Icc7805259722e7313cbb239f70a58ae9ad6dd210 --- .../docs/architecture/_assets/act_chain.puml | 31 ++++ .../docs/architecture/_assets/dyn_arch.puml | 155 ++++++++++++++++++ .../docs/architecture/_assets/stat_arch.puml | 83 ++++++++++ .../architecture/component_architecture.rst | 144 ++++++++++++++++ .../feo/modules/feo/feo/docs/index.rst | 1 + 5 files changed, 414 insertions(+) create mode 100644 docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/act_chain.puml create mode 100644 docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/dyn_arch.puml create mode 100644 docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/stat_arch.puml create mode 100644 docs/features/frameworks/feo/modules/feo/feo/docs/architecture/component_architecture.rst diff --git a/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/act_chain.puml b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/act_chain.puml new file mode 100644 index 0000000000..84dc9c64f8 --- /dev/null +++ b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/act_chain.puml @@ -0,0 +1,31 @@ +/' + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* +'/ + +hide empty description + +state "UserActivity 1" as a1 +state "UserActivity 2" as a2 +state "UserActivity 3" as a3 +state "UserActivity 4" as a4 + +a1: Primary Process +a2: Secondary Process 1 +a3: Secondary Process 1 +a4: Secondary Process 2 + +a3 --> a1 +a3 --> a4 +a1 --> a2 +a4 --> a2 \ No newline at end of file diff --git a/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/dyn_arch.puml b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/dyn_arch.puml new file mode 100644 index 0000000000..9fa58b1e89 --- /dev/null +++ b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/dyn_arch.puml @@ -0,0 +1,155 @@ +/' + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* +'/ + +box "Primary Process" #E0E0E0 +participant "Primary Agent" as prim +participant "Scheduler" as scheduler +participant "UserActivity 1" as activity_1 +end box + +box "Secondary Process 1" #F0F0F0 +participant "Secondary Agent 1" as sec_1 +participant "UserActivity 2" as activity_2 +participant "UserActivity 3" as activity_3 +end box + +box "Secondary Process 2" #F0F0F0 +participant "Secondary Agent 2" as sec_2 +participant "UserActivity 4" as activity_4 +end box + +== Process Startup == + +prim -> prim: create \nworker threads +sec_1 -> sec_1: create \nworker threads +sec_2 -> sec_2: create \nworker threads + +sec_1 -> prim: connect +sec_2 -> prim: connect + + +prim -> scheduler: sync_remotes() +activate scheduler + +scheduler -> sec_1: sync +scheduler -> sec_2: sync +sec_1 -> sec_1: sync +sec_2 -> sec_2: sync +sec_1 --> scheduler: ready +sec_2 --> scheduler: ready + +scheduler --> prim: ok +deactivate scheduler + + +== Activity Init == + +note over scheduler, activity_4 +Call each activity's init() method exactly once in an arbitrary order. +end note + +prim -> scheduler: run() +activate scheduler + +scheduler -> activity_1: init() +activity_1 -> activity_1: init +activity_1 --> scheduler: ready + +scheduler -> sec_1: init(a2) +sec_1 -> activity_2: init() +activity_2 -> activity_2: init +activity_2 --> sec_1: ready +sec_1 --> scheduler: ready(a2) + +scheduler -> sec_1: init(a3) +sec_1 -> activity_3: init() +activity_3 -> activity_3: init +activity_3 --> sec_1: ready +sec_1 --> scheduler: ready(a3) + +scheduler -> sec_2: init(a4) +sec_2 -> activity_4: init() +activity_4 -> activity_4: init +activity_4 --> sec_2: ready +sec_2 --> scheduler: ready(a4) + +== Main Loop == + +loop break on termination signal to Primary Process + +note over scheduler, activity_4 +Call each activity's step() method in the order defined by the activity graph. +end note + +scheduler -> sec_1: step(a3) +note left: Step a3 first +sec_1 -> activity_3: step() +activity_3 --> sec_1: ready +sec_1 --> scheduler: ready(a3) + +scheduler -> sec_2: step(a4) +note left: Step a1 and a4\nin parallel, but\nafter end of a3 +sec_2 -> activity_4: step() +scheduler -> activity_1: step() +activity_1 --> scheduler: ready +activity_4 --> sec_2: ready +sec_2 --> scheduler: ready(a4) + +scheduler -> sec_1: step(a2) +note left: Step a2 after\nend of a1 and a4 +sec_1 -> activity_2: step() +activity_2 --> sec_1: ready +sec_1 --> scheduler: ready(a2) + + +hnote over scheduler +sleep until end +of cycle time +end note + +end loop + +== Activity Shutdown == + +note over scheduler, activity_4 +Call each activity's shutdown() method exactly once in an arbitrary order. +end note + +scheduler -> activity_1: shutdown() +activity_1 -> activity_1: shutdown +activity_1 --> scheduler: ready + +scheduler -> sec_1: shutdown(a2) +sec_1 -> activity_2: shutdown() +activity_2 -> activity_2: shutdown +activity_2 --> sec_1: ready +sec_1 --> scheduler: ready(a2) + +scheduler -> sec_1: shutdown(a3) +sec_1 -> activity_3: shutdown() +activity_3 -> activity_3: shutdown +activity_3 --> sec_1: ready +sec_1 --> scheduler: ready(a3) + +scheduler -> sec_2: shutdown(a4) +sec_2 -> activity_4: shutdown() +activity_4 -> activity_4: shutdown +activity_4 --> sec_2: ready +sec_2 --> scheduler: ready(a4) + +scheduler --> prim: ok + +deactivate scheduler + diff --git a/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/stat_arch.puml b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/stat_arch.puml new file mode 100644 index 0000000000..9cd295eba0 --- /dev/null +++ b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/_assets/stat_arch.puml @@ -0,0 +1,83 @@ +/' + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* +'/ +allowmixing + +package FEO <> as feat_feo { + + struct "feo::agent::Primary" as feo_primary { + + new(config: PrimaryConfig) -> Self + + run(&mut self) -> Result + } + + struct "feo::agent::Secondary" as feo_secondary { + + new(config: SecondaryConfig) -> Self + + fn run(self) + } + + struct "feo::agent::PrimaryConfig" as feo_primary_config { + + cycle_time : Duration + + activity_dependencies : HashMap> + + recorder_ids : Vec + {field} + worker_assignments : Vec<(WorkerId, Vec)> + + timeout : Duration + + endpoint : NodeAddress, + } + + struct "feo::agent::SecondaryConfig" as feo_secondary_config { + + id: AgentId + {field} + worker_assignments: Vec<(WorkerId, Vec)> + + timeout: Duration, + + endpoint: NodeAddress, + } + + struct "feo::scheduler::Scheduler" as feo_scheduler { + + new(...) -> Self + + run() + + sync_remotes() -> Result + } + + interface "feo::activity::Activity" as activity { + + init() + + step() + + shutdown() + } + + feo_primary --> activity: use + feo_primary --> feo_scheduler: use + + feo_secondary --> activity: use + +} + +package "User Application" <> as user_application { + + component "Primary Process" as PP + component "Secondary Process" as SP + + struct "UserActivity_1" as user_activity_1 + struct "UserActivity_2" as user_activity_2 + + PP --> user_activity_1 : use + SP --> user_activity_2 : use + + user_activity_1 ..|> activity : impl + user_activity_2 ..|> activity : impl +} + +PP --> feo_primary : use +PP --> feo_primary_config : use +SP --> feo_secondary : use +SP --> feo_secondary_config : use + diff --git a/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/component_architecture.rst b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/component_architecture.rst new file mode 100644 index 0000000000..3f0bc952c4 --- /dev/null +++ b/docs/features/frameworks/feo/modules/feo/feo/docs/architecture/component_architecture.rst @@ -0,0 +1,144 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Component Architecture: feo +=========================== + +Overview +-------- +The current implementation of the feature "FEO" (Fixed Execution Order Framework) consists of a main +component (called "FEO" component) and a set of auxiliary components that will be either replaced by or +turned into wrappers to components from other S-CORE features. In the latter case, these wrappers will +possibly become sub-components of the main component. + +This document describes the architecture of the main component "FEO". + +Description +----------- + +Sub-Components +************** + +The main component "FEO" consists of the following sub-components: + +* feo: Implements activities, threads, agents, and scheduling +* feo-cpp-build: C++ and Rust Code simplifying the integration of C++ components +* feo-cpp-macros: Rust proc-macros simplifying the integration of C++ components. + +Rust requires proc-macros to reside in their own crate, therefore the latter two +sub-components cannot easily be combined into a single one. + + +Rationale Behind Architecture Decomposition +******************************************* + +The main component "FEO" has been split into three sub-components mainly according to usability +considerations and Rust compiler constraints. (Rust proc-macros must reside in their own crate.) + + +Static Architecture +------------------- + +.. comp_arc_sta:: Static Architecture + :id: comp_arc_sta__feo__main + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__feo__application, comp_req__feo__scheduler, comp_req__feo__task_chain, comp_req__feo__agent, comp_req__feo__comp_cfg, comp_req__feo__act_map_cfg + :includes: real_arc_int__feo__primary, real_arc_int__feo__primary_config, real_arc_int__feo__secondary, real_arc_int__feo__secondary_config, real_arc_int__feo__activity + + .. uml:: _assets/stat_arch.puml + :scale: 50 + :align: center + + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: Dynamic Architecture + :id: comp_arc_dyn__feo__main + :security: YES + :safety: ASIL_B + :fulfils: comp_req__feo__application, comp_req__feo__application_lifecycle, comp_req__feo__scheduler, comp_req__feo__task_chain, comp_req__feo__agent, comp_req__feo__activity_init, comp_req__feo__activitiy_step, comp_req__feo__activity_shutdown + :status: valid + + The actual dynamic call sequence during the execution of a FEO application depends on the distribution + of activities to processes as well as on the activity dependency graph defining the task chain. + As an example, we consider the simple task chain and process distribution depicted in the following diagram + + .. uml:: _assets/act_chain.puml + + For this task chain, a possible call sequence is shown below. + + .. uml:: _assets/dyn_arch.puml + :scale: 50 + :align: center + + +Interfaces +------------------ + +.. real_arc_int:: feo::agent::PrimaryConfig + :id: real_arc_int__feo__primary_config + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__feo__application, comp_req__feo__task_chain, comp_req__feo__comp_cfg, comp_req__feo__act_map_cfg + :language: rust + + See static architecture. + + +.. real_arc_int:: feo::agent::Primary + :id: real_arc_int__feo__primary + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__feo__application, comp_req__feo__task_chain, comp_req__feo__comp_cfg, comp_req__feo__act_map_cfg + :language: rust + + See static architecture. + + +.. real_arc_int:: feo::agent::SecondaryConfig + :id: real_arc_int__feo__secondary_config + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__feo__application, comp_req__feo__task_chain, comp_req__feo__comp_cfg, comp_req__feo__act_map_cfg + :language: rust + + See static architecture. + + +.. real_arc_int:: feo::agent::Secondary + :id: real_arc_int__feo__secondary + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__feo__application, comp_req__feo__task_chain, comp_req__feo__comp_cfg, comp_req__feo__act_map_cfg + :language: rust + + See static architecture. + + +.. real_arc_int:: feo::activity::Activity + :id: real_arc_int__feo__activity + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__feo__activity + :language: rust + + See static architecture. diff --git a/docs/features/frameworks/feo/modules/feo/feo/docs/index.rst b/docs/features/frameworks/feo/modules/feo/feo/docs/index.rst index 24c08a7459..408723fec9 100644 --- a/docs/features/frameworks/feo/modules/feo/feo/docs/index.rst +++ b/docs/features/frameworks/feo/modules/feo/feo/docs/index.rst @@ -21,4 +21,5 @@ Component Documentation: feo .. toctree:: :maxdepth: 1 + architecture/component_architecture requirements/component_requirements