eclipse-score · antonkri · Jul 4, 2025 · May 30, 2025
@@ -0,0 +1,136 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+.. _config_mgmt_feature:
+
+Configuration Management
+========================
+
+.. document:: Configuration Management
+   :id: doc__config_mgmt
+   :status: draft
+   :safety: ASIL_B
+   :tags: contribution_request, feature_request
+
+
+.. toctree::
+   :hidden:
+
+   requirements/index.rst
+
+Feature flag
+------------
+
+To activate this feature, use the following feature flag:
+
+``experimental_config_mgmt``
+
+Abstract
+--------
+
+Configuration Management feature is responsible for central storage, verification and modification of individual vehicle configuration properties. A generic interface for applications to access such properties is part of the feature.
+
+Motivation
+----------
+
+Embedded software usually needs specific adaptations to a particular vehicle in terms of configuration properties. Such configuration properties are called ``parameters`` in the following abstract. Examples of parameters are vehicle geometry or geographical region of use. Parameters are used in manifold computations and are expected to be constant during a driving cycle in customers' hand.
+Currently we differentiate between two kinds of parameters depending on type of configuration and related development process: coding parameters and calibration parameters.
+
+``ConfigDaemon`` application implements an on-target data base for all parameters used in a particular ECU and a generic interface for parameter accesses by user applications.
+
+The basic idea of ``ConfigDaemon`` is justified by the use case of having only flexible runtime dependencies on parameters from the viewpoint of a user application. Generic interface to access a parameter is defined by key-value principle, where key is a unique name for a required parameter and value is any data related to this name. Runtime dependencies have an added value in comparison to statically defined interfaces for every specific parameter, which must be resolved at build time. This approach allows to shorten build times and avoids the necessity of system model changes and following re-builds if a parameter changes.
+
+``ConfigDaemon`` is internally structured as
+
+- an application, which implements a parameter data base and interface for parameter access and
+- additional plugins, which handle specific kinds of parameters according to OEM functional requirements, like
+- coding plugin or
+- calibration plugin
+
+Flexibility of the generic interface is achieved by representation of any parameter value as a string. To convert the string representation to the original data type of a parameter an additional library ``ConfigProvider`` is offered. ``ConfigProvider`` is supposed to be integrated in a user application. ``ConfigProvider``, thus, is responsible for
+
+- establishing of communication to ``ConfigDaemon``,
+- receiving eventual parameter updates,
+- providing of typed access methods to parameters towards a user application.
+
+.. image:: _assets/config_mgmt_application_view.png
+   :width: 900
+   :alt: Application level view on configuration management.
+   :align: center
+
+Rationale
+---------
+
+No objections or concerns raised yet.
+
+Specification
+-------------
+
+``InternalConfigProviderService`` passes parameter data as json string to satisfy :need:`feat_req__config_mgmt__provider_interface`.
+
+``ConfigProvider`` library translates such a json string in a typed parameter accessible by its name from user application according to :need:`feat_req__config_mgmt__parameter_set_access`.
+
+``InternalConfigProviderService`` makes the usage of methods, events and fields. For instance
+
+- ``method GetParameterSet { in { String parameter_set_name } out { String parameter_set } }`` returns a parameter set in JSON representation in terms of :need:`feat_req__config_mgmt__parameter_set_access`
+- ``attribute InitialQualifierState InitialQualifierState readonly`` field provides qualifier state in terms of :need:`feat_req__config_mgmt__prm_initial_qualifier`
+- ``broadcast LastUpdatedParameterSet { out { ParameterSetName last_updated_parameter_set } }`` event notifies users in case a parameter set has been changed (updated) according to :need:`feat_req__config_mgmt__parameter_modification`.
+
+``LoLa`` can be used for IPC communication as soon as methods get supported.
+
+``ConfigDaemon`` uses the file system via ``json library`` to write and read files which contain parameters.
+
+Plugin infrastructure may have further dependencies, like ``SOVD`` for ``Coding`` or persistent key-value storage.
+
+Backwards Compatibility
+-----------------------
+
+No compatibility requirements imposed yet.
+
+Security Impact
+---------------
+
+``ConfigDaemon`` requires secpol abilities for IPC communication and file system accesses.
+
+Further specific mitigations shall be implemented by plugins depending on a kind of parameter.
+
+Safety Impact
+-------------
+
+Safety related parameters shall be protected by specific integrity checks. Their result will be indicated towards user applications according to :need:`feat_req__config_mgmt__prm_set_qualifier` and :need:`feat_req__config_mgmt__prm_initial_qualifier`.
+
+A safety related user application is assumed to consider a parameter as unsafe if belonging qualifier is not in a ``Qualified`` state.
+
+This feature is rated with ASIL B.
+
+License Impact
+--------------
+
+[How could the copyright impacted by the license of the new contribution?]
+
+How to Teach This
+-----------------
+
+Rejected Ideas
+--------------
+
+No ideas rejected yet.
+
+Open Issues
+-----------
+
+No open issues identified yet.
+
+Footnotes
+---------
@@ -0,0 +1,158 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2024 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Requirements
+############
+
+Terms and definitions
+=====================
+
+.. feat_req:: Term definition of Parameter
+   :id: feat_req__config_mgmt__term_parameter
+   :reqtype: Non-Functional
+   :security: NO
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   An individual vehicle configuration property used for vehicle specific adaptations is called ``Parameter``.
+
+.. feat_req:: Term definition of Parameter Set
+   :id: feat_req__config_mgmt__term_parameter_set
+   :reqtype: Non-Functional
+   :security: NO
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Group of Parameters which belong to the same functionality and share an integrity protection is called ``Parameter Set``.
+
+Data Housekeeping
+=================
+
+.. feat_req:: Central housekeeping for Parameters
+   :id: feat_req__config_mgmt__central_housekeeping
+   :reqtype: Functional
+   :security: NO
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Configuration Management shall provide a central housekeeping for Parameters.
+
+.. feat_req:: Parameter relation to a Set
+   :id: feat_req__config_mgmt__parameter_set_relation
+   :reqtype: Functional
+   :security: NO
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Every Parameter shall be contained in exactly one Parameter Set.
+
+.. feat_req:: Parameter name uniqueness
+   :id: feat_req__config_mgmt__prm_name_unique
+   :reqtype: Functional
+   :security: NO
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Parameters names shall be unique for an ECU project.
+
+.. feat_req:: Parameter name uniqueness
+   :id: feat_req__config_mgmt__prm_set_name_unique
+   :reqtype: Functional
+   :security: NO
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Parameters Set names shall be unique for an ECU project.
+
+.. feat_req:: Parameter Set configuration contents
+   :id: feat_req__config_mgmt__prm_set_cfg_content
+   :reqtype: Functional
+   :security: YES
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Parameter Set configuration shall contain a mapping of Parameters to Parameter Sets, Parameter names and default values.
+
+.. feat_req:: Parameter Set configuration source
+   :id: feat_req__config_mgmt__prm_set_cfg_source
+   :reqtype: Functional
+   :security: YES
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Parameter Set configuration shall be determined solely by a read-only input source, deployed on the target.
+
+.. feat_req:: Parameter modification
+   :id: feat_req__config_mgmt__parameter_modification
+   :reqtype: Functional
+   :security: YES
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Parameter values shall be modifiable during runtime regarding modification procedure specific for a parameter kind.
+
+Parameter Provision
+===================
+
+.. feat_req:: Config provider interface
+   :id: feat_req__config_mgmt__provider_interface
+   :reqtype: Functional
+   :security: YES
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   Configuration Management shall provide a generic interface, independent of any Parameter definitions, for applications to access Parameters in read-only mode.
+
+.. feat_req:: Parameter Set access
+   :id: feat_req__config_mgmt__parameter_set_access
+   :reqtype: Functional
+   :security: YES
+   :safety: QM
+   :satisfies: stkh_req__functional_req__file_based
+   :status: valid
+
+   A Parameter Set shall be accessible via interface using a key-value principle, where user application passes a Parameter Set name to the interface and its value is returned as result.
+
+Parameter Qualification
+=======================
+
+.. feat_req:: Parameter Set qualifier
+   :id: feat_req__config_mgmt__prm_set_qualifier
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :satisfies: stkh_req__functional_req__safe_config
+   :status: valid
+
+   A Parameter Set shall contain a qualifier to indicate its integrity.
+
+.. feat_req:: Parameter initial qualifier
+   :id: feat_req__config_mgmt__prm_initial_qualifier
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :satisfies: stkh_req__functional_req__safe_config
+   :status: valid
+
+   There shall exist an overall qualifier for all Parameter Sets to indicate the state of integrity checks at the point of time of initial provision of parameters.
@@ -0,0 +1,23 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2024 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Configuration
+#############
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :titlesonly:
+
+   */index