[rtems-docs commit] eng: Add glossary terms
Sebastian Huber
sebh at rtems.org
Thu Apr 2 07:47:14 UTC 2020
Module: rtems-docs
Branch: master
Commit: 6f0bc56893aa73de85c4dbd483dc7d6a6fe4a2a2
Changeset: http://git.rtems.org/rtems-docs/commit/?id=6f0bc56893aa73de85c4dbd483dc7d6a6fe4a2a2
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Tue Mar 31 08:04:11 2020 +0200
eng: Add glossary terms
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
More information about the vc
mailing list