diff --git a/process/folder_templates/features/feature_name/architecture/index.rst b/process/folder_templates/features/feature_name/architecture/index.rst index 99815e6803..de4c9549c1 100644 --- a/process/folder_templates/features/feature_name/architecture/index.rst +++ b/process/folder_templates/features/feature_name/architecture/index.rst @@ -75,6 +75,7 @@ Static Architecture :includes: logic_arc_int__feature_name__interface_name :consists_of: comp__component_name + General Feature Description .. feat_arc_sta:: Static View :id: feat_arc_sta__feature_name__static_view @@ -100,7 +101,7 @@ Dynamic Architecture :status: invalid :fulfils: feat_req__feature_name__some_title - put here a sequence diagram + Put here a sequence diagram Logical Interfaces ------------------ @@ -111,6 +112,8 @@ Logical Interfaces :safety: ASIL_B :status: invalid + General Interface Description + .. needarch:: :scale: 50 :align: center @@ -124,6 +127,8 @@ Logical Interfaces :status: invalid :included_by: logic_arc_int__feature_name__interface_name + General Operation Description + Module Viewpoint ---------------- @@ -155,7 +160,7 @@ They will be replaced by linking the proper SW component definitions in the used :implements: logic_arc_int__feature_name__interface_name .. note:: - Architecture can be split into multiple files, it is an High level architecture_design + Architecture can be split into multiple files, it is an high level architecture design which can be shown without actual c++/rust interfaces and data types and there will be link to lower level architecture till code to get actual api descriptions. diff --git a/process/folder_templates/features/feature_name/requirements/index.rst b/process/folder_templates/features/feature_name/requirements/index.rst index d0f75f846b..a8a1c8393b 100644 --- a/process/folder_templates/features/feature_name/requirements/index.rst +++ b/process/folder_templates/features/feature_name/requirements/index.rst @@ -55,7 +55,7 @@ Requirements :satisfies: stkh_req__requirements__template :status: invalid - The Feature shall do xyz to the user to bring him to this condition at this time + The Feature shall do xyz to the user to bring him to this condition at this time. Note: (optional, not to be verified) @@ -66,7 +66,7 @@ Requirements :safety: ASIL_B :status: invalid - The Feature User shall do xyz to use the feature safely + The Feature User shall do xyz to use the feature safely. .. attention:: The above directives must be updated according to your feature requirements. diff --git a/process/folder_templates/features/feature_name/safety_analysis/dfa.rst b/process/folder_templates/features/feature_name/safety_analysis/dfa.rst index a74b6dfedc..ba1afa5222 100644 --- a/process/folder_templates/features/feature_name/safety_analysis/dfa.rst +++ b/process/folder_templates/features/feature_name/safety_analysis/dfa.rst @@ -49,7 +49,7 @@ Dependent Failure Initiators :sufficient: :status: - .. note:: argument is inside the 'content'. Therefore content is mandatory + .. note:: Argument is inside the 'content'. Therefore content is mandatory. .. attention:: The above directive must be updated according to your feature DFA. diff --git a/process/folder_templates/features/feature_name/safety_analysis/fmea.rst b/process/folder_templates/features/feature_name/safety_analysis/fmea.rst index 21c81d386e..89a6a5ec14 100644 --- a/process/folder_templates/features/feature_name/safety_analysis/fmea.rst +++ b/process/folder_templates/features/feature_name/safety_analysis/fmea.rst @@ -50,7 +50,7 @@ Failure Mode List :sufficient: :status: - .. note:: argument is inside the 'content'. Therefore content is mandatory + .. note:: Argument is inside the 'content'. Therefore content is mandatory. .. attention:: The above directive must be updated according to your feature FMEA. diff --git a/process/folder_templates/modules/module_name/component_name/docs/architecture/index.rst b/process/folder_templates/modules/module_name/component_name/docs/architecture/index.rst index 27d0b97827..df79dd20c6 100644 --- a/process/folder_templates/modules/module_name/component_name/docs/architecture/index.rst +++ b/process/folder_templates/modules/module_name/component_name/docs/architecture/index.rst @@ -102,7 +102,7 @@ Dynamic Architecture :status: invalid :fulfils: comp_req__component_name__some_title - put here a sequence diagram + Put here a sequence diagram Interfaces @@ -128,7 +128,7 @@ Lower Level Components :fulfils: comp_req__component_name__some_title :implements: logic_arc_int__feature_name__interface_name - no architecture but detailed design + No architecture but detailed design .. note:: Architecture can be split into multiple files. At component level the public interfaces to be used by the user and tester to be shown. diff --git a/process/folder_templates/modules/module_name/component_name/docs/requirements/index.rst b/process/folder_templates/modules/module_name/component_name/docs/requirements/index.rst index 01973504b8..66b777004c 100644 --- a/process/folder_templates/modules/module_name/component_name/docs/requirements/index.rst +++ b/process/folder_templates/modules/module_name/component_name/docs/requirements/index.rst @@ -34,6 +34,9 @@ Requirements =================================================================== +Component Requirements +---------------------- + .. comp_req:: Some Title :id: comp_req__component_name__some_title :reqtype: Process @@ -53,6 +56,9 @@ Requirements - Set the status to valid and start the review/merge process - Add other needed requirements for your component +Assumption of Use Requirements +------------------------------ + .. aou_req:: Next Title :id: aou_req__component_name__next_title :reqtype: Process @@ -62,6 +68,22 @@ Requirements The Component User shall do xyz to use the component safely +Environmental Requirements +-------------------------- + +.. aou_req:: Another Title + :id: aou_req__component_name__another_title + :reqtype: Process + :security: YES + :safety: ASIL_B + :status: invalid + :tags: environment + + The Component shall only be used in a xyz environment to ensure its proper functioning. + +Hints +----- + .. attention:: The above directives must be updated according to your feature requirements. diff --git a/process/folder_templates/modules/module_name/component_name/docs/safety_analysis/dfa.rst b/process/folder_templates/modules/module_name/component_name/docs/safety_analysis/dfa.rst index f5318a43dd..62c8f48019 100644 --- a/process/folder_templates/modules/module_name/component_name/docs/safety_analysis/dfa.rst +++ b/process/folder_templates/modules/module_name/component_name/docs/safety_analysis/dfa.rst @@ -49,7 +49,7 @@ Dependent Failure Initiators :sufficient: :status: -.. note:: argument is inside the 'content'. Therefore content is mandatory +.. note:: Argument is inside the 'content'. Therefore content is mandatory. .. attention:: The above directive must be updated according to your component DFA. diff --git a/process/folder_templates/platform/safety_analysis/platform_dfa.rst b/process/folder_templates/platform/safety_analysis/platform_dfa.rst index adb3677003..cf86ee24b4 100644 --- a/process/folder_templates/platform/safety_analysis/platform_dfa.rst +++ b/process/folder_templates/platform/safety_analysis/platform_dfa.rst @@ -51,7 +51,7 @@ Dependent Failure Initiators :mitigation_issue: :sufficient: :status: -.. note:: argument is inside the 'content'. Therefore content is mandatory +.. note:: Argument is inside the 'content'. Therefore content is mandatory. .. attention:: The above directive must be updated according to the platform DFA. diff --git a/process/process_areas/architecture_design/_assets/metamodel_architectural_design.drawio.svg b/process/process_areas/architecture_design/_assets/metamodel_architectural_design.drawio.svg index f8889362a1..a7fde64ab2 100644 --- a/process/process_areas/architecture_design/_assets/metamodel_architectural_design.drawio.svg +++ b/process/process_areas/architecture_design/_assets/metamodel_architectural_design.drawio.svg @@ -1,4 +1,326 @@ - - - -
includes
includes
Feature
Feature
included by
included by
Logical Interface
Logical Interface
Logical Interface
Operation
Logical Interface...
implements
implements
Real Interface
Operation
Real Interface...
included by
included by
Real Interface
Real Interface
implements / uses
implements / uses
includes
includes
Component
Component
includes
includes
Module
ModuleText is not SVG - cannot display \ No newline at end of file + + + + + + + + + + + +
+
+
+ includes +
+
+
+ + + includes + + + + + + + + + + + +
+
+
+ Feature +
+ (feat) +
+
+
+ + + Feature... + + + + + + + + + + + + +
+
+
+ included by +
+
+
+ + + included by + + + + + + + + + + + +
+
+
+ Logical Interface +
+ (logic_arc_int) +
+
+
+
+ + + Logical Interface... + + + + + + + + + + + +
+
+
+ Logical Interface +
+ Operation +
+
+
+ + + Logical Interface... + + + + + + + + + + + + +
+
+
+ implements +
+
+
+ + + implements + + + + + + + + + + + +
+
+
+ Real Interface +
+ Operation +
+
+
+ + + Real Interface... + + + + + + + + + + + + +
+
+
+ included by +
+
+
+ + + included by + + + + + + + + + + + +
+
+
+ Real Interface +
+
+
+ + + Real Interface + + + + + + + + + + + + +
+
+
+ implements / uses +
+
+
+ + + implements / uses + + + + + + + + + + + + +
+
+
+ includes +
+
+
+ + + includes + + + + + + + + + + + +
+
+
+ Component +
+ (comp) +
+
+
+
+ + + Component... + + + + + + + + + + + + +
+
+
+ includes +
+
+
+ + + includes + + + + + + + + + + + +
+
+
+ Module +
+
+
+ + + Module + + + + + + + + + + Text is not SVG - cannot display + + + + diff --git a/process/process_areas/architecture_design/architecture_concept.rst b/process/process_areas/architecture_design/architecture_concept.rst index 214e341c4e..d938c21e5f 100644 --- a/process/process_areas/architecture_design/architecture_concept.rst +++ b/process/process_areas/architecture_design/architecture_concept.rst @@ -123,7 +123,7 @@ Static View The first viewpoint is named as *feature architecture*. It displays the SW modules (= top level SW components) which are required to realize the feature including their interactions. Also the *logical interfaces* and the interaction between the feature and the user are included in this view. On this architectural level the feature requirements shall be allocated. An example for the static architecture is shown here: -.. feat_arc_sta:: Feature 1 +.. feat_arc_sta:: Feature 1 Architecture :id: feat_arc_sta__example_feature__feature_1 :security: YES :safety: QM @@ -265,7 +265,7 @@ Although it is required to create a *DFA* on platform level no additional view i Specification of the architectural design ***************************************** -The architectural design shall be modeled with the help of static, dynamic and interfaces at each defined level. +The architectural design shall be modeled according to the :ref:`building blocks meta model ` with the help of static, dynamic and interfaces at each defined level. For the description a natural language, diagrams or a semi-formal language (*UML*, see :ref:`uml_diagram_selection`) shall be used. The architectural elements itself including their correlations shall be modeled in a database like approach. Therefore following architectural elements shall be used: @@ -277,30 +277,25 @@ The *static view* shows the *building blocks* of the architecture. It shall be c .. list-table:: Definition of the static architectural elements :header-rows: 1 - :widths: 15,35,35 + :widths: 15,35 * - Element - Sphinx Needs Directive - - Code Template * - Feature Architecture - feat_arc_sta - - feat_arc_sta_t * - Component Architecture - comp_arc_sta - - comp_arc_sta_t To represent the CI build tool module (for example a `Bazel Modules `_) an additional container (or package) is introduced. It can only contain components: .. list-table:: Definition of the static module view :header-rows: 1 - :widths: 15,35,35 + :widths: 15,35 * - Element - Sphinx Needs Directive - - Code Template * - Module View - mod_view_sta - - mod_view_sta_t Dynamic view ============ @@ -311,17 +306,14 @@ The dynamic view shall be modeled partly in Sphinx Needs and PlantUML. The compo .. list-table:: Definition of the dynamic architectural elements :header-rows: 1 - :widths: 15,35,35 + :widths: 15,35 * - Element - Sphinx Needs Directive - - Code Template * - Dynamic Feature Architecture - feat_arc_dyn - - feat_arc_sta_t * - Dynamic Component Architecture - comp_arc_dyn - - comp_arc_dyn_t Interface view ============== @@ -330,26 +322,28 @@ The *interface view* focuses on the interfaces of the components and shows the o .. list-table:: Definition of the architectural elements :header-rows: 1 - :widths: 15,35,35 + :widths: 15,35 * - (Logical) Interface - logic_arc_int - - logic_arc_int_t * - (Logical) Interface Operation - logic_arc_int_op - - logic_arc_int_op_t * - (Real) Interface - real_arc_int - - real_arc_int_t * - (Real) Interface Operation - real_arc_int_op - - real_arc_int_op_t Relations between the architectural elements ============================================ The traceability between the architectural elements itself shall be established by modeling the elements in the *docs-as-code* tool. Here a "clickable" architecture can be generated which allows an easy tracing through the element tree. The previously introduced architectural components shall be connected by using following relations: + .. note:: + The current state only considers logic_arc_int, others will be addressed later in the model and is work in progress. + +The following picture shows the metamodel for the architectural design including the defined elements and their relations. +It serves as a guidance for modeling the architecture. + .. figure:: _assets/metamodel_architectural_design.drawio.svg :width: 90% :align: center diff --git a/process/process_areas/architecture_design/architecture_getstrt.rst b/process/process_areas/architecture_design/architecture_getstrt.rst index 1ff3b4a2e9..f902a0299e 100644 --- a/process/process_areas/architecture_design/architecture_getstrt.rst +++ b/process/process_areas/architecture_design/architecture_getstrt.rst @@ -43,10 +43,12 @@ Tooling support Templates ========= -For creating the architectural design, snippets in vs code are available: +For creating the architectural design, snippets in RestructuredText (rst) are available: -* feat_arc__t -* comp_arc__t +* feat +* feat_arc_ +* comp +* comp_arc_ The needs itself which are the basis for the template are defined in the :ref:`Architectural Design `. @@ -58,7 +60,7 @@ Architecture Generation for Sphinx-Needs Overview -------- -The system provides utilities to generate `PlantUML `_ diagrams from requirement specifications. It supports various architectural elements types including: +The system provides utilities to generate diagrams (like `PlantUML `_) diagrams from requirement specifications. It supports various architectural elements types including: * Features * Logical Interfaces @@ -112,7 +114,15 @@ Feature Architecture The following section is an example, how an `Feature `_ looks like and how the architecture of an Feature is described. Please note that components with an "ASIL_B" safety rating are highlighted with red borders in the diagram (e.g., "Component 1"). -.. feat_arc_sta:: Feature Getting Started +.. feat:: Feature Name + :id: feat__feature_name_example + :security: YES + :safety: ASIL_B + :status: invalid + :includes: logic_arc_int__feature_name__interface_name + :consists_of: comp__component_name + +.. feat_arc_sta:: Feature Static Architecture - Getting Started Example :id: feat_arc_sta__example_feature__archdes_getstrt :security: YES :safety: QM @@ -128,7 +138,15 @@ The following section is an example, how an `Feature LI1: EXTRA_LINKAGE_MANUALLY_ADDED -.. comp_arc_sta:: Component Get Started Manually Edited +.. comp_arc_sta:: Component Static View - Get Started Manually Edited :id: comp_arc_sta__example_feature__component_manual_getstrt :status: valid :safety: ASIL_B diff --git a/process/process_areas/architecture_design/guidance/architecture_guideline.rst b/process/process_areas/architecture_design/guidance/architecture_guideline.rst index 596f1bb6c0..cbec7cbcf5 100644 --- a/process/process_areas/architecture_design/guidance/architecture_guideline.rst +++ b/process/process_areas/architecture_design/guidance/architecture_guideline.rst @@ -112,20 +112,16 @@ Based on the concept description a model of the feature architecture should be d .. list-table:: Architectural Elements of the Feature Architecture :header-rows: 1 - :widths: 10,30,30 + :widths: 10,30 * - Element - Sphinx directive - - VS Code Template * - Feature Architecture - - feat_arc_sta, feat_arc_dyn - - feat_arc_sta_t, feat_arc_dyn_t + - feat, feat_arc_sta, feat_arc_dyn * - Logical Interface - logic_arc_int - - logic_arc_int_t * - Logical Interface Operation - logic_arc_int_op - - logic_arc_int_op_t The relations of the static elements are described in :ref:`metamodel_architectural_design`. @@ -187,20 +183,16 @@ According to the architecture design description the model for the component arc .. list-table:: Architectural Elements of the Component Architecture :header-rows: 1 - :widths: 10,30,30 + :widths: 10,30 * - Element - Sphinx directive - - VS Code Template * - Component Architecture - - comp_arc_sta, comp_arc_dyn - - comp_arc_sta_t, comp_arc_dyn_t + - comp, comp_arc_sta, comp_arc_dyn * - (Real) Interface - real_arc_int - - real_arc_int_t * - (Real) Interface Operation - real_arc_int_op - - real_arc_int_op_t The relations of the static elements are described in :ref:`metamodel_architectural_design`. diff --git a/process/process_areas/architecture_design/_assets/architecture_modeling_example.rst b/process/process_areas/architecture_design/guidance/architecture_modeling_example.rst similarity index 88% rename from process/process_areas/architecture_design/_assets/architecture_modeling_example.rst rename to process/process_areas/architecture_design/guidance/architecture_modeling_example.rst index 06b22d4496..757a854583 100644 --- a/process/process_areas/architecture_design/_assets/architecture_modeling_example.rst +++ b/process/process_areas/architecture_design/guidance/architecture_modeling_example.rst @@ -22,7 +22,17 @@ This chapter only serves as an example how an architecture could be modeled in * Feature Architecture File ========================= -.. feat_arc_sta:: Feature 1 +.. feat:: Feature 1 + :id: feat__example_feature + :security: YES + :safety: QM + :status: valid + :includes: logic_arc_int__example_feature__archdes_logical_interface_1, logic_arc_int__example_feature__archdes_logical_interface_2 + :consists_of: comp__component_example_1 + + This is the example feature. + +.. feat_arc_sta:: Feature 1 Static View :id: feat_arc_sta__example_feature__archdes_static :security: YES :safety: QM @@ -122,6 +132,15 @@ Feature Architecture File Module Viewpoint ================ +.. mod:: Module 1 + :id: mod__example_feature_archdes_module_1 + :security: YES + :safety: ASIL_B + :status: valid + :includes: comp__component_example_1 + + This is Module 1. + .. mod_view_sta:: Module 1 :id: mod_view_sta__example_feature__archdes_1 :includes: comp_arc_sta__example_feature__archdes_component_1 @@ -145,6 +164,16 @@ Module Viewpoint Component Architecure File(s) ============================= +.. comp:: Component 1 + :id: comp__component_example_1 + :security: YES + :safety: ASIL_B + :status: invalid + :implements: logic_arc_int__example_feature__archdes_logical_interface_1, logic_arc_int__example_feature__archdes_logical_interface_2 + :uses: logic_arc_int__example_feature__archdes_logical_interface_3 + + Example Component 1 description. + .. comp_arc_sta:: Component 1 :id: comp_arc_sta__example_feature__archdes_component_1 :status: valid @@ -161,7 +190,7 @@ Component Architecure File(s) {{ draw_component(need(), needs) }} -.. comp_arc_sta:: Component 3 +.. comp_arc_sta:: Component 3 Static View :id: comp_arc_sta__example_feature__archdes_component_3 :status: valid :safety: QM diff --git a/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst b/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst index 74f47bee54..ee89753c6a 100644 --- a/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst +++ b/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst @@ -67,6 +67,7 @@ Architectural Model * Interface Operation (real_arc_int_op) * Module + * SW Module (mod) diff --git a/process/process_areas/architecture_design/index.rst b/process/process_areas/architecture_design/index.rst index 453f9b89e1..6761a261c2 100644 --- a/process/process_areas/architecture_design/index.rst +++ b/process/process_areas/architecture_design/index.rst @@ -27,7 +27,7 @@ Architecture Design architecture_roles architecture_workflow architecture_workproducts - _assets/architecture_modeling_example + guidance/architecture_modeling_example .. needextend:: docname is not None and "process_areas/architecture_design" in docname