diff options
Diffstat (limited to 'doc/develenv/direct.texi')
| -rw-r--r-- | doc/develenv/direct.texi | 712 |
1 files changed, 712 insertions, 0 deletions
diff --git a/doc/develenv/direct.texi b/doc/develenv/direct.texi new file mode 100644 index 0000000000..cea5959241 --- /dev/null +++ b/doc/develenv/direct.texi @@ -0,0 +1,712 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@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 + C Executive + | + +-----------+----------+-----------+----------+ + | | | | | +posix rtems sapi score wrapup +@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{RTEMS-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 KA9Q 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 + +Th "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 + Each BSP + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +clock console include shmsupp startup timer +@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 tools 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 + C Tests + | + +----------+---------+----------+---------+---------+---------+ + | | | | | | | +libtests sptests support tmtests mptests tools samples +@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 + C Samples + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +base_mp base_sp cdtest hello paranoia ticker +@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". |