diff --git a/process/folder_templates/modules/module_name/component_name/docs/detailed_design/index.rst b/process/folder_templates/modules/module_name/component_name/docs/detailed_design/index.rst index 227b0e957c..1ecafb1673 100644 --- a/process/folder_templates/modules/module_name/component_name/docs/detailed_design/index.rst +++ b/process/folder_templates/modules/module_name/component_name/docs/detailed_design/index.rst @@ -55,25 +55,104 @@ Static Diagrams for Unit Interactions .. code-block:: rst .. dd_sta:: - :id: dd_sta__<Feature>__<Title> + :id: dd_sta__<Component>__<Title> :security: <YES|NO> :safety: <QM|ASIL_B> :status: <valid|invalid> :implements: <link to component requirement id> :satisfies: <link to component architecture id> + :belongs_to: <link to component id> + :includes: <link to sw_unit id>, <link to sw_unit interface id> - .. image:: <link to drawio image> or .. uml:: <link to plantuml> + .. needarch:: or .. image:: <link to drawio image> Dynamic Diagrams for Unit Interactions -------------------------------------- .. code-block:: rst .. dd_dyn:: <Title> - :id: dd_dyn__<Feature>__<Title> + :id: dd_dyn__<Component>__<Title> :security: <YES|NO> :safety: <QM|ASIL_B> :status: <valid|invalid> :implements: <link to component requirement id> :satisfies: <link to component architecture id> + :belongs_to: <link to component id> + :includes: <link to sw_unit id>, <link to sw_unit interface id> - .. image:: <link to drawio image> or .. uml:: <link to plantuml> + .. needarch:: or .. image:: <link to drawio image> + +Units within the Component +-------------------------- + +In your rst file: + +.. code-block:: rst + + .. sw_unit:: cpp unit + :id: sw_unit__<Component>__<title> + :belongs_to: <link to component id> + + This implements the .... + +In your source file, any programming language, here with C++: + +.. code-block:: cpp + + # need-Id: sw_unit__<Component>__<title> + class <class name> { + public: + + }; + +Interface View +-------------- + +In your rst file: + +.. code-block:: rst + + .. sw_unit_int:: <here InterfaceDemo - change it> + :id: sw_unit_int__<Component>__<title> + :belongs_to: <link to sw_unit id> + :implements: <real_arc_int, real_arc_int_op> + + This implements the .... + +In your source file, any programming language, here with C++: + +.. code-block:: cpp + + # need-Id: sw_unit__<Component>__<title> + class InterfaceDemo + { + public: + virtual ~InterfaceDemo() {} + virtual void OverrideMe() = 0; + }; + +- For cpp using doxygen comments + +.. code-block:: cpp + + /** + * @rst + * .. sw_unit_int:: cpp unit + * :id: sw_unit_int__<Component>__<title> + * :belongs_to: <link to sw_unit id> + * :implements: <real_arc_int, real_arc_int_op> + * + * This implements the .... + * @endrst + */ + +- For rust + +.. code-block:: rust + + //! .. sw_unit_int:: rust unit + //! :id: sw_unit_int__<Component>__<title> + //! :belongs_to: <link to sw_unit id> + //! :implements: <real_arc_int, real_arc_int_op> + //! + //! This implements the .... diff --git a/process/process_areas/implementation/guidance/implementation_guideline.rst b/process/process_areas/implementation/guidance/implementation_guideline.rst index 461ebcef3b..e2cb7ed3c9 100644 --- a/process/process_areas/implementation/guidance/implementation_guideline.rst +++ b/process/process_areas/implementation/guidance/implementation_guideline.rst @@ -20,8 +20,8 @@ Guideline :status: valid :complies: std_req__iso26262__software_744 -This document describes the general guidances for implementation based on the concept which is defined :need:`[[title]]<doc_concept__imp_concept>`. -In the concept is a example of a Detailed Design included. +This document describes the general guidance for implementation based on the concept which is defined :need:`[[title]]<doc_concept__imp_concept>`. +The concept includes an example of a Detailed Design. Workflow for Implementation =========================== @@ -37,7 +37,7 @@ Detailed description which steps are need for implementation. #. Implement the source code, by using the coding guidelines given within the project specific :need:`SW development Plan <wp__sw_development_plan>` for the programming languages in your project. #. Create a pull request for your change. #. Detail Design and Code Inspection is done to review the code of the software and detect errors in it. -#. Check the results of the static and dynamic code analysis (this inlcludes compiler warnings). Acceptance criteria are defined in the Verification Plan :need:`gd_temp__verification_plan`. +#. Check the results of the static and dynamic code analysis (this includes compiler warnings). Acceptance criteria are defined in the Verification Plan :need:`gd_temp__verification_plan`. #. Fix or justify the errors. #. Merge the pull request. #. Create a follow up ticket if not all findings could be fixed. diff --git a/process/process_areas/implementation/guidance/implementation_process_reqs.rst b/process/process_areas/implementation/guidance/implementation_process_reqs.rst index 563cdd5ddc..abfdaf116a 100644 --- a/process/process_areas/implementation/guidance/implementation_process_reqs.rst +++ b/process/process_areas/implementation/guidance/implementation_process_reqs.rst @@ -24,28 +24,296 @@ Process Requirements The static diagram shall represent the unit and their relationships using UML notations. -.. gd_req:: Dynamic Diagram for Unit Interactions - :id: gd_req__impl_dynamic_diagram +Diagram Attributes +------------------ + +.. gd_req:: Diagram attribute: UID + :id: gd_req__impl_diagram_uid + :status: valid + :tags: manual_prio_1, attribute, mandatory + :satisfies: wf__sw_detailed_design + :complies: std_req__iso26262__software_843, std_req__aspice_40__SWE-3-BP1 + + Each diagram shall have a unique ID. It shall consist of three parts: + + * type of diagram + * structural element + * keyword describing the content of the diagram + + Consider the project's naming convention. + +.. gd_req:: Diagram attribute: title + :id: gd_req__impl_diagram_title + :status: valid + :tags: manual_prio_1 attribute, mandatory + :satisfies: wf__sw_detailed_design + :complies: std_req__iso26262__software_843, std_req__aspice_40__SWE-3-BP1 + + The title of the diagram shall provide a short summary of the description, but is not an "additional" requirement. + + This means for example that the word "shall" is not allowed in the title for all diagram. + +.. gd_req:: Diagram attribute: security + :id: gd_req__impl_diagram_security + :status: valid + :tags: manual_prio_2, attribute, mandatory + :satisfies: wf__sw_detailed_design + + Each diagram shall have a security relevance identifier: + + * Yes + * No + +.. gd_req:: Diagram attribute: safety + :id: gd_req__impl_diagram_safety + :status: valid + :tags: manual_prio_1, attribute, mandatory + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall have a automotive safety integrity level (ASIL) identifier: + + * QM + * ASIL_B + +.. gd_req:: Diagram attribute: status + :id: gd_req__impl_diagram_status + :status: valid + :tags: manual_prio_1, attribute, mandatory + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall have a status: + + * valid + * invalid + +.. gd_req:: Diagram attribute: description + :id: gd_req__impl_diagram_description + :status: valid + :tags: manual_prio_1, attribute, mandatory + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall have a description. The description shall provide a needarch or image of the diagram. + +.. _detailed_design_linkage: + +Diagram Linkage +''''''''''''''' + +.. gd_req:: Diagram Linkage check Component Requirement + :id: gd_req__impl_diagram_check_req + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be linked to the corresponding component requirement via the attribute implements. + +.. gd_req:: Diagram Linkage Component Requirement + :id: gd_req__impl_diagram_linkage_req + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be automatically linked (inverse direction) to the corresponding component requirement via the "implemented by" linkage. + +.. gd_req:: Diagram Linkage check Component Architecture + :id: gd_req__impl_diagram_check_arch + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be linked to the corresponding component architecture via the attribute satisfies. + +.. gd_req:: Diagram Linkage Component Architecture + :id: gd_req__impl_diagram_linkage_arch + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be automatically linked (inverse direction) to the corresponding component architecture via the "satisfied by" linkage. + +.. gd_req:: Diagram Linkage check Component ID + :id: gd_req__impl_diagram_check_id + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be linked to the corresponding component id via the attribute belongs_to. + +.. gd_req:: Diagram Linkage Component ID + :id: gd_req__impl_diagram_linkage_id + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be automatically linked (inverse direction) to the corresponding component id via the "belongs by" linkage. + +.. gd_req:: Diagram Linkage includes + :id: gd_req__impl_diagram_check_includes + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be linked to the corresponding + - SW Unit + - SW Unit Interface + via the attribute includes. + +.. gd_req:: Diagram Linkage includes + :id: gd_req__impl_diagram_linkage_includes + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each diagram shall be automatically linked (inverse direction) to the corresponding + - SW Unit + - SW Unit Interface + via the "included by" linkage. + +Diagram Checks +'''''''''''''' + +.. gd_req:: Diagram mandatory attributes provided + :id: gd_req__impl_diagram_mandatory + :status: valid + :tags: prio_2_automation, attribute, check + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + It shall be checked if all mandatory attributes for each diagram are provided by the user. For all diagrams following attributes shall be mandatory: + + .. needtable:: Overview mandatory Diagram attributes + :filter: "mandatory" in tags and "attribute" in tags and "implementation" in tags and type == "gd_req" + :style: table + :columns: title + :colwidths: 30 + +Unit Attributes +--------------- + +.. gd_req:: Unit attribute: UID + :id: gd_req__impl_unit_uid + :status: valid + :tags: manual_prio_1, attribute, mandatory + :satisfies: wf__sw_detailed_design + :complies: std_req__iso26262__software_843, std_req__aspice_40__SWE-3-BP1 + + Each unit shall have a unique ID. It shall consist of three parts: + + * type of unit + * structural element + * keyword describing the content of the unit + + Consider the project's naming convention. + +.. gd_req:: Unit attribute: description + :id: gd_req__impl_unit_description + :status: valid + :tags: manual_prio_1, attribute, mandatory + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each unit shall have a description. + +Unit Linkage +'''''''''''' + +.. gd_req:: Unit Linkage check Component ID + :id: gd_req__impl_unit_check_id :status: valid - :tags: manual_prio_2, mandatory + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 :satisfies: wf__sw_detailed_design - :complies: std_req__iso26262__software_843, std_req__aspice_40__SWE-3-BP2 - The dynamic diagram shall represent the unit and their relationships using UML notations. + Each unit shall be linked to the corresponding component id via the attribute belongs_to. -.. gd_req:: Design to Code Linking - :id: gd_req__impl_design_code_link +.. gd_req:: Unit Linkage Component ID + :id: gd_req__impl_unit_linkage_id :status: valid - :tags: prio_1_automation, mandatory + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 :satisfies: wf__sw_detailed_design - :complies: std_req__iso26262__software_843, std_req__aspice_40__SWE-3-BP3, std_req__aspice_40__SWE-3-BP4 - The detailed design (units and interfaces in DD document) shall be linked - to the source code which implements the units and interfaces in the DD. + Each unit shall be automatically linked (inverse direction) to the corresponding component id via the "belongs by" linkage. + +Interface Attributes +-------------------- + +.. gd_req:: Interface attribute: UID + :id: gd_req__impl_interface_uid + :status: valid + :tags: manual_prio_1, attribute, mandatory + :satisfies: wf__sw_detailed_design + :complies: std_req__iso26262__software_843, std_req__aspice_40__SWE-3-BP1 + + Each interface shall have a unique ID. It shall consist of three parts: + + * type of interface + * structural element + * keyword describing the content of the interface + + Consider the project's naming convention. + +.. gd_req:: Interface attribute: description + :id: gd_req__impl_interface_description + :status: valid + :tags: manual_prio_1, attribute, mandatory + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each interface shall have a description. + +Interface Linkage +''''''''''''''''' + +.. gd_req:: Interface Linkage check SW Unit ID + :id: gd_req__impl_interface_check_id + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each interface shall be linked to the corresponding SW Unit id via the attribute belongs_to. + +.. gd_req:: Interface Linkage SW Unit ID + :id: gd_req__impl_interface_linkage_id + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each interface shall be automatically linked (inverse direction) to the corresponding SW Unit id via the "belongs by" linkage. + +.. gd_req:: Interface Linkage check Architecture + :id: gd_req__impl_interface_check_req + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design + + Each interface shall be linked to the corresponding architecture via the attribute implements. + +.. gd_req:: Interface Linkage Architecture + :id: gd_req__impl_interface_linkage_req + :status: valid + :tags: prio_2_automation, attribute, automated + :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425 + :satisfies: wf__sw_detailed_design - Note: Not every code element must have such a link (i.e. is represented in the detailed design), - these elements are implementation detail. + Each interface shall be automatically linked (inverse direction) to the corresponding architecture via the "implemented by" linkage. +Dependency Analysis +''''''''''''''''''' .. gd_req:: Dependency Analysis :id: gd_req__impl_dependency_analysis diff --git a/process/process_areas/implementation/implementation_getstrt.rst b/process/process_areas/implementation/implementation_getstrt.rst index 1ec8545564..881a80b332 100644 --- a/process/process_areas/implementation/implementation_getstrt.rst +++ b/process/process_areas/implementation/implementation_getstrt.rst @@ -22,20 +22,20 @@ Getting Started This document describes the steps which need to be done to document detailed design and implement the code. -Therefore a detailed guideline :need:`gd_guidl__implementation` and a :need:`[[title]] <doc_concept__imp_concept>` is available. +Therefore a detailed guideline :need:`gd_guidl__implementation` and a :need:`doc_concept__imp_concept` are available. General Workflow ################ -Overview of the implemenation workflow. +Overview of the implementation workflow. .. figure:: _assets/implementation_workflow.drawio.svg :align: center :width: 80% :name: implementation_workflow_fig -The details of what needs to be done in each steps are described in the :need:`gd_guidl__implementation`. +The details of what needs to be done in each step are described in the :need:`gd_guidl__implementation`. Relevant Documents @@ -47,12 +47,12 @@ Implementation Guideline: :need:`gd_guidl__implementation` Details on the implem SW Development Plan: :need:`gd_temp__software_development_plan` Process description of SW development including - - selection of design and programming language - - design guideline - - coding guideline (e.g. MISRA, can also include style guide or naming convention) + - Selection of design and programming language + - Design guideline + - Coding guideline (e.g. MISRA, can also include style guide or naming convention) - SW configuration guideline - Method selection (e.g. for Architecture Verification) - - development tools + - Development tools .. _developer_experience: diff --git a/process/process_areas/implementation/implementation_workflow.rst b/process/process_areas/implementation/implementation_workflow.rst index e71d987990..4e30de2a93 100644 --- a/process/process_areas/implementation/implementation_workflow.rst +++ b/process/process_areas/implementation/implementation_workflow.rst @@ -48,7 +48,8 @@ For a detailed explanation of workflows and their role within the process model, The implementation is created, consisting of - Detailed Design - - Source Code + - Unit + - Interface .. workflow:: Verify Implementation :id: wf__sw_verify_implementation