Add a Hardware section.

6 files changed, 216 insertions, 0 deletions

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 <chrisj@rtems.org>
+.. 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 <chrisj@rtems.org>
+.. 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 <chrisj@rtems.org>
+.. 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 <chrisj@rtems.org>
+.. 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 <chrisj@rtems.org>
+.. 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.