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 +.. _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 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. +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. -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. +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 ` chapter. + +:ref:`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 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 - -.. _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* 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 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 supported by RTEMS has a :ref:`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: .. 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)