Skip to content

Commit e1435c3

Browse files
armin-acnarmin-acn
authored
Merge pull request #1096 from esrlabs/cr-131315
First draft of FEO safety manual, covering AoU wrt Rust std library.
2 parents 234e75b + 7b403db commit e1435c3

File tree

4 files changed

+200
-0
lines changed

4 files changed

+200
-0
lines changed

‎docs/features/frameworks/feo/modules/feo/docs/index.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
16+
FEO Module Documentation
17+
########################
18+
19+
.. toctree::
20+
:maxdepth: 1
21+
22+
manual/safety_manual

‎docs/features/frameworks/feo/modules/feo/docs/manual/safety_manual.rst

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
FEO Module Safety Manual Draft
16+
==============================
17+
18+
Introduction/Scope
19+
------------------
20+
This is a first *partial draft* version of the FEO (Fixed Order Execution Environment) module safety manual.
21+
For now it only contains Assumptions of Use related to the use of Rust libraries.
22+
23+
Assumed Platform Safety Requirements
24+
------------------------------------
25+
For <S-CORE platform / FEO> the following safety related stakeholder requirements are assumed to define the top level functionality (purpose)>. I.e. from these all the feature and component requirements implemented are derived.
26+
<List here all the stakeholder requirements, with safety not equal to QM, the module's components requirements are derived from.>
27+
28+
Assumptions of Use
29+
------------------
30+
31+
Assumptions on the Environment
32+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
33+
| Generally the assumption of the S-CORE 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.
34+
35+
36+
.. aou_req:: on_target_crates
37+
:id: aou_req__feo__on_target_crates
38+
:reqtype: Functional
39+
:security: YES
40+
:safety: ASIL_B
41+
:status: invalid
42+
43+
The following list is *not yet complete*. It needs to be refined based on a final implementation.
44+
Only the following crates of the FEO module shall be used to build code that runs on
45+
targets in release builds.
46+
47+
- feo
48+
- feo-cpp-build
49+
- feo-cpp-macros
50+
- feo-time
51+
52+
53+
.. aou_req:: rust_core_lib
54+
:id: aou_req__feo__rust_core_lib
55+
:reqtype: Functional
56+
:security: YES
57+
:safety: ASIL_B
58+
:status: valid
59+
60+
The Rust core lib shall be safety qualified
61+
62+
63+
.. aou_req:: rust_std_lib_modules
64+
:id: aou_req__feo__rust_std_lib_modules
65+
:reqtype: Functional
66+
:security: YES
67+
:safety: ASIL_B
68+
:status: invalid
69+
70+
The following list is *not yet complete*. It needs to be refined based on a final implementation.
71+
At the moment, it covers probably about 95% of std library usages.
72+
An accurate list could be determined by switching feo to #![no_std] and looking at the compilation errors,
73+
but it gets quickly out of date with a changing codebase.
74+
The following items from the Rust std library shall be safety qualified:
75+
76+
- std::collections::HashMap
77+
- std::collections::HashSet
78+
- std::fs::File
79+
- std::fs::OpenOptions
80+
- std::io::BufWriter
81+
- std::io::Cursor
82+
- std::io::Error
83+
- std::io::Read
84+
- std::io::Result
85+
- std::io::Write
86+
- std::net::TcpStream
87+
- std::path::Path
88+
- std::path::PathBuf
89+
- std::sync::mpsc::bounded
90+
- std::sync::mpsc::Receiver
91+
- std::sync::mpsc::RecvTimeoutError
92+
- std::sync::mpsc::SyncSender
93+
- std::sync::OnceLock
94+
- std::thread::JoinHandle
95+
- std::thread::spawn
96+
- std::time::Instant
97+
- std::time::SystemTime
98+
- std::time::UNIX_EPOCH
99+
- std::vec::Vec
100+
101+
102+
103+
List of AoUs expected from the environment the platform / module runs on:
104+
105+
106+
.. needtable::
107+
:style: table
108+
:columns: title;id;status
109+
:colwidths: 25,25,25
110+
:sort: title
111+
112+
results = []
113+
114+
for need in needs.filter_types(["aou_req"]):
115+
if need and "environment" in need["tags"]:
116+
results.append(need)
117+
118+
Assumptions on the User
119+
^^^^^^^^^^^^^^^^^^^^^^^
120+
| 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.
121+
| 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:
122+
| 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".
123+
| 2. There are assumption which can be fulfilled by a safety mechanism realized by some other S-CORE 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 S-CORE platform persistency feature.
124+
125+
List of AoUs on the user of the platform features or the module of this safety manual:
126+
127+
.. needtable::
128+
:style: table
129+
:columns: title;id;status
130+
:colwidths: 25,25,25
131+
:sort: title
132+
133+
results = []
134+
135+
for need in needs.filter_types(["aou_req"]):
136+
if need and "environment" not in need["tags"]:
137+
results.append(need)
138+
139+
Safety concept of the SEooC
140+
---------------------------
141+
| <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.>
142+
143+
Safety Anomalies
144+
----------------
145+
| 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>.
146+
147+
References
148+
----------
149+
| <link to the user manual>
150+
| <other links>

‎docs/features/frameworks/feo/modules/index.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
.. _modules:
16+
17+
Modules Documentation
18+
#####################
19+
20+
.. note::
21+
For now, we store the modules documentation in the feature tree, because multi-repo docs are not yet supported.
22+
Once this support becomes available it will be moved to the modules tree.
23+
24+
.. toctree::
25+
:maxdepth: 1
26+
27+
feo/docs/index

‎docs/features/frameworks/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ Frameworks
1919
.. toctree::
2020

2121
feo/index.rst
22+
feo/modules/index

0 commit comments

Comments
 (0)