source: rtems/doc/develenv/direct.t @ aa41429

4.104.114.84.95
Last change on this file since aa41429 was aa41429, checked in by Joel Sherrill <joel.sherrill@…>, on Feb 18, 2003 at 4:16:12 PM

2003-02-18 Joel Sherrill <joel@…>

  • Makefile.am, develenv.texi: Relect generating .texi from .t's.
  • direct.t, sample.t, utils.t: New files.
  • direct.texi, sample.texi, utils.texi: Removed. Now generated from corresponding .t files which are in the process of being updated. This commit is a anspshot of the update effort.
  • Property mode set to 100644
File size: 20.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Directory Structure
10
11The RTEMS directory structure is designed to meet
12the following requirements:
13
14@itemize @bullet
15@item encourage development of modular components.
16
17@item isolate processor and target dependent code, while
18allowing as much common source code as possible to be shared
19across multiple processors and target boards.
20
21@item allow multiple RTEMS users to perform simultaneous
22compilation of RTEMS and its support facilities for different
23processors and targets.
24@end itemize
25
26The resulting directory structure has processor and
27board dependent source files isolated from generic files.  When
28RTEMS is configured and built, object directories and
29an install point will be automatically created based upon
30the target CPU family and BSP selected. 
31
32The placement of object files based upon the selected BSP name
33ensures that object files are not mixed across CPUs or targets.
34This in combination with the makefiles allows the specific
35compilation options to be tailored for a particular target
36board.  For example, the efficiency of the memory subsystem for
37a particular target board may be sensitive to the alignment of
38data structures, while on another target board with the same
39processor memory may be very limited.  For the first target, the
40options could specify very strict alignment requirements, while
41on the second the data structures could be "packed" to conserve
42memory.  It is impossible to achieve this degree of flexibility
43without providing source code.
44
45@c
46@c  Directory Organization
47@c
48@section Directory Organization
49
50The RTEMS source tree is organized based on the
51following variables:
52
53@itemize @bullet
54
55@item functionality,
56@item target processor family,
57@item target processor model,
58@item peripherals, and
59@item target board.
60
61@end itemize
62
63Each of the following sections will describe the
64contents of the directories in the RTEMS source
65tree.  The top of the tree will be referenced
66as @code{$@{RTEMS_ROOT@}} in this discussion.
67
68@c
69@c  Top Level Tree
70@c
71
72@c @ifset use-ascii
73@example
74@group
75                      rtems-VERSION
76                           |
77   +--------+----+----+----+--+-----+---+------+-----+
78   |        |    |    |       |     |   |      |     |
79aclocal automake c contrib  cpukit doc make scripts tools
80@end group
81@end example
82@c @end ifset
83
84@ifset use-tex
85@end ifset
86
87@ifset use-html
88@html
89@end html
90@end ifset
91
92@table @code
93@item $@{RTEMS_ROOT@}/aclocal/
94This directory contains the custom M4 macros which are available to
95the various GNU autoconf @code{configure.ac} scripts throughout
96the RTEMS source tree.  GNU autoconf interprets @code{configure.ac}
97files to produce the @code{configure} files used to tailor
98RTEMS build for a particular host and target environment.  The
99contents of this directory will not be discussed further in this
100document.
101
102@item $@{RTEMS_ROOT@}/automake/
103This directory contains the custom GNU automake fragments
104which are used to support the various @code{Makefile.am}
105files throughout the RTEMS source tree.  The
106contents of this directory will not be discussed
107further in this document.
108
109@item $@{RTEMS_ROOT@}/c/
110This directory is the root of the portions of the RTEMS source
111tree which must be built tailored for a particular CPU model
112or BSP.  The contents of this directory will be discussed
113in the @ref{Directory Structure c/ Directory} section.
114
115@item $@{RTEMS_ROOT@}/contrib/
116This directory contains contributed support software.  Currently
117this directory contains the RPM specifications for cross-compilers
118hosted on GNU/Linux that target Cygwin and Solaris.  The
119cross-compilers produced using these specifications are then
120used in a Canadian cross build procedure to produce the Cygwin
121and Solaris hosted RTEMS toolsets on a GNU/Linux host.  This
122directory will not be discussed further in this document.
123
124@item $@{RTEMS_ROOT@}/cpukit/
125This directory is the root for all of the "multilib'able"
126portions of RTEMS.  This is a GNU way of saying the the
127contents of this directory can be compiled like the
128C Library (@code{libc.a}) and the functionality is
129neither CPU model nor BSP specific.  The source code
130for most RTEMS services reside under this directory.
131The contents of this directory will be discussed
132in the @ref{Directory Structure CPUKit Directory} section.
133
134@item $@{RTEMS_ROOT@}/doc/
135This directory is the root for all RTEMS documentation.
136The source for RTEMS is written in GNU TeXinfo and
137used to produce HTML, PDF, and "info" files.
138The RTEMS documentation is configured, built,
139and installed separately from the RTEMS executive and tests.
140The contents of this directory will be discussed
141in the @ref{Directory Structure Documentation Directory} section.
142
143@item $@{RTEMS_ROOT@}/make/
144This directory contains files which support the
145RTEMS Makefile's.  From a user's perspective, the
146most important parts are found in the @code{custom/}
147subdirectory.  Each ".cfg" file in this directory
148is associated with a specific BSP and describes
149the CPU model, compiler flags, and procedure to
150a produce an executable for the target board.
151These files are described in detail in the
152@b{RTEMS BSP and Device Driver Development Guide}
153and will not be discussed further in this document.
154
155@item $@{RTEMS_ROOT@}/scripts/
156This directory contains the RPM specifications for the
157prebuilt cross-compilation toolsets provided by the
158RTEMS project.  There are separate subdirectories
159for each of the components in the RTEMS Cross Compilation
160Environment including @code{binutils/}, @code{gcc3newlib/},
161and @code{gdb/}.  This directory is configured, built,
162and installed separately from the RTEMS executive
163and tests.  This directory will not be discussed further
164in this document.
165
166@item $@{RTEMS_ROOT@}/tools/
167This directory contains RTEMS specific support utilities which
168execute on the development host.  These utilities are divided
169into subdirectories based upon whether they are used in the process
170of building RTEMS and applications, are CPU specific, or are
171used to assist in updating the RTEMS source tree and applications.
172The support utilities used in the process of building RTEMS are
173described in @ref{RTEMS Specific Utilities}.  These are the
174only components of this subtree that will be discussed in this
175document.
176
177@end table
178
179
180
181@c
182@c  c/ Directions
183@c
184@subsection c/ Directory
185
186The @code{$@{RTEMS_ROOT@}/c/} directory was formerly
187the root directory of all RTEMS source code.  At this time, it contains
188the root directory for only those RTEMS components
189which must be compiled or linked in a way that is specific to a
190particular CPU model or board.  This directory contains the
191following subdirectories:
192
193@table @code
194@item $@{RTEMS_ROOT@}/c/src/
195This directory is logically the root for the RTEMS components
196which are CPU model or board dependent.  Thus this directory
197is the root for the BSPs and the various Test Suites as well
198as CPU model and BSP dependent libraries.  The contents of
199this directory are discussed in the
200@ref{Directory Structure c/src/ Directory} section.
201
202@item $@{RTEMS_ROOT@}/c/make/
203This directory is used to generate the file @code{target.cfg}
204which is installed as part of the Application Makefiles.  This
205file contains settings for various Makefile variables to
206tailor them to the particular CPU model and BSP configured.
207
208@end table
209
210@c
211@c c/src/ Directory
212@c
213@subsubsection c/src/ Directory
214
215As mentioned previously, this directory is logically
216the root for the RTEMS components
217which are CPU model or board dependent.  The
218following is a list of the subdirectories in this
219directorie and a description of each.
220
221@table @code
222@item $@{RTEMS_ROOT@}/c/src/ada-tests/
223This directory contains the test suite for the Ada
224language bindings to the Classic API.
225
226@item $@{RTEMS_ROOT@}/c/src/lib/
227
228@item $@{RTEMS_ROOT@}/c/src/libchip/
229This directory contains device drivers for various
230peripheral chips which are designed to be CPU and
231board dependent.  This directory contains a variety
232of drivers for serial devices, network interface
233controllers, and real-time clocks.
234
235@item $@{RTEMS_ROOT@}/c/src/libmisc/
236This directory contains support facilities which
237are RTEMS specific but otherwise unclassified.  In
238general, they do not adhere to a standard API. 
239Among the support facilities in this directory are
240a @code{/dev/null} device driver, the Stack
241Overflow Checker, a mini-shell, the CPU and
242rate monotonic period usage monitoring libraries,
243and a utility to "dump a buffer" in a nicely
244formatted way similar to many ROM monitors.
245
246@item $@{RTEMS_ROOT@}/c/src/libnetworking/
247This directory contains the networking components which
248might be tailored based upon the particular BSP.  This
249includes the RTEMS telnetd, httpd, and ftpd servers.
250
251@item $@{RTEMS_ROOT@}/c/src/librdbg/
252This directory contains the Ethernet-based remote debugging
253stub.  This software must be built to be intimately aware
254of a particular CPU model.
255
256@item $@{RTEMS_ROOT@}/c/src/librtems++/
257
258@item $@{RTEMS_ROOT@}/c/src/make/
259
260@item $@{RTEMS_ROOT@}/c/src/optman/
261
262@item $@{RTEMS_ROOT@}/c/src/tests/
263This directory contains the test suites for the
264various RTEMS APIs and support libraries.  This
265contents of this directory are discussed in the
266@ref{Directory Structure Test Suites} section.
267
268@item $@{RTEMS_ROOT@}/c/src/wrapup/
269
270@end table
271
272@c
273@c  Test Suites
274@c
275@lowersections
276@subsubsection Test Suites
277
278The following table lists the test suites currently included with the
279RTEMS and the directory in which they may be located:
280
281@table @code
282
283@item @{RTEMS_ROOT@}c/src/tests/itrontests
284ITRON API Tests
285
286@item @{RTEMS_ROOT@}c/src/tests/libtests
287Support Library Tests
288
289@item @{RTEMS_ROOT@}c/src/tests/mptests
290Classic API Multiprocessor Tests
291
292@item @{RTEMS_ROOT@}c/src/tests/psxtests
293POSIX API Tests
294
295@item @{RTEMS_ROOT@}c/src/tests/samples
296Sample Applications
297
298@item @{RTEMS_ROOT@}c/src/tests/sptests
299Classic API Single Processor Tests
300
301@item @{RTEMS_ROOT@}c/src/tests/support
302Test Support Software
303
304@item @{RTEMS_ROOT@}c/src/tests/tmitrontests
305ITRON API Timing Tests
306
307@item @{RTEMS_ROOT@}c/src/tests/tmtests
308Classic API Timing Tests
309
310@item @{RTEMS_ROOT@}c/src/tests/tools
311XXX
312
313@end table
314
315@raisesections
316
317
318@c
319@c  CPUKit Directory
320@c
321@subsection CPUKit Directory
322
323The @code{cpukit/} directory structure is as follows:
324
325@c
326@c  CPUKit Tree
327@c
328
329@ifset use-ascii
330@example
331@group
332                       CPUKit
333                         |
334  +-----------+----------+-----------+----------+
335  |           |          |           |          |
336posix       rtems       sapi       score     wrapup
337@end group
338@end example
339@end ifset
340
341This directory contains a set of subdirectories which
342contains the source files comprising the executive portion of
343the RTEMS development environment as well as portable support
344libraries such as support for the C Library and filesystems.
345The API specific and "SuperCore" (e.g. @code{score/} directory)
346source code files are separated into
347distinct directory trees.  The @code{rtems/}, @code{posix/}, and
348@code{itron/} subdirectories contain the C language source files for each
349module comprising the respective API.  Also included in this
350directory are the subdirectories @code{sapi/} and @code{score/} which are
351the SuperCore modules.  Within the @code{score/} directory the CPU
352dependent modules are found.
353
354The @code{score/cpu/} subdirectory contains a subdirectory for each
355target CPU supported by the @value{RELEASE} release of the RTEMS
356executive.  Each processor directory contains the CPU dependent
357code necessary to host RTEMS.  The "no_cpu" directory provides a
358starting point for developing a new port to an unsupported
359processor.  The files contained within the "no_cpu" directory
360may also be used as a reference for the other ports to specific
361processors.
362
363
364@c
365@c 
366@c
367@subsection Documentation Directory
368
369XXX
370
371@c
372@c 
373@c
374@subsection Support Library Source Directory
375
376The "lib" directory contains the support libraries and BSPS. 
377Board support packages (BSPs), processor environment start up code,
378C library support, the FreeBSD TCP/IP stack, common BSP header files,
379and miscellaneous support functions are provided in the subdirectories.
380These are combined with the RTEMS executive object to form the single
381RTEMS library which installed. 
382
383@c
384@c  Tree 6 - Libraries
385@c
386
387
388The "libbsp" directory contains a directory for each CPU family supported
389by RTEMS.  Beneath each CPU directory is a directory for each BSP for that
390processor family.
391
392@c
393@c  Tree 7 - C BSP Library
394@c
395
396The "libbsp" directory provides all the BSPs provided with this
397release of the RTEMS executive.  The subdirectories are
398divided,  as discussed previously, based on specific processor
399family, then further breaking down into specific target board
400environments.  The "shmdr" subdirectory provides the
401implementation of a shared memory driver which supports the
402multiprocessing portion of the executive.  In addition, two
403starting point subdirectories are provided for reference.  The
404"no_cpu" subdirectory provides a template BSP which can be used
405to develop a specific BSP for an unsupported target board.  The
406"stubdr" subdirectory provides stubbed out BSPs.  These files
407may aid in preliminary testing of the RTEMS development
408environment that has been built for no particular target in mind.
409
410Below each CPU dependent directory is a directory for each target BSP
411supported in this release.
412
413Each BSP provides the modules which comprise an RTEMS BSP.  The
414modules are separated into the subdirectories "clock", "console",
415"include", "shmsupp", "startup", and "timer" as shown in the following
416figure:
417
418@c
419@c  Tree 8 - Each BSP
420@c
421
422@ifset use-ascii
423@example
424@group
425                           Each BSP
426                               |
427  +-----------+----------+-----+-----+----------+----------+
428  |           |          |           |          |          |
429clock      console    include     shmsupp    startup     timer
430@end group
431@end example
432@end ifset
433
434@ifset use-tex
435@sp 1
436
437@tex
438{\parskip=0pt\offinterlineskip%
439\hskip 10.0em
440\hskip 10.25em\hbox to 4.50em{\hss{Each BSP}\hss}%
441\vrule width0em height1.972ex depth0.812ex\par\penalty10000
442\hskip 10.0em
443\hskip 12.50em\vrule width.04em%
444\vrule width0em height1.500ex depth0.500ex\par\penalty10000
445\hskip 10.0em
446\hskip 1.25em\vrule width11.25em height-0.407ex depth0.500ex%
447\vrule width.04em\vrule width11.25em height-0.407ex depth0.500ex%
448\vrule width0em height1.500ex depth0.500ex\par\penalty10000
449\hskip 10.0em
450\hskip 1.25em\vrule width.04em%
451\hskip 4.46em\vrule width.04em%
452\hskip 4.46em\vrule width.04em%
453\hskip 4.46em\vrule width.04em%
454\hskip 4.46em\vrule width.04em%
455\hskip 4.46em\vrule width.04em%
456\vrule width0em height1.500ex depth0.500ex\par\penalty10000
457\hskip 10.0em
458\hskip 0.00em\hbox to 2.50em{\hss{clock}\hss}%
459\hskip 1.50em\hbox to 3.50em{\hss{console}\hss}%
460\hskip 1.00em\hbox to 3.50em{\hss{include}\hss}%
461\hskip 1.00em\hbox to 3.50em{\hss{shmsupp}\hss}%
462\hskip 1.00em\hbox to 3.50em{\hss{startup}\hss}%
463\hskip 1.50em\hbox to 2.50em{\hss{timer}\hss}%
464\vrule width0em height1.972ex depth0.812ex\par}
465@end tex
466@end ifset
467
468@ifset use-html
469@example
470@group
471                           Each BSP
472                               |
473  +-----------+----------+-----+-----+----------+----------+
474  |           |          |           |          |          |
475clock      console    include       ...      startup     timer
476@end group
477@end example
478@html
479@end html
480@end ifset
481
482@c
483@c 
484@c
485@subsection Test Suite Source Directory
486
487The "tests" directory structure for the C
488implementation is as follows:
489
490@c
491@c  Tree 9 - C Tests
492@c
493
494@ifset use-ascii
495@example
496@group
497                                C Tests
498                                   |
499   +----------+---------+----------+---------+---------+---------+
500   |          |         |          |         |         |         |
501libtests   sptests   support    tmtests   mptests   psxtest   samples
502@end group
503@end example
504@end ifset
505
506@ifset use-tex
507@sp 1
508
509@tex
510{\parskip=0pt\offinterlineskip%
511\hskip 05.0em
512\hskip 14.50em\hbox to 3.50em{\hss{C Tests}\hss}%
513\vrule width0em height1.972ex depth0.812ex\par\penalty10000
514\hskip 05.0em
515\hskip 16.25em\vrule width.04em%
516\vrule width0em height1.500ex depth0.500ex\par\penalty10000
517\hskip 05.0em
518\hskip 2.00em\vrule width14.25em height-0.407ex depth0.500ex%
519\vrule width.04em\vrule width14.25em height-0.407ex depth0.500ex%
520\vrule width0em height1.500ex depth0.500ex\par\penalty10000
521\hskip 05.0em
522\hskip 2.00em\vrule width.04em%
523\hskip 4.71em\vrule width.04em%
524\hskip 4.71em\vrule width.04em%
525\hskip 4.71em\vrule width.04em%
526\hskip 4.71em\vrule width.04em%
527\hskip 4.71em\vrule width.04em%
528\hskip 4.71em\vrule width.04em%
529\vrule width0em height1.500ex depth0.500ex\par\penalty10000
530\hskip 05.0em
531\hskip 0.00em\hbox to 4.00em{\hss{libtests}\hss}%
532\hskip 1.00em\hbox to 3.50em{\hss{sptests}\hss}%
533\hskip 1.25em\hbox to 3.50em{\hss{support}\hss}%
534\hskip 1.25em\hbox to 3.50em{\hss{tmtests}\hss}%
535\hskip 1.25em\hbox to 3.50em{\hss{mptests}\hss}%
536\hskip 1.75em\hbox to 2.50em{\hss{tools}\hss}%
537\hskip 1.75em\hbox to 3.50em{\hss{samples}\hss}%
538\vrule width0em height1.972ex depth0.812ex\par}
539@end tex
540@end ifset
541
542@ifset use-html
543@example
544@group
545                                C Tests
546                                   |
547   +----------+---------+----------+---------+---------+---------+
548   |          |         |          |         |         |         |
549libtests   sptests   support    tmtests   mptests    tools    samples
550@end group
551@end example
552@html
553@end html
554@end ifset
555
556This directory provides the entire RTEMS Test Suite
557which includes the single processor tests, multiprocessor tests,
558timing tests, library tests, and sample tests.   Additionally,
559subdirectories for support functions and test related header
560files are provided.
561
562The "sptests" subdirectory consists of twenty-four
563tests designed to cover the entire executive code.  The
564"spfatal" test will verify any code associated with the
565occurrence of a fatal error.   Also provided is a test which
566will determine the size of the RTEMS executive.
567
568The multiprocessor test are provided in "mptests".
569Fourteen tests are provided in this subdirectory which address
570two node configurations and cover the multiprocessor code found
571in RTEMS.
572
573Tests that time each directive and a set of critical
574executive functions are provided in the "tmtests" subdirectory.
575Within this subdirectory  thirty-one tests are provided along
576with a subdirectory to contain each targets timing results.
577
578The "samples" directory structure for the C
579implementation is as follows:
580
581@c
582@c  Tree 10 - C Samples
583@c
584
585@ifset use-ascii
586@example
587@group
588                            C Samples
589                                |
590   +-----------+----------+-----+-----+----------+----------+
591   |           |          |           |          |          |
592base_mp     base_sp    cdtest       hello     paranoia    ticker
593@end group
594@end example
595@end ifset
596
597@ifset use-tex
598@sp 1
599
600@tex
601{\parskip=0pt\offinterlineskip%
602\hskip 05.0em
603\hskip 12.25em\hbox to 4.50em{\hss{C Samples}\hss}%
604\vrule width0em height1.972ex depth0.812ex\par\penalty10000
605\hskip 05.0em
606\hskip 14.50em\vrule width.04em%
607\vrule width0em height1.500ex depth0.500ex\par\penalty10000
608\hskip 05.0em
609\hskip 2.00em\vrule width12.50em height-0.407ex depth0.500ex%
610\vrule width.04em\vrule width12.50em height-0.407ex depth0.500ex%
611\vrule width0em height1.500ex depth0.500ex\par\penalty10000
612\hskip 05.0em
613\hskip 2.00em\vrule width.04em%
614\hskip 4.96em\vrule width.04em%
615\hskip 4.96em\vrule width.04em%
616\hskip 4.96em\vrule width.04em%
617\hskip 4.96em\vrule width.04em%
618\hskip 4.96em\vrule width.04em%
619\vrule width0em height1.500ex depth0.500ex\par\penalty10000
620\hskip 05.0em
621\hskip 0.00em\hbox to 4.00em{\hss{base\_mp}\hss}%
622\hskip 1.00em\hbox to 4.00em{\hss{base\_sp}\hss}%
623\hskip 1.50em\hbox to 3.00em{\hss{cdtest}\hss}%
624\hskip 2.25em\hbox to 2.50em{\hss{hello}\hss}%
625\hskip 1.75em\hbox to 4.00em{\hss{paranoia}\hss}%
626\hskip 1.50em\hbox to 3.00em{\hss{ticker}\hss}%
627\vrule width0em height1.972ex depth0.812ex\par}
628@end tex
629@end ifset
630
631@ifset use-html
632@example
633@group
634                            C Samples
635                                |
636   +-----------+----------+-----+-----+----------+----------+
637   |           |          |           |          |          |
638base_mp     base_sp    cdtest       hello     paranoia    ticker
639@end group
640@end example
641@html
642@end html
643@end ifset
644
645This directory provides sample application tests
646which aid in the testing a newly built RTEMS environment, a new
647BSP, or as starting points for the development of an application
648using the RTEMS executive.  A Hello World test is provided in
649the subdirectory "hello".  This test is helpful when testing new
650versions of RTEMS, BSPs, or modifications to any portion of the
651RTEMS development environment.  The "ticker" subdirectory
652provides a test for verification of clock chip device drivers of
653BSPs.  A simple single processor test similar to those in the
654single processor test suite is provided in "base_sp".  A simple
655two node multiprocessor test capable of testing an newly
656developed MPCI layer is provided in "base_mp".  The "cdtest"
657subdirectory provides a simple C++ application using
658constructors and destructors.   The final sample test is a
659public domain floating point and math library toolset test is
660provided in "paranoia".
Note: See TracBrowser for help on using the repository browser.