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.

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-aarch64
-   bsps-arm
+    bsps-arm
-   bsps-bfin
+    bsps-bfin
-   bsps-epiphany
+    bsps-epiphany
-   bsps-i386
+    bsps-i386
-   bsps-lm32
+    bsps-lm32
-   bsps-m68k
+    bsps-m68k
-   bsps-microblaze
+    bsps-microblaze
-   bsps-mips
+    bsps-mips
-   bsps-moxie
+    bsps-moxie
-   bsps-nios2
+    bsps-nios2
-   bsps-or1k
+    bsps-or1k
-   bsps-powerpc
+    bsps-powerpc
-   bsps-riscv
+    bsps-riscv
-   bsps-sh
+    bsps-sh
-   bsps-sparc64
+    bsps-sparc64
-   bsps-sparc
+    bsps-sparc
-   bsps-v850
+    bsps-v850
-   bsps-x86_64
+    bsps-x86_64

user/exe/index.rst

@@ -2,6 +2,8 @@
 
 .. Copyright (C) 2018 Chris Johns <chrisj@rtems.org>
 
+.. _Executables:
+
 Executables
 ***********
 .. index:: Executable

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

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
+An RTEMS architecture is a class or family of a processor architecture that
-supports. The RTEMS architecture model follows the architecture model of
+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
+differences in instructions sets, floating point support or other aspects.
-GCC to create separate runtime libraries for each supported instruction set and
+RTEMS configures GCC to create separate runtime libraries for each supported
-floating point unit in the architecture. This is termed **multlib**. Multlibs
+instruction set, floating point unit, vector unit, word size (e.g. 32-bit and
-are manage automatically by GCC by selecting a specific instruction set or
+64-bit), endianess, code model, :ref:term:`ABI`, processor errata workarounds,
-specific device in a family.
+and so on in the architecture. This is termed *multilib*. Multilibs are chosen
+automatically by GCC via selecting a specific set of machine options.
 
-RTEMS executables are statically linked for a specific target therefore a
+You can query the multilibs of a specific RTEMS GCC compiler via the
-precise and exact match can be made for the hardware that extracts the best
+``-print-multi-lib`` option:
-possible performance. The compiler supports the variants to the instruction set
+
-and RTEMS extends the specialization to specific processors in an
+.. code-block:: shell
-architecture. This specialization gives RTEMS a finer resolution of features
+
-and capabilites a specific device may offer allowing the kernel, drivers and
+    $ sparc-rtems5-gcc -print-multi-lib
-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
+    soft;@msoft-float
-a single target.
+    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

user/hardware/bsps.rst

@@ -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

user/hardware/index.rst

@@ -4,16 +4,13 @@
 
 .. _Hardware:
 
-Hardware
+Target Hardware
-********
+***************
 .. index:: Hardware
-
+.. index:: Target Hardware
-This section discusses supported Hardware, Architectures, Board Support
-Packages, and running RTEMS on real hardware and simulators.
 
 .. toctree::
 
    targets
    architectures
-   bsps
    tiers

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
+*Target hardware* that can run RTEMS is often referred to simply as the
-specifically aimed at that hardware or target. An RTEMS executable is
+*target* because RTEMS is specifically aimed at that target hardware. An RTEMS
-statically linked and executes in a single address space on the target
+executable is statically linked and executes in a single address space on the
-hardware. A statically linked executable means the RTEMS Kernel, drivers, third
+target hardware. A statically linked executable means the RTEMS Kernel,
-party packages and application code is linked into a single executable image. A
+drivers, third party packages and application code is linked into a single
-single address space means no virtual memory and no memory protected process
+executable image. A single address space means no virtual memory and no memory
-address space is running within the RTEMS arena and the RTEMS Kernel, drivers
+protected process address space is running within the RTEMS arena and the RTEMS
-and application have unprotected access to the whole address space and all
+executive, drivers and application have unprotected access to the whole address
-hardware.
+space and all hardware.
 
-Target hardware supported by RTEMS has a Board Support Package or BSP. A BSP is
+Target hardware supported by RTEMS has a :ref:`Board Support Package <BSPs>` or
-a specific instance of an RTEMS architecture that allows the creation of an
+BSP.  A BSP is a specific instance of an RTEMS architecture that allows the
-RTEMS executable. You can view the layering as:
+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.

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, 2019 embedded brains GmbH
-    | © 2016, 2017 Sebastian Huber
+    | © 2016, 2019 Sebastian Huber
     | © 2012, 2015 Chris Johns
     | © 1988, 2018 On-Line Applications Research Corporation (OAR)