summaryrefslogtreecommitdiffstats
path: root/user
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-07-06 14:59:00 +1000
committerChris Johns <chrisj@rtems.org>2016-07-06 14:59:00 +1000
commit8da3a62701bd78adc6c2d9e3f858c593a82357c0 (patch)
treed36bd54da6e5ed6b616fa977e700182f5c564e36 /user
parentb73ba927debec75971630b6911540e46f74c44d9 (diff)
downloadrtems-docs-8da3a62701bd78adc6c2d9e3f858c593a82357c0.tar.bz2
Add a Hardware section.
Diffstat (limited to 'user')
-rw-r--r--user/architecture/index.rst12
-rw-r--r--user/conf.py12
-rw-r--r--user/hardware/architectures.rst55
-rw-r--r--user/hardware/bsps.rst25
-rw-r--r--user/hardware/hw-layers.txt16
-rw-r--r--user/hardware/index.rst18
-rw-r--r--user/hardware/targets.rst40
-rw-r--r--user/hardware/tiers.rst62
-rw-r--r--user/index.rst3
9 files changed, 224 insertions, 19 deletions
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 <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.
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