Skip to content

Commit

Permalink
com: resolve refernce issues; clean up additional files and configura…
Browse files Browse the repository at this point in the history 
…tion

Issue-ref: see #69
  • Loading branch information
@qor-lb
qor-lb committed Jan 9, 2025
1 parent c303827 commit 8a955cb
Show file tree
Hide file tree
Showing 5 changed files with 23 additions and 113 deletions.
2 changes: 0 additions & 2 deletions .env
View file

This file was deleted.

14 changes: 0 additions & 14 deletions .vscode/settings.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,4 @@
"[restructuredtext]": {
"editor.tabSize": 3,
},

// Python emnvironment
"python.envFile": "${workspaceFolder}/.env",

// Restructured Text
"restructuredtext.linter.doc8.extraArgs": [
"--config",
"${workspaceFolder}/docs/doc8.ini"
],

// Sphinx-Needs
"ubcode.srcDir": "${workspaceFolder}/docs",
"ubcode.needsJson": "${workspaceFolder}/docs/needs.json",

}
78 changes: 1 addition & 77 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,83 +17,7 @@
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# from process.process_model_configuration import *
# from _extensions import metamodel, layouts

class metamodel:
needs_types = [
# Requirements
dict(
directive="stkh_req",
title="Stakeholder requirements",
prefix="STKH_REQ__",
color="#BFD8D2",
style="node",
),
dict(
directive="tool_req",
title="Tool Requirements",
prefix="TOOL_REQ__",
color="#BFD8D2",
style="node",
),
]

# Define extra options for needs object
needs_extra_options = [
"security",
"safety",
"level",
"rationale",
"mitigated_by",
"reqtype",
"codelink",
"testlink",
"reqcovered",
"testcovered",
]

needs_extra_links = [
# TODO: Refer process document for the usage of links
{
"option": "satisfies",
"incoming": "is satisfied by",
"outgoing": "satisfies",
"style_start": "-up",
"style_end": "->",
},
{"option": "implements", "incoming": "implements by", "outgoing": "implements"},
]

class layouts:
needs_layouts = {
"score": {
"grid": "complex",
"layout": {
"head_left": [
'<<meta("title")>>',
],
"head": [
'status: **<<meta("status")>>**',
'security: **<<meta("security")>>**',
'safety: **<<meta("safety")>>**',
],
"head_right": [
'<<collapse_button("meta",collapsed="icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>> '
],
"meta_left": [
'<<meta_all(no_links=True, exclude=["layout","style"])>>',
"<<meta_links_all()>>",
],
"meta_right": [],
"footer_left": ["<<meta_id()>>"],
"footer": ['<<meta("type_name")>>'],
"footer_right": [],
},
},
}

needs_global_options = {"layout": "score"}

from _extensions import metamodel, layouts


# -- Project information -----------------------------------------------------
Expand Down
2 changes: 0 additions & 2 deletions docs/doc8.ini
View file

This file was deleted.

40 changes: 22 additions & 18 deletions docs/features/communication/ipc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,9 @@ Information Elements

There are three fundamental concepts of information exchange defined. One communication element represents each concept:

* **Topics**: A topic is the information carrier for **data**. A unique Id identifies a topic while a *data type* defines it's memory layout. The topic carries zero or multiple *values*. A value represents a single instances of the data type. See _`Topics`, _`Names`, _`Data Types`.
* **Remote Procedures**: A remote procedure is the information carrier for **execution** progress. A Id handle identifies the remote procedure together with an ordered set of named *parameters*. Each parameter defined by a data type. A caller of a remote procedure can cause it's activation by invoking the remote procedure with passed *arguments*. An argument is a single value instance for a parameter. See _`Remote Procedures`, _`Names`, _`Data Types`.
* **Events**: An event is the information carrier for runtime **synchronization**. A unique Id identifies the event. It signals the change of state. There is no data conveyed with the event. See _`Events`, _`Names`.
* **Topics**: A topic is the information carrier for **data**. A unique Id identifies a topic while a *data type* defines it's memory layout. The topic carries zero or multiple *values*. A value represents a single instances of the data type. See `Topics`_, `Names`_, `Data Types`_.
* **Remote Procedures**: A remote procedure is the information carrier for **execution** progress. A Id handle identifies the remote procedure together with an ordered set of named *parameters*. Each parameter defined by a data type. A caller of a remote procedure can cause it's activation by invoking the remote procedure with passed *arguments*. An argument is a single value instance for a parameter. See `Remote Procedures`_, `Names`_, `Data Types`_.
* **Events**: An event is the information carrier for runtime **synchronization**. A unique Id identifies the event. It signals the change of state. There is no data conveyed with the event. See `Events`_, `Names`_.

While the Id uniquely identifies an information element within the communication framework, it can also have a *name* as alias to conveniently identify the element. While the Id may not be publicly known, the *name* allows for public lookup.

Expand All @@ -68,21 +68,21 @@ We define three fundamental building elements:

The combination of NodeId and EndpointId we also refer to as *address*. As nodes are also endpoints, they implicitly have an address.

Nodes and endpoints may also be identified by a *name* that resolves into references to these elements. See _`Names`, _`References`.
Nodes and endpoints may also be identified by a *name* that resolves into references to these elements. See `Names`_, `References`_.

Connecting nodes though links creates a mesh of nodes that can mutually exchange information utilizing the above concepts. The boundary of the mesh is at the sole discretion of the deployment and may span from a single application into a connected cloud environment.

The entirety of connected nodes within a mesh we call *fabric*.

**Design Note**
.. admonition:: Design Note

From a perspective of safety, a node also encapsulates a single safety domain. Links provide the means for separating safety domains and thus allow for mixed criticality applications.
From a perspective of safety, a node also encapsulates a single safety domain. Links provide the means for separating safety domains and thus allow for mixed criticality applications.


Names
-----

A name is an UTF-8 tag of an element. The underlying Unicode standard is release 16.0.0 https://www.unicode.org/versions/Unicode16.0.0/.
A name is an UTF-8 tag of an element. The underlying Unicode standard is `release 16.0.0 <https://www.unicode.org/versions/Unicode16.0.0>`_.

All codepoints are valid in a name with the exception of the following codepoints:

Expand All @@ -100,11 +100,11 @@ Further discouraged is the use of the *whitespace* codepoint ``SPACE``: `` `` ``

Element names prefixed with an underscore ``LOW LINE``: ``_`` ``&#005F`` are regarded to have *private* visibility within the scope they are defined in. While references to private elements are possible, name resolution ony works from within the namespace they are defined in.

**Design Note**
.. admonition:: Design Note

A name is not a property of an element itself.
Instead, a name acts as an *alias* to obtain an element *reference*.
See _`References`.
A name is not a property of an element itself.
Instead, a name acts as an *alias* to obtain an element *reference*.
See `References`_.


Namespaces
Expand Down Expand Up @@ -320,6 +320,7 @@ References
The communication framework allows for three potential classes of references:

* References to data types

There are no data types defined for references to data types.

* References to information elements
Expand All @@ -329,6 +330,7 @@ The communication framework allows for three potential classes of references:
* Event References, data type ``EventRef``

* References to infrastructure elements

Currently we do not define references to infrastructure elements.
However, for conceptual symmetry reasons and application value they
might come up in future versions.
Expand All @@ -350,13 +352,13 @@ The application should not have access to handles directly, but only to the refe
The operations granted through a reference to an information item shall be identical to the operations of the information item itself.


**Implementation Note**
.. admonition:: Implementation Note

Internally, the communication framework may actually only pass TopicRef's to the application. From a semantic view it makes no difference to hold a TopicRef or a Topic directly.
Internally, the communication framework may actually only pass TopicRef's to the application. From a semantic view it makes no difference to hold a TopicRef or a Topic directly.

**Implementation Note**
.. admonition:: Implementation Note

A ``TopicRef`` is *not* the same as ``&Topic`` as it may require additional validity checks.
A ``TopicRef`` is *not* the same as ``&Topic`` as it may require additional validity checks.


Topics
Expand Down Expand Up @@ -412,7 +414,9 @@ Result

A remote procedure may produce a result that is returned to the caller. The result also has a data type and consists of a single value.

**Note**: Instead of passing back the result from the procedure the caller may pass a result-return reference that is a remote procedure itself. This way the framework may have a straight-forward way of implementing a Future mechanism that completes upon reception of the response call.
.. note::

Instead of passing back the result from the procedure the caller may pass a result-return reference that is a remote procedure itself. This way the framework may have a straight-forward way of implementing a Future mechanism that completes upon reception of the response call.

Name & Namespace
````````````````
Expand Down Expand Up @@ -445,7 +449,7 @@ Events
An event is an information element that communicates the change of a state. An event has no value.
The main purpose of an event is to support runtime orchestration.

**Note**: An Event is not the same as a topic with no data. Topic mechanisms are designed to convey values. Events convey occurrences of state changes.
.. note:: An Event is not the same as a topic with no data. Topic mechanisms are designed to convey values. Events convey occurrences of state changes.

Publisher & Subscriber
``````````````````````
Expand Down Expand Up @@ -526,7 +530,7 @@ Security

We base this document on the ISO/SAE 21434 released in August 2021.

Communication and data exchange at the boundaries within the communication framework is subject of security considerations.
Communication and data exchange at the boundaries within the communication framework is subject of security considerations.

The communication framework shall support the following principal security capabilities:

Expand Down

0 comments on commit 8a955cb

Please sign in to comment.