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

4.115
Last change on this file since c2cefaa was c2cefaa, checked in by Joel Sherrill <joel@…>, on 10/27/16 at 23:35:41

develenv: Fix build errors for real

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