diff --git a/MODULE.bazel b/MODULE.bazel index 8e687088..0f6b4fca 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -89,11 +89,17 @@ bazel_dep(name = "openssl", version = "3.5.5.bcr.4") ## Custom Module Loading -bazel_dep(name = "score_docs_as_code", version = "4.0.3", dev_dependency = True) +bazel_dep(name = "score_docs_as_code", version = "4.2.0", dev_dependency = True) bazel_dep(name = "score_process", version = "1.5.4", dev_dependency = True) bazel_dep(name = "score_tooling", version = "1.2.0", dev_dependency = True) bazel_dep(name = "score_platform", version = "0.5.5", dev_dependency = True) +git_override( + module_name = "score_platform", + commit = "ef5a88b25f2e32eafeaadbef2e784aa3b7c2a18d", + remote = "https://github.com/eclipse-score/score", +) + ## Configure the python toolchain bazel_dep(name = "rules_python", version = "1.8.3", dev_dependency = True) diff --git a/docs/architecture/chklst_arc_inspection.rst b/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..03f3d3be --- /dev/null +++ b/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,185 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +Architecture Inspection Checklist +================================= + +.. document:: Baselibs Architecture Inspection Checklist + :id: doc__baselibs_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Purpose +------- + +The purpose of the software architecture checklist is to ensure that the design meets the criteria and quality as +defined per S-CORE processes and guidelines for feature and component architectural design elements. +It helps to check the compliance with requirements, identify errors or inconsistencies, and ensure adherence to best +practices. +The checklist guides evaluation of the architecture design, identifies potential problems, and aids in +communication and documentation of architectural decisions to stakeholders. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): ``_ +- reviewer: ``_ +- moderator: only needed for conflict resolution between author and reviewers, is the safety manager, security manager or quality manager called in as a reviewer (can be derived from version mgt tool) + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Architecture Design Review Checklist + :header-rows: 1 + + * - Review Id + - Acceptance criteria + - Guidance + - passed + - Remarks + - Issue link + * - ARC_01_01 + - Is the traceability from software architectural elements to requirements, and other level architectural + elements (e.g. component to interface) established according to the "Relations between the architectural elements" as described in :need:`doc_concept__arch_process`? + - Trace should be checked automatically by tool support in the future. It will be removed from the checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented. Refer to `Tool Requirements `_ for the current status. + - NO + - Several functional feature requirements are not linked to the baselibs feature architecture. + - `#2265 `_ + * - ARC_01_02 + - If the architectural element is related to any supplier manuals (incl. safety and security) + are the relevant parts covered? + - If the architecture makes use of supplied elements, their manuals (like safety) have to be considered (i.e. its provided functionality matches the expectation and assumptions are fulfilled). Note that in case of safety component this means that assumed Technical Safety Requirements and AoUs of the safety manual are covered. + - YES + - Baselibs uses OS. S-CORE's reference OS safety manual was considered during development, but cannot be published in this open source project + - + * - ARC_01_03 + - Is the architectural element traceable to the lower level artifacts as defined by the workproduct traceability? + - Will be removed from checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented by automated tool check. See `Tool Requirements `_. + Details of possible linking can be depicted from `traceability concept `_ + - YES + - Baselibs feature architecture includes logic interfaces, these can be used to link to components (see static view :need:`feat_arc_sta__baselibs__static_view_arch`) + - + * - ARC_02_01 + - Is the software architecture design compliant with the (overall) feature architecture? + - On component level check against the feature architecture, on feature level check other features with common components used. + - YES + - Shared module is the OS, which is designed to work with multiple components using it. + - + * - ARC_02_02 + - Is appropriate and comprehensible operation/interface naming present in the architectural design? + - Check :need:`gd_guidl__arch_design` + - YES + - Interfaces and operations names are abstract but sufficient for understanding. + - + * - ARC_02_03 + - Are correctness of data flow and control flow within the architectural elements considered? + - E.g. examine definitions, transformations, integrity, and interaction of data; check error handling, data + exchange between elements, correct response to inputs and documented decision making. + Note: consistency is ensured by the process/tooling, by defining each interface only once. + - YES + - There is no control/data flow between baselibs components (each of it is stand-alone), so no sequence diagram needed. + - + * - ARC_02_04 + - Are the interfaces between the software architectural element and other architectural elements well-defined? + - Check if the interface reacts on non-defined behavior or errors; can established protocols be used; are the + interfaces for inputs, outputs, error codes documented; is loose coupling considered and only limited exposure; + can unit or integration test be written against the interface; data amount transferred; no sensitive data + exposure; + - NO + - Errors are generally managed by the "Result" component (ok) + If an operation is an input or an output is not shown (nok) + Libraries are split in logical way, enable testing, data amount and sensitivity is not an issue. Maybe with the exception of JSON - add a AoU here? + - `#2265 `_ + * - ARC_02_05 + - Does the software architectural element consider the timing constraints (from the parent requirement)? + - If there are hard requirements on the timing a programming time estimation should be performed and also + deadline supervision considered. + - YES + - As the functionalities are quite small, timing should not be a problem. No requirements on timing for baselibs. + - + * - ARC_02_06 + - Is the documentation of the software architectural element, including textual and graphical descriptions + (e.g., UML diagrams), comprehensible and complete? + - Use of semi-formal notation is expected for architectural elements with an allocated ASIL level. + Is the architecture template correctly filled? + - NO + - Architecture template: Requirements section missing, but this is covered by Static View linking, Module View not needed (same as Feature Static View) (ok) + Semi-Formal Notation used (ok) + Mismatch between libraries mentioned in "Description" and the ones depicted in Static View (this also does not match with the 0.5 planning/release note) and also not matching feature request https://eclipse-score.github.io/score/main/features/baselibs/index.html (nok) + - `#2265 `_ + * - ARC_03_01 + - Is the architectural element modular and encapsulated? + - Check e.g. that only minimal interfaces are used. Design should be object oriented. Interfaces and interactions are clearly defined. Usage of access types (private, protected) properly set. Limited global variables. + - YES + - small functionality + - + * - ARC_03_02 + - Is the suitability of the software architecture for future modifications and maintainability considered? + - Check for e.g. loose coupling, separation of concerns, high cohesion, versioning strategy for interfaces, + decision records, use of established design patterns. + - YES + - Nothing which can be seen in the architecture documentation speaks against this. + - + * - ARC_03_03 + - Are simplicity and avoidance of unnecessary complexity present in the software architecture? + - Indicators for complexity are: number of use cases (corresponding to dynamic diagrams) + allocated to single design element, number of interfaces and operations in an interface, + function parameters, global variables, complex types, limited comprehensibility. + + Note: If the "number" above exceeds "3" a design rationale is mandatory (for all types) + - YES + - Baselibs is just a big container for globally shared library functions - thus offers a lot of (unconnected) interfaces. + - + * - ARC_03_04 + - Is the software architecture design following best practices and design principles? + - Refer to architectural guidelines and recommendations within the project documentation. + - YES + - Guideline :need:`gd_guidl__arch_design` is followed, template usage checked in ARC_02_06, some design principles already checked in ARC_03_02, no additional recommendations in the project's PMP + - + +.. attention:: + The above checklist entries must be filled according to your feature architecture in scope. + +Note: If a Review ID is not applicable for your architecture, then state ""n/a" in status and comment accordingly in remarks. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "baselibs" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: feat_arc_sta + :tags: baselibs + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "baselibs" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: feat_arc_dyn + :tags: baselibs + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst new file mode 100644 index 00000000..54355a5d --- /dev/null +++ b/docs/architecture/index.rst @@ -0,0 +1,122 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* +.. _baselibs_architecture: + +Architecture +===================== + +.. document:: Baselibs Architecture + :id: doc__baselibs_architecture + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__feature_arch + +Overview +-------- + +A brief overview of Baselibs is described :ref:`baselibs_feature`. + +Description +----------- + +A detailed description of the Baselibs module requirements is located :need:`feat_req__baselibs__core_utilities`. + +The Baselibs module provides foundational software utilities, safety mechanisms and robust infrastructure components. It comprises essential libraries organized into functional categories: + +**Core Utility Libraries** + +- **bitmanipulation**: Utilities for bit manipulation operations +- **containers**: Specialized container implementations including ``DynamicArray`` and intrusive linked lists +- **utils**: Reusable utilities including type traits, mathematical utilities and string manipulation helpers + +**Threading and Concurrency** + +- **concurrency**: Interface for parallel execution of C++ callables with thread pool management + +**Data Processing and Serialization** + +- **json**: JSON abstraction layer with pluggable backend support +- **static_reflection_with_serialization**: Binary serialization/deserialization with compile-time type reflection + +**File System and I/O Operations** + +- **filesystem**: Filesystem manipulation library similar to ``std::filesystem`` + +**Memory Management** + +- **memory**: Memory handling utilities for safety-critical applications with shared memory support + +**Operating System Abstraction** + +- **os**: OS Abstraction Layer (OSAL) for POSIX-like systems including Linux and QNX + +**Error Handling and Safety** + +- **result**: Error handling without exceptions, conforming to C++23 ``std::expected`` specification +- **safecpp**: Safety framework including exception prevention and overflow-safe implementations + +**Modern C++ Extensions and Logging** + +- **futurecpp**: C++14 Standard Library extensions with backported components +- **mw::log**: Logging library for automotive systems with structured logging and multiple backends + +These libraries form an integrated ecosystem designed for code reuse, consistency and safety throughout the platform. + + + +Rationale Behind Architecture Decomposition +******************************************* + +The decomposition of Baselibs into modular libraries is motivated by the need for code reuse, maintainability and consistent APIs across the platform. This approach enables platform modules to leverage common infrastructure, reduces duplication and supports safety and security requirements. + +Static Architecture +------------------- + +.. feat_arc_sta:: Baselibs Static View + :id: feat_arc_sta__baselibs__static_view_arch + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: feat_req__baselibs__core_utilities + :includes: logic_arc_int__baselibs__json, logic_arc_int__baselibs__memory_shared, logic_arc_int__baselibs__result, logic_arc_int__baselibs__bit_manipulation, logic_arc_int__baselibs__bit_mask_operator, logic_arc_int__baselibs__dynamic_array, logic_arc_int__baselibs__intrusive_list, logic_arc_int__baselibs__filesystem, logic_arc_int__baselibs__utils_base64, logic_arc_int__baselibs__utils_scoped_op, logic_arc_int__baselibs__promise, logic_arc_int__baselibs__future, logic_arc_int__baselibs__shared_future, logic_arc_int__baselibs__executor, logic_arc_int__baselibs__task, logic_arc_int__baselibs__task_result, logic_arc_int__baselibs__synchronized_queue, logic_arc_int__baselibs__condition_variable, logic_arc_int__baselibs__aborts_upon_ex, logic_arc_int__baselibs__coverage_termination, logic_arc_int__baselibs__safemath, logic_arc_int__baselibs__safeatomics, logic_arc_int__baselibs__scoped_function, logic_arc_int__baselibs__string_view + :tags: inspected + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_feature(need(), needs) }} + +.. feat_arc_dyn:: Baselibs Dynamic View + :id: feat_arc_dyn__baselibs__dynamic_view_arch + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: feat_req__baselibs__core_utilities + :belongs_to: feat__baselibs + + not needed, simple caller/callee sequence + +Logical Interfaces +------------------ + +The Baselibs feature exposes the following logical interfaces: + +.. needtable:: + :style: table + :columns: title;id;status + :sort: title + :filter: id in ['logic_arc_int__baselibs__json', 'logic_arc_int__baselibs__memory_shared', 'logic_arc_int__baselibs__result', 'logic_arc_int__baselibs__bit_manipulation', 'logic_arc_int__baselibs__bit_mask_operator', 'logic_arc_int__baselibs__dynamic_array', 'logic_arc_int__baselibs__intrusive_list', 'logic_arc_int__baselibs__filesystem', 'logic_arc_int__baselibs__utils_base64', 'logic_arc_int__baselibs__utils_scoped_op', 'logic_arc_int__baselibs__promise', 'logic_arc_int__baselibs__future', 'logic_arc_int__baselibs__shared_future', 'logic_arc_int__baselibs__executor', 'logic_arc_int__baselibs__task', 'logic_arc_int__baselibs__task_result', 'logic_arc_int__baselibs__synchronized_queue', 'logic_arc_int__baselibs__condition_variable', 'logic_arc_int__baselibs__aborts_upon_ex', 'logic_arc_int__baselibs__coverage_termination', 'logic_arc_int__baselibs__safemath', 'logic_arc_int__baselibs__safeatomics', 'logic_arc_int__baselibs__scoped_function', 'logic_arc_int__baselibs__string_view'] diff --git a/docs/bitmanipulation/docs/architecture/chklst_arc_inspection.rst b/docs/bitmanipulation/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..49966a43 --- /dev/null +++ b/docs/bitmanipulation/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Bitmanipulation Architecture Inspection Checklist + :id: doc__bitmanipulation_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: docname is not None and "bitmanipulation" in docname and "architecture" in docname and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "bitmanipulation" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/bitmanipulation/docs/architecture/index.rst b/docs/bitmanipulation/docs/architecture/index.rst new file mode 100644 index 00000000..c5e9dc54 --- /dev/null +++ b/docs/bitmanipulation/docs/architecture/index.rst @@ -0,0 +1,152 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Bitmanipulation Component Architecture +************************************** + +.. document:: bitmanipulation Architecture + :id: doc__bitmanipulation_architecture + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview/Description +-------------------- + +see :need:`doc__bitmanipulation` + +Static Architecture +------------------- + +.. comp:: Bit Manipulation + :id: comp__baselibs_bit_manipulation + :security: NO + :safety: ASIL_B + :status: valid + :tags: baselibs_bit_manipulation + :implements: logic_arc_int__baselibs__bit_manipulation,logic_arc_int__baselibs__bit_mask_operator + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Bit Manipulation Static view + :id: comp_arc_sta__baselibs__bit_manipulation + :security: NO + :safety: ASIL_B + :status: valid + :fulfils: comp_req__bitmanipulation__bit_operations,comp_req__bitmanipulation__byte_operations,comp_req__bitmanipulation__bitmask_operators,comp_req__bitmanipulation__bounds_safety,comp_req__bitmanipulation__header_only + :belongs_to: comp__baselibs_bit_manipulation + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Interfaces +---------- + +.. .. logic_arc_int:: Bit Manipulation + :id: logic_arc_int__baselibs__bit_manipulation + :security: NO + :safety: ASIL_B + :status: valid + +.. .. logic_arc_int:: Bit Mask Operator + :id: logic_arc_int__baselibs__bit_mask_operator + :security: NO + :safety: ASIL_B + :status: valid + +.. logic_arc_int_op:: Set Bit + :id: logic_arc_int_op__baselibs__set_bit + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_manipulation + +.. logic_arc_int_op:: Clear Bit + :id: logic_arc_int_op__baselibs__clear_bit + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_manipulation + +.. logic_arc_int_op:: Toggle Bit + :id: logic_arc_int_op__baselibs__toggle_bit + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_manipulation + +.. logic_arc_int_op:: Test Bit + :id: logic_arc_int_op__baselibs__test_bit + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_manipulation + +.. logic_arc_int_op:: Set (Half)-Byte + :id: logic_arc_int_op__baselibs__set_byte + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_manipulation + +.. logic_arc_int_op:: Extract (Half)-Byte + :id: logic_arc_int_op__baselibs__extract_byte + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_manipulation + +.. logic_arc_int_op:: OR operator + :id: logic_arc_int_op__baselibs__bitmask_or + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_mask_operator + +.. logic_arc_int_op:: AND operator + :id: logic_arc_int_op__baselibs__bitmask_and + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_mask_operator + +.. logic_arc_int_op:: XOR operator + :id: logic_arc_int_op__baselibs__bitmask_xor + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_mask_operator + +.. logic_arc_int_op:: Complement operator + :id: logic_arc_int_op__baselibs__bitmask_not + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_mask_operator + +.. logic_arc_int_op:: Assignment Operators + :id: logic_arc_int_op__baselibs__bitmask_assignmnt + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__bit_mask_operator diff --git a/docs/bitmanipulation/docs/detailed_design/chklst_impl_inspection.rst b/docs/bitmanipulation/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..04794e72 --- /dev/null +++ b/docs/bitmanipulation/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Bitmanipulation Implementation Inspection Checklist + :id: doc__bitmanipulation_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ , Rust ) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/bitmanipulation/docs/index.rst b/docs/bitmanipulation/docs/index.rst new file mode 100644 index 00000000..8a0b8286 --- /dev/null +++ b/docs/bitmanipulation/docs/index.rst @@ -0,0 +1,69 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +bitmanipulation +############### + +.. document:: Bit Manipulation Library + :id: doc__bitmanipulation + :status: draft + :safety: ASIL_B + :tags: baselibs_bitmanipulation + :realizes: wp__cmpt_request + :security: YES + +.. toctree:: + :hidden: + + requirements/index.rst + requirements/chklst_req_inspection.rst + architecture/index.rst + architecture/chklst_arc_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + + +Abstract +======== + +This component request proposes the integration of a safe Bit Manipulation library for constexpr bit operations and byte manipulation. It integrates a type-safe Bitmask Operator library. + + +Motivation and Rationale +======================== + +The Bit Manipulation library provides a type-safe mechanism to perform bitwise operations on integral types. +It enables safe and efficient bit operations and supports the development of safety-critical features by offering clear and reliable bit manipulation capabilities. +A Bit Manipulation library with constexpr operations is required in the S-CORE software platform to enable efficient, compile-time bit operations for embedded and automotive applications. +Typical use cases include setting control flags, extracting byte data from raw integers, and performing low-level bit operations with compile-time guarantees. +It integrates a type-safe Bitmask Operator library that extends enum class types to support standard bitmask operations ('|', '&', '^', '~', and their assignment forms). + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- + +The Bit Manipulation library should provide bit operation and byte extraction capabilities: + +* :need:`comp_req__bitmanipulation__bit_operations` +* :need:`comp_req__bitmanipulation__byte_operations` +* :need:`comp_req__bitmanipulation__bitmask_operators` +* :need:`comp_req__bitmanipulation__bounds_safety` +* :need:`comp_req__bitmanipulation__header_only` + +The component should be extensible in the future to support richer error information and integration with other platform components. diff --git a/docs/bitmanipulation/docs/requirements/chklst_req_inspection.rst b/docs/bitmanipulation/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..e19a8af7 --- /dev/null +++ b/docs/bitmanipulation/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,196 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. document:: Bitmanipulation Requirements Inspection Checklist + :id: doc__bitmanipulation_req_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + + +Requirement Inspection Checklist +================================ + + **Purpose** + + The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + + **Conduct** + + As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + + - content responsible (author): ``_ + - reviewer: ``_ + - moderator: ``_ + - test expert: ``_ + + **Checklist** + + See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + + .. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - YES + - Following requirements failed to comply with the requirements formulation template and were fixed in PR-2677: + + - :need:`aou_req__bitmanipulation__type_constraints` + - :need:`aou_req__bitmanipulation__concurrent_access` + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - YES + - The inspected requirements are clear and easy to understand. Some grammar mistakes were found and were fixed in PR-2677 and PR-2480: + + - :need:`comp_req__bitmanipulation__bit_operations` + - :need:`aou_req__bitmanipulation__type_constraints` + - :need:`aou_req__bitmanipulation__enum_constraints` + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - YES + - Following requirements had some ambiguities/weak word and were fixed in PR-2677: + + - :need:`comp_req__bitmanipulation__bit_operations` + - :need:`comp_req__bitmanipulation__bounds_safety` + - :need:`aou_req__bitmanipulation__enum_constraints` + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - YES + - One requirement was not atomic, this was fixed by splitting into these (PR-2677): + + - :need:`comp_req__bitmanipulation__bit_operations` + - :need:`comp_req__bitmanipulation__byte_operations` + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - YES + - All requirements are already implemented at the time of this inspection. + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - YES + - Note on :need:`comp_req__bitmanipulation__header_only` - It's describing an implementation constraint, so it is a "how". However, this is a justified architectural decision, and it's analogous to the "JSON format" example from the checklist. + - + * - REQ_03_01 + - Is the *linkage to the parent feature/component requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - YES + - The linkage to parent requirements is correct for all the requirements. + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. + - YES + - All the requirements are mutually consistent. However, there were inconsistencies between some requirements' titles and their descriptions, fixed in PR-2677: + + - :need:`aou_req__bitmanipulation__concurrent_access` + - :need:`aou_req__bitmanipulation__enum_constraints` + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - YES + - The overhead for bit manipulation operations is negligible. + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - YES + - For following requirements there was no description of the output, fixed in PR-2677: + + - :need:`comp_req__bitmanipulation__bit_operations` + - :need:`comp_req__bitmanipulation__bounds_safety` + + Additionally, following requirement shows mismatch with the architecture, to be fixed by architecture update: + + - :need:`comp_req__bitmanipulation__byte_operations` - "extracting bytes and manipulating half-bytes" have no corresponding interface operations in the architecture. + - #2698 + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - YES + - All safety attributes set correctly. + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - YES + - All security attributes set correctly. + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - YES + - @rahulthakre29: all requirements have test cases implemented + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - YES + - Only one requirement is relevant for this inspection - :need:`comp_req__bitmanipulation__header_only` and it's very well verifiable by design/code review. + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - YES + - There is only one requirement here that does define a safety mechanism - :need:`comp_req__bitmanipulation__bounds_safety`, findings on this were fixed in PR-2667 and PR-2696 + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + It is mandatory to fill remarks also for checklist entries which are passed, to be able to understand the verdict. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. For example "no stakeholder requirement (no rationale needed)" + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "bitmanipulation" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: bitmanipulation + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except questions REQ_03_01 and REQ_03_02): + +.. needtable:: + :filter: "bitmanipulation" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: bitmanipulation + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/bitmanipulation/docs/requirements/index.rst b/docs/bitmanipulation/docs/requirements/index.rst new file mode 100644 index 00000000..2970124d --- /dev/null +++ b/docs/bitmanipulation/docs/requirements/index.rst @@ -0,0 +1,133 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025-2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. _bitmanipulation_requirements: + +Requirements +############ + +.. document:: Bit Manipulation Requirements + :id: doc__bitmanipulation_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, bitmanipulation + +Functional Requirements +======================= + +.. comp_req:: Support for Bit Operations + :id: comp_req__bitmanipulation__bit_operations + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__bitmanipulation, feat_req__baselibs__core_utilities + :status: valid + :belongs_to: comp__baselibs_bit_manipulation + :tags: inspected + + The bit manipulation component shall provide an API for setting, clearing, toggling, and checking individual bits for any integral type up to 64 bits, returning boolean success status. + +.. comp_req:: Support for Byte and Half-Byte Operations + :id: comp_req__bitmanipulation__byte_operations + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__bitmanipulation, feat_req__baselibs__core_utilities + :status: valid + :belongs_to: comp__baselibs_bit_manipulation + :tags: inspected + + The bit manipulation component shall provide an API for extracting and setting bytes and half-bytes for any integral type up to 64 bits, returning boolean success status. + +.. comp_req:: Support for Bitmask Operators for Enum Classes + :id: comp_req__bitmanipulation__bitmask_operators + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__bitmanipulation, feat_req__baselibs__core_utilities + :status: valid + :belongs_to: comp__baselibs_bit_manipulation + :tags: inspected + + The bit manipulation library shall provide type-safe bitmask operations for scoped enumeration types. + +.. comp_req:: Bounds and Safety Checks + :id: comp_req__bitmanipulation__bounds_safety + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__bitmanipulation, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_bit_manipulation + :tags: inspected + + The bit manipulation functions shall validate input parameters against bounds and, on out-of-bounds access, shall leave the target value unmodified and return false. + +Non-Functional Requirements +=========================== + +.. comp_req:: Header-only API + :id: comp_req__bitmanipulation__header_only + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__bitmanipulation + :status: valid + :belongs_to: comp__baselibs_bit_manipulation + :tags: inspected + + The bit manipulation API shall be header-only and not require external dependencies. + +Assumptions of Use (AoU) +======================== + +.. aou_req:: Integral Type Constraints + :id: aou_req__bitmanipulation__type_constraints + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall use bit manipulation functions only with integral types (integers, enumerations) as specified in the library's type constraints. + + Note: Operations on floating-point or non-integral types are not supported. + +.. aou_req:: Bitmask Enum Value Constraints + :id: aou_req__bitmanipulation__enum_constraints + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall use scoped enumeration types (enum class) whose enumerators are defined as non-zero power-of-two values. + +.. aou_req:: External Synchronization Required for Concurrent Access + :id: aou_req__bitmanipulation__concurrent_access + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall implement external synchronization mechanisms (e.g., mutexes, atomic operations, or locks) when accessing or modifying the same integral value from multiple threads concurrently. + + Note: The library provides no internal thread safety guarantees. + +.. needextend:: "__bitmanipulation__" in id + :+tags: baselibs, bitmanipulation diff --git a/docs/bitmanipulation/docs/safety_analysis/dfa.rst b/docs/bitmanipulation/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..c8f242f4 --- /dev/null +++ b/docs/bitmanipulation/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: bitmanipulation DFA + :id: doc__bitmanipulation_dfa + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/bitmanipulation/docs/safety_analysis/fmea.rst b/docs/bitmanipulation/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..4f6a9626 --- /dev/null +++ b/docs/bitmanipulation/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: bitmanipulation FMEA + :id: doc__bitmanipulation_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/concurrency/docs/architecture/chklst_arc_inspection.rst b/docs/concurrency/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..e9e4a1d5 --- /dev/null +++ b/docs/concurrency/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Concurrency Architecture Inspection Checklist + :id: doc__concurrency_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "concurrency" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "concurrency" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/concurrency/docs/architecture/index.rst b/docs/concurrency/docs/architecture/index.rst new file mode 100644 index 00000000..3318c0aa --- /dev/null +++ b/docs/concurrency/docs/architecture/index.rst @@ -0,0 +1,280 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Concurrency Component Architecture +*********************************** + +.. document:: Concurrency Architecture + :id: doc__concurrency_architecture + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview/Description +-------------------- + +see :need:`doc__concurrency` + +Static Architecture +------------------- + +.. comp:: Concurrency + :id: comp__baselibs_concurrency + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_concurrency + :implements: logic_arc_int__baselibs__promise, logic_arc_int__baselibs__future, logic_arc_int__baselibs__shared_future, logic_arc_int__baselibs__executor, logic_arc_int__baselibs__task, logic_arc_int__baselibs__task_result, logic_arc_int__baselibs__synchronized_queue, logic_arc_int__baselibs__condition_variable + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Concurrency Static view + :id: comp_arc_sta__baselibs__concurrency + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__concurrency__task_interface, comp_req__concurrency__task_cancellation, comp_req__concurrency__simple_task, comp_req__concurrency__task_result, comp_req__concurrency__periodic_task, comp_req__concurrency__delayed_task, comp_req__concurrency__executor_interface, comp_req__concurrency__thread_pool, comp_req__concurrency__condition_variable, comp_req__concurrency__interruptible_wait, comp_req__concurrency__notification, comp_req__concurrency__synchronized_queue, comp_req__concurrency__long_running_threads, comp_req__concurrency__memory_usage_control, comp_req__concurrency__memory_reservation, comp_req__concurrency__thread_count_reporting, comp_req__concurrency__operation_timeout, comp_req__concurrency__error_handling + :belongs_to: comp__baselibs_concurrency + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Interfaces +---------- + +.. logic_arc_int_op:: Set Value + :id: logic_arc_int_op__conc__promise_setval + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__promise + +.. logic_arc_int_op:: Set Error + :id: logic_arc_int_op__conc__promise_set_error + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__promise + +.. logic_arc_int_op:: Get Future + :id: logic_arc_int_op__conc__promise_get_future + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__promise + +.. logic_arc_int_op:: On Abort + :id: logic_arc_int_op__conc__promise_on_abort + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__promise + +.. logic_arc_int_op:: Get + :id: logic_arc_int_op__conc__future_get + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Wait + :id: logic_arc_int_op__conc__future_wait + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Wait For + :id: logic_arc_int_op__conc__future_wait_for + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Wait Until + :id: logic_arc_int_op__conc__future_wait_until + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Valid + :id: logic_arc_int_op__conc__future_valid + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Share + :id: logic_arc_int_op__conc__future_share + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Then + :id: logic_arc_int_op__conc__future_then + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__future + +.. logic_arc_int_op:: Get Shared + :id: logic_arc_int_op__conc__shared_future_get + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__shared_future + +.. logic_arc_int_op:: Copy + :id: logic_arc_int_op__conc__shared_future_copy + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__shared_future + +.. logic_arc_int_op:: Enqueue + :id: logic_arc_int_op__conc__executor_enqueue + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__executor + +.. logic_arc_int_op:: Post + :id: logic_arc_int_op__conc__executor_post + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__executor + +.. logic_arc_int_op:: Submit + :id: logic_arc_int_op__conc__executor_submit + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__executor + +.. logic_arc_int_op:: Shutdown + :id: logic_arc_int_op__conc__executor_shutdown + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__executor + +.. logic_arc_int_op:: Max Concurrency Level + :id: logic_arc_int_op__conc__executor_max_conc + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__executor + +.. logic_arc_int_op:: Execute + :id: logic_arc_int_op__conc__task_execute + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__task + +.. logic_arc_int_op:: Get Stop Source + :id: logic_arc_int_op__conc__task_get_stop_source + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__task + +.. logic_arc_int_op:: Abort + :id: logic_arc_int_op__conc__task_result_abort + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__task_result + +.. logic_arc_int_op:: Aborted + :id: logic_arc_int_op__conc__task_result_aborted + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__task_result + +.. logic_arc_int_op:: Get Result + :id: logic_arc_int_op__conc__task_result_get + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__task_result + +.. logic_arc_int_op:: Push + :id: logic_arc_int_op__conc__sync_queue_push + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__synchronized_queue + +.. logic_arc_int_op:: Pop + :id: logic_arc_int_op__conc__sync_queue_pop + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__synchronized_queue + +.. logic_arc_int_op:: Try Push + :id: logic_arc_int_op__conc__sync_queue_try_push + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__synchronized_queue + +.. logic_arc_int_op:: Try Pop + :id: logic_arc_int_op__conc__sync_queue_try_pop + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__synchronized_queue + +.. logic_arc_int_op:: Wait + :id: logic_arc_int_op__conc__cv_wait + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__condition_variable + +.. logic_arc_int_op:: Wait For + :id: logic_arc_int_op__conc__cv_wait_for + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__condition_variable + +.. logic_arc_int_op:: Notify One + :id: logic_arc_int_op__conc__cv_notify_one + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__condition_variable + +.. logic_arc_int_op:: Notify All + :id: logic_arc_int_op__conc__cv_notify_all + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__condition_variable diff --git a/docs/concurrency/docs/detailed_design/chklst_impl_inspection.rst b/docs/concurrency/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..f911db35 --- /dev/null +++ b/docs/concurrency/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Concurrency Implementation Inspection Checklist + :id: doc__concurrency_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/concurrency/docs/index.rst b/docs/concurrency/docs/index.rst new file mode 100644 index 00000000..72554e94 --- /dev/null +++ b/docs/concurrency/docs/index.rst @@ -0,0 +1,46 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +concurrency +########### + +.. document:: Concurrency Library + :id: doc__concurrency + :status: draft + :safety: ASIL_B + :tags: baselibs_concurrency + :realizes: wp__cmpt_request + :security: YES + +.. toctree:: + :hidden: + + architecture/index.rst + architecture/chklst_arc_inspection.rst + requirements/index.rst + requirements/chklst_req_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +======== + +This component request proposes a concurrency library that provides abstractions for managing concurrent tasks, threads, and synchronization mechanisms. + +Motivation and Rationale +======================== + +The concurrency library shall provide safe and efficient way to handle concurrent operations. It aims to simplify the development of multi-threaded applications by offering high-level abstractions for task management, synchronization, and inter-thread communication. +The library is designed to improve code readability, maintainability, and portability across different platforms. diff --git a/docs/concurrency/docs/requirements/chklst_req_inspection.rst b/docs/concurrency/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..15b171ea --- /dev/null +++ b/docs/concurrency/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,175 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Concurrency Requirements Inspection Checklist + :id: doc__concurrency_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "concurrency" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: concurrency + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "concurrency" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: concurrency + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/concurrency/docs/requirements/index.rst b/docs/concurrency/docs/requirements/index.rst new file mode 100644 index 00000000..62b4c5b0 --- /dev/null +++ b/docs/concurrency/docs/requirements/index.rst @@ -0,0 +1,274 @@ + +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Requirements +############ + +.. document:: Concurrency Requirements + :id: doc__concurrency_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, concurrency + +Functional Requirements +======================= + +.. comp_req:: Asynchronous Task Execution + :id: comp_req__concurrency__task_interface + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall allow running tasks asynchronously. + +.. comp_req:: Task Cancellation + :id: comp_req__concurrency__task_cancellation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall allow cancelling tasks when needed. + +.. comp_req:: Simple Task Implementation + :id: comp_req__concurrency__simple_task + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide implementation for executing callable objects without returning results, supporting fire-and-forget asynchronous operations. + +.. comp_req:: Task Result Management + :id: comp_req__concurrency__task_result + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide implementation to access the result of an asynchronously running task or to request aborting the task when the result is no longer needed. + +.. comp_req:: Periodic Task Execution + :id: comp_req__concurrency__periodic_task + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide implementation for executing callable objects at regular intervals with configurable first execution time and period duration. + +.. comp_req:: Delayed Task Execution + :id: comp_req__concurrency__delayed_task + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide implementation for executing callable objects after a specified delay with support for early cancellation. + +.. comp_req:: Executor Interface + :id: comp_req__concurrency__executor_interface + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__consistent_apis + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide interface defining a common API for task submission operations, graceful shutdown, and maximum concurrency level reporting. + +.. comp_req:: Thread Pool Implementation + :id: comp_req__concurrency__thread_pool + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide implementation that manages submitted tasks in FIFO order. + +.. comp_req:: Interruptible Condition Variable + :id: comp_req__concurrency__condition_variable + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide an abortable mechanism for threads to wait for conditions. + +.. comp_req:: Interruptible Wait Utilities + :id: comp_req__concurrency__interruptible_wait + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide utilities offering APIs for sleep operations allowing early cancellation. + +.. comp_req:: Notification Mechanism + :id: comp_req__concurrency__notification + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall allow one thread to notify another thread once, with a timeout option. + +.. comp_req:: Synchronized Queue + :id: comp_req__concurrency__synchronized_queue + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide a thread-safe container facilitating FIFO transmission of data in a N:1 communication pattern. + +.. comp_req:: Long-Running Threads Container + :id: comp_req__concurrency__long_running_threads + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall provide a container for managing long-running threads, allowing addition and removal of threads. + +Non-Functional Requirements +=========================== + +.. comp_req:: Memory Usage Control + :id: comp_req__concurrency__memory_usage_control + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall limit memory usage to prevent uncontrolled resource consumption. + +.. comp_req:: Memory Reservation + :id: comp_req__concurrency__memory_reservation + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall allow reserving memory upfront for tasks to ensure predictable resource allocation. + +.. comp_req:: Thread Count Reporting + :id: comp_req__concurrency__thread_count_reporting + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall report the maximum number of concurrent threads available for task execution. + +.. comp_req:: Operation Timeout Protection + :id: comp_req__concurrency__operation_timeout + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall avoid indefinitely blocking, unabortable operations. + +.. comp_req:: Future Error Handling + :id: comp_req__concurrency__error_handling + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__concurrency_library + :status: valid + :belongs_to: comp__baselibs_concurrency + + The concurrency module shall use error codes instead of throwing exceptions. + +Assumptions of Use (AoU) +======================== + +.. aou_req:: Cooperative Cancellation Handling + :id: aou_req__concurrency__coop_cancellation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall implement cancellation logic in long-running tasks to respond to stop_token signals. + +.. aou_req:: Memory Management on Task Submission Failure + :id: aou_req__concurrency__memory_management + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall handle task submission failures when the bounded memory resource is exhausted and implement appropriate backpressure mechanisms. + +.. aou_req:: Thread Pool Sizing + :id: aou_req__concurrency__thread_pool_sizing + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall size ThreadPool according to task characteristics and avoid submitting blocking tasks that will starve the thread pool. + +.. aou_req:: Thread Safety + :id: aou_req__concurrency__thread_safety + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall implement appropriate synchronization mechanisms when sharing state between tasks, as the library only guarantees thread-safe task submission and execution scheduling. + +.. needextend:: "__concurrency__" in id + :+tags: baselibs + +.. needextend:: "__concurrency__" in id + :+tags: concurrency diff --git a/docs/concurrency/docs/safety_analysis/dfa.rst b/docs/concurrency/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..923f0af6 --- /dev/null +++ b/docs/concurrency/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: concurrency DFA + :id: doc__concurrency_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/concurrency/docs/safety_analysis/fmea.rst b/docs/concurrency/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..e9d5e602 --- /dev/null +++ b/docs/concurrency/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: concurrency FMEA + :id: doc__concurrency_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/containers/docs/architecture/chklst_arc_inspection.rst b/docs/containers/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..e6a1ac25 --- /dev/null +++ b/docs/containers/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Containers Architecture Inspection Checklist + :id: doc__containers_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "containers" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "containers" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/containers/docs/architecture/index.rst b/docs/containers/docs/architecture/index.rst new file mode 100644 index 00000000..1145a543 --- /dev/null +++ b/docs/containers/docs/architecture/index.rst @@ -0,0 +1,113 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Container Component Architecture +******************************** + +.. document:: Container Architecture + :id: doc__containers_architecture + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview/Description +-------------------- + +see :need:`doc__containers_architecture` + +Static Architecture +------------------- + +.. comp:: Containers + :id: comp__baselibs_containers + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_containers + :implements: logic_arc_int__baselibs__dynamic_array, logic_arc_int__baselibs__intrusive_list + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Containers Static view + :id: comp_arc_sta__baselibs__containers + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__containers__dynamic_array, comp_req__containers__intrusive_list, comp_req__containers__type_safety, comp_req__containers__non_relocatable_vector, comp_req__containers__deterministic_behavior + :belongs_to: comp__baselibs_containers + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + + +Interfaces +---------- + +.. logic_arc_int_op:: Access + :id: logic_arc_int_op__containers__dynarray_access + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__dynamic_array + +.. logic_arc_int_op:: Iterate + :id: logic_arc_int_op__containers__dynarray_itrate + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__dynamic_array + +.. logic_arc_int_op:: Change + :id: logic_arc_int_op__containers__dynarray_change + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__dynamic_array + +.. logic_arc_int_op:: Insert + :id: logic_arc_int_op__baselibs__intr_list_insert + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__intrusive_list + +.. logic_arc_int_op:: Remove + :id: logic_arc_int_op__baselibs__intr_list_remove + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__intrusive_list + +.. logic_arc_int_op:: Iterate + :id: logic_arc_int_op__baselibs__intr_list_iterate + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__intrusive_list + +.. logic_arc_int_op:: Access + :id: logic_arc_int_op__baselibs__intr_list_access + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__intrusive_list diff --git a/docs/containers/docs/detailed_design/chklst_impl_inspection.rst b/docs/containers/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..af8dbe3e --- /dev/null +++ b/docs/containers/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Containers Implementation Inspection Checklist + :id: doc__containers_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/containers/docs/index.rst b/docs/containers/docs/index.rst new file mode 100644 index 00000000..ccf9c17a --- /dev/null +++ b/docs/containers/docs/index.rst @@ -0,0 +1,65 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +containers +########## + +.. document:: Containers Library + :id: doc__containers + :status: draft + :safety: ASIL_B + :tags: baselibs_containers + :realizes: wp__cmpt_request + :security: YES + +.. toctree:: + :hidden: + + requirements/index.rst + requirements/chklst_req_inspection.rst + architecture/index.rst + architecture/chklst_arc_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +======== + +This component request proposes the integration of a safe Containers library for common data structures like dynamic arrays and linked lists. + +Motivation and Rationale +======================== + +The Containers library shall provide safe and efficient implementations of common data structures, such as dynamic arrays and linked lists. +Containers library shall enable developers to manage collections of data in a type-safe manner, reducing the risk of runtime errors and improving code quality. +A Containers library with type-safe data structures is needed in the S-CORE software platform due to the frequent use of collections in various features and the need for reliable data management. +There are multiple use-cases like managing lists of sensor readings, storing configuration parameters, or handling dynamic data sets. + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- + +The Containers library should provide type-safe data structures and efficient memory management capabilities: + +* :need:`comp_req__containers__dynamic_array` +* :need:`comp_req__containers__intrusive_list` +* :need:`comp_req__containers__type_safety` +* :need:`comp_req__containers__deterministic_behavior` + +The component should be extensible in the future to support additional data structures and algorithms as needed. diff --git a/docs/containers/docs/requirements/chklst_req_inspection.rst b/docs/containers/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..2d737165 --- /dev/null +++ b/docs/containers/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,176 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Containers Requirements Inspection Checklist + :id: doc__containers_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + :tags: template + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "containers" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: containers + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "containers" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: containers + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/containers/docs/requirements/index.rst b/docs/containers/docs/requirements/index.rst new file mode 100644 index 00000000..357ccf78 --- /dev/null +++ b/docs/containers/docs/requirements/index.rst @@ -0,0 +1,167 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. document:: Containers Library Requirements + :id: doc__containers_lib_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, containers_library + +Functional Requirements +======================= + +.. comp_req:: Dynamic Array + :id: comp_req__containers__dynamic_array + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__containers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_containers + + The Containers library shall provide a fixed-size array container with construction-time size specification. + +.. comp_req:: Intrusive List + :id: comp_req__containers__intrusive_list + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__containers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_containers + + The Containers library shall provide an intrusive doubly-linked list based on the C++ standardization proposal P0406R1. + +.. comp_req:: Type Safety + :id: comp_req__containers__type_safety + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__consistent_apis, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_containers + + The Containers library shall enforce compile-time type safety for all container operations. + +.. comp_req:: Non-Relocatable Vector + :id: comp_req__containers__non_relocatable_vector + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__containers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_containers + + The Containers library shall provide a non-relocatable vector container that maintains stable element addresses. + + +Non-Functional Requirements +=========================== + +.. comp_req:: Deterministic Behavior + :id: comp_req__containers__deterministic_behavior + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_containers + + The Containers library shall provide deterministic behavior with no dynamic memory allocation. + +Assumptions of Use (AoU) +======================== + +.. aou_req:: Check Capacity + :id: aou_req__containers__capacity_management + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall verify sufficient capacity or handle allocation failures before insertion operations to prevent exceeding container limits and undefined behavior. + +.. aou_req:: Iterator Validity + :id: aou_req__containers__iterator_validity + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall ensure that iterators are not used after operations that invalidate them and refresh iterators after modifying operations. + +.. aou_req:: Element Lifetime and Ownership + :id: aou_req__containers__element_lifetime + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall ensure that elements stored in containers remain valid throughout their lifetime in the container, and for intrusive containers, that element objects are not destroyed or moved while contained within the container. + +.. aou_req:: Thread Safety + :id: aou_req__containers__thread_safety + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall implement external synchronization mechanisms when accessing or modifying container objects from multiple threads concurrently, as the library provides no internal thread safety guarantees. + +.. aou_req:: Index Bounds Checking + :id: aou_req__containers__bounds_checking + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall ensure that all index-based access operations use valid indices within the container's current size range to prevent out-of-bounds access and undefined behavior. + +.. aou_req:: Container State Verification + :id: aou_req__containers__state_verification + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall verify container state before performing operations that depend on specific states, such as checking if a container is non-empty before accessing elements. + +.. aou_req:: Memory Resource Management + :id: aou_req__containers__memory_management + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall provide sufficient memory resources for all container operations. + +.. aou_req:: Element Type Requirements + :id: aou_req__containers__ele_type_requirements + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall ensure that element types are copy constructible, move constructible and destructible, and additionally for intrusive containers that they provide the required intrusive node members. + +.. needextend:: "__containers__" in id + :+tags: baselibs + +.. needextend:: "__containers__" in id + :+tags: containers diff --git a/docs/containers/docs/safety_analysis/dfa.rst b/docs/containers/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..18627863 --- /dev/null +++ b/docs/containers/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: containers DFA + :id: doc__containers_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/containers/docs/safety_analysis/fmea.rst b/docs/containers/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..e23f8e52 --- /dev/null +++ b/docs/containers/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: containers FMEA + :id: doc__containers_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/docs/index.rst b/docs/docs/index.rst new file mode 100644 index 00000000..25bc7d8f --- /dev/null +++ b/docs/docs/index.rst @@ -0,0 +1,44 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. mod:: Baselibs + :id: mod__baselibs + :includes: comp__baselibs_json, comp__baselibs_memory_shared, comp__baselibs_result, comp__baselibs_bit_manipulation, comp__baselibs_containers, comp__baselibs_filesystem, comp__baselibs_utils, comp__baselibs_concurrency, comp__baselibs_safecpp + :status: valid + :safety: ASIL_B + :security: YES + +.. mod_view_sta:: Baselibs Static View + :id: mod_view_sta__baselibs__baselibs + :includes: comp__baselibs_json, comp__baselibs_memory_shared, comp__baselibs_result, comp__baselibs_bit_manipulation, comp__baselibs_containers, comp__baselibs_filesystem, comp__baselibs_utils, comp__baselibs_concurrency, comp__baselibs_safecpp + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_module(need(), needs) }} + +.. _baselibs_module_docs: + +Module Documents +================ + +.. toctree:: + :maxdepth: 1 + :glob: + + manual/index.rst + safety_mgt/index.rst + verification/module_verification_report.rst + release/release_note.rst diff --git a/docs/docs/manual/index.rst b/docs/docs/manual/index.rst new file mode 100644 index 00000000..08ba1a6e --- /dev/null +++ b/docs/docs/manual/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Manuals +####### + +.. toctree:: + :titlesonly: + + safety_manual diff --git a/docs/docs/manual/safety_manual.rst b/docs/docs/manual/safety_manual.rst new file mode 100644 index 00000000..fc9d9ab7 --- /dev/null +++ b/docs/docs/manual/safety_manual.rst @@ -0,0 +1,113 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Safety Manual +============= + +.. note:: Document header + +.. document:: Baselibs Safety Manual + :id: doc__baselibs_safety_manual + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__module_safety_manual + + +Introduction/Scope +------------------ + +This is the safety manual for baselibs module which is a collection of several utilities of common use. + +Assumed Platform Safety Requirements +------------------------------------ + +For the Baselibs module the following safety related stakeholder requirements are assumed to define the top level functionality (purpose) of the module. I.e. from these all the feature and component requirements implemented are derived. + +- :need:`stkh_req__functional_req__base_libraries` - is QM, but some of the libraries combine this with the next requirement +- :need:`stkh_req__dependability__automotive_safety` +- :need:`stkh_req__dev_experience__prog_languages` - is QM, but some of the libraries combine this with the previous requirement + +This means that not all baselibs libraries and language API are provided in ASIL B. +So for Baselibs the definition of the assumed safety requirement(s) of each of the ASIL B libraries are defined in the following feature requirements: + +- bitmanipulation library: :need:`feat_req__baselibs__bitmanipulation` +- concurrency library: :need:`feat_req__baselibs__concurrency_library` +- containers library: :need:`feat_req__baselibs__containers_library` +- filesystem library: :need:`feat_req__baselibs__filesystem_library` +- flatbuffers library: :need:`feat_req__baselibs__flatbuffers_library` +- json library: :need:`feat_req__baselibs__json_library` +- memory library: :need:`feat_req__baselibs__memory_library` +- result library: :need:`feat_req__baselibs__result_library` +- safecpp, static_reflection_with_serialization, utils :need:`feat_req__baselibs__core_utilities` + +Assumptions of Use +------------------ + +Assumptions on the Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| Generally the assumption of the project platform SEooC is that it is integrated in a safe system, i.e. the POSIX OS it runs on is qualified and also the HW related failures are taken into account by the system integrator, if not otherwise stated in the module's safety concept. +| The platform-wide AoUs are collected in :need:`doc__platform_assumptions` +| +| To support :need:`aou_req__platform__safety_matching`: +| <List here all the OS/libcxx calls the module expects to be safe.> + +List of additional AoUs expected from the environment the module runs on: + +.. needtable:: + :style: table + :columns: title;id;status + :colwidths: 25,25,25 + :sort: title + + results = [] + + for need in needs.filter_types(["aou_req"]): + if need and "environment" in need["tags"] and "baselibs" in need["tags"]: + results.append(need) + + +Assumptions on the User +^^^^^^^^^^^^^^^^^^^^^^^ +| As there is no assumption on which specific OS and HW is used, the integration testing of the stakeholder and feature requirements is expected to be performed by the user of the platform SEooC. Tests covering all stakeholder and feature requirements performed on a reference platform (tbd link to reference platform specification), reviewed and passed are included in the platform SEooC safety case. +| Additionally the components of the platform may have additional specific assumptions how they are used. These are part of every module documentation: <link to add>. Assumptions from components to their users can be fulfilled in two ways: +| 1. There are assumption which need to be fulfilled by all SW components, e.g. "every user of an IPC mechanism needs to make sure that he provides correct data (including appropriate ASIL level)" - in this case the AoU is marked as "platform". +| 2. There are assumption which can be fulfilled by a safety mechanism realized by some other project platform component and are therefore not relevant for an user who uses the whole platform. But those are relevant if you chose to use the module SEooC stand-alone - in this case the AoU is marked as "module". An example would be the "JSON read" which requires "The user shall provide a string as input which is not corrupted due to HW or QM SW errors." - which is covered when using together with safe project platform persistency feature. + +List of AoUs on the user of the module of this safety manual: + +.. needtable:: + :style: table + :columns: title;id;status + :colwidths: 25,25,25 + :sort: title + + results = [] + + for need in needs.filter_types(["aou_req"]): + if need and "environment" not in need["tags"] and "baselibs" in need["tags"]: + results.append(need) + +Safety concept of the SEooC +--------------------------- +| <Describe here the safety concept incl. which faults are taken care of, reactions of the implemented functions under anomalous operating conditions ... if this is not already documented sufficiently in the feature documentation "safety impact" section of all the features the module is used in.> + +Safety Anomalies +---------------- +| Anomalies (bugs in ASIL SW, detected by testing or by users, which could not be fixed) known before release are documented in the platform/module release notes <add link to release note>. + +References +---------- +| <link to the user manual> +| <other links> diff --git a/docs/docs/release/release_note.rst b/docs/docs/release/release_note.rst new file mode 100644 index 00000000..320b1990 --- /dev/null +++ b/docs/docs/release/release_note.rst @@ -0,0 +1,27 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Release Note +============ + +.. note:: Document header + +.. document:: Baselibs Release Note + :id: doc__baselibs_release_note + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__module_sw_release_note + +For the release notes, see the `Baselibs releases <https://github.com/eclipse-score/baselibs/releases>`_ on GitHub. diff --git a/docs/docs/safety_mgt/index.rst b/docs/docs/safety_mgt/index.rst new file mode 100644 index 00000000..faf93567 --- /dev/null +++ b/docs/docs/safety_mgt/index.rst @@ -0,0 +1,25 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Safety Management +################# + +.. toctree:: + :titlesonly: + + module_safety_plan + module_codeowners + module_safety_plan_fdr + module_safety_package_fdr + module_safety_analysis_fdr diff --git a/docs/docs/safety_mgt/module_codeowners.rst b/docs/docs/safety_mgt/module_codeowners.rst new file mode 100644 index 00000000..072ddc85 --- /dev/null +++ b/docs/docs/safety_mgt/module_codeowners.rst @@ -0,0 +1,52 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Module Codeowners Skill Check +***************************** + +.. document:: Baselibs Codeowners + :id: doc__baselibs_codeowners + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__module_safety_plan + +Assigned Committer(s) +===================== + +According to `Baselibs Module Codeowners <https://github.com/eclipse-score/baselibs/blob/main/.github/CODEOWNERS>`_ +the following committers are assigned to guard the Baselibs repository: + +- `<https://github.com/castler>`_ +- `<https://github.com/hoe-jo>`_ +- `<https://github.com/LittleHuba>`_ +- `<https://github.com/ramceb>`_ +- `<https://github.com/nradakovic>`_ +- `<https://github.com/4og>`_ + +Skill Check +=========== + +For the CODEOWNERS the required skills, knowledge and experience is defined in `<https://eclipse-score.github.io/score/main/platform_management_plan/safety_management.html#functional-safety-management-organization>`_. + +The evidences are not published openly due to personal data confidentiality, but will be checked by the module safety manager. + +- `<https://github.com/castler>`_: SW developer and team lead for Safe POSIX SW platform at OEM > 2 years +- `<https://github.com/hoe-jo>`_: SW developer for Safe POSIX SW platform at OEM > 1.5y and safety manager for camera systems at OEM 1y, member of S-CORE process community +- `<https://github.com/LittleHuba>`_: SW developer for Safe POSIX SW platform at OEM > 2 years +- `<https://github.com/ramceb>`_: SW architect for Safe POSIX SW platform at OEM > 2 years +- `<https://github.com/nradakovic>`_: SW developer and tool expert for Safe POSIX SW platform at OEM > 2 years +- `<https://github.com/4og>`_: SW developer for safety related application at OEM > 2 years + +The S-CORE processes are trained on the job by the Baselibs module safety manager to the CODEOWNERS. diff --git a/docs/docs/safety_mgt/module_safety_analysis_fdr.rst b/docs/docs/safety_mgt/module_safety_analysis_fdr.rst new file mode 100644 index 00000000..df38697b --- /dev/null +++ b/docs/docs/safety_mgt/module_safety_analysis_fdr.rst @@ -0,0 +1,90 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +Safety Analysis Checklist +========================= + +.. document:: Baselibs Safety Analysis Checklist + :id: doc__baselibs_safety_analysis_fdr + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__fdr_reports + +**Purpose** + +The purpose of this Safety Analysis (DFA and FMEA) checklist template is to collect the topics to be checked during verification of the Safety Analysis. + +**Conduct** + +As described in :need:`wf__p_formal_rv`, the formal document review is performed by an "external" safety manager: + +- reviewer: <committer with safety manager skills explicitly named here> + +**Checklist** + +Please note that the "passed" column must contain "yes" or "no" for each checklist item. Additionally, the remarks column must explain why item passed or did not passed. In case of "no" an issue link to the issue tracking system has to be added in the last column. + +.. list-table:: Safety Analysis Checklist + :header-rows: 1 + :widths: 10,10,30,30,20 + + * - ID + - Safety analysis activity + - Compliant to ISO 26262? + - Reference + - Comment + + * - 1 + - Is it plausible that each potential identified dependent failure that has been identified, will lead to a dependent failure which cause a violation of FFI? + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_742>` + - <Rationale for result> + + * - 2 + - Are the failure initiators :need:`[[title]] <gd_guidl__dfa_failure_initiators>` / fault models :need:`[[title]] <gd_guidl__fault_models>` applied? + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_744>` + - <Rationale for result> + + * - 3 + - Are measures defined to resolute the identified potential dependent failures? + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_746>`, :need:`[[title]] <std_req__iso26262__analysis_747>` + - <Rationale for result> + + * - 4 + - Is the result of the safety analysis indicate if the safety requirements are complied? + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_842>` + - <Rationale for result> + + * - 5 + - Are for all not complied safety requirements mitigations defined to resolute the non-compliance? The mitigations shall have a direct influence on the violation by prevention, detection or mitigation to reduce the risk to an acceptable level. + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_843>` + - <Rationale for result> + + * - 6 + - Are the mitigations effective and implemented? + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_844>` + - <Rationale for result> + + * - 7 + - Are the templates for DFA and/or FMEA used? See :need:`gd_temp__comp_saf_dfa` and :need:`gd_temp__comp_saf_fmea` + - [YES | NO ] + - :need:`[[title]] <std_req__iso26262__analysis_748>`, :need:`[[title]] <std_req__iso26262__analysis_849>`, :need:`[[title]] <std_req__iso26262__analysis_8410>` + - <Rationale for result> diff --git a/docs/docs/safety_mgt/module_safety_package_fdr.rst b/docs/docs/safety_mgt/module_safety_package_fdr.rst new file mode 100644 index 00000000..0872c5ed --- /dev/null +++ b/docs/docs/safety_mgt/module_safety_package_fdr.rst @@ -0,0 +1,65 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Safety Package Formal Review Report +=================================== + +.. note:: Document header + +.. document:: Baselibs Safety Package Formal Review + :id: doc__baselibs_safety_package_fdr + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__fdr_reports + + +**1. Purpose** + +The purpose of this review checklist is to report status of the formal review for the safety package. + +**2. Checklist** + +.. list-table:: Safety Package Checklist + :header-rows: 1 + + * - Id + - Safety package activity + - Compliant to ISO 26262? + - Comment + + * - 1 + - Is a safety package provided which matches the safety plan (i.e. all planned work products referenced)? + - [YES | NO ] + - <Rationale for result> + + * - 2 + - Is the argument how functional safety is achieved, provided in the safety package, plausible and sufficient? + - NO + - The argument is intentionally not provided by the project. + + * - 3 + - Are the referenced work products available? + - [YES | NO ] + - <Rationale for result> + + * - 4 + - Are the referenced work products in released state, including the process safety audit? + - [YES | NO ] + - <Rationale for result> + + * - 5 + - If safety related deviations from the process or safety concept are documented, are these argued understandably? + - [YES | NO ] + - <Rationale for result> diff --git a/docs/docs/safety_mgt/module_safety_plan.rst b/docs/docs/safety_mgt/module_safety_plan.rst new file mode 100644 index 00000000..20f77ad2 --- /dev/null +++ b/docs/docs/safety_mgt/module_safety_plan.rst @@ -0,0 +1,811 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Module Safety Plan +****************** + +.. document:: Baselibs Safety Plan + :id: doc__baselibs_safety_plan + :status: valid + :safety: ASIL_B + :security: NO + :realizes: wp__module_safety_plan + + +Functional Safety Management Context +==================================== + +This Safety Plan adds to the :need:`doc__score_platform_safety_plan` all the module development relevant work products needed for ISO 26262 conformity. + +Functional Safety Management Scope +================================== + +This Safety Plan's scope is a SW module of the SW platform :ref:`baselibs_module_docs`. +The module consists of one or more SW components and will be qualified as a SEooC. + +Functional Safety Management Roles +================================== + +.. list-table:: Module roles + :header-rows: 1 + + * - Role + - Assignee + + * - Safety Manager + - Alexander Schemmel + + * - Module Project Manager (= Feature team lead) + - Andrey Babanin + +Tailoring +========= + +Additional to the tailoring in the SW platform project as defined in the :need:`doc__score_platform_safety_plan` we define here the additional tailoring on module level. + +Functional Safety Module Work products +====================================== + +One set of work products for the module and one set for each component of the module: + +Module Work products List +------------------------- + +.. list-table:: Module Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__module_safety_plan` + - :need:`gd_guidl__saf_plan_definitions` + - :ndf:`copy('status', need_id='gd_guidl__saf_plan_definitions')` + - this document + + * - :need:`wp__module_safety_package` + - :need:`gd_guidl__saf_package` + - :ndf:`copy('status', need_id='gd_guidl__saf_package')` + - this document (including the linked documentation) + + * - :need:`wp__fdr_reports` (module Safety Plan) + - :need:`gd_chklst__safety_plan` + - :ndf:`copy('status', need_id='gd_chklst__safety_plan')` + - :need:`doc__baselibs_safety_plan_fdr` + + * - :need:`wp__fdr_reports` (module Safety Package) + - :need:`gd_chklst__safety_package` + - :ndf:`copy('status', need_id='gd_chklst__safety_package')` + - :need:`doc__baselibs_safety_package_fdr` + + * - :need:`wp__fdr_reports` (module's Safety Analyses & DFA) + - :need:`gd_chklst__safety_analysis` + - :ndf:`copy('status', need_id='gd_chklst__safety_analysis')` + - :need:`doc__baselibs_safety_analysis_fdr` + + * - :need:`wp__audit_report` + - performed by external experts + - n/a + - see platform safety plan + + * - :need:`wp__module_safety_manual` + - :need:`gd_temp__safety_manual` + - :ndf:`copy('status', need_id='gd_temp__safety_manual')` + - :need:`doc__baselibs_safety_manual` + + * - :need:`wp__verification_module_ver_report` + - :need:`gd_temp__mod_ver_report` + - :ndf:`copy('status', need_id='gd_temp__mod_ver_report')` + - :need:`doc__baselibs_verification_report` + + * - :need:`wp__module_sw_release_note` + - :need:`gd_temp__rel_mod_rel_note` + - :ndf:`copy('status', need_id='gd_temp__rel_mod_rel_note')` + - :need:`doc__baselibs_release_note` + + +Component bitmanipulation Work products List +-------------------------------------------- + +.. list-table:: Component bitmanipulation Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__bitmanipulation_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__bitmanipulation_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__bitmanipulation_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__bitmanipulation_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__bitmanipulation_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__bitmanipulation_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__bitmanipulation_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `.h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/bitmanipulation>`_, `design <https://github.com/eclipse-score/baselibs/tree/main/score/bitmanipulation/design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/bitmanipulation>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__bitmanipulation_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component concurrency Work products List +---------------------------------------- + +.. list-table:: Component concurrency Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__concurrency_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__concurrency_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__concurrency_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__concurrency_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__concurrency_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__concurrency_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__concurrency_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `concurrency .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/concurrency>`_, `concurrency/design <https://github.com/eclipse-score/baselibs/tree/main/score/concurrency/design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `concurency/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/concurrency>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__concurrency_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component containers Work products List +--------------------------------------- + +.. list-table:: Component containers Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__containers_lib_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__containers_lib_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__containers_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__containers_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__containers_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__containers_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__containers_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `containers .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/containers>`_, `containers/design <https://github.com/eclipse-score/baselibs/tree/main/score/containers/design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `containers/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/containers>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__containers_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component filesystem Work products List +--------------------------------------- + +.. list-table:: Component filesystem Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__filesystem_lib_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__filesystem_lib_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__filesystem_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__filesystem_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__filesystem_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__filesystem_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__filesystem_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `filesystem .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/filesystem>`_, `filesystem/design <https://github.com/eclipse-score/baselibs/tree/main/score/filesystem/design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `filesystem/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/filesystem>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__filesystem_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component result Work products List +----------------------------------- + +.. list-table:: Component result Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__result_lib_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__result_lib_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__result_library_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__result_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__result_lib_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__result_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__result_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `result .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/result>`_, `result/design <https://github.com/eclipse-score/baselibs/tree/main/score/result/design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `result/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/result>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__result_lib_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component SafeCpp Work products List +------------------------------------ + +.. list-table:: Component SafeCpp Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__safecpp_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__safecpp_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__safecpp_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__safecpp_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__safecpp_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__safecpp_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__safecpp_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `safecpp .h/.cpp <https://github.com/eclipse-score/baselibs/blob/main/score/language/safecpp>`_, `safecpp/design <https://github.com/eclipse-score/baselibs/blob/main/score/language/safecpp/Readme.md>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `safecpp/test.cpp <https://github.com/eclipse-score/baselibs/blob/main/score/language/safecpp/Readme.md>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__safecpp_arc_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component Static Reflection Work products List +---------------------------------------------- + +.. list-table:: Component Static Reflection Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__static_reflect_serial_lib_req` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__static_reflect_serial_lib_req` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__static_reflection_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__static_refl_with_serial_arch` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__static_reflection_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__static_reflection_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__static_reflection_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `static_reflection .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/static_reflection_with_serialization>`_, `static_reflection/design <https://github.com/eclipse-score/baselibs/blob/main/score/static_reflection_with_serialization/serialization/ser_dser_lib.md>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `static_reflection/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/static_reflection_with_serialization>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__static_reflection_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component utils Work products List +---------------------------------- + +.. list-table:: Component utils Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__utils_lib_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__utils_lib_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__utils_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__utils_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__utils_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__utils_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__utils_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `utils .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/utils>`_, `utils/design <https://github.com/eclipse-score/baselibs/tree/main/score/utils/design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `utils/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/utils>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__utils_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - component integration not needed (no sub-components and units are independent) + +Component json Work products List +--------------------------------- + +.. list-table:: Component json Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__requirements_comp` + - :need:`gd_temp__req_comp_req` + - :ndf:`copy('status', need_id='gd_temp__req_comp_req')` + - :need:`doc__json_requirements` + + * - :need:`wp__requirements_comp_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__json_requirements` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__json_req_inspection` + + * - :need:`wp__component_arch` + - :need:`gd_temp__arch_comp` + - :ndf:`copy('status', need_id='gd_temp__arch_comp')` + - :need:`doc__json_architecture` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__json_arc_inspection` + + * - :need:`wp__sw_component_fmea` + - :need:`gd_temp__comp_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_fmea')` + - :need:`doc__json_fmea` + + * - :need:`wp__sw_component_dfa` + - :need:`gd_temp__comp_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__comp_saf_dfa')` + - :need:`doc__json_dfa` + + * - :need:`wp__sw_implementation` + - :need:`gd_guidl__implementation` + - :ndf:`copy('status', need_id='gd_guidl__implementation')` + - `json .h/.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/json>`_, `json/design <https://github.com/eclipse-score/baselibs/tree/main/score/json/detailed_design>`_ + + * - :need:`wp__verification_sw_unit_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - `json/test.cpp <https://github.com/eclipse-score/baselibs/tree/main/score/json>`_ + + * - :need:`wp__sw_implementation_inspection` + - :need:`gd_chklst__impl_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__impl_inspection_checklist')` + - :need:`doc__json_impl_inspection` + + * - :need:`wp__verification_comp_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - <Link to WP> + + * - :need:`wp__sw_component_class` + - :need:`tsf__trust__trustable-software` + - :ndf:`copy('status', need_id='gd_guidl__component_classification')` + - `TSF Report on nlohman/json <https://eclipse-score.github.io/inc_nlohmann_json/main/report.html>`_ + +All other components of the baselibs module as released in the :need:`doc__baselibs_release_note` +are not planned to be qualifiable stand alone (as SEooC), but only in context, for example as they are used +in other S-CORE modules (e.g. communication). To be qualifiable in context those come with unit tests, +are implemented according to defined coding and detailed design guidelines, achieve the required structural coverage +and fulfill the AoUs of the reference OS (e.g. don’t use banned functions). + +Link to project planning +------------------------ + +see epic `Baselibs safety work product issue for V1.0 <https://github.com/eclipse-score/baselibs/issues/148>`_ + +Module Safety Package +===================== + +To create the safety package (according to :need:`gd_guidl__saf_package`) the following +documents and work products status have to go to "valid" (after the relevant verification were performed). + +Module Documents Status +----------------------- + +For all the work product documents the status can be seen by following the "Link to WP". +A summary of the status is also documented in the project's documentation management plan. + +See :ref:`documents_docs_modules_baselibs_docs` + +Component Documents Status +-------------------------- + +For all the work product documents the status can be seen by following the "Link to WP". +A summary of the status is also documented in the project's documentation management plan. + +See :ref:`documents_docs_modules_baselibs_components` + +Component Requirements Status +----------------------------- + +.. needtable:: + :filter: docname is not None and "baselibs" in docname and "requirements" in docname + :style: table + :types: comp_req + :tags: baselibs + :columns: id;status;tags;fulfilled by + :colwidths: 25,5,20,25 + :sort: tags + +.. needpie:: Requirement Status + :labels: invalid, valid, inspected + :colors: red, yellow, green + + type == 'comp_req' and 'baselibs' in tags and status == 'invalid' + type == 'comp_req' and 'baselibs' in tags and status == 'valid' and 'inspected' not in tags + type == 'comp_req' and 'baselibs' in tags and status == 'valid' and 'inspected' in tags + +Component AoU Status +-------------------- + +.. needtable:: + :filter: docname is not None and "baselibs" in docname and "requirements" in docname + :style: table + :types: aou_req + :tags: baselibs + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: tags + +.. needpie:: AoU Status + :labels: invalid, valid, inspected + :colors: red, yellow, green + + type == 'aou_req' and 'baselibs' in tags and status == 'invalid' + type == 'aou_req' and 'baselibs' in tags and status == 'valid' and 'inspected' not in tags + type == 'aou_req' and 'baselibs' in tags and status == 'valid' and 'inspected' in tags + + +Component Architecture Status +----------------------------- + +.. needtable:: + :filter: docname is not None and "baselibs" in docname + :style: table + :types: comp_arc_sta; comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +Deviations from Module Safety Plan +---------------------------------- + +The following deviations from the module safety plan are present in the module safety package. +These are deviations from planned processes execution and/or work product results, +safety anomalies in the sense of known bugs in the software are reported in the release notes. + +<Describe here the deviations, whether they have an impact on module's safety functions, +how these can be mitigated or argued and if and when a resolution is planned.> diff --git a/docs/docs/safety_mgt/module_safety_plan_fdr.rst b/docs/docs/safety_mgt/module_safety_plan_fdr.rst new file mode 100644 index 00000000..de509be1 --- /dev/null +++ b/docs/docs/safety_mgt/module_safety_plan_fdr.rst @@ -0,0 +1,95 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Safety Plan Formal Review Report +================================ + +.. note:: Document header + +.. document:: Baselibs Safety Plan Formal Review + :id: doc__baselibs_safety_plan_fdr + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__fdr_reports + + +**1. Purpose** + +The purpose of this safety plan formal review checklist is to report status of the review for the safety plan. + +**2. Checklist** + +.. list-table:: Safety Plan Checklist + :header-rows: 1 + + * - Id + - Safety plan activity + - Compliant to ISO 26262? + - Comment + + * - 1 + - Is the rationale for the safety work products tailoring included? + - [YES | NO ] + - <Rationale for result> + + * - 2 + - Is impact analysis planned in case of re-use of SW (needed for every release following the first formal release)? + - [YES | NO ] + - <Rationale for result> + + * - 3 + - Does the safety plan define all needed activities for safety management (incl. Confirmation review and Safety Audit)? + - [YES | NO ] + - <Rationale for result> + + * - 4 + - Does the safety plan define all needed activities for System and SW development, integration and verification? + - [YES | NO ] + - <Rationale for result> + + * - 5 + - Does the safety plan define all needed activities for safety analysis and DFA? + - [YES | NO ] + - <Rationale for result> + + * - 6 + - Does the safety plan define all needed activities for supporting processes (incl. tool mgt)? + - [YES | NO ] + - <Rationale for result> + + * - 7 + - Does the safety plan document a responsible for all activities? + - [YES | NO ] + - <Rationale for result> + + * - 8 + - If OSS software components is used, is it planned to be qualified? + - [YES | NO ] + - <Rationale for result> + + * - 9 + - Is a safety manager and a project manager appointed for the project? + - [YES | NO ] + - <Rationale for result> + + * - 10 + - Is safety plan sufficiently linked to the project plan? + - [YES | NO ] + - <Rationale for result> + + * - 11 + - Is safety plan updated iteratively to show the progress? + - [YES | NO ] + - <Rationale for result> diff --git a/docs/docs/verification/module_verification_report.rst b/docs/docs/verification/module_verification_report.rst new file mode 100644 index 00000000..ccd3c88c --- /dev/null +++ b/docs/docs/verification/module_verification_report.rst @@ -0,0 +1,82 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Verification Report +=================== + +.. note:: Document header + +.. document:: Baselibs Verification Report + :id: doc__baselibs_verification_report + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__verification_module_ver_report + + +This verification report is based on the :need:`gd_temp__verification_plan`. +It covers all the components of the above stated module. + +Verification Report contains: + +**1. Verification Coverage** + +**1.1. on Requirements** + - Lists of component requirements (incl. AoU satisfied by the component) tested by which test case, passed/failed and completeness verdict + (this shall be generated by tools and accompanied by progress charts to be usable also for project steering) + - For external component Assumptions of Use: coverage by platform safety manual or feature/components incl. test case, passed/failed and completeness verdict + - This is split in a list of QM requirements tested and a separate list of tests for ASIL rated requirements. + - List of component requirements (ASIL rated) linked to inspection checklist and verdict (derived from PR export) + +**1.2. on Architecture** + - List of component architecture tags tested by which test case, passed/failed and completeness verdict + (this shall be generated by tools and accompanied by progress charts to be usable also for project steering) + - This is split in a list of QM components tested and a separate list of tests for ASIL rated components. + - List of component architecture tags (ASIL rated) linked to inspection checklist and verdict (derived from PR export) + +**1.3. on Detailed Design** + - List of detailed design tags tested by which test case, passed/failed and completeness verdict + (this shall be generated by tools and accompanied by progress charts to be usable also for project steering) + - This is split in a list of QM components tested and a separate list of tests for ASIL rated components. + - List of detailed design tags (ASIL rated) linked to inspection checklist and verdict (derived from PR export) + + - The lists may also contain other verification methods like "Analysis" - process tbd + +**2. DFA Report** + - List of the performed component DFA, pass/fail with open mitigations + +**3. Safety Analysis Report** + - List of the performed component Safety Analysis, pass/fail with open mitigations + +**4. Unit Verification Coverage** + +**4.1. Structural Coverage** + - List of the units with C0(line) and C1(branch) coverage absolute and percentage + (this shall be generated by tools and accompanied by progress charts to be usable also for project steering) + - List includes a column for the safety rating of each unit. + +**4.2. Static Code Analysis** + - List of the units with compiler warning numbers and coding rule violation numbers + (this shall be generated by tools and accompanied by progress charts to be usable also for project steering) + - List includes a column for the safety rating of each unit. + +**4.3. Manual Code Inspection** + - List of components (ASIL rated) linked to inspection checklist and verdict (derived from PR export) + +**5. Software component qualification verification report** + - Contains the needed verification results if for some components a qualification of pre-developed SW is performed. + +**Note1:** The verification report is valid for the module version tagged together with the report + +**Note2:** All the above lists are generated automatically diff --git a/docs/filesystem/docs/architecture/chklst_arc_inspection.rst b/docs/filesystem/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..48578c86 --- /dev/null +++ b/docs/filesystem/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Filesystem Architecture Inspection Checklist + :id: doc__filesystem_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "filesystem" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "filesystem" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/filesystem/docs/architecture/index.rst b/docs/filesystem/docs/architecture/index.rst new file mode 100644 index 00000000..92b819f2 --- /dev/null +++ b/docs/filesystem/docs/architecture/index.rst @@ -0,0 +1,223 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Filesystem Component Architecture +********************************** + +.. document:: Filesystem Architecture + :id: doc__filesystem_architecture + :status: valid + :security: YES + :safety: ASIL_B + :realizes: wp__component_arch + +Overview/Description +-------------------- +see :need:`doc__filesystem` + +Static Architecture +------------------- + +.. comp:: Filesystem + :id: comp__baselibs_filesystem + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_filesystem + :implements: logic_arc_int__baselibs__filesystem + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Filesystem Static view + :id: comp_arc_sta__baselibs__filesystem + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__filesystem__api_abstraction, comp_req__filesystem__path_utilities, comp_req__filesystem__directory_iterators, comp_req__filesystem__file_io, comp_req__filesystem__full_testability, comp_req__filesystem__file_utils, comp_req__filesystem__mock_fake + :belongs_to: comp__baselibs_filesystem + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Interfaces +---------- + +.. logic_arc_int_op:: Path Canonicalization + :id: logic_arc_int_op__baselibs__absolute + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: File/Directory Existence Check + :id: logic_arc_int_op__baselibs__exists + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: File Type Detection + :id: logic_arc_int_op__baselibs__file_type + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: File Status Query + :id: logic_arc_int_op__baselibs__file_status + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Copy File + :id: logic_arc_int_op__baselibs__copy_file + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Remove File or Directory + :id: logic_arc_int_op__baselibs__remove + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Modify File Permissions + :id: logic_arc_int_op__baselibs__permissions + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Create Directory + :id: logic_arc_int_op__baselibs__create_directory + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Symlink Operations + :id: logic_arc_int_op__baselibs__symlink_ops + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Hard Link Operations + :id: logic_arc_int_op__baselibs__hardlink_ops + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Last Write Time + :id: logic_arc_int_op__baselibs__last_write_time + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Current Path + :id: logic_arc_int_op__baselibs__current_path + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Empty Check + :id: logic_arc_int_op__baselibs__is_empty + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Directory Creation with Permissions + :id: logic_arc_int_op__baselibs__create_dir_perms + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: File Content Comparison + :id: logic_arc_int_op__baselibs__file_comparison + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Group Ownership Management + :id: logic_arc_int_op__baselibs__change_group + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Group Validation + :id: logic_arc_int_op__baselibs__validate_group + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Check Filesystem + :id: logic_arc_int_op__baselibs__check_filesystem + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Repair Filesystem + :id: logic_arc_int_op__baselibs__repair_filesystem + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Partition Formatting + :id: logic_arc_int_op__baselibs__format_partition + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: QNX Compatibility Check + :id: logic_arc_int_op__baselibs__qnx_compatible + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Directory Synchronization + :id: logic_arc_int_op__baselibs__sync_directory + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem + +.. logic_arc_int_op:: Unique File Creation + :id: logic_arc_int_op__baselibs__open_unique_file + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__filesystem diff --git a/docs/filesystem/docs/detailed_design/chklst_impl_inspection.rst b/docs/filesystem/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..b50dd5f9 --- /dev/null +++ b/docs/filesystem/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Filesystem Implementation Inspection Checklist + :id: doc__filesystem_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/filesystem/docs/index.rst b/docs/filesystem/docs/index.rst new file mode 100644 index 00000000..98b171a8 --- /dev/null +++ b/docs/filesystem/docs/index.rst @@ -0,0 +1,66 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +filesystem +############## + +.. document:: Filesystem Library + :id: doc__filesystem + :status: draft + :safety: ASIL_B + :security: YES + :tags: baselibs_filesystem + :realizes: wp__cmpt_request + +.. toctree:: + :hidden: + + requirements/index.rst + requirements/chklst_req_inspection.rst + architecture/index.rst + architecture/chklst_arc_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +======== + +The Filesystem Library provides a set of APIs for file and directory manipulation, including creation, deletion, and traversal of the filesystem. It aims to offer a consistent and safe interface for filesystem operations across different platforms. + +Motivation and Rationale +======================== + +The Filesystem Library is essential for applications that require interaction with the underlying filesystem. It provides a standardized way to perform file operations, ensuring safety and reliability. +The library is designed to handle various filesystem tasks while adhering to safety standards required for critical systems. + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- + +The Filesystem Library should provide robust and safe APIs for filesystem operations: + +* :need:`comp_req__filesystem__api_abstraction` +* :need:`comp_req__filesystem__path_utilities` +* :need:`comp_req__filesystem__directory_iterators` +* :need:`comp_req__filesystem__file_io` +* :need:`comp_req__filesystem__full_testability` +* :need:`comp_req__filesystem__file_utils` +* :need:`comp_req__filesystem__mock_fake` + +The library should ensure that all filesystem operations are performed safely, with appropriate error handling and resource management to prevent leaks and ensure system stability. diff --git a/docs/filesystem/docs/requirements/chklst_req_inspection.rst b/docs/filesystem/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..9d40ffaf --- /dev/null +++ b/docs/filesystem/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,175 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. document:: Filesystem Requirements Inspection Checklist + :id: doc__filesystem_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "filesystem" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: filesystem + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "filesystem" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: filesystem + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/filesystem/docs/requirements/index.rst b/docs/filesystem/docs/requirements/index.rst new file mode 100644 index 00000000..fb9050d4 --- /dev/null +++ b/docs/filesystem/docs/requirements/index.rst @@ -0,0 +1,170 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. document:: Filesystem Library Requirements + :id: doc__filesystem_lib_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, filesystem_library + +Functional Requirements +======================= + +.. comp_req:: Standard Filesystem Abstraction + :id: comp_req__filesystem__api_abstraction + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__consistent_apis, feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The Filesystem library shall provide filesystem API based on the C++ standardization. + +.. comp_req:: Path Manipulation Utilities + :id: comp_req__filesystem__path_utilities + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__consistent_apis, feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The Filesystem library shall provide type-safe utilities for path construction and manipulation. + +.. comp_req:: Directory Iterators + :id: comp_req__filesystem__directory_iterators + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The Filesystem library shall provide directory iterator types for traversing directory contents. + +.. comp_req:: File I/O Operations + :id: comp_req__filesystem__file_io + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The Filesystem library shall provide functionality for reading from and writing to files, including buffered I/O operations. + +.. comp_req:: Fully testable public API + :id: comp_req__filesystem__full_testability + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The public API of the library shall support dependency injection with test doubles. + + Note: This enables full testability of the user code. + +.. comp_req:: File Utility Functions + :id: comp_req__filesystem__file_utils + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The Filesystem library shall provide additional file utility functions, such as temporary file handling and file comparison. + +.. comp_req:: Mock and Fake Implementations + :id: comp_req__filesystem__mock_fake + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__filesystem_library + :status: valid + :belongs_to: comp__baselibs_filesystem + + The Filesystem library shall provide mock and fake implementations for unit testing and validation. + +Assumptions of Use (AoU) +======================== + +.. aou_req:: Low-Level Use Only + :id: aou_req__filesystem__low_level_use_only + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall use this library only when they need to manipulate files, directories, and paths at the operating system level beyond what higher-level storage abstractions provide, accepting reduced portability to other platforms. + +.. aou_req:: Supported Path Formats + :id: aou_req__filesystem__supported_path_formats + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall not use Windows paths with this library. + +.. aou_req:: Error Handling + :id: aou_req__filesystem__error_handling + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall handle all function return values and take appropriate action on errors. + +.. aou_req:: Path Validation + :id: aou_req__filesystem__path_validation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + + User shall ensure that all paths passed to the filesystem library are valid and originate from trusted sources. + + Note: The library does not perform any path sanitization or validation. + +.. aou_req:: Thread Safety + :id: aou_req__filesystem__thread_safety + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall implement appropriate synchronization mechanisms when accessing shared filesystem resources concurrently. + +.. aou_req:: Performance + :id: aou_req__filesystem__performance + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + Users shall not assume any performance characteristics. + + Note: Filesystem operations are subject to underlying OS and storage performance. + +.. needextend:: "__filesystem__" in id + :+tags: baselibs, filesystem diff --git a/docs/filesystem/docs/safety_analysis/dfa.rst b/docs/filesystem/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..6c7d2152 --- /dev/null +++ b/docs/filesystem/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: filesystem DFA + :id: doc__filesystem_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/filesystem/docs/safety_analysis/fmea.rst b/docs/filesystem/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..c04aba5c --- /dev/null +++ b/docs/filesystem/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: filesystem FMEA + :id: doc__filesystem_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/flatbuffers/docs/_assets/config_use_case_overview.drawio.svg b/docs/flatbuffers/docs/_assets/config_use_case_overview.drawio.svg new file mode 100644 index 00000000..f1d1a076 --- /dev/null +++ b/docs/flatbuffers/docs/_assets/config_use_case_overview.drawio.svg @@ -0,0 +1,636 @@ +<svg host="65bd71144e" xmlns="http://www.w3.org/2000/svg" style="background: transparent; background-color: transparent;" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="557px" height="717px" viewBox="-0.5 -0.5 557 717" content="<mxfile linkTarget="_top" scale="1" border="0"><diagram name="Page-1" id="JKaw5B2ZcuXeohqUGU1C">7Vzrc9q4Fv9rmEl2Bo+fPD7m1XTudm+zzfbu7aeMsAWoMRa15QT2r7+SJRnLEuCADdnuTTuJJQtZPud3njqi590sVvcpWM5/wxGMe64drXrebc91nSBw6B/Ws+Y9wdjmHbMURWLQpuMR/QVFpxyWowhmykCCcUzQUu0McZLAkCh9IE3xqzpsimP1qUswg1rHYwhivfdPFJE57x0F9qb/I0SzuXyyY4s7CyAHi45sDiL8Wuny7nreTYox4VeL1Q2MGfEkXfjnPmy5Wy4shQlp8oGP6HMYJOHn58nD+mNwG/76Kbb7Qz7LC4hz8cI9dxDT+a6nmE5LV03WghSDHzmWN/pZwagrOsDxl5TZ15v79GrG/v4B0hkkcjq6Lj4jvylIUk7upjhPIsiWatPbr3NE4OMShOzuK0UW7ZuTRUxbDr18gSlBlEdXMZoltI9gNgCIVsrZcR2BbF7MyD6S0clQMvsiWOWWa6gSUNCUTQ9XlS5B0HuIF5CkazpE3JUwEOB2Rp7l8Z7XDVgCiYB5BSiuLzqBAOisnHzDQ3oh2GhmafB9Ab79uHfxl2D1/PvjKrzHN3030HiahTiFTwsc5ZTcHVC+BUq6QaCQ0nVMpHT9QCelMw66IuXIIB418sEkumJ6hrYSnECVXCpt4QqR/1auv1Wub1fVxlo0FAhjBmHCbgXFwIS+Yjkda3wTA4vGZsKiJWfcyqoM52ko3skXipZLMKf86/wPOx8vgvWfOXj4+vvUw6v+QJADRooS1ZlclQaDMMi+FMaAoBdV9Zq4Kp7wgFGhpCSGbNuyKz+up0BqMKyJHH9lMUlVc9bmLQVYTOS7Q4lNORUnlTZVgbqSDkcAcWCWaaaCvasJyGCMJtk7FW3HbSLajmcARnei7bj7RftN5MtIip/hDY5xulEFLVDPo9SiyC1/HIWWgW8gpT+wPE8nZhsWx6gGfF/XilQjPIomTskcz3AC4rtNb001bsZ8wgx3BUm/Q0LWwiUEOcEqwRtpMvN6vYb6zWuo3o7UW31H1S9e0ExRHaJdnr5+Bv+5HX0b/3p39xh8Dv+Vw77E5EYUYgwiI08/gQl18BU+SLcrpHyAqUGRLFAUcZZD6jaCSTEfY/qSvVDxisF1L7g18nQn4DQpKuMA8ZRe1dU2SVfftlzPV6jvHGeL1pKnNQuBp9MMHsu+XSitsI8SYYpm1gQlGhPLKERxL+wGumyK4lh29SjR/HFQDI4ZJB5whgjCRhx8qg2YYELwYq8bX86DcxKjhC5HRnhstfQ9luyVFqsZCzytFwjBwooAAU90oS3p3qEqlzR4tVxd2xrslu9bOxBznLLV2c2l1Z7k0yklmAi4IvQigy2QRPy10XTNLzLGiU1kVhl7nBFsw1vQiG5bgUb0oYHoA9cadER0mcU4rYUzxgsW9aZ2hQyHm0Xpze81i37rdvE45uyViLcZshhOyUnMWLBNON5sxigq3NFAkZu+e5wdk7GP6m/2R6eyasHw/YjcbokrA/Ey9q586thQ3Ewbu6GkyqTKe5FUW5NUEIYwy9jDVCO1RXRPbY2oVFk1/9BzXWvYzCD53RkkPck3pRzkVDsyEdCBEfdkcL+HYvXApz166Zm8OQQRTPs4iddsbt1tClNAIL1lWVZDX4lSh3RlU5iu4ln3Zi56exkIjZlDU/5mbHKDu2LnQFckurV4Q2LWqMH3pVKlrZB247h0biNr0DRxIeXonSRm/do+iV8HRtNMbD1RQlVxZ4lYM/D0XEkrwHtTDr/dfYSfGng/De48HWYn8IYP9GzNXvTw7IFrY3Sexh0eyDTmRpnkmb5B+37yrhKFreRdbVfuwbQbsTqqu973ajLfXcgqcVjh59eMBTH2a4oIgYnJycQRfKeZOL+27ekOAmt8ylScceNufA5F2Eg3mfcZ371qMm846zm1GUwgj4hsDlp7SgMNHdGyK1uCRGHUtgIid0sBEV35dfH/w5c8qxYS8ZnVp+2RnTOk/HahtxUF6g+8oB0vSRHzcQfq0iwawVl8GumbWLb0R7h7Mh7tzvLRxgNMEX1rZm2buyy71ELXO8tOzXF1fKeh40ojGLCuDBOI3/okz3brT6phhs/YblmMbnDpJYoKLaUppo0Ca0NldON27RSUdtyuIKi5XUdueMup3VqpToeKQ+N6z7eV9OeH4plXrC80IOGC+UtLqkXoJAjQ349UCmKQPjMy5DHMLhtiJHuGJJwL/oJsyfenp2jFNBRnOEzvXiDne5G3a7L//uYtdb5zXkdiudGuYba+e77IQgCt4u4yRRm0WI11O16kVyvKs9VtKlarpLmUPnUfh7pX6Y0svyt/R4dUndczanqWzQnyZtn0a8mKwDXse5uK5NyuXG3dB9SIcnyJHKUSASjZYVN3Mmw/Dqvlw4aquM6opwf3hzjLExA+zwoq90NOOOYzo4RKPoiNbrMo/pmyetCdLvMk3edEn2K5F1k4hwtweZx/ryjig/Vuk7qnwGb/DlHSe+qejGVOezU3tbIohBZlegiXJLMyOv4pZ/PR+xGiHzujvJ1UWznnTZFSK+cMa2lS29+XKGWt9qIKYTOryYZzRh/lnqCwaEP/xGXz2083KRm4Ql9+zxqXxCnqwyi2u+KFtvVGXSO8wklMQZyJNzragRuopyh8z+CWGGsgve14OUrQR+eQ88OF0nCY5jRCeZxDbJKdOtl/wh32v+nRp8FAVbUHn3Wq73Tag+50tvFE6vs9S2Jc7js7SlKzuM5wbPnV4NtrhIq2eKkXqUVwGeO1kcUnz7Xtgl8bJbnOUCYx2s20OWN11k4Sb7vAvssm/HPOlxTrui7jXbn0CE5BHpNdSuXgAyiOMzZlyzo7gGIEgV5J+YgWyxhNUZFQLXftbLgCtF+vZ9heJdmGnJ+vTtKt7ZcPpC2tnnI1+QD1CoVDWGUSza3pG/HdDmEpbZukjMfthDGtxDZh7cWaHzpOwAJmPNXHmr+tb4o4io64h0S2LuSnXjBi4Phlkk8v1ayO+q0Qb8xDHfIiO9NfJ18NxWceskdSWaHNZJItm+TZKsm1dDa5oBNThNjyz6Ux07ZhkflhtcxbUfZs94bnZlZtrbahaw82r6IXkIQweqQ+IEpm7LTBL5m4vrgsP39mWA5vz7wCtc79bJJgG9jVOhbfmMAmKUgyaRwMotUMptRUee4TB+oTcyW2ga9JAvz84KuZ9T2bP7VSmxbs7bbi3moC2lSc5rRxyuRNuzsH2luqq7mzSdHEPiXEYIISUNAhlBaXHXcs6gzPLMJFYF2gu1waX3hFMVf0cidWruJ9bJGoiwpp/++MqKspCieYZGQ5NaFFrPojR2nh2QNCUjTJSVn6ZxfBcFZothKOtY3Hc2GQqVcJvxP4VhXIN3Ku+uU4bvtKb6R2Y2Mo/nbq2bVr4ZBJP48M+nncgnrWM0//xgRypt7w6lWxEcrgKw+b0gsUc026LH7LYP4fE8Kq39QUjHyNZcZ67wMiWNrcfPchT1BtvkHSu/sf</diagram></mxfile>"> + <defs/> + <g> + <g> + <rect x="25" y="168.3" width="520" height="240" fill="#ffffff" stroke="#000000" stroke-dasharray="3 3" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe flex-end; width: 516px; height: 1px; padding-top: 175px; margin-left: 25px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: right; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <font style="font-size: 14px;"> + Target + </font> + </div> + </div> + </div> + </foreignObject> + <text x="541" y="187" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="end"> + Target + </text> + </switch> + </g> + </g> + <g> + <rect x="230" y="198.3" width="245" height="195" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 243px; height: 1px; padding-top: 205px; margin-left: 231px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + score_module + </div> + </div> + </div> + </foreignObject> + <text x="353" y="217" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + score_module + </text> + </switch> + </g> + </g> + <g> + <path d="M 175 625 L 395 313.55" fill="none" stroke="#000000" stroke-opacity="0.5" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="100" y="198.3" width="130" height="195" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 128px; height: 1px; padding-top: 205px; margin-left: 101px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + score::baselibs + </div> + </div> + </div> + </foreignObject> + <text x="165" y="217" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + score::baselibs + </text> + </switch> + </g> + </g> + <g> + <rect x="288.67" y="39.3" width="46.33" height="40" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));"/> + </g> + <g> + <path d="M 145 266.8 L 115 266.8 L 91.37 266.41" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 86.12 266.32 L 93.18 262.94 L 91.37 266.41 L 93.06 269.93 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 255px; margin-left: 123px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + load + </div> + </div> + </div> + </foreignObject> + <text x="123" y="259" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + load + </text> + </switch> + </g> + </g> + <g> + <path d="M 80.68 287.39 L 78.12 288.3 L 76.11 285.97 L 75.77 285.97 L 73.79 288.23 L 71.2 287.28 L 71.71 284.48 L 71.46 284.27 L 68.18 284.66 L 67.12 282.51 L 69.89 280.77 L 69.88 280.55 L 67.2 278.85 L 68.24 276.65 L 71.7 277.08 L 71.88 276.92 L 71.34 274.18 L 74.03 273.27 L 75.98 275.59 L 76.31 275.57 L 78.33 273.33 L 80.9 274.23 L 80.42 277.02 L 80.72 277.21 L 83.96 276.84 L 85 278.99 L 82.37 280.68 L 82.34 281 L 84.95 282.67 L 83.87 284.86 L 80.56 284.4 L 80.27 284.66 L 80.68 287.39 Z M 48.8 280.72 C 47.45 280.72 45 279.59 45 277.25 L 45 244.2 L 68.81 244.2 L 76.82 250.93 L 76.82 272.96 L 76.21 273.66 L 74.51 271.73 L 69.77 273.36 L 70.11 275.67 L 67.32 275.29 L 65.32 279.24 L 67.57 280.62 L 67.4 280.72 L 48.8 280.72 Z" fill="#4495d1" stroke="none" pointer-events="all" style="fill: light-dark(rgb(68, 149, 209), rgb(61, 131, 183));"/> + <path d="M 70.87 265 C 71.49 265 71.58 264.39 71.58 263.65 C 71.58 262.88 71.5 262.14 70.86 262.14 C 70.33 262.14 70.06 262.48 70.12 263.63 C 70.12 264.66 70.33 265.02 70.87 265 L 70.87 265 Z M 70.8 265.65 C 69.54 265.65 69.13 265.02 69.13 263.51 C 69.13 262.24 69.64 261.48 70.88 261.48 C 71.95 261.47 72.56 261.93 72.56 263.56 C 72.56 265.17 71.94 265.65 70.8 265.65 L 70.8 265.65 Z M 55.17 265 C 55.79 265 55.89 264.38 55.89 263.64 C 55.89 262.87 55.8 262.13 55.16 262.13 C 54.63 262.13 54.37 262.47 54.42 263.63 C 54.42 264.66 54.63 265.01 55.17 265 L 55.17 265 Z M 55.1 265.65 C 53.84 265.65 53.43 265.02 53.43 263.51 C 53.43 262.24 53.95 261.47 55.18 261.47 C 56.25 261.47 56.87 261.93 56.87 263.55 C 56.87 265.17 56.24 265.65 55.1 265.65 L 55.1 265.65 Z M 60.59 258.57 C 61.21 258.57 61.31 257.95 61.31 257.21 C 61.31 256.44 61.23 255.7 60.59 255.7 C 60.05 255.7 59.79 256.04 59.85 257.19 C 59.85 258.22 60.05 258.58 60.59 258.57 Z M 60.53 259.22 C 59.26 259.22 58.86 258.59 58.86 257.07 C 58.85 255.8 59.37 255.04 60.61 255.04 C 61.68 255.03 62.29 255.5 62.29 257.12 C 62.29 258.74 61.66 259.22 60.53 259.22 Z M 53.87 273.88 C 53.68 273.98 53.47 273.98 53.47 273.85 L 53.47 273.55 C 53.47 273.46 53.53 273.35 53.76 273.23 L 54.73 272.72 L 55.51 272.72 L 55.51 276.22 L 56.19 276.22 C 56.37 276.22 56.48 276.31 56.48 276.44 L 56.48 276.68 C 56.48 276.82 56.39 276.88 56.22 276.88 L 53.76 276.88 C 53.59 276.88 53.47 276.84 53.47 276.69 L 53.47 276.41 C 53.47 276.28 53.59 276.22 53.74 276.22 L 54.51 276.22 L 54.51 273.58 L 53.87 273.88 Z M 65.02 262.66 C 64.82 262.76 64.62 262.76 64.62 262.63 L 64.62 262.33 C 64.62 262.24 64.68 262.13 64.9 262.01 L 65.88 261.5 L 66.65 261.5 L 66.65 265 L 67.33 265 C 67.51 265 67.63 265.09 67.63 265.22 L 67.63 265.46 C 67.63 265.6 67.54 265.66 67.37 265.66 L 64.91 265.66 C 64.74 265.66 64.62 265.62 64.62 265.47 L 64.62 265.18 C 64.62 265.06 64.73 265 64.88 265 L 65.65 265 L 65.65 262.36 L 65.02 262.66 Z M 59.62 262.64 C 59.42 262.74 59.21 262.74 59.21 262.61 L 59.21 262.31 C 59.21 262.22 59.27 262.11 59.5 261.99 L 60.47 261.48 L 61.25 261.48 L 61.25 264.98 L 61.93 264.98 C 62.11 264.98 62.23 265.06 62.23 265.2 L 62.23 265.44 C 62.23 265.58 62.14 265.63 61.97 265.63 L 59.51 265.63 C 59.33 265.63 59.21 265.6 59.21 265.44 L 59.21 265.16 C 59.21 265.04 59.33 264.98 59.48 264.98 L 60.25 264.98 L 60.25 262.34 L 59.62 262.64 Z M 48.74 262.64 C 48.54 262.74 48.34 262.74 48.34 262.61 L 48.34 262.31 C 48.34 262.22 48.4 262.11 48.62 261.99 L 49.6 261.48 L 50.37 261.48 L 50.37 264.98 L 51.05 264.98 C 51.23 264.98 51.35 265.06 51.35 265.2 L 51.35 265.44 C 51.35 265.58 51.26 265.63 51.09 265.63 L 48.63 265.63 C 48.46 265.63 48.34 265.6 48.34 265.44 L 48.34 265.16 C 48.34 265.04 48.45 264.98 48.6 264.98 L 49.37 264.98 L 49.37 262.34 L 48.74 262.64 Z M 68.71 250.93 L 68.71 245.82 L 74.6 250.93 L 68.71 250.93 Z M 76.09 283.61 C 74.13 283.61 72.63 282.39 72.63 280.65 C 72.63 279.24 74.13 277.89 76.05 277.89 C 77.96 277.89 79.47 279.14 79.47 280.87 C 79.47 282.15 78.15 283.61 76.09 283.61 L 76.09 283.61 Z" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + <path d="M 60.38 276.26 C 60.99 276.26 61.09 275.64 61.09 274.9 C 61.09 274.14 61.01 273.4 60.37 273.4 C 59.84 273.4 59.57 273.74 59.63 274.89 C 59.63 275.92 59.84 276.28 60.38 276.26 L 60.38 276.26 Z M 60.31 276.91 C 59.04 276.91 58.64 276.28 58.64 274.77 C 58.63 273.5 59.15 272.74 60.39 272.74 C 61.46 272.73 62.07 273.19 62.07 274.82 C 62.07 276.43 61.44 276.91 60.31 276.91 Z M 49.77 276.24 C 50.39 276.24 50.49 275.62 50.49 274.88 C 50.49 274.11 50.4 273.37 49.76 273.37 C 49.23 273.37 48.96 273.71 49.02 274.87 C 49.02 275.9 49.23 276.25 49.77 276.24 L 49.77 276.24 Z M 49.7 276.89 C 48.44 276.89 48.03 276.26 48.03 274.74 C 48.03 273.47 48.55 272.71 49.78 272.71 C 50.85 272.71 51.46 273.17 51.46 274.79 C 51.46 276.41 50.84 276.89 49.7 276.89 L 49.7 276.89 Z M 71.87 270.94 C 72.48 270.94 72.58 270.32 72.58 269.58 C 72.58 268.81 72.5 268.07 71.86 268.07 C 71.33 268.07 71.06 268.41 71.12 269.57 C 71.12 270.6 71.33 270.95 71.87 270.94 L 71.87 270.94 Z M 71.8 271.59 C 70.53 271.59 70.13 270.96 70.13 269.45 C 70.12 268.17 70.64 267.41 71.88 267.41 C 72.95 267.41 73.56 267.87 73.56 269.49 C 73.56 271.11 72.94 271.59 71.8 271.59 L 71.8 271.59 Z M 65.91 270.91 C 66.53 270.91 66.63 270.29 66.63 269.55 C 66.63 268.79 66.54 268.05 65.9 268.05 C 65.37 268.05 65.11 268.38 65.16 269.54 C 65.16 270.57 65.37 270.92 65.91 270.91 L 65.91 270.91 Z M 65.84 271.56 C 64.58 271.56 64.17 270.93 64.17 269.42 C 64.17 268.15 64.69 267.38 65.92 267.38 C 66.99 267.38 67.61 267.84 67.61 269.47 C 67.61 271.08 66.98 271.56 65.84 271.56 L 65.84 271.56 Z M 54.99 270.92 C 55.61 270.92 55.71 270.3 55.71 269.56 C 55.71 268.79 55.63 268.06 54.99 268.06 C 54.45 268.06 54.19 268.39 54.25 269.55 C 54.25 270.58 54.45 270.93 54.99 270.92 L 54.99 270.92 Z M 54.93 271.57 C 53.66 271.57 53.26 270.94 53.26 269.43 C 53.25 268.16 53.77 267.39 55.01 267.39 C 56.08 267.39 56.69 267.85 56.69 269.47 C 56.69 271.09 56.06 271.57 54.93 271.57 L 54.93 271.57 Z M 70.87 258.6 C 71.48 258.6 71.58 257.98 71.58 257.25 C 71.58 256.48 71.5 255.74 70.86 255.74 C 70.33 255.74 70.06 256.08 70.12 257.23 C 70.12 258.26 70.33 258.62 70.87 258.6 Z M 70.8 259.25 C 69.53 259.25 69.13 258.62 69.13 257.11 C 69.12 255.84 69.64 255.08 70.88 255.08 C 71.95 255.07 72.56 255.53 72.56 257.16 C 72.56 258.77 71.94 259.25 70.8 259.25 Z M 49.89 258.62 C 50.51 258.62 50.61 258.01 50.61 257.27 C 50.61 256.5 50.52 255.76 49.88 255.76 C 49.35 255.76 49.08 256.1 49.14 257.25 C 49.14 258.28 49.35 258.64 49.89 258.62 Z M 49.82 259.27 C 48.56 259.27 48.15 258.64 48.15 257.13 C 48.15 255.86 48.67 255.1 49.9 255.1 C 50.97 255.09 51.58 255.55 51.58 257.18 C 51.58 258.79 50.96 259.27 49.82 259.27 Z M 48.78 268.57 C 48.58 268.66 48.37 268.67 48.37 268.53 L 48.37 268.24 C 48.37 268.15 48.43 268.04 48.66 267.92 L 49.63 267.4 L 50.41 267.4 L 50.41 270.91 L 51.09 270.91 C 51.27 270.91 51.39 270.99 51.39 271.13 L 51.39 271.36 C 51.39 271.51 51.29 271.56 51.12 271.56 L 48.67 271.56 C 48.49 271.56 48.37 271.53 48.37 271.37 L 48.37 271.09 C 48.37 270.97 48.49 270.91 48.64 270.91 L 49.41 270.91 L 49.41 268.27 L 48.78 268.57 Z M 59.6 268.56 C 59.41 268.65 59.2 268.66 59.2 268.52 L 59.2 268.23 C 59.2 268.14 59.26 268.02 59.49 267.91 L 60.46 267.39 L 61.24 267.39 L 61.24 270.9 L 61.92 270.9 C 62.1 270.9 62.21 270.98 62.21 271.12 L 62.21 271.35 C 62.21 271.49 62.12 271.55 61.95 271.55 L 59.49 271.55 C 59.32 271.55 59.2 271.52 59.2 271.36 L 59.2 271.08 C 59.2 270.96 59.32 270.9 59.47 270.9 L 60.24 270.9 L 60.24 268.26 L 59.6 268.56 Z M 65.01 256.25 C 64.81 256.35 64.6 256.36 64.6 256.22 L 64.6 255.93 C 64.6 255.84 64.66 255.72 64.89 255.61 L 65.86 255.09 L 66.64 255.09 L 66.64 258.59 L 67.32 258.59 C 67.5 258.59 67.62 258.68 67.62 258.81 L 67.62 259.05 C 67.62 259.19 67.53 259.25 67.35 259.25 L 64.9 259.25 C 64.72 259.25 64.6 259.22 64.6 259.06 L 64.6 258.78 C 64.6 258.66 64.72 258.59 64.87 258.59 L 65.64 258.59 L 65.64 255.96 L 65.01 256.25 Z M 54.34 256.25 C 54.14 256.35 53.93 256.36 53.93 256.22 L 53.93 255.93 C 53.93 255.84 53.99 255.72 54.22 255.61 L 55.19 255.09 L 55.97 255.09 L 55.97 258.59 L 56.65 258.59 C 56.83 258.59 56.95 258.68 56.95 258.81 L 56.95 259.05 C 56.95 259.19 56.85 259.25 56.68 259.25 L 54.22 259.25 C 54.05 259.25 53.93 259.22 53.93 259.06 L 53.93 258.78 C 53.93 258.66 54.05 258.59 54.2 258.59 L 54.97 258.59 L 54.97 255.96 L 54.34 256.25 Z M 59.59 249.21 C 59.4 249.31 59.19 249.32 59.19 249.18 L 59.19 248.89 C 59.19 248.8 59.25 248.68 59.48 248.57 L 60.45 248.05 L 61.23 248.05 L 61.23 251.55 L 61.91 251.55 C 62.08 251.55 62.2 251.64 62.2 251.77 L 62.2 252.01 C 62.2 252.15 62.11 252.21 61.94 252.21 L 59.48 252.21 C 59.31 252.21 59.19 252.18 59.19 252.02 L 59.19 251.74 C 59.19 251.62 59.31 251.55 59.46 251.55 L 60.22 251.55 L 60.22 248.92 L 59.59 249.21 Z M 55.18 251.53 C 55.8 251.53 55.9 250.92 55.9 250.18 C 55.9 249.41 55.81 248.67 55.17 248.67 C 54.64 248.67 54.37 249.01 54.43 250.16 C 54.43 251.19 54.64 251.55 55.18 251.53 Z M 55.11 252.18 C 53.85 252.18 53.44 251.55 53.44 250.04 C 53.44 248.77 53.96 248.01 55.19 248.01 C 56.26 248 56.87 248.46 56.87 250.09 C 56.87 251.7 56.25 252.18 55.11 252.18 Z M 48.77 249.18 C 48.57 249.27 48.36 249.28 48.36 249.14 L 48.36 248.85 C 48.36 248.76 48.42 248.64 48.65 248.53 L 49.62 248.01 L 50.4 248.01 L 50.4 251.52 L 51.08 251.52 C 51.26 251.52 51.38 251.6 51.38 251.73 L 51.38 251.97 C 51.38 252.11 51.28 252.17 51.11 252.17 L 48.65 252.17 C 48.48 252.17 48.36 252.14 48.36 251.98 L 48.36 251.7 C 48.36 251.58 48.48 251.52 48.63 251.52 L 49.4 251.52 L 49.4 248.88 L 48.77 249.18 Z" fill-opacity="0.5" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 295px; margin-left: 65px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + config.bin + </div> + </div> + </div> + </foreignObject> + <text x="65" y="307" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + config... + </text> + </switch> + </g> + </g> + <g> + <rect x="145" y="235.5" width="70" height="62.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 267px; margin-left: 146px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + load buffer + <div> + and verify version + </div> + </div> + </div> + </div> + </foreignObject> + <text x="180" y="270" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + load buffer... + </text> + </switch> + </g> + </g> + <g> + <path d="M 395 266.6 L 305 266.6 L 221.37 266.79" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 216.12 266.8 L 223.11 263.28 L 221.37 266.79 L 223.13 270.28 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 257px; margin-left: 337px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + load buffer + </div> + </div> + </div> + </foreignObject> + <text x="337" y="261" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px"> + load buffer + </text> + </switch> + </g> + </g> + <g> + <path d="M 261.34 340 L 221.37 340" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 216.12 340 L 223.12 336.5 L 221.37 340 L 223.12 343.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="261.34" y="307.7" width="70" height="64.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 340px; margin-left: 262px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + access and verify buffer + </div> + </div> + </div> + </foreignObject> + <text x="296" y="344" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + access and... + </text> + </switch> + </g> + </g> + <g> + <rect x="145" y="315" width="70" height="50" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 340px; margin-left: 146px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + flatbuffers + </div> + </div> + </div> + </foreignObject> + <text x="180" y="344" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + flatbuffers + </text> + </switch> + </g> + </g> + <g> + <rect x="145" y="358.3" width="90" height="40" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 378px; margin-left: 147px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + header-only/ + <div> + crate/... + </div> + </div> + </div> + </div> + </foreignObject> + <text x="147" y="382" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px"> + header-only/... + </text> + </switch> + </g> + </g> + <g> + <path d="M 385 425 L 331.34 372.3" fill="none" stroke="#000000" stroke-opacity="0.5" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <path d="M 15 425 L 261.34 372.3" fill="none" stroke="#000000" stroke-opacity="0.5" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <path d="M 395 297.9 L 363.2 297.9 L 363.2 340 L 337.71 340" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 332.46 340 L 339.46 336.5 L 337.71 340 L 339.46 343.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 289px; margin-left: 376px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + use + </div> + </div> + </div> + </foreignObject> + <text x="376" y="292" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + use + </text> + </switch> + </g> + </g> + <g> + <rect x="395" y="250.95" width="70" height="62.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 282px; margin-left: 396px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + User written + <div> + code + </div> + </div> + </div> + </div> + </foreignObject> + <text x="430" y="286" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + User writte... + </text> + </switch> + </g> + </g> + <g> + <path d="M 296.4 69.7 L 296.4 188.7 L 296.31 301.33" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 296.3 306.58 L 292.81 299.58 L 296.31 301.33 L 299.81 299.58 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 143px; margin-left: 302px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + generate code for + <div> + <span style="font-size: 12px;"> + C++/Rust + </span> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="302" y="146" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px"> + generate code for... + </text> + </switch> + </g> + </g> + <g> + <path d="M 277.13 68.93 L 277.1 126.3 L 91.37 126.3" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 86.12 126.3 L 93.12 122.8 L 91.37 126.3 L 93.12 129.8 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 126px; margin-left: 192px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + validate + <div> + generate + </div> + </div> + </div> + </div> + </foreignObject> + <text x="192" y="129" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + validate... + </text> + </switch> + </g> + </g> + <g> + <rect x="275" y="31.3" width="42.67" height="38.4" fill="none" stroke="none" pointer-events="all"/> + <path d="M 287.34 48.47 C 284.52 49.4 281.41 48.91 279.04 47.16 C 276.26 45.1 275 41.66 275.83 38.38 L 280.91 43.18 L 285.94 41.92 L 287.25 37.2 L 282.18 32.52 C 285.24 31.69 288.53 32.49 290.81 34.64 C 293.05 36.76 293.95 39.88 293.17 42.81 L 295.67 45.13 L 293.98 45.13 L 290.09 48.79 L 292.41 50.99 L 291.19 52.13 Z M 294.87 46.51 C 296.17 46.7 297.5 46.29 298.44 45.4 C 299.39 44.52 299.85 43.26 299.69 42 L 311.2 31.3 L 317.67 37.28 L 306.25 47.9 C 304.9 47.66 303.53 48.06 302.54 48.97 C 301.56 49.88 301.1 51.19 301.3 52.49 L 298.63 54.97 L 296.35 52.78 L 284.93 63.39 L 285.39 63.8 L 283.61 65.84 L 277.82 69.25 L 276.89 68.36 L 280.53 63.03 L 282.73 61.36 L 283.15 61.81 L 294.61 51.15 L 292.24 48.95 Z M 302.91 51.84 L 314.71 62.87 C 315.83 64.42 315.69 66.51 314.37 67.91 C 312.82 69.55 310.18 69.7 308.45 68.24 L 295.42 55.99 L 296.69 54.85 L 298.97 57.01 L 302.91 53.39 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 28px; margin-left: 296px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + @flatbuffers//:flatc + <div> + (wrapped via Starlark rules) + </div> + </div> + </div> + </div> + </foreignObject> + <text x="296" y="28" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + @flatbu... + </text> + </switch> + </g> + </g> + <g/> + <g> + <rect x="415" y="37.5" width="23" height="26" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));"/> + </g> + <g> + <rect x="415" y="37.5" width="30" height="26" fill="none" stroke="none" pointer-events="all"/> + <path d="M 438.01 50.25 L 431.52 56.31 L 431.34 56.15 L 429.89 57.51 C 429.69 57.68 429.44 57.76 429.17 57.72 L 428.17 58.17 C 428.06 58.21 427.98 58.2 428.02 58.06 L 428.51 57.09 C 428.47 56.87 428.57 56.61 428.75 56.43 L 430.19 55.08 L 430.01 54.92 L 436.51 48.85 Z M 436.2 46.95 L 441.01 42.49 C 441.16 42.34 441.42 42.31 441.59 42.45 L 442.29 43.11 L 442.69 42.73 C 443.18 42.34 443.89 42.36 444.46 42.82 C 445 43.4 444.91 44.09 444.56 44.46 L 438.72 49.92 L 436.87 48.19 L 441.81 43.6 L 441.32 43.15 L 437.79 46.45 C 437.79 46.72 437.62 46.96 437.43 47.1 C 437.13 47.32 436.9 47.38 436.64 47.36 Z M 420.74 49.88 L 420.74 48.64 L 432.66 48.64 L 432.66 49.88 Z M 420.74 53.18 L 420.74 51.94 L 431.34 51.94 L 430.03 53.18 Z M 426.48 58.54 L 420.74 58.54 L 420.74 57.3 L 426.48 57.3 Z M 438.41 51.66 L 438.41 63.5 L 415 63.5 L 415 37.5 L 431.34 37.5 L 437.89 43.62 L 436.06 45.34 L 430.46 45.34 L 430.46 38.74 L 416.32 38.74 L 416.32 62.26 L 437.08 62.26 L 437.08 52.9 Z" fill="#505050" stroke="none" pointer-events="all" style="fill: light-dark(rgb(80, 80, 80), rgb(168, 168, 168));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 71px; margin-left: 430px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + <div> + <span style="background-color: initial;"> + config.fbs + </span> + <br/> + </div> + <div> + <span style="background-color: initial;"> + (schema) + </span> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="430" y="83" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + confi... + </text> + </switch> + </g> + </g> + <g> + <path d="M 78 50 L 176.5 50 L 269.36 50.61" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 274.61 50.65 L 267.58 54.1 L 269.36 50.61 L 267.63 47.1 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <path d="M 51.27 71.5 C 48.38 71.5 44.7 69.14 44.7 64.67 L 44.7 59.89 L 39.8 59.89 C 38.94 59.89 38 59.41 38.02 57.95 L 38.02 48.56 C 38.02 47.68 38.53 46.75 39.66 46.72 L 44.7 46.72 L 44.7 34.95 C 44.7 31.73 47.5 28.5 51.53 28.5 L 64.57 28.5 C 65.73 28.5 67.24 29.32 68.69 30.73 L 75.94 37.96 C 77.71 39.87 78 40.85 78 42.08 L 78 64.86 C 78 68.27 75.34 71.5 70.98 71.5 Z" fill="#000000" stroke="none" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"/> + <path d="M 61.12 56.63 L 61.12 49.53 L 63.39 49.53 L 65.9 53.45 L 65.9 49.53 L 67.65 49.53 L 67.65 56.63 L 65.81 56.63 L 62.9 51.92 L 62.9 56.63 Z M 57.83 53.12 C 57.83 52.26 57.59 50.85 56.09 50.81 C 54.97 50.79 54.4 51.95 54.41 53.04 C 54.44 54.71 55.21 55.37 56.14 55.37 C 57.16 55.35 57.82 54.52 57.83 53.12 Z M 52.43 52.64 C 52.48 50.79 53.95 49.55 55.37 49.42 C 56.93 49.28 57.71 49.56 58.43 50.01 C 59.38 50.69 60.02 51.94 59.75 53.91 C 59.49 55.29 58.61 56.64 56.49 56.78 C 55.71 56.82 54.21 56.86 53.18 55.49 C 52.71 54.81 52.41 54.32 52.43 52.64 Z M 45.54 54.46 L 45.8 54.44 C 47 55.33 47.88 55.39 48.73 55.36 C 49.24 55.29 49.66 55.17 49.7 54.73 C 49.72 54.42 49.39 54.21 49.06 54.12 C 48.06 53.86 47.23 53.95 46.2 53.15 C 45.37 52.39 45.41 51.45 45.8 50.72 C 46.51 49.62 47.74 49.46 48.49 49.39 C 49.75 49.38 50.76 49.6 51.39 49.9 L 51.39 51.57 L 51.11 51.59 C 50.53 51.15 49.9 50.86 49.01 50.81 C 48.52 50.8 47.93 50.8 47.58 51.19 C 47.39 51.86 47.88 51.9 48.31 52 C 49.44 52.25 50.07 52.32 50.95 52.86 C 52.04 53.7 51.7 55.14 51.12 55.79 C 50.36 56.52 49.63 56.78 48.24 56.78 C 47.44 56.77 46.46 56.65 45.53 56.2 Z M 39.88 55.06 C 40.33 55.21 40.65 55.42 41.68 55.29 C 42.05 55.19 42.44 54.91 42.44 54.35 L 42.44 50.91 L 40.8 50.91 L 40.8 49.53 L 44.36 49.53 L 44.36 54.77 C 44.21 55.87 43.59 56.44 42.62 56.63 C 41.95 56.77 41.16 56.85 39.88 56.62 Z M 48.01 59.89 L 67.99 59.89 C 69.03 59.89 69.68 59.09 69.68 58.1 L 69.68 48.41 C 69.68 47.44 68.98 46.72 67.9 46.72 L 48.01 46.72 L 48.01 35.17 C 48.01 32.82 49.98 31.78 51.33 31.78 L 63.26 31.78 C 64.48 31.78 64.69 33.17 64.69 33.9 L 64.69 40.02 C 64.69 41.15 65.65 41.72 66.37 41.72 L 72.59 41.72 C 73.44 41.72 74.71 41.99 74.71 43.47 L 74.71 64.71 C 74.71 66.6 73.47 68.18 71.24 68.18 L 51.44 68.18 C 49.83 68.18 48.01 67.05 48.01 64.76 Z" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 79px; margin-left: 58px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + <div> + config.json + </div> + </div> + </div> + </div> + </foreignObject> + <text x="58" y="91" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + config... + </text> + </switch> + </g> + </g> + <g> + <path d="M 415 50.5 L 324.04 50.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 318.79 50.5 L 325.79 47 L 324.04 50.5 L 325.79 54 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <path d="M 555 625 L 465 313.55" fill="none" stroke="#000000" stroke-opacity="0.5" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <path d="M 65 148.4 L 65 237.83" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 65 243.08 L 61.5 236.08 L 65 237.83 L 68.5 236.08 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 180px; margin-left: 84px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + deploy + </div> + </div> + </div> + </foreignObject> + <text x="84" y="183" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + deploy + </text> + </switch> + </g> + </g> + <g> + <path d="M 80.68 147.49 L 78.12 148.4 L 76.11 146.07 L 75.77 146.07 L 73.79 148.33 L 71.2 147.38 L 71.71 144.58 L 71.46 144.37 L 68.18 144.76 L 67.12 142.61 L 69.89 140.87 L 69.88 140.65 L 67.2 138.95 L 68.24 136.75 L 71.7 137.18 L 71.88 137.02 L 71.34 134.28 L 74.03 133.37 L 75.98 135.69 L 76.31 135.67 L 78.33 133.43 L 80.9 134.33 L 80.42 137.12 L 80.72 137.31 L 83.96 136.94 L 85 139.09 L 82.37 140.78 L 82.34 141.1 L 84.95 142.77 L 83.87 144.96 L 80.56 144.5 L 80.27 144.76 L 80.68 147.49 Z M 48.8 140.82 C 47.45 140.82 45 139.69 45 137.35 L 45 104.3 L 68.81 104.3 L 76.82 111.03 L 76.82 133.06 L 76.21 133.76 L 74.51 131.83 L 69.77 133.46 L 70.11 135.77 L 67.32 135.39 L 65.32 139.34 L 67.57 140.72 L 67.4 140.82 L 48.8 140.82 Z" fill="#4495d1" stroke="none" pointer-events="all" style="fill: light-dark(rgb(68, 149, 209), rgb(61, 131, 183));"/> + <path d="M 70.87 125.1 C 71.49 125.1 71.58 124.49 71.58 123.75 C 71.58 122.98 71.5 122.24 70.86 122.24 C 70.33 122.24 70.06 122.58 70.12 123.73 C 70.12 124.76 70.33 125.12 70.87 125.1 L 70.87 125.1 Z M 70.8 125.75 C 69.54 125.75 69.13 125.12 69.13 123.61 C 69.13 122.34 69.64 121.58 70.88 121.58 C 71.95 121.57 72.56 122.03 72.56 123.66 C 72.56 125.27 71.94 125.75 70.8 125.75 L 70.8 125.75 Z M 55.17 125.1 C 55.79 125.1 55.89 124.48 55.89 123.74 C 55.89 122.97 55.8 122.23 55.16 122.23 C 54.63 122.23 54.37 122.57 54.42 123.73 C 54.42 124.76 54.63 125.11 55.17 125.1 L 55.17 125.1 Z M 55.1 125.75 C 53.84 125.75 53.43 125.12 53.43 123.61 C 53.43 122.34 53.95 121.57 55.18 121.57 C 56.25 121.57 56.87 122.03 56.87 123.65 C 56.87 125.27 56.24 125.75 55.1 125.75 L 55.1 125.75 Z M 60.59 118.67 C 61.21 118.67 61.31 118.05 61.31 117.31 C 61.31 116.54 61.23 115.8 60.59 115.8 C 60.05 115.8 59.79 116.14 59.85 117.29 C 59.85 118.32 60.05 118.68 60.59 118.67 Z M 60.53 119.32 C 59.26 119.32 58.86 118.69 58.86 117.17 C 58.85 115.9 59.37 115.14 60.61 115.14 C 61.68 115.13 62.29 115.6 62.29 117.22 C 62.29 118.84 61.66 119.32 60.53 119.32 Z M 53.87 133.98 C 53.68 134.08 53.47 134.08 53.47 133.95 L 53.47 133.65 C 53.47 133.56 53.53 133.45 53.76 133.33 L 54.73 132.82 L 55.51 132.82 L 55.51 136.32 L 56.19 136.32 C 56.37 136.32 56.48 136.41 56.48 136.54 L 56.48 136.78 C 56.48 136.92 56.39 136.98 56.22 136.98 L 53.76 136.98 C 53.59 136.98 53.47 136.94 53.47 136.79 L 53.47 136.51 C 53.47 136.38 53.59 136.32 53.74 136.32 L 54.51 136.32 L 54.51 133.68 L 53.87 133.98 Z M 65.02 122.76 C 64.82 122.86 64.62 122.86 64.62 122.73 L 64.62 122.43 C 64.62 122.34 64.68 122.23 64.9 122.11 L 65.88 121.6 L 66.65 121.6 L 66.65 125.1 L 67.33 125.1 C 67.51 125.1 67.63 125.19 67.63 125.32 L 67.63 125.56 C 67.63 125.7 67.54 125.76 67.37 125.76 L 64.91 125.76 C 64.74 125.76 64.62 125.72 64.62 125.57 L 64.62 125.28 C 64.62 125.16 64.73 125.1 64.88 125.1 L 65.65 125.1 L 65.65 122.46 L 65.02 122.76 Z M 59.62 122.74 C 59.42 122.84 59.21 122.84 59.21 122.71 L 59.21 122.41 C 59.21 122.32 59.27 122.21 59.5 122.09 L 60.47 121.58 L 61.25 121.58 L 61.25 125.08 L 61.93 125.08 C 62.11 125.08 62.23 125.16 62.23 125.3 L 62.23 125.54 C 62.23 125.68 62.14 125.73 61.97 125.73 L 59.51 125.73 C 59.33 125.73 59.21 125.7 59.21 125.54 L 59.21 125.26 C 59.21 125.14 59.33 125.08 59.48 125.08 L 60.25 125.08 L 60.25 122.44 L 59.62 122.74 Z M 48.74 122.74 C 48.54 122.84 48.34 122.84 48.34 122.71 L 48.34 122.41 C 48.34 122.32 48.4 122.21 48.62 122.09 L 49.6 121.58 L 50.37 121.58 L 50.37 125.08 L 51.05 125.08 C 51.23 125.08 51.35 125.16 51.35 125.3 L 51.35 125.54 C 51.35 125.68 51.26 125.73 51.09 125.73 L 48.63 125.73 C 48.46 125.73 48.34 125.7 48.34 125.54 L 48.34 125.26 C 48.34 125.14 48.45 125.08 48.6 125.08 L 49.37 125.08 L 49.37 122.44 L 48.74 122.74 Z M 68.71 111.03 L 68.71 105.92 L 74.6 111.03 L 68.71 111.03 Z M 76.09 143.71 C 74.13 143.71 72.63 142.49 72.63 140.75 C 72.63 139.34 74.13 137.99 76.05 137.99 C 77.96 137.99 79.47 139.24 79.47 140.97 C 79.47 142.25 78.15 143.71 76.09 143.71 L 76.09 143.71 Z" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + <path d="M 60.38 136.36 C 60.99 136.36 61.09 135.74 61.09 135 C 61.09 134.24 61.01 133.5 60.37 133.5 C 59.84 133.5 59.57 133.84 59.63 134.99 C 59.63 136.02 59.84 136.38 60.38 136.36 L 60.38 136.36 Z M 60.31 137.01 C 59.04 137.01 58.64 136.38 58.64 134.87 C 58.63 133.6 59.15 132.84 60.39 132.84 C 61.46 132.83 62.07 133.29 62.07 134.92 C 62.07 136.53 61.44 137.01 60.31 137.01 Z M 49.77 136.34 C 50.39 136.34 50.49 135.72 50.49 134.98 C 50.49 134.21 50.4 133.47 49.76 133.47 C 49.23 133.47 48.96 133.81 49.02 134.97 C 49.02 136 49.23 136.35 49.77 136.34 L 49.77 136.34 Z M 49.7 136.99 C 48.44 136.99 48.03 136.36 48.03 134.84 C 48.03 133.57 48.55 132.81 49.78 132.81 C 50.85 132.81 51.46 133.27 51.46 134.89 C 51.46 136.51 50.84 136.99 49.7 136.99 L 49.7 136.99 Z M 71.87 131.04 C 72.48 131.04 72.58 130.42 72.58 129.68 C 72.58 128.91 72.5 128.17 71.86 128.17 C 71.33 128.17 71.06 128.51 71.12 129.67 C 71.12 130.7 71.33 131.05 71.87 131.04 L 71.87 131.04 Z M 71.8 131.69 C 70.53 131.69 70.13 131.06 70.13 129.55 C 70.12 128.27 70.64 127.51 71.88 127.51 C 72.95 127.51 73.56 127.97 73.56 129.59 C 73.56 131.21 72.94 131.69 71.8 131.69 L 71.8 131.69 Z M 65.91 131.01 C 66.53 131.01 66.63 130.39 66.63 129.65 C 66.63 128.89 66.54 128.15 65.9 128.15 C 65.37 128.15 65.11 128.48 65.16 129.64 C 65.16 130.67 65.37 131.02 65.91 131.01 L 65.91 131.01 Z M 65.84 131.66 C 64.58 131.66 64.17 131.03 64.17 129.52 C 64.17 128.25 64.69 127.48 65.92 127.48 C 66.99 127.48 67.61 127.94 67.61 129.57 C 67.61 131.18 66.98 131.66 65.84 131.66 L 65.84 131.66 Z M 54.99 131.02 C 55.61 131.02 55.71 130.4 55.71 129.66 C 55.71 128.89 55.63 128.16 54.99 128.16 C 54.45 128.16 54.19 128.49 54.25 129.65 C 54.25 130.68 54.45 131.03 54.99 131.02 L 54.99 131.02 Z M 54.93 131.67 C 53.66 131.67 53.26 131.04 53.26 129.53 C 53.25 128.26 53.77 127.49 55.01 127.49 C 56.08 127.49 56.69 127.95 56.69 129.57 C 56.69 131.19 56.06 131.67 54.93 131.67 L 54.93 131.67 Z M 70.87 118.7 C 71.48 118.7 71.58 118.08 71.58 117.35 C 71.58 116.58 71.5 115.84 70.86 115.84 C 70.33 115.84 70.06 116.18 70.12 117.33 C 70.12 118.36 70.33 118.72 70.87 118.7 Z M 70.8 119.35 C 69.53 119.35 69.13 118.72 69.13 117.21 C 69.12 115.94 69.64 115.18 70.88 115.18 C 71.95 115.17 72.56 115.63 72.56 117.26 C 72.56 118.87 71.94 119.35 70.8 119.35 Z M 49.89 118.72 C 50.51 118.72 50.61 118.11 50.61 117.37 C 50.61 116.6 50.52 115.86 49.88 115.86 C 49.35 115.86 49.08 116.2 49.14 117.35 C 49.14 118.38 49.35 118.74 49.89 118.72 Z M 49.82 119.37 C 48.56 119.37 48.15 118.74 48.15 117.23 C 48.15 115.96 48.67 115.2 49.9 115.2 C 50.97 115.19 51.58 115.65 51.58 117.28 C 51.58 118.89 50.96 119.37 49.82 119.37 Z M 48.78 128.67 C 48.58 128.76 48.37 128.77 48.37 128.63 L 48.37 128.34 C 48.37 128.25 48.43 128.14 48.66 128.02 L 49.63 127.5 L 50.41 127.5 L 50.41 131.01 L 51.09 131.01 C 51.27 131.01 51.39 131.09 51.39 131.23 L 51.39 131.46 C 51.39 131.61 51.29 131.66 51.12 131.66 L 48.67 131.66 C 48.49 131.66 48.37 131.63 48.37 131.47 L 48.37 131.19 C 48.37 131.07 48.49 131.01 48.64 131.01 L 49.41 131.01 L 49.41 128.37 L 48.78 128.67 Z M 59.6 128.66 C 59.41 128.75 59.2 128.76 59.2 128.62 L 59.2 128.33 C 59.2 128.24 59.26 128.12 59.49 128.01 L 60.46 127.49 L 61.24 127.49 L 61.24 131 L 61.92 131 C 62.1 131 62.21 131.08 62.21 131.22 L 62.21 131.45 C 62.21 131.59 62.12 131.65 61.95 131.65 L 59.49 131.65 C 59.32 131.65 59.2 131.62 59.2 131.46 L 59.2 131.18 C 59.2 131.06 59.32 131 59.47 131 L 60.24 131 L 60.24 128.36 L 59.6 128.66 Z M 65.01 116.35 C 64.81 116.45 64.6 116.46 64.6 116.32 L 64.6 116.03 C 64.6 115.94 64.66 115.82 64.89 115.71 L 65.86 115.19 L 66.64 115.19 L 66.64 118.69 L 67.32 118.69 C 67.5 118.69 67.62 118.78 67.62 118.91 L 67.62 119.15 C 67.62 119.29 67.53 119.35 67.35 119.35 L 64.9 119.35 C 64.72 119.35 64.6 119.32 64.6 119.16 L 64.6 118.88 C 64.6 118.76 64.72 118.69 64.87 118.69 L 65.64 118.69 L 65.64 116.06 L 65.01 116.35 Z M 54.34 116.35 C 54.14 116.45 53.93 116.46 53.93 116.32 L 53.93 116.03 C 53.93 115.94 53.99 115.82 54.22 115.71 L 55.19 115.19 L 55.97 115.19 L 55.97 118.69 L 56.65 118.69 C 56.83 118.69 56.95 118.78 56.95 118.91 L 56.95 119.15 C 56.95 119.29 56.85 119.35 56.68 119.35 L 54.22 119.35 C 54.05 119.35 53.93 119.32 53.93 119.16 L 53.93 118.88 C 53.93 118.76 54.05 118.69 54.2 118.69 L 54.97 118.69 L 54.97 116.06 L 54.34 116.35 Z M 59.59 109.31 C 59.4 109.41 59.19 109.42 59.19 109.28 L 59.19 108.99 C 59.19 108.9 59.25 108.78 59.48 108.67 L 60.45 108.15 L 61.23 108.15 L 61.23 111.65 L 61.91 111.65 C 62.08 111.65 62.2 111.74 62.2 111.87 L 62.2 112.11 C 62.2 112.25 62.11 112.31 61.94 112.31 L 59.48 112.31 C 59.31 112.31 59.19 112.28 59.19 112.12 L 59.19 111.84 C 59.19 111.72 59.31 111.65 59.46 111.65 L 60.22 111.65 L 60.22 109.02 L 59.59 109.31 Z M 55.18 111.63 C 55.8 111.63 55.9 111.02 55.9 110.28 C 55.9 109.51 55.81 108.77 55.17 108.77 C 54.64 108.77 54.37 109.11 54.43 110.26 C 54.43 111.29 54.64 111.65 55.18 111.63 Z M 55.11 112.28 C 53.85 112.28 53.44 111.65 53.44 110.14 C 53.44 108.87 53.96 108.11 55.19 108.11 C 56.26 108.1 56.87 108.56 56.87 110.19 C 56.87 111.8 56.25 112.28 55.11 112.28 Z M 48.77 109.28 C 48.57 109.37 48.36 109.38 48.36 109.24 L 48.36 108.95 C 48.36 108.86 48.42 108.74 48.65 108.63 L 49.62 108.11 L 50.4 108.11 L 50.4 111.62 L 51.08 111.62 C 51.26 111.62 51.38 111.7 51.38 111.83 L 51.38 112.07 C 51.38 112.21 51.28 112.27 51.11 112.27 L 48.65 112.27 C 48.48 112.27 48.36 112.24 48.36 112.08 L 48.36 111.8 C 48.36 111.68 48.48 111.62 48.63 111.62 L 49.4 111.62 L 49.4 108.98 L 48.77 109.28 Z" fill-opacity="0.5" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + </g> + <g> + <rect x="195" y="595" width="150" height="30" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 610px; margin-left: 270px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + Simplified C++ example + </div> + </div> + </div> + </foreignObject> + <text x="270" y="614" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + Simplified C++ example + </text> + </switch> + </g> + </g> + <g> + <rect x="15" y="425" width="370" height="150" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 368px; height: 1px; padding-top: 500px; margin-left: 17px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + const my::namespace::MyConfig GetMyConfig(const void *buf); + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + <br/> + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + struct + <span style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + MyConfig + </span> + ... { + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + const my::namespace::AdvancedSettings *settings() const; + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + }; + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + ... + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + struct AdvancedSettings ... { + </font> + </div> + <div> + <span style="background-color: transparent;"> + int32_t my_data() const; + </span> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + }; + </font> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="17" y="504" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px"> + const my::namespace::MyConfig GetMyConfig(const void *buf);... + </text> + </switch> + </g> + </g> + <g> + <rect x="175" y="625" width="380" height="90" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 378px; height: 1px; padding-top: 670px; margin-left: 177px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + config_file = ... binary config loader ... + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + auto my_config = my::namspace:: + <span style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + GetMyConfig + </span> + (config_file); + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + <br/> + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + // assumes required attribute for tables in config.fbs + </font> + </div> + <div> + <font color="#000000" style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + auto data = + <span style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237));"> + my_config + </span> + ->settings()->my_data(); + </font> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="177" y="674" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px"> + config_file = ... binary config loader ...... + </text> + </switch> + </g> + </g> + <g> + <rect x="0" y="569" width="270" height="30" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 584px; margin-left: 135px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + Note: Code contains buffer builder per default + </div> + </div> + </div> + </foreignObject> + <text x="135" y="588" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + Note: Code contains buffer builder per default + </text> + </switch> + </g> + </g> + </g> + <switch> + <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/> + <a transform="translate(0,-5)" xlink:href="https://www.drawio.com/doc/faq/svg-export-text-problems" target="_blank"> + <text text-anchor="middle" font-size="10px" x="50%" y="100%"> + Text is not SVG - cannot display + </text> + </a> + </switch> +</svg> diff --git a/docs/flatbuffers/docs/_assets/payload_format_use_case_overview.drawio.svg b/docs/flatbuffers/docs/_assets/payload_format_use_case_overview.drawio.svg new file mode 100644 index 00000000..ec8f2a91 --- /dev/null +++ b/docs/flatbuffers/docs/_assets/payload_format_use_case_overview.drawio.svg @@ -0,0 +1,395 @@ +<svg host="65bd71144e" xmlns="http://www.w3.org/2000/svg" style="background: transparent; background-color: transparent;" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="378px" height="526px" viewBox="-0.5 -0.5 378 526" content="<mxfile linkTarget="_top" scale="1" border="0"><diagram name="Page-1" id="JKaw5B2ZcuXeohqUGU1C">zVtdb5s6GP41kdpJQYCBpJf9Phc70raeaevV5ICTeAWcGdMk+/XHxiYB7CQ0kKZp1cBrY+zn/X7tDsBtsnqkcDH/l0QoHrh2tBqAu4HrOr7t8S9BWUtK4AaSMKM4Up22hCf8Fymirag5jlBW68gIiRle1IkhSVMUshoNUkqW9W5TEtffuoAzpBGeQhjr1B84YnNJHfv2lv4PwrN5+WbHVi0JLDsrQjaHEVlWSOB+AG4pIUxeJatbFAvwSlzkcw87WjcToyhlbR7wfyfw+c+jS775q5evT6vwkdwOXV8O8wrjXK04CwlFvxIS5RwDOXO2LuGgJE8jJEa0B+BmOccMPS1gKFqXXAA4bc6SmN85/PIVUYY5lNcxnqWcxojooM9bLUV0R6sKSa3jEZEEMbrmXVSr66tpK6FyHWABSVlumeR6qte8yqArRYRKMGab0bfY8QsF31ugDMxQDsA1/53ADMV4kn1QRB23DaIOsN8TUcfVEO0GX8YoeUG3JCaUU1KSon7QAxytYGRvPk4NS98zQOkFFgA6mJ7dHUt3Of/Pzq8Sf/0jh1++f50Cshp6wIBlEDOBygKmNVCDP7kwSjehBOqaN9LZ5CLgQ/CX29vvywI+ewLDl1nBiGHlEUZhmpWw3mxH5VczJmUZT9cS5wyTtJwOX56ckezWjeN9qMbIrquGb1u+xs+RQTMC1wpOxE7f0XBBEXdc6pZQNiczksL4fku9qSO37fOZCDNS4PUbMbZWXhjmjNTRRCvMfqrHxfWzuLa46ZC3d6tK291a3exkQUZyGpZuVgHFIJ0h1kKOxWr3co+iGDL8WnfjJj6oR78QzOe3VWm7wfWxY42uKp+G0ZOLUYM0mLuZVQd+jzX1nSMYITokabwWr1PaE+HXUnNCChn34A+WZVV0q9JBEyGuEazOcagcTYymzOB/EhxFUrRQhv/CSTGQYPpCAFFA498M/DsxEpemTArWTlM8xXHcv3VuKjAYmXzblUGBT2aNA3AW9U353H9Wb6QC++XtVoGLu1KDzWo/OpHaO/77aLjn6hruvl3DdcvR9BcHLIdc+8ksR+BpliPP9MBeoP0ZTnj2ZtT/kHMR0W4WQJeIvbqhKfgmyVNvGVTzKJPiD23LdssgUnFjqG47Co/j1UcFDUdPptMMdeWnMSi+OqvlqBiL55qtMFuOVkbAHPufzzAA0MiFtgFf/zprTiX1YH2GUiT9uT3l/lH39gej+SlJ2VB6YBGeO+5iZYzL+ZRvit+Hb3nGdkblrQKKA1ale1ShC9g+penFpHhBKR9dHVBNyq7ey4A4mmwNPHvKVzLJp1OeihXBJH/ntaCFBkm7EGnWgpsTPgiG/O8TV4cY0hcBSR6j7LKldGQviIVzxVuYLWT9bopXwlRJZiN6/4okz4uosayhiScimM03Rq0iXbEQuC882GQiqzT4rs+NDrKK0pTCCWGMJCYfyGexEEtIVjNR9LSSLITIKloXFGfIEhXKnioLNvdh1U9QExpRRdAiWY+nnSM9mAVjy+sezprtlS5STV6L+sCiPSBvVkzPq0ddvmtI0k3lK7eHFN0Iiqng0nvxiqPEIE6FWO5wuHsZdlgOq/VUQ73qZOjpUesxPs9cmcIp13wYG73fAq5jAiNrKkq1e13fhB5yhu8x34ssnKMEXnbz0zVLfLThPZjTD1zg2+LnGCu9scfmIjjJWcwV4XazD2S3Md3czeIQWVyNQrRgmZXx/r9yMR5vjzB/7IwK967manyOvOL4/MDT84N90U5/OUNrkDUD9ilCC5RGOJ1xuqh3qxI5x41fy+hLLF2AJfYP5bT+5JgWUX8RFrl2jBPMBVXj1u7aXR+5+xmrd42dKb/cGa4qimfQFNBD8U7f0quy7AJZM0uwain3+EKSXHbz8WbTpjFyZ9CkId0aVs8eG0JJMDJsoY4ca9Qd2pEGbS0H6YJiH/A0a8ZAlzrTlo/fg9Cdp8JjrPHuL/EeW082muTDtWJfN/mjjsb8pHs/2rhuI0cB/snKSs7+DQZlnk383/D8udJi5r/0AuWxGLfgc3QtDt1sX8EpD1hMswvnT7QB0DhF4tv2ydihF11UovHp7KauuQ/iAaeVqetjc6wso7cW09OJXP/i1bAibcVLG8g/NFB/e8+OHvB8z4qodEkxYyg1JLUhiVDLNPPcou0GflkDe5ejG46eBPR16KZZB4BhiLKs6LO3EFCwp8NZnyykJI4nkA4bTxTBsuhavbgsG8V5lYJWuTAvZJLjOKqvY1dR5SMvIyGRPN0E00iKsbwt07wPqS/uOLBAfVsCuG4Z7R9SGa8XlTlLHeLY/c1joqYjYyDTSYkTOS7QCFObQ7Q+CREE+wfq8eiDrVlaikIkQOB2EAkd1BzXm1Tx3c5HtN4KaYjMeK9mi31Lx3Nr7FCjHystXXYq+e324Lvsvv33AXD/Pw==</diagram></mxfile>"> + <defs/> + <g> + <g> + <rect x="130" y="198.3" width="245" height="195" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 243px; height: 1px; padding-top: 205px; margin-left: 131px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + score_module + </div> + </div> + </div> + </foreignObject> + <text x="253" y="217" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + score_module + </text> + </switch> + </g> + </g> + <g> + <rect x="0" y="198.3" width="130" height="195" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 128px; height: 1px; padding-top: 205px; margin-left: 1px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + score::baselibs + </div> + </div> + </div> + </foreignObject> + <text x="65" y="217" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + score::baselibs + </text> + </switch> + </g> + </g> + <g> + <rect x="188.67" y="39.3" width="46.33" height="40" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));"/> + </g> + <g> + <rect x="45" y="235.5" width="70" height="62.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 267px; margin-left: 46px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <span style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183)); background-color: transparent;"> + verify version + </span> + </div> + </div> + </div> + </foreignObject> + <text x="80" y="270" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + verify vers... + </text> + </switch> + </g> + </g> + <g> + <path d="M 295 266.05 L 205 266.1 L 121.37 266.75" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 116.12 266.79 L 123.09 263.24 L 121.37 266.75 L 123.14 270.24 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="45" y="358.3" width="90" height="40" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 378px; margin-left: 47px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + header-only/ + <div> + crate/... + </div> + </div> + </div> + </div> + </foreignObject> + <text x="47" y="382" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px"> + header-only/... + </text> + </switch> + </g> + </g> + <g> + <path d="M 295 297.35 L 263.2 297.4 L 263.2 340 L 237.71 340" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 232.46 340 L 239.46 336.5 L 237.71 340 L 239.46 343.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 282px; margin-left: 276px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + use + </div> + </div> + </div> + </foreignObject> + <text x="276" y="285" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + use + </text> + </switch> + </g> + </g> + <g> + <path d="M 196.4 69.7 L 196.4 188.7 L 196.34 301.33" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 196.34 306.58 L 192.84 299.58 L 196.34 301.33 L 199.84 299.58 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 143px; margin-left: 202px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + generate for + <div> + <span style="font-size: 12px;"> + C++/Rust + </span> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="202" y="146" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px"> + generate for... + </text> + </switch> + </g> + </g> + <g> + <rect x="175" y="31.3" width="42.67" height="38.4" fill="none" stroke="none" pointer-events="all"/> + <path d="M 187.34 48.47 C 184.52 49.4 181.41 48.91 179.04 47.16 C 176.26 45.1 175 41.66 175.83 38.38 L 180.91 43.18 L 185.94 41.92 L 187.25 37.2 L 182.18 32.52 C 185.24 31.69 188.53 32.49 190.81 34.64 C 193.05 36.76 193.95 39.88 193.17 42.81 L 195.67 45.13 L 193.98 45.13 L 190.09 48.79 L 192.41 50.99 L 191.19 52.13 Z M 194.87 46.51 C 196.17 46.7 197.5 46.29 198.44 45.4 C 199.39 44.52 199.85 43.26 199.69 42 L 211.2 31.3 L 217.67 37.28 L 206.25 47.9 C 204.9 47.66 203.53 48.06 202.54 48.97 C 201.56 49.88 201.1 51.19 201.3 52.49 L 198.63 54.97 L 196.35 52.78 L 184.93 63.39 L 185.39 63.8 L 183.61 65.84 L 177.82 69.25 L 176.89 68.36 L 180.53 63.03 L 182.73 61.36 L 183.15 61.81 L 194.61 51.15 L 192.24 48.95 Z M 202.91 51.84 L 214.71 62.87 C 215.83 64.42 215.69 66.51 214.37 67.91 C 212.82 69.55 210.18 69.7 208.45 68.24 L 195.42 55.99 L 196.69 54.85 L 198.97 57.01 L 202.91 53.39 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 28px; margin-left: 196px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + @flatbuffers//:flatc + <div> + (wrapped via Starlark rules) + </div> + </div> + </div> + </div> + </foreignObject> + <text x="196" y="28" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + @flatbu... + </text> + </switch> + </g> + </g> + <g/> + <g> + <rect x="315" y="37.5" width="23" height="26" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));"/> + </g> + <g> + <rect x="315" y="37.5" width="30" height="26" fill="none" stroke="none" pointer-events="all"/> + <path d="M 338.01 50.25 L 331.52 56.31 L 331.34 56.15 L 329.89 57.51 C 329.69 57.68 329.44 57.76 329.17 57.72 L 328.17 58.17 C 328.06 58.21 327.98 58.2 328.02 58.06 L 328.51 57.09 C 328.47 56.87 328.57 56.61 328.75 56.43 L 330.19 55.08 L 330.01 54.92 L 336.51 48.85 Z M 336.2 46.95 L 341.01 42.49 C 341.16 42.34 341.42 42.31 341.59 42.45 L 342.29 43.11 L 342.69 42.73 C 343.18 42.34 343.89 42.36 344.46 42.82 C 345 43.4 344.91 44.09 344.56 44.46 L 338.72 49.92 L 336.87 48.19 L 341.81 43.6 L 341.32 43.15 L 337.79 46.45 C 337.79 46.72 337.62 46.96 337.43 47.1 C 337.13 47.32 336.9 47.38 336.64 47.36 Z M 320.74 49.88 L 320.74 48.64 L 332.66 48.64 L 332.66 49.88 Z M 320.74 53.18 L 320.74 51.94 L 331.34 51.94 L 330.03 53.18 Z M 326.48 58.54 L 320.74 58.54 L 320.74 57.3 L 326.48 57.3 Z M 338.41 51.66 L 338.41 63.5 L 315 63.5 L 315 37.5 L 331.34 37.5 L 337.89 43.62 L 336.06 45.34 L 330.46 45.34 L 330.46 38.74 L 316.32 38.74 L 316.32 62.26 L 337.08 62.26 L 337.08 52.9 Z" fill="#505050" stroke="none" pointer-events="all" style="fill: light-dark(rgb(80, 80, 80), rgb(168, 168, 168));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 71px; margin-left: 330px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + <div> + <span style="background-color: initial;"> + payload.fbs + </span> + <br/> + </div> + <div> + <span style="background-color: initial;"> + (schema) + </span> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="330" y="83" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + paylo... + </text> + </switch> + </g> + </g> + <g> + <path d="M 315 50.5 L 224.04 50.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 218.79 50.5 L 225.79 47 L 224.04 50.5 L 225.79 54 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="0" y="495" width="340" height="30" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 510px; margin-left: 170px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + *depending on transport buffer size may require fixed limits. + </div> + </div> + </div> + </foreignObject> + <text x="170" y="514" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + *depending on transport buffer size may require fixed li... + </text> + </switch> + </g> + </g> + <g> + <rect x="0" y="393.3" width="375" height="71.7" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 373px; height: 1px; padding-top: 400px; margin-left: 1px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + transport (e.g. mw::com) + </div> + </div> + </div> + </foreignObject> + <text x="188" y="412" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + transport (e.g. mw::com) + </text> + </switch> + </g> + </g> + <g> + <rect x="45" y="315" width="70" height="50" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 340px; margin-left: 46px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + flatbuffers + </div> + </div> + </div> + </foreignObject> + <text x="80" y="344" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + flatbuffers + </text> + </switch> + </g> + </g> + <g> + <path d="M 161.34 340 L 121.37 340" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 116.12 340 L 123.12 336.5 L 121.37 340 L 123.12 343.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <path d="M 330 456 L 330 485" fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="295" y="416" width="70" height="40" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 436px; margin-left: 296px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + payload* + </div> + </div> + </div> + </foreignObject> + <text x="330" y="440" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + payload* + </text> + </switch> + </g> + </g> + <g> + <path d="M 375 485 L 275 485" fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="295" y="250.4" width="70" height="62.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 282px; margin-left: 296px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + User written + <div> + code + </div> + </div> + </div> + </div> + </foreignObject> + <text x="330" y="285" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + User writte... + </text> + </switch> + </g> + </g> + <g> + <rect x="161.34" y="307.7" width="70" height="64.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 340px; margin-left: 162px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <span style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183));"> + access, + </span> + <div style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183)); scrollbar-color: rgb(226, 226, 226) rgb(251, 251, 251);"> + build, + </div> + <div style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183)); scrollbar-color: rgb(226, 226, 226) rgb(251, 251, 251);"> + modify and verify buffer + </div> + </div> + </div> + </div> + </foreignObject> + <text x="196" y="344" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + access,... + </text> + </switch> + </g> + </g> + <g> + <path d="M 330 313 L 330 409.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 330 414.88 L 326.5 407.88 L 330 409.63 L 333.5 407.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 344px; margin-left: 332px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + receive/send + <div> + buffer + </div> + </div> + </div> + </div> + </foreignObject> + <text x="332" y="347" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + receive/send... + </text> + </switch> + </g> + </g> + </g> + <switch> + <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/> + <a transform="translate(0,-5)" xlink:href="https://www.drawio.com/doc/faq/svg-export-text-problems" target="_blank"> + <text text-anchor="middle" font-size="10px" x="50%" y="100%"> + Text is not SVG - cannot display + </text> + </a> + </switch> +</svg> diff --git a/docs/flatbuffers/docs/_assets/storage_format_use_case_overview.drawio.svg b/docs/flatbuffers/docs/_assets/storage_format_use_case_overview.drawio.svg new file mode 100644 index 00000000..801fca31 --- /dev/null +++ b/docs/flatbuffers/docs/_assets/storage_format_use_case_overview.drawio.svg @@ -0,0 +1,414 @@ +<svg host="65bd71144e" xmlns="http://www.w3.org/2000/svg" style="background: transparent; background-color: transparent;" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="630px" height="454px" viewBox="-0.5 -0.5 630 454" content="<mxfile linkTarget="_top" scale="1" border="0"><diagram name="Page-1" id="JKaw5B2ZcuXeohqUGU1C">zVtbc9o4FP41zLQ7g8d34DG3prPNTtKm3bZPHWELUGNbVJID7K9fyZLxRQLcYEhpp9hHspDO5TufjtyBd5WubwlYLv7BMUwGrh2vB971wHWdwPb5l5BspCR0QymYExSrTpXgEf0HldBW0hzFkDY6MowThpZNYYSzDEasIQOE4FWz2wwnzV9dgjnUBI8RSHTpVxSzhZSOA7uSv4dovih/2bFVSwrKzkpAFyDGq5rIuxl4VwRjJq/S9RVMhPJKvcjn3u1o3U6MwIx1eeA9uo+CLLp/mj5s3gfX0Ye7xB6O5CjPIMnVggdumPDxLmeYD8tnzTZKFeGvHJcNQ1oY6oJ3cPwlN/Zl1c6v5uL7MyBzyMrh+LzkiLJRqWQ7uEtwnsVQTNXmzasFYvBxCSLRuuKexWULlib8zuGXz5AwxG10kaB5xmUMiw5A3RFpjssY0EUxoniE8sFQNv+kTOVu51BXoNKpGB6uayKl0FuIU8jIhndRraUbKOd2xp7lScmqcpag9IBFzVFcXwmBctD5dvDKhvxCmdFs0uBnCr7/unXxp2D99PFxHd3iq6EbaDalESbwR4rjnKv7BJrvQZNuEDRU6TomVbp+oKvSmQSnUmVoVqXwfO9iCihM0JT+oRp13C4adTyDc55Oo45rAJxj1EcZwU/wCieYcEmGM9iP9jyurXBkbz9OQ5eBb1ClH1qepyuzj0B3V4vPdj5Jg83XHDx8+Tjz8Hro+5rqYMyTl7rFhC3wHGcguamkl03lVn3usPC7QqU/IWMblYlBznBT4Tt1S3FOIrhvvko5TCaG3R1VP7GYvaYiMAEMPTcztUnN6tEHjIqcpkw8dJro7QUtS8kVqadaxtpOo1ss/PhyD/69Hn+ffLi5eQzuo79zOCx9sgqFBINY/IzKmTF6LvMlZQJ2qlxaazI6wR2YciLWMFyZHiNuOEgMyJOiOJY+Anl6B9NiPOElS6GBQifB5SC4NjrBXg/Vwm7L19SvNCiRKRyHtuV6fjPZyruXOsGmdIIW1OHZjMJj7b3PrWv2jgED1hRlmgm3XNGu8xi7A/TNUJKUogFXmT8Jis6JcIgHTBFD2OgFd60OU8wYTg+Sre04OGcJyvh0Sh4uZsvXsRRLStdzsT2wniEEqSWW/YNPtCeoHjXD2A0mlquDsyHN+b61x1+Ow2bd2Cq4VSTb03w244pzQ5AKfWZTKvO+DHFOVzMj+46kbQXzJvPpm5D/Dp+hXX2/LUaxpyB6mhdgP6w9wgjIaKlsA2cHWSxVj2YbeUGFN1S4I+fVB4fvg+FolretQLP8yGD50LXCE1k+cDS9nCErwzVi39Tj4vq7uLY4A5S31+ta2/VG3XRK5ZOOSds/U9b23ZbR+Z7L9ifVp4Xn/SXxki4YNstdw9WWUVp+qVjl7s6GClBFzwTOzOG5C0I6RefZaEHnbN+BQQT7EYDTgjBsUvMjacGWG04ao243LqenCcHozwGQ/fjBTUc238oBxE3tKXFbPVbc/RbujHTcCc+DMJ7X3Dh7nme5k90II6eoIczhcfkWszW5/sDK7FpjDcEWEMSQDHGWbMw7j4gAxsHmnWVZHfcfAs7MGKOA7QiEEY4ra4/dKHB/BYE22fBGpnLKxEQzT1UACL1XQYoXRr0ZYUanoSij1yEjnuNbXjcCosNDm82OHWv0+7DTF1aE5d69woqc6tXjP6fYUEZDL8UG2y0TfkkA3F54heO3Rp2cgFYYK6+TV8WKGjx8b6DDEQzBXGB+NSxop/fabrT/kDUfV+hFhznMoEzg9gwTQ3o/uINpH/e5O477+JQvi7/vPuWU7dyU9FHBPJ5G6P61L2Z6QRQ/LP3j2JzT8LKz4YderR749oyvRO5CacEe+W9eCFlk8LQ3oga0hEWBCQH+7yMPhwSQJ6GSPIH0bUfvoE+QRQtlW0CXstw4Q2uBVNLYkNw8Q2lzR5YhD5dTf7tCKguhbS/c1k21FNguhqY0AtAqWpcEUWiJFxv6IauezVNY/RM2nEacVGnU1XetcKSzV29s+cfzVzNe6S7VtrUoYS67K+S3A9P3m6QrcA0VRNMRqdtD/dCoFB3DNaUcf0DKtcQAyoRb7si3ew122A/rZ/aGM9GTaU8nrS/JeebiOcp45IPEmP1ESQ7MoTUTrwPsTX1TcigZnmO+b2i0gCl4e1yebiDxi4G3yzlWYIs/L0HpA+dYxmOrg9DN0yyKoMXDKIJLRi3K+//IxXi8PUb8sVcMuLPC1fg1thUv3x74+vZgH9vpb8/QWckagP2V4hhxdwOFQ/OeHGFsWa+zl5hSJFIdF8+KxwgC8r6g7HwFCUxhQR8JFB4oFs8dg2x7iIMIzEVkhcT23s7galAdLdgU8hETTqfrv07gr5wgGFua8XfX/vqoBLxe9a9FE3xvrLGE0BR3Xg+1P/0ltAbtPoYc7KRRmrK610XLJR84gm2/bPMSzex+e/XY83PtYDyKIKVFn70Js8iWRxzb04jgJJkCMmw9UbiB6Fq/eFs2imOyQla7MC9kmqMkbq5jF/n4k5dRYKLwwtYbC9qR6D76cu5Qccd839Xcvnuua406xUvo9/HKwkSLmC+0wPkVQYzBzMA+Ixx3ffPs3ArV3gUIg3KzeooXQPht9bq+rKtU/+nBu/kf</diagram></mxfile>"> + <defs/> + <g> + <g> + <rect x="10" y="168.3" width="520" height="240" fill="#ffffff" stroke="#000000" stroke-dasharray="3 3" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe flex-end; width: 516px; height: 1px; padding-top: 175px; margin-left: 10px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: right; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <font style="font-size: 14px;"> + Target + </font> + </div> + </div> + </div> + </foreignObject> + <text x="526" y="187" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="end"> + Target + </text> + </switch> + </g> + </g> + <g> + <rect x="215" y="198.3" width="245" height="195" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 243px; height: 1px; padding-top: 205px; margin-left: 216px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + score_module + </div> + </div> + </div> + </foreignObject> + <text x="338" y="217" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + score_module + </text> + </switch> + </g> + </g> + <g> + <rect x="85" y="198.3" width="130" height="195" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 128px; height: 1px; padding-top: 205px; margin-left: 86px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + score::baselibs + </div> + </div> + </div> + </foreignObject> + <text x="150" y="217" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + score::baselibs + </text> + </switch> + </g> + </g> + <g> + <rect x="273.67" y="39.3" width="46.33" height="40" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));"/> + </g> + <g> + <path d="M 130 266.8 L 100 266.8 L 76.37 266.41" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 71.12 266.32 L 78.18 262.94 L 76.37 266.41 L 78.06 269.93 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 253px; margin-left: 108px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + load/ + <div> + store + </div> + </div> + </div> + </div> + </foreignObject> + <text x="108" y="257" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + load/... + </text> + </switch> + </g> + </g> + <g> + <path d="M 65.68 287.39 L 63.12 288.3 L 61.11 285.97 L 60.77 285.97 L 58.79 288.23 L 56.2 287.28 L 56.71 284.48 L 56.46 284.27 L 53.18 284.66 L 52.12 282.51 L 54.89 280.77 L 54.88 280.55 L 52.2 278.85 L 53.24 276.65 L 56.7 277.08 L 56.88 276.92 L 56.34 274.18 L 59.03 273.27 L 60.98 275.59 L 61.31 275.57 L 63.33 273.33 L 65.9 274.23 L 65.42 277.02 L 65.72 277.21 L 68.96 276.84 L 70 278.99 L 67.37 280.68 L 67.34 281 L 69.95 282.67 L 68.87 284.86 L 65.56 284.4 L 65.27 284.66 L 65.68 287.39 Z M 33.8 280.72 C 32.45 280.72 30 279.59 30 277.25 L 30 244.2 L 53.81 244.2 L 61.82 250.93 L 61.82 272.96 L 61.21 273.66 L 59.51 271.73 L 54.77 273.36 L 55.11 275.67 L 52.32 275.29 L 50.32 279.24 L 52.57 280.62 L 52.4 280.72 L 33.8 280.72 Z" fill="#4495d1" stroke="none" pointer-events="all" style="fill: light-dark(rgb(68, 149, 209), rgb(61, 131, 183));"/> + <path d="M 55.87 265 C 56.49 265 56.58 264.39 56.58 263.65 C 56.58 262.88 56.5 262.14 55.86 262.14 C 55.33 262.14 55.06 262.48 55.12 263.63 C 55.12 264.66 55.33 265.02 55.87 265 L 55.87 265 Z M 55.8 265.65 C 54.54 265.65 54.13 265.02 54.13 263.51 C 54.13 262.24 54.64 261.48 55.88 261.48 C 56.95 261.47 57.56 261.93 57.56 263.56 C 57.56 265.17 56.94 265.65 55.8 265.65 L 55.8 265.65 Z M 40.17 265 C 40.79 265 40.89 264.38 40.89 263.64 C 40.89 262.87 40.8 262.13 40.16 262.13 C 39.63 262.13 39.37 262.47 39.42 263.63 C 39.42 264.66 39.63 265.01 40.17 265 L 40.17 265 Z M 40.1 265.65 C 38.84 265.65 38.43 265.02 38.43 263.51 C 38.43 262.24 38.95 261.47 40.18 261.47 C 41.25 261.47 41.87 261.93 41.87 263.55 C 41.87 265.17 41.24 265.65 40.1 265.65 L 40.1 265.65 Z M 45.59 258.57 C 46.21 258.57 46.31 257.95 46.31 257.21 C 46.31 256.44 46.23 255.7 45.59 255.7 C 45.05 255.7 44.79 256.04 44.85 257.19 C 44.85 258.22 45.05 258.58 45.59 258.57 Z M 45.53 259.22 C 44.26 259.22 43.86 258.59 43.86 257.07 C 43.85 255.8 44.37 255.04 45.61 255.04 C 46.68 255.03 47.29 255.5 47.29 257.12 C 47.29 258.74 46.66 259.22 45.53 259.22 Z M 38.87 273.88 C 38.68 273.98 38.47 273.98 38.47 273.85 L 38.47 273.55 C 38.47 273.46 38.53 273.35 38.76 273.23 L 39.73 272.72 L 40.51 272.72 L 40.51 276.22 L 41.19 276.22 C 41.37 276.22 41.48 276.31 41.48 276.44 L 41.48 276.68 C 41.48 276.82 41.39 276.88 41.22 276.88 L 38.76 276.88 C 38.59 276.88 38.47 276.84 38.47 276.69 L 38.47 276.41 C 38.47 276.28 38.59 276.22 38.74 276.22 L 39.51 276.22 L 39.51 273.58 L 38.87 273.88 Z M 50.02 262.66 C 49.82 262.76 49.62 262.76 49.62 262.63 L 49.62 262.33 C 49.62 262.24 49.68 262.13 49.9 262.01 L 50.88 261.5 L 51.65 261.5 L 51.65 265 L 52.33 265 C 52.51 265 52.63 265.09 52.63 265.22 L 52.63 265.46 C 52.63 265.6 52.54 265.66 52.37 265.66 L 49.91 265.66 C 49.74 265.66 49.62 265.62 49.62 265.47 L 49.62 265.18 C 49.62 265.06 49.73 265 49.88 265 L 50.65 265 L 50.65 262.36 L 50.02 262.66 Z M 44.62 262.64 C 44.42 262.74 44.21 262.74 44.21 262.61 L 44.21 262.31 C 44.21 262.22 44.27 262.11 44.5 261.99 L 45.47 261.48 L 46.25 261.48 L 46.25 264.98 L 46.93 264.98 C 47.11 264.98 47.23 265.06 47.23 265.2 L 47.23 265.44 C 47.23 265.58 47.14 265.63 46.97 265.63 L 44.51 265.63 C 44.33 265.63 44.21 265.6 44.21 265.44 L 44.21 265.16 C 44.21 265.04 44.33 264.98 44.48 264.98 L 45.25 264.98 L 45.25 262.34 L 44.62 262.64 Z M 33.74 262.64 C 33.54 262.74 33.34 262.74 33.34 262.61 L 33.34 262.31 C 33.34 262.22 33.4 262.11 33.62 261.99 L 34.6 261.48 L 35.37 261.48 L 35.37 264.98 L 36.05 264.98 C 36.23 264.98 36.35 265.06 36.35 265.2 L 36.35 265.44 C 36.35 265.58 36.26 265.63 36.09 265.63 L 33.63 265.63 C 33.46 265.63 33.34 265.6 33.34 265.44 L 33.34 265.16 C 33.34 265.04 33.45 264.98 33.6 264.98 L 34.37 264.98 L 34.37 262.34 L 33.74 262.64 Z M 53.71 250.93 L 53.71 245.82 L 59.6 250.93 L 53.71 250.93 Z M 61.09 283.61 C 59.13 283.61 57.63 282.39 57.63 280.65 C 57.63 279.24 59.13 277.89 61.05 277.89 C 62.96 277.89 64.47 279.14 64.47 280.87 C 64.47 282.15 63.15 283.61 61.09 283.61 L 61.09 283.61 Z" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + <path d="M 45.38 276.26 C 45.99 276.26 46.09 275.64 46.09 274.9 C 46.09 274.14 46.01 273.4 45.37 273.4 C 44.84 273.4 44.57 273.74 44.63 274.89 C 44.63 275.92 44.84 276.28 45.38 276.26 L 45.38 276.26 Z M 45.31 276.91 C 44.04 276.91 43.64 276.28 43.64 274.77 C 43.63 273.5 44.15 272.74 45.39 272.74 C 46.46 272.73 47.07 273.19 47.07 274.82 C 47.07 276.43 46.44 276.91 45.31 276.91 Z M 34.77 276.24 C 35.39 276.24 35.49 275.62 35.49 274.88 C 35.49 274.11 35.4 273.37 34.76 273.37 C 34.23 273.37 33.96 273.71 34.02 274.87 C 34.02 275.9 34.23 276.25 34.77 276.24 L 34.77 276.24 Z M 34.7 276.89 C 33.44 276.89 33.03 276.26 33.03 274.74 C 33.03 273.47 33.55 272.71 34.78 272.71 C 35.85 272.71 36.46 273.17 36.46 274.79 C 36.46 276.41 35.84 276.89 34.7 276.89 L 34.7 276.89 Z M 56.87 270.94 C 57.48 270.94 57.58 270.32 57.58 269.58 C 57.58 268.81 57.5 268.07 56.86 268.07 C 56.33 268.07 56.06 268.41 56.12 269.57 C 56.12 270.6 56.33 270.95 56.87 270.94 L 56.87 270.94 Z M 56.8 271.59 C 55.53 271.59 55.13 270.96 55.13 269.45 C 55.12 268.17 55.64 267.41 56.88 267.41 C 57.95 267.41 58.56 267.87 58.56 269.49 C 58.56 271.11 57.94 271.59 56.8 271.59 L 56.8 271.59 Z M 50.91 270.91 C 51.53 270.91 51.63 270.29 51.63 269.55 C 51.63 268.79 51.54 268.05 50.9 268.05 C 50.37 268.05 50.11 268.38 50.16 269.54 C 50.16 270.57 50.37 270.92 50.91 270.91 L 50.91 270.91 Z M 50.84 271.56 C 49.58 271.56 49.17 270.93 49.17 269.42 C 49.17 268.15 49.69 267.38 50.92 267.38 C 51.99 267.38 52.61 267.84 52.61 269.47 C 52.61 271.08 51.98 271.56 50.84 271.56 L 50.84 271.56 Z M 39.99 270.92 C 40.61 270.92 40.71 270.3 40.71 269.56 C 40.71 268.79 40.63 268.06 39.99 268.06 C 39.45 268.06 39.19 268.39 39.25 269.55 C 39.25 270.58 39.45 270.93 39.99 270.92 L 39.99 270.92 Z M 39.93 271.57 C 38.66 271.57 38.26 270.94 38.26 269.43 C 38.25 268.16 38.77 267.39 40.01 267.39 C 41.08 267.39 41.69 267.85 41.69 269.47 C 41.69 271.09 41.06 271.57 39.93 271.57 L 39.93 271.57 Z M 55.87 258.6 C 56.48 258.6 56.58 257.98 56.58 257.25 C 56.58 256.48 56.5 255.74 55.86 255.74 C 55.33 255.74 55.06 256.08 55.12 257.23 C 55.12 258.26 55.33 258.62 55.87 258.6 Z M 55.8 259.25 C 54.53 259.25 54.13 258.62 54.13 257.11 C 54.12 255.84 54.64 255.08 55.88 255.08 C 56.95 255.07 57.56 255.53 57.56 257.16 C 57.56 258.77 56.94 259.25 55.8 259.25 Z M 34.89 258.62 C 35.51 258.62 35.61 258.01 35.61 257.27 C 35.61 256.5 35.52 255.76 34.88 255.76 C 34.35 255.76 34.08 256.1 34.14 257.25 C 34.14 258.28 34.35 258.64 34.89 258.62 Z M 34.82 259.27 C 33.56 259.27 33.15 258.64 33.15 257.13 C 33.15 255.86 33.67 255.1 34.9 255.1 C 35.97 255.09 36.58 255.55 36.58 257.18 C 36.58 258.79 35.96 259.27 34.82 259.27 Z M 33.78 268.57 C 33.58 268.66 33.37 268.67 33.37 268.53 L 33.37 268.24 C 33.37 268.15 33.43 268.04 33.66 267.92 L 34.63 267.4 L 35.41 267.4 L 35.41 270.91 L 36.09 270.91 C 36.27 270.91 36.39 270.99 36.39 271.13 L 36.39 271.36 C 36.39 271.51 36.29 271.56 36.12 271.56 L 33.67 271.56 C 33.49 271.56 33.37 271.53 33.37 271.37 L 33.37 271.09 C 33.37 270.97 33.49 270.91 33.64 270.91 L 34.41 270.91 L 34.41 268.27 L 33.78 268.57 Z M 44.6 268.56 C 44.41 268.65 44.2 268.66 44.2 268.52 L 44.2 268.23 C 44.2 268.14 44.26 268.02 44.49 267.91 L 45.46 267.39 L 46.24 267.39 L 46.24 270.9 L 46.92 270.9 C 47.1 270.9 47.21 270.98 47.21 271.12 L 47.21 271.35 C 47.21 271.49 47.12 271.55 46.95 271.55 L 44.49 271.55 C 44.32 271.55 44.2 271.52 44.2 271.36 L 44.2 271.08 C 44.2 270.96 44.32 270.9 44.47 270.9 L 45.24 270.9 L 45.24 268.26 L 44.6 268.56 Z M 50.01 256.25 C 49.81 256.35 49.6 256.36 49.6 256.22 L 49.6 255.93 C 49.6 255.84 49.66 255.72 49.89 255.61 L 50.86 255.09 L 51.64 255.09 L 51.64 258.59 L 52.32 258.59 C 52.5 258.59 52.62 258.68 52.62 258.81 L 52.62 259.05 C 52.62 259.19 52.53 259.25 52.35 259.25 L 49.9 259.25 C 49.72 259.25 49.6 259.22 49.6 259.06 L 49.6 258.78 C 49.6 258.66 49.72 258.59 49.87 258.59 L 50.64 258.59 L 50.64 255.96 L 50.01 256.25 Z M 39.34 256.25 C 39.14 256.35 38.93 256.36 38.93 256.22 L 38.93 255.93 C 38.93 255.84 38.99 255.72 39.22 255.61 L 40.19 255.09 L 40.97 255.09 L 40.97 258.59 L 41.65 258.59 C 41.83 258.59 41.95 258.68 41.95 258.81 L 41.95 259.05 C 41.95 259.19 41.85 259.25 41.68 259.25 L 39.22 259.25 C 39.05 259.25 38.93 259.22 38.93 259.06 L 38.93 258.78 C 38.93 258.66 39.05 258.59 39.2 258.59 L 39.97 258.59 L 39.97 255.96 L 39.34 256.25 Z M 44.59 249.21 C 44.4 249.31 44.19 249.32 44.19 249.18 L 44.19 248.89 C 44.19 248.8 44.25 248.68 44.48 248.57 L 45.45 248.05 L 46.23 248.05 L 46.23 251.55 L 46.91 251.55 C 47.08 251.55 47.2 251.64 47.2 251.77 L 47.2 252.01 C 47.2 252.15 47.11 252.21 46.94 252.21 L 44.48 252.21 C 44.31 252.21 44.19 252.18 44.19 252.02 L 44.19 251.74 C 44.19 251.62 44.31 251.55 44.46 251.55 L 45.22 251.55 L 45.22 248.92 L 44.59 249.21 Z M 40.18 251.53 C 40.8 251.53 40.9 250.92 40.9 250.18 C 40.9 249.41 40.81 248.67 40.17 248.67 C 39.64 248.67 39.37 249.01 39.43 250.16 C 39.43 251.19 39.64 251.55 40.18 251.53 Z M 40.11 252.18 C 38.85 252.18 38.44 251.55 38.44 250.04 C 38.44 248.77 38.96 248.01 40.19 248.01 C 41.26 248 41.87 248.46 41.87 250.09 C 41.87 251.7 41.25 252.18 40.11 252.18 Z M 33.77 249.18 C 33.57 249.27 33.36 249.28 33.36 249.14 L 33.36 248.85 C 33.36 248.76 33.42 248.64 33.65 248.53 L 34.62 248.01 L 35.4 248.01 L 35.4 251.52 L 36.08 251.52 C 36.26 251.52 36.38 251.6 36.38 251.73 L 36.38 251.97 C 36.38 252.11 36.28 252.17 36.11 252.17 L 33.65 252.17 C 33.48 252.17 33.36 252.14 33.36 251.98 L 33.36 251.7 C 33.36 251.58 33.48 251.52 33.63 251.52 L 34.4 251.52 L 34.4 248.88 L 33.77 249.18 Z" fill-opacity="0.5" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(rgb(255, 255, 255), rgb(18, 18, 18));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 295px; margin-left: 50px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + data.bin + </div> + </div> + </div> + </foreignObject> + <text x="50" y="307" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + data.b... + </text> + </switch> + </g> + </g> + <g> + <rect x="130" y="235.5" width="70" height="62.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 267px; margin-left: 131px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + load/store buffer + <span style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183)); background-color: transparent;"> + and verify version + </span> + </div> + </div> + </div> + </foreignObject> + <text x="165" y="270" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + load/store... + </text> + </switch> + </g> + </g> + <g> + <path d="M 380 266.05 L 290 266.1 L 206.37 266.75" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 201.12 266.79 L 208.09 263.24 L 206.37 266.75 L 208.14 270.24 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 256px; margin-left: 331px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + <span style="color: light-dark(rgb(0, 0, 0), rgb(237, 237, 237)); text-align: left;"> + load/store buffer + </span> + </div> + </div> + </div> + </foreignObject> + <text x="331" y="259" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + load/store buffer + </text> + </switch> + </g> + </g> + <g> + <path d="M 246.34 340 L 206.37 340" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 201.12 340 L 208.12 336.5 L 206.37 340 L 208.12 343.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="130" y="358.3" width="90" height="40" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 378px; margin-left: 132px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + header-only/ + <div> + crate/... + </div> + </div> + </div> + </div> + </foreignObject> + <text x="132" y="382" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px"> + header-only/... + </text> + </switch> + </g> + </g> + <g> + <path d="M 380 297.35 L 348.2 297.4 L 348.2 340 L 322.71 340" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 317.46 340 L 324.46 336.5 L 322.71 340 L 324.46 343.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 289px; margin-left: 361px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + use + </div> + </div> + </div> + </foreignObject> + <text x="361" y="292" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px" text-anchor="middle"> + use + </text> + </switch> + </g> + </g> + <g> + <path d="M 281.4 69.7 L 281.4 188.7 L 281.34 301.33" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 281.34 306.58 L 277.84 299.58 L 281.34 301.33 L 284.84 299.58 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 143px; margin-left: 287px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; background-color: #ffffff; "> + <div style="display: inline-block; font-size: 11px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); white-space: nowrap; "> + generate for + <div> + <span style="font-size: 12px;"> + C++/Rust + </span> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="287" y="146" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="11px"> + generate for... + </text> + </switch> + </g> + </g> + <g> + <rect x="260" y="31.3" width="42.67" height="38.4" fill="none" stroke="none" pointer-events="all"/> + <path d="M 272.34 48.47 C 269.52 49.4 266.41 48.91 264.04 47.16 C 261.26 45.1 260 41.66 260.83 38.38 L 265.91 43.18 L 270.94 41.92 L 272.25 37.2 L 267.18 32.52 C 270.24 31.69 273.53 32.49 275.81 34.64 C 278.05 36.76 278.95 39.88 278.17 42.81 L 280.67 45.13 L 278.98 45.13 L 275.09 48.79 L 277.41 50.99 L 276.19 52.13 Z M 279.87 46.51 C 281.17 46.7 282.5 46.29 283.44 45.4 C 284.39 44.52 284.85 43.26 284.69 42 L 296.2 31.3 L 302.67 37.28 L 291.25 47.9 C 289.9 47.66 288.53 48.06 287.54 48.97 C 286.56 49.88 286.1 51.19 286.3 52.49 L 283.63 54.97 L 281.35 52.78 L 269.93 63.39 L 270.39 63.8 L 268.61 65.84 L 262.82 69.25 L 261.89 68.36 L 265.53 63.03 L 267.73 61.36 L 268.15 61.81 L 279.61 51.15 L 277.24 48.95 Z M 287.91 51.84 L 299.71 62.87 C 300.83 64.42 300.69 66.51 299.37 67.91 C 297.82 69.55 295.18 69.7 293.45 68.24 L 280.42 55.99 L 281.69 54.85 L 283.97 57.01 L 287.91 53.39 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 28px; margin-left: 281px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + @flatbuffers//:flatc + <div> + (wrapped via Starlark rules) + </div> + </div> + </div> + </div> + </foreignObject> + <text x="281" y="28" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + @flatbu... + </text> + </switch> + </g> + </g> + <g/> + <g> + <rect x="400" y="37.5" width="23" height="26" fill="#ffffff" stroke="none" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));"/> + </g> + <g> + <rect x="400" y="37.5" width="30" height="26" fill="none" stroke="none" pointer-events="all"/> + <path d="M 423.01 50.25 L 416.52 56.31 L 416.34 56.15 L 414.89 57.51 C 414.69 57.68 414.44 57.76 414.17 57.72 L 413.17 58.17 C 413.06 58.21 412.98 58.2 413.02 58.06 L 413.51 57.09 C 413.47 56.87 413.57 56.61 413.75 56.43 L 415.19 55.08 L 415.01 54.92 L 421.51 48.85 Z M 421.2 46.95 L 426.01 42.49 C 426.16 42.34 426.42 42.31 426.59 42.45 L 427.29 43.11 L 427.69 42.73 C 428.18 42.34 428.89 42.36 429.46 42.82 C 430 43.4 429.91 44.09 429.56 44.46 L 423.72 49.92 L 421.87 48.19 L 426.81 43.6 L 426.32 43.15 L 422.79 46.45 C 422.79 46.72 422.62 46.96 422.43 47.1 C 422.13 47.32 421.9 47.38 421.64 47.36 Z M 405.74 49.88 L 405.74 48.64 L 417.66 48.64 L 417.66 49.88 Z M 405.74 53.18 L 405.74 51.94 L 416.34 51.94 L 415.03 53.18 Z M 411.48 58.54 L 405.74 58.54 L 405.74 57.3 L 411.48 57.3 Z M 423.41 51.66 L 423.41 63.5 L 400 63.5 L 400 37.5 L 416.34 37.5 L 422.89 43.62 L 421.06 45.34 L 415.46 45.34 L 415.46 38.74 L 401.32 38.74 L 401.32 62.26 L 422.08 62.26 L 422.08 52.9 Z" fill="#505050" stroke="none" pointer-events="all" style="fill: light-dark(rgb(80, 80, 80), rgb(168, 168, 168));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 71px; margin-left: 415px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + <div> + <span style="background-color: initial;"> + storage.fbs + </span> + <br/> + </div> + <div> + <span style="background-color: initial;"> + (schema) + </span> + </div> + </div> + </div> + </div> + </foreignObject> + <text x="415" y="83" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + stora... + </text> + </switch> + </g> + </g> + <g> + <path d="M 400 50.5 L 309.04 50.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + <path d="M 303.79 50.5 L 310.79 47 L 309.04 50.5 L 310.79 54 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <rect x="0" y="423" width="630" height="30" fill="none" stroke="none" pointer-events="all"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 438px; margin-left: 315px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: nowrap; "> + *modification is only possible if variable size element retain their size, otherwise new buffer serialization is requried. + </div> + </div> + </div> + </foreignObject> + <text x="315" y="442" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + *modification is only possible if variable size element retain their size, otherwise new buffer serializa... + </text> + </switch> + </g> + </g> + <g> + <rect x="130" y="315" width="70" height="50" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 340px; margin-left: 131px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + flatbuffers + </div> + </div> + </div> + </foreignObject> + <text x="165" y="344" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + flatbuffers + </text> + </switch> + </g> + </g> + <g> + <rect x="246.34" y="307.7" width="70" height="64.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 340px; margin-left: 247px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + <span style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183));"> + access, + </span> + <div style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183)); scrollbar-color: rgb(226, 226, 226) rgb(251, 251, 251);"> + build, + </div> + <div style="color: light-dark(rgb(63, 63, 63), rgb(183, 183, 183)); scrollbar-color: rgb(226, 226, 226) rgb(251, 251, 251);"> + modify and verify buffer + </div> + </div> + </div> + </div> + </foreignObject> + <text x="281" y="344" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + access,... + </text> + </switch> + </g> + </g> + <g> + <rect x="380" y="250.4" width="70" height="62.6" fill="#ffffff" stroke="#000000" pointer-events="all" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/> + </g> + <g> + <g transform="translate(-0.5 -0.5)"> + <switch> + <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 282px; margin-left: 381px;"> + <div style="box-sizing: border-box; font-size: 0; text-align: center; color: #000000; "> + <div style="display: inline-block; font-size: 12px; font-family: "Helvetica"; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "> + User written + <div> + code + </div> + </div> + </div> + </div> + </foreignObject> + <text x="415" y="285" fill="light-dark(#000000, #ffffff)" font-family=""Helvetica"" font-size="12px" text-anchor="middle"> + User writte... + </text> + </switch> + </g> + </g> + </g> + <switch> + <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/> + <a transform="translate(0,-5)" xlink:href="https://www.drawio.com/doc/faq/svg-export-text-problems" target="_blank"> + <text text-anchor="middle" font-size="10px" x="50%" y="100%"> + Text is not SVG - cannot display + </text> + </a> + </switch> +</svg> diff --git a/docs/flatbuffers/docs/architecture/index.rst b/docs/flatbuffers/docs/architecture/index.rst new file mode 100644 index 00000000..14b8d5ec --- /dev/null +++ b/docs/flatbuffers/docs/architecture/index.rst @@ -0,0 +1,25 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +FlatBuffers Component Architecture +================================== + +.. To be created. Link from comp_req to comp is mandatory for score metamodel check. + +.. comp:: FlatBuffers + :id: comp__baselibs_flatbuffers + :security: YES + :safety: ASIL_B + :status: invalid + :belongs_to: feat__baselibs diff --git a/docs/flatbuffers/docs/index.rst b/docs/flatbuffers/docs/index.rst new file mode 100644 index 00000000..01893a62 --- /dev/null +++ b/docs/flatbuffers/docs/index.rst @@ -0,0 +1,234 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +FlatBuffers-Library +=================== + +.. document:: FlatBuffers-Library + :id: doc__flatbuffers + :status: valid + :safety: ASIL_B + :security: YES + :tags: component_request + :realizes: wp__cmpt_request + + +.. toctree:: + :hidden: + + requirements/index.rst + architecture/index.rst + + +Abstract +======== + +This component request proposes the integration of Google FlatBuffers [#flatbuffers]_ providing +serialization, zero-copy read access, and structural verification of FlatBuffers data, as well as code +generation via the ``flatc`` compiler. + +FlatBuffers provides zero-copy access, schema validation, and access code generation for C++, Rust, +and further languages. Safety certification covers ``flatc`` tool qualification, runtime library verification, +and module-level testing of generated code. + +The introduction is proposed for the following use case: + +- Module configuration: FlatBuffers binary format for read-only configuration scenarios to achieve + aggressive start-up time requirements, as it eliminates the need for runtime parsing. + + +Motivation +========== + +Module-specific configuration is a cross-cutting concern that impacts system startup time and +development efficiency. For read-only configuration scenarios, runtime parsing approaches can +limit startup performance in time-critical applications. + +The FlatBuffers binary configuration approach addresses these engineering challenges by: + - Eliminating the need for runtime parsing to meet aggressive startup time requirements + - Providing compile-time type safety through generated access code + - Reducing development effort through automated access code generation + - Ensuring schema validation at build time + + +Rationale +========= + +Real-world experience with complex modules (e.g. diagnostics, SOME/IP) demonstrates that read-only +configuration scenarios benefit significantly from zero-copy access patterns. For these use cases, +FlatBuffers is ideal as it allows zero-copy data access. The schema-driven code generation further +accelerates development by providing type-safe access patterns, reducing both implementation effort +and the potential for configuration-related runtime errors. + + +Specification +============= + +The ``flatc`` compiler of FlatBuffers [#flatbuffers]_ generates code for serializing, accessing, and verifying +FlatBuffers binary data. + +The FlatBuffers-Library provides features defined in :need:`feat_req__baselibs__flatbuffers_library`. +Note: The FlatBuffers verification mechanism validates structural well-formedness only (e.g. offsets, vtables, +field boundaries), not payload data integrity. Therefore, :need:`aou_req__flatbuffers__data_integrity` needs +to be ensured by the user. + +In addition, opt-in common buffer identification functionality is provided to allow identification of a buffer +without further schema information. For details, refer to :need:`comp_req__flatbuffers__buffer_identification`. + +Schema Evolution +---------------- + +Backward compatibility is maintained through: + - Optional fields for new parameters + - Default values for missing fields + - Controlled field deprecation + +Build Integration +----------------- + +Build system integration provides reusable rules for: + - Buffer serialization from module-specific schema and provided JSON data + - Reverse conversion from binary to JSON for debugging purposes + +Supported use cases +------------------- + +Module configuration +^^^^^^^^^^^^^^^^^^^^ + +.. figure:: _assets/config_use_case_overview.drawio.svg + :alt: Configuration use case overview + :align: center + :width: 70% + +| FlatBuffers schema files (``config.fbs``) define the configuration structure using Interface Definition Language (IDL). +| The ``flatc`` compiler generates C++ or Rust access code from these schemas (``config.fbs``). +| The ``flatc`` compiler generates a cross-platform data binary from the schema (``config.fbs``) and JSON (``config.json``) input. +| Runtime access operates directly on the binary config data loaded from ``config.bin`` without parsing. +| The ``flatc`` compiler can convert binary config data (``config.bin``) back to JSON using the schema (``config.fbs``) for debugging purposes. + + +Identification and Versioning +""""""""""""""""""""""""""""" + +FlatBuffers binary files do not contain embedded schema information. Schema identification requires: + - Embedded version fields in the schema root table + - File naming conventions (e.g., config_v1.2.bin) + +Future use cases +---------------- + +Future use cases are not yet in scope and may require extension of the existing module requirements +and assumptions of use. + +Storage format (read/write/modify) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: _assets/storage_format_use_case_overview.drawio.svg + :alt: Storage format use case overview + :align: center + :width: 70% + +| FlatBuffers schema files (``storage.fbs``) define the storage structure using Interface Definition Language (IDL). +| The ``flatc`` compiler generates C++ or Rust access code from these schemas (``storage.fbs``). +| Runtime access/modify* operates directly on binary data loaded from the binary data file (``data.bin``). +| Runtime write serializes a new buffer that can be stored as a binary data file (``data.bin``). + +FlatBuffers is applicable as a storage format when reads significantly outnumber writes and write +latency is not time-critical. Serialization rewrites the entire buffer, making it unsuitable for +high-frequency write scenarios. Long-lived storage further benefits from schema evolution, +allowing stored files to remain compatible across software updates without requiring a format migration step. + +Payload format (communication) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: _assets/payload_format_use_case_overview.drawio.svg + :alt: Payload format use case overview + :align: center + :width: 50% + +| FlatBuffers schema files (``payload.fbs``) define the payload structure using Interface Definition Language (IDL). +| The ``flatc`` compiler generates C++ or Rust access code from these schemas (``payload.fbs``). +| Runtime sender serializes data into a FlatBuffers buffer (``payload``) and transmits it. +| Runtime receiver accesses data directly from the received buffer (``payload``). + +FlatBuffers is applicable as a payload format when message content is variable or sparse. Unlike +fixed-size binary structs, FlatBuffers supports optional fields and unions, making it suitable for +heterogeneous or extensible message types where not every field is present in every message. +Schema evolution allows sender and receiver to evolve independently across software versions +without requiring coordinated redeployment, which is relevant for interfaces with long maintenance +lifetimes. + +However, each message transmission comes at the cost of serialization, which adds overhead to +communication on the sender side. + + +Backwards Compatibility +======================= + +Module configuration: Switching from JSON to FlatBuffers for module configuration is not backwards compatible. + + +Security Impact +=============== + +Module configuration: No change expected when compared to the JSON-based configuration approach. + + +Safety Impact +============= + +**Tool Qualification**: ``flatc`` compiler qualification is limited to the buffer serialization use case. +Brief qualification is supplemented by module-specific validation. + +**Verification Runtime Library**: Footprint when excluding verifier/builder classes + - C++: 12 headers, ~250 LOC (incl. comments), standard library only + - Rust: 11 files, ~150 LOC (incl. comments), core/alloc only (assumes std/serialize features disabled) + +**Verification Generated Code**: Module-level verification is equivalent to handwritten access code verification. +Module testing contributes to ``flatc`` tool validation for specific schemas. +Test from configuration data (JSON) to value verification in access APIs. + + +License Impact +============== + +None. FlatBuffers is licensed under the Apache License Version 2.0. + + +How to Teach This +================= + +Developer adoption requires practical examples and reusable patterns. +The FlatBuffers-Library should provide examples for reference implementations. + + +Rejected Ideas +============== + +**Protocol Buffers**: Requires runtime parsing and memory allocation, defeating startup time objectives. + +**Custom binary formats**: Higher development and maintenance overhead compared to proven FlatBuffers ecosystem. + + +Open Issues +=========== + +No open issues identified yet. + + +Footnotes +========= + +.. [#flatbuffers] https://google.github.io/flatbuffers/ diff --git a/docs/flatbuffers/docs/requirements/index.rst b/docs/flatbuffers/docs/requirements/index.rst new file mode 100644 index 00000000..cb1d13d6 --- /dev/null +++ b/docs/flatbuffers/docs/requirements/index.rst @@ -0,0 +1,258 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Requirements +############ + +.. document:: FlatBuffers Requirements + :id: doc__flatbuffers_requirements + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + +FlatBuffers Tooling Requirements +================================ + +.. tool_req:: FlatBuffers Code Generation for C++ + :id: tool_req__flatbuffers_codegen_cpp + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety, feat_req__baselibs__multi_language_apis + :status: valid + :implemented: NO + + The FlatBuffers-Library tooling shall generate code for serialization and read access of FlatBuffers data for C++. + +.. tool_req:: FlatBuffers Code Generation for Rust + :id: tool_req__flatbuffers_codegen_rust + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety, feat_req__baselibs__multi_language_apis + :status: valid + :implemented: NO + + The FlatBuffers-Library tooling shall generate code for serialization and read access of FlatBuffers data for Rust. + +.. tool_req:: FlatBuffers Code Generation for Python + :id: tool_req__flatbuffers_codegen_python + :security: NO + :safety: QM + :satisfies: feat_req__baselibs__flatbuffers_library + :status: valid + :implemented: NO + + The FlatBuffers-Library tooling shall generate code for serialization and read access of FlatBuffers data for Python. + + .. note:: + Python code generation is nice-to-have for benchmark testing (scale configurations). + +.. tool_req:: FlatBuffers Binary Creation from JSON + :id: tool_req__flatbuffers_tooling_json_to_bin + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :implemented: NO + + The FlatBuffers-Library tooling shall support creation of FlatBuffers binary files from + JSON-encoded files conforming to the provided FlatBuffers schema, in case of violation + of the FlatBuffers schema the tool shall fail with an appropriate error message. + +.. tool_req:: FlatBuffers Data Constraint Validation + :id: tool_req__flatbuffers_tooling_data_validate + :security: NO + :safety: QM + :satisfies: feat_req__baselibs__flatbuffers_library + :status: valid + :implemented: NO + + The FlatBuffers-Library tooling shall provide a mechanism to validate JSON-encoded files containing + FlatBuffers data against JSON-schema defined semantic constraints such as value ranges, allowed values + and required field presence, in case of violation of the JSON-schema the tool shall fail with an appropriate error message. + + .. note:: + FlatBuffers schemas constrain values only via type bounds (e.g. uint8) or enum membership, arbitrary + constraints such as custom value ranges must be enforced externally. + Within FlatBuffers tables, scalar fields always carry a value (their default if not explicitly set) + and cannot be absent. Reference-type fields (strings, vectors, nested tables, unions) can be + marked with required to enforce their presence, otherwise they are optional. + +.. tool_req:: FlatBuffers Schema Evolution Check + :id: tool_req__flatbuffers_tooling_evolution + :security: NO + :safety: QM + :satisfies: feat_req__baselibs__flatbuffers_library + :status: valid + :implemented: NO + + The FlatBuffers-Library tooling shall provide a mechanism to check whether a new version of a + FlatBuffers schema is backward compatible with a previous version. + + .. note:: + Backward compatibility in FlatBuffers requires that existing fields are not removed or + reordered, field types are not changed, and deprecated fields retain their field identifier. + Breaking these rules silently corrupts data when old binaries access buffers produced from + a new schema or vice versa. + +FlatBuffers Library Requirements +================================ + +.. comp_req:: FlatBuffers Serialization + :id: comp_req__flatbuffers__serialization + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_flatbuffers + + The FlatBuffers-Library shall provide functionality to serialize data into the FlatBuffers binary format. + + .. note:: + Although this is only required for future use cases and not for the module configuration, it is already + included, as excluding it would require extensive patching of ``flatc`` functionality. + +.. comp_req:: FlatBuffers Access + :id: comp_req__flatbuffers__access + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_flatbuffers + + The FlatBuffers-Library shall provide functionality to read FlatBuffers binary data. + + .. note:: + FlatBuffers uses a zero-copy approach where data is accessed directly from the binary buffer. + +.. comp_req:: FlatBuffers Verification + :id: comp_req__flatbuffers__verification + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_flatbuffers + + The FlatBuffers-Library shall provide a verification mechanism to validate the structural well-formedness of a FlatBuffers buffer. + + .. note:: + Verification only validates the buffer structure (e.g. offsets, vtables, field boundaries), + not the correctness or integrity of the payload data. + +Buffer Identification and Versioning +===================================== + +.. comp_req:: Common Buffer Identification + :id: comp_req__flatbuffers__buffer_identification + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_flatbuffers + + The FlatBuffers-Library shall provide a common opt-in buffer identification mechanism consisting + of a major version, a minor version, and a 4-character identifier. + +.. comp_req:: Common Version Check + :id: comp_req__flatbuffers__version_check + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_flatbuffers + + The FlatBuffers-Library shall provide a common opt-in version check mechanism that validates + the major version, minor version, and 4-character identifier of a FlatBuffers buffer. + +Safety Impact +============= + +.. comp_req:: FlatBuffers library ASIL level + :id: comp_req__flatbuffers__asil + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__flatbuffers_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_flatbuffers + + The FlatBuffers library shall be ASIL-B compliant for C++ and Rust language support. + +AoU Requirements +================= + +.. aou_req:: FlatBuffers data integrity + :id: aou_req__flatbuffers__data_integrity + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall provide FlatBuffers binary data as input which is not corrupted due to HW, QM SW, or communication channel errors. + + .. note:: + The FlatBuffers-Library verification mechanism only validates structural well-formedness, + not payload data integrity. Data integrity shall be ensured by external means such as a safe + read-only filesystem for FlatBuffers binary file storage or a checksum protection on the + FlatBuffers binary file content. + +.. aou_req:: FlatBuffers access control + :id: aou_req__flatbuffers__access_control + :reqtype: Non-Functional + :security: YES + :safety: ASIL_B + :status: valid + + The user shall ensure access control and manipulation prevention on the FlatBuffers binary files. + + .. note:: + This can be done by the hosting process and system configuration (e.g. by using dm-verity). + +.. aou_req:: FlatBuffers buffer version check before access + :id: aou_req__flatbuffers__verify_version + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall apply the version check mechanism provided by :need:`comp_req__flatbuffers__version_check` + to a loaded buffer and confirm a successful result before accessing any data from that buffer. + + .. note:: + This provides early detection of schema or version mismatches before any further buffer data is + verified or accessed. + +.. aou_req:: FlatBuffers buffer verification before access + :id: aou_req__flatbuffers__verify_structure + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall apply the verification mechanism provided by :need:`comp_req__flatbuffers__verification` + to a loaded buffer and confirm a successful result before accessing any data from that buffer. + + .. note:: + Accessing data from an unverified or malformed buffer results in undefined behaviour. + The verification mechanism only checks structural well-formedness; it does not replace + the data integrity measures required by :need:`aou_req__flatbuffers__data_integrity`. + + +.. needextend:: "__flatbuffers__" in id + :+tags: baselibs diff --git a/docs/index.rst b/docs/index.rst index f6a90b26..bb123142 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,9 +33,43 @@ Summary **Type:** C++ Base Libraries .. toctree:: - :maxdepth: 2 - :caption: Contents: + :titlesonly: + :hidden: + :glob: - json/index.rst + ./docs/index + language/index + ./*/docs/index +Components +========== + +- :need:`doc__bitmanipulation`: Utilities for bit manipulation. +- :need:`doc__concurrency`: Provides a generic interface to execute any C++ callable in a parallel context, + supporting various execution strategies (e.g., thread pool, timed execution), thread safety, + interruption handling, and periodic/delayed task execution. +- :need:`doc__containers`: Offers a ``DynamicArray`` (fixed-size array with dynamic construction-time size) + and an intrusive linked list implementation conforming to the + `P0406R1 proposal <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0406r1.html>`_. +- :need:`doc__json`: JSON abstraction layer that can switch between different parsers/serializers under the hood. +- :need:`doc__flatbuffers`: FlatBuffers-Library with serialization, read access, and structural + verification of FlatBuffers data, plus code generation via ``flatc`` for C++, Rust, and Python. +- :need:`doc__filesystem`: Filesystem manipulation library similar to ``std::filesystem``. +- :need:`doc__futurecpp`: Extends the C++17 Standard Library with features from newer C++ standards up to C++26, + as well as selected proposals for the C++ Standard Library. +- :need:`doc__safecpp`: A collection of utilities that helps developers write safer C++ code, including + overflow-safe arithmetic, scoped callable execution, abort-on-exception enforcement, atomic overflow + prevention, null-terminated string view utilities, and coverage data preservation in GTest death tests. +- :need:`doc__memory`: Utility library for memory handling, including an abstraction layer for shared memory. +- :need:`doc__os`: OS Abstraction Layer (OSAL) to interface with different POSIX-like operating systems such + as Linux and QNX. +- :need:`doc__result`: Provides a unified approach to error handling without exceptions, conforming to C++23 + ``std::expected``. +- :need:`doc__static_reflection_with_serialization`: A header-only library for binary serialization, + deserialization, and compile-time type reflection of heterogenuous C++ data structures with focus + on compile-time safety and efficiency of serialization, as well as efficiency of filtering by + content during deserialization. +- *mw::log*: Logging frontend. +- :need:`doc__utils`: Provides a collection of small, reusable utilities that do not fit into the other + base libraries. diff --git a/docs/json2/docs/architecture/chklst_arc_inspection.rst b/docs/json2/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..0c7c70ba --- /dev/null +++ b/docs/json2/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,199 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Json Architecture Inspection Checklist + :id: doc__json_arc_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +Purpose +------- + +The purpose of the software architecture checklist is to ensure that the design meets the criteria and quality as +defined per project processes and guidelines for feature and component architectural design elements. +It helps to check the compliance with requirements, identify errors or inconsistencies, and ensure adherence to best +practices. +The checklist guides evaluation of the architecture design, identifies potential problems, and aids in +communication and documentation of architectural decisions to stakeholders. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Architecture Design Review Checklist + :header-rows: 1 + + * - Review Id + - Acceptance criteria + - Guidance + - passed + - Remarks + - Issue link + * - ARC_01_01 + - Is the traceability from software architectural elements to requirements, and other level architectural elements (e.g. component to interface) established according to the "Relations between the architectural elements" as described in :need:`doc_concept__arch_process`? + - automated + - Trace should be checked automatically by tool support in the future. Will be removed from the checklist once the requirement (:need:`Correlations of the architectural building blocks <gd_req__arch_build_blocks_corr>`) is implemented. Refer to `Tool Requirements <https://eclipse-score.github.io/docs-as-code/main/internals/requirements/requirements.html>`_ for the current status. + - + - + * - ARC_01_02 + - Does the software architecture design consider all the requirements allocated or belonging to the architectural element, including functional, non-functional, safety, and security requirements and all related design decisions? + - manual + - Check if all requirements allocated or belonging to the architectural element are considered in the design. This includes functional requirements (e.g. functional safety requirements), non-functional requirements (e.g. performance, reliability), and security requirements (e.g. confidentiality, integrity). Additionally, ensure that all related design decisions are taken into account and documented in the architectural design. + - + - + * - ARC_01_03 + - If the architectural element is related to any supplier manuals (incl. safety and security) + are the relevant parts covered? + - If the architecture makes use of supplied elements, their manuals (like safety) have to be considered (i.e. its provided functionality matches the expectation and assumptions are fulfilled). Note that in case of safety component this means that assumed Technical Safety Requirements and AoUs of the safety manual are covered. + - + - + - + * - ARC_01_04 + - Is the architectural element traceable to the lower level artifacts as defined by the workproduct traceability? + - Will be removed from checklist once the requirement (:need:`Correlations of the architectural building blocks <gd_req__arch_build_blocks_corr>`) is implemented by automated tool check. See `Tool Requirements <https://eclipse-score.github.io/docs-as-code/main/internals/requirements/requirements.html>`_. + Details of possible linking can be depicted from :need:`doc_concept__general_traceability`. + - + - + - + * - ARC_02_01 + - Is the software architecture design compliant with the (overall) feature architecture? + - On component level check against the feature architecture, on feature level check other features with common components used. + - + - + - + * - ARC_02_02 + - Is appropriate and comprehensible operation/interface naming present in the architectural design? + - Check :need:`gd_guidl__arch_design` + - + - + - + * - ARC_02_03 + - Are correctness of data flow and control flow within the architectural elements considered? + - E.g. examine definitions, transformations, integrity, and interaction of data; check error handling, data + exchange between elements, correct response to inputs and documented decision making. + Note: consistency is ensured by the process/tooling, by defining each interface only once. + - + - + - + * - ARC_02_04 + - Are the interfaces between the software architectural element and other architectural elements well-defined? + - Check if the interface reacts on non-defined behaviour or errors; can established protocols be used; are the + interfaces for inputs, outputs, error codes documented; is loose coupling considered and only limited exposure; + can unit or integration test be written against the interface; data amount transferred; no sensitive data + exposure; + - + - + - + * - ARC_02_05 + - Does the software architectural element consider the timing constraints (from the parent requirement)? + - If there are hard requirements on the timing a programming time estimation should be performed and also + deadline supervision considered. + - + - + - + * - ARC_02_06 + - Is the documentation of the software architectural element, including textual and graphical descriptions + (e.g., UML diagrams), comprehensible and complete? + - Use of semi-formal notation is expected for architectural elements with an allocated ASIL level. + Is the architecture template correctly filled? + - + - + - + * - ARC_03_01 + - Is the architectural element modular and encapsulated? + - Check e.g. that only minimal interfaces are used. Design should be object oriented. Interfaces and interactions are clearly defined. Usage of access types (private, protected) properly set. Limited global variables. + - + - + - + * - ARC_03_02 + - Is the suitability of the software architecture for future modifications and maintainability considered? + - Check for e.g. loose coupling, separation of concerns, high cohesion, versioning strategy for interfaces, + decision records, use of established design patterns. + - + - + - + * - ARC_03_03 + - Are simplicity and avoidance of unnecessary complexity present in the software architecture and the component? + - Indicators for complexity are: number of use cases (corresponding to dynamic diagrams) + allocated to single design element, number of interfaces and operations in an interface, + function parameters, global variables, complex types, limited comprehensibility. + The belonging code metrics (see :need:`gd_req__impl_complexity_analysis`) should be checked. + + Notes: + + If the "number of use cases" or "number of interfaces" above exceeds "3" or "number of function parameters" exceeds "5" or the "number of operations" exceeds "20" or global variables are used, a design rationale is mandatory. + + See also if component classification :need:`gd_temp__component_classification` as measure is present. + + - + - + - + * - ARC_03_04 + - Is the software architecture design following best practices and design principles? + - Refer to architectural guidelines and recommendations within the project documentation. + - + - + - + * - ARC_04_03 + - If your software architectural design of the component includes processes and tasks, are their scheduling policies and priorities (at least the needed relation one to another) defined to ensure that timing requirements are met? Please note, that the particular priorities or priority ranges will be probably defined by the project handbook or the software development plan. + + Note: see :need:`std_req__iso26262__software_743` + - Give a reason for these scheduling policies and priorities or explain why not needed. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component architecture in scope. + +Note: If a Review ID is not applicable for your architecture, then state ""n/a" in status and comment accordingly in remarks. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "json" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "json" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/json2/docs/architecture/index.rst b/docs/json2/docs/architecture/index.rst new file mode 100644 index 00000000..4a62bf4f --- /dev/null +++ b/docs/json2/docs/architecture/index.rst @@ -0,0 +1,132 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +JSON Component Architecture +=========================== + +.. document:: JSON Architecture + :id: doc__json_architecture + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview +-------- +The component JSON implements functionality for reading/parsing JSON data and also to write. +It provides currently only a C++ API. + +Requirements Linked to Component Architecture +--------------------------------------------- + +See the "fulfils" links in static and dynamic architecture below. + +Description +----------- + +JSON provides an abstraction layer to underlying implementations, in first iteration there is only one +implementation provided. But generally there is a "Wrapper" and an "Implementation" lower-level component. + +Design Decisions: + +It was decided to use the nlohman_json OSS library (see `nlohman/json <https://github.com/nlohmann/json>`_). This decision still has to be documented (TBD). + +JSON writing functionality is implemented in the "Wrapper", i.e. the nlohman_json OSS library is not used for this. +Reasoning is that this functionality is reused from an already qualified baselibs implementation. + +Design Constraints: + +The feature description states that this component provides a "JSON abstraction layer that can switch between different parsers/serializers under the hood." + +Rationale Behind Architecture Decomposition +******************************************* + +The decomposition in a wrapper and an implemetation component already comes from the feature definition, +the main driver is to re-use existing implementation(s), enable switch of implementation but providing a stable API. + +Static Architecture +------------------- + +.. comp:: JSON + :id: comp__baselibs_json + :security: YES + :safety: ASIL_B + :status: valid + :implements: logic_arc_int__baselibs__json + :consists_of: comp__baselibs_json_wrapper, comp__baselibs_nlohman_json + :belongs_to: feat__baselibs + +.. comp_arc_sta:: JSON Static view + :id: comp_arc_sta__baselibs__json + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__json__deserialization, comp_req__json__serialization, comp_req__json__user_format, comp_req__json__lang_idioms, comp_req__json__lang_infra, comp_req__json__type_compatibility, comp_req__json__full_testability, comp_req__json__asil + :belongs_to: comp__baselibs_json + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: JSON dynamic arch + :id: comp_arc_dyn__baselibs__json_dynamic_view + :security: YES + :safety: ASIL_B + :status: invalid + :fulfils: comp_req__json__deserialization, comp_req__json__serialization, comp_req__json__user_format, comp_req__json__lang_idioms, comp_req__json__lang_infra, comp_req__json__type_compatibility, comp_req__json__full_testability, comp_req__json__asil + :belongs_to: comp__baselibs_json + + put here a sequence diagram (TBD) + + +Interfaces +---------- + +.. logic_arc_int_op:: Parse + :id: logic_arc_int_op__baselibs__parse + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__json + +.. logic_arc_int_op:: Write + :id: logic_arc_int_op__baselibs__write + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__json + +Lower Level Components +---------------------- + +.. comp:: JSON-Wrapper + :id: comp__baselibs_json_wrapper + :security: YES + :safety: ASIL_B + :status: valid + :implements: logic_arc_int__baselibs__json + :belongs_to: feat__baselibs + +.. comp:: nlohman-JSON + :id: comp__baselibs_nlohman_json + :security: YES + :safety: ASIL_B + :status: valid + :belongs_to: feat__baselibs diff --git a/docs/json2/docs/detailed_design/chklst_impl_inspection.rst b/docs/json2/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..11699671 --- /dev/null +++ b/docs/json2/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Json Implementation Inspection Checklist + :id: doc__json_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/json2/docs/index.rst b/docs/json2/docs/index.rst new file mode 100644 index 00000000..b03fc79c --- /dev/null +++ b/docs/json2/docs/index.rst @@ -0,0 +1,138 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +JSON-Library +============ + +.. document:: JSON-Library + :id: doc__json + :status: valid + :safety: ASIL_B + :security: YES + :tags: component_request + :realizes: wp__cmpt_request + + +.. toctree:: + :hidden: + + requirements/index.rst + requirements/chklst_req_inspection.rst + architecture/index.rst + architecture/chklst_arc_inspection.rst + json_wrapper/index.rst + nlohman_json/index.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + + +Abstract +======== + +This component request proposes the integration of a safe JSON-Library with parsing functionality. + + +Basic Functionality +---------------------- +The component shall support parsing JSON data and convert that information to a compatible user format. + + +Future Extensions +---------------------- +The component shall support a future extension for serializing from user format into JSON data. + +Optional extensions which may be added if required: + +* JSON schema validation. +* Compile-time parsing (used for test purposes to ensure that a component with errors cannot exist even in the absence of a pipeline). + +Motivation +========== + +S-CORE is targeting high-performance automotive systems with safety impact. +Some applications, like the IPC communication solution, require a safe JSON-Library with parsing functionality to enable loading of configuration information at runtime. +There is currently no solution for this inside S-CORE. + +Rationale +========= + +A JSON-Library with parsing functionality needs to be introduced in S-CORE software platform due to specific functional dependencies of different features (ex: IPC). + +Further details are available in the following section: +.. _Specification: + +Specification +============= + +The following details and requirements describe the aspects of current feature in the context of S-CORE. + +General considerations +---------------------- + +The JSON-Library should provide parsing, writing and data conversion capabilities: + +* :need:`comp_req__json__deserialization` +* :need:`comp_req__json__serialization` +* :need:`comp_req__json__user_format` + +User friendly API +----------------- + +Programming languages have their own feature set and idioms. +It is crucial for any library that it seamlessly integrates into both. +This means, wherever possible and meaningful, infrastructure of the programming language and accompanying standard +libraries shall be reused. +Further, a developer used to the programming language shall have no problems understanding the API. +It should feel natural to use. +This includes error handling, which shall follow one of the error handling concepts of the programming language. + +* :need:`comp_req__json__lang_idioms` +* :need:`comp_req__json__lang_infra` +* :need:`comp_req__json__type_compatibility` + +Full testability for the public API +---------------------------------------- + +Our users will be required to proof certain coverage metrics, like line coverage or branch coverage. +For them to reach full coverage, they need to be easily able to mock or fake the public API of the JSON-Library in their unit tests. + +* :need:`comp_req__json__full_testability` + +Backwards Compatibility +======================= + +As there is currently no previous solution in S-CORE, no backwards compatibility is required. + +Security Impact +=============== + +[How could a malicious user take advantage of this new/modified component?] + +Safety Impact +============= + +Overall, the component shall support use cases up to ASIL-B: + +* :need:`comp_req__json__asil` + +License Impact +============== + +[How could the copyright impacted by the license of the new contribution?] + +How to Teach This +================= + +[How to teach users, new and experienced, how to apply the CR to their work.] diff --git a/docs/json2/docs/json_wrapper/index.rst b/docs/json2/docs/json_wrapper/index.rst new file mode 100644 index 00000000..c9bb5885 --- /dev/null +++ b/docs/json2/docs/json_wrapper/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +JSON Wrapper +############ + +.. toctree:: + + requirements/index.rst diff --git a/docs/json2/docs/json_wrapper/requirements/index.rst b/docs/json2/docs/json_wrapper/requirements/index.rst new file mode 100644 index 00000000..115ef6d5 --- /dev/null +++ b/docs/json2/docs/json_wrapper/requirements/index.rst @@ -0,0 +1,31 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Requirements +============ + +.. document:: JSON Wrapper Requirements + :id: doc__json_wrapper_requirements + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + +Due to low complexity, the requirements of the JSON component were not split into the "sub" components +"JSON Wrapper" and "nlohman_json". Reasoning is the low number of requirements (only about ten). +The component split was done nevertheless, because "JSON Wrapper" is implemented as part of the S-CORE project and +"nlohman_json" is reused from open source. + +So the requirements for "JSON Wrapper" are documented in :need:`doc__json_requirements` +(all requirements which are "fulfilled_by" :need:`comp__baselibs_json_wrapper`) diff --git a/docs/json2/docs/nlohman_json/index.rst b/docs/json2/docs/nlohman_json/index.rst new file mode 100644 index 00000000..3c354f10 --- /dev/null +++ b/docs/json2/docs/nlohman_json/index.rst @@ -0,0 +1,23 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +nlohman_json +############ + +nlohman_json is an OSS library (see `nlohman/json <https://github.com/nlohmann/json>`_) + +It is integrated into JSON component by forking and built as a Bazel third-party component. + +The library will be qualified by using the TSF methodology as described in `process_description/trustable <https://eclipse-score.github.io/process_description/main/trustable/index.html>`_ +The qualification documentation is here (TBD: add link) diff --git a/docs/json2/docs/requirements/chklst_req_inspection.rst b/docs/json2/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..0c3b350a --- /dev/null +++ b/docs/json2/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,175 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. document:: JSON Requirements Inspection Checklist + :id: doc__json_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "json" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: json + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "json" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: json + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/json2/docs/requirements/index.rst b/docs/json2/docs/requirements/index.rst new file mode 100644 index 00000000..5967e0e6 --- /dev/null +++ b/docs/json2/docs/requirements/index.rst @@ -0,0 +1,164 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. document:: JSON Requirements + :id: doc__json_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + +General Requirements +==================== + +.. comp_req:: JSON Deserialization + :id: comp_req__json__deserialization + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + :belongs_to: comp__baselibs_json + + The JSON-Library shall provide a service to deserialize JSON data according to RFC8259, i.e. + parse and check for well-formedness. + +.. comp_req:: JSON Serialization + :id: comp_req__json__serialization + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + :belongs_to: comp__baselibs_json + + The JSON-Library shall provide a service to serialize user format into JSON data according to RFC8259. + +.. comp_req:: Return data in user format + :id: comp_req__json__user_format + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + :belongs_to: comp__baselibs_json + + The JSON-Library shall return parsed data in a compatible user format. + + Note: The user format shall be a regular type and not defined within the library. + +User friendly API for information exchange +========================================== + +.. comp_req:: Support for programming language idioms + :id: comp_req__json__lang_idioms + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library, feat_req__baselibs__consistent_apis + :status: valid + :belongs_to: comp__baselibs_json + + The public API shall support the idioms of the programming language it is written in. + +.. comp_req:: Use programming language infrastructure + :id: comp_req__json__lang_infra + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + :belongs_to: comp__baselibs_json + + The public API shall use core infrastructure of its programming language and accompanying standard libraries, + whenever possible and meaningful. + + Note: This includes error handling. + +.. comp_req:: Enforce strict type compatibility + :id: comp_req__json__type_compatibility + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + :belongs_to: comp__baselibs_json + + The public API shall enforce strict type compatibility. When a user requests a value, the API shall + validate that the requested return type is compatible with the type and value of the stored JSON data. + + Note: This includes checking if the stored value exceeds the range of the expected type. + +Full testability for the user facing API +======================================== + +.. comp_req:: Fully testable public API + :id: comp_req__json__full_testability + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + :belongs_to: comp__baselibs_json + + The public API of the library shall support dependency injection with test doubles. + + Note: This enables full testability of the user code. + +Safety Impact +============= + +.. comp_req:: JSON library ASIL level + :id: comp_req__json__asil + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_json + + The JSON library shall be ASIL-B compliant. + +AoU Requirements +================= +.. aou_req:: JSON data integrity + :id: aou_req__json__data_integrity + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall provide a string as input which is not corrupted due to HW or QM SW errors. + + Note: This could be achieved by using a safe read-only filesystem for JSON file storage or a checksum protection on the JSON file content. + +.. aou_req:: Access control + :id: aou_req__json__access_control + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + + The user shall ensure access control and manipulation prevention on the JSON files. + + Note: This can be done by the hosting process and system configuration (e.g. by using dm-verity). + +.. needextend:: "__json__" in id + :+tags: baselibs + +.. needextend:: "__json__" in id + :+tags: json diff --git a/docs/json2/docs/safety_analysis/dfa.rst b/docs/json2/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..c2123a26 --- /dev/null +++ b/docs/json2/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: JSON DFA + :id: doc__json_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/json2/docs/safety_analysis/fmea.rst b/docs/json2/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..8630f563 --- /dev/null +++ b/docs/json2/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: JSON FMEA + :id: doc__json_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/language/futurecpp/docs/index.rst b/docs/language/futurecpp/docs/index.rst new file mode 100644 index 00000000..881d015b --- /dev/null +++ b/docs/language/futurecpp/docs/index.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +futurecpp +######### + +.. document:: FutureCPP Library + :id: doc__futurecpp + :status: draft + :safety: ASIL_B + :tags: baselibs_futurecpp + :realizes: wp__cmpt_request + :security: YES + +.. toctree:: + :hidden: + +Abstract +======== + +FutureCPP extends the C++ Standard Library with features from newer standards up to C++26 and selected proposals, offering an STL-like API. + +Motivation and Rationale +======================== + +Adopting the latest C++ standards is often challenging in safety-critical environments, which can delay access to modern language and library features. +FutureCPP addresses this by providing forward-compatible extensions that mirror upcoming Standard Library capabilities, allowing developers to benefit +from modern APIs without waiting for full compiler support. This approach ensures smoother transitions to future standards. + +Following components are provided by FutureCPP: + +- **Containers library**: Provides data structures such as fixed-size circular buffers, multi-dimensional array views, and containers for optional or variant types. +- **Functional library**: Provides APIs for function wrappers and error handling. +- **Numeric and Math library**: Provides mathematical utilities such as angle conversions, safe numeric casts, interpolation, and angle wrapping. +- **Memory management library**: Provides polymorphic allocators and related utilities which allow flexible memory allocation. +- **Meta Programming**: Provides compile-time utilities for generic programming, enabling type-safe abstractions and reducing code duplication. +- **Threading Support**: Provides API for thread management. +- **Utilities library**: Provides APIs for type safe conversion. +- **String Utilities**: Provides APIs for managing string related functionality. diff --git a/docs/language/index.rst b/docs/language/index.rst new file mode 100644 index 00000000..f7a6ba3c --- /dev/null +++ b/docs/language/index.rst @@ -0,0 +1,22 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +language +######## + +.. toctree:: + :hidden: + + futurecpp/docs/index.rst + safecpp/docs/index.rst diff --git a/docs/language/safecpp/docs/architecture/chklst_arc_inspection.rst b/docs/language/safecpp/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..53ef2fa9 --- /dev/null +++ b/docs/language/safecpp/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Safecpp Architecture Inspection Checklist + :id: doc__safecpp_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "safecpp" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "safecpp" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/language/safecpp/docs/architecture/index.rst b/docs/language/safecpp/docs/architecture/index.rst new file mode 100644 index 00000000..7dcbd4d2 --- /dev/null +++ b/docs/language/safecpp/docs/architecture/index.rst @@ -0,0 +1,209 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Safecpp Component Architecture +******************************** + +.. document:: Safecpp Architecture + :id: doc__safecpp_architecture + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview/Description +-------------------- + +see :need:`doc__safecpp_architecture` + +Static Architecture +------------------- + +.. comp:: SafeCpp + :id: comp__baselibs_safecpp + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_safecpp + :implements: logic_arc_int__baselibs__aborts_upon_ex, logic_arc_int__baselibs__coverage_termination, logic_arc_int__baselibs__safemath, logic_arc_int__baselibs__safeatomics, logic_arc_int__baselibs__scoped_function, logic_arc_int__baselibs__string_view + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Safecpp Static view + :id: comp_arc_sta__baselibs__safecpp + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__safecpp__aborts_upon_exception, comp_req__safecpp__safe_math, comp_req__safecpp__scoped_guards, comp_req__safecpp__nullstring, comp_req__safecpp__safe_atomic, comp_req__safecpp__coverage_termination + :belongs_to: comp__baselibs_safecpp + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Interfaces +---------- +.. logic_arc_int_op:: Allocate exception + :id: logic_arc_int_op__safecpp__allocate_exception + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__aborts_upon_ex + +.. logic_arc_int_op:: Terminate_handler + :id: logic_arc_int_op__safecpp__terminate_handler + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__coverage_termination + +.. logic_arc_int_op:: Signal_handler + :id: logic_arc_int_op__safecpp__signal_handler + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__coverage_termination + +.. logic_arc_int_op:: Add + :id: logic_arc_int_op__safecpp__safemath_add + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Subtract + :id: logic_arc_int_op__safecpp__safemath_subtract + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Multiply + :id: logic_arc_int_op__safecpp__safemath_multiply + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Divide + :id: logic_arc_int_op__safecpp__safemath_divide + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Negate + :id: logic_arc_int_op__safecpp__safemath_negate + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Abs + :id: logic_arc_int_op__safecpp__safemath_abs + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Cast + :id: logic_arc_int_op__safecpp__safemath_cast + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Less + :id: logic_arc_int_op__safecpp__safemath_less + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Greater + :id: logic_arc_int_op__safecpp__safemath_greater + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Equal + :id: logic_arc_int_op__safecpp__safemath_equal + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Notequal + :id: logic_arc_int_op__safecpp__safemath_notequal + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Lessequal + :id: logic_arc_int_op__safecpp__safemath_lessequal + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Greaterequal + :id: logic_arc_int_op__safecpp__safemath_greatereq + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safemath + +.. logic_arc_int_op:: Atomic Add + :id: logic_arc_int_op__safecpp__safeatomics_atomic + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__safeatomics + +.. logic_arc_int_op:: Move Only Scoped Function + :id: logic_arc_int_op__safecpp__scoped_function_mo + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__scoped_function + +.. logic_arc_int_op:: Copyable Scoped Function + :id: logic_arc_int_op__safecpp__scoped_function_co + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__scoped_function + +.. logic_arc_int_op:: Expire + :id: logic_arc_int_op__safecpp__scoped_function_ex + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__scoped_function + +.. logic_arc_int_op:: Null Termination Check + :id: logic_arc_int_op__safecpp__string_view_null + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__string_view diff --git a/docs/language/safecpp/docs/detailed_design/chklst_impl_inspection.rst b/docs/language/safecpp/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..542e8089 --- /dev/null +++ b/docs/language/safecpp/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Safecpp Implementation Inspection Checklist + :id: doc__safecpp_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/language/safecpp/docs/index.rst b/docs/language/safecpp/docs/index.rst new file mode 100644 index 00000000..0051eb47 --- /dev/null +++ b/docs/language/safecpp/docs/index.rst @@ -0,0 +1,55 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +safecpp +####### + +.. document:: Safecpp Library + :id: doc__safecpp + :status: draft + :safety: ASIL_B + :security: YES + :tags: baselibs_safecpp + :realizes: wp__cmpt_request + + +.. toctree:: + :hidden: + + architecture/index.rst + architecture/chklst_arc_inspection.rst + requirements/index.rst + requirements/chklst_req_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +======== + +SafeCPP is a collection of utilities that helps developers write safer C++ code. + +Motivation and Rationale +======================== + +The C++ standard library targets general-purpose software and often lacks the stricter semantics needed in safety-critical code. SafeCPP fills these gaps with small, opt-in utilities that make failure modes explicit and are easy to adopt incrementally. + +Following components are provided by SafeCPP: + +- **aborts_upon_exception**: Globally replaces C++ exception handling with ``std::abort()`` calls for safety compliance. +- **coverage_termination_handler**: Ensures coverage data is preserved in GoogleTest death tests. +- **safe_atomics**: Prevents overflow when adding numbers to atomic variables (thread-safe addition with `TryAtomicAdd`). +- **safe_math**: Provides overflow-safe arithmetic operations for integral and floating-point types. +- **scoped_function**: Offers controlled callable execution with explicit lifetime guarantees. +- **string_view**: Provides null-terminated string view types and safety utilities for secure string handling. diff --git a/docs/language/safecpp/docs/requirements/chklst_req_inspection.rst b/docs/language/safecpp/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..523886db --- /dev/null +++ b/docs/language/safecpp/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,175 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. document:: Safecpp Requirements Inspection Checklist + :id: doc__safecpp_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "safecpp" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: safecpp + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "safecpp" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: safecpp + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/language/safecpp/docs/requirements/index.rst b/docs/language/safecpp/docs/requirements/index.rst new file mode 100644 index 00000000..9429f793 --- /dev/null +++ b/docs/language/safecpp/docs/requirements/index.rst @@ -0,0 +1,111 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Requirements +############ + +.. document:: Safecpp Requirements + :id: doc__safecpp_requirements + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__requirements_comp + :tags: requirements + +Functional Requirements +======================= + +.. comp_req:: C++ Exception Abort + :id: comp_req__safecpp__aborts_upon_exception + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_safecpp + + The safecpp library shall provide a mechanism to abort the program upon C++ exception allocation, + allowing users to prevent any exception object from being created and hence to guarantee that + no single exception will be possible to be thrown within an executable. + + .. Note:: + This satisfies :need:`aou_req__platform__no_exceptions` + +.. comp_req:: Safe Arithmetic Operations + :id: comp_req__safecpp__safe_math + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_safecpp + + The safecpp library shall provide arithmetic operations + (addition, subtraction, multiplication, division, negation, absolute value, type casting, and comparison operations) + that detect overflow, underflow, divide-by-zero, and precision loss for both integer and floating-point types, + ensuring errors are handled safely and undefined behavior is prevented. + +.. comp_req:: Scoped Guards + :id: comp_req__safecpp__scoped_guards + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_safecpp + + The safecpp library shall provide scope-bound callable wrappers that prevent resource leaks. + +.. comp_req:: Null-Terminated String + :id: comp_req__safecpp__nullstring + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_safecpp + + The safecpp library shall provide a view type which guarantees that an underlying character sequence is guaranteed to be null-terminated. + Such views type's underlying character sequence shall not be possible to get modified via such view type's methods. + +.. comp_req:: Safe Atomic operations + :id: comp_req__safecpp__safe_atomic + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_safecpp + + The safecpp library shall provide a lock-free atomic addition operation for integral types with overflow detection. + +Non-Functional Requirements +=========================== + +.. comp_req:: Code Coverage Termination + :id: comp_req__safecpp__coverage_termination + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__maintainable_design + :status: valid + :belongs_to: comp__baselibs_safecpp + + The safecpp library shall provide a mechanism which automatically registers a termination handler + which ensures that code coverage data is also persisted upon any process exit (e.g. during gtest's Death Tests). + +.. needextend:: "__safecpp__" in id + :+tags: baselibs +.. needextend:: "safecpp" in id + :+tags: safecpp diff --git a/docs/language/safecpp/docs/safety_analysis/dfa.rst b/docs/language/safecpp/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..973427ab --- /dev/null +++ b/docs/language/safecpp/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: SafeCpp DFA + :id: doc__safecpp_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/language/safecpp/docs/safety_analysis/fmea.rst b/docs/language/safecpp/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..99eefb07 --- /dev/null +++ b/docs/language/safecpp/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: SafeCpp FMEA + :id: doc__safecpp_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/memory_shared/docs/architecture/index.rst b/docs/memory_shared/docs/architecture/index.rst new file mode 100644 index 00000000..1a67a16e --- /dev/null +++ b/docs/memory_shared/docs/architecture/index.rst @@ -0,0 +1,73 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Memory Shared Component Architecture +************************************ + +.. comp:: Memory Shared + :id: comp__baselibs_memory_shared + :security: YES + :safety: ASIL_B + :status: valid + :implements: logic_arc_int__baselibs__memory_shared + :uses: logic_arc_int__os__fcntl, logic_arc_int__os__stat, logic_arc_int__os__mman + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Memory Shared Static view + :id: comp_arc_sta__baselibs__memory_shared + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__memory__shared_memory, comp_req__memory__offset_ptr, comp_req__memory__shared_container, comp_req__memory__inter_process_sync, comp_req__memory__bounds_check, comp_req__memory__endianness, comp_req__memory__sealed_shm, comp_req__memory__typed_memory, comp_req__memory__resource_registry, comp_req__memory__string_utils, comp_req__memory__atomic_ops, comp_req__memory__deterministic_alloc, comp_req__memory__address_independence + :belongs_to: comp__baselibs_memory_shared + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. logic_arc_int_op:: Open + :id: logic_arc_int_op__baselibs__open + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__memory_shared + +.. logic_arc_int_op:: Update + :id: logic_arc_int_op__baselibs__update + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__memory_shared + +.. logic_arc_int_op:: Lock + :id: logic_arc_int_op__baselibs__lock + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__memory_shared + +.. logic_arc_int_op:: Set Permissions + :id: logic_arc_int_op__baselibs__set_perm + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__memory_shared diff --git a/docs/memory_shared/docs/index.rst b/docs/memory_shared/docs/index.rst new file mode 100644 index 00000000..9e57de70 --- /dev/null +++ b/docs/memory_shared/docs/index.rst @@ -0,0 +1,69 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _comp_doc_memory_shared: + +memory +###### + +.. document:: Memory Library + :id: doc__memory + :status: draft + :safety: ASIL_B + :tags: baselibs_memory + :realizes: wp__cmpt_request + :security: YES + +.. toctree:: + :hidden: + + architecture/index + requirements/index.rst + +Abstract +======== + +The Memory library provides APIs for memory management to facilitate inter-process communication (IPC) in the S-CORE software platform. + +Motivation and Rationale +======================== + +The Memory library shall provide mechanisms for creating, accessing, and managing shared memory between different processes. +It includes support for polymorphic memory resource allocators using offset pointers and additional utilities to deal with memory use-cases. + +The Memory library is needed in the S-CORE software platform because subsystems like Communication and Logging rely on shared memory for inter-process communication. + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- + +The Memory Library should provide APIs for memory management: + +* :need:`comp_req__memory__shared_memory` +* :need:`comp_req__memory__offset_ptr` +* :need:`comp_req__memory__shared_container` +* :need:`comp_req__memory__inter_process_sync` +* :need:`comp_req__memory__bounds_check` +* :need:`comp_req__memory__endianness` +* :need:`comp_req__memory__sealed_shm` +* :need:`comp_req__memory__typed_memory` +* :need:`comp_req__memory__resource_registry` +* :need:`comp_req__memory__string_utils` +* :need:`comp_req__memory__atomic_ops` + +The library should ensure that all memory operations are performed safely, with appropriate bounds checking and synchronization mechanisms to prevent memory corruption. diff --git a/docs/memory_shared/docs/requirements/index.rst b/docs/memory_shared/docs/requirements/index.rst new file mode 100644 index 00000000..c903a6f4 --- /dev/null +++ b/docs/memory_shared/docs/requirements/index.rst @@ -0,0 +1,180 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. document:: Memory Library Requirements + :id: doc__memory_lib_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, memory_library + +Functional Requirements +======================= + +.. comp_req:: Shared Memory Management + :id: comp_req__memory__shared_memory + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide capabilities for creating, opening and managing shared memory. + +.. comp_req:: Polymorphic OffsetPtr Allocator + :id: comp_req__memory__offset_ptr + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide polymorphic memory resource allocators using offset pointers instead of raw pointers to enable allocation in shared memory regions accessible across multiple processes. The standard library's std::pmr::polymorphic_allocator is not applicable as it uses raw pointers that are invalid when shared memory is mapped at different virtual addresses in different processes. + +.. comp_req:: Shared Memory Container + :id: comp_req__memory__shared_container + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide type aliases for STL containers (vector, map, string) that use offset pointers for shared memory storage. + +.. comp_req:: Inter-Process Synchronization + :id: comp_req__memory__inter_process_sync + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide file-based locking mechanisms for inter-process synchronization and mutual exclusion. + +.. comp_req:: Memory Region Bounds Checking + :id: comp_req__memory__bounds_check + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety, feat_req__baselibs__memory_library + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall track and validate memory region boundaries to prevent out-of-bounds access in shared memory. + +.. comp_req:: Endianness Conversion + :id: comp_req__memory__endianness + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide byte order conversion between host and network byte order (big/little endian). + +.. comp_req:: Sealed Shared Memory + :id: comp_req__memory__sealed_shm + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety, feat_req__baselibs__memory_library, feat_req__baselibs__security + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide immutable shared memory segments that become read-only after initialization. + +.. comp_req:: Typed Memory + :id: comp_req__memory__typed_memory + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety, feat_req__baselibs__memory_library + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide an interface to allocate shared memory from typed memory regions. + +.. comp_req:: Memory Resource Registry + :id: comp_req__memory__resource_registry + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide a global registry for memory resource lookup and management. + +.. comp_req:: String Utilities + :id: comp_req__memory__string_utils + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__memory_library + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide zero-allocation string utilities including splitting, comparison, and compile-time literals. + +.. comp_req:: Atomic Operations in Shared Memory + :id: comp_req__memory__atomic_ops + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__memory_library, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall provide atomic operations on shared memory data for lock-free inter-process communication. + + +Non-Functional Requirements +=========================== + +.. comp_req:: Deterministic Memory Allocation + :id: comp_req__memory__deterministic_alloc + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The shared memory allocation shall provide deterministic behavior with predictable execution time suitable for real-time automotive systems. + +.. comp_req:: Process Address Space Independence + :id: comp_req__memory__address_independence + :reqtype: Non-Functional + :security: YES + :safety: ASIL_B + :satisfies: feat_req__baselibs__safety, feat_req__baselibs__memory_library + :status: valid + :belongs_to: comp__baselibs_memory_shared + + The Memory library shall ensure shared memory data structures remain valid regardless of process virtual address space mappings. + +.. needextend:: "__memory__" in id + :+tags: baselibs + +.. needextend:: "__memory__" in id + :+tags: memory diff --git a/docs/os/docs/index.rst b/docs/os/docs/index.rst new file mode 100644 index 00000000..522f82a3 --- /dev/null +++ b/docs/os/docs/index.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +os +### + +.. document:: OS Library + :id: doc__os + :status: draft + :safety: ASIL_B + :security: YES + :tags: baselibs_os + :realizes: wp__cmpt_request + +.. toctree:: + :hidden: + +Abstract +======== + +This component request proposes the integration of a safe OS library for operating system abstractions. + +Motivation and Rationale +======================== + +The OS library shall provide safe and efficient abstractions for operating system functionalities. +The library shall enable developers to interact with the underlying operating system in a type-safe manner, reducing +the risk of runtime errors and improving code quality. +An OS library with type-safe abstractions is needed in the S-CORE software platform due to the frequent interaction with operating system features +and the need for reliable OS operations. + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- +The OS library should provide type-safe abstractions for operating system functionalities: diff --git a/docs/result/docs/architecture/chklst_arc_inspection.rst b/docs/result/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..d1f75348 --- /dev/null +++ b/docs/result/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Result Library Architecture Inspection Checklist + :id: doc__result_lib_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "result" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "result" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/result/docs/architecture/index.rst b/docs/result/docs/architecture/index.rst new file mode 100644 index 00000000..5f8be82d --- /dev/null +++ b/docs/result/docs/architecture/index.rst @@ -0,0 +1,97 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Result Component Architecture +***************************** + +.. document:: Result Architecture + :id: doc__result_architecture + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview/Description +-------------------- + +see :need:`doc__result` + +Static Architecture +------------------- + +.. comp:: Result + :id: comp__baselibs_result + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_result + :implements: logic_arc_int__baselibs__result + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Result Static view + :id: comp_arc_sta__baselibs__result + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__result__error_handling, comp_req__result__set_result, comp_req__result__domain_error_information, comp_req__result__type_safety, comp_req__result__std_integration, comp_req__result__deterministic_behavior, comp_req__result__exception_free_operation + :belongs_to: comp__baselibs_result + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: Result Dynamic view + :id: comp_arc_dyn__baselibs__result + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__result__error_handling, comp_req__result__set_result, comp_req__result__domain_error_information, comp_req__result__type_safety, comp_req__result__std_integration, comp_req__result__deterministic_behavior, comp_req__result__exception_free_operation + :belongs_to: comp__baselibs_result + + No need for sequence diagram. Simple caller callee flow. + +Interfaces +---------- + +.. logic_arc_int_op:: Set Result + :id: logic_arc_int_op__baselibs__set_result + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__result + +.. logic_arc_int_op:: Get Value + :id: logic_arc_int_op__baselibs__get_value + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__result + +.. logic_arc_int_op:: Get Error + :id: logic_arc_int_op__baselibs__get_error + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__result diff --git a/docs/result/docs/detailed_design/chklst_impl_inspection.rst b/docs/result/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..63eb9d4d --- /dev/null +++ b/docs/result/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Result Lib Implementation Inspection Checklist + :id: doc__result_lib_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/result/docs/index.rst b/docs/result/docs/index.rst new file mode 100644 index 00000000..ef20d22e --- /dev/null +++ b/docs/result/docs/index.rst @@ -0,0 +1,67 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +result +###### + +.. document:: Result Library + :id: doc__result + :status: draft + :safety: ASIL_B + :security: YES + :tags: baselibs_result + :realizes: wp__cmpt_request + +.. toctree:: + :hidden: + + requirements/index.rst + requirements/chklst_req_inspection.rst + architecture/index.rst + architecture/chklst_arc_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +======== + +This component request proposes the integration of a safe Result library for type-safe error handling and value propagation. + +Motivation and Rationale +======================== + +The Result library shall provide a type-safe mechanism to represent and propagate either a successful value or an error. +Result library will enable explicit error management and support the development of safety-critical features by providing clear value or error propagation paths. +A Result library with type-safe error handling is needed in the S-CORE software platform due to functional dependencies of different features and the need for explicit, reliable error propagation. +There are multiple use-case like logging error messages or comparing on expected error states to trigger other countermeasures. + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- + +The Result library should provide value/error propagation and error handling capabilities: + +* :need:`comp_req__result__error_handling` +* :need:`comp_req__result__domain_error_information` +* :need:`comp_req__result__type_safety` +* :need:`comp_req__result__std_integration` +* :need:`comp_req__result__deterministic_behavior` +* :need:`comp_req__result__exception_free_operation` + +The component should be extensible in the future to support richer error information and integration with other platform components. diff --git a/docs/result/docs/requirements/chklst_req_inspection.rst b/docs/result/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..339fbd41 --- /dev/null +++ b/docs/result/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,166 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Result Library Requirements Inspection Checklist + :id: doc__result_library_req_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + + +Requirement Inspection Checklist +================================ + + **Purpose** + The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + + **Conduct** + + As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + + - author: `<https://github.com/4og>`_ + - reviewer: `<https://github.com/aschemmel-tech>`_ + - moderator: only needed for conflict resolution between author and reviewers, is the safety manager, security manager or quality manager called in as a reviewer (can be derived from version mgt tool) + - test expert: `<https://github.com/rahulthakre29>`_ + + **Checklist** + + .. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - YES + - none + - none + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - YES + - Fixed: :need:`comp_req__result__std_integration` : it is not clear what "standard library optional type, with enforced error handling" means. + - `#2229 <https://github.com/eclipse-score/score/issues/2229>`_ + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - YES + - Fixed: :need:`aou_req__result__thread_safety` : uses "appropriate" + - `#2229 <https://github.com/eclipse-score/score/issues/2229>`_ + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The sentence template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - YES + - (old) finding explained + - none + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementationat the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert shall be invited to the inspection to explicitly check this item. + - YES + - existing implementation taken over by S-CORE baselibs + - none + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - YES + - This is appropriate for the component level. No use of exceptions and standard library relation is a S-CORE platform condition. + - none + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - YES + - linking is appropriate, that it exists is checked automatically + - none + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. + - YES + - no contradicting requirements or AoU found in the Result component requirements and the linked feature requirements. + - none + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - Think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - YES + - No timing requirements found and also no timing problems expected + - none + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - YES + - Fixed: This could be improved by using the interfaces defined in :need:`comp__baselibs_result` + - `#2229 <https://github.com/eclipse-score/score/issues/2229>`_ + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - YES + - all requirements are ASIL B as expected + - none + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - YES + - all requirements have no security implication as expected (no security impact analysis done) + - none + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - YES + - all requirements have test cases implemented + - none + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - n/a + - Requirement is testable (see REQ_08_01) + - none + * - REQ_09_01 + - Do the requirements defining a safety mechanism contain the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - YES + - Fixed: There should be an AoU covering this, :need:`aou_req__result__value_handling` is not. + - `#2229 <https://github.com/eclipse-score/score/issues/2229>`_ + +Note: If a Review ID is not applicable for your requirement, then state "n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: docname is not None and "result" in docname and "requirements" in docname and status == "valid" + :style: table + :types: comp_req + :tags: result_library + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer +the questions above as if the AoUs are requirements, except questions REQ_03_01 and REQ_03_02): + +.. needtable:: + :filter: docname is not None and "result" in docname and "requirements" in docname and status == "valid" + :style: table + :types: aou_req + :tags: result_library + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/result/docs/requirements/index.rst b/docs/result/docs/requirements/index.rst new file mode 100644 index 00000000..cea078db --- /dev/null +++ b/docs/result/docs/requirements/index.rst @@ -0,0 +1,174 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. document:: Result Library Requirements + :id: doc__result_lib_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, result_library + +Functional Requirements +======================= + +.. comp_req:: Result-Based Error Handling + :id: comp_req__result__error_handling + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__result_library, feat_req__baselibs__safety + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall provide an error handling mechanism that enables functions to return either successful values ("Get Value") or error information ("Get Error") without using C++ exceptions. + +.. comp_req:: Set Result + :id: comp_req__result__set_result + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__result_library + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall provide a "Set Result" operation that accepts either a successful value of type T or an Error object. + +.. comp_req:: Domain-Specific Error Information + :id: comp_req__result__domain_error_information + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__result_library, feat_req__baselibs__safety + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall support user-defined error domains and error codes. + +.. comp_req:: Type-Safe Error Handling + :id: comp_req__result__type_safety + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__consistent_apis, feat_req__baselibs__safety + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall enforce compile-time type safety for error handling operations. + +.. comp_req:: Standard Library Integration + :id: comp_req__result__std_integration + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__consistent_apis, feat_req__baselibs__safety + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall provide conversion utilities to transform Result objects into std::optional<T> types. The conversion shall require explicit handling of error cases before discarding error information, ensuring that errors cannot be silently ignored. + +Non-Functional Requirements +=========================== + +.. comp_req:: Deterministic Behavior + :id: comp_req__result__deterministic_behavior + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall provide deterministic behavior with no dynamic memory allocation. + +.. comp_req:: Exception-Free Operation + :id: comp_req__result__exception_free_operation + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :tags: inspected + :belongs_to: comp__baselibs_result + + The Result library shall operate without throwing C++ exceptions. + +Assumptions of Use (AoU) +======================== + +.. aou_req:: Error Domain Implementation + :id: aou_req__result__error_domain_implementation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall implement error domain classes and error code enumerations according to the library's interface specification. + +.. aou_req:: Result Value Handling + :id: aou_req__result__value_handling + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall check and handle both successful and error states of Result objects before accessing contained values to prevent undefined behavior. + +.. aou_req:: Error Reaction and Safe State + :id: aou_req__result__error_reaction + :reqtype: Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall implement error reaction mechanisms that transition the system to a safe state when error conditions are detected in Result objects. + +.. aou_req:: Thread Safety + :id: aou_req__result__thread_safety + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall implement external synchronization mechanisms (e.g., mutexes, atomic operations, or locks) when accessing or modifying Result objects from multiple threads concurrently, as the library provides no internal thread safety guarantees. + +.. aou_req:: Resource Lifetime + :id: aou_req__result__resource_lifetime + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + :tags: inspected + + The user shall ensure that error domain objects and referenced resources remain valid throughout the entire lifetime of any dependent Result or Error objects. + + +.. needextend:: "__result__" in id + :+tags: baselibs + +.. needextend:: "__result__" in id + :+tags: result_lib diff --git a/docs/result/docs/safety_analysis/dfa.rst b/docs/result/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..a3f81804 --- /dev/null +++ b/docs/result/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: result DFA + :id: doc__result_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/result/docs/safety_analysis/fmea.rst b/docs/result/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..1989c418 --- /dev/null +++ b/docs/result/docs/safety_analysis/fmea.rst @@ -0,0 +1,154 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: result FMEA + :id: doc__result_fmea + :status: valid + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +Failure Mode List +----------------- + +Fault Models for sequence diagrams + .. list-table:: Fault Models for sequence diagrams + :header-rows: 1 + :widths: 10,20,10,20 + + * - ID + - Failure Mode + - Applicability + - Rationale + * - MF_01_01 + - message is not received (is a subset/more precise description of MF_01_05) + - no + - If set result was not received before the get value/error are called, this will lead to an exception/terminate. In case of the get value user defined defaults are provided. + * - MF_01_02 + - message received too late (only relevant if delay is a realistic fault) + - no + - Do not see this as a problem for result lib, would lead to the same consideration as in MF_01_01 + * - MF_01_03 + - message received too early (usually not a problem) + - no + - No problem for result lib + * - MF_01_04 + - message not received correctly by all recipients (different messages or messages partly lost). Only relevant if the same message goes to multiple recipients. + - no + - No multiple recipients (maybe from different threads?) + * - MF_01_05 + - message is corrupted + - yes + - The error message carried within the error object does not own the underlying data. If the data source is destroyed before the error message is accessed by the user, the message reference becomes invalid (see :need:`comp_saf_fmea__result__error_message_life`). + * - MF_01_06 + - message is not sent + - yes + - Value or error are not returned - see :need:`comp_saf_fmea__result__unchecked` + * - MF_01_07 + - message is unintended sent + - no + - not applicable for a library + * - CO_01_01 + - minimum constraint boundary is violated + - yes + - The error code returned is not bound to a specific error domain at the type level. A user may interpret the code against the wrong domain, violating the constraint that error codes are only meaningful within their originating domain (see :need:`comp_saf_fmea__result__error_code`). + * - CO_01_02 + - maximum constraint boundary is violated + - yes + - same as above + * - EX_01_01 + - Process calculates wrong result(s) (is a subset/more precise description of MF_01_05 or MF_01_04). This failure mode is related to the analysis if e.g. internal safety mechanisms are required (level 2 function, plausibility check of the output, …) because of the size / complexity of the feature. + - no + - Due to low complexity of the component this error is completely eliminated by testing. Low complex architecture according to criteria in :need:`gd_chklst__arch_inspection_checklist` ARC_03_03 and design complexity below numbers as in :need:`gd_req__impl_complexity_analysis` + * - EX_01_02 + - processing too slow (only relevant if timing is considered) + - no + - Due to the small functionality, being too slow is no likely issue. + * - EX_01_03 + - processing too fast (only relevant if timing is considered) + - no + - Get functions only deliver data when called, no "too fast" is possible. + * - EX_01_04 + - loss of execution + - yes + - Loss of execution leads to the same error as MF_01_06 + * - EX_01_05 + - processing changes to arbitrary process + - no + - Not a problem of result lib as this is a library and not a process + * - EX_01_06 + - processing is not complete (infinite loop) + - yes + - The Result library accepts user-provided operations for value and error transformation. If such an operation does not complete, the calling execution is halted (see :need:`comp_saf_fmea__result__stop_user`). + +FMEA +---- +For all identified applicable failure initiators, the FMEA is performed in the following section. + +.. comp_saf_fmea:: Result Error Code Cross-Domain Misinterpretation + :violates: comp_arc_dyn__baselibs__result + :id: comp_saf_fmea__result__error_code + :fault_id: CO_01_01 + :failure_effect: When retrieving error information, the error code is returned as a domain-agnostic integer. If the user interprets this code under a different error domain than the one that produced it, the error is misidentified, potentially leading to incorrect error reaction. + :mitigation_issue: https://github.com/eclipse-score/score/issues/2880 + :sufficient: no + :status: valid + + If the user relies on the error code not only for diagnostic purposes but for selecting an error reaction path, + misinterpreting the code under a wrong domain could lead to an incorrect safety-relevant decision. + An Assumption of Use shall ensure the user verifies the error domain before interpreting the error code. + +.. comp_saf_fmea:: Result Error Message Lifetime Violation + :violates: comp_arc_dyn__baselibs__result + :id: comp_saf_fmea__result__error_message_life + :fault_id: MF_01_05 + :failure_effect: The error message provided during error construction is stored as a non-owning reference. If the referenced data is no longer valid when the user retrieves the error message, accessing it results in undefined behavior. + :mitigated_by: aou_req__result__resource_lifetime + :mitigation_issue: https://github.com/eclipse-score/score/issues/2880 + :sufficient: no + :status: valid + + The existing Assumption of Use for resource lifetime addresses the validity of error domain objects + and referenced resources. However, it does not explicitly cover the user-provided error message, + which is equally subject to lifetime constraints. The AoU should be extended to explicitly include the error message data, + or a separate AoU should be established for it. + +.. comp_saf_fmea:: Result Unchecked Value or Error Access + :violates: comp_arc_dyn__baselibs__result + :id: comp_saf_fmea__result__unchecked + :fault_id: MF_01_06 + :failure_effect: If the user calls value without the result containing a value, or calls error without the result containing an error, the program will terminate. This may occur when the user does not check the state of the result before accessing it. + :mitigated_by: aou_req__result__value_handling, aou_req__result__error_reaction + :sufficient: yes + :status: valid + + If the user accesses the value or the error without first verifying the state of the result, + the program will deterministically terminate. The provided Assumptions of Use require the user to check and handle both states before access. + +.. comp_saf_fmea:: Result Stop User + :violates: comp_arc_dyn__baselibs__result + :id: comp_saf_fmea__result__stop_user + :fault_id: EX_01_06 + :failure_effect: The user provides a transformation or error handling operation to the Result library. If this operation does not terminate (e.g., infinite loop), the calling execution is blocked indefinitely. + :mitigated_by: aou_req__platform__flow_monitoring + :sufficient: yes + :status: valid + + The Result library invokes user-provided operations synchronously during transformation of values or errors. + Ensuring these operations terminate is outside the scope of the library and is the responsibility of the user via program flow monitoring, + as covered by the referenced platform-level Assumption of Use. diff --git a/docs/safety_analysis/dfa.rst b/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..4a6b4eaf --- /dev/null +++ b/docs/safety_analysis/dfa.rst @@ -0,0 +1,289 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: Baselibs DFA + :id: doc__baselibs_dfa + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__feature_dfa + + +Dependent Failure Initiators +---------------------------- + +The DFA for the feature baselibs is performed. To show evidence that all failure initiators are considered, the applicability has to be filled out in the +following tables. For all applicable failure initiators, the DFA has to be performed. + +Dependent Failure Initiators +---------------------------- + +Shared resources +^^^^^^^^^^^^^^^^ + +.. list-table:: DFA shared resources (used for Platform DFA) + :header-rows: 1 + :widths: 10,20,10,20 + + * - ID + - Violation cause shared resources + - Applicability + - Rationale + * - SR_01_01 + - Reused software modules + - no + - Baselibs only uses libraries and not other executable modules. + * - SR_01_02 + - Libraries + - yes + - Baselibs filesystem component may suffer from concurrent access to a file, :need:`feat_saf_dfa__baselibs__conc_file_access` + * - SR_01_04 + - Basic software + - no + - Not a baselibs specific topic, covered on platform level. + * - SR_01_05 + - Operating system including scheduler + - no + - Not a baselibs specific topic, covered on platform level. + * - SR_01_06 + - Any service stack, e.g. communication stack + - no + - Not a baselibs specific topic, covered on platform level. + * - SR_01_07 + - Configuration data + - no + - No shared configuration data for baselibs. + * - SR_01_09 + - Execution time + - no + - Not a baselibs specific topic, covered on platform level. + * - SR_01_10 + - Allocated memory + - yes + - Bitmanipulation component may operate on the same memory, :need:`feat_saf_dfa__baselibs__conc_memory_access` + +Communication between the two elements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Receiving function is affected by information that is false, lost, sent multiple times, or in the wrong order etc. from the sender. + +.. list-table:: DFA communication between elements + :header-rows: 1 + :widths: 10,20,10,20 + + * - ID + - Violation cause communication between elements + - Applicability + - Rationale + * - CO_01_01 + - Information passed via argument through a function call, or via writing/reading a variable being global to the two software functions (data flow) + - no + - According to its architecture shown in :need:`feat_arc_sta__baselibs__static_view_arch` baselibs do not rely on common input. + * - CO_01_02 + - Data or message corruption / repetition / loss / delay / masquerading or incorrect addressing of information + - no + - Baselibs are not sending messages between their components. + * - CO_01_03 + - Insertion / sequence of information + - no + - Baselibs are not sending messages between their components. + * - CO_01_04 + - Corruption of information, inconsistent data + - no + - Baselibs are not sending messages between their components. Data eventually shared by function calls are covered by FMEA already. + * - CO_01_05 + - Asymmetric information sent from a sender to multiple receivers, so that not all defined receivers have the same information + - no + - Asymmetric information sending is not done in baselibs. + * - CO_01_06 + - Information from a sender received by only a subset of the receivers + - no + - This is not done in baselibs. + * - CO_01_07 + - Blocking access to a communication channel + - no + - There are no communication channels in baselibs. + +Shared information inputs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Same information input used by multiple functions. + +.. list-table:: DFA shared information inputs + :header-rows: 1 + :widths: 10,20,10,20 + + * - ID + - Violation cause shared information inputs + - Applicability + - Rationale + * - SI_01_02 + - Configuration data + - no + - There is no shared config data in baselibs. + * - SI_01_03 + - Constants, or variables, being global to the two software functions + - no + - No global variables are used in baselibs. + * - SI_01_04 + - Basic software passes data (read from hardware register and converted into logical information) to two applications software functions + - no + - No shared low level data are used between baselibs. + * - SI_01_05 + - Data / function parameter arguments / messages delivered by software function to more than one other function + - no + - No common input can be seen in architecture of baselibs. + +Unintended impact +^^^^^^^^^^^^^^^^^ + +Unintended impacts to function due to various failures. + +.. list-table:: DFA unintended impact + :header-rows: 1 + :widths: 10,20,10,20 + + * - ID + - Violation cause unintended impact + - Applicability + - Rationale + * - UI_01_01 + - Memory miss-allocation and leaks + - no + - Not a specific baselibs topic, therefore covered at platform DFA. + * - UI_01_02 + - Read/Write access to memory allocated to another software element + - yes + - As baselibs are in context of a application, they may access their memory, :need:`feat_saf_dfa__baselibs__memory_access` + * - UI_01_03 + - Stack/Buffer under-/overflow + - no + - Not a specific baselibs topic, therefore covered at platform DFA. + * - UI_01_04 + - Deadlocks + - yes + - shared memory or file access may lead to deadlock, :need:`feat_saf_dfa__baselibs__locked_ressource` + * - UI_01_05 + - Livelocks + - no + - Should be covered together with deadlock. + * - UI_01_06 + - Blocking of execution + - yes + - As baselibs are in context of a application, they may block execution, :need:`feat_saf_dfa__baselibs__blocked_execution` + * - UI_01_07 + - Incorrect allocation of execution time + - no + - Execution time allocated by (external) OS on platform level, should be covered centrally at platform level. + * - UI_01_08 + - Incorrect execution flow + - no + - Execution flow controlled by (external) OS on platform level, should be covered centrally at platform level. + * - UI_01_09 + - Incorrect synchronization between software elements + - no + - There is no need for synchronization for baselibs. + * - UI_01_10 + - CPU time depletion + - yes + - Baselibs may deplete or suffer from depletion, :need:`feat_saf_dfa__baselibs__cpu_starvation` + * - UI_01_11 + - Memory depletion + - no + - Not a specific baselibs topic, therefore covered at platform DFA. + * - UI_01_12 + - Other HW unavailability + - no + - No special HW used for baselibs. + + +DFA +=== + +For all identified applicable failure initiators, the DFA is performed in the following section. + +.. feat_saf_dfa:: memory access + :violates: feat_arc_sta__baselibs__static_view_arch + :id: feat_saf_dfa__baselibs__memory_access + :failure_id: UI_01_02 + :failure_effect: memory of using component may be corrupted leading to safety requirement violation + :mitigation_issue: https://github.com/eclipse-score/score/issues/2816 + :sufficient: no + :status: valid + + All the baselibs components have to be developed to ASIL_B standard to maintain Freedom From Interference, + out of bounds access should be detected by unit testing/sanitizers. + +.. feat_saf_dfa:: locked ressource + :violates: feat_arc_sta__baselibs__static_view_arch + :id: feat_saf_dfa__baselibs__locked_ressource + :failure_id: UI_01_04 + :failure_effect: Deadlock/Livelock leads to stalling of the execution + :mitigated_by: feat_req__baselibs__memory_library,aou_req__platform__flow_monitoring + :sufficient: yes + :status: valid + + Only components "filesystem" and "memory_shared" should have the problem ("bitmanipulation" should not be affected due to shortness of execution) + "memory_shared" cares for this by above linked feature requirement and :need:`comp_req__memory__atomic_ops`. + "filesystem" component may fail on this but this is covered by common platform aou linked above. + +.. feat_saf_dfa:: concurrent file access + :violates: feat_arc_sta__baselibs__static_view_arch + :id: feat_saf_dfa__baselibs__conc_file_access + :failure_id: SR_01_02 + :failure_effect: Concurrent file access may lead to corruption of the file + :mitigated_by: aou_req__filesystem__thread_safety + :sufficient: yes + :status: valid + + The user has to care for concurrent file access. This is not covered by the filesytem library. + +.. feat_saf_dfa:: concurrent memory access + :violates: feat_arc_sta__baselibs__static_view_arch + :id: feat_saf_dfa__baselibs__conc_memory_access + :failure_id: SR_01_10 + :failure_effect: Concurrent memory access may lead to corruption of the memory + :mitigated_by: aou_req__bitmanipulation__concurrent_access + :sufficient: yes + :status: valid + + The user has to care for concurrent memory access. This is not covered by the bitmanipulation library. + +.. feat_saf_dfa:: blocked execution + :violates: feat_arc_sta__baselibs__static_view_arch + :id: feat_saf_dfa__baselibs__blocked_execution + :failure_id: UI_01_06 + :failure_effect: Using application is blocked from execution and thus cannot fulfill its safety function + :mitigation_issue: https://github.com/eclipse-score/score/issues/2816 + :sufficient: no + :status: valid + + All the baselibs components have to be developed to ASIL_B standard to maintain Freedom From Interference, + all blocks should be detected by unit testing. + +.. feat_saf_dfa:: CPU starvation + :violates: feat_arc_sta__baselibs__static_view_arch + :id: feat_saf_dfa__baselibs__cpu_starvation + :failure_id: UI_01_10 + :failure_effect: CPU starvation leads to delayed execution and may violate safety timing requirements. + :mitigated_by: aou_req__platform__flow_monitoring + :sufficient: yes + :status: valid + + Some care is taken to avoid using too much CPU time, but this cannot be covered fully. + Platform level AoU asks applications with timing requirements to cover this by program flow monitoring. diff --git a/docs/safety_analysis/fmea.rst b/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..bc3d662f --- /dev/null +++ b/docs/safety_analysis/fmea.rst @@ -0,0 +1,33 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: Baselibs FMEA + :id: doc__baselibs_fmea + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__feature_fmea + +The feature baselibs consists of multiple components which provide very different functionality. +They are also low-complex (i.e. no component architecture is documented, so that the feature architecture is the only one to analyze, +with one exception which is the Json component). + +For a better usability and readability the FMEA will be documented on component level and for every +component individually, but using the feature architecture views (plus additional component architecture if any decompositon was done). + +Consequently there is no AoU detected and documented on feature level. diff --git a/docs/safety_planning/index.rst b/docs/safety_planning/index.rst new file mode 100644 index 00000000..39d99752 --- /dev/null +++ b/docs/safety_planning/index.rst @@ -0,0 +1,128 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +Feature Safety Work Products List +================================= + +.. document:: Baselibs Safety WPs + :id: doc__baselibs_safety_wp + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__platform_safety_plan + + +.. list-table:: Feature Baselibs Work products + :header-rows: 1 + + * - Work product Id + - Link to process + - Process status + - Link to WP + + * - :need:`wp__feat_request` + - :need:`gd_temp__change_feature_request` + - :ndf:`copy('status', need_id='gd_temp__change_feature_request')` + - :need:`doc__baselibs` + + * - :need:`wp__requirements_feat` + - :need:`gd_temp__req_feat_req` + - :ndf:`copy('status', need_id='gd_temp__req_feat_req')` + - :need:`doc__baselibs_requirements` + + * - :need:`wp__requirements_feat_aou` + - :need:`gd_temp__req_aou_req` + - :ndf:`copy('status', need_id='gd_temp__req_aou_req')` + - :need:`doc__baselibs_requirements` + + * - :need:`wp__feature_arch` + - :need:`gd_temp__arch_feature` + - :ndf:`copy('status', need_id='gd_temp__arch_feature')` + - :need:`doc__baselibs_architecture` + + * - :need:`wp__feature_fmea` + - :need:`gd_temp__feat_saf_fmea` + - :ndf:`copy('status', need_id='gd_temp__feat_saf_fmea')` + - :need:`doc__baselibs_fmea` + + * - :need:`wp__feature_dfa` + - :need:`gd_temp__feat_saf_dfa` + - :ndf:`copy('status', need_id='gd_temp__feat_saf_dfa')` + - :need:`doc__baselibs_dfa` + + * - :need:`wp__requirements_inspect` + - :need:`gd_chklst__req_inspection` + - :ndf:`copy('status', need_id='gd_chklst__req_inspection')` + - :need:`doc__baselibs_req_inspection` + + * - :need:`wp__sw_arch_verification` + - :need:`gd_chklst__arch_inspection_checklist` + - :ndf:`copy('status', need_id='gd_chklst__arch_inspection_checklist')` + - :need:`doc__baselibs_arc_inspection` + + * - :need:`wp__verification_feat_int_test` + - :need:`gd_guidl__verification_guide` + - :ndf:`copy('status', need_id='gd_guidl__verification_guide')` + - <Link to WP> + +Feature Safety Package +====================== + +To create the safety package (according to :need:`gd_guidl__saf_package`) the following +documents and work products status have to go to "valid" (after the relevant verification were performed). + +Feature Documents Status +------------------------ + +For all the work product documents the status can be seen by following the "Link to WP". +A summary of the status is also documented in the project's documentation management plan. + +See :ref:`documents_docs_features_baselibs` + +Feature Requirements Status +--------------------------- + +.. needtable:: + :filter: docname is not None and "baselibs" in docname and "requirements" in docname + :style: table + :types: feat_req + :tags: baselibs + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +Feature AoU Status +------------------ + +.. needtable:: + :filter: docname is not None and "baselibs" in docname and "requirements" and "features" in docname + :style: table + :types: aou_req + :tags: baselibs + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +Feature Architecture Status +--------------------------- + +.. needtable:: + :filter: docname is not None and "baselibs" in docname and "architecture" in docname + :style: table + :types: feat_arc_sta; feat_arc_dyn + :tags: baselibs + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/static_reflection_with_serialization/docs/architecture/chklst_arc_inspection.rst b/docs/static_reflection_with_serialization/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..3a8dd5bd --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,46 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Static Reflection Architecture Inspection Checklist + :id: doc__static_reflection_arc_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +Component is missing in feature architecture :need:`doc__baselibs_architecture` and this has to be corrected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "static_reflection" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "static_reflection" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/static_reflection_with_serialization/docs/architecture/index.rst b/docs/static_reflection_with_serialization/docs/architecture/index.rst new file mode 100644 index 00000000..b4020685 --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/architecture/index.rst @@ -0,0 +1,135 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Static Reflection with Serialization Component Architecture +************************************************************ + +.. document:: static_reflection_with_serialization Architecture + :id: doc__static_refl_with_serial_arch + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__component_arch + +Overview/Description +-------------------- + +see :need:`doc__static_reflection_with_serialization` + +Static Architecture +------------------- + +.. comp:: Static Reflection with Serialization + :id: comp__baselibs_static_reflection + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_static_reflection_serialization + :implements: logic_arc_int__baselibs__static_reflection,logic_arc_int__baselibs__generic_serial,logic_arc_int__baselibs__log_serial + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Static Reflection with Serialization Static view + :id: comp_arc_sta__baselibs__static_reflection + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__static_reflect_serial__reflect, comp_req__static_reflect_serial__visitor, comp_req__static_reflect_serial__container, comp_req__static_reflect_serial__nested, comp_req__static_reflect_serial__header_only, comp_req__static_reflect_serial__compile_eff + :belongs_to: comp__baselibs_static_reflection + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Interfaces +---------- + +Static Reflection Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. logic_arc_int_op:: Visit + :id: logic_arc_int_op__baselibs__visit + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__static_reflection + +.. logic_arc_int_op:: Declare Struct Visitable + :id: logic_arc_int_op__baselibs__decl_struct_visit + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__static_reflection + +.. logic_arc_int_op:: Struct Introspection + :id: logic_arc_int_op__baselibs__struct_intro + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__static_reflection + +Generic Serialization Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. logic_arc_int_op:: Serialize + :id: logic_arc_int_op__baselibs__serialize + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__generic_serial + +.. logic_arc_int_op:: Deserialize + :id: logic_arc_int_op__baselibs__deserialize + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__generic_serial + +.. logic_arc_int_op:: Get Serialized Size + :id: logic_arc_int_op__baselibs__get_serial_size + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__generic_serial + +Logging Serialization Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. logic_arc_int_op:: Serialize + :id: logic_arc_int_op__baselibs__log_ser + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__log_serial + +.. logic_arc_int_op:: Deserialize + :id: logic_arc_int_op__baselibs__log_deser + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__log_serial + +.. logic_arc_int_op:: Get Serialized Size + :id: logic_arc_int_op__baselibs__get_log_ser_size + :security: NO + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__log_serial diff --git a/docs/static_reflection_with_serialization/docs/detailed_design/chklst_impl_inspection.rst b/docs/static_reflection_with_serialization/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..cf06eff2 --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Static Reflection Implementation Inspection Checklist + :id: doc__static_reflection_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/static_reflection_with_serialization/docs/index.rst b/docs/static_reflection_with_serialization/docs/index.rst new file mode 100644 index 00000000..830e6ddb --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/index.rst @@ -0,0 +1,52 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +static_reflection_with_serialization +#################################### + +.. document:: Static Reflection With Serialization Library + :id: doc__static_reflection_with_serialization + :status: draft + :safety: ASIL_B + :tags: baselibs_static_reflection_with_serialization + :realizes: wp__cmpt_request + :security: YES + +.. toctree:: + :hidden: + + architecture/index.rst + architecture/chklst_arc_inspection.rst + requirements/index.rst + requirements/chklst_req_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +========= + +This component request proposes a static reflection with serialization library, which provides compile-time visitor pattern +mechanisms and binary serialization capabilities for the S-CORE software platform. The library enables type-safe object +traversal, struct introspection, and efficient data serialization or deserialization. + +Motivation and Rationale +========================= + +The static reflection with serialization library shall provide mechanism for: + +- **Compile-time visitor pattern**: Type-safe traversal of heterogeneous data structures and their nested members using template metaprogramming. +- **Struct introspection**: Automatic field enumeration and metadata extraction for aggregate types. +- **Binary serialization**: Efficient serialization and deserialization of C++ objects with size calculation and type safety. +- **Extensible processing**: Custom visitor implementations for domain-specific operations (logging, IPC, persistence). diff --git a/docs/static_reflection_with_serialization/docs/requirements/chklst_req_inspection.rst b/docs/static_reflection_with_serialization/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..41197ff1 --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,175 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. document:: Static Reflection Requirements Inspection Checklist + :id: doc__static_reflection_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "static_reflection" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: static_reflect + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "static_reflection" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: static_reflect + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/static_reflection_with_serialization/docs/requirements/index.rst b/docs/static_reflection_with_serialization/docs/requirements/index.rst new file mode 100644 index 00000000..99848e85 --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/requirements/index.rst @@ -0,0 +1,99 @@ + .. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Requirements +############ + +.. document:: Static Reflection with Serialization Library Requirements + :id: doc__static_reflect_serial_lib_req + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, static_reflection_serialization_library + +.. comp_req:: Static Reflection Support + :id: comp_req__static_reflect_serial__reflect + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :belongs_to: comp__baselibs_static_reflection + :status: valid + :tags: baselibs + + The library shall provide compile-time reflection-based serialization and deserialization for C++ Data Structures. + +.. comp_req:: Generic Visitor Pattern + :id: comp_req__static_reflect_serial__visitor + :reqtype: Interface + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__consistent_apis, feat_req__baselibs__safety + :belongs_to: comp__baselibs_static_reflection + :status: valid + :tags: baselibs + + The library shall provide a visitor pattern for traversal of C++ data structures. + +.. comp_req:: Automatic Container Iteration + :id: comp_req__static_reflect_serial__container + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :belongs_to: comp__baselibs_static_reflection + :status: valid + :tags: baselibs + + The library shall automatically traverse containers using appropriate iteration. + +.. comp_req:: Nested Type Support + :id: comp_req__static_reflect_serial__nested + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :belongs_to: comp__baselibs_static_reflection + :status: valid + :tags: baselibs + + The library shall support serialization and visitation of nested data structures. + +.. comp_req:: Header-Only Implementation + :id: comp_req__static_reflect_serial__header_only + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :belongs_to: comp__baselibs_static_reflection + :status: valid + :tags: baselibs + + The library shall be implemented as a header-only library to enable compile-time optimizations and avoid runtime dependencies. + +.. comp_req:: Compile-Time Efficiency + :id: comp_req__static_reflect_serial__compile_eff + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :belongs_to: comp__baselibs_static_reflection + :status: valid + :tags: baselibs + + The library shall provide compile-time safety and efficiency of serialization operations with minimal runtime overhead. + +.. needextend:: "__static_reflect_serial__" in id + :+tags: static_reflect diff --git a/docs/static_reflection_with_serialization/docs/safety_analysis/dfa.rst b/docs/static_reflection_with_serialization/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..37e5dd51 --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: Static Reflection DFA + :id: doc__static_reflection_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/static_reflection_with_serialization/docs/safety_analysis/fmea.rst b/docs/static_reflection_with_serialization/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..b1af61cd --- /dev/null +++ b/docs/static_reflection_with_serialization/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: Static Reflection FMEA + :id: doc__static_reflection_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/utils/docs/architecture/chklst_arc_inspection.rst b/docs/utils/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..a1678061 --- /dev/null +++ b/docs/utils/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,47 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: Utils Architecture Inspection Checklist + :id: doc__utils_arc_inspection + :status: valid + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + +Architecture Inspection Checklist +================================= + +No need for component architecture inspection, as there is no additional information as in the +feature architecture :need:`doc__baselibs_architecture` and this is to be inspected. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "utils" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "utils" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/utils/docs/architecture/index.rst b/docs/utils/docs/architecture/index.rst new file mode 100644 index 00000000..293b44ac --- /dev/null +++ b/docs/utils/docs/architecture/index.rst @@ -0,0 +1,90 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Utils Component Architecture +********************************** + +.. document:: Utils Architecture + :id: doc__utils_architecture + :status: valid + :security: YES + :safety: ASIL_B + :realizes: wp__component_arch + +Overview/Description +-------------------- +see :need:`doc__utils` + +Static Architecture +------------------- + +.. comp:: Utils + :id: comp__baselibs_utils + :security: YES + :safety: ASIL_B + :status: valid + :tags: baselibs_utils + :implements: logic_arc_int__baselibs__utils_base64,logic_arc_int__baselibs__utils_scoped_op + :belongs_to: feat__baselibs + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +.. comp_arc_sta:: Utils Static view + :id: comp_arc_sta__baselibs__utils + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__utils__base64, comp_req__utils__scoped_operation, comp_req__utils__deterministic_behavior + :belongs_to: comp__baselibs_utils + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Interfaces +---------- + +.. logic_arc_int_op:: Encode + :id: logic_arc_int_op__utils__base64_encode + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__utils_base64 + +.. logic_arc_int_op:: Decode + :id: logic_arc_int_op__utils__base64_decode + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__utils_base64 + +.. logic_arc_int_op:: Constructor + :id: logic_arc_int_op__utils__scoped_op_construct + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__utils_scoped_op + +.. logic_arc_int_op:: Destructor + :id: logic_arc_int_op__utils__scoped_op_destruct + :security: YES + :safety: ASIL_B + :status: valid + :included_by: logic_arc_int__baselibs__utils_scoped_op diff --git a/docs/utils/docs/detailed_design/chklst_impl_inspection.rst b/docs/utils/docs/detailed_design/chklst_impl_inspection.rst new file mode 100644 index 00000000..d1f0f8e7 --- /dev/null +++ b/docs/utils/docs/detailed_design/chklst_impl_inspection.rst @@ -0,0 +1,106 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. document:: Utils Implementation Inspection Checklist + :id: doc__utils_impl_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__sw_implementation_inspection + + +Implementation Inspection Checklist +=================================== + +Purpose +------- + +The purpose of this checklist is to collect the topics to be checked during implementation, +i.e. in the detailed design and the source code of the units. + +The checklist shall be agnostic to which programming language is used. Differences shall be treated +by linking to C++ or Rust specific documentation. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Implementation Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - IMPL_01_01 + - Is the design according to guidelines? + - see :need:`gd_temp__detailed_design` and :need:`doc_concept__imp_concept` + (e.g. are the views done with the proposed UML diagrams) + - + - + - + * - IMPL_01_02 + - Is the implementation according to specification? + - Check if the linked component requirements are fulfilled + and detailed design also matches architecture description. + - + - + - + * - IMPL_01_03 + - Are the design decisions and constraints documented? + - Check also for plausibility of these. + - + - + - + * - IMPL_01_04 + - Are all external libraries used by the component specified in the detailed design? + - Check the automated dependency analysis. + Also make sure ASIL rated units also only use ASIL rated libraries. + - + - + - + * - IMPL_02_01 + - Are the static and dynamic code analysis reports verified for violations? + - All violations in ASIL related code must be justified. This includes the checks of coding guidelines. + - + - + - + * - IMPL_02_02 + - Do manual checks, that are derived from the coding guideline, find no safety critical error? + - Check this for the programming language used (e.g. C++ <link_to_checks_list>, Rust <link_to_checks_list>) + - + - + - + * - IMPL_02_03 + - Are detailed design and source code consistent? + - Check if the static and dynamic design descriptions match the code (e.g. naming of elements) + and that the respective traceability is established + - + - + - diff --git a/docs/utils/docs/index.rst b/docs/utils/docs/index.rst new file mode 100644 index 00000000..438c9102 --- /dev/null +++ b/docs/utils/docs/index.rst @@ -0,0 +1,64 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +utils +###### + +.. document:: Utils Library + :id: doc__utils + :status: draft + :safety: ASIL_B + :security: YES + :tags: baselibs_utils + :realizes: wp__cmpt_request + +.. toctree:: + :hidden: + + requirements/index.rst + requirements/chklst_req_inspection.rst + architecture/index.rst + architecture/chklst_arc_inspection.rst + safety_analysis/fmea.rst + safety_analysis/dfa.rst + detailed_design/chklst_impl_inspection.rst + +Abstract +======== + +This component request proposes the integration of a safe Utils library for common utility functions and algorithms. + +Motivation and Rationale +======================== + +The Utils library shall provide safe and efficient implementations of common utility functions and algorithms. +The library shall enable developers to perform common tasks in a type-safe manner, reducing the risk of runtime errors and improving code quality. +A Utils library with type-safe utility functions is needed in the S-CORE software platform due to the frequent use of such functions in various features and the need for reliable utility operations. +There are multiple use-cases like calculating string hashes, embedding binary data in string format or managing resource lifetimes. + +Specification +============= + +The following details and requirements describe the aspects of the current feature in the context of S-CORE. + +General considerations +---------------------- + +The Utils library should provide type-safe utility functions and efficient algorithms: + +* :need:`comp_req__utils__base64` +* :need:`comp_req__utils__scoped_operation` +* :need:`comp_req__utils__deterministic_behavior` + +The component should be extensible in the future to support additional utility functions and algorithms as needed. diff --git a/docs/utils/docs/requirements/chklst_req_inspection.rst b/docs/utils/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..e99f079a --- /dev/null +++ b/docs/utils/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,175 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. document:: Utils Requirements Inspection Checklist + :id: doc__utils_req_inspection + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): <contributor/committer explicitly named here, who is the main author, as can be seen in config mgt tooling> +- reviewer: <contributor/committer explicitly named here, who is the main content reviewer, must be different from content responsible> +- moderator: <committer explicitly named here, who is is the safety manager, security manager or quality manager initiating the inspection> +- test expert: <one of the reviewers explicitly named here, to cover REQ_08_01 as described> + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "utils" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: utils + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "utils" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: utils + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title diff --git a/docs/utils/docs/requirements/index.rst b/docs/utils/docs/requirements/index.rst new file mode 100644 index 00000000..a2138787 --- /dev/null +++ b/docs/utils/docs/requirements/index.rst @@ -0,0 +1,66 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. document:: Utils Library Requirements + :id: doc__utils_lib_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: requirements, utils_library + +Functional Requirements +======================= + +.. comp_req:: Base64 Encoding and Decoding + :id: comp_req__utils__base64 + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_utils + + The Utils component shall provide functions for encoding data to Base64 format and decoding Base64 data back to its original form. + +.. comp_req:: Scoped Operation Management + :id: comp_req__utils__scoped_operation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_utils + + The Utils component shall provide a functionality that stores a callback and executes it automatically when the class is destructed + +Non-Functional Requirements +=========================== + +.. comp_req:: Deterministic Behavior + :id: comp_req__utils__deterministic_behavior + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__core_utilities, feat_req__baselibs__safety + :status: valid + :belongs_to: comp__baselibs_utils + + The Utils component shall ensure that all operations complete in a predictable manner and without dynamic memory allocation. + +.. needextend:: "__utils__" in id + :+tags: baselibs, utils diff --git a/docs/utils/docs/safety_analysis/dfa.rst b/docs/utils/docs/safety_analysis/dfa.rst new file mode 100644 index 00000000..70665317 --- /dev/null +++ b/docs/utils/docs/safety_analysis/dfa.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +DFA (Dependent Failure Analysis) +================================ + +.. document:: utils DFA + :id: doc__utils_dfa + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_dfa + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Dependent Failure Initiators +---------------------------- + +.. code-block:: rst + + .. comp_saf_dfa:: <Title> + :violates: <Component architecture> + :id: comp_saf_dfa__<Component>__<Element descriptor> + :failure_id: <ID from DFA failure initiators :need:`gd_guidl__dfa_failure_initiators`> + :failure_effect: "description of failure effect of the failure initiator on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component DFA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets> diff --git a/docs/utils/docs/safety_analysis/fmea.rst b/docs/utils/docs/safety_analysis/fmea.rst new file mode 100644 index 00000000..d6ba8ed6 --- /dev/null +++ b/docs/utils/docs/safety_analysis/fmea.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +FMEA (Failure Modes and Effects Analysis) +========================================= + +.. document:: utils FMEA + :id: doc__utils_fmea + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__sw_component_fmea + +.. note:: Use the content of the document to describe e.g. why a fault model is not applicable for the diagram. + + +Failure Mode List +----------------- + +.. code-block:: rst + + .. comp_saf_fmea:: <Title> + :violates: <Component architecture> + :id: comp_saf_fmea__<Component>__<Element descriptor> + :fault_id: <ID from fault model :need:`gd_guidl__fault_models`> + :failure_effect: "description of failure effect of the fault model on the element" + :mitigated_by: <ID from Component Requirement | ID from AoU Component Requirement> + :mitigation_issue: <ID from Issue Tracker> + :sufficient: <yes|no> + :status: <valid|invalid> + +.. note:: argument is inside the 'content'. Therefore content is mandatory + +.. attention:: + The above directive must be updated according to your component FMEA. + + - The above "code-block" directive must be updated + - Fill in all the needed information in the <brackets>