RTEMS 4.9.6 On-Line Library

Directory Structure

RTEMS Development Environment Guide

Chapter 2: Directory Structure

Directory Structure c/ Directory

Directory Structure CPU Kit Directory

Directory Structure testsuites/ Test Suites

Directory Structure Documentation Directory

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 target boards.
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 board dependent source files isolated from generic files. When RTEMS is configured and built, object directories and an install point will be automatically created based upon the target CPU family and BSP selected.

The placement of object files based upon the selected BSP name ensures that object files are not mixed across CPUs or targets. This in combination with the makefiles 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.

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

functionality,
target processor family,
target processor model,
peripherals, and
target board.

Each of the following sections will describe the contents of the directories in the RTEMS source tree. The top of the tree will be referenced as ${RTEMS_ROOT} in this discussion.

                      rtems-VERSION
                           |
   +--------+----+----+----+--+-----+---+-------+--------+
   |        |    |    |       |     |   |       |        |
aclocal automake c contrib  cpukit doc make testsuites tools

${RTEMS_ROOT}/aclocal/: This directory contains the custom M4 macros which are available to the various GNU autoconf configure.ac scripts throughout the RTEMS source tree. GNU autoconf interprets configure.ac files to produce the configure files used to tailor RTEMS build for a particular host and target environment. The contents of this directory will not be discussed further in this document.
${RTEMS_ROOT}/automake/: This directory contains the custom GNU automake fragments which are used to support the various Makefile.am files throughout the RTEMS source tree. The contents of this directory will not be discussed further in this document.
${RTEMS_ROOT}/c/: This directory is the root of the portions of the RTEMS source tree which must be built tailored for a particular CPU model or BSP. The contents of this directory will be discussed in the Directory Structure c/ Directory section.
${RTEMS_ROOT}/contrib/: This directory contains contributed support software. Currently this directory contains the RPM specifications for cross-compilers hosted on GNU/Linux that target various operating systems including MinGW, Cygwin, FreeBSD, and Solaris. The cross-compilers produced using these specifications are then used in a Canadian cross build procedure to produce the various RTEMS toolsets on a GNU/Linux host.
This directory also contains RPM specifications for the prebuilt cross-compilation toolsets provided by the RTEMS project. There are separate subdirectories for each of the components in the RTEMS Cross Compilation Environment unde the contrib/crossrpms/ directory. This directory is configured, built, and installed separately from the RTEMS executive and tests. This directory will not be discussed further in this document.
${RTEMS_ROOT}/cpukit/: This directory is the root for all of the "multilib'able" portions of RTEMS. This is a GNU way of saying the contents of this directory can be compiled like the C Library (libc.a) and the functionality is neither CPU model nor BSP specific. The source code for most RTEMS services reside under this directory. The contents of this directory will be discussed in the Directory Structure CPU Kit Directory section.
${RTEMS_ROOT}/doc/: This directory is the root for all RTEMS documentation. The source for RTEMS is written in GNU TeXinfo and used to produce HTML, PDF, and "info" files. The RTEMS documentation is configured, built, and installed separately from the RTEMS executive and tests. The contents of this directory will be discussed in the Directory Structure Documentation Directory section.
${RTEMS_ROOT}/make/: This directory contains files which support the RTEMS Makefile's. From a user's perspective, the most important parts are found in the custom/ subdirectory. Each ".cfg" file in this directory is associated with a specific BSP and describes the CPU model, compiler flags, and procedure to produce an executable for the target board. These files are described in detail in the RTEMS BSP and Device Driver Development Guide and will not be discussed further in this document.
${RTEMS_ROOT}/testsuites/: This directory contains the test suites for the various RTEMS APIs and support libraries. The contents of this directory are discussed in the Directory Structure testsuites/ Test Suites section.
${RTEMS_ROOT}/tools/: This directory contains RTEMS specific support utilities which execute on the development host. These utilities are divided into subdirectories based upon whether they are used in the process of building RTEMS and applications, are CPU specific, or are used to assist in updating the RTEMS source tree and applications. The support utilities used in the process of building RTEMS are described in RTEMS Specific Utilities. These are the only components of this subtree that will be discussed in this document.

RTEMS Development Environment Guide