Subversion Repositories or1k

@c

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  direct.texi,v 1.8 2002/01/17 21:47:44 joel Exp

@c

@ifinfo

@node Directory Structure, Directory Structure Suites, Introduction, Top

@end ifinfo

@chapter Directory Structure

@ifinfo

@menu

* Directory Structure Suites::

@end menu

@end ifinfo

The RTEMS directory structure is designed to meet

the following requirements:

@itemize @bullet

@item encourage development of modular components.

@item isolate processor and target dependent code, while

allowing as much common source code as possible to be shared

across multiple processors and targets.

@item allow multiple RTEMS users to perform simultaneous

compilation of RTEMS and its support facilities for different

processors and targets.

@end itemize

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.

@ifinfo

@node Directory Structure Suites, C Suites, Directory Structure, Directory Structure

@end ifinfo

@section Suites

@ifinfo

@menu

* C Suites::

* Executive Source Directory::

* Support Library Source Directory::

* Test Suite Source Directory::

@end menu

@end ifinfo

The RTEMS source tree is organized based on the

following four variables:

@itemize @bullet

@item language,

@item target processor,

@item target board, and

@item compiler vendor (Ada only).

@end itemize

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.

@c

@c  Tree 1 - Top Level

@c

@ifset use-ascii

@example

@group

                      RTEMS

                        |

+-----------------------+-----------------------+

|                                               |

c                                              doc

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 15.0em

\hskip 1.25em\hbox to 3.00em{\hss{RTEMS}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 15.0em

\hskip 2.75em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 15.0em

\hskip 0.25em\vrule width2.50em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width2.50em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 15.0em

\hskip 0.25em\vrule width.04em%

\hskip 4.92em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 15.0em

\hskip 0.00em\hbox to 0.50em{\hss{c}\hss}%

\hskip 1.50em\hbox to 1.50em{\hss{   }\hss}%

\hskip 1.00em\hbox to 1.50em{\hss{doc}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@c

@c for now continue to use the ascii

@c

@ifset use-html

@example

@group

                      RTEMS

                        |

+-----------------------+-----------------------+

|                                               |

c                                              doc

@end group

@end example

@html

@end html

@end ifset

Each of the following sections will describe the

contents of the directories in the RTEMS source

tree.

@ifinfo

@node C Suites, Executive Source Directory, Directory Structure Suites, Directory Structure Suites

@end ifinfo

@subsection 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:

@ifset use-texinfo-tables

@table @code

@item Support Libraries (BSPs, C library, CPU support)

$RTEMS_ROOT/c/src/lib

@item Single Processor Tests

$RTEMS_ROOT/c/src/tests/sptests

@item Timing Tests

$RTEMS_ROOT/c/src/tests/tmtests

@item Multiprocessor Tests

$RTEMS_ROOT/c/src/tests/mptests

@item Sample Applications

$RTEMS_ROOT/c/src/tests/samples

@item RTEMS Build Tools

$RTEMS_SRC_BASE/c/build_tools

@item Make Support

$RTEMS_ROOT/c/make

@end table

@end ifset

@ifclear use-texinfo-tables

@html

<CENTER>

  <TABLE COLS=2 WIDTH="80%" BORDER=2>

<TR><TD ALIGN=center>Support Libraries (BSPs, C library, CPU support)</TD>

    <TD ALIGN=center>$RTEMS_ROOT/c/src/lib</TD></TR>

<TR><TD ALIGN=center>Single Processor Tests</TD>

    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/sptests</TD></TR>

<TR><TD ALIGN=center>Timing Tests</TD>

    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/tmtests</TD></TR>

<TR><TD ALIGN=center>Multiprocessor Tests</TD>

    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/mptests</TD></TR>

<TR><TD ALIGN=center>Sample Applications</TD>

    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/samples</TD></TR>

<TR><TD ALIGN=center>RTEMS Build Tools</TD>

    <TD ALIGN=center>$RTEMS_SRC_BASE/c/build_tools</TD></TR>

<TR><TD ALIGN=center>Make Support</TD>

    <TD ALIGN=center>$RTEMS_ROOT/c/make</TD></TR>

  </TABLE>

</CENTER>

@end html

@end ifclear

The top level directory structure for the C implementation of RTEMS

is as follows:

@c

@c  Tree 2 - Top C Level

@c

@ifset use-ascii

@example

@group

                     C

                     |

    +----------+-----------+----------+

    |          |           |          |

build_tools   make        src   update_tools

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 08.0em

\hskip 13.00em\hbox to 0.50em{\hss{C}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 08.0em

\hskip 13.25em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 08.0em

\hskip 1.75em\vrule width11.50em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width11.50em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 08.0em

\hskip 1.75em\vrule width.04em%

\hskip 5.71em\vrule width.04em%

\hskip 5.71em\vrule width.04em%

\hskip 5.71em\vrule width.04em%

\hskip 5.71em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 08.0em

\hskip 0.00em\hbox to 3.50em{\hss{Modules}\hss}%

\hskip 1.00em\hbox to 6.00em{\hss{build\_tools}\hss}%

\hskip 1.75em\hbox to 2.00em{\hss{make}\hss}%

\hskip 4.00em\hbox to 1.50em{\hss{src}\hss}%

\hskip 1.75em\hbox to 6.50em{\hss{update\_tools}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@ifset use-html

@example

@group

                     C

                     |

    +----------+-----------+----------+

    |          |           |          |

build_tools   make        src   update_tools

@end group

@end example

@html

@end html

@end ifset

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:

@c

@c  Tree 3 - Top C src Level

@c

@ifset use-ascii

@example

@group

                     C Source

                         |

 +-----------------------+-----------------------+

 |                       |                       |

exec                    lib                    tests

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 15.0em

\hskip 2.00em\hbox to 4.00em{\hss{C Source}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 15.0em

\hskip 4.00em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 15.0em

\hskip 1.00em\vrule width3.00em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width3.00em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 15.0em

\hskip 1.00em\vrule width.04em%

\hskip 2.96em\vrule width.04em%

\hskip 2.96em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 15.0em

\hskip 0.00em\hbox to 2.00em{\hss{exec}\hss}%

\hskip 1.25em\hbox to 1.50em{\hss{lib}\hss}%

\hskip 1.00em\hbox to 2.50em{\hss{tests}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@ifset use-html

@example

@group

                     C Source

                         |

 +-----------------------+-----------------------+

 |                       |                       |

exec                    lib                    tests

@end group

@end example

@html

@end html

@end ifset

This directory contains all source files that

comprises the RTEMS executive, supported target board support

packages, and the RTEMS Test Suite.

@ifinfo

@node Executive Source Directory, Support Library Source Directory, C Suites, Directory Structure Suites

@end ifinfo

@subsection Executive Source Directory

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

@c

@c  Tree 4 - C Executive Tree

@c

@ifset use-ascii

@example

@group

                    C Executive

                         |

  +-----------+----------+-----------+----------+

  |           |          |           |          |

posix       rtems       sapi       score     wrapup

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 10.0em

\hskip 6.00em\hbox to 5.50em{\hss{C Executive}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 10.0em

\hskip 8.75em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 10.0em

\hskip 1.25em\vrule width7.50em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width7.50em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 10.0em

\hskip 1.25em\vrule width.04em%

\hskip 3.71em\vrule width.04em%

\hskip 3.71em\vrule width.04em%

\hskip 3.71em\vrule width.04em%

\hskip 3.71em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 10.0em

\hskip 0.00em\hbox to 2.50em{\hss{posix}\hss}%

\hskip 1.25em\hbox to 2.50em{\hss{rtems}\hss}%

\hskip 1.50em\hbox to 2.00em{\hss{sapi}\hss}%

\hskip 1.50em\hbox to 2.50em{\hss{score}\hss}%

\hskip 1.00em\hbox to 3.00em{\hss{wrapup}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@ifset use-html

@example

@group

                    C Executive

                         |

  +-----------+----------+-----------+----------+

  |           |          |           |          |

posix       rtems       sapi       score     wrapup

@end group

@end example

@html

@end html

@end ifset

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 @value{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.

@ifinfo

@node Support Library Source Directory, Test Suite Source Directory, Executive Source Directory, Directory Structure Suites

@end ifinfo

@subsection 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.

@c

@c  Tree 6 - Libraries

@c

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.

@c

@c  Tree 7 - C BSP Library

@c

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:

@c

@c  Tree 8 - Each BSP

@c

@ifset use-ascii

@example

@group

                           Each BSP

                               |

  +-----------+----------+-----+-----+----------+----------+

  |           |          |           |          |          |

clock      console    include     shmsupp    startup     timer

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 10.0em

\hskip 10.25em\hbox to 4.50em{\hss{Each BSP}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 10.0em

\hskip 12.50em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 10.0em

\hskip 1.25em\vrule width11.25em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width11.25em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 10.0em

\hskip 1.25em\vrule width.04em%

\hskip 4.46em\vrule width.04em%

\hskip 4.46em\vrule width.04em%

\hskip 4.46em\vrule width.04em%

\hskip 4.46em\vrule width.04em%

\hskip 4.46em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 10.0em

\hskip 0.00em\hbox to 2.50em{\hss{clock}\hss}%

\hskip 1.50em\hbox to 3.50em{\hss{console}\hss}%

\hskip 1.00em\hbox to 3.50em{\hss{include}\hss}%

\hskip 1.00em\hbox to 3.50em{\hss{shmsupp}\hss}%

\hskip 1.00em\hbox to 3.50em{\hss{startup}\hss}%

\hskip 1.50em\hbox to 2.50em{\hss{timer}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@ifset use-html

@example

@group

                           Each BSP

                               |

  +-----------+----------+-----+-----+----------+----------+

  |           |          |           |          |          |

clock      console    include       ...      startup     timer

@end group

@end example

@html

@end html

@end ifset

@ifinfo

@node Test Suite Source Directory, Sample Applications, Support Library Source Directory, Directory Structure Suites

@end ifinfo

@subsection Test Suite Source Directory

The "tests" directory structure for the C

implementation is as follows:

@c

@c  Tree 9 - C Tests

@c

@ifset use-ascii

@example

@group

                                C Tests

                                   |

   +----------+---------+----------+---------+---------+---------+

   |          |         |          |         |         |         |

libtests   sptests   support    tmtests   mptests   psxtest   samples

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 05.0em

\hskip 14.50em\hbox to 3.50em{\hss{C Tests}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 05.0em

\hskip 16.25em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 05.0em

\hskip 2.00em\vrule width14.25em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width14.25em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 05.0em

\hskip 2.00em\vrule width.04em%

\hskip 4.71em\vrule width.04em%

\hskip 4.71em\vrule width.04em%

\hskip 4.71em\vrule width.04em%

\hskip 4.71em\vrule width.04em%

\hskip 4.71em\vrule width.04em%

\hskip 4.71em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 05.0em

\hskip 0.00em\hbox to 4.00em{\hss{libtests}\hss}%

\hskip 1.00em\hbox to 3.50em{\hss{sptests}\hss}%

\hskip 1.25em\hbox to 3.50em{\hss{support}\hss}%

\hskip 1.25em\hbox to 3.50em{\hss{tmtests}\hss}%

\hskip 1.25em\hbox to 3.50em{\hss{mptests}\hss}%

\hskip 1.75em\hbox to 2.50em{\hss{tools}\hss}%

\hskip 1.75em\hbox to 3.50em{\hss{samples}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@ifset use-html

@example

@group

                                C Tests

                                   |

   +----------+---------+----------+---------+---------+---------+

   |          |         |          |         |         |         |

libtests   sptests   support    tmtests   mptests    tools    samples

@end group

@end example

@html

@end html

@end ifset

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:

@c

@c  Tree 10 - C Samples

@c

@ifset use-ascii

@example

@group

                            C Samples

                                |

   +-----------+----------+-----+-----+----------+----------+

   |           |          |           |          |          |

base_mp     base_sp    cdtest       hello     paranoia    ticker

@end group

@end example

@end ifset

@ifset use-tex

@sp 1

@tex

{\parskip=0pt\offinterlineskip%

\hskip 05.0em

\hskip 12.25em\hbox to 4.50em{\hss{C Samples}\hss}%

\vrule width0em height1.972ex depth0.812ex\par\penalty10000

\hskip 05.0em

\hskip 14.50em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 05.0em

\hskip 2.00em\vrule width12.50em height-0.407ex depth0.500ex%

\vrule width.04em\vrule width12.50em height-0.407ex depth0.500ex%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 05.0em

\hskip 2.00em\vrule width.04em%

\hskip 4.96em\vrule width.04em%

\hskip 4.96em\vrule width.04em%

\hskip 4.96em\vrule width.04em%

\hskip 4.96em\vrule width.04em%

\hskip 4.96em\vrule width.04em%

\vrule width0em height1.500ex depth0.500ex\par\penalty10000

\hskip 05.0em

\hskip 0.00em\hbox to 4.00em{\hss{base\_mp}\hss}%

\hskip 1.00em\hbox to 4.00em{\hss{base\_sp}\hss}%

\hskip 1.50em\hbox to 3.00em{\hss{cdtest}\hss}%

\hskip 2.25em\hbox to 2.50em{\hss{hello}\hss}%

\hskip 1.75em\hbox to 4.00em{\hss{paranoia}\hss}%

\hskip 1.50em\hbox to 3.00em{\hss{ticker}\hss}%

\vrule width0em height1.972ex depth0.812ex\par}

@end tex

@end ifset

@ifset use-html

@example

@group

                            C Samples

                                |

   +-----------+----------+-----+-----+----------+----------+

   |           |          |           |          |          |

base_mp     base_sp    cdtest       hello     paranoia    ticker

@end group

@end example

@html

@end html

@end ifset

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".