Changeset 9b53679 in rtems-docs


Ignore:
Timestamp:
Oct 27, 2016, 11:12:50 PM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, 5, am, master
Children:
8e59c99
Parents:
be428d1
git-author:
Chris Johns <chrisj@…> (10/27/16 23:12:50)
git-committer:
Chris Johns <chrisj@…> (10/27/16 23:13:03)
Message:

Fix develenv. Needs more fixes.

Location:
develenv
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • develenv/command.rst

    rbe428d1 r9b53679  
    55
    66There are currently no Command and Variable Index entries.
    7 
    8 .. COMMENT: @printindex fn
    9 

  • develenv/directory.rst

    rbe428d1 r9b53679  
    11.. 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.
    26
    37Directory Structure
    48###################
    59
    6 The RTEMS directory structure is designed to meet
    7 the following requirements:
     10The RTEMS directory structure is designed to meet the following requirements:
    811
    912- encourage development of modular components.
    1013
    11 - isolate processor and target dependent code, while
    12   allowing as much common source code as possible to be shared
    13   across multiple processors and target boards.
    14 
    15 - allow multiple RTEMS users to perform simultaneous
    16   compilation of RTEMS and its support facilities for different
    17   processors and targets.
    18 
    19 The resulting directory structure has processor and
    20 board dependent source files isolated from generic files.  When
    21 RTEMS is configured and built, object directories and
    22 an install point will be automatically created based upon
    23 the target CPU family and BSP selected.
    24 
    25 The placement of object files based upon the selected BSP name
    26 ensures that object files are not mixed across CPUs or targets.
    27 This in combination with the makefiles allows the specific
    28 compilation options to be tailored for a particular target
    29 board.  For example, the efficiency of the memory subsystem for
    30 a particular target board may be sensitive to the alignment of
    31 data structures, while on another target board with the same
    32 processor memory may be very limited.  For the first target, the
    33 options could specify very strict alignment requirements, while
    34 on the second the data structures could be *packed* to conserve
    35 memory.  It is impossible to achieve this degree of flexibility
    36 without providing source code.
     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.
    3736
    3837The RTEMS source tree is organized based on the following variables:
    … …  
    4847- target board.
    4948
    50 Each of the following sections will describe the
    51 contents of the directories in the RTEMS source
    52 tree.  The top of the tree will be referenced
    53 as ``${RTEMS_ROOT}`` in this discussion.
    54 
    55 .. COMMENT: Top Level Tree
    56 
    57 .. COMMENT: @ifset use-ascii
    58 .. code:: c
     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
    5954
    6055    rtems-VERSION
    … …  
    6459    aclocal automake c contrib  cpukit doc make testsuites tools
    6560
    66 .. COMMENT: @end ifset
    67 
    6861``${RTEMS_ROOT}/aclocal/``
    69     This directory contains the custom M4 macros which are available to
    70     the various GNU autoconf ``configure.ac`` scripts throughout
    71     the RTEMS source tree.  GNU autoconf interprets ``configure.ac``
    72     files to produce the ``configure`` files used to tailor
    73     RTEMS build for a particular host and target environment.  The
    74     contents of this directory will not be discussed further in this
     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
    7573    document.
    7674
    77 ``${RTEMS_ROOT}/automake/``
    78     This directory contains the custom GNU automake fragments
    79     which are used to support the various ``Makefile.am``
    80     files throughout the RTEMS source tree.  The
    81     contents of this directory will not be discussed
    82     further in this document.
    83 
    8475``${RTEMS_ROOT}/c/``
    85     This directory is the root of the portions of the RTEMS source
    86     tree which must be built tailored for a particular CPU model
    87     or BSP.  The contents of this directory will be discussed
    88     in the `c/ Directory`_ section.
     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.
    8979
    9080``${RTEMS_ROOT}/contrib/``
    91     This directory contains contributed support software.  Currently
    92     this directory contains the RPM specifications for cross-compilers
    93     hosted on GNU/Linux that target various operating systems
    94     including MinGW, Cygwin, FreeBSD, and Solaris.  The
    95     cross-compilers produced using these specifications are then
    96     used in a Canadian cross build procedure to produce the various
    97     RTEMS toolsets on a GNU/Linux host.
    98     This directory also contains RPM specifications for the
    99     prebuilt cross-compilation toolsets provided by the
    100     RTEMS project.  There are separate subdirectories
    101     for each of the components in the RTEMS Cross Compilation
    102     Environment unde the  ``contrib/crossrpms/`` directory.
    103     This directory is configured, built, and installed separately
    104     from the RTEMS executive and tests.  This directory will not
     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
    105116    be discussed further in this document.
    106117
    107 ``${RTEMS_ROOT}/cpukit/``
    108     This directory is the root for all of the "multilib'able"
    109     portions of RTEMS.  This is a GNU way of saying the
    110     contents of this directory can be compiled like the
    111     C Library (``libc.a``) and the functionality is
    112     neither CPU model nor BSP specific.  The source code
    113     for most RTEMS services reside under this directory.
    114     The contents of this directory will be discussed
    115     in the `CPU Kit Directory`_ section.
    116 
    117 ``${RTEMS_ROOT}/doc/``
    118     This directory is the root for all RTEMS documentation.
    119     The source for RTEMS is written in GNU TeXinfo and
    120     used to produce HTML, PDF, and "info" files.
    121     The RTEMS documentation is configured, built,
    122     and installed separately from the RTEMS executive and tests.
    123     The contents of this directory will be discussed
    124     in the `Documentation Directory`_ section.
    125 
    126 ``${RTEMS_ROOT}/make/``
    127     This directory contains files which support the
    128     RTEMS Makefile's.  From a user's perspective, the
    129     most important parts are found in the ``custom/``
    130     subdirectory.  Each ".cfg" file in this directory
    131     is associated with a specific BSP and describes
    132     the CPU model, compiler flags, and procedure to
    133     produce an executable for the target board.
    134     These files are described in detail in the*RTEMS BSP and Device Driver Development Guide*
    135     and will not be discussed further in this document.
    136 
    137118``${RTEMS_ROOT}/testsuites/``
    138     This directory contains the test suites for the
    139     various RTEMS APIs and support libraries.  The
    140     contents of this directory are discussed in the `testsuites/ Test Suites`_ section.
     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.
    141122
    142123``${RTEMS_ROOT}/tools/``
    143     This directory contains RTEMS specific support utilities which
    144     execute on the development host.  These utilities are divided
    145     into subdirectories based upon whether they are used in the process
    146     of building RTEMS and applications, are CPU specific, or are
    147     used to assist in updating the RTEMS source tree and applications.
    148     The support utilities used in the process of building RTEMS are
    149     described in `RTEMS Specific Utilities`_.  These are the
    150     only components of this subtree that will be discussed in this
    151     document.
    152 
    153 .. COMMENT: c/ Directions
     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 `RTEMS Specific Utilities`_.  These are the
     130    only components of this subtree that will be discussed in this document.
    154131
    155132c/ Directory
    156133============
    157134
    158 The ``${RTEMS_ROOT}/c/`` directory was formerly
    159 the root directory of all RTEMS source code.  At this time, it contains
    160 the root directory for only those RTEMS components
    161 which must be compiled or linked in a way that is specific to a
    162 particular CPU model or board.  This directory contains the
    163 following subdirectories:
     135The ``${RTEMS_ROOT}/c/`` directory was formerly the root directory of all RTEMS
     136source code.  At this time, it contains the root directory for only those RTEMS
     137components which must be compiled or linked in a way that is specific to a
     138particular CPU model or board.  This directory contains the following
     139subdirectories:
    164140
    165141``${RTEMS_ROOT}/c/src/``
    166     This directory is logically the root for the RTEMS components
    167     which are CPU model or board dependent.  Thus this directory
    168     is the root for the BSPs and the Ada Test Suites as well
    169     as CPU model and BSP dependent libraries.  The contents of
    170     this directory are discussed in the `c/src/ Directory`_ section.
    171 
    172 .. COMMENT: c/src/ Directory
     142    This directory is logically the root for the RTEMS components which are CPU
     143    model or board dependent.  Thus this directory is the root for the BSPs and
     144    the Ada Test Suites as well as CPU model and BSP dependent libraries.  The
     145    contents of this directory are discussed in the `c/src/ Directory`_
     146    section.
    173147
    174148c/src/ Directory
    175149----------------
    176150
    177 As mentioned previously, this directory is logically
    178 the root for the RTEMS components
    179 which are CPU model or board dependent.  The
    180 following is a list of the subdirectories in this
    181 directory and a description of each.
     151As mentioned previously, this directory is logically the root for the RTEMS
     152components which are CPU model or board dependent.  The following is a list of
     153the subdirectories in this directory and a description of each.
    182154
    183155``${RTEMS_ROOT}/c/src/aclocal/``
    184     This directory contains the custom M4 macros which are available to
    185     the various GNU autoconf ``configure.ac`` scripts throughout
    186     this portion of the RTEMS source tree.  GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used
    187     to tailor RTEMS build for a particular host and target environment.  The
    188     contents of this directory will not be discussed further in this
    189     document.
     156    This directory contains the custom M4 macros which are available to the
     157    various GNU autoconf ``configure.ac`` scripts throughout this portion of
     158    the RTEMS source tree.  GNU autoconf interprets``configure.ac`` files to
     159    produce the ``configure`` files used to tailor RTEMS build for a particular
     160    host and target environment.  The contents of this directory will not be
     161    discussed further in this document.
    190162
    191163``${RTEMS_ROOT}/c/src/ada/``
    192     This directory contains the Ada95 language bindings to the
    193     RTEMS Classic API.
     164    This directory contains the Ada95 language bindings to the RTEMS Classic
     165    API.
    194166
    195167``${RTEMS_ROOT}/c/src/ada-tests/``
    196     This directory contains the test suite for the Ada
    197     language bindings to the Classic API.
     168    This directory contains the test suite for the Ada language bindings to the
     169    Classic API.
    198170
    199171``${RTEMS_ROOT}/c/src/automake/``
    200     This directory contains files which are "Makefile fragments."
    201     They are included as required by the various ``Makefile.am``
    202     files throughout this portion of the RTEMS source tree.
     172    This directory contains files which are "Makefile fragments."  They are
     173    included as required by the various ``Makefile.am`` files throughout this
     174    portion of the RTEMS source tree.
    203175
    204176``${RTEMS_ROOT}/c/src/lib/``
    205     This directory contains the directories ``libbsp/``
    206     and ``libcpu/`` which contain the source code for
    207     the Board Support Packages (BSPs) and CPU Model
    208     specific source code for RTEMS.
    209     The ``libbsp/`` is organized based upon the CPU
    210     family and boards BSPs.  The contents of ``libbsp/``
    211     are discussed briefly in `c/src/lib/libbsp BSP Directory`_
    212     and presented in detail in the*RTEMS BSP and Device Driver Development Guide*.
    213     The ``libcpu/`` directory is also organized by
    214     CPU family with further divisions based upon CPU
    215     model and features that are shared across CPU models
    216     such as caching and DMA.
     177    This directory contains the directories ``libbsp/`` and ``libcpu/`` which
     178    contain the source code for the Board Support Packages (BSPs) and CPU Model
     179    specific source code for RTEMS.  The ``libbsp/`` is organized based upon
     180    the CPU family and boards BSPs.  The contents of ``libbsp/`` are discussed
     181    briefly in `c/src/lib/libbsp BSP Directory`_ and presented in detail in
     182    the*RTEMS BSP and Device Driver Development Guide*.  The ``libcpu/``
     183    directory is also organized by CPU family with further divisions based upon
     184    CPU model and features that are shared across CPU models such as caching
     185    and DMA.
    217186
    218187``${RTEMS_ROOT}/c/src/libchip/``
    219     This directory contains device drivers for various
    220     peripheral chips which are designed to be CPU and
    221     board dependent.  This directory contains a variety
    222     of drivers for serial devices, network interface
    223     controllers, shared memory and real-time clocks.
     188    This directory contains device drivers for various peripheral chips which
     189    are designed to be CPU and board dependent.  This directory contains a
     190    variety of drivers for serial devices, network interface controllers,
     191    shared memory and real-time clocks.
    224192
    225193``${RTEMS_ROOT}/c/src/librtems++/``
    226     This directory contains C++ classes which map to the RTEMS
    227     Classic API.
     194    This directory contains C++ classes which map to the RTEMS Classic API.
    228195
    229196``${RTEMS_ROOT}/c/src/make/``
    230     This directory is used to generate the bulk of the supporting
    231     rules files which are installed as part of the Application Makefiles.
    232     This file contains settings for various Makefile variables to
    233     tailor them to the particular CPU model and BSP configured.
     197    This directory is used to generate the bulk of the supporting rules files
     198    which are installed as part of the Application Makefiles.  This file
     199    contains settings for various Makefile variables to tailor them to the
     200    particular CPU model and BSP configured.
    234201
    235202``${RTEMS_ROOT}/c/src/nfsclient/``
    236     This directory contains a Network File System (NFS) client
    237     for RTEMS.  With this file system, a user's application can
    238     access files on a remote computer.
     203    This directory contains a Network File System (NFS) client for RTEMS.  With
     204    this file system, a user's application can access files on a remote
     205    computer.
    239206
    240207``${RTEMS_ROOT}/c/src/optman/``
    241     This directory contains stubs for the RTEMS Classic API
    242     Managers which are considered optional and whose use
    243     may be explicitly forbidden by an application.  All of the
    244     directive implementations in this Optional Managers
    245     return ``E_NOTCONFIGURED``.
     208    This directory contains stubs for the RTEMS Classic API Managers which are
     209    considered optional and whose use may be explicitly forbidden by an
     210    application.  All of the directive implementations in this Optional
     211    Managers return ``E_NOTCONFIGURED``.
    246212
    247213``${RTEMS_ROOT}/c/src/support/``
    248     This directory exists solely to generate the RTEMS
    249     version string which includes the RTEMS version,
    250     CPU architecture, CPU model, and BSP name.
     214    This directory exists solely to generate the RTEMS version string which
     215    includes the RTEMS version, CPU architecture, CPU model, and BSP name.
    251216
    252217``${RTEMS_ROOT}/c/src/wrapup/``
    253     This directory is responsible for taking the individual
    254     libraries and objects built in each of the components
    255     in the RTEMS source tree and bundling them together to form
    256     the single RTEMS library ``librtemsbsp.a``.  This
    257     library contains all BSP and CPU model specific software.
    258 
    259 .. COMMENT: c/src/lib/libbsp BSP Directory
     218    This directory is responsible for taking the individual libraries and
     219    objects built in each of the components in the RTEMS source tree and
     220    bundling them together to form the single RTEMS library ``librtemsbsp.a``.
     221    This library contains all BSP and CPU model specific software.
    260222
    261223c/src/lib/libbsp BSP Directory
    262224~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    263225
    264 The "libbsp" directory contains a directory for each CPU family supported
    265 by RTEMS.  Beneath each CPU directory is a directory for each BSP for that
     226The "libbsp" directory contains a directory for each CPU family supported by
     227RTEMS.  Beneath each CPU directory is a directory for each BSP for that
    266228processor family.
    267229
    268 .. COMMENT: Tree 7 - C BSP Library
    269 
    270 The "libbsp" directory provides all the BSPs provided with this
    271 release of the RTEMS executive.  The subdirectories are
    272 divided,  as discussed previously, based on specific processor
    273 family, then further broken down into specific target board
    274 environments.  The "no_cpu" subdirectory provides a starting point
    275 template BSP which can be used to develop a specific BSP for an
    276 unsupported target board.  The files in this subdirectory may aid
    277 in preliminary testing of the RTEMS development environment that has
    278 been built for no particular target in mind.
    279 
    280 Below each CPU dependent directory is a directory for each target BSP
    281 supported in this release.
    282 
    283 Each BSP provides the modules which comprise an RTEMS BSP.  The
    284 modules are separated into the subdirectories "clock", "console",
    285 "include", "shmsupp", "startup", and "timer" as shown in the following
    286 figure:
    287 
    288 .. COMMENT: Tree 8 - Each BSP
    289 
    290 .. COMMENT: @ifset use-ascii
    291 .. code:: c
     230The "libbsp" directory provides all the BSPs provided with this release of the
     231RTEMS executive.  The subdirectories are divided, as discussed previously,
     232based on specific processor family, then further broken down into specific
     233target board environments.  The "no_cpu" subdirectory provides a starting point
     234template BSP which can be used to develop a specific BSP for an unsupported
     235target board.  The files in this subdirectory may aid in preliminary testing of
     236the RTEMS development environment that has been built for no particular target
     237in mind.
     238
     239Below each CPU dependent directory is a directory for each target BSP supported
     240in this release.
     241
     242Each BSP provides the modules which comprise an RTEMS BSP.  The modules are
     243separated into the subdirectories "clock", "console", "include", "shmsupp",
     244"startup", and "timer" as shown in the following figure:
     245
     246.. code-block:: c
    292247
    293248    Each BSP
    … …  
    297252    clock      console    include     shmsupp    startup     timer
    298253
    299 .. COMMENT: @end ifset
    300 
    301 .. COMMENT: CPU Kit Directory
    302 
    303254CPU Kit Directory
    304255=================
    305256
    306 .. COMMENT: The @code{cpukit/} directory structure is as follows:
    307 
    308 .. COMMENT: CPU Kit Tree
    309 
    310 .. COMMENT: @ifset use-ascii
    311 
    312 .. COMMENT: @example
    313 
    314 .. COMMENT: @group
    315 
    316 .. COMMENT: cpukit
    317 
    318 .. COMMENT: |
    319 
    320 .. COMMENT: +-+-+-+-+
    321 
    322 .. COMMENT: |           |          |           |          |
    323 
    324 .. COMMENT: posix       rtems       sapi       score     wrapup
    325 
    326 .. COMMENT: @end group
    327 
    328 .. COMMENT: @end example
    329 
    330 .. COMMENT: @end ifset
    331 
    332 The ``cpukit/`` directory contains a set of subdirectories which
    333 contains the source files comprising the executive portion of
    334 the RTEMS development environment as well as portable support
    335 libraries such as support for the C Library and filesystems.
    336 The API specific and "SuperCore" (e.g. ``score/`` directory)
    337 source code files are separated into distinct directory trees.
    338 
    339 The following is a description of each of the subdirectories
    340 under ``cpukit/``:
     257The @code{cpukit/} directory structure is as follows:
     258
     259.. code-block:: c
     260
     261    cpukit
     262    |
     263    +-----------+----------+-----------+----------+
     264    |           |          |           |          |
     265    posix       rtems       sapi       score     wrapup
     266
     267The ``cpukit/`` directory contains a set of subdirectories which contains the
     268source files comprising the executive portion of the RTEMS development
     269environment as well as portable support libraries such as support for the C
     270Library and filesystems.  The API specific and "SuperCore" (e.g. ``score/``
     271directory) source code files are separated into distinct directory trees.
     272
     273The following is a description of each of the subdirectories under ``cpukit/``:
    341274
    342275``${RTEMS_ROOT}/cpukit/aclocal/``
    343     This directory contains the custom M4 macros which are available to
    344     the various GNU autoconf ``configure.ac`` scripts throughout
    345     the CPU Kit portion of the RTEMS source tree.
    346     GNU autoconf interprets ``configure.ac``
    347     files to produce the ``configure`` files used to tailor
    348     RTEMS build for a particular host and target environment.  The
    349     contents of this directory will not be discussed further in this
    350     document.
     276    This directory contains the custom M4 macros which are available to the
     277    various GNU autoconf ``configure.ac`` scripts throughout the CPU Kit
     278    portion of the RTEMS source tree.  GNU autoconf interprets ``configure.ac``
     279    files to produce the ``configure`` files used to tailor RTEMS build for a
     280    particular host and target environment.  The contents of this directory
     281    will not be discussed further in this document.
    351282
    352283``${RTEMS_ROOT}/cpukit/automake/``
    353     This directory contains files which are "Makefile fragments."
    354     They are included as required by the various ``Makefile.am``
    355     files throughout the CPU Kit portion of the RTEMS source tree.
     284    This directory contains files which are "Makefile fragments."  They are
     285    included as required by the various ``Makefile.am`` files throughout the
     286    CPU Kit portion of the RTEMS source tree.
    356287
    357288``${RTEMS_ROOT}/cpukit/ftpd/``
    … …  
    359290
    360291``${RTEMS_ROOT}/cpukit/httpd/``
    361     This directory contains the port of the GoAhead
    362     web server to RTEMS.
     292    This directory contains the port of the GoAhead web server to RTEMS.
    363293
    364294``${RTEMS_ROOT}/cpukit/include/``
    365     This directory contains header files which are private to
    366     RTEMS and not considered to be owned by any other component
    367     in the CPU Kit.
     295    This directory contains header files which are private to RTEMS and not
     296    considered to be owned by any other component in the CPU Kit.
    368297
    369298``${RTEMS_ROOT}/cpukit/libblock/``
    370     This directory contains support code for using
    371     Block Devices such as hard drives, floppies, and
    372     CD-ROMs.  It includes the generic IO primitives
    373     for block device drivers, disk caching support,
    374     and a RAM disk block device driver.
     299    This directory contains support code for using Block Devices such as hard
     300    drives, floppies, and CD-ROMs.  It includes the generic IO primitives for
     301    block device drivers, disk caching support, and a RAM disk block device
     302    driver.
    375303
    376304``${RTEMS_ROOT}/cpukit/libcsupport/``
    377     This directory contains the RTEMS specific support routines
    378     for the Newlib C Library.  This includes what are referred
    379     to as system calls and found in section 2 of the traditional
    380     UNIX manual.   In addition, it contains a thread-safe
    381     implementation of the Malloc family of routines as well
    382     as BSD and POSIX services not found in Newlib.
     305    This directory contains the RTEMS specific support routines for the Newlib
     306    C Library.  This includes what are referred to as system calls and found in
     307    section 2 of the traditional UNIX manual.  In addition, it contains a
     308    thread-safe implementation of the Malloc family of routines as well as BSD
     309    and POSIX services not found in Newlib.
    383310
    384311``${RTEMS_ROOT}/cpukit/libfs/``
    385     This directory contains the various non-networked
    386     filesystem implementations for RTEMS.  It includes
    387     the In-Memory FileSystem (IMFS), the mini-IMFS,
    388     and FAT filesystems.
     312    This directory contains the various non-networked filesystem
     313    implementations for RTEMS.  It includes the In-Memory FileSystem (IMFS),
     314    the mini-IMFS, and FAT filesystems.
    389315
    390316``${RTEMS_ROOT}/cpukit/libi2c/``
    … …  
    392318
    393319``${RTEMS_ROOT}/cpukit/libmd/``
    394     This directory contains a port of the standard MD5
    395     checksum code.
     320    This directory contains a port of the standard MD5 checksum code.
    396321
    397322``${RTEMS_ROOT}/c/src/libmisc/``
    398     This directory contains support facilities which
    399     are RTEMS specific but otherwise unclassified.  In
    400     general, they do not adhere to a standard API.
    401     Among the support facilities in this directory are
    402     a ``/dev/null`` device driver, the Stack
    403     Overflow Checker, a mini-shell, the CPU and
    404     rate monotonic period usage monitoring libraries,
    405     and a utility to "dump a buffer" in a nicely
    406     formatted way similar to many ROM monitors.
     323    This directory contains support facilities which are RTEMS specific but
     324    otherwise unclassified.  In general, they do not adhere to a standard API.
     325    Among the support facilities in this directory are a ``/dev/null`` device
     326    driver, the Stack Overflow Checker, a mini-shell, the CPU and rate
     327    monotonic period usage monitoring libraries, and a utility to "dump a
     328    buffer" in a nicely formatted way similar to many ROM monitors.
    407329
    408330``${RTEMS_ROOT}/cpukit/libnetworking/``
    409     This directory contains the port of the FreeBSD
    410     TCP/IP stack to RTEMS.
     331    This directory contains the port of the FreeBSD TCP/IP stack to RTEMS.
    411332
    412333``${RTEMS_ROOT}/cpukit/librpc/``
    413     This directory contains the port of the FreeBSD
    414     RPC/XDR source to RTEMS.
     334    This directory contains the port of the FreeBSD RPC/XDR source to RTEMS.
    415335
    416336``${RTEMS_ROOT}/cpukit/libpci/``
    … …  
    418338
    419339``${RTEMS_ROOT}/cpukit/posix/``
    420     This directory contains the RTEMS implementation
    421     of the threading portions of the POSIX API.
     340    This directory contains the RTEMS implementation of the threading portions
     341    of the POSIX API.
    422342
    423343``${RTEMS_ROOT}/cpukit/pppd/``
    424     This directory contains a port of the free implementation
    425     of the PPPD network protocol.
     344    This directory contains a port of the free implementation of the PPPD
     345    network protocol.
    426346
    427347``${RTEMS_ROOT}/cpukit/rtems/``
    428     This directory contains the implementation of the
    429     Classic API.
     348    This directory contains the implementation of the Classic API.
    430349
    431350``${RTEMS_ROOT}/cpukit/sapi/``
    432     This directory contains the implementation of RTEMS
    433     services which are required but beyond the realm
    434     of any standardization efforts.  It includes
     351    This directory contains the implementation of RTEMS services which are
     352    required but beyond the realm of any standardization efforts.  It includes
    435353    initialization, shutdown, and IO services.
    436354
    437355``${RTEMS_ROOT}/cpukit/score/``
    438     This directory contains the "SuperCore" of RTEMS.
    439     All APIs are implemented in terms of SuperCore services.
    440     For example, Classic API tasks and POSIX threads
    441     are all implemented in terms of SuperCore threads.
    442     This provides a common infrastructure and a high degree
    443     of interoperability between the APIs.  For example,
    444     services from all APIs may be used by any task/thread
    445     independent of the API used to create it.
    446     Within the ``score/`` directory the CPU dependent modules are found.
    447     The ``score/cpu/`` subdirectory contains a subdirectory for each
    448     target CPU supported by this release of the RTEMS
    449     executive.  Each processor directory contains the CPU dependent
    450     code necessary to host RTEMS.  The ``no_cpu`` directory provides a
    451     starting point for developing a new port to an unsupported
    452     processor.  The files contained within the ``no_cpu`` directory
    453     may also be used as a reference for the other ports to specific
    454     processors.
     356    This directory contains the "SuperCore" of RTEMS.  All APIs are implemented
     357    in terms of SuperCore services.  For example, Classic API tasks and POSIX
     358    threads are all implemented in terms of SuperCore threads.  This provides a
     359    common infrastructure and a high degree of interoperability between the
     360    APIs.  For example, services from all APIs may be used by any task/thread
     361    independent of the API used to create it.  Within the ``score/`` directory
     362    the CPU dependent modules are found.  The ``score/cpu/`` subdirectory
     363    contains a subdirectory for each target CPU supported by this release of
     364    the RTEMS executive.  Each processor directory contains the CPU dependent
     365    code necessary to host RTEMS.  The ``no_cpu`` directory provides a starting
     366    point for developing a new port to an unsupported processor.  The files
     367    contained within the ``no_cpu`` directory may also be used as a reference
     368    for the other ports to specific processors.
    455369
    456370``${RTEMS_ROOT}/cpukit/shttpd/``
    457     This directory contains the port of the Simple HTTPD
    458     web server to RTEMS.
     371    This directory contains the port of the Simple HTTPD web server to RTEMS.
    459372
    460373``${RTEMS_ROOT}/cpukit/telnetd/``
    … …  
    462375
    463376``${RTEMS_ROOT}/cpukit/wrapup/``
    464     This directory is responsible for taking the individual
    465     libraries and objects built in each of the components
    466     in the RTEMS CPU Kit source tree and bundling them
    467     together to form the single RTEMS library ``librtemscpu.a``.  This
    468     library contains all BSP and CPU model specific software.
     377    This directory is responsible for taking the individual libraries and
     378    objects built in each of the components in the RTEMS CPU Kit source tree
     379    and bundling them together to form the single RTEMS library
     380    ``librtemscpu.a``.  This library contains all BSP and CPU model specific
     381    software.
    469382
    470383``${RTEMS_ROOT}/cpukit/zlib/``
    471     This directory contains a port of the GNU Zlib compression
    472     library to RTEMS.
    473 
    474 .. COMMENT: testsuites/ Test Suites
     384    This directory contains a port of the GNU Zlib compression library to
     385    RTEMS.
    475386
    476387testsuites/ Test Suites
    477388=======================
    478389
    479 This directory provides all of the RTEMS Test Suite
    480 except those for the Classic API Ada95 binding
    481 This includes the single processor tests, multiprocessor tests,
    482 timing tests, library tests, and sample tests.   Additionally,
    483 subdirectories for support functions and test related header
    484 files are provided.  The following table lists the test suites
    485 currently included with the RTEMS and the directory in which
    486 they may be located:
     390This directory provides all of the RTEMS Test Suite except those for the
     391Classic API Ada95 binding This includes the single processor tests,
     392multiprocessor tests, timing tests, library tests, and sample tests.
     393Additionally, subdirectories for support functions and test related header
     394files are provided.  The following table lists the test suites currently
     395included with the RTEMS and the directory in which they may be located:
    487396
    488397``${RTEMS_ROOT}/testsuites/libtests/``
    489     This directory contains the test suite for the
    490     various RTEMS support components.
     398    This directory contains the test suite for the various RTEMS support
     399    components.
    491400
    492401``${RTEMS_ROOT}/testsuites/mptests/``
    493     This directory contains the test suite for the
    494     multiprocessor support in the Classic API.
    495     The tests provided address two node configurations
    496     and provide coverage for the multiprocessor code found
    497     in RTEMS.
     402    This directory contains the test suite for the multiprocessor support in
     403    the Classic API.  The tests provided address two node configurations and
     404    provide coverage for the multiprocessor code found in RTEMS.
    498405
    499406``${RTEMS_ROOT}/testsuites/psxtests/``
    500     This directory contains the test suite for the
    501     RTEMS POSIX API.
     407    This directory contains the test suite for the RTEMS POSIX API.
    502408
    503409``${RTEMS_ROOT}/testsuites/samples/``
    504     This directory provides sample application tests
    505     which aid in the testing a newly built RTEMS environment, a new
    506     BSP, or as starting points for the development of an application
    507     using the RTEMS executive.  They are discussed in `Sample Applications`_.
     410    This directory provides sample application tests which aid in the testing a
     411    newly built RTEMS environment, a new BSP, or as starting points for the
     412    development of an application using the RTEMS executive.  They are
     413    discussed in `Sample Applications`_.
    508414
    509415``${RTEMS_ROOT}/testsuites/sptests/``
    510     This directory contains the test suite for the RTEMS
    511     Classic API when executing on a single processor.
    512     The tests were originally designed to provide
    513     near complete test coverage for the entire
    514     executive code.  With the addition of multiple APIs,
    515     this is no longer the case as some SuperCore functionality
    516     is not available through the Classic API.  Thus
    517     some functionality in the SuperCore is only covered
    518     by tests in the POSIX API Test Suites.
     416    This directory contains the test suite for the RTEMS Classic API when
     417    executing on a single processor.  The tests were originally designed to
     418    provide near complete test coverage for the entire executive code.  With
     419    the addition of multiple APIs, this is no longer the case as some SuperCore
     420    functionality is not available through the Classic API.  Thus some
     421    functionality in the SuperCore is only covered by tests in the POSIX API
     422    Test Suites.
    519423
    520424``${RTEMS_ROOT}/testsuites/support/``
    521     This directory contains support software and header files
    522     for the various test suites.
     425    This directory contains support software and header files for the various
     426    test suites.
    523427
    524428``${RTEMS_ROOT}/testsuites/tmtests/``
    525     This directory contains the timing test suite for
    526     the RTEMS Classic API.  This include tests that
    527     benchmark each directive in the Classic API
    528     as well as a set of critical SuperCore functions.
    529     These tests are important for helping to verify
    530     that RTEMS performs as expected on your target hardware.
    531     It is not uncommon to discover mistakes in board
    532     initialization such as caching being disabled as
    533     a side-effect of analyzing the results of these tests.
     429    This directory contains the timing test suite for the RTEMS Classic API.
     430    This include tests that benchmark each directive in the Classic API as well
     431    as a set of critical SuperCore functions.  These tests are important for
     432    helping to verify that RTEMS performs as expected on your target hardware.
     433    It is not uncommon to discover mistakes in board initialization such as
     434    caching being disabled as a side-effect of analyzing the results of these
     435    tests.
    534436
    535437``${RTEMS_ROOT}/testsuites/tools/``
    536     This directory contains tools which execute on
    537     the development host and aid in executing and
    538     evaluating the results of the test suite.  The
    539     tools ``difftest`` compares the output of one
    540     or more tests with the expected output.  If you
    541     place the output of all the ``tmtests/`` in
    542     a single file, then the utility ``sorttimes``
    543     will be able to produce a report organizing the
    544     execution times by manager.
    545 
    546 .. COMMENT: Documentation Directory
     438    This directory contains tools which execute on the development host and aid
     439    in executing and evaluating the results of the test suite.  The tools
     440    ``difftest`` compares the output of one or more tests with the expected
     441    output.  If you place the output of all the ``tmtests/`` in a single file,
     442    then the utility ``sorttimes`` will be able to produce a report organizing
     443    the execution times by manager.
    547444
    548445Documentation Directory
    549446=======================
    550447
    551 This directory contains the source code for all RTEMS documentation
    552 in ``TexInfo`` format as well as utilities used in the generation
    553 of the RTEMS documentation set.  This source code is used to produce
    554 the RTEMS documentation in various formats including PDF, HTML,
    555 and PostScript.
     448This directory contains the source code for all RTEMS documentation in
     449``TexInfo`` format as well as utilities used in the generation of the RTEMS
     450documentation set.  This source code is used to produce the RTEMS documentation
     451in various formats including PDF, HTML, and PostScript.
    556452
    557453``${RTEMS_ROOT}/doc/ada_user/``
    558     This directory contains the source code for the *RTEMS
    559     Applications Ada User's Guide* which documents the Ada95
    560     binding to the Classic API.  This manual is produced from
    561     from the same source base as the *RTEMS Application
     454    This directory contains the source code for the *RTEMS Applications Ada
     455    User's Guide* which documents the Ada95 binding to the Classic API.  This
     456    manual is produced from from the same source base as the *RTEMS Application
    562457    C User's Guide*.
    563458
    564459``${RTEMS_ROOT}/doc/bsp_howto/``
    565     This directory contains the source code for the*RTEMS BSP and Device Driver Development Guide*.
     460    This directory contains the source code for the*RTEMS BSP and Device Driver
     461    Development Guide*.
    566462
    567463``${RTEMS_ROOT}/doc/common/``
    568     This directory contains the source code for the files which
    569     are shared across multiple manuals in the RTEMS Documentation Set.
    570     This includes the copyright page as well as the timing
    571     tables which can be filled in on a per BSP basis in the
    572     CPU supplements.
     464    This directory contains the source code for the files which are shared
     465    across multiple manuals in the RTEMS Documentation Set.  This includes the
     466    copyright page as well as the timing tables which can be filled in on a per
     467    BSP basis in the CPU supplements.
    573468
    574469``${RTEMS_ROOT}/doc/cpu_supplement/``
    575     This directory contains the source code for the
    576     RTEMS CPU Supplement.
     470    This directory contains the source code for the RTEMS CPU Supplement.
    577471
    578472``${RTEMS_ROOT}/doc/develenv/``
    579     This directory contains the source code for the*RTEMS Development Environment Guide*.  This is
    580     the document you are currently reading.
     473    This directory contains the source code for the*RTEMS Development
     474    Environment Guide*.  This is the document you are currently reading.
    581475
    582476``${RTEMS_ROOT}/doc/filesystem/``
    583     This directory contains the source code for the*RTEMS Filesystem Design Guide*.  This manual
    584     is a continuous work in process as it attempts to
    585     capture the design of the interface between system
    586     calls and filesystem implementations as well as the
    587     information required by those implementing filesystems.
     477    This directory contains the source code for the*RTEMS Filesystem Design
     478    Guide*.  This manual is a continuous work in process as it attempts to
     479    capture the design of the interface between system calls and filesystem
     480    implementations as well as the information required by those implementing
     481    filesystems.
    588482
    589483``${RTEMS_ROOT}/doc/images/``
    590     This directory contains the source code for the graphics
    591     used in the HTML version of the RTEMS Documentation.
     484    This directory contains the source code for the graphics used in the HTML
     485    version of the RTEMS Documentation.
    592486
    593487``${RTEMS_ROOT}/doc/networking/``
    … …  
    596490``${RTEMS_ROOT}/doc/new_chapters/``
    597491    This directory contains the source code for the new documentation
    598     components which have not yet been collected into a new manual or
    599     merged into an existing document.  Currently, this primarily
    600     contains draft documentation for some portions of
    601     the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``.
     492    components which have not yet been collected into a new manual or merged
     493    into an existing document.  Currently, this primarily contains draft
     494    documentation for some portions of the facilities implemented in
     495    ``${RTEMS_ROOT}/c/src/libmisc/``.
    602496
    603497``${RTEMS_ROOT}/doc/porting/``
    … …  
    605499
    606500``${RTEMS_ROOT}/doc/posix1003.1/``
    607     This directory contains the source code for the*RTEMS POSIX 1003.1 Compliance Guide*.
     501    This directory contains the source code for the*RTEMS POSIX 1003.1
     502    Compliance Guide*.
    608503
    609504``${RTEMS_ROOT}/doc/posix_users/``
    610     This directory contains the source code for the*RTEMS POSIX API User's Guide*.  It is important to
    611     note that RTEMS' support for POSIX is a combination of
    612     functionality provided by RTEMS and the Newlib C Library
    613     so some functionality is documented by Newlib.
     505    This directory contains the source code for the*RTEMS POSIX API User's
     506    Guide*.  It is important to note that RTEMS' support for POSIX is a
     507    combination of functionality provided by RTEMS and the Newlib C Library so
     508    some functionality is documented by Newlib.
    614509
    615510``${RTEMS_ROOT}/doc/relnotes/``
    616     This directory contains the source code for a formally
    617     release notes document.  This has not been used for
    618     recent RTEMS releases.
     511    This directory contains the source code for a formally release notes
     512    document.  This has not been used for recent RTEMS releases.
    619513
    620514``${RTEMS_ROOT}/doc/started/``
    621     This directory contains the source code for the*Getting Started with RTEMS for C/C++ Users* manual.
     515    This directory contains the source code for the*Getting Started with RTEMS
     516    for C/C++ Users* manual.
    622517
    623518``${RTEMS_ROOT}/doc/tools/``
    624     This directory contains the source code for the tools
    625     used on the development host to assist in producing the
    626     RTEMS Documentation.  The most important of these tools
    627     is ``bmenu`` which generates the hierarchical node
    628     linking commands based upon chapter, section, and
    629     subsection organization.
     519    This directory contains the source code for the tools used on the
     520    development host to assist in producing the RTEMS Documentation.  The most
     521    important of these tools is ``bmenu`` which generates the hierarchical node
     522    linking commands based upon chapter, section, and subsection organization.
    630523
    631524``${RTEMS_ROOT}/doc/user/``
    632     This directory contains the source code for the *RTEMS
    633     Applications C User's Guide* which documents the Classic API.
    634 
    635 .. COMMENT: COPYRIGHT (c) 1989-2007.
    636 
    637 .. COMMENT: On-Line Applications Research Corporation (OAR).
    638 
    639 .. COMMENT: All rights reserved.
    640 
    641 
     525    This directory contains the source code for the *RTEMS Applications C
     526    User's Guide* which documents the Classic API.

  • develenv/index.rst

    rbe428d1 r9b53679  
    55===================================
    66
    7 COPYRIGHT (c) 1988 - 2015.
     7 | COPYRIGHT (c) 1988 - 2015.
     8 | On-Line Applications Research Corporation (OAR).
    89
    9 On-Line Applications Research Corporation (OAR).
     10The authors have used their best efforts in preparing this material.  These
     11efforts include the development, research, and testing of the theories and
     12programs to determine their effectiveness.  No warranty of any kind, expressed
     13or implied, with regard to the software or the material contained in this
     14document is provided.  No liability arising out of the application or use of
     15any product described in this document is assumed.  The authors reserve the
     16right to revise this material and to make changes from time to time in the
     17content hereof without obligation to notify anyone of such revision or changes.
    1018
    11 The authors have used their best efforts in preparing
    12 this material.  These efforts include the development, research,
    13 and testing of the theories and programs to determine their
    14 effectiveness.  No warranty of any kind, expressed or implied,
    15 with regard to the software or the material contained in this
    16 document is provided.  No liability arising out of the
    17 application or use of any product described in this document is
    18 assumed.  The authors reserve the right to revise this material
    19 and to make changes from time to time in the content hereof
    20 without obligation to notify anyone of such revision or changes.
     19The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
     20RTEMS, its related support components, or its documentation should be directed
     21to the Community Project hosted at http://www.rtems.org/.
    2122
    22 The RTEMS Project is hosted at http://www.rtems.org.  Any
    23 inquiries concerning RTEMS, its related support components, or its
    24 documentation should be directed to the Community Project hosted athttp://www.rtems.org.
     23.. topic:: RTEMS Online Resources
    2524
    26 Any inquiries for commercial services including training, support, custom
    27 development, application development assistance should be directed tohttp://www.rtems.com.
    28 
    29 
    30 Table of Contents
    31 -----------------
    32 
    33 .. toctree::
    34 
    35         introduction
    36 
     25  ================  =============================
     26  Home              https://www.rtems.org/
     27  Developers        https://devel.rtems.org/
     28  Documentation     https://docs.rtems.org/
     29  Bug Reporting     https://devel.rtems.org/query
     30  Mailing Lists     https://lists.rtems.org/
     31  Git Repositories  https://git.rtems.org/
     32  ================  =============================
    3733
    3834.. toctree::
    … …  
    4036        :numbered:
    4137
    42 
     38        introduction
    4339        directory
    4440        sample
    … …  
    4642        command
    4743
    48 
    4944*       :ref:`genindex`
    5045*       :ref:`search`

  • develenv/introduction.rst

    rbe428d1 r9b53679  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1989-2010.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37============
    … …  
    59============
    610
    7 This document describes the RTEMS development
    8 environment.  Discussions are provided for the following topics:
     11This document describes the RTEMS development environment.  Discussions are
     12provided for the following topics:
    913
    1014- the directory structure used by RTEMS,
    1115
    12 - usage of the GNU Make utility within the RTEMS
    13   development environment,
     16- usage of the GNU Make utility within the RTEMS development environment,
    1417
    1518- sample applications, and
    … …  
    1720- the RTEMS specific utilities.
    1821
    19 RTEMS was designed as a reusable software component.
    20 Highly reusable software such as RTEMS is typically distributed
    21 in the form of source code without providing any support tools.
    22 RTEMS is the foundation for a complex family of facilities
    23 including board support packages, device drivers, and support
    24 libraries.  The RTEMS Development Environment is not a CASE
    25 tool.  It is a collection of tools designed to reduce the
    26 complexity of using and enhancing the RTEMS family.  Tools are
    27 provided which aid in the management of the development,
    28 maintenance, and usage of RTEMS, its run-time support
    29 facilities, and applications which utilize the executive.
     22RTEMS was designed as a reusable software component.  Highly reusable software
     23such as RTEMS is typically distributed in the form of source code without
     24providing any support tools.  RTEMS is the foundation for a complex family of
     25facilities including board support packages, device drivers, and support
     26libraries.  The RTEMS Development Environment is not a CASE tool.  It is a
     27collection of tools designed to reduce the complexity of using and enhancing
     28the RTEMS family.  Tools are provided which aid in the management of the
     29development, maintenance, and usage of RTEMS, its run-time support facilities,
     30and applications which utilize the executive.
    3031
    31 A key component of the RTEMS development environment
    32 is the GNU family of free tools.  This is  robust set of
    33 development and POSIX compatible tools for which source code is
    34 freely available.  The primary compilers, assemblers, linkers,
    35 and make utility used by the RTEMS development team are the GNU
    36 tools.  They are highly portable supporting a wide variety of
    37 host computers and, in the case of the development tools, a wide
    38 variety of target processors.
     32A key component of the RTEMS development environment is the GNU family of free
     33tools.  This is robust set of development and POSIX compatible tools for which
     34source code is freely available.  The primary compilers, assemblers, linkers,
     35and make utility used by the RTEMS development team are the GNU tools.  They
     36are highly portable supporting a wide variety of host computers and, in the
     37case of the development tools, a wide variety of target processors.
    3938
    40 It is recommended that the RTEMS developer become
    41 familiar with the RTEMS Development Environment before
    42 proceeding with any modifications to the executive source tree.
    43 The source code for the executive is very modular and source
    44 code is divided amongst directories based upon functionality as
    45 well as dependencies on CPU and target board.  This organization
    46 is aimed at isolating and minimizing non-portable code.  This
    47 has the immediate result that adding support for a new CPU or
    48 target board requires very little "wandering" around the source
    49 tree.
    50 
    51 .. COMMENT: COPYRIGHT (c) 1989-2010.
    52 
    53 .. COMMENT: On-Line Applications Research Corporation (OAR).
    54 
    55 .. COMMENT: All rights reserved.
    56 
     39It is recommended that the RTEMS developer become familiar with the RTEMS
     40Development Environment before proceeding with any modifications to the
     41executive source tree.  The source code for the executive is very modular and
     42source code is divided amongst directories based upon functionality as well as
     43dependencies on CPU and target board.  This organization is aimed at isolating
     44and minimizing non-portable code.  This has the immediate result that adding
     45support for a new CPU or target board requires very little "wandering" around
     46the source tree.

  • develenv/sample.rst

    rbe428d1 r9b53679  
    77============
    88
    9 The RTEMS source distribution includes a set of sample applications
    10 that are located in the ``${RTEMS_ROOT}/testsuites/samples/``
    11 directory.  These applications are intended to illustrate the
    12 basic format of RTEMS single and multiple processor
    13 applications and the use of some features.  In addition, these
    14 relatively simple applications can be used to test locally
    15 developed board support packages and device drivers as they
    16 exercise a critical subset of RTEMS functionality that is often
    17 broken in new BSPs.
    18 
    19 Some of the following sample applications will be covered in
    20 more detail in subsequent sections:
     9The RTEMS source distribution includes a set of sample applications that are
     10located in the ``${RTEMS_ROOT}/testsuites/samples/`` directory.  These
     11applications are intended to illustrate the basic format of RTEMS single and
     12multiple processor applications and the use of some features.  In addition,
     13these relatively simple applications can be used to test locally developed
     14board support packages and device drivers as they exercise a critical subset of
     15RTEMS functionality that is often broken in new BSPs.
     16
     17Some of the following sample applications will be covered in more detail in
     18subsequent sections:
    2119
    2220*Hello World*
    23     The RTEMS Hello World test is provided in
    24     the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``.
    25     This test is helpful when testing new RTEMS development environment.
     21    The RTEMS Hello World test is provided in the subdirectory
     22    ``${RTEMS_ROOT}/testsuites/samples/hello/``.  This test is helpful when
     23    testing new RTEMS development environment.
    2624
    2725*Clock Tick*
    28     The ``${RTEMS_ROOT}/testsuites/samples/ticker/``
    29     subdirectory provides a test for verification of clock chip
    30     device drivers of BSPs.
     26    The ``${RTEMS_ROOT}/testsuites/samples/ticker/`` subdirectory provides a
     27    test for verification of clock chip device drivers of BSPs.
    3128
    3229*Base Single Processor*
    33     A simple single processor test similar to those in the
    34     single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
     30    A simple single processor test similar to those in the single processor
     31    test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
    3532
    3633*Base Multiple Processor*
    37     A simple two node multiprocessor test capable of testing an newly
    38     developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
     34    A simple two node multiprocessor test capable of testing an newly developed
     35    MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
    3936
    4037*Capture*
    41     The RTEMS Capture test is provided in
    42     the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``.
    43     This is an interactive test which demonstrates the capabilities
    44     of the RTEMS Capture Engine.  It includes a few test threads
    45     which generate interesting execution patterns.  Look at the
    46     file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
     38    The RTEMS Capture test is provided in the subdirectory
     39    ``${RTEMS_ROOT}/testsuites/samples/capture/``.  This is an interactive test
     40    which demonstrates the capabilities of the RTEMS Capture Engine.  It
     41    includes a few test threads which generate interesting execution patterns.
     42    Look at the file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
    4743    for a sample session.
    4844
    4945*Constructor/Destructor C++ Test*
    50     The ``${RTEMS_ROOT}/testsuites/samples/cdtest/``
    51     subdirectory provides a simple C++ application using
    52     constructors and destructors.  It is only built when
    53     C++ is enabled and its primary purpose is to demonstrate
    54     that global constructors and destructors work.  Since this
    55     requires that the linker script for your BSP be correct, this is
    56     an important test.
     46    The ``${RTEMS_ROOT}/testsuites/samples/cdtest/`` subdirectory provides a
     47    simple C++ application using constructors and destructors.  It is only
     48    built when C++ is enabled and its primary purpose is to demonstrate that
     49    global constructors and destructors work.  Since this requires that the
     50    linker script for your BSP be correct, this is an important test.
    5751
    5852*File IO*
    59     The RTEMS File IO test is provided in
    60     the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``.
    61     This is an interactive test which allows the user to interact with
    62     an ATA/IDE device.  It will read the partition table and allow the
    63     user to dynamically mount one of the FAT32 partitions it finds.
    64     Commands are also provided to write and read files on the disk.
     53    The RTEMS File IO test is provided in the subdirectory
     54    ``${RTEMS_ROOT}/testsuites/samples/fileio/``.  This is an interactive test
     55    which allows the user to interact with an ATA/IDE device.  It will read the
     56    partition table and allow the user to dynamically mount one of the FAT32
     57    partitions it finds.  Commands are also provided to write and read files on
     58    the disk.
    6559
    6660*IO Stream*
    67     The RTEMS IO Stream test is provided in
    68     the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``.
    69     This test is a simple C++ application which demonstrates that
    70     C++ iostreams are functional. This requires that the RTEMS C++
    71     run-time support is functioning properly.  This test is only
    72     build when C++ is enabled.
     61    The RTEMS IO Stream test is provided in the subdirectory
     62    ``${RTEMS_ROOT}/testsuites/samples/iostream/``.  This test is a simple C++
     63    application which demonstrates that C++ iostreams are functional. This
     64    requires that the RTEMS C++ run-time support is functioning properly.  This
     65    test is only build when C++ is enabled.
    7366
    7467*Network Loopback Test*
    75     The ``${RTEMS_ROOT}/testsuites/samples/loopback/``
    76     directory contains a sample test that demonstrates the use of
    77     sockets and the loopback network device.  It does not require
    78     the presence of network hardware in order to run.
    79     It is only built if RTEMS was configured with networking enabled.
     68    The ``${RTEMS_ROOT}/testsuites/samples/loopback/`` directory contains a
     69    sample test that demonstrates the use of sockets and the loopback network
     70    device.  It does not require the presence of network hardware in order to
     71    run.  It is only built if RTEMS was configured with networking enabled.
    8072
    8173*Minimum Size Test*
    82     The directory``${RTEMS_ROOT}/testsuites/samples/minimum/``
    83     contains a simple RTEMS program that results in a non-functional
    84     executable.  It is intended to show the size of a minimum footprint
    85     application based upon the current RTEMS configuration.
     74    The directory ``${RTEMS_ROOT}/testsuites/samples/minimum/`` contains a
     75    simple RTEMS program that results in a non-functional executable.  It is
     76    intended to show the size of a minimum footprint application based upon the
     77    current RTEMS configuration.
    8678
    8779*Nanoseconds*
    88     The RTEMS Nanoseconds test is provided in
    89     the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``.
    90     This test demonstrates that the BSP has support for nanosecond
    91     timestamp granularity.  It prints the time of day and uptime multiple
    92     times as quickly as possible.  It should be possible from the output
    93     to determine if your BSP has nanosecond accurate clock support
    94     and it is functional.
     80
     81    The RTEMS Nanoseconds test is provided in the subdirectory
     82    ``${RTEMS_ROOT}/testsuites/samples/nsecs/``.  This test demonstrates that
     83    the BSP has support for nanosecond timestamp granularity.  It prints the
     84    time of day and uptime multiple times as quickly as possible.  It should be
     85    possible from the output to determine if your BSP has nanosecond accurate
     86    clock support and it is functional.
    9587
    9688*Paranoia Floating Point Test*
    97     The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/``
    98     contains the public domain floating point and math library test.
     89    The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/`` contains the
     90    public domain floating point and math library test.
    9991
    10092*Point-to-Point Protocol Daemon*
    101     The RTEMS Point-to-Point Protocol Daemon test is provided in
    102     the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``.
    103     This test primarily serves as the baseline for a user application
    104     using the PPP protocol.
     93    The RTEMS Point-to-Point Protocol Daemon test is provided in the
     94    subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``.  This test
     95    primarily serves as the baseline for a user application using the PPP
     96    protocol.
    10597
    10698*Unlimited Object Allocation*
    107     The ``${RTEMS_ROOT}/testsuites/samples/unlimited/``
    108     directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS.
    109 
    110 The sample tests are written using the Classic API so the reader
    111 should be familiar with the terms used and
    112 material presented in the *RTEMS Applications Users Guide*.
     99    The ``${RTEMS_ROOT}/testsuites/samples/unlimited/`` directory contains a
     100    sample test that demonstrates the use of the*unlimited* object allocation
     101    configuration option to RTEMS.
     102
     103The sample tests are written using the Classic API so the reader should be
     104familiar with the terms used and material presented in the *RTEMS Applications
     105Users Guide*.
    113106
    114107Hello World
    … …  
    116109
    117110This sample application is in the following directory:
    118 .. code:: c
     111
     112.. code-block:: c
    119113
    120114    ${RTEMS_ROOT}/testsuites/samples/hello/
    121115
    122 It provides a rudimentary test of the BSP start up
    123 code and the console output routine.  The C version of this
    124 sample application uses the printf function from the RTEMS
    125 Standard C Library to output messages.   The Ada version of this
    126 sample uses the TEXT_IO package to output the hello messages.
    127 The following messages are printed:
    128 .. code:: c
    129 
    130     *** HELLO WORLD TEST \***
     116It provides a rudimentary test of the BSP start up code and the console output
     117routine.  The C version of this sample application uses the printf function
     118from the RTEMS Standard C Library to output messages.  The Ada version of this
     119sample uses the TEXT_IO package to output the hello messages.  The following
     120messages are printed:
     121
     122.. code-block:: c
     123
     124    *** HELLO WORLD TEST ***
    131125    Hello World
    132     \*** END OF HELLO WORLD TEST \***
    133 
    134 These messages are printed from the application's
    135 single initialization task.  If the above messages are not
    136 printed correctly, then either the BSP start up code or the
    137 console output routine is not operating properly.
     126    *** END OF HELLO WORLD TEST ***
     127
     128These messages are printed from the application's single initialization task.
     129If the above messages are not printed correctly, then either the BSP start up
     130code or the console output routine is not operating properly.
    138131
    139132Clock Tick
    … …  
    141134
    142135This sample application is in the following directory:
    143 .. code:: c
     136
     137.. code-block:: c
    144138
    145139    ${RTEMS_ROOT}/testsuites/samples/ticker/
    146140
    147 This application is designed as a simple test of the
    148 clock tick device driver.  In addition, this application also
    149 tests the printf function from the RTEMS Standard C Library by
    150 using it to output the following messages:
    151 .. code:: c
    152 
    153     *** CLOCK TICK TEST \***
     141This application is designed as a simple test of the clock tick device driver.
     142In addition, this application also tests the printf function from the RTEMS
     143Standard C Library by using it to output the following messages:
     144
     145.. code-block:: c
     146
     147    *** CLOCK TICK TEST ***
    154148    TA1 - tm_get - 09:00:00   12/31/1988
    155149    TA2 - tm_get - 09:00:00   12/31/1988
    … …  
    166160    TA2 - tm_get - 09:00:30   12/31/1988
    167161    TA3 - tm_get - 09:00:30   12/31/1988
    168     \*** END OF CLOCK TICK TEST \***
    169 
    170 The clock tick sample application utilizes a single
    171 initialization task and three copies of the single application
    172 task.  The initialization task prints the test herald, sets the
    173 time and date, and creates and starts the three application
    174 tasks before deleting itself.  The three application tasks
    175 generate the rest of the output.  Every five seconds, one or
    176 more of the tasks will print the current time obtained via the
    177 tm_get directive.  The first task, TA1, executes every five
    178 seconds, the second task, TA2, every ten seconds, and the third
    179 task, TA3, every fifteen seconds. If the time printed does not
    180 match the above output, then the clock device driver is not
    181 operating properly.
     162    *** END OF CLOCK TICK TEST ***
     163
     164The clock tick sample application utilizes a single initialization task and
     165three copies of the single application task.  The initialization task prints
     166the test herald, sets the time and date, and creates and starts the three
     167application tasks before deleting itself.  The three application tasks generate
     168the rest of the output.  Every five seconds, one or more of the tasks will
     169print the current time obtained via the tm_get directive.  The first task, TA1,
     170executes every five seconds, the second task, TA2, every ten seconds, and the
     171third task, TA3, every fifteen seconds. If the time printed does not match the
     172above output, then the clock device driver is not operating properly.
    182173
    183174Base Single Processor Application
    … …  
    185176
    186177This sample application is in the following directory:
    187 .. code:: c
     178
     179.. code-block:: c
    188180
    189181    ${RTEMS_ROOT}/testsuites/samples/base_sp/
    190182
    191 It provides a framework from which a single processor
    192 RTEMS application can be developed. The use of the task argument
    193 is illustrated.  This sample application uses the printf
    194 function from the RTEMS Standard C Library or TEXT_IO functions
    195 when using the Ada version to output the following messages:
    196 .. code:: c
    197 
    198     *** SAMPLE SINGLE PROCESSOR APPLICATION \***
     183It provides a framework from which a single processor RTEMS application can be
     184developed. The use of the task argument is illustrated.  This sample
     185application uses the printf function from the RTEMS Standard C Library or
     186TEXT_IO functions when using the Ada version to output the following messages:
     187
     188.. code-block:: c
     189
     190    *** SAMPLE SINGLE PROCESSOR APPLICATION ***
    199191    Creating and starting an application task
    200192    Application task was invoked with argument (0) and has id of 0x10002
    201     \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \***
    202 
    203 The first two messages are printed from the
    204 application's single initialization task.  The final messages
    205 are printed from the single application task.
     193    *** END OF SAMPLE SINGLE PROCESSOR APPLICATION ***
     194
     195The first two messages are printed from the application's single initialization
     196task.  The final messages are printed from the single application task.
    206197
    207198Base Multiple Processor Application
    … …  
    209200
    210201This sample application is in the following directory:
    211 .. code:: c
     202
     203.. code-block:: c
    212204
    213205    ${RTEMS_ROOT}/testsuites/samples/base_mp/
    214206
    215 It provides a framework from which a multiprocessor
    216 RTEMS application can be developed. This directory has a
    217 subdirectory for each node in the multiprocessor system.  The
    218 task argument is used to distinguish the node on which the
    219 application task is executed.  The first node will print the
     207It provides a framework from which a multiprocessor RTEMS application can be
     208developed. This directory has a subdirectory for each node in the
     209multiprocessor system.  The task argument is used to distinguish the node on
     210which the application task is executed.  The first node will print the
    220211following messages:
    221 .. code:: c
    222 
    223     *** SAMPLE MULTIPROCESSOR APPLICATION \***
     212
     213.. code-block:: c
     214
     215    *** SAMPLE MULTIPROCESSOR APPLICATION ***
    224216    Creating and starting an application task
    225217    This task was invoked with the node argument (1)
    226218    This task has the id of 0x10002
    227     \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
     219    *** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
    228220
    229221The second node will print the following messages:
    230 .. code:: c
    231 
    232     *** SAMPLE MULTIPROCESSOR APPLICATION \***
     222
     223.. code-block:: c
     224
     225    *** SAMPLE MULTIPROCESSOR APPLICATION ***
    233226    Creating and starting an application task
    234227    This task was invoked with the node argument (2)
    235228    This task has the id of 0x20002
    236     \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
    237 
    238 The herald is printed from the application's single
    239 initialization task on each node.  The final messages are
    240 printed from the single application task on each node.
    241 
    242 In this sample application, all source code is shared
    243 between the nodes except for the node dependent configuration
    244 files.  These files contains the definition of the node number
    245 used in the initialization of the  RTEMS Multiprocessor
    246 Configuration Table. This file is not shared because the node
    247 number field in the RTEMS Multiprocessor Configuration Table
    248 must be unique on each node.
     229    *** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
     230
     231The herald is printed from the application's single initialization task on each
     232node.  The final messages are printed from the single application task on each
     233node.
     234
     235In this sample application, all source code is shared between the nodes except
     236for the node dependent configuration files.  These files contains the
     237definition of the node number used in the initialization of the RTEMS
     238Multiprocessor Configuration Table. This file is not shared because the node
     239number field in the RTEMS Multiprocessor Configuration Table must be unique on
     240each node.
    249241
    250242Constructor/Destructor C++ Application
    … …  
    252244
    253245This sample application is in the following directory:
    254 .. code:: c
     246
     247.. code-block:: c
    255248
    256249    ${RTEMS_ROOT}/testsuites/samples/cdtest/
    257250
    258 This sample application demonstrates that RTEMS is
    259 compatible with C++ applications.  It uses constructors,
    260 destructor, and I/O stream output in testing these various
    261 capabilities.  The board support package responsible for this
    262 application must support a C++ environment.
    263 
    264 This sample application uses the printf function from
    265 the RTEMS Standard C Library to output the following messages:
    266 .. code:: c
     251This sample application demonstrates that RTEMS is compatible with C++
     252applications.  It uses constructors, destructor, and I/O stream output in
     253testing these various capabilities.  The board support package responsible for
     254this application must support a C++ environment.
     255
     256This sample application uses the printf function from the RTEMS Standard C
     257Library to output the following messages:
     258
     259.. code-block:: c
    267260
    268261    Hey I'M in base class constructor number 1 for 0x400010cc.
    269262    Hey I'M in base class constructor number 2 for 0x400010d4.
    270263    Hey I'M in derived class constructor number 3 for 0x400010d4.
    271     \*** CONSTRUCTOR/DESTRUCTOR TEST \***
     264    *** CONSTRUCTOR/DESTRUCTOR TEST ***
    272265    Hey I'M in base class constructor number 4 for 0x4009ee08.
    273266    Hey I'M in base class constructor number 5 for 0x4009ee10.
    … …  
    286279    Hey I'M in base class constructor number 4 for 0x4009ee08.
    287280    Instantiation order 5
    288     \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \***
     281    *** END OF CONSTRUCTOR/DESTRUCTOR TEST ***
    289282    Hey I'M in base class constructor number 3 for 0x400010d4.
    290283    Hey I'M in base class constructor number 2 for 0x400010d4.
    … …  
    295288
    296289This sample application is in the following directory:
    297 .. code:: c
     290
     291.. code-block:: c
    298292
    299293    ${RTEMS_ROOT}/testsuites/samples/minimum/
    300294
    301 This sample application is designed to produce the
    302 minimum code space required for any RTEMS application
    303 based upon the current RTEMS configuration and
    304 BSP.  In many situations, the bulk of this executable
    305 consists of hardware and RTEMS initialization, basic
    306 infrastructure such as malloc(), and RTEMS and
    307 hardware shutdown support.
     295This sample application is designed to produce the minimum code space required
     296for any RTEMS application based upon the current RTEMS configuration and BSP.
     297In many situations, the bulk of this executable consists of hardware and RTEMS
     298initialization, basic infrastructure such as malloc(), and RTEMS and hardware
     299shutdown support.
    308300
    309301Nanosecond Granularity Application
    … …  
    311303
    312304This sample application is in the following directory:
    313 .. code:: c
     305
     306.. code-block:: c
    314307
    315308    ${RTEMS_ROOT}/testsuites/samples/nsecs/
    316309
    317 This sample application exercises the Clock Driver
    318 for this BSP and demonstrates its ability to generate
    319 accurate timestamps.  This application does this by
    320 exercising the time subsystem in three ways:
     310This sample application exercises the Clock Driver for this BSP and
     311demonstrates its ability to generate accurate timestamps.  This application
     312does this by exercising the time subsystem in three ways:
    321313
    322314- Obtain Time of Day Twice Back to Back
    … …  
    326318- Use System Up Time to Measure Loops
    327319
    328 The following is an example of what the output of this
    329 test may appear like:
    330 .. code:: c
    331 
    332     *** NANOSECOND CLOCK TEST \***
     320The following is an example of what the output of this test may appear like:
     321
     322.. code-block:: c
     323
     324    *** NANOSECOND CLOCK TEST ***
    333325    10 iterations of getting TOD
    334326    Start: Sat Mar 24 11:15:00 2007:540000
    … …  
    374366    loop of 90000 0:156145000 0:158099000 --> 0:1954000
    375367    loop of 100000 0:160770000 0:162942000 --> 0:2172000
    376     \*** END OF NANOSECOND CLOCK TEST \***
     368    *** END OF NANOSECOND CLOCK TEST ***
    377369
    378370Paranoia Floating Point Application
    … …  
    380372
    381373This sample application is in the following directory:
    382 .. code:: c
     374
     375.. code-block:: c
    383376
    384377    ${RTEMS_ROOT}/testsuites/samples/paranoia/
    385378
    386 This sample application uses a public domain floating
    387 point and math library test to verify these capabilities of the
    388 RTEMS executive.  Deviations between actual and expected results
    389 are reported to the screen.  This is a very extensive test which
    390 tests all mathematical and number conversion functions.
    391 Paranoia is also very large and requires a long period of time
    392 to run.   Problems which commonly prevent this test from
    393 executing to completion include stack overflow and FPU exception
    394 handlers not installed.
     379This sample application uses a public domain floating point and math library
     380test to verify these capabilities of the RTEMS executive.  Deviations between
     381actual and expected results are reported to the screen.  This is a very
     382extensive test which tests all mathematical and number conversion functions.
     383Paranoia is also very large and requires a long period of time to run.
     384Problems which commonly prevent this test from executing to completion include
     385stack overflow and FPU exception handlers not installed.
    395386
    396387Network Loopback Test
    … …  
    398389
    399390This sample application is in the following directory:
    400 .. code:: c
     391
     392.. code-block:: c
    401393
    402394    ${RTEMS_ROOT}/testsuites/samples/loopback/
    403395
    404 This sample application uses the network loopback device to
    405 demonstrate the use of the RTEMS TCP/IP stack.  This sample
    406 test illustrates the basic configuration and initialization
    407 of the TCP/IP stack as well as simple socket usage.
    408 
    409 .. COMMENT: COPYRIGHT (c) 1989-2007.
    410 
    411 .. COMMENT: On-Line Applications Research Corporation (OAR).
    412 
    413 .. COMMENT: All rights reserved.
    414 
     396This sample application uses the network loopback device to demonstrate the use
     397of the RTEMS TCP/IP stack.  This sample test illustrates the basic
     398configuration and initialization of the TCP/IP stack as well as simple socket
     399usage.

  • develenv/utilities.rst

    rbe428d1 r9b53679  
    44########################
    55
    6 This section describes the additional commands
    7 available within the *RTEMS Development Environment*.  Although
    8 some of these commands are of general use, most are included to
    9 provide some capability necessary to perform a required function
    10 in the development of the RTEMS executive, one of its support
     6This section describes the additional commands available within the *RTEMS
     7Development Environment*.  Although some of these commands are of general use,
     8most are included to provide some capability necessary to perform a required
     9function in the development of the RTEMS executive, one of its support
    1110components, or an RTEMS based application.
    1211
    13 Some of the commands are implemented as C programs.
    14 However, most commands are implemented as Bourne shell scripts.
    15 Even if the current user has selected a different shell, the
    16 scripts will automatically invoke the Bourne shell during their
    17 execution lifetime.
     12Some of the commands are implemented as C programs.  However, most commands are
     13implemented as Bourne shell scripts.  Even if the current user has selected a
     14different shell, the scripts will automatically invoke the Bourne shell during
     15their execution lifetime.
    1816
    19 The commands are presented in UNIX manual page style
    20 for compatibility and convenience.  A standard set of paragraph
    21 headers were used for all of the command descriptions.  If a
    22 section contained no data, the paragraph header was omitted to
    23 conserve space.  Each of the permissible paragraph headers and
    24 their contents are described below:
     17The commands are presented in UNIX manual page style for compatibility and
     18convenience.  A standard set of paragraph headers were used for all of the
     19command descriptions.  If a section contained no data, the paragraph header was
     20omitted to conserve space.  Each of the permissible paragraph headers and their
     21contents are described below:
    2522
    2623``SYNOPSIS``
    … …  
    4845    lists any relevant commands which can be consulted
    4946
    50 Most environment variables referenced by the commands
    51 are defined for the RTEMS Development Environment during the
    52 login procedure.  During login, the user selects a default RTEMS
    53 environment through the use of the Modules package.  This tool
    54 effectively sets the environment variables to provide a
    55 consistent development environment for a specific user.
    56 Additional environment variables within the RTEMS environment
    57 were set by the system administrator during installation.  When
    58 specifying paths, a command description makes use of these
     47Most environment variables referenced by the commands are defined for the RTEMS
     48Development Environment during the login procedure.  During login, the user
     49selects a default RTEMS environment through the use of the Modules package.
     50This tool effectively sets the environment variables to provide a consistent
     51development environment for a specific user.  Additional environment variables
     52within the RTEMS environment were set by the system administrator during
     53installation.  When specifying paths, a command description makes use of these
    5954environment variables.
    6055
    61 When referencing other commands in the SEE ALSO
    62 paragraph, the following notation is used:   command(code).
    63 Where command is the name of a related command, and code is a
    64 section number.  Valid section numbers are as follows:
     56When referencing other commands in the SEE ALSO paragraph, the following
     57notation is used: command(code).  Where command is the name of a related
     58command, and code is a section number.  Valid section numbers are as follows:
    6559
    6660``1``
    … …  
    7367    a manual page from this document, the RTEMS Development Environment Guide
    7468
    75 For example, ls(1) means see the standard ls command
    76 in section 1 of the UNIX documentation.  gcc020(1G) means see
    77 the description of gcc020 in section 1 of the GNU documentation.
    78 
    79 .. COMMENT: packhex
     69For example, ``ls(1)`` means see the standard ls command in section 1 of the
     70UNIX documentation.  gcc020(1G) means see the description of gcc020 in section
     711 of the GNU documentation.
    8072
    8173packhex - Compress Hexadecimal File
    … …  
    8476**SYNOPSIS**
    8577
    86 .. code:: c
     78.. code-block:: c
    8779
    8880    packhex <source >destination
    … …  
    9082**DESCRIPTION**
    9183
    92 packhex accepts Intel Hexadecimal or Motorola Srecord
    93 on its standard input and attempts to pack as many contiguous
    94 bytes as possible into a single hexadecimal record.  Many
    95 programs output hexadecimal records which are less than 80 bytes
    96 long (for human viewing).  The overhead required by each
    97 unnecessary record is significant and packhex can often reduce
    98 the size of the download image by 20%.  packhex attempts to
    99 output records which are as long as the hexadecimal format
     84packhex accepts Intel Hexadecimal or Motorola Srecord on its standard input and
     85attempts to pack as many contiguous bytes as possible into a single hexadecimal
     86record.  Many programs output hexadecimal records which are less than 80 bytes
     87long (for human viewing).  The overhead required by each unnecessary record is
     88significant and packhex can often reduce the size of the download image by 20%.
     89packhex attempts to output records which are as long as the hexadecimal format
    10090allows.
    10191
    … …  
    10696**EXAMPLES**
    10797
    108 Assume the current directory contains the Motorola
    109 Srecord file download.sr. Then executing the command:
    110 .. code:: c
     98Assume the current directory contains the Motorola Srecord file
     99download.sr. Then executing the command:
     100
     101.. code-block:: c
    111102
    112103    packhex <download.sr >packed.sr
    113104
    114 will generate the file packed.sr which is usually
    115 smaller than download.sr.
     105will generate the file packed.sr which is usually smaller than download.sr.
    116106
    117107**CREDITS**
    118108
    119 The source for packhex first appeared in the May 1993
    120 issue of Embedded Systems magazine.  The code was downloaded
    121 from their BBS.  Unfortunately, the author's name was not
    122 provided in the listing.
    123 
    124 .. COMMENT: unhex
     109The source for packhex first appeared in the May 1993 issue of Embedded Systems
     110magazine.  The code was downloaded from their BBS.  Unfortunately, the author's
     111name was not provided in the listing.
    125112
    126113unhex - Convert Hexadecimal File into Binary Equivalent
    … …  
    129116**SYNOPSIS**
    130117
    131 .. code:: c
     118.. code-block:: c
    132119
    133     unhex \[-valF] \[-o file] \[file \[file ...] ]
     120    unhex [-valF] [-o file] [file [file ...] ]
    134121
    135122**DESCRIPTION**
    136123
    137 unhex accepts Intel Hexadecimal, Motorola Srecord, or
    138 TI 'B' records and converts them to their binary equivalent.
    139 The output may sent to standout or may be placed in a specified
    140 file with the -o option.  The designated output file may not be
    141 an input file.  Multiple input files may be specified with their
    142 outputs logically concatenated into the output file.
     124unhex accepts Intel Hexadecimal, Motorola Srecord, or TI 'B' records and
     125converts them to their binary equivalent.  The output may sent to standout or
     126may be placed in a specified file with the -o option.  The designated output
     127file may not be an input file.  Multiple input files may be specified with
     128their outputs logically concatenated into the output file.
    143129
    144130**OPTIONS**
    … …  
    150136
    151137``a base``
    152     First byte of output corresponds with base
    153     address
     138    First byte of output corresponds with base address
    154139
    155140``l``
    … …  
    164149**EXAMPLES**
    165150
    166 The following command will create a binary equivalent
    167 file for the two Motorola S record files in the specified output
    168 file binary.bin:
    169 .. code:: c
     151The following command will create a binary equivalent file for the two Motorola
     152S record files in the specified output file binary.bin:
     153
     154.. code-block:: c
    170155
    171156    unhex -o binary.bin downloadA.sr downloadB.sr
    172 
Note: See TracChangeset for help on using the changeset viewer.