From da26b41fd43f3ed18d246be43ecfc197686684d1 Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Fri, 11 Sep 2026 09:36:28 +0100 Subject: [PATCH 1/6] linking all fet reqs to arch --- .../_assets/launch_manager_parallel_dep.puml | 45 ++++ .../_assets/launch_manager_random_crash.puml | 40 +++ .../_assets/launch_manager_running_dep.puml | 49 ++++ .../_assets/launch_manager_terminate_dep.puml | 59 +++++ .../launch_manager_terminate_request.puml | 44 ++++ .../features/lifecycle/architecture/alive.rst | 64 +++++ .../lifecycle/architecture/control_client.rst | 80 ++++++ .../lifecycle/architecture/health_monitor.rst | 6 +- .../features/lifecycle/architecture/index.rst | 43 ++-- .../lifecycle/architecture/launch_manager.rst | 240 +++++------------- .../launch_manager_configuration.rst | 4 +- .../architecture/lifecycle_client.rst | 131 ++++++++++ score/launch_manager/BUILD | 2 +- .../architecture/component_architecture.rst | 8 +- score/launch_manager/docs/index.rst | 6 +- .../{subcomponents => interfaces}/index.rst | 2 +- 16 files changed, 614 insertions(+), 209 deletions(-) create mode 100644 docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml create mode 100644 docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml create mode 100644 docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml create mode 100644 docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml create mode 100644 docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml create mode 100644 docs/features/lifecycle/architecture/alive.rst create mode 100644 docs/features/lifecycle/architecture/control_client.rst create mode 100644 docs/features/lifecycle/architecture/lifecycle_client.rst rename score/launch_manager/docs/{subcomponents => interfaces}/index.rst (96%) diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml new file mode 100644 index 0000000000..54af9d793a --- /dev/null +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml @@ -0,0 +1,45 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +@startuml +title Launch Manager - Run Components in Parallel + +autonumber "[00]" + +participant "Launch Manager" as LM +participant "OS (kernel)" as kernel +participant "Reporting App 1" as app1 +participant "Reporting App 2" as app2 +activate LM + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +LM -> kernel: Start Reporting App 1 +LM -> kernel: Start Reporting App 2 +kernel -> app1 **: Start +kernel -> app2 **: Start + +activate app1 +activate app2 + +app1 -> app1: Internal User app initialization +app1 -> LM: signal ready state via Lifecycle API +app2 -> app2: Internal User app initialization +app2 -> LM: signal ready state via Lifecycle API + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +... +@enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml new file mode 100644 index 0000000000..6aa408a9ca --- /dev/null +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml @@ -0,0 +1,40 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +@startuml +title Launch Manager - Termination Request + +autonumber "[00]" + +participant "Launch Manager" as LM +participant "OS (kernel)" as kernel +participant "Crashing Process" as app1 + + +activate LM +activate app1 + +== Switch Run Target == + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +app1 -> app1: Random crash +app1 -> kernel: terminate +destroy app1 +kernel -> LM: process termianted + +LM -> LM: analyze current state +LM -> LM: transiotion to fallback run target + +@enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml new file mode 100644 index 0000000000..c99104625f --- /dev/null +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml @@ -0,0 +1,49 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +@startuml +title Launch Manager - Components Depends on Each Other + +autonumber "[00]" + +participant "Launch Manager" as LM +participant "OS (kernel)" as kernel +participant "Reporting App 1" as app1 +participant "Reporting App 2" as app2 +activate LM + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +LM -> kernel: Start Reporting App 1 +kernel -> app1 **: Start +activate app1 +LM -> LM: wait for Reporting App 1 ready condition +app1 -> app1: Internal User app initialization +app1 -> LM: signal ready state via Lifecycle API + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +LM -> kernel: Start Reporting App 2 +kernel -> app2 **: Start +activate app2 +LM -> LM: wait for Reporting App 2 ready condition +app2 -> app2: Internal User app initialization +app2 -> LM: signal ready state via Lifecycle API + +LM -> LM: analyze current state +LM -> LM: update current run target state to active + +... +@enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml new file mode 100644 index 0000000000..5564e4beac --- /dev/null +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml @@ -0,0 +1,59 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +@startuml +title Launch Manager - Components Depends on Termination + +autonumber "[00]" + +participant "Launch Manager" as LM +participant "OS (kernel)" as kernel +participant "Reporting App 1" as app1 +participant "Reporting App 2" as app2 +activate LM + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +LM -> kernel: Start Reporting App 1 +kernel -> app1 **: Start +activate app1 +LM -> LM: wait for Reporting App 1 ready condition +app1 -> app1: Internal User app initialization +app1 -> LM: signal ready state via Lifecycle API + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +... + +app1 -> kernel: Termination +destroy app1 +kernel -> LM: Reporting App 1 Terminated +deactivate app1 + +LM -> LM: analyze current state +LM -> LM: determine transition plan + +LM -> kernel: Start Reporting App 2 +kernel -> app2 **: Start +activate app2 +LM -> LM: wait for Reporting App 2 ready condition +app2 -> app2: Internal User app initialization +app2 -> LM: signal ready state via Lifecycle API + +LM -> LM: analyze current state +LM -> LM: update current run target state to active + +... +@enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml new file mode 100644 index 0000000000..f823dd038d --- /dev/null +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml @@ -0,0 +1,44 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +@startuml +title Launch Manager - Termination Request + +autonumber "[00]" + +participant "Launch Manager" as LM +participant "OS (kernel)" as kernel +participant "Non self-terminating (well behaving)" as app1 +participant "Non self-terminating (badly behaving)" as app2 + +activate LM +activate app1 +activate app2 + +== Switch Run Target == + +LM -> LM: analyze current state +LM -> LM: determine transition plan + + +LM -> app1: SIGTERM +app1 -> kernel: terminate +destroy app1 + +LM -> app2: SIGTERM +app2 -> app2: Ignore +LM -> app2: SIGKILL +app2 -> kernel: terminate +destroy app2 + +@enduml diff --git a/docs/features/lifecycle/architecture/alive.rst b/docs/features/lifecycle/architecture/alive.rst new file mode 100644 index 0000000000..04c588fd2d --- /dev/null +++ b/docs/features/lifecycle/architecture/alive.rst @@ -0,0 +1,64 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Alive +##### +The Alive Interface provides a basic watchdog functionality interface that +delivers essential monitoring capabilities for system health and responsiveness +tracking. +It implements core watchdog operations including heartbeat signals to ensure +reliable operation and automatic recovery from unresponsive states. + +**SCORE Application Liveliness Reporting** + +SCORE applications can periodically signal their liveliness to the +:term:`Launch Manager` through the Alive Interface. +This mechanism allows the :term:`Launch Manager` to: + +- Detect application failures or hangs +- Trigger recovery actions when liveliness is lost +- Maintain accurate process health status + +The liveliness mechanism includes: + +- Configurable heartbeat intervals per application +- Timeout detection and failure handling + +Interface +========= + +The alive interface is defined here: :need:`logic_arc_int__lifecycle__alive_if` + +Requirements +============ +- :need:`feat_req__lifecycle__liveliness_detection` + +Dynamic architecture +==================== + +.. feat_arc_dyn:: Alive Monitoring + :id: feat_arc_dyn__lifecycle__alive_monitor + :security: YES + :status: valid + :version: 1 + :safety: ASIL_B + :fulfils: feat_req__lifecycle__liveliness_detection[version==1] + :includes: + :belongs_to: feat__lifecycle[version==1] + + .. uml:: _assets/alive_monitoring_dynamic.puml + :scale: 50 + :align: center + + diff --git a/docs/features/lifecycle/architecture/control_client.rst b/docs/features/lifecycle/architecture/control_client.rst new file mode 100644 index 0000000000..2f4044c063 --- /dev/null +++ b/docs/features/lifecycle/architecture/control_client.rst @@ -0,0 +1,80 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Control Client +############## + +This interface provides control functionality for activating and managing run targets.It allows users to trigger execution of configured :term:`Run targets ` through a standardized activation mechanism. + +Interface +========= + +The control interface is defined here: :need:`logic_arc_int__lifecycle__controlif` +The :term:`Launch Manager` provides an interface, which allows an external State Manager application to request the :term:`Launch Manager` to start, stop or restart applications or groups of applications, +which allows the implementation of a state management applications to support dynamic state control. + +Requirements +============ + +- :need:`feat_req__lifecycle__control_commands` +- :need:`feat_req__lifecycle__request_run_target_start` +- :need:`feat_req__lifecycle__switch_run_targets` + + +Dynamic architecture +==================== + +The following use cases are supported by the `ControlInterface` provided by the :term:`Launch Manager`. + +**Activating a Run Target** + +When a request to activate a run target is received via the `ControlInterface`, the :term:`Launch Manager` shall perform the following operations: + +1. **Validation**: Evaluate if the conditions are correct for activating the requested run target: + - The run target exists in the configuration + - All dependencies for the run target are resolvable + - Required resources are available + +2. **Transition Logic**: Determine the transition from the current state to the target state: + - If a different run target is active, perform a switch operation (stop current, start requested) + - If the same run target is already active, verify its state and potentially restart failed components + +3. **Execution**: Execute the transition in the correct dependency order: + - Stop components that are not part of the new run target + - Start components that are required for the new run target + - Respect dependency relationships during both stop and start operations + +4. **Response**: Return status to the caller: + - Success if all components transitioned correctly + - Failure with detailed error information if any component failed to transition + +This unified approach allows external state managers to request any run target activation without needing to know the current system state, as the :term:`Launch Manager` handles the transition logic internally. + +.. feat_arc_dyn:: Control interface dynamic architecture activate run target + :id: feat_arc_dyn__lifecycle__control_activate + :status: valid + :version: 1 + :safety: ASIL_B + :security: YES + :fulfils: feat_req__lifecycle__control_commands[version==1], + feat_req__lifecycle__request_run_target_start[version==1], + feat_req__lifecycle__switch_run_targets[version==1], + :belongs_to: feat__lifecycle[version==1] + + .. uml:: _assets/control_interface_start_sequence.puml + :scale: 50 + :align: center + + + diff --git a/docs/features/lifecycle/architecture/health_monitor.rst b/docs/features/lifecycle/architecture/health_monitor.rst index d335dd7379..b61c41a069 100644 --- a/docs/features/lifecycle/architecture/health_monitor.rst +++ b/docs/features/lifecycle/architecture/health_monitor.rst @@ -99,7 +99,8 @@ Dynamic Architecture :status: valid :version: 1 :safety: ASIL_B - :fulfils: feat_req__lifecycle__liveliness_detection[version==1] + :fulfils: feat_req__lifecycle__liveliness_detection[version==1], + feat_req__lifecycle__hm_checkpoint[version==1] :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/application_health_monitoring_dynamic.puml @@ -141,7 +142,10 @@ The most important interactions are the following: Requirements ------------ +- :need:`feat_req__lifecycle__liveliness_detection` - :need:`feat_req__lifecycle__hm_deadline` +- :need:`feat_req__lifecycle__hm_checkpoint` +- :need:`feat_req__lifecycle__hm_logical` Logical Monitor API =================== diff --git a/docs/features/lifecycle/architecture/index.rst b/docs/features/lifecycle/architecture/index.rst index 5e4b820cd3..4cf0b5b5ea 100644 --- a/docs/features/lifecycle/architecture/index.rst +++ b/docs/features/lifecycle/architecture/index.rst @@ -64,8 +64,13 @@ Static Architecture :safety: ASIL_B :status: valid :version: 1 - :fulfils: feat_req__lifecycle__launch_support[version==1] - :includes: logic_arc_int__lifecycle__lifecycle_if[version==1], logic_arc_int__lifecycle__alive_if[version==1], logic_arc_int__lifecycle__controlif[version==1], logic_arc_int__lifecycle__deadline_monitor_if[version==1], logic_arc_int__lifecycle__logical_monitor_if[version==1] + :fulfils: feat_req__lifecycle__launch_support[version==1], + feat_req__lifecycle__logging_support[version==1] + :includes: logic_arc_int__lifecycle__lifecycle_if[version==1], + logic_arc_int__lifecycle__alive_if[version==1], + logic_arc_int__lifecycle__controlif[version==1], + logic_arc_int__lifecycle__deadline_monitor_if[version==1], + logic_arc_int__lifecycle__logical_monitor_if[version==1] :belongs_to: feat__lifecycle .. needarch:: @@ -77,22 +82,26 @@ Static Architecture Dynamic Architecture -------------------- -.. code-block:: rst +The dynamic architecture between the interfaces and the user application +are described in the following sub-pages: - .. feat_arc_dyn:: Dynamic View - :id: feat_arc_dyn__feature_name__dynamic_view - :security: YES - :safety: ASIL_B - :status: invalid - :fulfils: feat_req__feature_name__some_title - :belongs_to: feat__feature_name +.. toctree:: + :maxdepth: 1 - Put here a sequence diagram + ./launch_manager + ./control_client + ./lifecycle_client + ./alive + ./launch_manager_configuration + ./health_monitor + ./external_monitoring Logical Interfaces ------------------ -The logical interfaces of the feature are defined in the `interfaces` section of the feature documentation in the project repository: :need:`doc__lifecycle_architecture` +The logical interfaces of the feature are defined in the `interfaces` section +of the feature documentation in the project repository: +:need:`doc__lifecycle_architecture` Module Viewpoint ---------------- @@ -117,14 +126,4 @@ Module Viewpoint NativeApplication --> posix_signals : implements comp__lifecycle_launch_manager --> posix_signals : use -Components Details ------------------- - -.. toctree:: - :maxdepth: 1 - :glob: - ./launch_manager - ./launch_manager_configuration - ./health_monitor - ./external_monitoring diff --git a/docs/features/lifecycle/architecture/launch_manager.rst b/docs/features/lifecycle/architecture/launch_manager.rst index 7f79310ce9..3868afb038 100644 --- a/docs/features/lifecycle/architecture/launch_manager.rst +++ b/docs/features/lifecycle/architecture/launch_manager.rst @@ -23,6 +23,21 @@ S-CORE and knows about the state of all processes in the system. It's foreseen ECU projects will need a custom state management to fulfill ECU-project specific requirements. The S-CORE stack will offer a framework to control application lifecycle, but will not specify the State Manager. + +Requirements +============ + +- :need:`feat_req__lifecycle__launch_support` done +- :need:`feat_req__lifecycle__process_ordering` done +- :need:`feat_req__lifecycle__parallel_launch_support` +- :need:`feat_req__lifecycle__conditional_startup` done +- :need:`feat_req__lifecycle__start_named_run_target` done +- :need:`feat_req__lifecycle__process_termination` done +- :need:`feat_req__lifecycle__terminationn_dependency` done +- :need:`feat_req__lifecycle__monitor_abnormal_term` +- :need:`feat_req__lifecycle__recovery_action_support` +- :need:`feat_req__lifecycle__recov_run_target_switch` + Overview ======== @@ -55,215 +70,84 @@ When a component is started the :term:`Launch Manager` will start the correspond :term:`Ready Conditions ` are essential mechanisms that determine when a component has successfully completed its startup phase and is ready to fulfill its intended role in the system. These conditions provide flexibility in defining what constitutes a "ready" state for different types of components. For SCORE applications, components can actively report their readiness through the Lifecycle Interface by signaling specific states or custom conditions. For native applications, the :term:`Launch Manager` relies on external indicators such as process existence, file creation, network socket availability, or successful process termination. This dual approach ensures that both modern SCORE-aware applications and legacy native applications can participate in the dependency management system, allowing the :term:`Launch Manager` to orchestrate complex startup sequences where components depend on each other's readiness rather than just their launch order. -Control Interface -================= - -This interface provides control functionality for activating and managing run targets.It allows users to trigger execution of configured :term:`Run targets ` through a standardized activation mechanism. - -Interface ---------- - -The control interface is defined here: :need:`logic_arc_int__lifecycle__controlif` -The :term:`Launch Manager` provides an interface, which allows an external State Manager application to request the :term:`Launch Manager` to start, stop or restart applications or groups of applications, -which allows the implementation of a state management applications to support dynamic state control. - - - -Dynamic architecture --------------------- - -The following use cases are supported by the `ControlInterface` provided by the :term:`Launch Manager`. - -**Activating a Run Target** - -When a request to activate a run target is received via the `ControlInterface`, the :term:`Launch Manager` shall perform the following operations: - -1. **Validation**: Evaluate if the conditions are correct for activating the requested run target: - - The run target exists in the configuration - - All dependencies for the run target are resolvable - - Required resources are available - -2. **Transition Logic**: Determine the transition from the current state to the target state: - - If a different run target is active, perform a switch operation (stop current, start requested) - - If the same run target is already active, verify its state and potentially restart failed components - -3. **Execution**: Execute the transition in the correct dependency order: - - Stop components that are not part of the new run target - - Start components that are required for the new run target - - Respect dependency relationships during both stop and start operations - -4. **Response**: Return status to the caller: - - Success if all components transitioned correctly - - Failure with detailed error information if any component failed to transition - -This unified approach allows external state managers to request any run target activation without needing to know the current system state, as the :term:`Launch Manager` handles the transition logic internally. - - -.. feat_arc_dyn:: Control interface dynamic architecture activate run target - :id: feat_arc_dyn__lifecycle__control_activate +.. feat_arc_dyn:: Application health monitoring + :id: feat_arc_dyn__lifecycle__lcm_start + :security: YES :status: valid :version: 1 :safety: ASIL_B - :security: YES - :fulfils: feat_req__lifecycle__control_commands[version==1], feat_req__lifecycle__request_run_target_start[version==1], feat_req__lifecycle__switch_run_targets[version==1] :belongs_to: feat__lifecycle[version==1] + :fulfils: feat_req__lifecycle__launch_support[version==1], + feat_req__lifecycle__process_ordering[version==1], + feat_req__lifecycle__start_named_run_target[version==1], + feat_req__lifecycle__conditional_startup[version==1], - .. uml:: _assets/control_interface_start_sequence.puml + .. uml:: _assets/launch_manager_running_dep.puml :scale: 50 :align: center -Requirements ------------- - -- :need:`feat_req__lifecycle__control_commands` -- :need:`feat_req__lifecycle__request_run_target_start` -- :need:`feat_req__lifecycle__switch_run_targets` - - - -Lifecycle Interface -=================== - - -The :term:`Launch Manager` provides interfaces for communication with launched applications, supporting two distinct application types: - -1. **SCORE Applications**: Implement the full Lifecycle Interface for bidirectional communication with state reporting, liveliness indication, and conditional signaling -2. **Native Applications**: Controlled exclusively via POSIX signals (SIGTERM, SIGKILL, etc.) without direct API communication - -This dual approach enables the :term:`Launch Manager` to manage both legacy native applications and SCORE-aware applications within the same system. - -The Lifecycle Interface serves as the communication channel between applications and the :term:`Launch Manager`: - -**For SCORE Applications:** -- Application state reporting (started, running, stopped) -- Conditional signaling for application dependencies - -**For Native Applications:** -- Process lifecycle control via POSIX signals -- Basic process monitoring (PID-based status checking) -- Exit code evaluation for failure detection - -Interface ---------- - -The lifecycle interface is defined here: :need:`logic_arc_int__lifecycle__lifecycle_if` - -The following use cases are supported by the Lifecycle Interface, with different capabilities depending on the application type. - -**SCORE Application State Communication** - -SCORE applications implementing the Lifecycle Interface can communicate their internal state to the :term:`Launch Manager`. The state information includes: - -- **Started**: Application has successfully initialized and is ready to operate -- **Running**: Application is actively executing its main functionality -- **Stopped**: Application has terminated or is in the process of shutting down - -The :term:`Launch Manager` uses this state information for: - -- Dependency resolution for other applications -- Recovery action decisions -- Status reporting to external state managers via the Control Interface - - -**SCORE Application Conditional Signaling** - -SCORE applications can signal custom conditions to the :term:`Launch Manager` via the Alive Interface. This enables: - -- Complex dependency management beyond simple process startup -- Coordination between interdependent applications - -Custom conditions can be used by other applications as launch dependencies, allowing for sophisticated startup orchestration. - -**Native Application Control** - -Native applications that do not implement the Lifecycle Interface are controlled through POSIX signals: - -- **SIGTERM**: Graceful shutdown request -- **SIGKILL**: Forced termination (after timeout) -- **SIGUSR1/SIGUSR2**: Application-specific signals (if configured) - -The :term:`Launch Manager` monitors native applications through: - -- Process ID (PID) tracking -- Exit code evaluation -- Resource usage monitoring via OS facilities -- Timeout-based failure detection - -For native applications, the :term:`Launch Manager` provides: - -- Basic lifecycle control (start/stop) -- Simple dependency management based on process existence -- Configurable startup/shutdown timeouts -- Exit code-based success/failure determination - - -Dynamic Architecture --------------------- - -.. feat_arc_dyn:: Lifecyle Interface - :id: feat_arc_dyn__lifecycle__state_machine_if +.. feat_arc_dyn:: Application health monitoring + :id: feat_arc_dyn__lifecycle__lcm_term :security: YES :status: valid :version: 1 :safety: ASIL_B - :fulfils: feat_req__lifecycle__process_termination[version==1], feat_req__lifecycle__launch_support[version==1] :belongs_to: feat__lifecycle[version==1] + :fulfils: feat_req__lifecycle__launch_support[version==1], + feat_req__lifecycle__process_termination[version==1], + feat_req__lifecycle__process_ordering[version==1], - .. uml:: _assets/lifecycle_state_machine.puml + .. uml:: _assets/launch_manager_terminate_request.puml :scale: 50 :align: center -Requirements ------------- - -- :need:`feat_req__lifecycle__process_termination` -- :need:`feat_req__lifecycle__launch_support` - - - -Alive Interface -=============== -The Alive Interface provides a basic watchdog functionality interface that delivers essential monitoring capabilities for system health and responsiveness tracking. -It implements core watchdog operations including heartbeat signals to ensure reliable operation and automatic recovery from unresponsive states. - -**SCORE Application Liveliness Reporting** - -SCORE applications can periodically signal their liveliness to the :term:`Launch Manager` through the Alive Interface. This mechanism allows the :term:`Launch Manager` to: - -- Detect application failures or hangs -- Trigger recovery actions when liveliness is lost -- Maintain accurate process health status - -The liveliness mechanism includes: +.. feat_arc_dyn:: Application health monitoring + :id: feat_arc_dyn__lifecycle__lcm_term_order + :security: YES + :status: valid + :version: 1 + :safety: ASIL_B + :belongs_to: feat__lifecycle[version==1] + :fulfils: feat_req__lifecycle__launch_support[version==1], + feat_req__lifecycle__process_termination[version==1], + feat_req__lifecycle__process_ordering[version==1], + feat_req__lifecycle__terminationn_dependency[version==1] -- Configurable heartbeat intervals per application -- Timeout detection and failure handling + .. uml:: _assets/launch_manager_terminate_dep.puml + :scale: 50 + :align: center -Interface ---------- -The alive interface is defined here: :need:`logic_arc_int__lifecycle__alive_if` +.. feat_arc_dyn:: Application health monitoring + :id: feat_arc_dyn__lifecycle__lcm_parallel + :security: YES + :status: valid + :version: 1 + :safety: ASIL_B + :belongs_to: feat__lifecycle[version==1] + :fulfils: feat_req__lifecycle__launch_support[version==1], + feat_req__lifecycle__process_ordering[version==1], + feat_req__lifecycle__parallel_launch_support[version==1] + .. uml:: _assets/launch_manager_parallel_dep.puml + :scale: 50 + :align: center -Dynamic architecture --------------------- -.. feat_arc_dyn:: Alive Monitoring - :id: feat_arc_dyn__lifecycle__alive_monitor +.. feat_arc_dyn:: Application health monitoring + :id: feat_arc_dyn__lifecycle__crash :security: YES :status: valid :version: 1 :safety: ASIL_B - :fulfils: feat_req__lifecycle__liveliness_detection[version==1] - :includes: :belongs_to: feat__lifecycle[version==1] + :fulfils: feat_req__lifecycle__monitor_abnormal_term[version==1], + feat_req__lifecycle__recovery_action_support[version==1], + feat_req__lifecycle__recov_run_target_switch[version==1] - .. uml:: _assets/alive_monitoring_dynamic.puml + .. uml:: _assets/launch_manager_random_crash.puml :scale: 50 :align: center -Requirements ------------- -- :need:`feat_req__lifecycle__liveliness_detection` diff --git a/docs/features/lifecycle/architecture/launch_manager_configuration.rst b/docs/features/lifecycle/architecture/launch_manager_configuration.rst index c42fc7de28..85970421a1 100644 --- a/docs/features/lifecycle/architecture/launch_manager_configuration.rst +++ b/docs/features/lifecycle/architecture/launch_manager_configuration.rst @@ -65,7 +65,9 @@ Static Architecture :safety: ASIL_B :status: valid :version: 1 - :fulfils: feat_req__com__interfaces[version==1] + :fulfils: feat_req__lifecycle__component_group_config[version==1], + feat_req__lifecycle__config_file_support[version==1], + feat_req__lifecycle__run_target_support[version==1] .. uml:: _assets/config_params_static.puml :scale: 50 diff --git a/docs/features/lifecycle/architecture/lifecycle_client.rst b/docs/features/lifecycle/architecture/lifecycle_client.rst new file mode 100644 index 0000000000..7adaa3cd81 --- /dev/null +++ b/docs/features/lifecycle/architecture/lifecycle_client.rst @@ -0,0 +1,131 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Lifecycle Client +################ + +The :term:`Launch Manager` provides interfaces for communication with launched +applications, supporting two distinct application types: + +1. **SCORE Applications**: Implement the full Lifecycle Interface for + bidirectional communication with state reporting, liveliness indication, and + conditional signaling +2. **Native Applications**: Controlled exclusively via POSIX signals (SIGTERM, + SIGKILL, etc.) without direct API communication + +This dual approach enables the :term:`Launch Manager` to manage both legacy +native applications and SCORE-aware applications within the same system. + +The Lifecycle Interface serves as the communication channel between +applications and the :term:`Launch Manager`: + +**For SCORE Applications:** +- Application state reporting (started, running, stopped) +- Conditional signaling for application dependencies + +**For Native Applications:** +- Process lifecycle control via POSIX signals +- Basic process monitoring (PID-based status checking) +- Exit code evaluation for failure detection + +Requirements +============ + +Interface +========= + +The lifecycle interface is defined here: +:need:`logic_arc_int__lifecycle__lifecycle_if` + +The following use cases are supported by the Lifecycle Interface, with +different capabilities depending on the application type. + +**SCORE Application State Communication** + +SCORE applications implementing the Lifecycle Interface can communicate their +internal state to the :term:`Launch Manager`. The state information includes: + +- **Started**: Application has successfully initialized and is ready to operate +- **Running**: Application is actively executing its main functionality +- **Stopped**: Application has terminated or is in the process of shutting down + +The :term:`Launch Manager` uses this state information for: + +- Dependency resolution for other applications +- Recovery action decisions +- Status reporting to external state managers via the Control Interface + + +**SCORE Application Conditional Signaling** + +SCORE applications can signal custom conditions to the :term:`Launch Manager` +via the Alive Interface. This enables: + +- Complex dependency management beyond simple process startup +- Coordination between interdependent applications + +Custom conditions can be used by other applications as launch dependencies, +allowing for sophisticated startup orchestration. + +**Native Application Control** + +Native applications that do not implement the Lifecycle Interface are +controlled through POSIX signals: + +- **SIGTERM**: Graceful shutdown request +- **SIGKILL**: Forced termination (after timeout) +- **SIGUSR1/SIGUSR2**: Application-specific signals (if configured) + +The :term:`Launch Manager` monitors native applications through: + +- Process ID (PID) tracking +- Exit code evaluation +- Resource usage monitoring via OS facilities +- Timeout-based failure detection + +For native applications, the :term:`Launch Manager` provides: + +- Basic lifecycle control (start/stop) +- Simple dependency management based on process existence +- Configurable startup/shutdown timeouts +- Exit code-based success/failure determination + + +Dynamic Architecture +==================== + +.. feat_arc_dyn:: Component State Machine + :id: feat_arc_dyn__lifecycle__state_machine_if + :security: YES + :status: valid + :version: 1 + :safety: ASIL_B + :fulfils: feat_req__lifecycle__process_termination[version==1], + feat_req__lifecycle__launch_support[version==1], + feat_req__lifecycle__process_ordering[version==1], + feat_req__lifecycle__custom_cond_support[version==1], + feat_req__lifecycle__conditional_startup[version==1], + feat_req__lifecycle__prog_lang[version==1], + :belongs_to: feat__lifecycle[version==1] + + .. uml:: _assets/lifecycle_state_machine.puml + :scale: 50 + :align: center + +Requirements +============ + +- :need:`feat_req__lifecycle__process_termination` +- :need:`feat_req__lifecycle__launch_support` +- :need:`feat_req__lifecycle__prog_lang` diff --git a/score/launch_manager/BUILD b/score/launch_manager/BUILD index 55dd202efc..c83a20c4dd 100644 --- a/score/launch_manager/BUILD +++ b/score/launch_manager/BUILD @@ -139,7 +139,7 @@ docs_bundle( bundles = [ { "bundle": "//score/launch_manager/src/lifecycle_client:docs", - "mount_at": "subcomponents/lifecycle_client", + "mount_at": "interfaces/lifecycle_client", }, ], code_targets = [ diff --git a/score/launch_manager/docs/architecture/component_architecture.rst b/score/launch_manager/docs/architecture/component_architecture.rst index 8bce3cb5d5..bb1c4acb25 100644 --- a/score/launch_manager/docs/architecture/component_architecture.rst +++ b/score/launch_manager/docs/architecture/component_architecture.rst @@ -32,8 +32,12 @@ Overview :status: valid :version: 1 :safety: ASIL_B - :implements: logic_arc_int__lifecycle__controlif[version==1], logic_arc_int__lifecycle__alive_if[version==1] - :uses: logic_arc_int__log_cpp__logging[version==1], logic_arc_int__baselibs__json[version==1], logic_arc_int__os__unistd[version==1], logic_arc_int__lifecycle__lifecycle_if[version==1] + :implements: logic_arc_int__lifecycle__controlif[version==1], + logic_arc_int__lifecycle__alive_if[version==1], + logic_arc_int__lifecycle__lifecycle_if[version==1], + :uses: logic_arc_int__log_cpp__logging[version==1], + logic_arc_int__baselibs__json[version==1], + logic_arc_int__os__unistd[version==1], :security: NO :belongs_to: feat__lifecycle[version==1] diff --git a/score/launch_manager/docs/index.rst b/score/launch_manager/docs/index.rst index e1dc57ed47..35d5f4c2d9 100644 --- a/score/launch_manager/docs/index.rst +++ b/score/launch_manager/docs/index.rst @@ -34,9 +34,9 @@ Launch Manager safety_analysis/dfa.rst safety_analysis/aou_requirements.rst -Subcomponents -============= +Interfaces +========== .. toctree:: :titlesonly: - subcomponents/index + interfaces/index diff --git a/score/launch_manager/docs/subcomponents/index.rst b/score/launch_manager/docs/interfaces/index.rst similarity index 96% rename from score/launch_manager/docs/subcomponents/index.rst rename to score/launch_manager/docs/interfaces/index.rst index 7d3cd8326b..de58447f25 100644 --- a/score/launch_manager/docs/subcomponents/index.rst +++ b/score/launch_manager/docs/interfaces/index.rst @@ -12,7 +12,7 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Sub-Component documentation +Interfaces documentation --------------------------- .. toctree will be filled by docs_bundle via bazel From 06ad8e74092077cb339711e42db99c35fecbfbd7 Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Fri, 11 Sep 2026 11:31:23 +0100 Subject: [PATCH 2/6] All stuff linked --- .../_assets/launch_manager_parallel_dep.puml | 4 - .../_assets/launch_manager_random_crash.puml | 11 +- .../_assets/launch_manager_terminate_dep.puml | 7 - .../features/lifecycle/architecture/alive.rst | 4 +- .../lifecycle/architecture/control_client.rst | 24 +- .../features/lifecycle/architecture/index.rst | 14 +- .../lifecycle/architecture/launch_manager.rst | 250 +++++++++++++++--- .../architecture/component_architecture.rst | 13 + 8 files changed, 263 insertions(+), 64 deletions(-) diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml index 54af9d793a..c9a90a4e28 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml @@ -37,9 +37,5 @@ app1 -> app1: Internal User app initialization app1 -> LM: signal ready state via Lifecycle API app2 -> app2: Internal User app initialization app2 -> LM: signal ready state via Lifecycle API - -LM -> LM: analyze current state -LM -> LM: determine transition plan - ... @enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml index 6aa408a9ca..1995458e25 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml @@ -24,17 +24,18 @@ participant "Crashing Process" as app1 activate LM activate app1 -== Switch Run Target == +... -LM -> LM: analyze current state -LM -> LM: determine transition plan app1 -> app1: Random crash app1 -> kernel: terminate destroy app1 -kernel -> LM: process termianted +kernel -> LM: process terminated LM -> LM: analyze current state -LM -> LM: transiotion to fallback run target +LM -> LM: determine transition plan.\nA recovery action has to be ran,\nthe recovery action is to switch to a different Run Target. +LM -> LM: Switch Run Target. + +... @enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml index 5564e4beac..fe5cbc6c07 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml @@ -32,9 +32,6 @@ LM -> LM: wait for Reporting App 1 ready condition app1 -> app1: Internal User app initialization app1 -> LM: signal ready state via Lifecycle API -LM -> LM: analyze current state -LM -> LM: determine transition plan - ... app1 -> kernel: Termination @@ -51,9 +48,5 @@ activate app2 LM -> LM: wait for Reporting App 2 ready condition app2 -> app2: Internal User app initialization app2 -> LM: signal ready state via Lifecycle API - -LM -> LM: analyze current state -LM -> LM: update current run target state to active - ... @enduml diff --git a/docs/features/lifecycle/architecture/alive.rst b/docs/features/lifecycle/architecture/alive.rst index 04c588fd2d..52b38eb37f 100644 --- a/docs/features/lifecycle/architecture/alive.rst +++ b/docs/features/lifecycle/architecture/alive.rst @@ -14,6 +14,7 @@ Alive ##### + The Alive Interface provides a basic watchdog functionality interface that delivers essential monitoring capabilities for system health and responsiveness tracking. @@ -35,9 +36,6 @@ The liveliness mechanism includes: - Configurable heartbeat intervals per application - Timeout detection and failure handling -Interface -========= - The alive interface is defined here: :need:`logic_arc_int__lifecycle__alive_if` Requirements diff --git a/docs/features/lifecycle/architecture/control_client.rst b/docs/features/lifecycle/architecture/control_client.rst index 2f4044c063..64c9dbcc10 100644 --- a/docs/features/lifecycle/architecture/control_client.rst +++ b/docs/features/lifecycle/architecture/control_client.rst @@ -15,14 +15,20 @@ Control Client ############## -This interface provides control functionality for activating and managing run targets.It allows users to trigger execution of configured :term:`Run targets ` through a standardized activation mechanism. +This interface provides control functionality for activating and managing run +targets. +It allows users to trigger execution of configured :term:`Run targets ` through a standardized activation mechanism. Interface ========= -The control interface is defined here: :need:`logic_arc_int__lifecycle__controlif` -The :term:`Launch Manager` provides an interface, which allows an external State Manager application to request the :term:`Launch Manager` to start, stop or restart applications or groups of applications, -which allows the implementation of a state management applications to support dynamic state control. +The control interface is defined here: +:need:`logic_arc_int__lifecycle__controlif` The :term:`Launch Manager` provides +an interface, which allows an external State Manager application to request the +:term:`Launch Manager` to start, stop or restart applications or groups of +applications, which allows the implementation of a state management +applications to support dynamic state control. Requirements ============ @@ -35,11 +41,13 @@ Requirements Dynamic architecture ==================== -The following use cases are supported by the `ControlInterface` provided by the :term:`Launch Manager`. +The following use cases are supported by the `ControlInterface` provided by the +:term:`Launch Manager`. **Activating a Run Target** -When a request to activate a run target is received via the `ControlInterface`, the :term:`Launch Manager` shall perform the following operations: +When a request to activate a run target is received via the `ControlInterface`, +the :term:`Launch Manager` shall perform the following operations: 1. **Validation**: Evaluate if the conditions are correct for activating the requested run target: - The run target exists in the configuration @@ -59,7 +67,9 @@ When a request to activate a run target is received via the `ControlInterface`, - Success if all components transitioned correctly - Failure with detailed error information if any component failed to transition -This unified approach allows external state managers to request any run target activation without needing to know the current system state, as the :term:`Launch Manager` handles the transition logic internally. +This unified approach allows external state managers to request any run target +activation without needing to know the current system state, as the +:term:`Launch Manager` handles the transition logic internally. .. feat_arc_dyn:: Control interface dynamic architecture activate run target :id: feat_arc_dyn__lifecycle__control_activate diff --git a/docs/features/lifecycle/architecture/index.rst b/docs/features/lifecycle/architecture/index.rst index 4cf0b5b5ea..a2cd243eac 100644 --- a/docs/features/lifecycle/architecture/index.rst +++ b/docs/features/lifecycle/architecture/index.rst @@ -82,8 +82,8 @@ Static Architecture Dynamic Architecture -------------------- -The dynamic architecture between the interfaces and the user application -are described in the following sub-pages: +Interactions between the :term:`Launch Manager` and a User applications +(through it's interfaces): .. toctree:: :maxdepth: 1 @@ -93,9 +93,17 @@ are described in the following sub-pages: ./lifecycle_client ./alive ./launch_manager_configuration - ./health_monitor ./external_monitoring + +Interaction between the :term:`Health Monitor` and :term:`Launch Manager`: + +.. toctree:: + :maxdepth: 1 + + ./health_monitor + + Logical Interfaces ------------------ diff --git a/docs/features/lifecycle/architecture/launch_manager.rst b/docs/features/lifecycle/architecture/launch_manager.rst index 3868afb038..1d5b26a3ce 100644 --- a/docs/features/lifecycle/architecture/launch_manager.rst +++ b/docs/features/lifecycle/architecture/launch_manager.rst @@ -15,25 +15,20 @@ Launch manager ############## -The :term:`Launch Manager` is a component that provides a framework for managing -the lifecycle of processes in the S-CORE platform. It allows for launching, -monitoring, and controlling processes based on defined configurations and -requirements. As such, it is a central part of the lifecycle management in -S-CORE and knows about the state of all processes in the system. - -It's foreseen ECU projects will need a custom state management to fulfill ECU-project specific requirements. The S-CORE stack will offer a framework to control application lifecycle, but will not specify the State Manager. +The following describes the intaraction between the +:need:`comp__lifecycle_launch_manager` and the user application. Requirements ============ -- :need:`feat_req__lifecycle__launch_support` done -- :need:`feat_req__lifecycle__process_ordering` done +- :need:`feat_req__lifecycle__launch_support` +- :need:`feat_req__lifecycle__process_ordering` - :need:`feat_req__lifecycle__parallel_launch_support` -- :need:`feat_req__lifecycle__conditional_startup` done -- :need:`feat_req__lifecycle__start_named_run_target` done -- :need:`feat_req__lifecycle__process_termination` done -- :need:`feat_req__lifecycle__terminationn_dependency` done +- :need:`feat_req__lifecycle__conditional_startup` +- :need:`feat_req__lifecycle__start_named_run_target` +- :need:`feat_req__lifecycle__process_termination` +- :need:`feat_req__lifecycle__terminationn_dependency` - :need:`feat_req__lifecycle__monitor_abnormal_term` - :need:`feat_req__lifecycle__recovery_action_support` - :need:`feat_req__lifecycle__recov_run_target_switch` @@ -41,11 +36,19 @@ Requirements Overview ======== -The functionality of the :term:`Launch Manager` is defined by configuration data, which spawns a directed acyclic graph (DAG) of :term:`Components ` and so called :term:`Run Targets `. -The :term:`Run Targets ` are virtual nodes in the DAG and represent :term:`Run States ` of the system. -The :term:`Launch Manager` is responsible for starting and stopping the processes in the correct order, based on the dependencies defined in the configuration data. +The functionality of the :term:`Launch Manager` is defined by configuration +data, which spawns a directed acyclic graph (DAG) of :term:`Components +` and so called :term:`Run Targets `. +The :term:`Run Targets ` are virtual nodes in the DAG and represent +:term:`Run States ` of the system. +The :term:`Launch Manager` is responsible for starting and stopping the +processes in the correct order, based on the dependencies defined in the +configuration data. -E.g. the configuration below consists of three :term:`Run Targets ` managing 9 components. If the user selects e.g. the :term:`Run Target` "debug" the :term:`Launch Manager` will start the components in the following order defined by the dependencies. +E.g. the configuration below consists of three :term:`Run Targets ` +managing 9 components. If the user selects e.g. the :term:`Run Target` "debug" +the :term:`Launch Manager` will start the components in the following order +defined by the dependencies. 1. flash driver 2. filesystem @@ -57,20 +60,41 @@ E.g. the configuration below consists of three :term:`Run Targets ` :scale: 50 :align: center -The :need:`comp__lifecycle_launch_manager` implements the following interfaces,for the selection of :term:`Run Target` s, starting and stopping of components and monitoring of the processes. +The :need:`comp__lifecycle_launch_manager` implements the following +interfaces,for the selection of :term:`Run Target` s, starting and stopping of +components and monitoring of the processes. Switching between Run Targets ----------------------------- -The :term:`Launch Manager` allows switching between different :term:`Run Targets `. When a switch is requested, the :term:`Launch Manager` evaluates the current state and the target state, -determining which components need to be started or stopped based on their dependencies. - -When a component is started the :term:`Launch Manager` will start the corresponding process and monitor its state via :term:`Ready Conditions `. - -:term:`Ready Conditions ` are essential mechanisms that determine when a component has successfully completed its startup phase and is ready to fulfill its intended role in the system. These conditions provide flexibility in defining what constitutes a "ready" state for different types of components. For SCORE applications, components can actively report their readiness through the Lifecycle Interface by signaling specific states or custom conditions. For native applications, the :term:`Launch Manager` relies on external indicators such as process existence, file creation, network socket availability, or successful process termination. This dual approach ensures that both modern SCORE-aware applications and legacy native applications can participate in the dependency management system, allowing the :term:`Launch Manager` to orchestrate complex startup sequences where components depend on each other's readiness rather than just their launch order. - - -.. feat_arc_dyn:: Application health monitoring +The :term:`Launch Manager` allows switching between different :term:`Run +Targets `. When a switch is requested, the :term:`Launch Manager` +evaluates the current state and the target state, determining which components +need to be started or stopped based on their dependencies. + +When a component is started the :term:`Launch Manager` will start the +corresponding process and monitor its state via :term:`Ready Conditions `. + +:term:`Ready Conditions ` are essential mechanisms that +determine when a component has successfully completed its startup phase and is +ready to fulfill its intended role in the system. +These conditions provide +flexibility in defining what constitutes a "ready" state for different types of +components. +For SCORE applications, components can actively report their readiness through +the Lifecycle Interface by signaling specific states or custom conditions. +For native applications, the :term:`Launch Manager` relies on external +indicators such as process existence, file creation, network socket +availability, or successful process termination. +This dual approach ensures that both modern SCORE-aware applications and legacy +native applications can participate in the dependency management system, +allowing the :term:`Launch Manager` to orchestrate complex startup sequences +where components depend on each other's readiness rather than just their launch +order. + + +.. feat_arc_dyn:: Launch Manager - Components Depends on Each Other :id: feat_arc_dyn__lifecycle__lcm_start :security: YES :status: valid @@ -86,9 +110,51 @@ When a component is started the :term:`Launch Manager` will start the correspond :scale: 50 :align: center - - -.. feat_arc_dyn:: Application health monitoring + Configuration: + Reporting App 2 depends on Reporting App 1, Reporting App 1 has a ready + condition of begin in state running. + + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - Launch Manager analyzes the current state of the system. + * - 002 + - Launch Manager identifies the components that need to be started or stopped based on the current state. + * - 003 + - Launch Manager starts the components that need to be started. In this case Reporting App 1. + * - 004 + - Reporting App 1 is started. + * - 005 + - Launch Manager waits for the signal from the Lifecycle API. + * - 006 + - Reporting App 1 does its internal initialization. + * - 007 + - Reporting App 1 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + * - 008 + - Launch Manager analyzes the current state of the system. + * - 009 + - Launch Manager identifies the components that need to be started or stopped based on the current state. In this case Reporting App 2 can be started. + * - 010 + - Launch Manager starts the components that need to be started. In this case Reporting App 2. + * - 011 + - Reporting App 2 is started. + * - 012 + - Launch Manager waits for the signal from the Lifecycle API. + * - 013 + - Reporting App 2 does its internal initialization. + * - 014 + - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + * - 015 + - Launch Manager analyzes the current state of the system. + * - 016 + - Launch Manager marks the Run Target as active. + + +.. feat_arc_dyn:: Launch Manager - Termination Request :id: feat_arc_dyn__lifecycle__lcm_term :security: YES :status: valid @@ -103,7 +169,30 @@ When a component is started the :term:`Launch Manager` will start the correspond :scale: 50 :align: center -.. feat_arc_dyn:: Application health monitoring + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - Launch Manager analyzes the current state of the system. + * - 002 + - Launch Manager determines the transition plan for switching the run target. In this case all components are to be terminated. + * - 003 + - Launch Manager sends SIGTERM to the well behaving application. + * - 004 + - The well behaving application terminates through the operating system. + * - 005 + - Launch Manager sends SIGTERM to the badly behaving application. + * - 006 + - The badly behaving application ignores the SIGTERM request. + * - 007 + - Launch Manager sends SIGKILL to force termination of the badly behaving application. + * - 008 + - The badly behaving application terminates through the operating system. + +.. feat_arc_dyn:: Launch Manager - Components Depends on Termination :id: feat_arc_dyn__lifecycle__lcm_term_order :security: YES :status: valid @@ -119,8 +208,50 @@ When a component is started the :term:`Launch Manager` will start the correspond :scale: 50 :align: center - -.. feat_arc_dyn:: Application health monitoring + Configuration: + Reporting App 2 depends on the termination of Reporting App 1. + + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - Launch Manager analyzes the current state of the system. + * - 002 + - Launch Manager determines the transition plan. In this case Reporting App 1 can be started, Reporting App 2 needs to wait for Reporting App 1 to terminate. + * - 003 + - Launch Manager starts Reporting App 1. + * - 004 + - Reporting App 1 is started. + * - 005 + - Launch Manager waits for the ready condition of Reporting App 1. + * - 006 + - Reporting App 1 does its internal initialization. + * - 007 + - Reporting App 1 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + * - 008 + - At some point Reporting App 1 terminates. + * - 009 + - The operating system reports the termination of Reporting App 1 to the Launch Manager. + * - 010 + - Launch Manager analyzes the current state of the system. + * - 011 + - Launch Manager determines the transition plan. In this case Reporting App 2 can be started. + * - 012 + - Launch Manager starts Reporting App 2. + * - 013 + - Reporting App 2 is started. + * - 014 + - Launch Manager waits for the ready condition of Reporting App 2. + * - 015 + - Reporting App 2 does its internal initialization. + * - 016 + - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + + +.. feat_arc_dyn:: Launch Manager - Run Components in Parallel :id: feat_arc_dyn__lifecycle__lcm_parallel :security: YES :status: valid @@ -135,8 +266,38 @@ When a component is started the :term:`Launch Manager` will start the correspond :scale: 50 :align: center - -.. feat_arc_dyn:: Application health monitoring + Configuration: + Reporting App 1 and Reporting App 2 can be started independently. + + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - Launch Manager analyzes the current state of the system. + * - 002 + - Launch Manager determines the transition plan. In this case both Reporting App 1 and Reporting App 2 can be started in parallel. + * - 003 + - Launch Manager starts Reporting App 1. + * - 004 + - Launch Manager starts Reporting App 2. + * - 005 + - Reporting App 1 is started. + * - 006 + - Reporting App 2 is started. + * - 007 + - Reporting App 1 does its internal initialization. + * - 008 + - Reporting App 1 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + * - 009 + - Reporting App 2 does its internal initialization. + * - 010 + - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + + +.. feat_arc_dyn:: Launch Manager - Termination Request :id: feat_arc_dyn__lifecycle__crash :security: YES :status: valid @@ -151,3 +312,22 @@ When a component is started the :term:`Launch Manager` will start the correspond :scale: 50 :align: center + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - The monitored process crashes unexpectedly. + * - 002 + - The crashed process terminates through the operating system. + * - 003 + - The operating system reports the terminated process to the Launch Manager. + * - 004 + - Launch Manager analyzes the current state of the system. + * - 005 + - Launch Manager determines the transition plan.\nIn this case a recovery action needs to be run,\nand the recovery action is to switch to a different Run Target. + * - 006 + - Launch Manager switches to the configured fallback Run Target. + diff --git a/score/launch_manager/docs/architecture/component_architecture.rst b/score/launch_manager/docs/architecture/component_architecture.rst index bb1c4acb25..ddac16fc65 100644 --- a/score/launch_manager/docs/architecture/component_architecture.rst +++ b/score/launch_manager/docs/architecture/component_architecture.rst @@ -41,6 +41,19 @@ Overview :security: NO :belongs_to: feat__lifecycle[version==1] + The :term:`Launch Manager` is a component that provides a framework for + managing the lifecycle of processes in the S-CORE platform. + It allows for launching, monitoring, and controlling processes based on + defined configurations and requirements. + As such, it is a central part of the lifecycle management in S-CORE and + knows about the state of all processes in the system. + + It's foreseen ECU projects will need a custom state management to fulfill + ECU-project specific requirements. + The S-CORE stack will offer a framework to control application lifecycle, + but will not specify the State Manager. + + Requirements Linked to Component Architecture --------------------------------------------- From 35034b920cbcd2791d792b9108980f99c50fc8fe Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Fri, 11 Sep 2026 12:14:27 +0100 Subject: [PATCH 3/6] Some cleanup --- .../features/lifecycle/architecture/alive.rst | 3 - .../lifecycle/architecture/control_client.rst | 34 +++---- .../architecture/external_monitoring.rst | 99 +++++++++++-------- .../lifecycle/architecture/health_monitor.rst | 87 +++++++--------- .../features/lifecycle/architecture/index.rst | 11 +-- .../launch_manager_configuration.rst | 3 +- 6 files changed, 114 insertions(+), 123 deletions(-) diff --git a/docs/features/lifecycle/architecture/alive.rst b/docs/features/lifecycle/architecture/alive.rst index 52b38eb37f..bde2626bc7 100644 --- a/docs/features/lifecycle/architecture/alive.rst +++ b/docs/features/lifecycle/architecture/alive.rst @@ -38,9 +38,6 @@ The liveliness mechanism includes: The alive interface is defined here: :need:`logic_arc_int__lifecycle__alive_if` -Requirements -============ -- :need:`feat_req__lifecycle__liveliness_detection` Dynamic architecture ==================== diff --git a/docs/features/lifecycle/architecture/control_client.rst b/docs/features/lifecycle/architecture/control_client.rst index 64c9dbcc10..126eebc1ea 100644 --- a/docs/features/lifecycle/architecture/control_client.rst +++ b/docs/features/lifecycle/architecture/control_client.rst @@ -20,27 +20,6 @@ targets. It allows users to trigger execution of configured :term:`Run targets ` through a standardized activation mechanism. -Interface -========= - -The control interface is defined here: -:need:`logic_arc_int__lifecycle__controlif` The :term:`Launch Manager` provides -an interface, which allows an external State Manager application to request the -:term:`Launch Manager` to start, stop or restart applications or groups of -applications, which allows the implementation of a state management -applications to support dynamic state control. - -Requirements -============ - -- :need:`feat_req__lifecycle__control_commands` -- :need:`feat_req__lifecycle__request_run_target_start` -- :need:`feat_req__lifecycle__switch_run_targets` - - -Dynamic architecture -==================== - The following use cases are supported by the `ControlInterface` provided by the :term:`Launch Manager`. @@ -71,6 +50,19 @@ This unified approach allows external state managers to request any run target activation without needing to know the current system state, as the :term:`Launch Manager` handles the transition logic internally. +Interface +========= + +The control interface is defined here: +:need:`logic_arc_int__lifecycle__controlif` The :term:`Launch Manager` provides +an interface, which allows an external State Manager application to request the +:term:`Launch Manager` to start, stop or restart applications or groups of +applications, which allows the implementation of a state management +applications to support dynamic state control. + +Dynamic architecture +==================== + .. feat_arc_dyn:: Control interface dynamic architecture activate run target :id: feat_arc_dyn__lifecycle__control_activate :status: valid diff --git a/docs/features/lifecycle/architecture/external_monitoring.rst b/docs/features/lifecycle/architecture/external_monitoring.rst index d8b6962335..ccc6661080 100644 --- a/docs/features/lifecycle/architecture/external_monitoring.rst +++ b/docs/features/lifecycle/architecture/external_monitoring.rst @@ -24,58 +24,77 @@ The following participants are related to the concept. Launch Manager -------------- -As the :term:`Launch Manager` is critical component for the system, it shall support alive monitoring of itself. This means it must implement internal health management, such as -a worker thread, that wakes up every N milliseconds, checks if the component is in a consistent state, and send a notification to the external monitor. +As the :term:`Launch Manager` is critical component for the system, it shall +support alive monitoring of itself. +This means it must implement internal health management, such as a worker +thread, that wakes up every N milliseconds, checks if the component is in a +consistent state, and send a notification to the external monitor. External monitor ---------------- -The aliveness of the :term:`Launch Manager` shall be monitored by an `external monitor, or a watchdog `_, to be able to detect "hanging" of the -`Launch Manager`. The implementation of the external watchdog is out of scope in S-SCORE, as it is ECU and/or project specific. +The aliveness of the :term:`Launch Manager` shall be monitored by an `external +monitor, or a watchdog `_, to be +able to detect "hanging" of the `Launch Manager`. +The implementation of the external watchdog is out of scope in S-SCORE, as it +is ECU and/or project specific. Watchdog Proxy -------------- -The component `Watchdog Proxy` is the project specific logical component, which has to implement the logical interface `HealthStatus` and translate alive events from the :term:`Launch Manager` as -project specific messages to the `External monitor`. The channel for sending these notifications is project specific, and can be for example `GPIO`, `UART` or `SPI`. -In a hypervisor based environment, the `external monitor` could also run with the same SoC as software only solution. +The component `Watchdog Proxy` is the project specific logical component, which +has to implement the logical interface `HealthStatus` and translate alive +events from the :term:`Launch Manager` as project specific messages to the +`External monitor`. +The channel for sending these notifications is project specific, and can be for +example `GPIO`, `UART` or `SPI`. +In a hypervisor based environment, the `external monitor` could also run with +the same SoC as software only solution. -The `Watchdog Proxy` implementation is not specified in the S-CORE with high details, as the realization depends heavily on OS, :term:`Launch Manager` or even project specific needs. -For example, in Linux and `systemd` as the :term:`Launch Manager`, the interface can be `/dev/watchdog`, and `systemd` can use the interface directly. +The `Watchdog Proxy` implementation is not specified in the S-CORE with high +details, as the realization depends heavily on OS, :term:`Launch Manager` or +even project specific needs. +For example, in Linux and `systemd` as the :term:`Launch Manager`, the +interface can be `/dev/watchdog`, and `systemd` can use the interface directly. -In QNX, one could implement a component listening to the events (or even poll) from the :term:`Launch Manager` and translate these events as hardware specific notifications. - -Requirements related to the external monitoring -=============================================== - -- :need:`feat_req__lifecycle__lm_self_health_check` +In QNX, one could implement a component listening to the events (or even poll) +from the :term:`Launch Manager` and translate these events as hardware specific +notifications. Dynamic Architecture ==================== -.. uml:: _assets/external_monitoring_sequence.puml - :alt: External monitoring static arch - -The most important interactions are the following: - -.. list-table:: Sequence diagram Description - :widths: 10 90 - :header-rows: 1 - - * - Sequence number - - Description - * - 001 - - The configuration. (notification interval, startup grace period, etc.) Additionally, if a watchdog interface is used, the used interface name (eg. /dev/watchdog) must be configurable. - * - 002 - - If the :term:`Launch Manager` provides a client library implementation, the library must connect and attach to the :term:`Launch Manager` - * - 006 - - Check the internal status and trigger alive notification (007) - * - 007 - - Send the alive notification to the external monitor. (UART/SPI/GPIO/etc.) - * - 009 - - Watchdog to check if the notification fits the expected window - * - 018 - - If the status check fails, do not trigger alive notification (or :term:`Launch Manager` has crashed) - * - 019 - - If there is no alive notification, trigger watchdog error reaction +.. feat_arc_dyn:: Launch Manager Watchdog Interaction + :id: feat_arc_dyn__lifecycle__watch + :status: valid + :version: 1 + :safety: ASIL_B + :security: YES + :fulfils: feat_req__lifecycle__lm_self_health_check[version==1], + :belongs_to: feat__lifecycle[version==1] + + .. uml:: _assets/external_monitoring_sequence.puml + :alt: External monitoring static arch + + + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - The configuration. (notification interval, startup grace period, etc.) Additionally, if a watchdog interface is used, the used interface name (eg. /dev/watchdog) must be configurable. + * - 002 + - If the :term:`Launch Manager` provides a client library implementation, the library must connect and attach to the :term:`Launch Manager` + * - 006 + - Check the internal status and trigger alive notification (007) + * - 007 + - Send the alive notification to the external monitor. (UART/SPI/GPIO/etc.) + * - 009 + - Watchdog to check if the notification fits the expected window + * - 018 + - If the status check fails, do not trigger alive notification (or :term:`Launch Manager` has crashed) + * - 019 + - If there is no alive notification, trigger watchdog error reaction diff --git a/docs/features/lifecycle/architecture/health_monitor.rst b/docs/features/lifecycle/architecture/health_monitor.rst index b61c41a069..502f045e13 100644 --- a/docs/features/lifecycle/architecture/health_monitor.rst +++ b/docs/features/lifecycle/architecture/health_monitor.rst @@ -100,64 +100,45 @@ Dynamic Architecture :version: 1 :safety: ASIL_B :fulfils: feat_req__lifecycle__liveliness_detection[version==1], - feat_req__lifecycle__hm_checkpoint[version==1] + feat_req__lifecycle__hm_checkpoint[version==1], + feat_req__lifecycle__hm_deadline[version==1], :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/application_health_monitoring_dynamic.puml :scale: 50 :align: center -The most important interactions are the following: - -.. list-table:: Sequence diagram Description - :widths: 10 90 - :header-rows: 1 - - * - Sequence number - - Description - * - 001 - - :term:`Launch Manager` configuration for the alive monitoring of the `Monitored application` is parsed. This contains for example, what is the expected interval of alive notifications, - how long grace period is given before failing to a missed (never received) alive notification etc. - * - 002 - - Start the startup grace period timer to allow the application to startup, before timing out to a missed alive notification - * - 003 - - The `Monitored application` is started. (To simplify, no startup checks drawn here) - * - 004 - - The `Monitored application` instantiate and configure the HealthMonitor - * - 006 - - Cyclic reporting aliveness to the monitor. - * - 007 - - HealthMonitor waking up and checking if the checkpoint(s) have been called - * - 008 - - Report aliveness to the LM's application specific supervision, observing the health of the HealthMonitor itself - * - 009 - - Checkpoint sent, but not on time - * - 010 - - Wake up and check if the checkpoint(s) have been triggered. In this case it was not, and thus actions 011 and 012 are triggered. - * - 011 - - Trigger a failure event to the Launch Manager. This event allows the monitor react faster than waiting for the timeout to expire. - * - 012 - - Additionally, triggering alive must be stopped + The most important interactions are the following: + + .. list-table:: Sequence diagram Description + :widths: 10 90 + :header-rows: 1 + + * - Sequence number + - Description + * - 001 + - :term:`Launch Manager` configuration for the alive monitoring of the `Monitored application` is parsed. This contains for example, what is the expected interval of alive notifications, how long grace period is given before failing to a missed (never received) alive notification etc. + * - 002 + - Start the startup grace period timer to allow the application to startup, before timing out to a missed alive notification + * - 003 + - The `Monitored application` is started. (To simplify, no startup checks drawn here) + * - 004 + - The `Monitored application` instantiate and configure the HealthMonitor + * - 006 + - Cyclic reporting aliveness to the monitor. + * - 007 + - HealthMonitor waking up and checking if the checkpoint(s) have been called + * - 008 + - Report aliveness to the LM's application specific supervision, observing the health of the HealthMonitor itself + * - 009 + - Checkpoint sent, but not on time + * - 010 + - Wake up and check if the checkpoint(s) have been triggered. In this case it was not, and thus actions 011 and 012 are triggered. + * - 011 + - Trigger a failure event to the Launch Manager. This event allows the monitor react faster than waiting for the timeout to expire. + * - 012 + - Additionally, triggering alive must be stopped -Requirements ------------- - -- :need:`feat_req__lifecycle__liveliness_detection` -- :need:`feat_req__lifecycle__hm_deadline` -- :need:`feat_req__lifecycle__hm_checkpoint` -- :need:`feat_req__lifecycle__hm_logical` - -Logical Monitor API -=================== - -Interface ---------- - -The logical monitor interface is defined here: :need:`logic_arc_int__lifecycle__logical_monitor_if` - - -Dynamic Architecture --------------------- .. feat_arc_dyn:: Logical control flow monitoring :id: feat_arc_dyn__lifecycle__app_ctrl_flow_mon @@ -165,7 +146,9 @@ Dynamic Architecture :status: valid :version: 1 :safety: ASIL_B - :fulfils: feat_req__lifecycle__liveliness_detection[version==1] + :fulfils: feat_req__lifecycle__liveliness_detection[version==1], + feat_req__lifecycle__hm_checkpoint[version==1], + feat_req__lifecycle__hm_logical[version==1], :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/logical_sup.puml diff --git a/docs/features/lifecycle/architecture/index.rst b/docs/features/lifecycle/architecture/index.rst index a2cd243eac..ff5a5305d1 100644 --- a/docs/features/lifecycle/architecture/index.rst +++ b/docs/features/lifecycle/architecture/index.rst @@ -43,10 +43,6 @@ The concept is based on 2 major components: -Requirements ------------- - -The requirements for the feature architecture are defined in the `requirements` section of the feature documentation in the project repository: :need:`doc__lifecycle_requirements` Rationale Behind Architecture Decomposition ******************************************* @@ -78,21 +74,24 @@ Static Architecture :align: center {{ draw_feature(need(), needs) }} + artifact "Configuration" as cfg + + comp__lifecycle_launch_manager --> cfg: use Dynamic Architecture -------------------- -Interactions between the :term:`Launch Manager` and a User applications +Interactions between the :term:`Launch Manager` and a User application (through it's interfaces): .. toctree:: :maxdepth: 1 - ./launch_manager ./control_client ./lifecycle_client ./alive ./launch_manager_configuration + ./launch_manager ./external_monitoring diff --git a/docs/features/lifecycle/architecture/launch_manager_configuration.rst b/docs/features/lifecycle/architecture/launch_manager_configuration.rst index 85970421a1..0a9b10e1e9 100644 --- a/docs/features/lifecycle/architecture/launch_manager_configuration.rst +++ b/docs/features/lifecycle/architecture/launch_manager_configuration.rst @@ -15,7 +15,8 @@ Launch Manager Configuration ############################ -The :term:`Launch Manager` supports a set of configuration parameters, which are grouped in the following categories: +The :term:`Launch Manager` supports a set of configuration parameters, which +are grouped in the following categories: Component Configuration Parameters ================================== From b9b69d8a53cf7f26f8c50e65906ab23fa721a0c2 Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Mon, 14 Sep 2026 08:16:49 +0100 Subject: [PATCH 4/6] Fixing comments --- ...application_health_monitoring_dynamic.puml | 7 ++-- .../_assets/launch_manager_parallel_dep.puml | 20 ++++++------ .../_assets/launch_manager_random_crash.puml | 12 +++---- .../_assets/launch_manager_running_dep.puml | 32 +++++++++---------- .../_assets/launch_manager_terminate_dep.puml | 32 +++++++++---------- .../launch_manager_terminate_request.puml | 16 +++++----- .../lifecycle/architecture/control_client.rst | 2 +- .../architecture/external_monitoring.rst | 2 +- .../lifecycle/architecture/health_monitor.rst | 4 +-- .../lifecycle/architecture/launch_manager.rst | 20 +++++------- .../architecture/lifecycle_client.rst | 11 ------- .../architecture/component_architecture.rst | 4 +-- 12 files changed, 73 insertions(+), 89 deletions(-) diff --git a/docs/features/lifecycle/architecture/_assets/application_health_monitoring_dynamic.puml b/docs/features/lifecycle/architecture/_assets/application_health_monitoring_dynamic.puml index 487be5f5cb..b1292c18c9 100644 --- a/docs/features/lifecycle/architecture/_assets/application_health_monitoring_dynamic.puml +++ b/docs/features/lifecycle/architecture/_assets/application_health_monitoring_dynamic.puml @@ -43,7 +43,7 @@ HM -> HM: Wakeup and check if the\ncheckpoints have been called HM -> LM: Supervision failure notification HM -X LM: Stop triggering alive -LM -> LM: Error reaction\n(notify State manager) +LM -> LM: Error reaction\n(Recovery Action) hnote across: Use Case: Direct error report by the Application @@ -51,7 +51,7 @@ App -> HM: Report error HM -> LM: Supervision failure notification HM -X LM: Stop triggering alive -LM -> LM: Error reaction\n(notify State manager) +LM -> LM: Error reaction\n(Recovery Action) hnote across: Use Case: Crashed Application @@ -61,7 +61,6 @@ destroy HM LM -> LM: Wakeup and check if the\ncheckpoints have been called LM -> LM: No alive notification seen -LM -> LM: Error reaction\n(notify State manager) - +LM -> LM: Error reaction\n(Recovery Action) @enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml index c9a90a4e28..62ad396254 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_parallel_dep.puml @@ -22,20 +22,20 @@ participant "Reporting App 1" as app1 participant "Reporting App 2" as app2 activate LM -LM -> LM: analyze current state -LM -> LM: determine transition plan +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 1 -LM -> kernel: Start Reporting App 2 -kernel -> app1 **: Start -kernel -> app2 **: Start +LM -> kernel: Start Reporting App 1. +LM -> kernel: Start Reporting App 2. +kernel -> app1 **: Start. +kernel -> app2 **: Start. activate app1 activate app2 -app1 -> app1: Internal User app initialization -app1 -> LM: signal ready state via Lifecycle API -app2 -> app2: Internal User app initialization -app2 -> LM: signal ready state via Lifecycle API +app1 -> app1: Internal User app initialization. +app1 -> LM: Signal ready state via Lifecycle API. +app2 -> app2: Internal User app initialization. +app2 -> LM: Signal ready state via Lifecycle API. ... @enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml index 1995458e25..633ef697be 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_random_crash.puml @@ -12,7 +12,7 @@ ' ******************************************************************************* @startuml -title Launch Manager - Termination Request +title Launch Manager - Crash Recovery autonumber "[00]" @@ -27,13 +27,13 @@ activate app1 ... -app1 -> app1: Random crash -app1 -> kernel: terminate +app1 -> app1: Random crash. +app1 -> kernel: Terminate. destroy app1 -kernel -> LM: process terminated +kernel -> LM: Process terminated. -LM -> LM: analyze current state -LM -> LM: determine transition plan.\nA recovery action has to be ran,\nthe recovery action is to switch to a different Run Target. +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan.\nA recovery action has to be ran,\nthe recovery action is to switch to a different Run Target. LM -> LM: Switch Run Target. ... diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml index c99104625f..188f6a33c4 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml @@ -22,28 +22,28 @@ participant "Reporting App 1" as app1 participant "Reporting App 2" as app2 activate LM -LM -> LM: analyze current state -LM -> LM: determine transition plan +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 1 -kernel -> app1 **: Start +LM -> kernel: Start Reporting App 1. +kernel -> app1 **: Start. activate app1 -LM -> LM: wait for Reporting App 1 ready condition -app1 -> app1: Internal User app initialization -app1 -> LM: signal ready state via Lifecycle API +LM -> LM: Wait for Reporting App 1 ready condition. +app1 -> app1: Internal User app initialization. +app1 -> LM: Signal ready state via Lifecycle API. -LM -> LM: analyze current state -LM -> LM: determine transition plan +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 2 -kernel -> app2 **: Start +LM -> kernel: Start Reporting App 2. +kernel -> app2 **: Start. activate app2 -LM -> LM: wait for Reporting App 2 ready condition -app2 -> app2: Internal User app initialization -app2 -> LM: signal ready state via Lifecycle API +LM -> LM: Wait for Reporting App 2 ready condition. +app2 -> app2: Internal User app initialization. +app2 -> LM: Signal ready state via Lifecycle API. -LM -> LM: analyze current state -LM -> LM: update current run target state to active +LM -> LM: Analyze current state. +LM -> LM: Update current run target state to active. ... @enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml index fe5cbc6c07..0c00036cfc 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml @@ -22,31 +22,31 @@ participant "Reporting App 1" as app1 participant "Reporting App 2" as app2 activate LM -LM -> LM: analyze current state -LM -> LM: determine transition plan +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 1 -kernel -> app1 **: Start +LM -> kernel: Start Reporting App 1. +kernel -> app1 **: Start. activate app1 -LM -> LM: wait for Reporting App 1 ready condition -app1 -> app1: Internal User app initialization -app1 -> LM: signal ready state via Lifecycle API +LM -> LM: Wait for Reporting App 1 ready condition. +app1 -> app1: Internal User app initialization. +app1 -> LM: Signal ready state via Lifecycle API. ... -app1 -> kernel: Termination +app1 -> kernel: Termination. destroy app1 -kernel -> LM: Reporting App 1 Terminated +kernel -> LM: Reporting App 1 terminated. deactivate app1 -LM -> LM: analyze current state -LM -> LM: determine transition plan +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 2 -kernel -> app2 **: Start +LM -> kernel: Start Reporting App 2. +kernel -> app2 **: Start. activate app2 -LM -> LM: wait for Reporting App 2 ready condition -app2 -> app2: Internal User app initialization -app2 -> LM: signal ready state via Lifecycle API +LM -> LM: Wait for Reporting App 2 ready condition. +app2 -> app2: Internal User app initialization. +app2 -> LM: Signal ready state via Lifecycle API. ... @enduml diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml index f823dd038d..497537e392 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml @@ -27,18 +27,18 @@ activate app2 == Switch Run Target == -LM -> LM: analyze current state -LM -> LM: determine transition plan +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. -LM -> app1: SIGTERM -app1 -> kernel: terminate +LM -> app1: SIGTERM. +app1 -> kernel: Terminate. destroy app1 -LM -> app2: SIGTERM -app2 -> app2: Ignore -LM -> app2: SIGKILL -app2 -> kernel: terminate +LM -> app2: SIGTERM. +app2 -> app2: Ignore. +LM -> app2: SIGKILL. +app2 -> kernel: Terminate. destroy app2 @enduml diff --git a/docs/features/lifecycle/architecture/control_client.rst b/docs/features/lifecycle/architecture/control_client.rst index 126eebc1ea..b0aab9b132 100644 --- a/docs/features/lifecycle/architecture/control_client.rst +++ b/docs/features/lifecycle/architecture/control_client.rst @@ -71,7 +71,7 @@ Dynamic architecture :security: YES :fulfils: feat_req__lifecycle__control_commands[version==1], feat_req__lifecycle__request_run_target_start[version==1], - feat_req__lifecycle__switch_run_targets[version==1], + feat_req__lifecycle__switch_run_targets[version==1] :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/control_interface_start_sequence.puml diff --git a/docs/features/lifecycle/architecture/external_monitoring.rst b/docs/features/lifecycle/architecture/external_monitoring.rst index ccc6661080..9affe0a72a 100644 --- a/docs/features/lifecycle/architecture/external_monitoring.rst +++ b/docs/features/lifecycle/architecture/external_monitoring.rst @@ -71,7 +71,7 @@ Dynamic Architecture :version: 1 :safety: ASIL_B :security: YES - :fulfils: feat_req__lifecycle__lm_self_health_check[version==1], + :fulfils: feat_req__lifecycle__lm_self_health_check[version==1] :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/external_monitoring_sequence.puml diff --git a/docs/features/lifecycle/architecture/health_monitor.rst b/docs/features/lifecycle/architecture/health_monitor.rst index 502f045e13..cd0eed03e1 100644 --- a/docs/features/lifecycle/architecture/health_monitor.rst +++ b/docs/features/lifecycle/architecture/health_monitor.rst @@ -101,7 +101,7 @@ Dynamic Architecture :safety: ASIL_B :fulfils: feat_req__lifecycle__liveliness_detection[version==1], feat_req__lifecycle__hm_checkpoint[version==1], - feat_req__lifecycle__hm_deadline[version==1], + feat_req__lifecycle__hm_deadline[version==1] :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/application_health_monitoring_dynamic.puml @@ -148,7 +148,7 @@ Dynamic Architecture :safety: ASIL_B :fulfils: feat_req__lifecycle__liveliness_detection[version==1], feat_req__lifecycle__hm_checkpoint[version==1], - feat_req__lifecycle__hm_logical[version==1], + feat_req__lifecycle__hm_logical[version==1] :belongs_to: feat__lifecycle[version==1] .. uml:: _assets/logical_sup.puml diff --git a/docs/features/lifecycle/architecture/launch_manager.rst b/docs/features/lifecycle/architecture/launch_manager.rst index 1d5b26a3ce..1d290cba10 100644 --- a/docs/features/lifecycle/architecture/launch_manager.rst +++ b/docs/features/lifecycle/architecture/launch_manager.rst @@ -15,7 +15,7 @@ Launch manager ############## -The following describes the intaraction between the +The following describes the interaction between the :need:`comp__lifecycle_launch_manager` and the user application. @@ -79,19 +79,15 @@ Condition>`. :term:`Ready Conditions ` are essential mechanisms that determine when a component has successfully completed its startup phase and is ready to fulfill its intended role in the system. -These conditions provide -flexibility in defining what constitutes a "ready" state for different types of -components. +These conditions provide flexibility in defining what constitutes a "ready" +state for different types of components. For SCORE applications, components can actively report their readiness through the Lifecycle Interface by signaling specific states or custom conditions. For native applications, the :term:`Launch Manager` relies on external indicators such as process existence, file creation, network socket availability, or successful process termination. This dual approach ensures that both modern SCORE-aware applications and legacy -native applications can participate in the dependency management system, -allowing the :term:`Launch Manager` to orchestrate complex startup sequences -where components depend on each other's readiness rather than just their launch -order. +native applications can participate in the dependency management system. .. feat_arc_dyn:: Launch Manager - Components Depends on Each Other @@ -104,7 +100,7 @@ order. :fulfils: feat_req__lifecycle__launch_support[version==1], feat_req__lifecycle__process_ordering[version==1], feat_req__lifecycle__start_named_run_target[version==1], - feat_req__lifecycle__conditional_startup[version==1], + feat_req__lifecycle__conditional_startup[version==1] .. uml:: _assets/launch_manager_running_dep.puml :scale: 50 @@ -112,7 +108,7 @@ order. Configuration: Reporting App 2 depends on Reporting App 1, Reporting App 1 has a ready - condition of begin in state running. + condition of being in state running. .. list-table:: Sequence diagram Description :widths: 10 90 @@ -163,7 +159,7 @@ order. :belongs_to: feat__lifecycle[version==1] :fulfils: feat_req__lifecycle__launch_support[version==1], feat_req__lifecycle__process_termination[version==1], - feat_req__lifecycle__process_ordering[version==1], + feat_req__lifecycle__process_ordering[version==1] .. uml:: _assets/launch_manager_terminate_request.puml :scale: 50 @@ -297,7 +293,7 @@ order. - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. -.. feat_arc_dyn:: Launch Manager - Termination Request +.. feat_arc_dyn:: Launch Manager - Crash Recovery :id: feat_arc_dyn__lifecycle__crash :security: YES :status: valid diff --git a/docs/features/lifecycle/architecture/lifecycle_client.rst b/docs/features/lifecycle/architecture/lifecycle_client.rst index 7adaa3cd81..a484645491 100644 --- a/docs/features/lifecycle/architecture/lifecycle_client.rst +++ b/docs/features/lifecycle/architecture/lifecycle_client.rst @@ -39,9 +39,6 @@ applications and the :term:`Launch Manager`: - Basic process monitoring (PID-based status checking) - Exit code evaluation for failure detection -Requirements -============ - Interface ========= @@ -85,7 +82,6 @@ controlled through POSIX signals: - **SIGTERM**: Graceful shutdown request - **SIGKILL**: Forced termination (after timeout) -- **SIGUSR1/SIGUSR2**: Application-specific signals (if configured) The :term:`Launch Manager` monitors native applications through: @@ -122,10 +118,3 @@ Dynamic Architecture .. uml:: _assets/lifecycle_state_machine.puml :scale: 50 :align: center - -Requirements -============ - -- :need:`feat_req__lifecycle__process_termination` -- :need:`feat_req__lifecycle__launch_support` -- :need:`feat_req__lifecycle__prog_lang` diff --git a/score/launch_manager/docs/architecture/component_architecture.rst b/score/launch_manager/docs/architecture/component_architecture.rst index ddac16fc65..1e5dae1705 100644 --- a/score/launch_manager/docs/architecture/component_architecture.rst +++ b/score/launch_manager/docs/architecture/component_architecture.rst @@ -34,10 +34,10 @@ Overview :safety: ASIL_B :implements: logic_arc_int__lifecycle__controlif[version==1], logic_arc_int__lifecycle__alive_if[version==1], - logic_arc_int__lifecycle__lifecycle_if[version==1], + logic_arc_int__lifecycle__lifecycle_if[version==1] :uses: logic_arc_int__log_cpp__logging[version==1], logic_arc_int__baselibs__json[version==1], - logic_arc_int__os__unistd[version==1], + logic_arc_int__os__unistd[version==1] :security: NO :belongs_to: feat__lifecycle[version==1] From 63e3a7b526e0aeb453aeabe98a9b885003ad829b Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Mon, 14 Sep 2026 13:00:48 +0100 Subject: [PATCH 5/6] Fixing comments --- .../_assets/launch_manager_running_dep.puml | 20 ++--- .../_assets/launch_manager_terminate_dep.puml | 14 ++-- .../launch_manager_terminate_request.puml | 4 +- .../features/lifecycle/architecture/alive.rst | 2 + .../lifecycle/architecture/control_client.rst | 2 + .../architecture/external_monitoring.rst | 4 +- .../lifecycle/architecture/health_monitor.rst | 10 +-- .../features/lifecycle/architecture/index.rst | 41 ++++++---- .../lifecycle/architecture/launch_manager.rst | 69 ++++++----------- .../launch_manager_configuration.rst | 75 ------------------- .../architecture/lifecycle_client.rst | 2 + .../architecture/component_architecture.rst | 3 +- 12 files changed, 83 insertions(+), 163 deletions(-) delete mode 100644 docs/features/lifecycle/architecture/launch_manager_configuration.rst diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml index 188f6a33c4..c91603656b 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_running_dep.puml @@ -25,16 +25,6 @@ activate LM LM -> LM: Analyze current state. LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 1. -kernel -> app1 **: Start. -activate app1 -LM -> LM: Wait for Reporting App 1 ready condition. -app1 -> app1: Internal User app initialization. -app1 -> LM: Signal ready state via Lifecycle API. - -LM -> LM: Analyze current state. -LM -> LM: Determine transition plan. - LM -> kernel: Start Reporting App 2. kernel -> app2 **: Start. activate app2 @@ -42,6 +32,16 @@ LM -> LM: Wait for Reporting App 2 ready condition. app2 -> app2: Internal User app initialization. app2 -> LM: Signal ready state via Lifecycle API. +LM -> LM: Analyze current state. +LM -> LM: Determine transition plan. + +LM -> kernel: Start Reporting App 1. +kernel -> app1 **: Start. +activate app1 +LM -> LM: Wait for Reporting App 1 ready condition. +app1 -> app1: Internal User app initialization. +app1 -> LM: Signal ready state via Lifecycle API. + LM -> LM: Analyze current state. LM -> LM: Update current run target state to active. diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml index 0c00036cfc..7c46bd05c0 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_dep.puml @@ -21,20 +21,18 @@ participant "OS (kernel)" as kernel participant "Reporting App 1" as app1 participant "Reporting App 2" as app2 activate LM +activate app1 + +== Switch Run Target == LM -> LM: Analyze current state. LM -> LM: Determine transition plan. -LM -> kernel: Start Reporting App 1. -kernel -> app1 **: Start. -activate app1 -LM -> LM: Wait for Reporting App 1 ready condition. -app1 -> app1: Internal User app initialization. -app1 -> LM: Signal ready state via Lifecycle API. +LM -> app1: SIGTERM +app1 -> kernel: Termination. +destroy app1 -... -app1 -> kernel: Termination. destroy app1 kernel -> LM: Reporting App 1 terminated. deactivate app1 diff --git a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml index 497537e392..2d5d2de8df 100644 --- a/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml +++ b/docs/features/lifecycle/architecture/_assets/launch_manager_terminate_request.puml @@ -18,8 +18,8 @@ autonumber "[00]" participant "Launch Manager" as LM participant "OS (kernel)" as kernel -participant "Non self-terminating (well behaving)" as app1 -participant "Non self-terminating (badly behaving)" as app2 +participant "User App 1 (well behaving)" as app1 +participant "User App 2 (badly behaving)" as app2 activate LM activate app1 diff --git a/docs/features/lifecycle/architecture/alive.rst b/docs/features/lifecycle/architecture/alive.rst index bde2626bc7..cfa5ec5a9b 100644 --- a/docs/features/lifecycle/architecture/alive.rst +++ b/docs/features/lifecycle/architecture/alive.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + Alive ##### diff --git a/docs/features/lifecycle/architecture/control_client.rst b/docs/features/lifecycle/architecture/control_client.rst index b0aab9b132..d4d74b2a1a 100644 --- a/docs/features/lifecycle/architecture/control_client.rst +++ b/docs/features/lifecycle/architecture/control_client.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + Control Client ############## diff --git a/docs/features/lifecycle/architecture/external_monitoring.rst b/docs/features/lifecycle/architecture/external_monitoring.rst index 9affe0a72a..28e76926dd 100644 --- a/docs/features/lifecycle/architecture/external_monitoring.rst +++ b/docs/features/lifecycle/architecture/external_monitoring.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + External Monitoring ################### @@ -78,7 +80,7 @@ Dynamic Architecture :alt: External monitoring static arch - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 diff --git a/docs/features/lifecycle/architecture/health_monitor.rst b/docs/features/lifecycle/architecture/health_monitor.rst index cd0eed03e1..ad07eb385c 100644 --- a/docs/features/lifecycle/architecture/health_monitor.rst +++ b/docs/features/lifecycle/architecture/health_monitor.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + Health Monitor ############## @@ -110,7 +112,7 @@ Dynamic Architecture The most important interactions are the following: - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 @@ -154,9 +156,3 @@ Dynamic Architecture .. uml:: _assets/logical_sup.puml :scale: 50 :align: center - - -Requirements ------------- - -- :need:`feat_req__lifecycle__hm_logical` diff --git a/docs/features/lifecycle/architecture/index.rst b/docs/features/lifecycle/architecture/index.rst index ff5a5305d1..254699ad36 100644 --- a/docs/features/lifecycle/architecture/index.rst +++ b/docs/features/lifecycle/architecture/index.rst @@ -78,29 +78,44 @@ Static Architecture comp__lifecycle_launch_manager --> cfg: use + +.. feat_arc_sta:: Configuration parameters static architecture + :id: feat_arc_sta__lifecycle__cfg_params_static + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__lifecycle__component_group_config[version==1], + feat_req__lifecycle__config_file_support[version==1], + feat_req__lifecycle__run_target_support[version==1] + :belongs_to: feat__lifecycle + :includes: logic_arc_int__lifecycle__lifecycle_if[version==1], + logic_arc_int__lifecycle__alive_if[version==1], + logic_arc_int__lifecycle__controlif[version==1], + logic_arc_int__lifecycle__deadline_monitor_if[version==1], + logic_arc_int__lifecycle__logical_monitor_if[version==1] + + .. uml:: _assets/config_params_static.puml + :scale: 50 + :align: center + + Dynamic Architecture -------------------- Interactions between the :term:`Launch Manager` and a User application (through it's interfaces): -.. toctree:: - :maxdepth: 1 - - ./control_client - ./lifecycle_client - ./alive - ./launch_manager_configuration - ./launch_manager - ./external_monitoring +* :doc:`./control_client` +* :doc:`./lifecycle_client` +* :doc:`./alive` +* :doc:`./launch_manager` +* :doc:`./external_monitoring` Interaction between the :term:`Health Monitor` and :term:`Launch Manager`: -.. toctree:: - :maxdepth: 1 - - ./health_monitor +* :doc:`./health_monitor` Logical Interfaces diff --git a/docs/features/lifecycle/architecture/launch_manager.rst b/docs/features/lifecycle/architecture/launch_manager.rst index 1d290cba10..55def046d7 100644 --- a/docs/features/lifecycle/architecture/launch_manager.rst +++ b/docs/features/lifecycle/architecture/launch_manager.rst @@ -12,27 +12,14 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + Launch manager ############## The following describes the interaction between the :need:`comp__lifecycle_launch_manager` and the user application. - -Requirements -============ - -- :need:`feat_req__lifecycle__launch_support` -- :need:`feat_req__lifecycle__process_ordering` -- :need:`feat_req__lifecycle__parallel_launch_support` -- :need:`feat_req__lifecycle__conditional_startup` -- :need:`feat_req__lifecycle__start_named_run_target` -- :need:`feat_req__lifecycle__process_termination` -- :need:`feat_req__lifecycle__terminationn_dependency` -- :need:`feat_req__lifecycle__monitor_abnormal_term` -- :need:`feat_req__lifecycle__recovery_action_support` -- :need:`feat_req__lifecycle__recov_run_target_switch` - Overview ======== @@ -110,7 +97,7 @@ native applications can participate in the dependency management system. Reporting App 2 depends on Reporting App 1, Reporting App 1 has a ready condition of being in state running. - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 @@ -129,7 +116,7 @@ native applications can participate in the dependency management system. * - 006 - Reporting App 1 does its internal initialization. * - 007 - - Reporting App 1 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + - Reporting App 1 signals to the Launch Manager that it has finished initialization. * - 008 - Launch Manager analyzes the current state of the system. * - 009 @@ -143,7 +130,7 @@ native applications can participate in the dependency management system. * - 013 - Reporting App 2 does its internal initialization. * - 014 - - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + - Reporting App 2 signals to the Launch Manager that it has finished initialization. * - 015 - Launch Manager analyzes the current state of the system. * - 016 @@ -165,7 +152,7 @@ native applications can participate in the dependency management system. :scale: 50 :align: center - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 @@ -174,7 +161,7 @@ native applications can participate in the dependency management system. * - 001 - Launch Manager analyzes the current state of the system. * - 002 - - Launch Manager determines the transition plan for switching the run target. In this case all components are to be terminated. + - Launch Manager determines the transition plan for switching the run target. In this case all components can be terminated in parallel. * - 003 - Launch Manager sends SIGTERM to the well behaving application. * - 004 @@ -207,7 +194,7 @@ native applications can participate in the dependency management system. Configuration: Reporting App 2 depends on the termination of Reporting App 1. - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 @@ -216,35 +203,27 @@ native applications can participate in the dependency management system. * - 001 - Launch Manager analyzes the current state of the system. * - 002 - - Launch Manager determines the transition plan. In this case Reporting App 1 can be started, Reporting App 2 needs to wait for Reporting App 1 to terminate. + - Launch Manager determines the transition plan. In this case Reporting App 1 needs to be terminated before Reporting App 2 can be started. * - 003 - - Launch Manager starts Reporting App 1. + - Launch Manager sends SIGTERM to Reporting App 1. * - 004 - - Reporting App 1 is started. + - Reporting App 1 terminates through the operating system. * - 005 - - Launch Manager waits for the ready condition of Reporting App 1. - * - 006 - - Reporting App 1 does its internal initialization. - * - 007 - - Reporting App 1 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. - * - 008 - - At some point Reporting App 1 terminates. - * - 009 - The operating system reports the termination of Reporting App 1 to the Launch Manager. - * - 010 + * - 006 - Launch Manager analyzes the current state of the system. - * - 011 + * - 007 - Launch Manager determines the transition plan. In this case Reporting App 2 can be started. - * - 012 + * - 008 - Launch Manager starts Reporting App 2. - * - 013 + * - 009 - Reporting App 2 is started. - * - 014 + * - 010 - Launch Manager waits for the ready condition of Reporting App 2. - * - 015 + * - 011 - Reporting App 2 does its internal initialization. - * - 016 - - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + * - 012 + - Reporting App 2 signals to the Launch Manager that it has finished initialization. .. feat_arc_dyn:: Launch Manager - Run Components in Parallel @@ -265,7 +244,7 @@ native applications can participate in the dependency management system. Configuration: Reporting App 1 and Reporting App 2 can be started independently. - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 @@ -286,11 +265,11 @@ native applications can participate in the dependency management system. * - 007 - Reporting App 1 does its internal initialization. * - 008 - - Reporting App 1 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + - Reporting App 1 signals to the Launch Manager that it has finished initialization. * - 009 - Reporting App 2 does its internal initialization. * - 010 - - Reporting App 2 signals to the Launch Manager that it has reached the ready condition using the Lifecycle API. + - Reporting App 2 signals to the Launch Manager that it has finished initialization. .. feat_arc_dyn:: Launch Manager - Crash Recovery @@ -308,7 +287,7 @@ native applications can participate in the dependency management system. :scale: 50 :align: center - .. list-table:: Sequence diagram Description + .. list-table:: :widths: 10 90 :header-rows: 1 @@ -323,7 +302,7 @@ native applications can participate in the dependency management system. * - 004 - Launch Manager analyzes the current state of the system. * - 005 - - Launch Manager determines the transition plan.\nIn this case a recovery action needs to be run,\nand the recovery action is to switch to a different Run Target. + - Launch Manager determines the transition plan.In this case a recovery action needs to be run, and the recovery action is to switch to a different Run Target. * - 006 - Launch Manager switches to the configured fallback Run Target. diff --git a/docs/features/lifecycle/architecture/launch_manager_configuration.rst b/docs/features/lifecycle/architecture/launch_manager_configuration.rst deleted file mode 100644 index 0a9b10e1e9..0000000000 --- a/docs/features/lifecycle/architecture/launch_manager_configuration.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 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 - # ******************************************************************************* - -Launch Manager Configuration -############################ - -The :term:`Launch Manager` supports a set of configuration parameters, which -are grouped in the following categories: - -Component Configuration Parameters -================================== - -These parameters specify the arguments needed for spawning a process. - -- :need:`comp_req__launch_man__uid_gid_support` -- :need:`comp_req__launch_man__supplementary_groups` -- :need:`comp_req__launch_man__runmask_support` -- :need:`comp_req__launch_man__launch_priority_support` -- :need:`comp_req__launch_man__cwd_support` -- :need:`comp_req__launch_man__process_launch_args` -- :need:`comp_req__launch_man__std_handle_redir` -- :need:`comp_req__launch_man__aslr_support` -- :need:`comp_req__launch_man__process_rlimit_support` -- :need:`comp_req__launch_man__support_secpol_type` - -Dependency parameters -===================== - -These parameters specify how the components depend on each other. - -Recovery parameters -=================== - -These parameters specify the recovery actions for a component, when it fails. - -Alive monitoring parameters -=========================== - -These parameters specify the alive monitoring rules for the application. - -Requirements related to the external monitoring -=============================================== - -These parameters specify how the :term:`Launch Manager` itself is monitored. - -- :need:`feat_req__lifecycle__lm_self_health_check` - - -Static Architecture -=================== - -.. logic_arc_int:: Configuration parameters static architecture - :id: logic_arc_int__lifecycle__cfg_params_static - :security: YES - :safety: ASIL_B - :status: valid - :version: 1 - :fulfils: feat_req__lifecycle__component_group_config[version==1], - feat_req__lifecycle__config_file_support[version==1], - feat_req__lifecycle__run_target_support[version==1] - - .. uml:: _assets/config_params_static.puml - :scale: 50 - :align: center diff --git a/docs/features/lifecycle/architecture/lifecycle_client.rst b/docs/features/lifecycle/architecture/lifecycle_client.rst index a484645491..3929b0fec0 100644 --- a/docs/features/lifecycle/architecture/lifecycle_client.rst +++ b/docs/features/lifecycle/architecture/lifecycle_client.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + Lifecycle Client ################ diff --git a/score/launch_manager/docs/architecture/component_architecture.rst b/score/launch_manager/docs/architecture/component_architecture.rst index 1e5dae1705..b545d94210 100644 --- a/score/launch_manager/docs/architecture/component_architecture.rst +++ b/score/launch_manager/docs/architecture/component_architecture.rst @@ -36,13 +36,12 @@ Overview logic_arc_int__lifecycle__alive_if[version==1], logic_arc_int__lifecycle__lifecycle_if[version==1] :uses: logic_arc_int__log_cpp__logging[version==1], - logic_arc_int__baselibs__json[version==1], logic_arc_int__os__unistd[version==1] :security: NO :belongs_to: feat__lifecycle[version==1] The :term:`Launch Manager` is a component that provides a framework for - managing the lifecycle of processes in the S-CORE platform. + managing the lifecycle of any processes in the S-CORE platform. It allows for launching, monitoring, and controlling processes based on defined configurations and requirements. As such, it is a central part of the lifecycle management in S-CORE and From 5824e6cd8da345851d880105585d25777696a69e Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Mon, 14 Sep 2026 13:23:10 +0100 Subject: [PATCH 6/6] Moving some lifecycle docs to launch manager --- .../lifecycle/architecture/launch_manager.rst | 54 +++++++++++++++ .../architecture/lifecycle_client.rst | 68 +------------------ 2 files changed, 55 insertions(+), 67 deletions(-) diff --git a/docs/features/lifecycle/architecture/launch_manager.rst b/docs/features/lifecycle/architecture/launch_manager.rst index 55def046d7..00f70c9b61 100644 --- a/docs/features/lifecycle/architecture/launch_manager.rst +++ b/docs/features/lifecycle/architecture/launch_manager.rst @@ -77,6 +77,60 @@ This dual approach ensures that both modern SCORE-aware applications and legacy native applications can participate in the dependency management system. +Interacting with processes +-------------------------- + +The :term:`Launch Manager` provides interfaces for communication with launched +applications, supporting two distinct application types: + +1. **SCORE Applications**: Implement the full Lifecycle Interface for + bidirectional communication with state reporting, liveliness indication, and + conditional signaling +2. **Native Applications**: Controlled exclusively via POSIX signals (SIGTERM, + SIGKILL, etc.) without direct API communication + +This dual approach enables the :term:`Launch Manager` to manage both legacy +native applications and SCORE-aware applications within the same system. + +The Lifecycle Interface serves as the communication channel between +applications and the :term:`Launch Manager`. + +SCORE Applications +^^^^^^^^^^^^^^^^^^ + +**For SCORE Applications:** +- Application state reporting (started, running, stopped) +- Conditional signaling for application dependencies + +See :doc:`./lifecycle_client` for the full description of the Lifecycle Interface. + +Native Applications +^^^^^^^^^^^^^^^^^^^ + +Native applications that do not implement the Lifecycle Interface are +controlled through POSIX signals: + +- **SIGTERM**: Graceful shutdown request +- **SIGKILL**: Forced termination (after timeout) + +The :term:`Launch Manager` monitors native applications through: + +- Process ID (PID) tracking +- Exit code evaluation +- Resource usage monitoring via OS facilities +- Timeout-based failure detection + +For native applications, the :term:`Launch Manager` provides: + +- Basic lifecycle control (start/stop) +- Simple dependency management based on process existence +- Configurable startup/shutdown timeouts +- Exit code-based success/failure determination + + +Dynamic Architecture +==================== + .. feat_arc_dyn:: Launch Manager - Components Depends on Each Other :id: feat_arc_dyn__lifecycle__lcm_start :security: YES diff --git a/docs/features/lifecycle/architecture/lifecycle_client.rst b/docs/features/lifecycle/architecture/lifecycle_client.rst index 3929b0fec0..7a8c27de51 100644 --- a/docs/features/lifecycle/architecture/lifecycle_client.rst +++ b/docs/features/lifecycle/architecture/lifecycle_client.rst @@ -17,33 +17,6 @@ Lifecycle Client ################ -The :term:`Launch Manager` provides interfaces for communication with launched -applications, supporting two distinct application types: - -1. **SCORE Applications**: Implement the full Lifecycle Interface for - bidirectional communication with state reporting, liveliness indication, and - conditional signaling -2. **Native Applications**: Controlled exclusively via POSIX signals (SIGTERM, - SIGKILL, etc.) without direct API communication - -This dual approach enables the :term:`Launch Manager` to manage both legacy -native applications and SCORE-aware applications within the same system. - -The Lifecycle Interface serves as the communication channel between -applications and the :term:`Launch Manager`: - -**For SCORE Applications:** -- Application state reporting (started, running, stopped) -- Conditional signaling for application dependencies - -**For Native Applications:** -- Process lifecycle control via POSIX signals -- Basic process monitoring (PID-based status checking) -- Exit code evaluation for failure detection - -Interface -========= - The lifecycle interface is defined here: :need:`logic_arc_int__lifecycle__lifecycle_if` @@ -53,12 +26,7 @@ different capabilities depending on the application type. **SCORE Application State Communication** SCORE applications implementing the Lifecycle Interface can communicate their -internal state to the :term:`Launch Manager`. The state information includes: - -- **Started**: Application has successfully initialized and is ready to operate -- **Running**: Application is actively executing its main functionality -- **Stopped**: Application has terminated or is in the process of shutting down - +internal state to the :term:`Launch Manager`. The :term:`Launch Manager` uses this state information for: - Dependency resolution for other applications @@ -66,40 +34,6 @@ The :term:`Launch Manager` uses this state information for: - Status reporting to external state managers via the Control Interface -**SCORE Application Conditional Signaling** - -SCORE applications can signal custom conditions to the :term:`Launch Manager` -via the Alive Interface. This enables: - -- Complex dependency management beyond simple process startup -- Coordination between interdependent applications - -Custom conditions can be used by other applications as launch dependencies, -allowing for sophisticated startup orchestration. - -**Native Application Control** - -Native applications that do not implement the Lifecycle Interface are -controlled through POSIX signals: - -- **SIGTERM**: Graceful shutdown request -- **SIGKILL**: Forced termination (after timeout) - -The :term:`Launch Manager` monitors native applications through: - -- Process ID (PID) tracking -- Exit code evaluation -- Resource usage monitoring via OS facilities -- Timeout-based failure detection - -For native applications, the :term:`Launch Manager` provides: - -- Basic lifecycle control (start/stop) -- Simple dependency management based on process existence -- Configurable startup/shutdown timeouts -- Exit code-based success/failure determination - - Dynamic Architecture ====================