summaryrefslogtreecommitdiffstats
path: root/user
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2019-01-11 14:44:36 +0100
committerSebastian Huber <sebastian.huber@embedded-brains.de>2019-01-14 07:15:27 +0100
commit3de74baacbb4145642d0e058846485bb4a3f631f (patch)
tree0ca1c20a49f765a293dd06b2ec69e6cc17a623e3 /user
parent89a33b3db80521673bdd7c180f95b834e7f303d4 (diff)
downloadrtems-docs-3de74baacbb4145642d0e058846485bb4a3f631f.tar.bz2
user: Rework "Hardware" chapter
Rename it to "Target Hardware". Remove BSPs section and reference the BSPs chapter instead. Remove explicit list of architectures and reference the BSPs chapter instead. Fix typos. Elaborate multilib description in the architecture section.
Diffstat (limited to 'user')
-rw-r--r--user/bsps/index.rst46
-rw-r--r--user/exe/index.rst2
-rw-r--r--user/glossary/index.rst3
-rw-r--r--user/hardware/architectures.rst108
-rw-r--r--user/hardware/bsps.rst24
-rw-r--r--user/hardware/index.rst9
-rw-r--r--user/hardware/targets.rst28
-rw-r--r--user/index.rst4
8 files changed, 120 insertions, 104 deletions
diff --git a/user/bsps/index.rst b/user/bsps/index.rst
index e5acfd7..a8035e1 100644
--- a/user/bsps/index.rst
+++ b/user/bsps/index.rst
@@ -2,7 +2,7 @@
.. Copyright (C) 2018 embedded brains GmbH
-.. _BoardSupportPackages:
+.. _BSPs:
Board Support Packages
**********************
@@ -16,24 +16,30 @@ applications.
RTEMS contains a large number of BSPs for commonly available simulators and
target hardware.
+You can see the current BSP list in the RTEMS sources by asking RTEMS with:
+
+.. code-block:: shell
+
+ $ ./rtems-bsps
+
.. toctree::
- bsps-aarch64
- bsps-arm
- bsps-bfin
- bsps-epiphany
- bsps-i386
- bsps-lm32
- bsps-m68k
- bsps-microblaze
- bsps-mips
- bsps-moxie
- bsps-nios2
- bsps-or1k
- bsps-powerpc
- bsps-riscv
- bsps-sh
- bsps-sparc64
- bsps-sparc
- bsps-v850
- bsps-x86_64
+ bsps-aarch64
+ bsps-arm
+ bsps-bfin
+ bsps-epiphany
+ bsps-i386
+ bsps-lm32
+ bsps-m68k
+ bsps-microblaze
+ bsps-mips
+ bsps-moxie
+ bsps-nios2
+ bsps-or1k
+ bsps-powerpc
+ bsps-riscv
+ bsps-sh
+ bsps-sparc64
+ bsps-sparc
+ bsps-v850
+ bsps-x86_64
diff --git a/user/exe/index.rst b/user/exe/index.rst
index 9380a00..136a410 100644
--- a/user/exe/index.rst
+++ b/user/exe/index.rst
@@ -2,6 +2,8 @@
.. Copyright (C) 2018 Chris Johns <chrisj@rtems.org>
+.. _Executables:
+
Executables
***********
.. index:: Executable
diff --git a/user/glossary/index.rst b/user/glossary/index.rst
index 2258925..5648b39 100644
--- a/user/glossary/index.rst
+++ b/user/glossary/index.rst
@@ -6,6 +6,9 @@ Glossary
.. glossary::
+ ABI
+ Application Binary Interface
+
Architecture
Family or class of processor based around a common instruction set. RTEMS
architectures follow the GCC architecture model as RTEMS needs an GCC
diff --git a/user/hardware/architectures.rst b/user/hardware/architectures.rst
index 02bcbe0..5328db8 100644
--- a/user/hardware/architectures.rst
+++ b/user/hardware/architectures.rst
@@ -1,30 +1,83 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
Architectures
=============
.. index:: Architectures
-An RTEMS architecture is a class or family of a processor that RTEMS
-supports. The RTEMS architecture model follows the architecture model of
+An RTEMS architecture is a class or family of a processor architecture that
+RTEMS supports. The RTEMS architecture model follows the architecture model of
GCC. An architecture in GCC results in a specific RTEMS GCC compiler. This
compiler may support a range of processors in the family that may have
-differences in instructions sets or floating point support. RTEMS configures
-GCC to create separate runtime libraries for each supported instruction set and
-floating point unit in the architecture. This is termed **multlib**. Multlibs
-are manage automatically by GCC by selecting a specific instruction set or
-specific device in a family.
-
-RTEMS executables are statically linked for a specific target therefore a
-precise and exact match can be made for the hardware that extracts the best
-possible performance. The compiler supports the variants to the instruction set
-and RTEMS extends the specialization to specific processors in an
-architecture. This specialization gives RTEMS a finer resolution of features
-and capabilites a specific device may offer allowing the kernel, drivers and
-application to make the most of those resources. The trade off is portability
-however this is not important because the executable are statically linked for
-a single target.
+differences in instructions sets, floating point support or other aspects.
+RTEMS configures GCC to create separate runtime libraries for each supported
+instruction set, floating point unit, vector unit, word size (e.g. 32-bit and
+64-bit), endianess, code model, :ref:term:`ABI`, processor errata workarounds,
+and so on in the architecture. This is termed *multilib*. Multilibs are chosen
+automatically by GCC via selecting a specific set of machine options.
+
+You can query the multilibs of a specific RTEMS GCC compiler via the
+``-print-multi-lib`` option:
+
+.. code-block:: shell
+
+ $ sparc-rtems5-gcc -print-multi-lib
+ .;
+ soft;@msoft-float
+ v8;@mcpu=v8
+ leon3;@mcpu=leon3
+ leon3v7;@mcpu=leon3v7
+ leon;@mcpu=leon
+ leon3/gr712rc;@mcpu=leon3@mfix-gr712rc
+ leon3v7/gr712rc;@mcpu=leon3v7@mfix-gr712rc
+ leon/ut699;@mcpu=leon@mfix-ut699
+ leon/at697f;@mcpu=leon@mfix-at697f
+ soft/v8;@msoft-float@mcpu=v8
+ soft/leon3;@msoft-float@mcpu=leon3
+ soft/leon3v7;@msoft-float@mcpu=leon3v7
+ soft/leon;@msoft-float@mcpu=leon
+ soft/leon3/gr712rc;@msoft-float@mcpu=leon3@mfix-gr712rc
+ soft/leon3v7/gr712rc;@msoft-float@mcpu=leon3v7@mfix-gr712rc
+ soft/leon/ut699;@msoft-float@mcpu=leon@mfix-ut699
+ soft/leon/at697f;@msoft-float@mcpu=leon@mfix-at697f
+
+Each printed line represents a multilib. The ``.`` corresponds to the default
+multilib. It is used if a set of machine options does not match to a
+specialized multilib. The string before the ``;`` describes the directory in
+the GCC installation used for the particular multilib. After the ``;`` the set
+of machine options for this multilib follows separated by ``@`` characters.
+
+You can figure out the multilib selected by GCC for a set of machine options
+with the ``-print-multi-directory`` option:
+
+.. code-block:: shell
+
+ $ sparc-rtems5-gcc -print-multi-directory -mcpu=leon3
+ leon3
+
+It is crucial that the RTEMS BSP, support libraries and the application code
+are compiled consistently with a compatible set of machine options. Otherwise,
+in the best case errors during linking will occur or you may end up silently
+with undefined behaviour which results in sporadic run-time crashes. A wrong
+set of machine options may result in a running application, however, with
+degraded performance, e.g. hardware floating point unit is not used by the
+mathematical library.
+
+For a list of architectures supported by RTEMS please have a look at the
+sections of the :ref:`Board Support Packages <BSPs>` chapter.
+
+:ref:`RTEMS executables <Executables>` are statically linked for a specific
+target therefore a precise and exact match can be made for the hardware that
+extracts the best possible performance. The compiler supports the variants to
+the instruction set and RTEMS extends the specialization to specific processors
+in an architecture. This specialization gives RTEMS a finer resolution of
+features and capabilities a specific device may offer allowing the kernel,
+drivers and application to make the most of those resources. The trade off is
+portability however this is not important because the executable are statically
+linked for a single target.
.. note::
@@ -32,24 +85,3 @@ a single target.
interface. Loading code via this interface results in an executable image
that is equivalent to statically linked executable of the same code. Dynamic
loading is a system level tool for system architects.
-
-RTEMS supports 18 architectures:
-
-- arm
-- bfin
-- epiphany
-- i386
-- lm32
-- m68k
-- mips
-- moxie
-- nios2
-- no_cpu
-- or1k
-- riscv
-- powerpc
-- sh
-- sparc
-- sparc64
-- v850
-- x86_64
diff --git a/user/hardware/bsps.rst b/user/hardware/bsps.rst
deleted file mode 100644
index c55747d..0000000
--- a/user/hardware/bsps.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
-
-.. _bsps:
-
-Board Support Packages (BSP)
-============================
-.. index:: Board Support Package
-.. index:: BSP
-
-A Board Suport Package is a historical term for a package of code, and
-supporting documentation for a target. The sparation is still important today
-for users with custom hardware.
-
-RTEMS includes 173 board support packages in it's source tree and this is a
-small number of actual targets running because it does not take into account
-the custom targets.
-
-You can see the BSP list in RTEMS by asking RTEMS with:
-
-.. code-block:: shell
-
- $ ./rtems-bsps
diff --git a/user/hardware/index.rst b/user/hardware/index.rst
index ea2c3ab..0442c4f 100644
--- a/user/hardware/index.rst
+++ b/user/hardware/index.rst
@@ -4,16 +4,13 @@
.. _Hardware:
-Hardware
-********
+Target Hardware
+***************
.. index:: Hardware
-
-This section discusses supported Hardware, Architectures, Board Support
-Packages, and running RTEMS on real hardware and simulators.
+.. index:: Target Hardware
.. toctree::
targets
architectures
- bsps
tiers
diff --git a/user/hardware/targets.rst b/user/hardware/targets.rst
index 943d77b..4d5e87f 100644
--- a/user/hardware/targets.rst
+++ b/user/hardware/targets.rst
@@ -8,19 +8,19 @@ Targets
=======
.. index:: Targets
-Hardware that can run RTEMS is often referred to as a *target* because RTEMS is
-specifically aimed at that hardware or target. An RTEMS executable is
-statically linked and executes in a single address space on the target
-hardware. A statically linked executable means the RTEMS Kernel, drivers, third
-party packages and application code is linked into a single executable image. A
-single address space means no virtual memory and no memory protected process
-address space is running within the RTEMS arena and the RTEMS Kernel, drivers
-and application have unprotected access to the whole address space and all
-hardware.
-
-Target hardware supported by RTEMS has a Board Support Package or BSP. A BSP is
-a specific instance of an RTEMS architecture that allows the creation of an
-RTEMS executable. You can view the layering as:
+*Target hardware* that can run RTEMS is often referred to simply as the
+*target* because RTEMS is specifically aimed at that target hardware. An RTEMS
+executable is statically linked and executes in a single address space on the
+target hardware. A statically linked executable means the RTEMS Kernel,
+drivers, third party packages and application code is linked into a single
+executable image. A single address space means no virtual memory and no memory
+protected process address space is running within the RTEMS arena and the RTEMS
+executive, drivers and application have unprotected access to the whole address
+space and all hardware.
+
+Target hardware supported by RTEMS has a :ref:`Board Support Package <BSPs>` or
+BSP. A BSP is a specific instance of an RTEMS architecture that allows the
+creation of an RTEMS executable. You can view the layering as:
.. comment Build image with:
.. comment aafigure hw-layers.txt --textual --type png --option
@@ -31,7 +31,7 @@ RTEMS executable. You can view the layering as:
:align: center
:alt: Software Layers on Hardware
-RTEMS Targets are grouped by architectures and within an architecture there are
+RTEMS targets are grouped by architectures and within an architecture there are
a number of Board Support Packages or BPSs. An architecture is a specific class
or family of processors and can be large such as ARM or specific such as the
NIOS-II or Microblaze.
diff --git a/user/index.rst b/user/index.rst
index b61942e..31895b4 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -12,8 +12,8 @@ RTEMS User Manual (|version|).
| © 2018 Marçal Comajoan Cara
| © 2018 Vidushi Vashishth
| © 2017 Tanu Hari Dixit
- | © 2016, 2017 embedded brains GmbH
- | © 2016, 2017 Sebastian Huber
+ | © 2016, 2019 embedded brains GmbH
+ | © 2016, 2019 Sebastian Huber
| © 2012, 2015 Chris Johns
| © 1988, 2018 On-Line Applications Research Corporation (OAR)