source: rtems-docs/develenv/directory.rst @ c0d6eff6

4.115am
Last change on this file since c0d6eff6 was c0d6eff6, checked in by Amar Takhar <verm@…>, on 01/16/16 at 19:53:40

Split document.

  • Property mode set to 100644
File size: 24.6 KB
Line 
1Directory Structure
2###################
3
4The RTEMS directory structure is designed to meet
5the following requirements:
6
7- encourage development of modular components.
8
9- isolate processor and target dependent code, while
10  allowing as much common source code as possible to be shared
11  across multiple processors and target boards.
12
13- allow multiple RTEMS users to perform simultaneous
14  compilation of RTEMS and its support facilities for different
15  processors and targets.
16
17The resulting directory structure has processor and
18board dependent source files isolated from generic files.  When
19RTEMS is configured and built, object directories and
20an install point will be automatically created based upon
21the target CPU family and BSP selected.
22
23The placement of object files based upon the selected BSP name
24ensures that object files are not mixed across CPUs or targets.
25This in combination with the makefiles allows the specific
26compilation options to be tailored for a particular target
27board.  For example, the efficiency of the memory subsystem for
28a particular target board may be sensitive to the alignment of
29data structures, while on another target board with the same
30processor memory may be very limited.  For the first target, the
31options could specify very strict alignment requirements, while
32on the second the data structures could be *packed* to conserve
33memory.  It is impossible to achieve this degree of flexibility
34without providing source code.
35
36The RTEMS source tree is organized based on the following variables:
37
38- functionality,
39
40- target processor family,
41
42- target processor model,
43
44- peripherals, and
45
46- target board.
47
48Each of the following sections will describe the
49contents of the directories in the RTEMS source
50tree.  The top of the tree will be referenced
51as ``${RTEMS_ROOT}`` in this discussion.
52
53.. COMMENT: Top Level Tree
54
55.. COMMENT: @ifset use-ascii
56.. code:: c
57
58    rtems-VERSION
59    |
60    +--------+----+----+----+--+-----+---+-------+--------+
61    |        |    |    |       |     |   |       |        |
62    aclocal automake c contrib  cpukit doc make testsuites tools
63
64.. COMMENT: @end ifset
65
66``${RTEMS_ROOT}/aclocal/``
67    This directory contains the custom M4 macros which are available to
68    the various GNU autoconf ``configure.ac`` scripts throughout
69    the RTEMS source tree.  GNU autoconf interprets ``configure.ac``
70    files to produce the ``configure`` files used to tailor
71    RTEMS build for a particular host and target environment.  The
72    contents of this directory will not be discussed further in this
73    document.
74
75``${RTEMS_ROOT}/automake/``
76    This directory contains the custom GNU automake fragments
77    which are used to support the various ``Makefile.am``
78    files throughout the RTEMS source tree.  The
79    contents of this directory will not be discussed
80    further in this document.
81
82``${RTEMS_ROOT}/c/``
83    This directory is the root of the portions of the RTEMS source
84    tree which must be built tailored for a particular CPU model
85    or BSP.  The contents of this directory will be discussed
86    in the `c/ Directory`_ section.
87
88``${RTEMS_ROOT}/contrib/``
89    This directory contains contributed support software.  Currently
90    this directory contains the RPM specifications for cross-compilers
91    hosted on GNU/Linux that target various operating systems
92    including MinGW, Cygwin, FreeBSD, and Solaris.  The
93    cross-compilers produced using these specifications are then
94    used in a Canadian cross build procedure to produce the various
95    RTEMS toolsets on a GNU/Linux host.
96    This directory also contains RPM specifications for the
97    prebuilt cross-compilation toolsets provided by the
98    RTEMS project.  There are separate subdirectories
99    for each of the components in the RTEMS Cross Compilation
100    Environment unde the  ``contrib/crossrpms/`` directory.
101    This directory is configured, built, and installed separately
102    from the RTEMS executive and tests.  This directory will not
103    be discussed further in this document.
104
105``${RTEMS_ROOT}/cpukit/``
106    This directory is the root for all of the "multilib’able"
107    portions of RTEMS.  This is a GNU way of saying the
108    contents of this directory can be compiled like the
109    C Library (``libc.a``) and the functionality is
110    neither CPU model nor BSP specific.  The source code
111    for most RTEMS services reside under this directory.
112    The contents of this directory will be discussed
113    in the `CPU Kit Directory`_ section.
114
115``${RTEMS_ROOT}/doc/``
116    This directory is the root for all RTEMS documentation.
117    The source for RTEMS is written in GNU TeXinfo and
118    used to produce HTML, PDF, and "info" files.
119    The RTEMS documentation is configured, built,
120    and installed separately from the RTEMS executive and tests.
121    The contents of this directory will be discussed
122    in the `Documentation Directory`_ section.
123
124``${RTEMS_ROOT}/make/``
125    This directory contains files which support the
126    RTEMS Makefile’s.  From a user’s perspective, the
127    most important parts are found in the ``custom/``
128    subdirectory.  Each ".cfg" file in this directory
129    is associated with a specific BSP and describes
130    the CPU model, compiler flags, and procedure to
131    produce an executable for the target board.
132    These files are described in detail in the*RTEMS BSP and Device Driver Development Guide*
133    and will not be discussed further in this document.
134
135``${RTEMS_ROOT}/testsuites/``
136    This directory contains the test suites for the
137    various RTEMS APIs and support libraries.  The
138    contents of this directory are discussed in the `testsuites/ Test Suites`_ section.
139
140``${RTEMS_ROOT}/tools/``
141    This directory contains RTEMS specific support utilities which
142    execute on the development host.  These utilities are divided
143    into subdirectories based upon whether they are used in the process
144    of building RTEMS and applications, are CPU specific, or are
145    used to assist in updating the RTEMS source tree and applications.
146    The support utilities used in the process of building RTEMS are
147    described in `RTEMS Specific Utilities`_.  These are the
148    only components of this subtree that will be discussed in this
149    document.
150
151.. COMMENT: c/ Directions
152
153c/ Directory
154============
155
156The ``${RTEMS_ROOT}/c/`` directory was formerly
157the root directory of all RTEMS source code.  At this time, it contains
158the root directory for only those RTEMS components
159which must be compiled or linked in a way that is specific to a
160particular CPU model or board.  This directory contains the
161following subdirectories:
162
163``${RTEMS_ROOT}/c/src/``
164    This directory is logically the root for the RTEMS components
165    which are CPU model or board dependent.  Thus this directory
166    is the root for the BSPs and the Ada Test Suites as well
167    as CPU model and BSP dependent libraries.  The contents of
168    this directory are discussed in the `c/src/ Directory`_ section.
169
170.. COMMENT: c/src/ Directory
171
172c/src/ Directory
173----------------
174
175As mentioned previously, this directory is logically
176the root for the RTEMS components
177which are CPU model or board dependent.  The
178following is a list of the subdirectories in this
179directory and a description of each.
180
181``${RTEMS_ROOT}/c/src/aclocal/``
182    This directory contains the custom M4 macros which are available to
183    the various GNU autoconf ``configure.ac`` scripts throughout
184    this portion of the RTEMS source tree.  GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used
185    to tailor RTEMS build for a particular host and target environment.  The
186    contents of this directory will not be discussed further in this
187    document.
188
189``${RTEMS_ROOT}/c/src/ada/``
190    This directory contains the Ada95 language bindings to the
191    RTEMS Classic API.
192
193``${RTEMS_ROOT}/c/src/ada-tests/``
194    This directory contains the test suite for the Ada
195    language bindings to the Classic API.
196
197``${RTEMS_ROOT}/c/src/automake/``
198    This directory contains files which are "Makefile fragments."
199    They are included as required by the various ``Makefile.am``
200    files throughout this portion of the RTEMS source tree.
201
202``${RTEMS_ROOT}/c/src/lib/``
203    This directory contains the directories ``libbsp/``
204    and ``libcpu/`` which contain the source code for
205    the Board Support Packages (BSPs) and CPU Model
206    specific source code for RTEMS.
207    The ``libbsp/`` is organized based upon the CPU
208    family and boards BSPs.  The contents of ``libbsp/``
209    are discussed briefly in `c/src/lib/libbsp BSP Directory`_
210    and presented in detail in the*RTEMS BSP and Device Driver Development Guide*.
211    The ``libcpu/`` directory is also organized by
212    CPU family with further divisions based upon CPU
213    model and features that are shared across CPU models
214    such as caching and DMA.
215
216``${RTEMS_ROOT}/c/src/libchip/``
217    This directory contains device drivers for various
218    peripheral chips which are designed to be CPU and
219    board dependent.  This directory contains a variety
220    of drivers for serial devices, network interface
221    controllers, shared memory and real-time clocks.
222
223``${RTEMS_ROOT}/c/src/librtems++/``
224    This directory contains C++ classes which map to the RTEMS
225    Classic API.
226
227``${RTEMS_ROOT}/c/src/make/``
228    This directory is used to generate the bulk of the supporting
229    rules files which are installed as part of the Application Makefiles.
230    This file contains settings for various Makefile variables to
231    tailor them to the particular CPU model and BSP configured.
232
233``${RTEMS_ROOT}/c/src/nfsclient/``
234    This directory contains a Network File System (NFS) client
235    for RTEMS.  With this file system, a user’s application can
236    access files on a remote computer.
237
238``${RTEMS_ROOT}/c/src/optman/``
239    This directory contains stubs for the RTEMS Classic API
240    Managers which are considered optional and whose use
241    may be explicitly forbidden by an application.  All of the
242    directive implementations in this Optional Managers
243    return ``E_NOTCONFIGURED``.
244
245``${RTEMS_ROOT}/c/src/support/``
246    This directory exists solely to generate the RTEMS
247    version string which includes the RTEMS version,
248    CPU architecture, CPU model, and BSP name.
249
250``${RTEMS_ROOT}/c/src/wrapup/``
251    This directory is responsible for taking the individual
252    libraries and objects built in each of the components
253    in the RTEMS source tree and bundling them together to form
254    the single RTEMS library ``librtemsbsp.a``.  This
255    library contains all BSP and CPU model specific software.
256
257.. COMMENT: c/src/lib/libbsp BSP Directory
258
259c/src/lib/libbsp BSP Directory
260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261
262The "libbsp" directory contains a directory for each CPU family supported
263by RTEMS.  Beneath each CPU directory is a directory for each BSP for that
264processor family.
265
266.. COMMENT: Tree 7 - C BSP Library
267
268The "libbsp" directory provides all the BSPs provided with this
269release of the RTEMS executive.  The subdirectories are
270divided,  as discussed previously, based on specific processor
271family, then further broken down into specific target board
272environments.  The "no_cpu" subdirectory provides a starting point
273template BSP which can be used to develop a specific BSP for an
274unsupported target board.  The files in this subdirectory may aid
275in preliminary testing of the RTEMS development environment that has
276been built for no particular target in mind.
277
278Below each CPU dependent directory is a directory for each target BSP
279supported in this release.
280
281Each BSP provides the modules which comprise an RTEMS BSP.  The
282modules are separated into the subdirectories "clock", "console",
283"include", "shmsupp", "startup", and "timer" as shown in the following
284figure:
285
286.. COMMENT: Tree 8 - Each BSP
287
288.. COMMENT: @ifset use-ascii
289.. code:: c
290
291    Each BSP
292    |
293    +-----------+----------+-----+-----+----------+----------+
294    |           |          |           |          |          |
295    clock      console    include     shmsupp    startup     timer
296
297.. COMMENT: @end ifset
298
299.. COMMENT: CPU Kit Directory
300
301CPU Kit Directory
302=================
303
304.. COMMENT: The @code{cpukit/} directory structure is as follows:
305
306.. COMMENT: CPU Kit Tree
307
308.. COMMENT: @ifset use-ascii
309
310.. COMMENT: @example
311
312.. COMMENT: @group
313
314.. COMMENT: cpukit
315
316.. COMMENT: |
317
318.. COMMENT: +-+-+-+-+
319
320.. COMMENT: |           |          |           |          |
321
322.. COMMENT: posix       rtems       sapi       score     wrapup
323
324.. COMMENT: @end group
325
326.. COMMENT: @end example
327
328.. COMMENT: @end ifset
329
330The ``cpukit/`` directory contains a set of subdirectories which
331contains the source files comprising the executive portion of
332the RTEMS development environment as well as portable support
333libraries such as support for the C Library and filesystems.
334The API specific and "SuperCore" (e.g. ``score/`` directory)
335source code files are separated into distinct directory trees.
336
337The following is a description of each of the subdirectories
338under ``cpukit/``:
339
340``${RTEMS_ROOT}/cpukit/aclocal/``
341    This directory contains the custom M4 macros which are available to
342    the various GNU autoconf ``configure.ac`` scripts throughout
343    the CPU Kit portion of the RTEMS source tree.
344    GNU autoconf interprets ``configure.ac``
345    files to produce the ``configure`` files used to tailor
346    RTEMS build for a particular host and target environment.  The
347    contents of this directory will not be discussed further in this
348    document.
349
350``${RTEMS_ROOT}/cpukit/automake/``
351    This directory contains files which are "Makefile fragments."
352    They are included as required by the various ``Makefile.am``
353    files throughout the CPU Kit portion of the RTEMS source tree.
354
355``${RTEMS_ROOT}/cpukit/ftpd/``
356    This directory contains the RTEMS ftpd server.
357
358``${RTEMS_ROOT}/cpukit/httpd/``
359    This directory contains the port of the GoAhead
360    web server to RTEMS.
361
362``${RTEMS_ROOT}/cpukit/include/``
363    This directory contains header files which are private to
364    RTEMS and not considered to be owned by any other component
365    in the CPU Kit.
366
367``${RTEMS_ROOT}/cpukit/libblock/``
368    This directory contains support code for using
369    Block Devices such as hard drives, floppies, and
370    CD-ROMs.  It includes the generic IO primitives
371    for block device drivers, disk caching support,
372    and a RAM disk block device driver.
373
374``${RTEMS_ROOT}/cpukit/libcsupport/``
375    This directory contains the RTEMS specific support routines
376    for the Newlib C Library.  This includes what are referred
377    to as system calls and found in section 2 of the traditional
378    UNIX manual.   In addition, it contains a thread-safe
379    implementation of the Malloc family of routines as well
380    as BSD and POSIX services not found in Newlib.
381
382``${RTEMS_ROOT}/cpukit/libfs/``
383    This directory contains the various non-networked
384    filesystem implementations for RTEMS.  It includes
385    the In-Memory FileSystem (IMFS), the mini-IMFS,
386    and FAT filesystems.
387
388``${RTEMS_ROOT}/cpukit/libi2c/``
389    This directory contains the RTEMS I2C framework.
390
391``${RTEMS_ROOT}/cpukit/libmd/``
392    This directory contains a port of the standard MD5
393    checksum code.
394
395``${RTEMS_ROOT}/c/src/libmisc/``
396    This directory contains support facilities which
397    are RTEMS specific but otherwise unclassified.  In
398    general, they do not adhere to a standard API.
399    Among the support facilities in this directory are
400    a ``/dev/null`` device driver, the Stack
401    Overflow Checker, a mini-shell, the CPU and
402    rate monotonic period usage monitoring libraries,
403    and a utility to "dump a buffer" in a nicely
404    formatted way similar to many ROM monitors.
405
406``${RTEMS_ROOT}/cpukit/libnetworking/``
407    This directory contains the port of the FreeBSD
408    TCP/IP stack to RTEMS.
409
410``${RTEMS_ROOT}/cpukit/librpc/``
411    This directory contains the port of the FreeBSD
412    RPC/XDR source to RTEMS.
413
414``${RTEMS_ROOT}/cpukit/libpci/``
415    This directory contains RTEMS PCI Library.
416
417``${RTEMS_ROOT}/cpukit/posix/``
418    This directory contains the RTEMS implementation
419    of the threading portions of the POSIX API.
420
421``${RTEMS_ROOT}/cpukit/pppd/``
422    This directory contains a port of the free implementation
423    of the PPPD network protocol.
424
425``${RTEMS_ROOT}/cpukit/rtems/``
426    This directory contains the implementation of the
427    Classic API.
428
429``${RTEMS_ROOT}/cpukit/sapi/``
430    This directory contains the implementation of RTEMS
431    services which are required but beyond the realm
432    of any standardization efforts.  It includes
433    initialization, shutdown, and IO services.
434
435``${RTEMS_ROOT}/cpukit/score/``
436    This directory contains the "SuperCore" of RTEMS.
437    All APIs are implemented in terms of SuperCore services.
438    For example, Classic API tasks and POSIX threads
439    are all implemented in terms of SuperCore threads.
440    This provides a common infrastructure and a high degree
441    of interoperability between the APIs.  For example,
442    services from all APIs may be used by any task/thread
443    independent of the API used to create it.
444    Within the ``score/`` directory the CPU dependent modules are found.
445    The ``score/cpu/`` subdirectory contains a subdirectory for each
446    target CPU supported by this release of the RTEMS
447    executive.  Each processor directory contains the CPU dependent
448    code necessary to host RTEMS.  The ``no_cpu`` directory provides a
449    starting point for developing a new port to an unsupported
450    processor.  The files contained within the ``no_cpu`` directory
451    may also be used as a reference for the other ports to specific
452    processors.
453
454``${RTEMS_ROOT}/cpukit/shttpd/``
455    This directory contains the port of the Simple HTTPD
456    web server to RTEMS.
457
458``${RTEMS_ROOT}/cpukit/telnetd/``
459    This directory contains the RTEMS telnetd server.
460
461``${RTEMS_ROOT}/cpukit/wrapup/``
462    This directory is responsible for taking the individual
463    libraries and objects built in each of the components
464    in the RTEMS CPU Kit source tree and bundling them
465    together to form the single RTEMS library ``librtemscpu.a``.  This
466    library contains all BSP and CPU model specific software.
467
468``${RTEMS_ROOT}/cpukit/zlib/``
469    This directory contains a port of the GNU Zlib compression
470    library to RTEMS.
471
472.. COMMENT: testsuites/ Test Suites
473
474testsuites/ Test Suites
475=======================
476
477This directory provides all of the RTEMS Test Suite
478except those for the Classic API Ada95 binding
479This includes the single processor tests, multiprocessor tests,
480timing tests, library tests, and sample tests.   Additionally,
481subdirectories for support functions and test related header
482files are provided.  The following table lists the test suites
483currently included with the RTEMS and the directory in which
484they may be located:
485
486``${RTEMS_ROOT}/testsuites/libtests/``
487    This directory contains the test suite for the
488    various RTEMS support components.
489
490``${RTEMS_ROOT}/testsuites/mptests/``
491    This directory contains the test suite for the
492    multiprocessor support in the Classic API.
493    The tests provided address two node configurations
494    and provide coverage for the multiprocessor code found
495    in RTEMS.
496
497``${RTEMS_ROOT}/testsuites/psxtests/``
498    This directory contains the test suite for the
499    RTEMS POSIX API.
500
501``${RTEMS_ROOT}/testsuites/samples/``
502    This directory provides sample application tests
503    which aid in the testing a newly built RTEMS environment, a new
504    BSP, or as starting points for the development of an application
505    using the RTEMS executive.  They are discussed in `Sample Applications`_.
506
507``${RTEMS_ROOT}/testsuites/sptests/``
508    This directory contains the test suite for the RTEMS
509    Classic API when executing on a single processor.
510    The tests were originally designed to provide
511    near complete test coverage for the entire
512    executive code.  With the addition of multiple APIs,
513    this is no longer the case as some SuperCore functionality
514    is not available through the Classic API.  Thus
515    some functionality in the SuperCore is only covered
516    by tests in the POSIX API Test Suites.
517
518``${RTEMS_ROOT}/testsuites/support/``
519    This directory contains support software and header files
520    for the various test suites.
521
522``${RTEMS_ROOT}/testsuites/tmtests/``
523    This directory contains the timing test suite for
524    the RTEMS Classic API.  This include tests that
525    benchmark each directive in the Classic API
526    as well as a set of critical SuperCore functions.
527    These tests are important for helping to verify
528    that RTEMS performs as expected on your target hardware.
529    It is not uncommon to discover mistakes in board
530    initialization such as caching being disabled as
531    a side-effect of analyzing the results of these tests.
532
533``${RTEMS_ROOT}/testsuites/tools/``
534    This directory contains tools which execute on
535    the development host and aid in executing and
536    evaluating the results of the test suite.  The
537    tools ``difftest`` compares the output of one
538    or more tests with the expected output.  If you
539    place the output of all the ``tmtests/`` in
540    a single file, then the utility ``sorttimes``
541    will be able to produce a report organizing the
542    execution times by manager.
543
544.. COMMENT: Documentation Directory
545
546Documentation Directory
547=======================
548
549This directory contains the source code for all RTEMS documentation
550in ``TexInfo`` format as well as utilities used in the generation
551of the RTEMS documentation set.  This source code is used to produce
552the RTEMS documentation in various formats including PDF, HTML,
553and PostScript.
554
555``${RTEMS_ROOT}/doc/ada_user/``
556    This directory contains the source code for the *RTEMS
557    Applications Ada User’s Guide* which documents the Ada95
558    binding to the Classic API.  This manual is produced from
559    from the same source base as the *RTEMS Application
560    C User’s Guide*.
561
562``${RTEMS_ROOT}/doc/bsp_howto/``
563    This directory contains the source code for the*RTEMS BSP and Device Driver Development Guide*.
564
565``${RTEMS_ROOT}/doc/common/``
566    This directory contains the source code for the files which
567    are shared across multiple manuals in the RTEMS Documentation Set.
568    This includes the copyright page as well as the timing
569    tables which can be filled in on a per BSP basis in the
570    CPU supplements.
571
572``${RTEMS_ROOT}/doc/cpu_supplement/``
573    This directory contains the source code for the
574    RTEMS CPU Supplement.
575
576``${RTEMS_ROOT}/doc/develenv/``
577    This directory contains the source code for the*RTEMS Development Environment Guide*.  This is
578    the document you are currently reading.
579
580``${RTEMS_ROOT}/doc/filesystem/``
581    This directory contains the source code for the*RTEMS Filesystem Design Guide*.  This manual
582    is a continuous work in process as it attempts to
583    capture the design of the interface between system
584    calls and filesystem implementations as well as the
585    information required by those implementing filesystems.
586
587``${RTEMS_ROOT}/doc/images/``
588    This directory contains the source code for the graphics
589    used in the HTML version of the RTEMS Documentation.
590
591``${RTEMS_ROOT}/doc/networking/``
592    This directory contains the source code for the*RTEMS Network Supplement*.
593
594``${RTEMS_ROOT}/doc/new_chapters/``
595    This directory contains the source code for the new documentation
596    components which have not yet been collected into a new manual or
597    merged into an existing document.  Currently, this primarily
598    contains draft documentation for some portions of
599    the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``.
600
601``${RTEMS_ROOT}/doc/porting/``
602    This directory contains the source code for the*RTEMS Porting Guide*.
603
604``${RTEMS_ROOT}/doc/posix1003.1/``
605    This directory contains the source code for the*RTEMS POSIX 1003.1 Compliance Guide*.
606
607``${RTEMS_ROOT}/doc/posix_users/``
608    This directory contains the source code for the*RTEMS POSIX API User’s Guide*.  It is important to
609    note that RTEMS’ support for POSIX is a combination of
610    functionality provided by RTEMS and the Newlib C Library
611    so some functionality is documented by Newlib.
612
613``${RTEMS_ROOT}/doc/relnotes/``
614    This directory contains the source code for a formally
615    release notes document.  This has not been used for
616    recent RTEMS releases.
617
618``${RTEMS_ROOT}/doc/started/``
619    This directory contains the source code for the*Getting Started with RTEMS for C/C++ Users* manual.
620
621``${RTEMS_ROOT}/doc/tools/``
622    This directory contains the source code for the tools
623    used on the development host to assist in producing the
624    RTEMS Documentation.  The most important of these tools
625    is ``bmenu`` which generates the hierarchical node
626    linking commands based upon chapter, section, and
627    subsection organization.
628
629``${RTEMS_ROOT}/doc/user/``
630    This directory contains the source code for the *RTEMS
631    Applications C User’s Guide* which documents the Classic API.
632
633.. COMMENT: COPYRIGHT (c) 1989-2007.
634
635.. COMMENT: On-Line Applications Research Corporation (OAR).
636
637.. COMMENT: All rights reserved.
638
639
Note: See TracBrowser for help on using the repository browser.