Directory Structure
*******************

The RTEMS directory structure is designed to meet the following requirements:

  * encourage development of modular components.

  * isolate processor and target dependent code, while allowing as much common source code as possible to be shared across multiple processors and targets.

  * allow multiple RTEMS users to perform simultaneous compilation of RTEMS and its support facilities for different processors and targets.

The resulting directory structure has processor and target dependent source files isolated from generic files.  When RTEMS is built, object directories and an install point will be automatically created based upon the target BSP selected.  The placement of object files based upon the selected BSP name insures that object files are not mixed across CPUs or targets. This in combination with the make files allows the specific compilation options to be tailored for a particular target board.  For example, the efficiency of the memory subsystem for a particular target board may be sensitive to the alignment of data structures, while on another target board with the same processor memory may be very limited.  For the first target, the options could specify very strict alignment requirements, while on the second the data structures could be "packed" to conserve memory.  It is impossible to achieve this degree of flexibility without providing source code.

Suites
======

The RTEMS source tree is organized based on the following four variables:

  * language,

  * target processor,

  * target board, and

  * compiler vendor (Ada only).

The language may be either C or Ada and there is currently nothing shared between the source trees for these two implementations of RTEMS.  The user generally selects the subdirectory for the implementation they are using and ignores that for the other implementation.  The only exceptions to this normally occurs when comparing the source code for the two implementations or when porting both to a new CPU or target board.  The following shows the top level RTEMS directory structure which includes directories for each language implementation and a language independent source documentation directory.  The source documentation directory is currently not supported.

Each of the following sections will describe the contents of the directories in the RTEMS source tree.

C Suites
--------

The following table lists the suites currently included with the C implementation of RTEMS and the directory in which they may be located:

The top level directory structure for the C implementation of RTEMS is as follows:

This directory contains the subdirectories which contain the entire C implementation of the RTEMS executive. The "build-tools" directory contains an assortment of support tools for the RTEMS development environment.  Two subdirectories exist under "build-tools" which contain scripts (executables) and source for the support tools.  The "make" directory contains configuration files and subdirectories which provide a robust host and cross-target makefile system supporting the building of the  executive for numerous application environments.  The "update_tools" directory contains utilities which aid in the updating from a previous version to the current version of the RTEMS executive.

The "src" directory structure for the C implementation of RTEMS is as follows:

This directory contains all source files that comprises the RTEMS executive, supported target board support packages, and the RTEMS Test Suite.

Executive Source Directory
--------------------------

The "exec" directory structure for the C implementation is as follows:

This directory contains a set of subdirectories which contains the source files comprising the executive portion of the RTEMS development environment.  At this point the API specific and "supercore" source code files are separated into distinct directory trees.  The "rtems" and the "posix" subdirectories contain the C language source files for each module comprising the respective API.  Also included in this directory are the subdirectories "sapi" and "score" which are the supercore modules.  Within the "score" directory the CPU dependent modules are found.

The "cpu" directory contains a subdirectory for each target CPU supported by the RELEASE release of the RTEMS executive.  Each processor directory contains the CPU dependent code necessary to host RTEMS.  The "no_cpu" directory provides a starting point for developing a new port to an unsupported processor.  The files contained within the "no_cpu" directory may also be used as a reference for the other ports to specific processors.

Support Library Source Directory
--------------------------------

The "lib" directory contains the support libraries and BSPS. Board support packages (BSPs), processor environment start up code, C library support, the FreeBSD TCP/IP stack, common BSP header files, and miscellaneous support functions are provided in the subdirectories. These are combined with the RTEMS executive object to form the single RTEMS library which installed.

The "libbsp" directory contains a directory for each CPU family supported by RTEMS.  Beneath each CPU directory is a directory for each BSP for that processor family.

The "libbsp" directory provides all the BSPs provided with this release of the RTEMS executive.  The subdirectories are divided,  as discussed previously, based on specific processor family, then further breaking down into specific target board environments.  The "shmdr" subdirectory provides the implementation of a shared memory driver which supports the multiprocessing portion of the executive.  In addition, two starting point subdirectories are provided for reference.  The "no_cpu" subdirectory provides a template BSP which can be used to develop a specific BSP for an unsupported target board.  The "stubdr" subdirectory provides stubbed out BSPs.  These files may aid in preliminary testing of the RTEMS development environment that has been built for no particular target in mind.

Below each CPU dependent directory is a directory for each target BSP supported in this release.

Each BSP provides the modules which comprise an RTEMS BSP.  The modules are separated into the subdirectories "clock", "console", "include", "shmsupp", "startup", and "timer" as shown in the following figure:

Test Suite Source Directory
---------------------------

The "tests" directory structure for the C implementation is as follows:

This directory provides the entire RTEMS Test Suite which includes the single processor tests, multiprocessor tests, timing tests, library tests, and sample tests.   Additionally, subdirectories for support functions and test related header files are provided.

The "sptests" subdirectory consists of twenty-four tests designed to cover the entire executive code.  The "spfatal" test will verify any code associated with the occurrence of a fatal error.   Also provided is a test which will determine the size of the RTEMS executive.

The multiprocessor test are provided in "mptests". Fourteen tests are provided in this subdirectory which address two node configurations and cover the multiprocessor code found in RTEMS.

Tests that time each directive and a set of critical executive functions are provided in the "tmtests" subdirectory. Within this subdirectory  thirty-one tests are provided along with a subdirectory to contain each targets timing results.

The "samples" directory structure for the C implementation is as follows:

This directory provides sample application tests which aid in the testing a newly built RTEMS environment, a new BSP, or as starting points for the development of an application using the RTEMS executive.  A Hello World test is provided in the subdirectory "hello".  This test is helpful when testing new versions of RTEMS, BSPs, or modifications to any portion of the RTEMS development environment.  The "ticker" subdirectory provides a test for verification of clock chip device drivers of BSPs.  A simple single processor test similar to those in the single processor test suite is provided in "base_sp".  A simple two node multiprocessor test capable of testing an newly developed MPCI layer is provided in "base_mp".  The "cdtest" subdirectory provides a simple C++ application using constructors and destructors.   The final sample test is a public domain floating point and math library toolset test is provided in "paranoia".