From 2200794478f1403843d56d6c39e6af1ab8c9784a Mon Sep 17 00:00:00 2001 From: "jhr2hi@bosch.com" Date: Thu, 18 Jun 2026 15:47:41 +0200 Subject: [PATCH] fix implementation review findngs --- .../guidance/implementation_process_reqs.rst | 276 +++--------------- .../implementation/implementation_concept.rst | 25 +- .../implementation_workproducts.rst | 8 +- 3 files changed, 67 insertions(+), 242 deletions(-) diff --git a/process/process_areas/implementation/guidance/implementation_process_reqs.rst b/process/process_areas/implementation/guidance/implementation_process_reqs.rst index 007ef2ea50..3830d633f1 100644 --- a/process/process_areas/implementation/guidance/implementation_process_reqs.rst +++ b/process/process_areas/implementation/guidance/implementation_process_reqs.rst @@ -15,6 +15,9 @@ Process Requirements #################### +Please notice, that detail design description files (within MarkDown or RestructuredText) are optional. +Also diagrams are optional, but if they are created, they shall have the following attributes to ensure consistency and traceability. + .. gd_req:: Static Diagram for Unit Interactions :id: gd_req__impl_static_diagram :status: valid @@ -26,7 +29,7 @@ Process Requirements std_req__iso26262__software_845[version==1], std_req__aspice_40__SWE-3-BP1[version==1] - The static diagram shall represent the unit and their relationships using UML notations. + The static diagram shall represent the units and their relationships using UML notations. Diagram Attributes ------------------ @@ -42,11 +45,11 @@ Diagram Attributes std_req__iso26262__software_845[version==1], std_req__aspice_40__SWE-3-BP2[version==1] - Each diagram shall have a unique ID. It shall consist of three parts: + Each diagram shall have a unique name. It shall consist of three parts: - * type of diagram - * structural element - * keyword describing the content of the diagram + * type of diagram + * structural element + * keyword describing the content of the diagram Consider the project's naming convention. @@ -66,44 +69,6 @@ Diagram Attributes 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 - :version: 1 - :tags: manual_prio_2, attribute, mandatory - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall have a security relevance identifier: - - * Yes - * No - -.. gd_req:: Diagram attribute: safety - :id: gd_req__impl_diagram_safety - :status: valid - :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall have a status: - - * valid - * invalid - .. gd_req:: Diagram attribute: description :id: gd_req__impl_diagram_description :status: valid @@ -112,241 +77,87 @@ Diagram Attributes :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - Each diagram shall have a description. The description shall provide a needarch or image of the diagram. + Each diagram shall have a description. .. _detailed_design_linkage: -Diagram Linkage -''''''''''''''' - -.. gd_req:: Diagram Linkage check Component Requirement - :id: gd_req__impl_diagram_check_req - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1], std_req__aspice_40__iic-13-51[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1], std_req__aspice_40__iic-13-51[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 +.. gd_req:: Diagram mandatory consistency + :id: gd_req__impl_diagram_consistency :status: valid :version: 1 - :tags: prio_2_automation, attribute, check + :tags: prio_2_manual, attribute, check :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - 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 + It shall be checked if all diagrams are consistent with the source code and the design principles + outlined in the development plan. This includes checking that the naming of the units, their + interfaces and functions in any diagrams or descriptions matches the naming in the source code to ensure traceability. + That means the diagrams and descriptions should not be outdated and be consistent with + the source code and not introduce new terminology or concepts that are not present in the code. Unit Attributes --------------- -.. gd_req:: Unit attribute: UID - :id: gd_req__impl_unit_uid +.. gd_req:: Unit naming + :id: gd_req__impl_unit_naming :status: valid :version: 1 :tags: manual_prio_1, attribute, mandatory :satisfies: wf__sw_detailed_design[version==1] :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1] - Each unit shall have a unique ID. It shall consist of three parts: + Each unit shall have a proper naming, which is unique within the component and + follows a consistent naming convention. The name should be descriptive and reflect + the functionality of the unit to ensure traceability and understandability. - * type of unit - * structural element - * keyword describing the content of the unit + The naming convention should be defined in the project guidelines and consistently applied across all units. - Consider the project's naming convention. - -.. gd_req:: Unit attribute: description +.. gd_req:: Unit description :id: gd_req__impl_unit_description :status: valid :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each unit shall have a description. - -Unit Linkage -'''''''''''' - -.. gd_req:: Unit Linkage check Component ID - :id: gd_req__impl_unit_check_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each unit shall be linked to the corresponding component id via the attribute belongs_to. - -.. gd_req:: Unit Linkage Component ID - :id: gd_req__impl_unit_linkage_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated + :tags: manual_prio_1, mandatory :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - Each unit shall be automatically linked (inverse direction) to the corresponding component id via the "belongs by" linkage. + Each unit shall have a description in the source code. Interface Attributes -------------------- -.. gd_req:: Interface attribute: UID - :id: gd_req__impl_interface_uid +.. gd_req:: Interface naming + :id: gd_req__impl_interface_naming :status: valid :version: 1 - :tags: manual_prio_1, attribute, mandatory + :tags: manual_prio_1, mandatory :satisfies: wf__sw_detailed_design[version==1] :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1] - 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 + Each interface shall have a proper naming, which is unique within the component and + follows a consistent naming convention. The name should be descriptive and reflect + the functionality of the interface to ensure traceability and understandability. Consider the project's naming convention. -.. gd_req:: Interface attribute: description +.. gd_req:: Interface description :id: gd_req__impl_interface_description :status: valid :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - 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 - :version: 1 - :tags: prio_2_automation, attribute, automated + :tags: manual_prio_1, mandatory :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - Each interface shall be automatically linked (inverse direction) to the corresponding architecture via the "implemented by" linkage. + Each interface shall have a description in the source code if the source code does not + already provide sufficient information. It should provide a clear and comprehensive explanation + of the interface's purpose, its inputs and outputs, and how it interacts with other units + or components. The description should be sufficient to allow users of the interface + to understand how to interact with it without needing to read the implementation details. + It should also include any relevant information about the expected behavior, constraints, + and any assumptions made in the design of the interface. The documentation should be + maintained and updated as the implementation evolves to ensure it remains accurate and useful. Dependency Analysis ''''''''''''''''''' @@ -360,7 +171,8 @@ Dependency Analysis :complies: std_req__iso26262__software_942[version==1] For each component a dependency tree view shall be created to support design inspection and Safety Analysis. - It shall show the libraries used by the component (i.e. which libraries are linked to the component, defined as CI build tool target) up to the leaves of the tree. + It shall show the libraries used by the component (i.e. which libraries are linked to the component, + defined as CI build tool target) up to the leaves of the tree. .. needextend:: docname is not None and "process_areas/implementation" in docname :+tags: implementation diff --git a/process/process_areas/implementation/implementation_concept.rst b/process/process_areas/implementation/implementation_concept.rst index 6ccfba0225..82e743cd0e 100644 --- a/process/process_areas/implementation/implementation_concept.rst +++ b/process/process_areas/implementation/implementation_concept.rst @@ -92,23 +92,36 @@ per unit is **not required**; the unit's attributes and behaviour are documented code itself as the source code is sufficiently self-explanatory and adheres to the design principles outlined in the development plan. This is sufficient for ASIL B compliance per :need:`ISO 26262-6 §8 `, as the structural decomposition -is evident from the directory layout and the component-level static view already captures the -relevant unit relationships. +is evident from the directory layout and the safety/security level and requirements are inherited from the component. -However, for components with complex interactions or a large number of units, a static view can be beneficial for understanding the overall structure and relationships between units. The developer may choose to add a additional unit-level static and dynamic view if they believe it helps to explain the source code better. +However, for components with complex interactions or a large number of units, a textual description, a static or dynamic view can +be beneficial for understanding the overall structure and relationships between units. +The developer may choose to add a additional unit-level description, static and dynamic view if they believe it helps to explain the source code better. +It is important that the naming of the units, their interfaces and functions in any diagrams or descriptions matches the naming in the source code to ensure traceability. +That means the diagrams and descriptions should not be outdated and be consistent with the source code and not introduce new terminology or concepts that are not present in the code. Design Principles of the Units `````````````````````````````` -The unit design shall achieve quality attributes (like simplicity, modularity, and encapsulation) which shall be enforced through coding guidelines and static analysis tooling appropriate for the programming language in use (e.g. MISRA C for C/C++, Clippy lints for Rust) as specified in the project development plan to fulfill the guidelines :need:`ISO 26262-6 §8.4.5, Table 6 ` and :need:`ASPICE SWE.3/SWE.4` requirements. +The unit design shall achieve quality attributes (like simplicity, modularity, and encapsulation) +which shall be enforced through coding guidelines and static analysis tooling appropriate +for the programming language in use (e.g. MISRA C for C/C++, Clippy lints for Rust) as specified +in the project development plan to fulfill the guidelines :need:`ISO 26262-6 §8.4.5, Table 6 ` and :need:`ASPICE SWE.3/SWE.4` requirements. -The **source code** itself shall be self-documenting with meaningful naming and structure. +The **source code** itself shall be self-documenting with meaningful naming and structure +to fulfill the guidelines :need:`ISO 26262-6 §8.4.3 `. **Code comments** may be used where the logic is not self-evident and to give an rationale. These comments, along with commit messages, and any additional documentation accompanying the source code shall use natural language. The interface documentation of a software unit is part of the source code (e.g. public API headers, -trait definitions, or documented function signatures). +trait definitions, or documented function signatures). If interfaces of the units are also interfaces of the component, +they shall follow the same documentation rules as the component interfaces (see :need:`gd_guidl__arch_design`). +Especially for public interfaces, the interface naming should follow the naming of the +logical interface in the feature and component architecture to ensure traceability. +The interface documentation should be clear and comprehensive to ensure that users of the +unit can understand how to interact with it without needing to read the implementation details. +The documentation should be maintained and updated as the implementation evolves to ensure it remains accurate and useful. Diagrams -------- diff --git a/process/process_areas/implementation/implementation_workproducts.rst b/process/process_areas/implementation/implementation_workproducts.rst index 23bfb1b79f..287e56e0c3 100644 --- a/process/process_areas/implementation/implementation_workproducts.rst +++ b/process/process_areas/implementation/implementation_workproducts.rst @@ -26,8 +26,8 @@ Implementation Work Products std_req__aspice_40__iic-04-05[version==1], std_req__aspice_40__iic-11-05[version==1] - Implementation includes source code and detailed design (e.g. in form of comments or linked graphical representations) and SW configuration (e.g. #ifdef) - The "how to" is described in the SW Development Plan guidelines + Implementation includes source code and detailed design (e.g. in form of comments or linked graphical representations) and SW configuration (e.g. #ifdef). + The "how to" is described in the SW Development Plan guidelines. .. workproduct:: Implementation Inspection :id: wp__sw_implementation_inspection @@ -36,7 +36,7 @@ Implementation Work Products :tags: doc_lifecycle_model_2 :complies: std_wp__iso26262__software_952[version==1] - Github review with integrated inspection checklist, only valid Detailed Design and Code get merged + Github review with integrated inspection checklist, only valid Detailed Design and Code get merged. .. workproduct:: Software Development Plan :id: wp__sw_development_plan @@ -45,7 +45,7 @@ Implementation Work Products :tags: doc_lifecycle_model_2 :complies: std_wp__iso26262__software_551[version==1], std_wp__iso26262__software_app_c_58[version==1], std_wp__isosae21434__development_1053[version==1] - Process description of SW development including + 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)