diff options
Diffstat (limited to 'doc/develenv/direct.texi')
| -rw-r--r-- | doc/develenv/direct.texi | 730 |
1 files changed, 0 insertions, 730 deletions
diff --git a/doc/develenv/direct.texi b/doc/develenv/direct.texi deleted file mode 100644 index 13f366509f..0000000000 --- a/doc/develenv/direct.texi +++ /dev/null @@ -1,730 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@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". |