Skip to content

Commit a4b897f

Browse files
pawelrutkaqpawelrutkaq
authored
Merge pull request #19 from qorix-group/adwi_module-requirements
Requirements and specs for containers component
2 parents a1b1868 + f75f9b7 commit a4b897f

File tree

20 files changed

+686
-1
lines changed

20 files changed

+686
-1
lines changed

‎docs/baselibs_rust/containers_rust/architecture/index.rst‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
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+
Rust Containers Architecture
16+
============================
17+
18+
.. document:: Rust Containers Architecture
19+
:id: doc__containers_rust_architecture
20+
:status: draft
21+
:safety: ASIL_B
22+
:security: NO
23+
:realizes: wp__component_arch
24+
:tags: baselibs_rust_containers_rust
25+
26+
27+
Overview
28+
--------
29+
30+
The implementation of the containers library comprises two main parts:
31+
32+
- The generic storage abstraction for elements, with two concrete implementations:
33+
heap-allocated and inline storage
34+
- The generic logic for each container type, each of which has two specializations:
35+
one using heap-allocated storage, and one using inline storage
36+
37+
Static Architecture
38+
-------------------
39+
40+
.. comp_arc_sta:: Rust Containers
41+
:id: comp_arc_sta__baselibs_rust__containers_rust
42+
:security: YES
43+
:safety: ASIL_B
44+
:status: valid
45+
:tags: baselibs_rust_containers_rust
46+
:implements: logic_arc_int__b_r__fixvec, logic_arc_int__b_r__inlinevec, logic_arc_int__b_r__fixqueue, logic_arc_int__b_r__inlqueue
47+
48+
.. needarch::
49+
:scale: 50
50+
:align: center
51+
52+
{{ draw_component(need(), needs) }}
53+
54+
55+
Interfaces
56+
----------
57+
58+
.. logic_arc_int:: Fixed-Capacity Vector
59+
:id: logic_arc_int__b_r__fixvec
60+
:security: YES
61+
:safety: ASIL_B
62+
:status: valid
63+
64+
.. logic_arc_int_op:: Push
65+
:id: logic_arc_int_op__cont__fixvec_push
66+
:security: YES
67+
:safety: ASIL_B
68+
:status: valid
69+
:included_by: logic_arc_int__b_r__fixvec
70+
71+
.. logic_arc_int_op:: Pop
72+
:id: logic_arc_int_op__cont__fixvec_pop
73+
:security: YES
74+
:safety: ASIL_B
75+
:status: valid
76+
:included_by: logic_arc_int__b_r__fixvec
77+
78+
.. logic_arc_int_op:: Clear
79+
:id: logic_arc_int_op__cont__fixvec_clear
80+
:security: YES
81+
:safety: ASIL_B
82+
:status: valid
83+
:included_by: logic_arc_int__b_r__fixvec
84+
85+
.. logic_arc_int_op:: Index
86+
:id: logic_arc_int_op__cont__fixvec_index
87+
:security: YES
88+
:safety: ASIL_B
89+
:status: valid
90+
:included_by: logic_arc_int__b_r__fixvec
91+
92+
.. logic_arc_int_op:: Iterate
93+
:id: logic_arc_int_op__cont__fixvec_iterate
94+
:security: YES
95+
:safety: ASIL_B
96+
:status: valid
97+
:included_by: logic_arc_int__b_r__fixvec
98+
99+
100+
.. logic_arc_int:: Inline-Storage Vector
101+
:id: logic_arc_int__b_r__inlinevec
102+
:security: YES
103+
:safety: ASIL_B
104+
:status: valid
105+
106+
.. logic_arc_int_op:: Push
107+
:id: logic_arc_int_op__cont__inlinevec_push
108+
:security: YES
109+
:safety: ASIL_B
110+
:status: valid
111+
:included_by: logic_arc_int__b_r__inlinevec
112+
113+
.. logic_arc_int_op:: Pop
114+
:id: logic_arc_int_op__cont__inlinevec_pop
115+
:security: YES
116+
:safety: ASIL_B
117+
:status: valid
118+
:included_by: logic_arc_int__b_r__inlinevec
119+
120+
.. logic_arc_int_op:: Clear
121+
:id: logic_arc_int_op__cont__inlinevec_clear
122+
:security: YES
123+
:safety: ASIL_B
124+
:status: valid
125+
:included_by: logic_arc_int__b_r__inlinevec
126+
127+
.. logic_arc_int_op:: Index
128+
:id: logic_arc_int_op__cont__inlinevec_index
129+
:security: YES
130+
:safety: ASIL_B
131+
:status: valid
132+
:included_by: logic_arc_int__b_r__inlinevec
133+
134+
.. logic_arc_int_op:: Iterate
135+
:id: logic_arc_int_op__cont__inlinevec_iterate
136+
:security: YES
137+
:safety: ASIL_B
138+
:status: valid
139+
:included_by: logic_arc_int__b_r__inlinevec
140+
141+
142+
.. logic_arc_int:: Fixed-Capacity Queue
143+
:id: logic_arc_int__b_r__fixqueue
144+
:security: YES
145+
:safety: ASIL_B
146+
:status: valid
147+
148+
.. logic_arc_int_op:: Push Front
149+
:id: logic_arc_int_op__cont__fixqueue_pushfront
150+
:security: YES
151+
:safety: ASIL_B
152+
:status: valid
153+
:included_by: logic_arc_int__b_r__fixqueue
154+
155+
.. logic_arc_int_op:: Push Back
156+
:id: logic_arc_int_op__cont__fixqueue_pushback
157+
:security: YES
158+
:safety: ASIL_B
159+
:status: valid
160+
:included_by: logic_arc_int__b_r__fixqueue
161+
162+
.. logic_arc_int_op:: Pop Front
163+
:id: logic_arc_int_op__cont__fixqueue_popfront
164+
:security: YES
165+
:safety: ASIL_B
166+
:status: valid
167+
:included_by: logic_arc_int__b_r__fixqueue
168+
169+
.. logic_arc_int_op:: Pop Back
170+
:id: logic_arc_int_op__cont__fixqueue_popback
171+
:security: YES
172+
:safety: ASIL_B
173+
:status: valid
174+
:included_by: logic_arc_int__b_r__fixqueue
175+
176+
.. logic_arc_int_op:: Clear
177+
:id: logic_arc_int_op__cont__fixqueue_clear
178+
:security: YES
179+
:safety: ASIL_B
180+
:status: valid
181+
:included_by: logic_arc_int__b_r__fixqueue
182+
183+
.. logic_arc_int_op:: Iterate
184+
:id: logic_arc_int_op__cont__fixqueue_iterate
185+
:security: YES
186+
:safety: ASIL_B
187+
:status: valid
188+
:included_by: logic_arc_int__b_r__fixqueue
189+
190+
191+
.. logic_arc_int:: Inline-Storage Queue
192+
:id: logic_arc_int__b_r__inlqueue
193+
:security: YES
194+
:safety: ASIL_B
195+
:status: valid
196+
197+
.. logic_arc_int_op:: Push Front
198+
:id: logic_arc_int_op__cont__inlqueue_pushfront
199+
:security: YES
200+
:safety: ASIL_B
201+
:status: valid
202+
:included_by: logic_arc_int__b_r__inlqueue
203+
204+
.. logic_arc_int_op:: Push Back
205+
:id: logic_arc_int_op__cont__inlqueue_pushback
206+
:security: YES
207+
:safety: ASIL_B
208+
:status: valid
209+
:included_by: logic_arc_int__b_r__inlqueue
210+
211+
.. logic_arc_int_op:: Pop Front
212+
:id: logic_arc_int_op__cont__inlqueue_popfront
213+
:security: YES
214+
:safety: ASIL_B
215+
:status: valid
216+
:included_by: logic_arc_int__b_r__inlqueue
217+
218+
.. logic_arc_int_op:: Pop Back
219+
:id: logic_arc_int_op__cont__inlqueue_popback
220+
:security: YES
221+
:safety: ASIL_B
222+
:status: valid
223+
:included_by: logic_arc_int__b_r__inlqueue
224+
225+
.. logic_arc_int_op:: Clear
226+
:id: logic_arc_int_op__cont__inlqueue_clear
227+
:security: YES
228+
:safety: ASIL_B
229+
:status: valid
230+
:included_by: logic_arc_int__b_r__inlqueue
231+
232+
.. logic_arc_int_op:: Iterate
233+
:id: logic_arc_int_op__cont__inlqueue_iterate
234+
:security: YES
235+
:safety: ASIL_B
236+
:status: valid
237+
:included_by: logic_arc_int__b_r__inlqueue

‎docs/baselibs_rust/containers_rust/index.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
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+
.. _component_containers_rust:
16+
17+
containers_rust
18+
###############
19+
20+
.. document:: Rust Containers Library
21+
:id: doc__containers_rust
22+
:status: draft
23+
:safety: ASIL_B
24+
:security: NO
25+
:realizes: wp__cmpt_request
26+
:tags: baselibs_rust_containers_rust
27+
28+
29+
Abstract
30+
========
31+
32+
This component provides a library of Rust containers with fixed capacity.
33+
Each container is available in two variations: one which stores its elements within the data structure itself, and one which allocates memory on the heap.
34+
The inline-storage containers have a stable, well-defined memory layout and can serve as the basis for implementing *ABI-compatible data structures*.
35+
The heap-allocated containers only perform a single allocation when they are created, and reject operations that would exceed their capacity.
36+
37+
38+
Motivation
39+
==========
40+
41+
Software based on the S-CORE platform requires a rich set of data structures, including vectors, maps, and sets.
42+
These data structures should exhibit deterministic behavior; in particular, operations on them should not fail due to memory allocation errors.
43+
One way to achieve this would be to reserve a fixed amount of memory in the form of static variables.
44+
However, this approach requires selecting the maximum capacity already at compile time.
45+
A more flexible solution, which allows defering this decision until runtime, is to allocate memory only during the startup phase of the program, so that any out-of-memory errors occur immediately and not during the main operational phase.
46+
After the creation of such a *fixed-capacity container*, any operation that would exceed the allocated capacity should fail with an explicit error return value, instead of panicking or aborting the program.
47+
48+
Another use case requiring custom container implementations are *ABI-compatible data structures*.
49+
These data structures guarantee that they can be safely sent to other processes via shared memory.
50+
They have different requirements compared to the aforementioned fixed-capacity containers;
51+
specifically, they need to store their elements *inline*, i.e., within the type instance itself instead of on the heap, and therefore require that their capacity to be chosen at compile-time.
52+
The reason for including these inline-storage containers in this component is that they offer a similar interface to fixed-capacity containers, and share nearly all of their implementation logic.
53+
54+
55+
Rationale
56+
=========
57+
58+
Minimum Capacity on Inline Storage
59+
----------------------------------
60+
61+
The inline storage implementation requires a minimum capacity of 1.
62+
The reason for this is that the containers which use this inline storage are intended as the basis for ABI-compatible data structures, and C++ doesn't allow zero-sized types.
63+
Although it would be possible (through template-specialization for the zero-capacity case) to implement C++ data structures which circumvent this restriction, this would make the C++ code more complex.
64+
Since containers with a statically-determined capacity of zero are not very useful, they are forbidden for now;
65+
this constraint may be relaxed in the future.
66+
67+
Fixed-capacity, heap-allocated containers are not affected by this minimum:
68+
When a capacity of zero is requested, no memory is allocated and the container behaves accordingly.
69+
70+
71+
Maximum Capacity
72+
----------------
73+
74+
The capacity field in containers is encoded as a 32-bit unsigned integer (``u32``), so the maximum number of elements per instance is 4,294,967,295.
75+
This makes the computation of indices within the container's logic more efficient.
76+
Larger containers are expected to be an extremely rare case in the context of the S-CORE platform:
77+
Even single-byte elements would involve reserving more than 4 GiB of memory, a prohibitively large commitment of resources on typical embedded systems.
78+
In case an application really *does* need a larger container, it can implement a custom data structure according to its demands, or it can distribute the elements over several standard containers.
79+
80+
81+
Specification
82+
=============
83+
84+
[Describe the requirements, architecture of any new component.] or
85+
[Describe the change to requirements, architecture, implementation, documentation of any change request.]
86+
87+
.. note::
88+
A CR shall specify the component requirements as part of our platform/project.
89+
Thereby the :need:`rl__project_lead` will approve these requirements as part of accepting the CR (e.g. merging the PR with the CR).
90+
91+
92+
Security Impact
93+
===============
94+
95+
The implementation of the container data structures requires low-level memory management and `unsafe` operations.
96+
These code sections are thoroughly tested and strictly encapsulated behind a safe interface.
97+
The API provided by the data structures doesn't contain any `unsafe` methods beyond those available through the Rust standard library.
98+
Therefore, no security impact is expected.
99+
100+
101+
Safety Impact
102+
=============
103+
104+
[How could the safety be impacted by the new/modified component?]
105+
106+
.. note::
107+
If there are safety concerns in relation to the CR, those concerns should be explicitly written out to make sure reviewers of the CR are aware of them.
108+
109+
Which safety requirements are affected or has to be changed?
110+
Could the new/modified component be a potential common cause or cascading failure initiator?
111+
If applicable, which additional safety measures must be implemented to mitigate the risk?
112+
113+
.. note::
114+
Use Dependency Failure Analysis and/or Safety Software Critically Analysis.
115+
[Methods will be defined later in Process area Safety Analysis]
116+
117+
For new feature/component contributions:
118+
119+
[What is the expected ASIL level?]
120+
[What is the expected classification of the contribution?]
121+
122+
.. note::
123+
Use the component classification method here to classify your component, if it shall to be used in a safety context: :need:`gd_temp__component_classification`.
124+
125+
126+
License Impact
127+
==============
128+
129+
No license impact expected.
130+
131+
132+
How to Teach This
133+
=================
134+
135+
The container types provide an interface which is very similar to the corresponding containers in the Rust standard library, except that capacity-related operations return ``Result`` or ``Option``.
136+
The API should therefore be quick and easy to learn for any Rust developer.
137+
138+
139+
.. toctree::
140+
:hidden:
141+
142+
requirements/index.rst
143+
architecture/index.rst

0 commit comments

Comments
 (0)