[PATCH] eng: Add glossary terms
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Mar 31 06:06:21 UTC 2020
Define the following terms:
* assembler language
* C language
* ELF
* interrupt service
* software component
* software unit
Clarify:
* task
Update #3715.
---
c-user/glossary.rst | 83 +++++++++++++++++++++++++++++++++++++++++++++----
eng/glossary.rst | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++
eng/req-eng.rst | 6 ++--
3 files changed, 169 insertions(+), 9 deletions(-)
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index d0996e8..dfbda11 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -29,6 +29,12 @@ Glossary
ASR
An acronym for :term:`Asynchronous Signal Routine`.
+ assembler language
+ The assembler language is a programming language which can be translated very
+ easily into machine code and data. For this project assembler languages are
+ restricted to languages accepted by the :term:`GNU` assembler
+ program for the target architectures.
+
asynchronous
Not related in order or timing to other occurrences in the system.
@@ -76,6 +82,10 @@ Glossary
buffer
A fixed length block of memory allocated from a partition.
+ C language
+ The C language for this project is defined in terms of
+ :term:`C11`.
+
C++11
The standard ISO/IEC 14882:2011.
@@ -178,6 +188,10 @@ Glossary
EARS
An acronym for Easy Approach to Requirements Syntax.
+ ELF
+ An acronym for
+ `Executable and Linkable Format <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_.
+
embedded
An application that is delivered as a hidden part of a larger system.
For example, the software in a fuel-injection control system is an
@@ -304,6 +318,14 @@ Glossary
serviced. If a pending interrupt is below the current interrupt level,
then the CPU does not recognize that interrupt.
+ interrupt service
+ An *interrupt service* consists of an
+ :term:`Interrupt Service Routine` which is called with a user
+ provided argument upon reception of an interrupt service request. The
+ routine is invoked in interrupt context. Interrupt service requests may have
+ a priority and an affinity to a set of processors. An *interrupt service* is
+ a :term:`software component`.
+
Interrupt Service Routine
An ISR is invoked by the CPU to process a pending interrupt.
@@ -683,12 +705,54 @@ Glossary
A real-time system in which a missed deadline does not compromise the
integrity of the system.
+ software component
+ This term is defined by ECSS-E-ST-40C 3.2.28 as a "part of a software
+ system". For this project a *software component* shall be any of the
+ following items and nothing else:
+
+ * :term:`software unit`
+
+ * explicitly defined :term:`ELF` symbol in a
+ :term:`source code` file
+
+ * :term:`assembler language` data in a source code file
+
+ * :term:`C language` object with static storage duration
+
+ * C language object with thread-local storage duration
+
+ * :term:`thread`
+
+ * :term:`interrupt service`
+
+ * collection of *software components* (this is a software architecture
+ element)
+
+ Please note that explicitly defined ELF symbols and assembler language
+ data are considered a software component only if they are defined in a
+ :term:`source code` file. For example, this rules out symbols
+ and data generated as side-effects by the toolchain (compiler, assembler,
+ linker) such as jump tables, linker trampolines, exception frame information,
+ etc.
+
software item
This term has the same meaning as :term:`software product`.
software product
The *software product* is the :term:`RTEMS` real-time operating system.
+ software unit
+ This term is defined by ECSS-E-ST-40C 3.2.24 as a "separately compilable
+ piece of source code". For this project a *software unit* shall be any of
+ the following items and nothing else:
+
+ * :term:`assembler language` function in a
+ :term:`source code` file
+
+ * :term:`C language` function (external and internal linkage)
+
+ A *software unit* is a :term:`software component`.
+
source code
This project uses the *source code* definition of the
`Linux Information Project <http://www.linfo.org/source_code.html>`_:
@@ -729,12 +793,19 @@ Glossary
An acronym for Test-And-Set.
task
- A logically complete thread of execution. It consists normally of a set
- of registers and a stack. The scheduler assigns processors to a subset
- of the ready tasks. The terms task and thread are synonym in RTEMS. The
- term task is used throughout the Classic API, however, internally in the
- operating system implementation and the POSIX API the term thread is
- used.
+ This project uses the
+ `thread definition of Wikipedia <https://en.wikipedia.org/wiki/Thread_(computing)>`_:
+ "a thread of execution is the smallest sequence of programmed
+ instructions that can be managed independently by a scheduler, which is
+ typically a part of the operating system."
+
+ It consists normally of a set of registers and a stack. The scheduler
+ assigns processors to a subset of the ready tasks. The terms task and
+ :term:`thread` are synonym in RTEMS. The term task is used
+ throughout the Classic API, however, internally in the operating system
+ implementation and the POSIX API the term thread is used.
+
+ A *task* is a :term:`software component`.
Task Control Block
A data structure associated with each task used by RTEMS to manage that
diff --git a/eng/glossary.rst b/eng/glossary.rst
index c58e67f..d0fc1eb 100644
--- a/eng/glossary.rst
+++ b/eng/glossary.rst
@@ -1,6 +1,7 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2017, 2019 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 1988, 1998 On-Line Applications Research Corporation (OAR)
Glossary
********
@@ -14,6 +15,19 @@ Glossary
API
An acronym for Application Programming Interface.
+ assembler language
+ The assembler language is a programming language which can be translated very
+ easily into machine code and data. For this project assembler languages are
+ restricted to languages accepted by the :term:`GNU` assembler
+ program for the target architectures.
+
+ C language
+ The C language for this project is defined in terms of
+ :term:`C11`.
+
+ C11
+ The standard ISO/IEC 9899:2011.
+
CCB
An acronym for Change Control Board.
@@ -24,6 +38,10 @@ Glossary
EARS
An acronym for Easy Approach to Requirements Syntax.
+ ELF
+ An acronym for
+ `Executable and Linkable Format <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_.
+
GCC
An acronym for `GNU Compiler Collection <https://gcc.gnu.org/>`_.
@@ -34,6 +52,17 @@ Glossary
GNU
An acronym for `GNU's Not Unix <https://www.gnu.org/>`_.
+ interrupt service
+ An *interrupt service* consists of an
+ :term:`Interrupt Service Routine` which is called with a user
+ provided argument upon reception of an interrupt service request. The
+ routine is invoked in interrupt context. Interrupt service requests may have
+ a priority and an affinity to a set of processors. An *interrupt service* is
+ a :term:`software component`.
+
+ Interrupt Service Routine
+ An ISR is invoked by the CPU to process a pending interrupt.
+
ISVV
An acronym for Independent Software Verification and Validation.
@@ -44,12 +73,54 @@ Glossary
RTEMS
An acronym for Real-Time Executive for Multiprocessor Systems.
+ software component
+ This term is defined by ECSS-E-ST-40C 3.2.28 as a "part of a software
+ system". For this project a *software component* shall be any of the
+ following items and nothing else:
+
+ * :term:`software unit`
+
+ * explicitly defined :term:`ELF` symbol in a
+ :term:`source code` file
+
+ * :term:`assembler language` data in a source code file
+
+ * :term:`C language` object with static storage duration
+
+ * C language object with thread-local storage duration
+
+ * :term:`thread`
+
+ * :term:`interrupt service`
+
+ * collection of *software components* (this is a software architecture
+ element)
+
+ Please note that explicitly defined ELF symbols and assembler language
+ data are considered a software component only if they are defined in a
+ :term:`source code` file. For example, this rules out symbols
+ and data generated as side-effects by the toolchain (compiler, assembler,
+ linker) such as jump tables, linker trampolines, exception frame information,
+ etc.
+
software item
This term has the same meaning as :term:`software product`.
software product
The *software product* is the :term:`RTEMS` real-time operating system.
+ software unit
+ This term is defined by ECSS-E-ST-40C 3.2.24 as a "separately compilable
+ piece of source code". For this project a *software unit* shall be any of
+ the following items and nothing else:
+
+ * :term:`assembler language` function in a
+ :term:`source code` file
+
+ * :term:`C language` function (external and internal linkage)
+
+ A *software unit* is a :term:`software component`.
+
source code
This project uses the *source code* definition of the
`Linux Information Project <http://www.linfo.org/source_code.html>`_:
@@ -57,5 +128,23 @@ Glossary
software as it is originally written (i.e., typed into a computer) by a
human in plain text (i.e., human readable alphanumeric characters)."
+ task
+ This project uses the
+ `thread definition of Wikipedia <https://en.wikipedia.org/wiki/Thread_(computing)>`_:
+ "a thread of execution is the smallest sequence of programmed
+ instructions that can be managed independently by a scheduler, which is
+ typically a part of the operating system."
+
+ It consists normally of a set of registers and a stack. The scheduler
+ assigns processors to a subset of the ready tasks. The terms task and
+ :term:`thread` are synonym in RTEMS. The term task is used
+ throughout the Classic API, however, internally in the operating system
+ implementation and the POSIX API the term thread is used.
+
+ A *task* is a :term:`software component`.
+
+ thread
+ This term has the same meaning as :term:`task`.
+
YAML
An acronym for `YAML Ain't Markup Language <https://yaml.org/>`_.
diff --git a/eng/req-eng.rst b/eng/req-eng.rst
index 61b82be..a5e615d 100644
--- a/eng/req-eng.rst
+++ b/eng/req-eng.rst
@@ -934,9 +934,9 @@ program may be provided to place Doxygen markup in assembler files. The
software architecture is documented via Doxygen groups. Each Doxygen group
name should have a project-specific name and the name should be unique within
the project, e.g. RTEMSTopLevel\ MidLevel\ LowLevel. The link from a Doxygen
-group to its parent group is realized through the `@ingroup` special command.
-The link from a Doxygen group or software component to the corresponding
-requirement is realized through a `@satisfy{req}`
+group to its parent group is realized through the ``@ingroup`` special command.
+The link from a Doxygen group or :term:`software component` to the
+corresponding requirement is realized through a ``@satisfy{req}``
`custom command <http://www.doxygen.nl/manual/custcmd.html>`_
which needs the identifier of the requirement as its one and only parameter.
Only links to parents are explicitly given in the Doxygen markup. The links
--
2.16.4
More information about the devel
mailing list