From 8da3a62701bd78adc6c2d9e3f858c593a82357c0 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Wed, 6 Jul 2016 14:59:00 +1000 Subject: Add a Hardware section. --- user/architecture/index.rst | 12 -------- user/conf.py | 12 ++++---- user/hardware/architectures.rst | 55 ++++++++++++++++++++++++++++++++++++ user/hardware/bsps.rst | 25 +++++++++++++++++ user/hardware/hw-layers.txt | 16 +++++++++++ user/hardware/index.rst | 18 ++++++++++++ user/hardware/targets.rst | 40 ++++++++++++++++++++++++++ user/hardware/tiers.rst | 62 +++++++++++++++++++++++++++++++++++++++++ user/index.rst | 3 +- 9 files changed, 224 insertions(+), 19 deletions(-) delete mode 100644 user/architecture/index.rst create mode 100644 user/hardware/architectures.rst create mode 100644 user/hardware/bsps.rst create mode 100644 user/hardware/hw-layers.txt create mode 100644 user/hardware/index.rst create mode 100644 user/hardware/targets.rst create mode 100644 user/hardware/tiers.rst diff --git a/user/architecture/index.rst b/user/architecture/index.rst deleted file mode 100644 index eb8beaa..0000000 --- a/user/architecture/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -============= -Architectures -============= - -XXX: preamble Architectures - - - -Testing. :r:arch:`sparc` - diff --git a/user/conf.py b/user/conf.py index 9865a2d..17a4a20 100644 --- a/user/conf.py +++ b/user/conf.py @@ -11,13 +11,8 @@ project = "RTEMS User Manual" exclude_patterns = ['config/build.rst', 'config/runtime.rst', - 'start/installation.rst', - 'start/basics.rst', - 'start/depend.rst', 'start/quick.rst', - 'start/transition.rst', - 'hosts/os.rst', 'hosts/prefixes.rst', 'hosts/macos.rst', @@ -29,11 +24,18 @@ exclude_patterns = ['config/build.rst', 'installation/developer.rst', 'installation/kernel.rst', + 'hardware/targets.rst', + 'hardware/architectures.rst', + 'hardware/bsps.rst', + 'hardware/tiers.rst', + 'tools/build.rst', 'tools/simulation.rst', 'test/create.rst', 'test/running.rst', + 'start/installation.rst', + 'start/transition.rst', 'waf/index.rst'] diff --git a/user/hardware/architectures.rst b/user/hardware/architectures.rst new file mode 100644 index 0000000..1d6fd26 --- /dev/null +++ b/user/hardware/architectures.rst @@ -0,0 +1,55 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. comment: All rights reserved. + +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 +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. + +.. note:: + + RTEMS support dynamically load code through the ``dlopen`` + 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 17 architectures: + +- arm +- bfin +- epiphany +- i386 +- lm32 +- m32c +- m68k +- mips +- moxie +- nios2 +- no_cpu +- or1k +- powerpc +- sh +- sparc +- sparc64 +- v850 diff --git a/user/hardware/bsps.rst b/user/hardware/bsps.rst new file mode 100644 index 0000000..907a161 --- /dev/null +++ b/user/hardware/bsps.rst @@ -0,0 +1,25 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. comment: All rights reserved. + +.. _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/hw-layers.txt b/user/hardware/hw-layers.txt new file mode 100644 index 0000000..7fb29bb --- /dev/null +++ b/user/hardware/hw-layers.txt @@ -0,0 +1,16 @@ + + +--------------------------------------------------+ + | User Application | + +--------------+--------------------+--------------+ + | | | | + | Drivers | Packages | | + | | | | + | +-----+--------------------+ | + | | RTEMS API | + | +-----------------------------------------+ + | | Supercore | + | +---+-----------------------------------------+ + | | BSP | + +----+---------------------------------------------+ + | Hardware | + +--------------------------------------------------+ diff --git a/user/hardware/index.rst b/user/hardware/index.rst new file mode 100644 index 0000000..df4eeef --- /dev/null +++ b/user/hardware/index.rst @@ -0,0 +1,18 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. comment: All rights reserved. + +.. _Hardware: + +Hardware +======== +.. index:: Hardware + +This section discusses supported Hardware, Architectures, Board Support +Packages, and running RTEMS on real hardware and simulators. + +.. include:: targets.rst +.. include:: architectures.rst +.. include:: bsps.rst +.. include:: tiers.rst diff --git a/user/hardware/targets.rst b/user/hardware/targets.rst new file mode 100644 index 0000000..08917c6 --- /dev/null +++ b/user/hardware/targets.rst @@ -0,0 +1,40 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. comment: All rights reserved. + +.. _targets: + +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: + +.. comment Build image with: +.. comment aafigure hw-layers.txt --textual --type png --option +.. comment font=/usr/local/lib/X11/fonts/webfonts/arialbd.ttf --background +.. comment '#dbe5c6' --scale 1.5 -o ../../images/user/hw-layers.png + +.. figure:: ../../images/user/hw-layers.png + :align: center + :alt: Software Layers on Hardware + +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. + +RTEMS is designed to be ported to new target hardware easily and efficiently. diff --git a/user/hardware/tiers.rst b/user/hardware/tiers.rst new file mode 100644 index 0000000..0b216df --- /dev/null +++ b/user/hardware/tiers.rst @@ -0,0 +1,62 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. comment: All rights reserved. + +.. _tiers: + +Tiers +----- +.. index Tiers + +RTEMS has a tiered structure for architecture and BSPs. It provides: + +#. A way to determine the state of a BSP in RTEMS. + +#. A quaility measure for changes entering the RTEMS source code. + +The tier structure in RTEMS is support by the Buildbot continuous integration +server. Changes to RTEMS are automatically built and tested and the results +indicate if a BSP currently meets it's tier status. + +The rules for Tiers are: + +#. A BSP can only be in one of the following tiers: + ++------+-----------------------------------------------------------------------+ +| Tier | Description | ++------+-----------------------------------------------------------------------+ +| 1 | * The RTEMS Kernel must build without error. | +| | * Tests are run on target hardware. | ++------+-----------------------------------------------------------------------+ +| 2 | * The RTEMS Kernel must build without error. | +| | * Tests can be run on simulation. | ++------+-----------------------------------------------------------------------+ +| 3 | * The RTEMS Kernel must build without error. | +| | * There are no test results. | ++------+-----------------------------------------------------------------------+ +| 4 | * The RTEMS Kernel does not build. | ++------+-----------------------------------------------------------------------+ +| 5 | * The BSP is to be removed after the next release. | ++------+-----------------------------------------------------------------------+ + +#. An architecuture's tier is set by the highest BSP tier reached. + +#. The tier level for a BSP is set by the RTEMS Project team. Movement of BSP + between tier level requires agreement. The Buildbot results indicate the + current tier level. + +#. Changes to RTEMS may result in a BSP not meeting it's tier are acceptable if + the change is accompanied by an announcement and a plan on how this is to be + resolved. + +#. Test results are set on a per BSP basis by the RTEMS Project team. Changes + to the test result values requires agreement. The test results are defined + as: + + #. Passes + + #. Expected Failures + + Expected failures must be explicitly listed. A BSP is required to have a + valid test result entry to reach tier 1. diff --git a/user/index.rst b/user/index.rst index 868e187..07edad3 100644 --- a/user/index.rst +++ b/user/index.rst @@ -26,8 +26,7 @@ Table of Contents hosts/index installation/index - architecture/index - bsp/index + hardware/index support/index additional/index -- cgit v1.2.3