From ce15a2e63d12e22306f20c0f0d801c7736ce54d2 Mon Sep 17 00:00:00 2001 From: lgesdv Date: Fri, 13 Feb 2026 18:36:09 +0530 Subject: [PATCH 1/9] vso: create initial draft feature request [#2597] --- .../features/vso/_assets/VSO_architecture.png | Bin 0 -> 56900 bytes docs/features/vso/index.rst | 436 ++++++++++++++++++ docs/features/vso/requirements/index.rst | 99 ++++ docs/requirements/stakeholder/index.rst | 102 +++- 4 files changed, 635 insertions(+), 2 deletions(-) create mode 100644 docs/features/vso/_assets/VSO_architecture.png create mode 100644 docs/features/vso/index.rst create mode 100644 docs/features/vso/requirements/index.rst diff --git a/docs/features/vso/_assets/VSO_architecture.png b/docs/features/vso/_assets/VSO_architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..b0ec8bad6ab813e23dcbf2cf11699d2aeb8863a5 GIT binary patch literal 56900 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%0D5IIjHN# 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 WH#m7LEt>`WJ8E{q^qH}H+`j=VRE|gh literal 0 HcmV?d00001 diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst new file mode 100644 index 00000000000..e563c3dd72a --- /dev/null +++ b/docs/features/vso/index.rst @@ -0,0 +1,436 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +.. _vso_feature: + +Vehicle Service Orchestrator +############################# + +.. document:: Vehicle Service Orchestrator + :id: doc__vso + :status: draft + :safety: ASIL-B + :tags: feature_request + + +.. toctree:: + :maxdepth: 1 + :glob: + :titlesonly: + :hidden: + + requirements/index + +Feature flag +============ + +To activate this feature, use the following feature flag: + +``experimental_vehicle_service_orchestrator`` + + +Abstract +======== + +We propose adding a vehicle-specialized orchestration framework that adapts cloud-native container technologies to the in-vehicle environment. +The Vehicle Service Orchestrator (VSO) extends cloud-native orchestration with vehicle-specific capabilities, +enabling applications developed in the cloud to be deployed to the vehicle without modification. +It supports explicit resource management for mixed-criticality workloads and provides execution guarantees and automatic recovery for safety-critical applications. + +The term "Vehicle Service Orchestrator" reflects the orchestrator's role in managing services under the unique operational conditions of a vehicle, +rather than simply adapting a cloud-native orchestrator. +Unlike traditional container orchestrators designed for scalable datacenter environments, +a vehicle-specific orchestrator must account for constrained compute budgets, +strict isolation between workloads of differing criticality, +and continuous operation under varying driving conditions. +The name emphasizes that its primary purpose is to coordinate and safeguard in-vehicle services in a manner appropriate for automotive constraints, +bridging cloud-native development models with the operational realities of the vehicle environment. + +The intent of this feature request is to define a high-level architecture for the Vehicle Service Orchestrator. +The components listed throughout this document may require detailed feature requests in the future respectively. + + +Motivation +========== + +1. Complexity and Platform Dependency in Vehicle Software Deployment +--------------------------------------------------------------------- + +Current vehicle software deployment faces significant constraints due to complex multi-stage validation processes, +platform-specific customized builds, and limited update mechanisms. +In a typical deployment scenario, any modification to an application requires repeated validation across the development, testing, and vehicle environments, +and each validation stage must faithfully reproduce the same execution environment. +Integration issues frequently occur due to environment inconsistencies, +and model-specific builds are unavoidable because each vehicle ECU uses different hardware architectures (x86, ARM, RISC-V) +and different OS conditions (Linux distributions, kernel versions, library dependencies). + +During OTA updates, a full system reboot is often required, rollback capabilities are limited, and recovering from update failures is challenging. +Version management also becomes unnecessarily complex. +To address these challenges, vehicle-optimized orchestration technology is required—one that enables "build once, run anywhere" through container-based deployment, +defines deployment state with a declarative Manifest, and supports automated rollout and rollback. +A lightweight solution that accounts for limited in-vehicle resources and real-time constraints is essential. + +2. Application Behavior in Mixed-Criticality Domains +----------------------------------------------------- + +Vehicle software is composed of applications with variant execution requirements depending on their safety level. +For example, an ASIL-D Automatic Emergency Braking (AEB) system requires strict timing guarantees, +while a QM-level infotainment system can tolerate delays. +This mixed-critical structure also applies when distributing workloads across high-performance and low-performance ECUs. + +Expected issues in this execution model include resource contention and inappropriate node placement between critical and non-critical applications. +For instance, an infotainment application consuming excessive CPU resources could delay object detection in AEB or increase braking response time—posing a significant safety risk. + +To address these challenges, ASIL-D applications must be allocated dedicated CPU cores and memory, while QM applications should share resources. +Furthermore, dynamic resource reallocation is necessary to ensure the execution guarantees and timing requirements of safety-critical functions when driving conditions change (e.g., urban → highway). +Since standard cloud-native orchestration does not inherently understand ASIL concepts or guarantee prioritization for safety-critical workloads, +a vehicle-optimized orchestrator is required. + + +Rationale +========= + +1. Selection of a Cloud-Native Orchestration Foundation +-------------------------------------------------------- + +This feature is built upon cloud-native orchestration technologies that have already been validated at scale in cloud environments. +Container orchestration systems proven in the cloud provide core capabilities such as declarative deployment, automatic recovery, and rolling updates, +all of which can be directly applied to address the complexity and platform dependency issues found in vehicle software deployment. +By optimizing these proven cloud technologies for the in-vehicle environment, development time can be reduced while improving overall system reliability. + +2. Extension Architecture for Vehicle-Specific Capabilities +------------------------------------------------------------ + +The reason we adopted an extension architecture—adding vehicle-specific capabilities instead of using the existing cloud-native orchestrator as-is—is +the fundamental difference between vehicle and cloud environments. +Cloud systems assume virtually infinite scalability, persistent network connectivity, and 99.9% availability, +whereas vehicles operate under constrained resources, intermittent connectivity, 99.9999% availability requirements, and stringent real-time constraints. +In particular, mixed-criticality management based on ASIL levels is a requirement unique to automotive systems and does not exist in cloud environments. +Therefore, while the base orchestration features are reused, extensions such as mixed-criticality awareness, real-time scheduling, +and vehicle-specific health checks are added. + +3. Declarative Manifest-Based Configuration +-------------------------------------------- + +Defining ASIL levels, resource allocations, and dependencies through a declarative Manifest separates the responsibilities of developers and integrators +while reducing deployment complexity. +In traditional workflows, developers must manually manage platform-specific build scripts, environment variables, and resource settings, +requiring repetitive adjustments whenever the vehicle model or ECU changes. +With a declarative Manifest, developers specify what to deploy, while the orchestrator determines how to deploy it. +This allows developers to focus on application logic while integrators adjust only the Manifest to support diverse vehicle environments. + +4. Portability Without Application Code Changes +------------------------------------------------ + +The decision to allow cloud-developed applications to be deployed to vehicles without modifying their code is driven by the need for development productivity and ecosystem utilization. +Previously, porting a cloud application to a vehicle required manual adjustments to platform-specific library dependencies, environment variables, +and network configurations—introducing delays and increasing the likelihood of errors. +Container-based deployment encapsulates the application and all of its dependencies into an image, ensuring a consistent execution environment across cloud and vehicle platforms. +The orchestrator abstracts environment-specific differences such as networking, storage, and security. +This enables immediate reuse of cloud-validated applications and frameworks (e.g., AI inference engines, data processing pipelines) within the vehicle +while significantly reducing integration overhead through consistent cloud-to-vehicle development environments. + +5. Container-Based Isolation and Resource Management +----------------------------------------------------- + +Managing all applications—including the Executor—within containers ensures explicit resource management and consistent runtime environments. +Previously, the Executor existed as a Rust package with implicit and manually maintained resource allocation, +which risked violating FEO guarantees when additional applications were introduced. +Through container isolation, each Executor can be explicitly assigned dedicated CPU cores, memory, and GPU resources. +cgroup and namespace isolation prevents interference from other workloads. +Additionally, container images enable "build once, run anywhere," providing platform independence across heterogeneous hardware architectures such as x86, ARM, and RISC-V. + +6. Real-Time Monitoring and Automatic Recovery Mechanisms +---------------------------------------------------------- + +The design choice to support real-time monitoring and automated recovery of resource usage, timing metrics, and health status is essential +due to the safety requirements and operational complexity of vehicle environments. +Previously, when the Executor crashed or timing constraints were violated, issues were only logged and required manual investigation and restart, +with little visibility into root causes. +In vehicular systems, interruptions to safety-critical functions can directly affect human life, making millisecond-level fault detection and recovery indispensable. +Periodic health checks via a Liveness Probe, timing-constraint validation using a Timing Probe, and immediate restart policies upon failure ensure +continuity of critical functions without human intervention. +Collecting metrics such as CPU and memory usage, per-task execution time, and timing violation counts enables both post-incident analysis and proactive prevention. + + +Specification +============= + +Overview +-------- + +A Vehicle Service Orchestrator is a structured and declarative framework for managing the execution flow, timing constraints, and error handling of containers. +Developers can define application control flows and resource-management policies in a platform-independent manner, +while the orchestration automates container deployment, execution guarantees, and dynamic resource allocation. +This clearly separates application logic from infrastructure management, enabling stable and vehicle-optimized operation. + + +System Architecture +------------------- + +The system follows a three-layer architecture specialized for in-vehicle environments: +- **API Layer:** API Server Allows the user to configure(add/remove) the Manifest +- **Orchestration Layer:** vehicleData FilterGateway, ActionController and StateManager coordinate workloads +- **Agent Layer:** NodeAgent handles execution on each node +- **Runtime Layer:** Container engine performs actual container operations + +.. image:: _assets/vso-architecture.svg + :alt: Vehicle Service Orchestrator Architecture + +Core Components +^^^^^^^^^^^^^^^ + +**APIServer + Interfaces with user to add or remove the manifest(scenarios) + +**Vehicle Data Filtergatewy + Services are automatically controlled based on changes in vehicle state. + +**ActionController** + Scenario-based workload control and real-time scheduling + +**StateManager** + Tracking container lifecycle and managing state transitions + +**NodeAgent** + Container execution and resource management per node + + +Workload Lifecycle Management +------------------------------ + +Standard Command Set +^^^^^^^^^^^^^^^^^^^^ + +Seven essential workload commands are supported: + +- ``create`` +- ``start`` +- ``pause`` +- ``resume`` +- ``stop`` +- ``restart`` +- ``delete`` + +All commands are delivered via remote procedure calls and follow a standardized response format. + +Container State Model +^^^^^^^^^^^^^^^^^^^^^^ + +Containers are managed across five main states: + +- **Created:** Image ready for execution +- **Running:** Active execution +- **Paused:** Memory preserved, execution suspended +- **Exited:** Normal or error termination +- **Restarting:** Automatic recovery in progress + +Transitions between these states follow strict rules enforced by the StateManager. + + +Scenario-Based Automation +-------------------------- + +Conditional Execution Engine +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Services are automatically controlled based on changes in vehicle state. +Scenario information is retrieved from a distributed key-value store, and corresponding actions are executed automatically when conditions are met. +Integration with real-time data streams ensures immediate responsiveness. + + +Resource Management and Isolation +---------------------------------- + +Container Security Isolation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +User identifiers, group permissions, and Linux capabilities are strictly controlled according to the principle of least privilege. +Restricting privileged mode and applying security contexts strengthens system-level protection. + +Performance Optimization +^^^^^^^^^^^^^^^^^^^^^^^^ + +Processor and memory usage are tracked in real time, allowing early detection of resource shortages. +Parallel container creation, asynchronous processing, and automatic scaling optimize startup times and maximize efficiency. + + +Monitoring and Recovery +------------------------ + +State Monitoring +^^^^^^^^^^^^^^^^ + +Comprehensive health checks continuously monitor: + +- Process status +- Port connectivity +- Application-level health (Liveness Probe) +- Timing constraints (Timing Probe) + process status, port connectivity, and application-level health.Failure recovery is automated according to restart policies. +Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. +Customized recovery logic is applied depending on the error type. + + +Requirements +------------ + +The related requirements can be found in :doc:`requirements/index`. + + +Backwards Compatibility +======================= + +This feature is designed as an optional extension module that does not modify the existing S-CORE architecture. +No changes are required to the current Executors (FEO, Lifecycle, Orchestration) or to application logic. +Container-based deployment and resource-management features are applied only to services that require them, +while existing process-based workloads remain fully preserved. + +The Manifest operates as an additional configuration layer that can be used alongside the existing Launch mechanism rather than replacing it. +The image-delivery pipeline, data formats, and OS initialization procedures (Linux/QNX) remain unchanged. +Furthermore, safety and security features complement—rather than replace—current mechanisms, +ensuring full backward compatibility for the entire platform and all existing applications. + + +Security Impact +=============== + +The introduction of a Vehicle Service Orchestrator has security implications due to its system-level capabilities and distributed nature. +The orchestrator manages container lifecycle, resource allocation, and network access—all of which pose risks if accessed by unauthorized actors. + +Container isolation provides security boundaries, but misconfigured containers or privileged containers could expose the host system. +Remote procedure calls between orchestration components introduce network attack surfaces that must be secured with mutual TLS and authentication. +The distributed key-value store used for configuration must be protected against unauthorized modification. + +To mitigate these risks, the Vehicle Service Orchestrator shall: + +- Enforce the principle of least privilege for all containers +- Restrict privileged mode and dangerous Linux capabilities +- Implement mutual TLS authentication for all inter-component communication +- Apply security contexts (SELinux, AppArmor) to containers +- Validate and sanitize all Manifest inputs +- Audit all orchestrator operations for security monitoring + +Since the orchestrator manages both QM and ASIL workloads, a security breach must not violate safety guarantees. +Resource isolation mechanisms (cgroups, namespaces) must be robust enough to prevent QM workload compromises from affecting ASIL workloads. +The orchestrator components themselves must be developed with safety-appropriate quality standards to provide FFI (Freedom From Interference) guarantees. + + +Safety Impact +============= + +The Vehicle Service Orchestrator is classified as **ASIL-B** due to its role in managing safety-critical workloads. + +While the orchestrator does not directly implement safety functions (e.g., braking, steering), +it provides the runtime environment and resource guarantees necessary for safety-critical applications to meet their timing and reliability requirements. +A failure in the orchestrator's resource allocation, timing enforcement, or automatic recovery mechanisms could indirectly impact safety by: + +- Causing timing violations in ASIL-D applications (e.g., delayed object detection in AEB) +- Allowing resource contention between QM and ASIL workloads +- Failing to restart safety-critical containers after crashes + +To address these risks: + +- ASIL-level workloads are allocated dedicated, isolated resources +- Timing constraints are continuously validated with millisecond-level precision +- Automatic recovery mechanisms ensure continuity of critical functions +- The orchestrator enforces FFI (Freedom From Interference) between criticality levels +- Health checks and monitoring detect failures immediately + +The core orchestrator components (ActionController, StateManager, NodeAgent) must be developed according to ASIL-B quality standards. +Safety analysis (FMEA, DFA) will be conducted to identify and mitigate potential failure modes. + + +License Impact +============== + +The Vehicle Service Orchestrator is built upon open-source container technologies. +The base container runtime and orchestration concepts are freely available under permissive licenses (Apache 2.0, MIT). + +However, specific implementation choices may introduce license considerations: + +- Container runtime engines (e.g., containerd, runc) are typically Apache 2.0 licensed +- Kubernetes components (if used as a base) are Apache 2.0 licensed +- Linux kernel features (cgroups, namespaces) are GPL but do not affect userspace licensing +- Automotive-specific extensions will be developed as S-CORE components under Apache 2.0 + +No license restrictions prevent the implementation of an open-source Vehicle Service Orchestrator at this time. + + +How to Teach This +================= + +For developers familiar with cloud-native technologies (Kubernetes, Docker), the Vehicle Service Orchestrator will feel familiar +with automotive-specific extensions for ASIL levels and real-time constraints. + +For automotive engineers unfamiliar with containers, the following learning path is recommended: + +1. **Container Basics:** Understand container images, isolation, and resource management +2. **Declarative Configuration:** Learn Manifest-based deployment vs. imperative scripting +3. **Mixed-Criticality Concepts:** Understand ASIL-based resource allocation and FFI +4. **Orchestration Patterns:** Learn automatic recovery, health checks, and state management +5. **Vehicle-Specific Adaptations:** Understand timing probes, scenario-based automation, and constrained resource management + +Reference implementations, tutorials, and example Manifests will be provided to accelerate onboarding. + + +Rejected Ideas +============== + +Process-Based Orchestration Without Containers +----------------------------------------------- + +Managing workloads as native processes without container isolation was considered but rejected. +Containers provide explicit resource boundaries, consistent runtime environments, and platform portability that are difficult to achieve with bare processes. +The "build once, run anywhere" benefit of containers significantly outweighs the overhead of container runtime. + +Full Kubernetes Deployment +--------------------------- + +Deploying unmodified Kubernetes as the vehicle orchestrator was considered but rejected. +Kubernetes assumes datacenter-scale resources, persistent network connectivity, and does not understand automotive safety concepts (ASIL levels, timing constraints). +The resource overhead and complexity of Kubernetes are inappropriate for constrained vehicle environments. +An automotive-optimized orchestrator provides better resource efficiency and safety integration. + +Static Configuration Without Scenario-Based Automation +------------------------------------------------------- + +Using static configuration files without dynamic scenario-based automation was considered but rejected. +Vehicles operate in highly dynamic environments (urban vs. highway, parking vs. driving) that require runtime adaptation. +Static configuration cannot optimize resource allocation or workload placement based on driving conditions. +Scenario-based automation is essential for efficient mixed-criticality management. + + +Open Issues +=========== + +- Define detailed Manifest schema and validation rules +- Specify distributed key-value store selection and configuration +- Determine container runtime selection (containerd vs. alternatives) +- Define metrics collection format and integration with S-CORE monitoring +- Specify integration points with existing S-CORE Lifecycle Management +- Determine OTA update flow for containerized workloads +- Define certification and qualification strategy for ASIL-B components +- Specify testing strategy for mixed-criticality scenarios +- Determine multi-ECU orchestration and cross-node communication patterns +- Define failure mode analysis and safety case structure +- Specify resource reservation strategy for different driving scenarios +- Determine integration with S-CORE::COM for inter-container communication + + +Footnotes +========= + +.. [#v1] "Kubernetes Documentation", Kubernetes, https://kubernetes.io/docs/. +.. [#v2] "ISO 26262 Road vehicles — Functional safety", ISO, https://www.iso.org/standard/68383.html. +.. [#v3] "OCI Runtime Specification", Open Container Initiative, https://github.com/opencontainers/runtime-spec. diff --git a/docs/features/vso/requirements/index.rst b/docs/features/vso/requirements/index.rst new file mode 100644 index 00000000000..28c06776e4d --- /dev/null +++ b/docs/features/vso/requirements/index.rst @@ -0,0 +1,99 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +.. _vso_requirements: + +Requirements +############ + +Workload Lifecycle Management +============================== + +.. feat_req:: Standard Container Command Set + :id: feat_req__vso__standard_commands + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__vso__workload_control + :status: valid + + The orchestrator shall support seven essential workload commands: create, start, pause, resume, stop, restart, and delete. All commands shall be delivered via remote procedure calls and follow a standardized response format. + +.. feat_req:: Container State Model + :id: feat_req__vso__state_model + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__vso__workload_control + :status: valid + + The system shall manage containers across five main states: Created, Running, Paused, Exited, and Restarting. State transitions shall follow strict rules and be tracked by the StateManager component. + +Scenario-Based Automation +========================== + +.. feat_req:: Conditional Execution Engine + :id: feat_req__vso__conditional_execution + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__vso__vehicle_state_awareness + :status: valid + + The orchestrator shall automatically control services based on changes in vehicle state. Scenario information shall be retrieved from a distributed key-value store, and corresponding actions shall be executed automatically when conditions are met. + +Resource Management and Isolation +================================== + +.. feat_req:: Container Security Isolation + :id: feat_req__vso__security_isolation + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__dependability__security_features,stkh_req__vso__security_isolation + :status: valid + + User identifiers, group permissions, and Linux capabilities are strictly controlled according to the principle of least privilege. Restricting privileged mode and applying security contexts strengthens system-level protection. + +.. feat_req:: Performance Optimization + :id: feat_req__vso__perf_optimization + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__vso__resource_guarantees + :status: valid + + Processor and memory usage are tracked in real time, allowing early detection of resource shortages. Parallel container creation, asynchronous processing, and automatic scaling optimize startup times and maximize efficiency. + +Monitoring and Recovery +======================== + +.. feat_req:: State Monitoring + :id: feat_req__vso__state_monitoring + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__dependability__automotive_safety,stkh_req__vso__failure_detection + :status: valid + + Comprehensive health checks continuously monitor process status, port connectivity, and application-level health. Changes in status are detected immediately, ensuring consistency across the entire system. + +.. feat_req:: Automatic Recovery Mechanisms + :id: feat_req__vso__auto_recovery + :reqtype: Functional + :security: YES + :safety: ASIL-B + :satisfies: stkh_req__dependability__automotive_safety,stkh_req__vso__fault_tolerance + :status: valid + + Failure recovery is automated according to restart policies. Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. Customized recovery logic is applied depending on the error type. diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index 52eebb53bec..86435646897 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -78,13 +78,13 @@ Overall goals -Functional requirements +Functional requirementshttps://github.com/eclipse-score/score.git ----------------------- .. stkh_req:: File Based Configuration :id: stkh_req__functional_req__file_based :reqtype: Functional - :security: NO + :security: NOhttps://github.com/eclipse-score/score.git :safety: QM :rationale: File based configuration allows changes without rebuilding the software. :status: valid @@ -956,6 +956,104 @@ Diagnostics and Fault Management The SW-platform shall enforce secure access control for all diagnostic interfaces, including authentication, encryption, and role-based access enforcement. +Vehicle Service Orchestrator +----------------------------- +VSO Workload Management +----------------------- + +.. stkh_req:: Container Lifecycle Management + :id: stkh_req__vso__workload_control + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Provide standardized workload control mechanisms consistent with cloud-native practices while meeting automotive reliability requirements. + :status: valid + + The platform shall provide standardized lifecycle management for containerized workloads, + including creation, startup, pause, resume, stop, restart, and deletion operations. + +.. stkh_req:: Vehicle State-Aware Orchestration + :id: stkh_req__vso__vehicle_state_awareness + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Enable dynamic workload management based on driving conditions to optimize resource utilization and ensure safety requirements are met. + :status: valid + + The platform shall support scenario-based workload orchestration that automatically adjusts application execution + based on vehicle state changes (e.g., driving mode, parking, charging). + + +VSO Mixed-Criticality Support +----------------------------- +.. stkh_req:: ASIL and QM Workload Coexistence + :id: stkh_req__vso__asil_qm_coexistence + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Enable safe coexistence of safety-critical and quality-managed applications on shared hardware while preventing interference. + :status: valid + +VSO Resource Management +----------------------- +.. stkh_req:: Workload Isolation + :id: stkh_req__vso__workload_isolation + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Prevent resource contention and timing violations between workloads of different criticality levels to maintain system safety. + :status: valid + + The platform shall enforce strict isolation between workloads using container-based mechanisms (cgroups, namespaces) + to prevent resource contention and timing interference across criticality boundaries. + + +VSO Security and Isolation +------------------------ +.. stkh_req:: Container Security Enforcement + :id: stkh_req__vso__security_isolation + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Protect the system from compromised or malicious containers through strict security controls and least-privilege enforcement. + :status: valid + + The platform shall enforce container security isolation through strict control of user identifiers, group permissions, + and Linux capabilities according to the principle of least privilegend maintain safety-critical functionality. + :status: valid + + The platform shall provide comprehensive health monitoring for all workloads, + including process status, application-level health checks, and resource utilization tracking. + +.. stkh_req:: Automatic Fault Recovery + :id: stkh_req__vso__fault_tolerance + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Maintain system availability and safety by automatically recovering from failures without human intervention. + :status: valid + + The platform shall provide automatic recovery mechanisms for failed workloads, + including configurable restart policies and state-based corrective actions to minimize operational downtime. + +.. stkh_req:: Timing Constraint Enforcement + :id: stkh_req__vso__timing_guarantees + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Ensure safety-critical applications meet their real-time timing requirements under all operating conditions. + :status: valid + + The platform shall validate and enforce timing constraints for safety-critical workloads, + detecting violations at millisecond-level precision and triggering immediate corrective actions. + +.. stkh_req:: System Observability + :id: stkh_req__vso__observability + :reqtype: Functional + :security: YES + :safety: ASIL-B + :rationale: Enable proactive problem detection and post-incident analysis through comprehensive system metrics + Hardware support ---------------- From 9a28b5b4fe7a61a51e11d6a626031870ec3e8f7b Mon Sep 17 00:00:00 2001 From: lgesdv Date: Fri, 13 Feb 2026 18:58:02 +0530 Subject: [PATCH 2/9] fix docascode issues[2597] --- docs/features/vso/requirements/index.rst | 14 +++++++------- docs/requirements/stakeholder/index.rst | 16 ++++++++-------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/features/vso/requirements/index.rst b/docs/features/vso/requirements/index.rst index 28c06776e4d..094c00ce6c9 100644 --- a/docs/features/vso/requirements/index.rst +++ b/docs/features/vso/requirements/index.rst @@ -23,7 +23,7 @@ Workload Lifecycle Management :id: feat_req__vso__standard_commands :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__vso__workload_control :status: valid @@ -33,7 +33,7 @@ Workload Lifecycle Management :id: feat_req__vso__state_model :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__vso__workload_control :status: valid @@ -46,7 +46,7 @@ Scenario-Based Automation :id: feat_req__vso__conditional_execution :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__vso__vehicle_state_awareness :status: valid @@ -59,7 +59,7 @@ Resource Management and Isolation :id: feat_req__vso__security_isolation :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__dependability__security_features,stkh_req__vso__security_isolation :status: valid @@ -69,7 +69,7 @@ Resource Management and Isolation :id: feat_req__vso__perf_optimization :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__vso__resource_guarantees :status: valid @@ -82,7 +82,7 @@ Monitoring and Recovery :id: feat_req__vso__state_monitoring :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__dependability__automotive_safety,stkh_req__vso__failure_detection :status: valid @@ -92,7 +92,7 @@ Monitoring and Recovery :id: feat_req__vso__auto_recovery :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :satisfies: stkh_req__dependability__automotive_safety,stkh_req__vso__fault_tolerance :status: valid diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index 86435646897..c59715387ac 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -965,7 +965,7 @@ VSO Workload Management :id: stkh_req__vso__workload_control :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Provide standardized workload control mechanisms consistent with cloud-native practices while meeting automotive reliability requirements. :status: valid @@ -976,7 +976,7 @@ VSO Workload Management :id: stkh_req__vso__vehicle_state_awareness :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Enable dynamic workload management based on driving conditions to optimize resource utilization and ensure safety requirements are met. :status: valid @@ -990,7 +990,7 @@ VSO Mixed-Criticality Support :id: stkh_req__vso__asil_qm_coexistence :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Enable safe coexistence of safety-critical and quality-managed applications on shared hardware while preventing interference. :status: valid @@ -1000,7 +1000,7 @@ VSO Resource Management :id: stkh_req__vso__workload_isolation :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Prevent resource contention and timing violations between workloads of different criticality levels to maintain system safety. :status: valid @@ -1014,7 +1014,7 @@ VSO Security and Isolation :id: stkh_req__vso__security_isolation :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Protect the system from compromised or malicious containers through strict security controls and least-privilege enforcement. :status: valid @@ -1029,7 +1029,7 @@ VSO Security and Isolation :id: stkh_req__vso__fault_tolerance :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Maintain system availability and safety by automatically recovering from failures without human intervention. :status: valid @@ -1040,7 +1040,7 @@ VSO Security and Isolation :id: stkh_req__vso__timing_guarantees :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Ensure safety-critical applications meet their real-time timing requirements under all operating conditions. :status: valid @@ -1051,7 +1051,7 @@ VSO Security and Isolation :id: stkh_req__vso__observability :reqtype: Functional :security: YES - :safety: ASIL-B + :safety: ASIL_B :rationale: Enable proactive problem detection and post-incident analysis through comprehensive system metrics Hardware support From 617315d2acbc36df2c4dc3235f265c51fff77780 Mon Sep 17 00:00:00 2001 From: lgesdv Date: Fri, 13 Feb 2026 19:25:49 +0530 Subject: [PATCH 3/9] fixed docsascode issues [#2597] --- docs/features/vso/index.rst | 47 ++++++++++++------------ docs/features/vso/requirements/index.rst | 4 +- docs/requirements/stakeholder/index.rst | 8 +++- 3 files changed, 32 insertions(+), 27 deletions(-) diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst index e563c3dd72a..4bf7e912bf2 100644 --- a/docs/features/vso/index.rst +++ b/docs/features/vso/index.rst @@ -19,9 +19,10 @@ Vehicle Service Orchestrator .. document:: Vehicle Service Orchestrator :id: doc__vso :status: draft - :safety: ASIL-B + :safety: ASIL_B + :security: YES :tags: feature_request - + :realizes: wp__feat_request .. toctree:: :maxdepth: 1 @@ -184,16 +185,15 @@ The system follows a three-layer architecture specialized for in-vehicle environ - **Agent Layer:** NodeAgent handles execution on each node - **Runtime Layer:** Container engine performs actual container operations -.. image:: _assets/vso-architecture.svg +.. image:: _assets/VSO_architecture.png :alt: Vehicle Service Orchestrator Architecture Core Components -^^^^^^^^^^^^^^^ - -**APIServer +--------------- +**APIServer** Interfaces with user to add or remove the manifest(scenarios) -**Vehicle Data Filtergatewy +**Vehicle Data Filtergateway** Services are automatically controlled based on changes in vehicle state. **ActionController** @@ -210,7 +210,7 @@ Workload Lifecycle Management ------------------------------ Standard Command Set -^^^^^^^^^^^^^^^^^^^^ +-------------------- Seven essential workload commands are supported: @@ -225,7 +225,7 @@ Seven essential workload commands are supported: All commands are delivered via remote procedure calls and follow a standardized response format. Container State Model -^^^^^^^^^^^^^^^^^^^^^^ +--------------------- Containers are managed across five main states: @@ -242,7 +242,7 @@ Scenario-Based Automation -------------------------- Conditional Execution Engine -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- Services are automatically controlled based on changes in vehicle state. Scenario information is retrieved from a distributed key-value store, and corresponding actions are executed automatically when conditions are met. @@ -253,13 +253,13 @@ Resource Management and Isolation ---------------------------------- Container Security Isolation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- User identifiers, group permissions, and Linux capabilities are strictly controlled according to the principle of least privilege. Restricting privileged mode and applying security contexts strengthens system-level protection. Performance Optimization -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ Processor and memory usage are tracked in real time, allowing early detection of resource shortages. Parallel container creation, asynchronous processing, and automatic scaling optimize startup times and maximize efficiency. @@ -269,7 +269,7 @@ Monitoring and Recovery ------------------------ State Monitoring -^^^^^^^^^^^^^^^^ +---------------- Comprehensive health checks continuously monitor: @@ -278,8 +278,8 @@ Comprehensive health checks continuously monitor: - Application-level health (Liveness Probe) - Timing constraints (Timing Probe) process status, port connectivity, and application-level health.Failure recovery is automated according to restart policies. -Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. -Customized recovery logic is applied depending on the error type. + Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. + Customized recovery logic is applied depending on the error type. Requirements @@ -329,7 +329,7 @@ The orchestrator components themselves must be developed with safety-appropriate Safety Impact ============= -The Vehicle Service Orchestrator is classified as **ASIL-B** due to its role in managing safety-critical workloads. +The Vehicle Service Orchestrator is classified as **ASIL_B** due to its role in managing safety-critical workloads. While the orchestrator does not directly implement safety functions (e.g., braking, steering), it provides the runtime environment and resource guarantees necessary for safety-critical applications to meet their timing and reliability requirements. @@ -347,7 +347,7 @@ To address these risks: - The orchestrator enforces FFI (Freedom From Interference) between criticality levels - Health checks and monitoring detect failures immediately -The core orchestrator components (ActionController, StateManager, NodeAgent) must be developed according to ASIL-B quality standards. +The core orchestrator components (ActionController, StateManager, NodeAgent) must be developed according to ASIL_B quality standards. Safety analysis (FMEA, DFA) will be conducted to identify and mitigate potential failure modes. @@ -377,7 +377,7 @@ For automotive engineers unfamiliar with containers, the following learning path 1. **Container Basics:** Understand container images, isolation, and resource management 2. **Declarative Configuration:** Learn Manifest-based deployment vs. imperative scripting -3. **Mixed-Criticality Concepts:** Understand ASIL-based resource allocation and FFI +3. **Mixed-Criticality Concepts:** Understand ASIL_Based resource allocation and FFI 4. **Orchestration Patterns:** Learn automatic recovery, health checks, and state management 5. **Vehicle-Specific Adaptations:** Understand timing probes, scenario-based automation, and constrained resource management @@ -420,7 +420,7 @@ Open Issues - Define metrics collection format and integration with S-CORE monitoring - Specify integration points with existing S-CORE Lifecycle Management - Determine OTA update flow for containerized workloads -- Define certification and qualification strategy for ASIL-B components +- Define certification and qualification strategy for ASIL_B components - Specify testing strategy for mixed-criticality scenarios - Determine multi-ECU orchestration and cross-node communication patterns - Define failure mode analysis and safety case structure @@ -430,7 +430,8 @@ Open Issues Footnotes ========= - -.. [#v1] "Kubernetes Documentation", Kubernetes, https://kubernetes.io/docs/. -.. [#v2] "ISO 26262 Road vehicles — Functional safety", ISO, https://www.iso.org/standard/68383.html. -.. [#v3] "OCI Runtime Specification", Open Container Initiative, https://github.com/opencontainers/runtime-spec. +# ******* +# .. [#v1] "Kubernetes Documentation", Kubernetes, https://kubernetes.io/docs/. +# .. [#v2] "ISO 26262 Road vehicles — Functional safety", ISO, https://www.iso.org/standard/68383.html. +# .. [#v3] "OCI Runtime Specification", Open Container Initiative, https://github.com/opencontainers/runtime-spec. +# ******** diff --git a/docs/features/vso/requirements/index.rst b/docs/features/vso/requirements/index.rst index 094c00ce6c9..79c3419be5b 100644 --- a/docs/features/vso/requirements/index.rst +++ b/docs/features/vso/requirements/index.rst @@ -70,7 +70,7 @@ Resource Management and Isolation :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__vso__resource_guarantees + :satisfies: stkh_req__dependability__security_features :status: valid Processor and memory usage are tracked in real time, allowing early detection of resource shortages. Parallel container creation, asynchronous processing, and automatic scaling optimize startup times and maximize efficiency. @@ -83,7 +83,7 @@ Monitoring and Recovery :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__dependability__automotive_safety,stkh_req__vso__failure_detection + :satisfies: stkh_req__dependability__automotive_safety :status: valid Comprehensive health checks continuously monitor process status, port connectivity, and application-level health. Changes in status are detected immediately, ensuring consistency across the entire system. diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index c59715387ac..b5dade7f7b4 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -78,7 +78,7 @@ Overall goals -Functional requirementshttps://github.com/eclipse-score/score.git +Functional requirements ----------------------- .. stkh_req:: File Based Configuration @@ -1009,7 +1009,7 @@ VSO Resource Management VSO Security and Isolation ------------------------- +-------------------------- .. stkh_req:: Container Security Enforcement :id: stkh_req__vso__security_isolation :reqtype: Functional @@ -1053,6 +1053,10 @@ VSO Security and Isolation :security: YES :safety: ASIL_B :rationale: Enable proactive problem detection and post-incident analysis through comprehensive system metrics + :status: valid + + The platform shall verify System Observability + Hardware support ---------------- From 276c26941e26d14d071fde97f11e7cf722295e71 Mon Sep 17 00:00:00 2001 From: lgesdv Date: Fri, 13 Feb 2026 19:31:40 +0530 Subject: [PATCH 4/9] fix doc issues [#2597] --- docs/features/vso/index.rst | 6 +++--- docs/requirements/stakeholder/index.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst index 4bf7e912bf2..ba802d32d2a 100644 --- a/docs/features/vso/index.rst +++ b/docs/features/vso/index.rst @@ -277,9 +277,9 @@ Comprehensive health checks continuously monitor: - Port connectivity - Application-level health (Liveness Probe) - Timing constraints (Timing Probe) - process status, port connectivity, and application-level health.Failure recovery is automated according to restart policies. - Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. - Customized recovery logic is applied depending on the error type. +process status, port connectivity, and application-level health.Failure recovery is automated according to restart policies. +Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. +Customized recovery logic is applied depending on the error type. Requirements diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index b5dade7f7b4..a8ede5ccaf3 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -84,7 +84,7 @@ Functional requirements .. stkh_req:: File Based Configuration :id: stkh_req__functional_req__file_based :reqtype: Functional - :security: NOhttps://github.com/eclipse-score/score.git + :security: NO :safety: QM :rationale: File based configuration allows changes without rebuilding the software. :status: valid From d74b71dfb95b42bda96c2244a2c91a2dd583d8be Mon Sep 17 00:00:00 2001 From: lgesdv Date: Fri, 13 Feb 2026 19:38:26 +0530 Subject: [PATCH 5/9] fixed docs issue[#2597] --- docs/features/vso/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst index ba802d32d2a..b043160fafc 100644 --- a/docs/features/vso/index.rst +++ b/docs/features/vso/index.rst @@ -277,6 +277,7 @@ Comprehensive health checks continuously monitor: - Port connectivity - Application-level health (Liveness Probe) - Timing constraints (Timing Probe) + process status, port connectivity, and application-level health.Failure recovery is automated according to restart policies. Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. Customized recovery logic is applied depending on the error type. From c944c1ac830c1ce967f4c4914c7c2219dc1827b3 Mon Sep 17 00:00:00 2001 From: basheerFZ <46041610+basheerFZ@users.noreply.github.com> Date: Thu, 12 Mar 2026 10:59:29 +0530 Subject: [PATCH 6/9] Update copyright notice formatting in index.rst Update copyright notice formatting in index.rst Signed-off-by: basheerFZ <46041610+basheerFZ@users.noreply.github.com> --- docs/features/vso/requirements/index.rst | 25 ++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/features/vso/requirements/index.rst b/docs/features/vso/requirements/index.rst index 79c3419be5b..4066f896951 100644 --- a/docs/features/vso/requirements/index.rst +++ b/docs/features/vso/requirements/index.rst @@ -1,15 +1,16 @@ -# ******************************************************************************* -# 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 -# ******************************************************************************* +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* .. _vso_requirements: From cb0730e8c191c19702855d11ba66fa663f255b65 Mon Sep 17 00:00:00 2001 From: basheerFZ <46041610+basheerFZ@users.noreply.github.com> Date: Thu, 12 Mar 2026 11:00:17 +0530 Subject: [PATCH 7/9] Fix copyright block formatting in index.rst Signed-off-by: basheerFZ <46041610+basheerFZ@users.noreply.github.com> --- docs/features/vso/index.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst index b043160fafc..1c7475856b1 100644 --- a/docs/features/vso/index.rst +++ b/docs/features/vso/index.rst @@ -1,15 +1,16 @@ -# ******************************************************************************* -# 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 -# ******************************************************************************* +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* .. _vso_feature: From 45e11f327063cdb59a61643aead698566c7557d7 Mon Sep 17 00:00:00 2001 From: lgesdv Date: Tue, 2 Jun 2026 12:50:42 +0530 Subject: [PATCH 8/9] modified the assets file to suit Score formats --- .../features/vso/_assets/VSO_architecture.svg | 258 ++++++++++++++++++ docs/features/vso/index.rst | 4 +- docs/features/vso/requirements/index.rst | 2 +- 3 files changed, 261 insertions(+), 3 deletions(-) create mode 100644 docs/features/vso/_assets/VSO_architecture.svg diff --git a/docs/features/vso/_assets/VSO_architecture.svg b/docs/features/vso/_assets/VSO_architecture.svg new file mode 100644 index 00000000000..48bf335a100 --- /dev/null +++ b/docs/features/vso/_assets/VSO_architecture.svg @@ -0,0 +1,258 @@ + + + + + + LGE Internal Use Only + + + + + + ADAS Container + + FEO + + + A + + C + + B + + D + + E + + + + + + + + + + + System Services + Container + + Lifecycle&Health + + Svc + #1 + + Svc + #2 + + + + Digital Cockpit + Container + + Orchestration + + DMS + + IVI + + BMS + + ... + + + + + + User + + + + + + + Scenario.yml + + + + Vehicle Service Orchestrator (VSO) + + + deploy + + + + + + + + + + API Server + + + FilterGateway + + + + + + + + ActionController + + + StateManager + + + + + + + + + + NodeAgent + + + Monitoring + + + + + + + + + + + + + + + + + control + + + + + control + + + + + control + + + + + + + + + DB + + + + + + + + + + + use + + + + + + + use + + + + + + + use + + + + + + + use + + + + + + + + + + OCI + Interface + + + + Logging + Interface + + + + Communication + Gateway + + + + Tracing + Interface + + + + + implement + + + + + implement + + + + + implement + + + + + implement + + + + + + + + Container engine + + Podman + + + + Logging + Logging + + + + Communication + DDS/IPC/ + SOMEIP + + + + Tracing + Tracing + diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst index 1c7475856b1..66d289485b6 100644 --- a/docs/features/vso/index.rst +++ b/docs/features/vso/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -186,7 +186,7 @@ The system follows a three-layer architecture specialized for in-vehicle environ - **Agent Layer:** NodeAgent handles execution on each node - **Runtime Layer:** Container engine performs actual container operations -.. image:: _assets/VSO_architecture.png +.. image:: _assets/VSO_architecture.svg :alt: Vehicle Service Orchestrator Architecture Core Components diff --git a/docs/features/vso/requirements/index.rst b/docs/features/vso/requirements/index.rst index 4066f896951..369f3ae62cf 100644 --- a/docs/features/vso/requirements/index.rst +++ b/docs/features/vso/requirements/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. From 74a577a57a74b97406d0ad2c4e97d2c07ce9d6b4 Mon Sep 17 00:00:00 2001 From: lgesdv Date: Fri, 12 Jun 2026 19:12:50 +0530 Subject: [PATCH 9/9] updated the revised VSO Proposal with Feature request[#2597] --- docs/features/vso/_assets/README.md | 36 ++ .../_assets/SCORE_architecture_with_VSO.svg | 254 ++++++++ .../features/vso/_assets/VSO_architecture.png | Bin 56900 -> 0 bytes .../features/vso/_assets/VSO_architecture.svg | 445 ++++++-------- .../_assets/VSO_component_relationship.svg | 104 ++++ .../vso/_assets/VSO_evidence_state_matrix.svg | 166 ++++++ docs/features/vso/index.rst | 557 ++++++++++-------- docs/features/vso/requirements/index.rst | 124 ++-- docs/requirements/stakeholder/index.rst | 97 +-- 9 files changed, 1171 insertions(+), 612 deletions(-) create mode 100644 docs/features/vso/_assets/README.md create mode 100644 docs/features/vso/_assets/SCORE_architecture_with_VSO.svg delete mode 100644 docs/features/vso/_assets/VSO_architecture.png create mode 100644 docs/features/vso/_assets/VSO_component_relationship.svg create mode 100644 docs/features/vso/_assets/VSO_evidence_state_matrix.svg diff --git a/docs/features/vso/_assets/README.md b/docs/features/vso/_assets/README.md new file mode 100644 index 00000000000..6f3794136a9 --- /dev/null +++ b/docs/features/vso/_assets/README.md @@ -0,0 +1,36 @@ +# VSO Assets + +This folder contains visual assets for the Vehicle Service Orchestrator (VSO) feature documentation. + + +## Architecture Diagrams + +### VSO_architecture.svg +**Used in:** [docs/features/vso/index.rst](../index.rst) - System Architecture section + +Main architecture diagram showing the Multi-node Scenario Evidence Layer: +- **Data Inputs Layer:** Per-node signals from Runtime Plane, Diagnostics Module, and Platform Resources (purple boxes) +- **VSO Core Modules:** Scenario Management, State Manager, Evidence Aggregation, Scenario Evidence Violation, Response Management (orange/yellow boxes) +- **Output Layer:** OEM State Manager / Safety Manager integration and S-CORE Lifecycle handoff (green boxes) + +Key principle: VSO observes and generates evidence but does NOT execute or decide. + +### VSO_component_relationship.svg +**Used in:** [docs/features/vso/index.rst](../index.rst) - Integration with S-CORE Components section + +Diagram showing the clear separation of concerns between: +- **S-CORE Diagnostics / OpenSOVD** (blue) - raw signals, fault lifecycle +- **VSO** (orange) - evidence generation, pipeline monitoring +- **OEM State Manager / Safety Manager** (green) - decision-making +- **S-CORE Lifecycle** (purple) - execution + +### VSO_evidence_state_matrix.svg +**Used in:** [docs/features/vso/index.rst](../index.rst) - Evidence State Response Matrix section + +Visual representation of the Evidence State Response Matrix showing six evidence states: +- **OK** (green): Normal execution, no action +- **WATCH** (yellow): Light monitoring, minor deviations +- **WARN** (orange): Focused debugging (30s), pre-snapshot, dashboard warning +- **VIOLATED** (red): Intensive diagnostics (60s), snapshot freeze, critical alert +- **INCOMPLETE** (purple): Missing signals, low confidence evidence +- **RECOVERED** (blue): Return to normal, recovery package archived diff --git a/docs/features/vso/_assets/SCORE_architecture_with_VSO.svg b/docs/features/vso/_assets/SCORE_architecture_with_VSO.svg new file mode 100644 index 00000000000..e7c93c75a61 --- /dev/null +++ b/docs/features/vso/_assets/SCORE_architecture_with_VSO.svg @@ -0,0 +1,254 @@ + + + + + + + + + + + + + + + + + + + + + Eclipse SDV S-CORE Platform Architecture + with Vehicle Service Orchestrator (VSO) Integration + + + + Application Layer + + + ADAS Applications + L3 Perception, Fusion, + Planning, Control + + + Vehicle Functions + Parking, Highway Pilot, + Automated Valet + + + Infotainment + HMI, Media, + Connectivity Apps + + + Cloud Services + OTA Updates, + Remote Diagnostics + + + AI/ML Services + Inference Engine, + Model Management + + + Safety Monitor + ASIL Functions, + Watchdog + + + + Mixed Criticality Software Orchestrator Layer + + + + S-CORE Platform Components + + + + Lifecycle Manager + Application lifecycle, + State management, + Process control + + + Orchestrator + Resource allocation, + Workload scheduling, + Container management + + + Configuration + Key/Value store, + Config management, + Persistency + + + Security & Crypto + Auth, Encryption, + Key Management + + + + Communication + DDS, SOME/IP, + Message Bus, + Network Stack + + + Diagnostics + SOVD/OpenSOVD, + Fault management, + DTC handling + + + Logging & Tracing + System logs, + Distributed tracing, + Event recording + + + Time Services + Time sync, PTP, + Timestamp services + + + + + VSO + (NEW - Multi Node Evidence Layer) + + + + NEW + + + + + Scenario Contract Management + Contract Registration, + Capability/Node Data, + Data Subscription + + + + Evidence Aggregation + Runtime, Diagnostic, + Fault, Log & Resource + Signals + + + + Evidence Package Generation + Violation Detection, + Scenario-level root-cause, + Evidence package model + + + + Response Management + Notification, + Recovery actions, + Debug escalation + + + OEM/Vehicle Components + + + OEM State Manager + Function Group States, + Decision making, + Mode management + + + Safety Manager + ASIL functions, + Safety monitoring, + Degradation control + + + Vehicle Frameworks + Vehicle State Management, + Power Management, + Update Management, + Platform Health Monitor, + Resource Monitor, + FEO (Execution Order) + + + + Base Libraries + Memory management, + Thread pools, + Error handling, + Data structures, + Utilities, + Common interfaces, + Platform abstraction + + + Hardware Abstraction + HAL, Device drivers, + Board support, + Platform APIs + + + OS Services + Linux kernel, Drivers, + System services + + + + + + Operating System Layer + Linux Kernel • Real-time Extensions • Device Drivers • File Systems • Network Stack + Container Runtime (e.g., containerd) • Hypervisor (optional) • Hardware Abstraction + + + + Hardware Platform + Multi-core SoCs (x86, ARM, RISC-V) • HPC Units • Zone Controllers • GPUs • Accelerators • Network Interfaces • Storage + + + + Legend + + + App/OEM + + + Platform + + + Runtime + + + Diagnostics + + + VSO (NEW) + + + Base/HAL + + \ No newline at end of file diff --git a/docs/features/vso/_assets/VSO_architecture.png b/docs/features/vso/_assets/VSO_architecture.png deleted file mode 100644 index b0ec8bad6ab813e23dcbf2cf11699d2aeb8863a5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 56900 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%0D5IIjHN# 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 WH#m7LEt>`WJ8E{q^qH}H+`j=VRE|gh diff --git a/docs/features/vso/_assets/VSO_architecture.svg b/docs/features/vso/_assets/VSO_architecture.svg index 48bf335a100..487a156e09a 100644 --- a/docs/features/vso/_assets/VSO_architecture.svg +++ b/docs/features/vso/_assets/VSO_architecture.svg @@ -1,258 +1,187 @@ - - - - - - LGE Internal Use Only - - - - - - ADAS Container - - FEO - - - A - - C - - B - - D - - E - - - - - - - - - - - System Services - Container - - Lifecycle&Health - - Svc - #1 - - Svc - #2 - - - - Digital Cockpit - Container - - Orchestration - - DMS - - IVI - - BMS - - ... - - - - - - User - - - - - - - Scenario.yml - - - - Vehicle Service Orchestrator (VSO) - - - deploy - - - - - - - - - - API Server - - - FilterGateway - - - - - - - - ActionController - - - StateManager - - - - - - - - - - NodeAgent - - - Monitoring - - - - - - - - - - - - - - - - - control - - - - - control - - - - - control - - - - - - - - - DB - - - - - - - - - - - use - - - - - - - use - - - - - - - use - - - - - - - use - - - - - - - - - - OCI - Interface - - - - Logging - Interface - - - - Communication - Gateway - - - - Tracing - Interface - - - - - implement - - - - - implement - - - - - implement - - - - - implement - - - - - - - - Container engine - - Podman - - - - Logging - Logging - - - - Communication - DDS/IPC/ - SOMEIP - - - - Tracing - Tracing - + + + + + + + + + + + + + + + + + + + + + + + + + + Node-based Architecture with Separate VSO Component + + + DATA INPUTS (per node) + + + + Node A (ECU1) + + + + VSO + + Evidence Package + scenario_run_id | node_id | metrics + + + Lifecycle + timing, deadline events, runtime plane + + + Diagnostics Module + logs, fault status, debug controls + + + Platform Resource + CPU/memory, node health + + + + Node B (ECU2) + + + + VSO + + Evidence Package + scenario_run_id | node_id | metrics + + + Lifecycle + timing, deadline events, runtime plane + + + Diagnostics Module + logs, fault status, debug controls + + + Platform Resource + CPU/memory, node health + + + + Node C (ECU3) + + + + VSO + + Evidence Package + scenario_run_id | node_id | metrics + + + Lifecycle + timing, deadline events, runtime plane + + + Diagnostics Module + logs, fault status, debug controls + + + Platform Resource + CPU/memory, node health + + + + OEM State and Safety Management + • Receives data from nodes + • Decision + - Degrade + - Fallback + - Maintain + • Executes lifecycle transitions + + + VSO + + + Vehicle Service Orchestrator (VSO) + Separate monitoring and evidence layer + + + + Scenario Contract Management + • Scenario Contract Registration + • Monitoring Server + • Data Subscription + + + + Evidence Aggregation + Correlate by scenario_run_id: + • Runtime timing & deadline events (multi-node) + • Diagnostic faults & logs (per node) + + + + Evidence Package Generation + • Violation detection + • Evidence package generation + • Observability & Dashboard alerts + + + + Response Management + • Snapshot freeze/archive + • Notification & recovery tracking + + + + + + + + + + + + + Legend: + + Data Input + + + VSO Module + + + Decision/Execute + + + Data flow + + + Control flow + + + + Architecture Overview + Nodes provide data directly to OEM State Manager for decision-making + VSO operates as an independent monitoring and evidence layer (shown separately) + \ No newline at end of file diff --git a/docs/features/vso/_assets/VSO_component_relationship.svg b/docs/features/vso/_assets/VSO_component_relationship.svg new file mode 100644 index 00000000000..6eaea5d2fca --- /dev/null +++ b/docs/features/vso/_assets/VSO_component_relationship.svg @@ -0,0 +1,104 @@ + + + + + + + + + + + + + + + + + + + + VSO Relationship to S-CORE Components + Clear Separation of Concerns + + + + S-CORE Diagnostics / + OpenSOVD + Responsibilities: + • Raw signals: logs, faults, metrics + • Fault lifecycle management + • SOVD API exposure + • DTC management + + + + VSO + (Evidence Layer) + Responsibilities: + • Multi-node pipeline monitoring + • Determinism violation detection + • Evidence package generation + • Scenario-level correlation + + + + OEM State Manager / + Safety Manager + Responsibilities: + • Decision-making + • Degrade / Fallback / Maintain + • Entry/Stay/Exit evaluation + • Function Group State mgmt + + + + S-CORE Lifecycle + Responsibilities: + • Application lifecycle execution + • Container/process management + + + + + signals + + + + evidence + + + + + + + What VSO Does NOT Do: + ✗ Does NOT own fault lifecycle + ✗ Does NOT make decisions + ✗ Does NOT execute lifecycle actions + ✗ Does NOT manage containers + ✗ Does NOT control actuators + + + What VSO Does: + ✓ Observes multi-node pipelines + ✓ Detects determinism violations + ✓ Generates structured evidence + ✓ Correlates by scenario_run_id + ✓ Provides dashboard notifications + + + + Core Principle + VSO is a passive observer that generates evidence for decision makers. + Execution remains in S-CORE Lifecycle. Decision remains OEM-specific. + \ No newline at end of file diff --git a/docs/features/vso/_assets/VSO_evidence_state_matrix.svg b/docs/features/vso/_assets/VSO_evidence_state_matrix.svg new file mode 100644 index 00000000000..5109324a04a --- /dev/null +++ b/docs/features/vso/_assets/VSO_evidence_state_matrix.svg @@ -0,0 +1,166 @@ + + + + + + + + + + + + + + VSO Evidence State Response Matrix + Observability Escalation and Response Actions + + + + State + + + Observability + + + Evidence + + + Handoff + + + Visibility / Notify + + + + OK + Pipeline executing + within constraints + + + NORMAL + + + none + + + none + + + none + + + + WATCH + Minor deviations + detected + + + optional light + observe + + + monitor + + + optional info + + + none + + + + WARN + Constraint violations + approaching threshold + + + FOCUSED_DEBUG + (30s collection) + + + pre-snapshot + + + package + condRef + + + Dashboard WARN + + + + VIOLATED + Determinism contract + breach detected + (critical violation) + + + INTENSIVE_DIAG + (60s collection) + + + freeze snapshot + + + package + condRef + + quality metrics + + + Diagnostic Event + + Dashboard ERROR + + + + INCOMPLETE + Missing evidence + signals + + + source health + report + + + mark incomplete + + + package with + LOW confidence + + + Dashboard WARN + + + + RECOVERED + Return to normal + from violation + + + NORMAL + + + archive snapshot + + + recovery package + + + Dashboard INFO + + + + State transitions are managed by VSO Policy Manager based on scenario determinism contracts. + Evidence packages are delivered to OEM State Manager / Safety Manager. VSO does NOT make execution decisions. + \ No newline at end of file diff --git a/docs/features/vso/index.rst b/docs/features/vso/index.rst index 66d289485b6..3069b3afd8d 100644 --- a/docs/features/vso/index.rst +++ b/docs/features/vso/index.rst @@ -44,244 +44,348 @@ To activate this feature, use the following feature flag: Abstract ======== -We propose adding a vehicle-specialized orchestration framework that adapts cloud-native container technologies to the in-vehicle environment. -The Vehicle Service Orchestrator (VSO) extends cloud-native orchestration with vehicle-specific capabilities, -enabling applications developed in the cloud to be deployed to the vehicle without modification. -It supports explicit resource management for mixed-criticality workloads and provides execution guarantees and automatic recovery for safety-critical applications. +Vehicle Service Orchestrator (VSO) is a Multi-node Scenario Evidence Layer for Eclipse SDV S-CORE. -The term "Vehicle Service Orchestrator" reflects the orchestrator's role in managing services under the unique operational conditions of a vehicle, -rather than simply adapting a cloud-native orchestrator. -Unlike traditional container orchestrators designed for scalable datacenter environments, -a vehicle-specific orchestrator must account for constrained compute budgets, -strict isolation between workloads of differing criticality, -and continuous operation under varying driving conditions. -The name emphasizes that its primary purpose is to coordinate and safeguard in-vehicle services in a manner appropriate for automotive constraints, -bridging cloud-native development models with the operational realities of the vehicle environment. +VSO defines multi-node scenario contracts (pipeline chains) and subscribes to runtime/diagnostic/platform signals. +monitors pipeline execution determinism, detects policy violations at scenario level, and correlates evidence using scenario_run_id. -The intent of this feature request is to define a high-level architecture for the Vehicle Service Orchestrator. -The components listed throughout this document may require detailed feature requests in the future respectively. +VSO does NOT own diagnostic fault lifecycle, does NOT decide Function Group State, and does NOT execute application lifecycle. +VSO hands off determinism evidence packages and conditionRefs to Safety Managers for final safety decisions and approvals. +Execution is performed by S-CORE Lifecycle. + +**Core Proposal:** + +- VSO does not execute +- VSO does not decide +- VSO observes multi-node scenario pipelines +- VSO detects determinism policy violations +- VSO generates structured evidence +- VSO delivers evidence packages for decisions and statemanagement. + +Execution remains in S-CORE Lifecycle. Safety Decisions remain external to S-CORE. + +The intent of this feature request is to define the architecture and interfaces for the Vehicle Service Orchestrator +as a scenario evidence layer that complements existing S-CORE Diagnostics, Lifecycle and Orchestrator components. Motivation ========== -1. Complexity and Platform Dependency in Vehicle Software Deployment ---------------------------------------------------------------------- +Problem Statement +----------------- -Current vehicle software deployment faces significant constraints due to complex multi-stage validation processes, -platform-specific customized builds, and limited update mechanisms. -In a typical deployment scenario, any modification to an application requires repeated validation across the development, testing, and vehicle environments, -and each validation stage must faithfully reproduce the same execution environment. -Integration issues frequently occur due to environment inconsistencies, -and model-specific builds are unavoidable because each vehicle ECU uses different hardware architectures (x86, ARM, RISC-V) -and different OS conditions (Linux distributions, kernel versions, library dependencies). +Modern SDV scenario pipelines (L3 Highway, Parking/Valet, ADAS services) span HPC, Zonal Controllers and ECUs. +Policy based decisions become ineffective without VSO Evidences, such as decisions to switch Autonomous mode to Manual mode, or degrade to a lower ASIL level. +Pipeline stages have timing, resource, dependency and diagnostic constraints. -During OTA updates, a full system reboot is often required, rollback capabilities are limited, and recovering from update failures is challenging. -Version management also becomes unnecessarily complex. -To address these challenges, vehicle-optimized orchestration technology is required—one that enables "build once, run anywhere" through container-based deployment, -defines deployment state with a declarative Manifest, and supports automated rollout and rollback. -A lightweight solution that accounts for limited in-vehicle resources and real-time constraints is essential. +**What goes wrong without VSO:** -2. Application Behavior in Mixed-Criticality Domains ------------------------------------------------------ +- Raw diagnostic data is available, but scenario-level operational evidence is not standardized +- Policy violation data is often lost, late, or not correlated by scenario_run_id +- Orchestrators may accidentally become state decision makers +- Diagnostic fault lifecycle and scenario policy lifecycle may be mixed +- Debug escalation is ad-hoc and not contract-driven +- Lack of structured evidence for safety decsisions and learning +- Fleet/cloud analysis loses context and root-cause evidence +- No standard for multi-node scenario evidence layer +- Missing determinism monitoring layer + +**Gap Analysis:** -Vehicle software is composed of applications with variant execution requirements depending on their safety level. -For example, an ASIL-D Automatic Emergency Braking (AEB) system requires strict timing guarantees, -while a QM-level infotainment system can tolerate delays. -This mixed-critical structure also applies when distributing workloads across high-performance and low-performance ECUs. +- **S-CORE Diagnostics** → "what happened" (raw signals, faults, logs) +- **VSO** → "did multi-node pipeline break determinism ?" (scenario-level evidence) +- **OEM State Manager** → "what should we do" (decision-making) +- **S-CORE Lifecycle** → "execute decision" (lifecycle actions) -Expected issues in this execution model include resource contention and inappropriate node placement between critical and non-critical applications. -For instance, an infotainment application consuming excessive CPU resources could delay object detection in AEB or increase braking response time—posing a significant safety risk. +S-CORE already has Diagnostics, Lifecycle, Orchestrator, Logging, and FEO-related building blocks. +VSO is proposed as a scenario evidence policy layer that consumes those signals without duplicating their ownership. -To address these challenges, ASIL-D applications must be allocated dedicated CPU cores and memory, while QM applications should share resources. -Furthermore, dynamic resource reallocation is necessary to ensure the execution guarantees and timing requirements of safety-critical functions when driving conditions change (e.g., urban → highway). -Since standard cloud-native orchestration does not inherently understand ASIL concepts or guarantee prioritization for safety-critical workloads, -a vehicle-optimized orchestrator is required. +Why VSO Fits S-CORE +------------------- +**S-CORE Direction:** -Rationale -========= +- Common open-source SDV runtime foundation +- Modular, extensible, safety-ready stack +- Feature requests can propose structural changes and new functionality -1. Selection of a Cloud-Native Orchestration Foundation --------------------------------------------------------- +**Diagnostics Direction:** -This feature is built upon cloud-native orchestration technologies that have already been validated at scale in cloud environments. -Container orchestration systems proven in the cloud provide core capabilities such as declarative deployment, automatic recovery, and rolling updates, -all of which can be directly applied to address the complexity and platform dependency issues found in vehicle software deployment. -By optimizing these proven cloud technologies for the in-vehicle environment, development time can be reduced while improving overall system reliability. +- S-CORE Diagnostics proposes SOVD-based diagnostics +- Real-time fault access and advanced data handling +- Diagnostic feature scope -2. Extension Architecture for Vehicle-Specific Capabilities ------------------------------------------------------------- +**VSO Alignment:** -The reason we adopted an extension architecture—adding vehicle-specific capabilities instead of using the existing cloud-native orchestrator as-is—is -the fundamental difference between vehicle and cloud environments. -Cloud systems assume virtually infinite scalability, persistent network connectivity, and 99.9% availability, -whereas vehicles operate under constrained resources, intermittent connectivity, 99.9999% availability requirements, and stringent real-time constraints. -In particular, mixed-criticality management based on ASIL levels is a requirement unique to automotive systems and does not exist in cloud environments. -Therefore, while the base orchestration features are reused, extensions such as mixed-criticality awareness, real-time scheduling, -and vehicle-specific health checks are added. +VSO aligns with S-CORE's feature request process by introducing a bounded, scenario operational feature +that does not bypass safety or execution authority. VSO complements existing S-CORE components: -3. Declarative Manifest-Based Configuration --------------------------------------------- +- **Diagnostics:** VSO consumes diagnostic outputs; it does not redefine diagnostics +- **VSO:** VSO generates evidence; safety managers make decisions +- **Lifecycle:** VSO observes; Lifecycle executes -Defining ASIL levels, resource allocations, and dependencies through a declarative Manifest separates the responsibilities of developers and integrators -while reducing deployment complexity. -In traditional workflows, developers must manually manage platform-specific build scripts, environment variables, and resource settings, -requiring repetitive adjustments whenever the vehicle model or ECU changes. -With a declarative Manifest, developers specify what to deploy, while the orchestrator determines how to deploy it. -This allows developers to focus on application logic while integrators adjust only the Manifest to support diverse vehicle environments. -4. Portability Without Application Code Changes ------------------------------------------------- +Rationale +========= -The decision to allow cloud-developed applications to be deployed to vehicles without modifying their code is driven by the need for development productivity and ecosystem utilization. -Previously, porting a cloud application to a vehicle required manual adjustments to platform-specific library dependencies, environment variables, -and network configurations—introducing delays and increasing the likelihood of errors. -Container-based deployment encapsulates the application and all of its dependencies into an image, ensuring a consistent execution environment across cloud and vehicle platforms. -The orchestrator abstracts environment-specific differences such as networking, storage, and security. -This enables immediate reuse of cloud-validated applications and frameworks (e.g., AI inference engines, data processing pipelines) within the vehicle -while significantly reducing integration overhead through consistent cloud-to-vehicle development environments. - -5. Container-Based Isolation and Resource Management ------------------------------------------------------ - -Managing all applications—including the Executor—within containers ensures explicit resource management and consistent runtime environments. -Previously, the Executor existed as a Rust package with implicit and manually maintained resource allocation, -which risked violating FEO guarantees when additional applications were introduced. -Through container isolation, each Executor can be explicitly assigned dedicated CPU cores, memory, and GPU resources. -cgroup and namespace isolation prevents interference from other workloads. -Additionally, container images enable "build once, run anywhere," providing platform independence across heterogeneous hardware architectures such as x86, ARM, and RISC-V. - -6. Real-Time Monitoring and Automatic Recovery Mechanisms ----------------------------------------------------------- - -The design choice to support real-time monitoring and automated recovery of resource usage, timing metrics, and health status is essential -due to the safety requirements and operational complexity of vehicle environments. -Previously, when the Executor crashed or timing constraints were violated, issues were only logged and required manual investigation and restart, -with little visibility into root causes. -In vehicular systems, interruptions to safety-critical functions can directly affect human life, making millisecond-level fault detection and recovery indispensable. -Periodic health checks via a Liveness Probe, timing-constraint validation using a Timing Probe, and immediate restart policies upon failure ensure -continuity of critical functions without human intervention. -Collecting metrics such as CPU and memory usage, per-task execution time, and timing violation counts enables both post-incident analysis and proactive prevention. +Multi-node Scenario Awareness +------------------------------ +**What "true multi-node awareness" actually means:** -Specification -============= +A system is multi-node aware only if a control entity can answer all four questions at runtime: -Overview --------- +1. Which nodes exist right now? +2. What is the role and capability of each node? +3. What is the real-time health of each node (not just apps)? +4. Can workloads be safely placed / moved / stopped across nodes? -A Vehicle Service Orchestrator is a structured and declarative framework for managing the execution flow, timing constraints, and error handling of containers. -Developers can define application control flows and resource-management policies in a platform-independent manner, -while the orchestration automates container deployment, execution guarantees, and dynamic resource allocation. -This clearly separates application logic from infrastructure management, enabling stable and vehicle-optimized operation. +S-CORE today can only partially answer #4 inside a single node. +**Health signals S-CORE already provides (baseline):** -System Architecture -------------------- +1. Component alive / heartbeat +2. Lifecycle state (Init, Running, Error, Terminated) +3. Local application failures +4. Controlled shutdown / restart hooks -The system follows a three-layer architecture specialized for in-vehicle environments: -- **API Layer:** API Server Allows the user to configure(add/remove) the Manifest -- **Orchestration Layer:** vehicleData FilterGateway, ActionController and StateManager coordinate workloads -- **Agent Layer:** NodeAgent handles execution on each node -- **Runtime Layer:** Container engine performs actual container operations +These are necessary, but not sufficient for multi-node decision. -.. image:: _assets/VSO_architecture.svg - :alt: Vehicle Service Orchestrator Architecture +**Additional signal categories required for true multi-node awareness:** -Core Components ---------------- -**APIServer** - Interfaces with user to add or remove the manifest(scenarios) +- **CATEGORY A:** Node Identity & Topology Signals +- **CATEGORY B:** Node Liveness & Reachability Signals +- **CATEGORY C:** Resource Availability (Node-Level) +- **CATEGORY D:** Safety Capability & ASIL Compatibility Signals +- **CATEGORY E:** Workload Placement Feedback (Cross-Node) +- **CATEGORY F:** Fault Domain & Failure Propagation Signals -**Vehicle Data Filtergateway** - Services are automatically controlled based on changes in vehicle state. +**VSO Solution: Multi-node Scenario Evidence Layer** -**ActionController** - Scenario-based workload control and real-time scheduling +VSO addresses these gaps by: -**StateManager** - Tracking container lifecycle and managing state transitions +- Defining and identifying pipeline chains per Node +- Monitoring end-to-end determinism +- Detecting and correlating violations +- Generating structured evidence packages -**NodeAgent** - Container execution and resource management per node +OEM State / Safety Manager subscribes and receives: +- Violation type +- Affected nodes +- Confidence level +- conditionRefs for execution adaptation +- evidence quality metrics (freshness, completeness) -Workload Lifecycle Management ------------------------------- +Determinism Monitoring +----------------------- -Standard Command Set --------------------- +VSO defines and monitors **determinism contracts** enabling multi-node scenarios. -Seven essential workload commands are supported: +**Key Concepts:** -- ``create`` -- ``start`` -- ``pause`` -- ``resume`` -- ``stop`` -- ``restart`` -- ``delete`` +- **Multi-node Scenario:** A defined pipeline chain and execution dependencies (e.g., L3 Highway: Perception → Fusion → Planning across HPC and zone nodes) +- **Determinism Contract:** Constraints that ensure timing, ordering, and resource guarantees for the entire pipeline (e.g., end-to-end latency ≤ budget, stage ordering preserved, CPU < 90%) +- **Determinism Evidence:** Scenario-level evidence capturing violations of pipeline determinism across nodes +- **Scenario Policy:** Rules for classifying evidence as OK, WATCH, WARN, VIOLATED, or RECOVERED +- **Evidence Package:** Structured package delivered to OEM State Manager / Safety Manager (scenario_run_id, pipeline_id, affected_nodes, violation_type, confidence) -All commands are delivered via remote procedure calls and follow a standardized response format. +Clear Boundaries +---------------- -Container State Model ---------------------- +VSO maintains strict boundaries to avoid conflicting with existing S-CORE components: -Containers are managed across five main states: +**VSO Is:** -- **Created:** Image ready for execution -- **Running:** Active execution -- **Paused:** Memory preserved, execution suspended -- **Exited:** Normal or error termination -- **Restarting:** Automatic recovery in progress +- Multi-node scenario evidence layer +- Pipeline determinism monitoring layer +- Scenario contract manager +- Debug/focused collection response coordinator +- Evidence package generator +- Diagnostic visibility publisher +- Operator/dashboard notification source -Transitions between these states follow strict rules enforced by the StateManager. +**VSO Is Not:** +- ASIL safety decision layer +- Diagnostic Fault Manager +- DTC lifecycle owner +- OEM Decision Manager replacement +- Lifecycle/Execution replacement +- Container/process/resource controller +- Actuator/trajectory/emergency braking controller -Scenario-Based Automation --------------------------- -Conditional Execution Engine ----------------------------- +Specification +============= -Services are automatically controlled based on changes in vehicle state. -Scenario information is retrieved from a distributed key-value store, and corresponding actions are executed automatically when conditions are met. -Integration with real-time data streams ensures immediate responsiveness. +Overview +-------- +VSO is a Multi-node Scenario Evidence Layer that monitors pipeline chain determinism per node and generates evidence for state and Safety Management. -Resource Management and Isolation ----------------------------------- +**Input:** -Container Security Isolation ----------------------------- +- Runtime timing (multi-node) +- Diagnostic data / fault status +- Platform resource metrics (per node) -User identifiers, group permissions, and Linux capabilities are strictly controlled according to the principle of least privilege. -Restricting privileged mode and applying security contexts strengthens system-level protection. +**VSO Processing:** -Performance Optimization ------------------------- +- Multi-node pipeline monitoring +- Determinism contract evaluation +- Per-node evidence correlation -Processor and memory usage are tracked in real time, allowing early detection of resource shortages. -Parallel container creation, asynchronous processing, and automatic scaling optimize startup times and maximize efficiency. +**Output:** +- Determinism violation evidence package +- conditionRefs for execution adaptation +- Diagnostic/decisions event notification -Monitoring and Recovery ------------------------- +System Architecture +------------------- -State Monitoring ----------------- +S-CORE Platform Architecture with VSO Integration +------------------------------------------------ -Comprehensive health checks continuously monitor: +VSO is integrated as a Multi-node Evidence Layer within the Eclipse SDV S-CORE platform architecture, positioned between +the Diagnostics module and OEM/Vehicle components. The diagram below shows the complete platform architecture with VSO's +position and interactions: -- Process status -- Port connectivity -- Application-level health (Liveness Probe) -- Timing constraints (Timing Probe) +.. image:: _assets/SCORE_architecture_with_VSO.svg + :alt: Eclipse SDV S-CORE Platform Architecture with VSO Integration + :align: center -process status, port connectivity, and application-level health.Failure recovery is automated according to restart policies. -Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. -Customized recovery logic is applied depending on the error type. +VSO Architecture Details +----------------------- + +The system follows a modular architecture integrated within the S-CORE ecosystem: + +- **Data Inputs Layer:** Per-node signals (Runtime Plane, Diagnostics Module, Platform Resources) +- **VSO Core Modules:** Scenario Contract Management, Evidence Aggregation, Evidence Package Generation, Response Management +- **Output Layer:** OEM State Manager / Safety Manager integration, S-CORE Lifecycle handoff + +.. image:: _assets/VSO_architecture.svg + :alt: Vehicle Service Orchestrator Architecture - Multi-node Pipeline Evidence Layer + +Core Components +--------------- + +**Scenario Management** + +The Scenario Management module handles: + +- **Scenario Contract Registration:** Define scenario scope, pipeline dependencies, evidence requirements, and response policy +- **Monitoring Server:** Subscribe to runtime/diagnostic/platform signals per node +- **Scenario Data Collector:** Collect timing, deadline events, resource metrics, and diagnostic data + +**State Manager** + +The State Manager tracks: + +- **Multi-node Scenario State:** Monitor pipeline execution across nodes +- **Policy Manager:** Evaluate determinism contracts and classify evidence states +- **Scenario Policy Evaluator:** Apply policy rules (OK, WATCH, WARN, VIOLATED, RECOVERED) + +**Action Controller** + +The Action Controller coordinates: + +- **Response Management:** Observability escalation, snapshot freeze, handoff +- **Diagnostic Event Publication:** Notify diagnostic systems of violations +- **Evidence Package Handoff:** Deliver structured evidence to OEM State Manager / Safety Manager +- **Dashboard Notification:** Alert operators of WARN/ERROR states + +Evidence State Response Matrix +------------------------------- + +VSO classifies evidence into six states with corresponding observability and response actions: + +.. list-table:: + :header-rows: 1 + :widths: 15 20 20 25 20 + + * - State + - Observability + - Evidence + - Handoff + - Visibility / Notify + * - OK + - NORMAL + - none + - none + - none + * - WATCH + - optional light observe + - monitor + - optional info + - none + * - WARN + - FOCUSED_DEBUG 30s + - pre-snapshot + - package + condRef + - Dashboard WARN + * - VIOLATED + - INTENSIVE_DIAG 60s + - freeze snapshot + - package + condRef + quality + - event + Dashboard ERROR + * - INCOMPLETE + - source health report + - mark incomplete + - package LOW confidence + - Dashboard WARN + * - RECOVERED + - NORMAL + - archive snapshot + - recovery package + - Dashboard INFO + +.. image:: _assets/VSO_evidence_state_matrix.svg + :alt: VSO Evidence State Response Matrix - Observability Escalation + :align: center + +Data Flow +--------- + +**Per-Node Data Inputs:** + +1. **Diagnostics Module:** logs, fault status, debug controls +2. **Platform Resource:** CPU/memory, node pressure/health +3. **Runtime Plane:** stage timing, deadline events, lifecycle signals + +**VSO Processing:** + +1. **Data Subscription:** Subscribe to Diag/Platform signals per node +2. **Evidence Aggregation:** Correlate runtime, diagnostic, fault, log, and resource signals by scenario_run_id +3. **Scenario Evidence Violation:** Generate scenario-level root-cause evidence package model +4. **Response Management:** Execute notification and recovery actions + +**Output to Decision Layer:** + +1. **OEM State Manager / Safety Manager:** Receives violation evidence package from VSO +2. **Decision:** OEM/Safety Manager decides (degrade / fallback / maintain) +3. **Execution:** Sends command to S-CORE Lifecycle +4. **S-CORE Lifecycle:** Executes lifecycle transition per OEM/Safety Manager decision + +Integration with S-CORE Components +----------------------------------- + +**Relationship to S-CORE Diagnostics / OpenSOVD:** + +- **Diagnostics/OpenSOVD:** Raw signals (logs, faults, metrics), Fault lifecycle management, SOVD API exposure +- **VSO:** Multi-node pipeline determinism evidence, Violation evidence generation, Evidence package handoff +- **OEM State Manager/Safety Manager:** Decision (degrade / fallback / maintain), Entry/stay/exit evaluation +- **S-CORE Lifecycle:** Application lifecycle execution + +VSO consumes diagnostic outputs; it does not redefine diagnostics. +VSO monitors pipeline determinism and generates violation evidence. +OEM State Manager / Safety Manager receives evidence and makes decisions. +S-CORE Lifecycle executes decisions. VSO does not decide or execute. + +.. image:: _assets/VSO_component_relationship.svg + :alt: VSO Relationship to S-CORE Components - Clear Separation of Concerns + :align: center Requirements @@ -290,15 +394,49 @@ Requirements The related requirements can be found in :doc:`requirements/index`. +Value to Eclipse SDV S-CORE +============================ + +For Developers +-------------- + +- Scenario-level root-cause evidence +- Evidences escalation by contract +- Reusable sample scenarios (L3 Highway, Parking/Valet) + +For Platform +------------ + +- Clear boundaries with Diagnostics/State/Lifecycle +- Reduced duplicate orchestration logic +- Reusable evidence package model +- Modular integration with existing S-CORE components + +For OEMs/Tier-1s +---------------- +- +- Better decision making (decisions to switch Autonomous mode to Manual mode, or degrade to a lower ASIL level.) +- Fleet learning readiness +- Operational degradation traceability +- Structured evidence for safety analysis + +**VSO Complements S-CORE:** + +- **S-CORE Diagnostics:** VSO turns diagnostic/runtime signals into scenario-level evidence +- **OEM State Manager:** VSO delivers structured evidence instead of unstructured symptoms +- **S-CORE Lifecycle:** VSO keeps execution responsibility in the lifecycle layer + + Backwards Compatibility ======================= -This feature is designed as an optional extension module that does not modify the existing S-CORE architecture. -No changes are required to the current Executors (FEO, Lifecycle, Orchestration) or to application logic. -Container-based deployment and resource-management features are applied only to services that require them, -while existing process-based workloads remain fully preserved. +- VSO operates as a passive observer consuming existing diagnostic/runtime signals +- OEM State Manager integration is optional and OEM-specific +- VSO can operate as PerNode in virtualization scenario as well as multi node scenario +- Existing fault management and lifecycle workflows remain fully preserved + +VSO can be enabled or disabled via the feature flag without affecting existing S-CORE functionality. -The Manifest operates as an additional configuration layer that can be used alongside the existing Launch mechanism rather than replacing it. The image-delivery pipeline, data formats, and OS initialization procedures (Linux/QNX) remain unchanged. Furthermore, safety and security features complement—rather than replace—current mechanisms, ensuring full backward compatibility for the entire platform and all existing applications. @@ -308,23 +446,17 @@ Security Impact =============== The introduction of a Vehicle Service Orchestrator has security implications due to its system-level capabilities and distributed nature. -The orchestrator manages container lifecycle, resource allocation, and network access—all of which pose risks if accessed by unauthorized actors. -Container isolation provides security boundaries, but misconfigured containers or privileged containers could expose the host system. Remote procedure calls between orchestration components introduce network attack surfaces that must be secured with mutual TLS and authentication. The distributed key-value store used for configuration must be protected against unauthorized modification. To mitigate these risks, the Vehicle Service Orchestrator shall: -- Enforce the principle of least privilege for all containers -- Restrict privileged mode and dangerous Linux capabilities - Implement mutual TLS authentication for all inter-component communication -- Apply security contexts (SELinux, AppArmor) to containers - Validate and sanitize all Manifest inputs - Audit all orchestrator operations for security monitoring Since the orchestrator manages both QM and ASIL workloads, a security breach must not violate safety guarantees. -Resource isolation mechanisms (cgroups, namespaces) must be robust enough to prevent QM workload compromises from affecting ASIL workloads. The orchestrator components themselves must be developed with safety-appropriate quality standards to provide FFI (Freedom From Interference) guarantees. @@ -334,7 +466,7 @@ Safety Impact The Vehicle Service Orchestrator is classified as **ASIL_B** due to its role in managing safety-critical workloads. While the orchestrator does not directly implement safety functions (e.g., braking, steering), -it provides the runtime environment and resource guarantees necessary for safety-critical applications to meet their timing and reliability requirements. +it ensure the runtime decisions and resource guarantees necessary for safety-critical applications to meet their timing and reliability requirements. A failure in the orchestrator's resource allocation, timing enforcement, or automatic recovery mechanisms could indirectly impact safety by: - Causing timing violations in ASIL-D applications (e.g., delayed object detection in AEB) @@ -346,23 +478,16 @@ To address these risks: - ASIL-level workloads are allocated dedicated, isolated resources - Timing constraints are continuously validated with millisecond-level precision - Automatic recovery mechanisms ensure continuity of critical functions -- The orchestrator enforces FFI (Freedom From Interference) between criticality levels - Health checks and monitoring detect failures immediately -The core orchestrator components (ActionController, StateManager, NodeAgent) must be developed according to ASIL_B quality standards. Safety analysis (FMEA, DFA) will be conducted to identify and mitigate potential failure modes. License Impact ============== -The Vehicle Service Orchestrator is built upon open-source container technologies. -The base container runtime and orchestration concepts are freely available under permissive licenses (Apache 2.0, MIT). - -However, specific implementation choices may introduce license considerations: +The Vehicle Service Orchestrator is built upon open-source technologies. However, specific implementation choices may introduce license considerations: -- Container runtime engines (e.g., containerd, runc) are typically Apache 2.0 licensed -- Kubernetes components (if used as a base) are Apache 2.0 licensed - Linux kernel features (cgroups, namespaces) are GPL but do not affect userspace licensing - Automotive-specific extensions will be developed as S-CORE components under Apache 2.0 @@ -372,13 +497,11 @@ No license restrictions prevent the implementation of an open-source Vehicle Ser How to Teach This ================= -For developers familiar with cloud-native technologies (Kubernetes, Docker), the Vehicle Service Orchestrator will feel familiar -with automotive-specific extensions for ASIL levels and real-time constraints. +For developers the Vehicle Service Orchestrator will feel familiar with automotive-specific extensions for ASIL levels and real-time constraints. For automotive engineers unfamiliar with containers, the following learning path is recommended: -1. **Container Basics:** Understand container images, isolation, and resource management -2. **Declarative Configuration:** Learn Manifest-based deployment vs. imperative scripting +1. **Declarative Configuration:** Learn Manifest-based deployment vs. imperative scripting 3. **Mixed-Criticality Concepts:** Understand ASIL_Based resource allocation and FFI 4. **Orchestration Patterns:** Learn automatic recovery, health checks, and state management 5. **Vehicle-Specific Adaptations:** Understand timing probes, scenario-based automation, and constrained resource management @@ -386,54 +509,22 @@ For automotive engineers unfamiliar with containers, the following learning path Reference implementations, tutorials, and example Manifests will be provided to accelerate onboarding. -Rejected Ideas -============== - -Process-Based Orchestration Without Containers ------------------------------------------------ - -Managing workloads as native processes without container isolation was considered but rejected. -Containers provide explicit resource boundaries, consistent runtime environments, and platform portability that are difficult to achieve with bare processes. -The "build once, run anywhere" benefit of containers significantly outweighs the overhead of container runtime. - -Full Kubernetes Deployment ---------------------------- - -Deploying unmodified Kubernetes as the vehicle orchestrator was considered but rejected. -Kubernetes assumes datacenter-scale resources, persistent network connectivity, and does not understand automotive safety concepts (ASIL levels, timing constraints). -The resource overhead and complexity of Kubernetes are inappropriate for constrained vehicle environments. -An automotive-optimized orchestrator provides better resource efficiency and safety integration. - -Static Configuration Without Scenario-Based Automation -------------------------------------------------------- - -Using static configuration files without dynamic scenario-based automation was considered but rejected. -Vehicles operate in highly dynamic environments (urban vs. highway, parking vs. driving) that require runtime adaptation. -Static configuration cannot optimize resource allocation or workload placement based on driving conditions. -Scenario-based automation is essential for efficient mixed-criticality management. - - Open Issues =========== - Define detailed Manifest schema and validation rules - Specify distributed key-value store selection and configuration -- Determine container runtime selection (containerd vs. alternatives) - Define metrics collection format and integration with S-CORE monitoring - Specify integration points with existing S-CORE Lifecycle Management -- Determine OTA update flow for containerized workloads - Define certification and qualification strategy for ASIL_B components - Specify testing strategy for mixed-criticality scenarios -- Determine multi-ECU orchestration and cross-node communication patterns - Define failure mode analysis and safety case structure -- Specify resource reservation strategy for different driving scenarios - Determine integration with S-CORE::COM for inter-container communication Footnotes ========= # ******* -# .. [#v1] "Kubernetes Documentation", Kubernetes, https://kubernetes.io/docs/. +# .. [#v1] "Vehicle Service Orchestrator: A Multi-node Scenario Evidence Layer for Eclipse SDV S-CORE", Eclipse Foundation, # .. [#v2] "ISO 26262 Road vehicles — Functional safety", ISO, https://www.iso.org/standard/68383.html. -# .. [#v3] "OCI Runtime Specification", Open Container Initiative, https://github.com/opencontainers/runtime-spec. # ******** diff --git a/docs/features/vso/requirements/index.rst b/docs/features/vso/requirements/index.rst index 369f3ae62cf..ccd649084fc 100644 --- a/docs/features/vso/requirements/index.rst +++ b/docs/features/vso/requirements/index.rst @@ -17,84 +17,110 @@ Requirements ############ -Workload Lifecycle Management -============================== +VSO Contract API +================ -.. feat_req:: Standard Container Command Set - :id: feat_req__vso__standard_commands +.. feat_req:: VSO Scenario Contract Definition + :id: feat_req__vso__contract_api :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__vso__workload_control + :satisfies: stkh_req__vso__scenario_evidence :status: valid - The orchestrator shall support seven essential workload commands: create, start, pause, resume, stop, restart, and delete. All commands shall be delivered via remote procedure calls and follow a standardized response format. + The system shall provide APIs to identify roles, capabilities, real-time health, workload policy configuration information of node such as placement, movement, starting and stopping with pipeline dependencies. All APIs shall be delivered via remote procedure calls and follow a standardized response format. -.. feat_req:: Container State Model - :id: feat_req__vso__state_model - :reqtype: Functional - :security: YES - :safety: ASIL_B - :satisfies: stkh_req__vso__workload_control - :status: valid - - The system shall manage containers across five main states: Created, Running, Paused, Exited, and Restarting. State transitions shall follow strict rules and be tracked by the StateManager component. - -Scenario-Based Automation -========================== - -.. feat_req:: Conditional Execution Engine - :id: feat_req__vso__conditional_execution - :reqtype: Functional - :security: YES - :safety: ASIL_B - :satisfies: stkh_req__vso__vehicle_state_awareness - :status: valid - - The orchestrator shall automatically control services based on changes in vehicle state. Scenario information shall be retrieved from a distributed key-value store, and corresponding actions shall be executed automatically when conditions are met. +VSO Evidence Aggregation +========================= -Resource Management and Isolation -================================== - -.. feat_req:: Container Security Isolation - :id: feat_req__vso__security_isolation +.. feat_req:: VSO Evidence Aggregation and Correlation + :id: feat_req__vso__evidence_aggregation :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__dependability__security_features,stkh_req__vso__security_isolation + :satisfies: stkh_req__vso__scenario_evidence :status: valid - User identifiers, group permissions, and Linux capabilities are strictly controlled according to the principle of least privilege. Restricting privileged mode and applying security contexts strengthens system-level protection. - -.. feat_req:: Performance Optimization - :id: feat_req__vso__perf_optimization + The system shall correlate runtime, diagnostic, fault, health, log, and resource signals by scenario_run_id. + + Evidence aggregation shall: + + - Collect runtime timing and deadline events + - Collect diagnostic logs and fault status + - Collect platform resource metrics (CPU, memory, node health) + - Correlate all signals using scenario_run_id as the reference + - Support pipeline chain tracking + - Maintain temporal ordering of events across nodes + +VSO Evidence Quality +===================== + +.. feat_req:: VSO Evidence Quality Metrics + :id: feat_req__vso__evidence_quality :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__dependability__security_features + :satisfies: stkh_req__vso__scenario_evidence :status: valid - Processor and memory usage are tracked in real time, allowing early detection of resource shortages. Parallel container creation, asynchronous processing, and automatic scaling optimize startup times and maximize efficiency. + The system shall attach freshness, completeness, and confidence to all evidence packages. Evidence packages marked INCOMPLETE shall indicate missing signals and affected nodes. + + Quality metrics shall include: + + - **Freshness:** Timestamp and age of evidence data + - **Completeness:** Percentage of required signals successfully collected + - **Confidence:** Classification confidence level (HIGH, MEDIUM, LOW) + - **Source Health:** Health status of data sources -Monitoring and Recovery +VSO Response Management ======================== -.. feat_req:: State Monitoring - :id: feat_req__vso__state_monitoring +.. feat_req:: VSO Observability Escalation and Response + :id: feat_req__vso__response_management :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__dependability__automotive_safety + :satisfies: stkh_req__vso__observability, stkh_req__vso__fault_detection, stkh_req__vso__events_visibility :status: valid - Comprehensive health checks continuously monitor process status, port connectivity, and application-level health. Changes in status are detected immediately, ensuring consistency across the entire system. + The system shall support observability escalation, snapshot freeze, handoff, event publication, notification, and recovery. + + Response actions per evidence state: + + - **OK:** NORMAL observability, no action + - **WATCH:** Optional light observation, monitoring only + - **WARN:** FOCUSED_DEBUG (30s), pre-snapshot collection, package + condRef handoff, Dashboard WARN notification + - **VIOLATED:** INTENSIVE_DIAG (60s), freeze snapshot, package + condRef + quality handoff, event publication + Dashboard ERROR notification + - **INCOMPLETE:** Source health report, mark incomplete, package with LOW confidence, Dashboard WARN notification + - **RECOVERED:** NORMAL observability, archive snapshot, recovery package, Dashboard INFO notification + + +VSO Evidence Package Model +================================= -.. feat_req:: Automatic Recovery Mechanisms - :id: feat_req__vso__auto_recovery +.. feat_req:: VSO Evidence Package Model + :id: feat_req__vso__evidence_package_model :reqtype: Functional :security: YES :safety: ASIL_B - :satisfies: stkh_req__dependability__automotive_safety,stkh_req__vso__fault_tolerance + :satisfies: stkh_req__vso__state_manager_integration :status: valid - Failure recovery is automated according to restart policies. Failed containers are automatically restarted, and state-based corrective actions minimize operational downtime. Customized recovery logic is applied depending on the error type. + The system shall deliver the generated evidence packages and conditionRefs without forcing target states. + + Evidence package shall include: + + - scenario_run_id (unique identifier for this scenario execution) + - pipeline_id (identifier for the pipeline chain) + - affected_nodes (list of nodes involved in the violation) + - violation_type (timing, resource, ordering, diagnostic) + - confidence (HIGH, MEDIUM, LOW) + - conditionRefs (references to conditions for execution adaptation) + - timestamp and evidence quality metrics + + VSO shall NOT: + + - Force specific Function Group States + - Execute lifecycle transitions + - Make safety decisions + - Control application execution directly diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index cdd0b264c77..b3155b6f63a 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -1065,107 +1065,60 @@ Diagnostics and Fault Management The SW-platform shall enforce secure access control for all diagnostic interfaces, including authentication, encryption, and role-based access enforcement. -Vehicle Service Orchestrator ----------------------------- -VSO Workload Management ------------------------ - -.. stkh_req:: Container Lifecycle Management - :id: stkh_req__vso__workload_control - :reqtype: Functional - :security: YES - :safety: ASIL_B - :rationale: Provide standardized workload control mechanisms consistent with cloud-native practices while meeting automotive reliability requirements. - :status: valid +VSO Scenario Evidence Layer +---------------------------- - The platform shall provide standardized lifecycle management for containerized workloads, - including creation, startup, pause, resume, stop, restart, and deletion operations. - -.. stkh_req:: Vehicle State-Aware Orchestration - :id: stkh_req__vso__vehicle_state_awareness +.. stkh_req:: Multi-ECU Scenario Evidence Interfaces + :id: stkh_req__vso__scenario_evidence :reqtype: Functional :security: YES :safety: ASIL_B - :rationale: Enable dynamic workload management based on driving conditions to optimize resource utilization and ensure safety requirements are met. + :rationale: Enables the system to operate in modern, virtualized or distributed vehicle architectures, supporting safety-critical decisions. :status: valid - The platform shall support scenario-based workload orchestration that automatically adjusts application execution - based on vehicle state changes (e.g., driving mode, parking, charging). - + The platform shall provide a scenario evidence layer that monitors and aggregates scenario data for Multi Node support. -VSO Mixed-Criticality Support ------------------------------ -.. stkh_req:: ASIL and QM Workload Coexistence - :id: stkh_req__vso__asil_qm_coexistence - :reqtype: Functional - :security: YES - :safety: ASIL_B - :rationale: Enable safe coexistence of safety-critical and quality-managed applications on shared hardware while preventing interference. - :status: valid - -VSO Resource Management ------------------------ -.. stkh_req:: Workload Isolation - :id: stkh_req__vso__workload_isolation +.. stkh_req:: Multi-ECU State Management + :id: stkh_req__vso__state_manager_integration :reqtype: Functional :security: YES :safety: ASIL_B - :rationale: Prevent resource contention and timing violations between workloads of different criticality levels to maintain system safety. + :rationale: Provide structured evidence to enable safety and state management decisions without conflicting with execution authority. :status: valid - The platform shall enforce strict isolation between workloads using container-based mechanisms (cgroups, namespaces) - to prevent resource contention and timing interference across criticality boundaries. - - -VSO Security and Isolation --------------------------- -.. stkh_req:: Container Security Enforcement - :id: stkh_req__vso__security_isolation + The platform shall deliver evidence packages and conditionRefs for decision-making. + + .. stkh_req:: Scenario-level Observability + :id: stkh_req__vso__observability :reqtype: Functional :security: YES :safety: ASIL_B - :rationale: Protect the system from compromised or malicious containers through strict security controls and least-privilege enforcement. - :status: valid - - The platform shall enforce container security isolation through strict control of user identifiers, group permissions, - and Linux capabilities according to the principle of least privilegend maintain safety-critical functionality. + :rationale: Enable proactive problem detection and post-incident analysis through comprehensive system metrics for multi-node scenario execution. :status: valid - The platform shall provide comprehensive health monitoring for all workloads, - including process status, application-level health checks, and resource utilization tracking. - -.. stkh_req:: Automatic Fault Recovery - :id: stkh_req__vso__fault_tolerance + The platform shall provide scenario-level observability. + +.. stkh_req:: Multi-ECU Fault Detection and Correlation + :id: stkh_req__vso__fault_detection :reqtype: Functional :security: YES :safety: ASIL_B - :rationale: Maintain system availability and safety by automatically recovering from failures without human intervention. + :rationale: Detect and correlate faults across ECUs to enable decisions based on safe recovery. :status: valid + + The platform shall detect and correlate faults with in ECUs for Multi-ECU fault tolerance. - The platform shall provide automatic recovery mechanisms for failed workloads, - including configurable restart policies and state-based corrective actions to minimize operational downtime. - -.. stkh_req:: Timing Constraint Enforcement - :id: stkh_req__vso__timing_guarantees +.. stkh_req:: Multi-ECU Event Notification + :id: stkh_req__vso__events_visibility :reqtype: Functional :security: YES :safety: ASIL_B - :rationale: Ensure safety-critical applications meet their real-time timing requirements under all operating conditions. + :rationale: Enable event notifications and execution context to fault, lifecycle and other systems. :status: valid - The platform shall validate and enforce timing constraints for safety-critical workloads, - detecting violations at millisecond-level precision and triggering immediate corrective actions. + The platform shall publish and manage scenario-level events. -.. stkh_req:: System Observability - :id: stkh_req__vso__observability - :reqtype: Functional - :security: YES - :safety: ASIL_B - :rationale: Enable proactive problem detection and post-incident analysis through comprehensive system metrics - :status: valid - - The platform shall verify System Observability - Hardware support ----------------