summaryrefslogtreecommitdiffstats
path: root/develenv
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-10-27 16:12:50 -0700
committerChris Johns <chrisj@rtems.org>2016-10-27 16:13:03 -0700
commit9b53679540443784bc0dba6426b1a8a2da9f6b37 (patch)
treef049208fc21f94be6f5bb523789654878f3298cd /develenv
parentcommon/waf.py: Improve Sphinx version parsing to work with their git master (diff)
downloadrtems-docs-9b53679540443784bc0dba6426b1a8a2da9f6b37.tar.bz2
Fix develenv. Needs more fixes.
Diffstat (limited to 'develenv')
-rw-r--r--develenv/command.rst3
-rw-r--r--develenv/directory.rst739
-rw-r--r--develenv/index.rst59
-rw-r--r--develenv/introduction.rst74
-rw-r--r--develenv/sample.rst373
-rw-r--r--develenv/utilities.rst122
6 files changed, 603 insertions, 767 deletions
diff --git a/develenv/command.rst b/develenv/command.rst
index 46bd174..67fa271 100644
--- a/develenv/command.rst
+++ b/develenv/command.rst
@@ -4,6 +4,3 @@ Command and Variable Index
##########################
There are currently no Command and Variable Index entries.
-
-.. COMMENT: @printindex fn
-
diff --git a/develenv/directory.rst b/develenv/directory.rst
index fa4ecb4..dad27c8 100644
--- a/develenv/directory.rst
+++ b/develenv/directory.rst
@@ -1,39 +1,38 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1989-2007.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Directory Structure
###################
-The RTEMS directory structure is designed to meet
-the following requirements:
+The RTEMS directory structure is designed to meet the following requirements:
- encourage development of modular components.
-- isolate processor and target dependent code, while
- allowing as much common source code as possible to be shared
- across multiple processors and target boards.
-
-- allow multiple RTEMS users to perform simultaneous
- compilation of RTEMS and its support facilities for different
- processors and targets.
-
-The resulting directory structure has processor and
-board dependent source files isolated from generic files. When
-RTEMS is configured and built, object directories and
-an install point will be automatically created based upon
-the target CPU family and BSP selected.
-
-The placement of object files based upon the selected BSP name
-ensures that object files are not mixed across CPUs or targets.
-This in combination with the makefiles allows the specific
-compilation options to be tailored for a particular target
-board. For example, the efficiency of the memory subsystem for
-a particular target board may be sensitive to the alignment of
-data structures, while on another target board with the same
-processor memory may be very limited. For the first target, the
-options could specify very strict alignment requirements, while
-on the second the data structures could be *packed* to conserve
-memory. It is impossible to achieve this degree of flexibility
-without providing source code.
+- isolate processor and target dependent code, while allowing as much common
+ source code as possible to be shared across multiple processors and target
+ boards.
+
+- allow multiple RTEMS users to perform simultaneous compilation of RTEMS and
+ its support facilities for different processors and targets.
+
+The resulting directory structure has processor and board dependent source
+files isolated from generic files. When RTEMS is configured and built, object
+directories and an install point will be automatically created based upon the
+target CPU family and BSP selected.
+
+The placement of object files based upon the selected BSP name ensures that
+object files are not mixed across CPUs or targets. This in combination with
+the makefiles allows the specific compilation options to be tailored for a
+particular target board. For example, the efficiency of the memory subsystem
+for a particular target board may be sensitive to the alignment of data
+structures, while on another target board with the same processor memory may be
+very limited. For the first target, the options could specify very strict
+alignment requirements, while on the second the data structures could be
+*packed* to conserve memory. It is impossible to achieve this degree of
+flexibility without providing source code.
The RTEMS source tree is organized based on the following variables:
@@ -47,15 +46,11 @@ The RTEMS source tree is organized based on the following variables:
- target board.
-Each of the following sections will describe the
-contents of the directories in the RTEMS source
-tree. The top of the tree will be referenced
-as ``${RTEMS_ROOT}`` in this discussion.
-
-.. COMMENT: Top Level Tree
+Each of the following sections will describe the contents of the directories in
+the RTEMS source tree. The top of the tree will be referenced as
+``${RTEMS_ROOT}`` in this discussion.
-.. COMMENT: @ifset use-ascii
-.. code:: c
+.. code-block:: c
rtems-VERSION
|
@@ -63,232 +58,192 @@ as ``${RTEMS_ROOT}`` in this discussion.
| | | | | | | | |
aclocal automake c contrib cpukit doc make testsuites tools
-.. COMMENT: @end ifset
-
``${RTEMS_ROOT}/aclocal/``
- This directory contains the custom M4 macros which are available to
- the various GNU autoconf ``configure.ac`` scripts throughout
- the RTEMS source tree. GNU autoconf interprets ``configure.ac``
- files to produce the ``configure`` files used to tailor
- RTEMS build for a particular host and target environment. The
- contents of this directory will not be discussed further in this
- document.
+ This directory contains the custom M4 macros which are available to the
+ various GNU autoconf ``configure.ac`` scripts throughout the RTEMS source
+ tree. GNU autoconf interprets ``configure.ac`` files to produce the
+ ``configure`` files used to tailor RTEMS build for a particular host and
+ target environment. The contents of this directory will not be discussed
+ further in this document.
``${RTEMS_ROOT}/automake/``
- This directory contains the custom GNU automake fragments
- which are used to support the various ``Makefile.am``
- files throughout the RTEMS source tree. The
- contents of this directory will not be discussed
- further in this document.
+ This directory contains the custom GNU automake fragments which are used to
+ support the various ``Makefile.am`` files throughout the RTEMS source tree.
+ The contents of this directory will not be discussed further in this
+ document.
``${RTEMS_ROOT}/c/``
- This directory is the root of the portions of the RTEMS source
- tree which must be built tailored for a particular CPU model
- or BSP. The contents of this directory will be discussed
- in the `c/ Directory`_ section.
+ This directory is the root of the portions of the RTEMS source tree which
+ must be built tailored for a particular CPU model or BSP. The contents of
+ this directory will be discussed in the `c/ Directory`_ section.
``${RTEMS_ROOT}/contrib/``
- This directory contains contributed support software. Currently
- this directory contains the RPM specifications for cross-compilers
- hosted on GNU/Linux that target various operating systems
- including MinGW, Cygwin, FreeBSD, and Solaris. The
- cross-compilers produced using these specifications are then
- used in a Canadian cross build procedure to produce the various
- RTEMS toolsets on a GNU/Linux host.
- This directory also contains RPM specifications for the
- prebuilt cross-compilation toolsets provided by the
- RTEMS project. There are separate subdirectories
- for each of the components in the RTEMS Cross Compilation
- Environment unde the ``contrib/crossrpms/`` directory.
- This directory is configured, built, and installed separately
- from the RTEMS executive and tests. This directory will not
- be discussed further in this document.
+ This directory contains contributed support software. Currently this
+ directory contains the RPM specifications for cross-compilers hosted on
+ GNU/Linux that target various operating systems including MinGW, Cygwin,
+ FreeBSD, and Solaris. The cross-compilers produced using these
+ specifications are then used in a Canadian cross build procedure to produce
+ the various RTEMS toolsets on a GNU/Linux host. This directory also
+ contains RPM specifications for the prebuilt cross-compilation toolsets
+ provided by the RTEMS project. There are separate subdirectories for each
+ of the components in the RTEMS Cross Compilation Environment unde the
+ ``contrib/crossrpms/`` directory. This directory is configured, built, and
+ installed separately from the RTEMS executive and tests. This directory
+ will not be discussed further in this document.
``${RTEMS_ROOT}/cpukit/``
- This directory is the root for all of the "multilib'able"
- portions of RTEMS. This is a GNU way of saying the
- contents of this directory can be compiled like the
- C Library (``libc.a``) and the functionality is
- neither CPU model nor BSP specific. The source code
- for most RTEMS services reside under this directory.
- The contents of this directory will be discussed
- in the `CPU Kit Directory`_ section.
+ This directory is the root for all of the "multilib'able" portions of
+ RTEMS. This is a GNU way of saying the contents of this directory can be
+ compiled like the C Library (``libc.a``) and the functionality is neither
+ CPU model nor BSP specific. The source code for most RTEMS services reside
+ under this directory. The contents of this directory will be discussed in
+ the `CPU Kit Directory`_ section.
``${RTEMS_ROOT}/doc/``
- This directory is the root for all RTEMS documentation.
- The source for RTEMS is written in GNU TeXinfo and
- used to produce HTML, PDF, and "info" files.
- The RTEMS documentation is configured, built,
- and installed separately from the RTEMS executive and tests.
- The contents of this directory will be discussed
- in the `Documentation Directory`_ section.
+ This directory is the root for all RTEMS documentation. The source for
+ RTEMS is written in GNU TeXinfo and used to produce HTML, PDF, and "info"
+ files. The RTEMS documentation is configured, built, and installed
+ separately from the RTEMS executive and tests. The contents of this
+ directory will be discussed in the `Documentation Directory`_ section.
``${RTEMS_ROOT}/make/``
- This directory contains files which support the
- RTEMS Makefile's. From a user's perspective, the
- most important parts are found in the ``custom/``
- subdirectory. Each ".cfg" file in this directory
- is associated with a specific BSP and describes
- the CPU model, compiler flags, and procedure to
- produce an executable for the target board.
- These files are described in detail in the*RTEMS BSP and Device Driver Development Guide*
- and will not be discussed further in this document.
+ This directory contains files which support the RTEMS Makefile's. From a
+ user's perspective, the most important parts are found in the ``custom/``
+ subdirectory. Each ".cfg" file in this directory is associated with a
+ specific BSP and describes the CPU model, compiler flags, and procedure to
+ produce an executable for the target board. These files are described in
+ detail in the*RTEMS BSP and Device Driver Development Guide* and will not
+ be discussed further in this document.
``${RTEMS_ROOT}/testsuites/``
- This directory contains the test suites for the
- various RTEMS APIs and support libraries. The
- contents of this directory are discussed in the `testsuites/ Test Suites`_ section.
+ This directory contains the test suites for the various RTEMS APIs and
+ support libraries. The contents of this directory are discussed in the
+ `testsuites/ Test Suites`_ section.
``${RTEMS_ROOT}/tools/``
- This directory contains RTEMS specific support utilities which
- execute on the development host. These utilities are divided
- into subdirectories based upon whether they are used in the process
- of building RTEMS and applications, are CPU specific, or are
- used to assist in updating the RTEMS source tree and applications.
- The support utilities used in the process of building RTEMS are
- described in `RTEMS Specific Utilities`_. These are the
- only components of this subtree that will be discussed in this
- document.
-
-.. COMMENT: c/ Directions
+ This directory contains RTEMS specific support utilities which execute on
+ the development host. These utilities are divided into subdirectories
+ based upon whether they are used in the process of building RTEMS and
+ applications, are CPU specific, or are used to assist in updating the RTEMS
+ source tree and applications. The support utilities used in the process of
+ building RTEMS are described in `RTEMS Specific Utilities`_. These are the
+ only components of this subtree that will be discussed in this document.
c/ Directory
============
-The ``${RTEMS_ROOT}/c/`` directory was formerly
-the root directory of all RTEMS source code. At this time, it contains
-the root directory for only those RTEMS components
-which must be compiled or linked in a way that is specific to a
-particular CPU model or board. This directory contains the
-following subdirectories:
+The ``${RTEMS_ROOT}/c/`` directory was formerly the root directory of all RTEMS
+source code. At this time, it contains the root directory for only those RTEMS
+components which must be compiled or linked in a way that is specific to a
+particular CPU model or board. This directory contains the following
+subdirectories:
``${RTEMS_ROOT}/c/src/``
- This directory is logically the root for the RTEMS components
- which are CPU model or board dependent. Thus this directory
- is the root for the BSPs and the Ada Test Suites as well
- as CPU model and BSP dependent libraries. The contents of
- this directory are discussed in the `c/src/ Directory`_ section.
-
-.. COMMENT: c/src/ Directory
+ This directory is logically the root for the RTEMS components which are CPU
+ model or board dependent. Thus this directory is the root for the BSPs and
+ the Ada Test Suites as well as CPU model and BSP dependent libraries. The
+ contents of this directory are discussed in the `c/src/ Directory`_
+ section.
c/src/ Directory
----------------
-As mentioned previously, this directory is logically
-the root for the RTEMS components
-which are CPU model or board dependent. The
-following is a list of the subdirectories in this
-directory and a description of each.
+As mentioned previously, this directory is logically the root for the RTEMS
+components which are CPU model or board dependent. The following is a list of
+the subdirectories in this directory and a description of each.
``${RTEMS_ROOT}/c/src/aclocal/``
- This directory contains the custom M4 macros which are available to
- the various GNU autoconf ``configure.ac`` scripts throughout
- this portion of the RTEMS source tree. GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used
- to tailor RTEMS build for a particular host and target environment. The
- contents of this directory will not be discussed further in this
- document.
+ This directory contains the custom M4 macros which are available to the
+ various GNU autoconf ``configure.ac`` scripts throughout this portion of
+ the RTEMS source tree. GNU autoconf interprets``configure.ac`` files to
+ produce the ``configure`` files used to tailor RTEMS build for a particular
+ host and target environment. The contents of this directory will not be
+ discussed further in this document.
``${RTEMS_ROOT}/c/src/ada/``
- This directory contains the Ada95 language bindings to the
- RTEMS Classic API.
+ This directory contains the Ada95 language bindings to the RTEMS Classic
+ API.
``${RTEMS_ROOT}/c/src/ada-tests/``
- This directory contains the test suite for the Ada
- language bindings to the Classic API.
+ This directory contains the test suite for the Ada language bindings to the
+ Classic API.
``${RTEMS_ROOT}/c/src/automake/``
- This directory contains files which are "Makefile fragments."
- They are included as required by the various ``Makefile.am``
- files throughout this portion of the RTEMS source tree.
+ This directory contains files which are "Makefile fragments." They are
+ included as required by the various ``Makefile.am`` files throughout this
+ portion of the RTEMS source tree.
``${RTEMS_ROOT}/c/src/lib/``
- This directory contains the directories ``libbsp/``
- and ``libcpu/`` which contain the source code for
- the Board Support Packages (BSPs) and CPU Model
- specific source code for RTEMS.
- The ``libbsp/`` is organized based upon the CPU
- family and boards BSPs. The contents of ``libbsp/``
- are discussed briefly in `c/src/lib/libbsp BSP Directory`_
- and presented in detail in the*RTEMS BSP and Device Driver Development Guide*.
- The ``libcpu/`` directory is also organized by
- CPU family with further divisions based upon CPU
- model and features that are shared across CPU models
- such as caching and DMA.
+ This directory contains the directories ``libbsp/`` and ``libcpu/`` which
+ contain the source code for the Board Support Packages (BSPs) and CPU Model
+ specific source code for RTEMS. The ``libbsp/`` is organized based upon
+ the CPU family and boards BSPs. The contents of ``libbsp/`` are discussed
+ briefly in `c/src/lib/libbsp BSP Directory`_ and presented in detail in
+ the*RTEMS BSP and Device Driver Development Guide*. The ``libcpu/``
+ directory is also organized by CPU family with further divisions based upon
+ CPU model and features that are shared across CPU models such as caching
+ and DMA.
``${RTEMS_ROOT}/c/src/libchip/``
- This directory contains device drivers for various
- peripheral chips which are designed to be CPU and
- board dependent. This directory contains a variety
- of drivers for serial devices, network interface
- controllers, shared memory and real-time clocks.
+ This directory contains device drivers for various peripheral chips which
+ are designed to be CPU and board dependent. This directory contains a
+ variety of drivers for serial devices, network interface controllers,
+ shared memory and real-time clocks.
``${RTEMS_ROOT}/c/src/librtems++/``
- This directory contains C++ classes which map to the RTEMS
- Classic API.
+ This directory contains C++ classes which map to the RTEMS Classic API.
``${RTEMS_ROOT}/c/src/make/``
- This directory is used to generate the bulk of the supporting
- rules files which are installed as part of the Application Makefiles.
- This file contains settings for various Makefile variables to
- tailor them to the particular CPU model and BSP configured.
+ This directory is used to generate the bulk of the supporting rules files
+ which are installed as part of the Application Makefiles. This file
+ contains settings for various Makefile variables to tailor them to the
+ particular CPU model and BSP configured.
``${RTEMS_ROOT}/c/src/nfsclient/``
- This directory contains a Network File System (NFS) client
- for RTEMS. With this file system, a user's application can
- access files on a remote computer.
+ This directory contains a Network File System (NFS) client for RTEMS. With
+ this file system, a user's application can access files on a remote
+ computer.
``${RTEMS_ROOT}/c/src/optman/``
- This directory contains stubs for the RTEMS Classic API
- Managers which are considered optional and whose use
- may be explicitly forbidden by an application. All of the
- directive implementations in this Optional Managers
- return ``E_NOTCONFIGURED``.
+ This directory contains stubs for the RTEMS Classic API Managers which are
+ considered optional and whose use may be explicitly forbidden by an
+ application. All of the directive implementations in this Optional
+ Managers return ``E_NOTCONFIGURED``.
``${RTEMS_ROOT}/c/src/support/``
- This directory exists solely to generate the RTEMS
- version string which includes the RTEMS version,
- CPU architecture, CPU model, and BSP name.
+ This directory exists solely to generate the RTEMS version string which
+ includes the RTEMS version, CPU architecture, CPU model, and BSP name.
``${RTEMS_ROOT}/c/src/wrapup/``
- This directory is responsible for taking the individual
- libraries and objects built in each of the components
- in the RTEMS source tree and bundling them together to form
- the single RTEMS library ``librtemsbsp.a``. This
- library contains all BSP and CPU model specific software.
-
-.. COMMENT: c/src/lib/libbsp BSP Directory
+ This directory is responsible for taking the individual libraries and
+ objects built in each of the components in the RTEMS source tree and
+ bundling them together to form the single RTEMS library ``librtemsbsp.a``.
+ This library contains all BSP and CPU model specific software.
c/src/lib/libbsp BSP Directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The "libbsp" directory contains a directory for each CPU family supported
-by RTEMS. Beneath each CPU directory is a directory for each BSP for that
+The "libbsp" directory contains a directory for each CPU family supported by
+RTEMS. Beneath each CPU directory is a directory for each BSP for that
processor family.
-.. COMMENT: Tree 7 - C BSP Library
-
-The "libbsp" directory provides all the BSPs provided with this
-release of the RTEMS executive. The subdirectories are
-divided, as discussed previously, based on specific processor
-family, then further broken down into specific target board
-environments. The "no_cpu" subdirectory provides a starting point
-template BSP which can be used to develop a specific BSP for an
-unsupported target board. The files in this subdirectory may aid
-in preliminary testing of the RTEMS development environment that has
-been built for no particular target in mind.
-
-Below each CPU dependent directory is a directory for each target BSP
-supported in this release.
+The "libbsp" directory provides all the BSPs provided with this release of the
+RTEMS executive. The subdirectories are divided, as discussed previously,
+based on specific processor family, then further broken down into specific
+target board environments. The "no_cpu" subdirectory provides a starting point
+template BSP which can be used to develop a specific BSP for an unsupported
+target board. The files in this subdirectory may aid in preliminary testing of
+the RTEMS development environment that has been built for no particular target
+in mind.
-Each BSP provides the modules which comprise an RTEMS BSP. The
-modules are separated into the subdirectories "clock", "console",
-"include", "shmsupp", "startup", and "timer" as shown in the following
-figure:
+Below each CPU dependent directory is a directory for each target BSP supported
+in this release.
-.. COMMENT: Tree 8 - Each BSP
+Each BSP provides the modules which comprise an RTEMS BSP. The modules are
+separated into the subdirectories "clock", "console", "include", "shmsupp",
+"startup", and "timer" as shown in the following figure:
-.. COMMENT: @ifset use-ascii
-.. code:: c
+.. code-block:: c
Each BSP
|
@@ -296,346 +251,276 @@ figure:
| | | | | |
clock console include shmsupp startup timer
-.. COMMENT: @end ifset
-
-.. COMMENT: CPU Kit Directory
-
CPU Kit Directory
=================
-.. COMMENT: The @code{cpukit/} directory structure is as follows:
+The @code{cpukit/} directory structure is as follows:
-.. COMMENT: CPU Kit Tree
+.. code-block:: c
-.. COMMENT: @ifset use-ascii
-
-.. COMMENT: @example
-
-.. COMMENT: @group
-
-.. COMMENT: cpukit
-
-.. COMMENT: |
-
-.. COMMENT: +-+-+-+-+
-
-.. COMMENT: | | | | |
-
-.. COMMENT: posix rtems sapi score wrapup
-
-.. COMMENT: @end group
-
-.. COMMENT: @end example
-
-.. COMMENT: @end ifset
+ cpukit
+ |
+ +-----------+----------+-----------+----------+
+ | | | | |
+ posix rtems sapi score wrapup
-The ``cpukit/`` directory contains a set of subdirectories which
-contains the source files comprising the executive portion of
-the RTEMS development environment as well as portable support
-libraries such as support for the C Library and filesystems.
-The API specific and "SuperCore" (e.g. ``score/`` directory)
-source code files are separated into distinct directory trees.
+The ``cpukit/`` directory contains a set of subdirectories which contains the
+source files comprising the executive portion of the RTEMS development
+environment as well as portable support libraries such as support for the C
+Library and filesystems. The API specific and "SuperCore" (e.g. ``score/``
+directory) source code files are separated into distinct directory trees.
-The following is a description of each of the subdirectories
-under ``cpukit/``:
+The following is a description of each of the subdirectories under ``cpukit/``:
``${RTEMS_ROOT}/cpukit/aclocal/``
- This directory contains the custom M4 macros which are available to
- the various GNU autoconf ``configure.ac`` scripts throughout
- the CPU Kit portion of the RTEMS source tree.
- GNU autoconf interprets ``configure.ac``
- files to produce the ``configure`` files used to tailor
- RTEMS build for a particular host and target environment. The
- contents of this directory will not be discussed further in this
- document.
+ This directory contains the custom M4 macros which are available to the
+ various GNU autoconf ``configure.ac`` scripts throughout the CPU Kit
+ portion of the RTEMS source tree. GNU autoconf interprets ``configure.ac``
+ files to produce the ``configure`` files used to tailor RTEMS build for a
+ particular host and target environment. The contents of this directory
+ will not be discussed further in this document.
``${RTEMS_ROOT}/cpukit/automake/``
- This directory contains files which are "Makefile fragments."
- They are included as required by the various ``Makefile.am``
- files throughout the CPU Kit portion of the RTEMS source tree.
+ This directory contains files which are "Makefile fragments." They are
+ included as required by the various ``Makefile.am`` files throughout the
+ CPU Kit portion of the RTEMS source tree.
``${RTEMS_ROOT}/cpukit/ftpd/``
This directory contains the RTEMS ftpd server.
``${RTEMS_ROOT}/cpukit/httpd/``
- This directory contains the port of the GoAhead
- web server to RTEMS.
+ This directory contains the port of the GoAhead web server to RTEMS.
``${RTEMS_ROOT}/cpukit/include/``
- This directory contains header files which are private to
- RTEMS and not considered to be owned by any other component
- in the CPU Kit.
+ This directory contains header files which are private to RTEMS and not
+ considered to be owned by any other component in the CPU Kit.
``${RTEMS_ROOT}/cpukit/libblock/``
- This directory contains support code for using
- Block Devices such as hard drives, floppies, and
- CD-ROMs. It includes the generic IO primitives
- for block device drivers, disk caching support,
- and a RAM disk block device driver.
+ This directory contains support code for using Block Devices such as hard
+ drives, floppies, and CD-ROMs. It includes the generic IO primitives for
+ block device drivers, disk caching support, and a RAM disk block device
+ driver.
``${RTEMS_ROOT}/cpukit/libcsupport/``
- This directory contains the RTEMS specific support routines
- for the Newlib C Library. This includes what are referred
- to as system calls and found in section 2 of the traditional
- UNIX manual. In addition, it contains a thread-safe
- implementation of the Malloc family of routines as well
- as BSD and POSIX services not found in Newlib.
+ This directory contains the RTEMS specific support routines for the Newlib
+ C Library. This includes what are referred to as system calls and found in
+ section 2 of the traditional UNIX manual. In addition, it contains a
+ thread-safe implementation of the Malloc family of routines as well as BSD
+ and POSIX services not found in Newlib.
``${RTEMS_ROOT}/cpukit/libfs/``
- This directory contains the various non-networked
- filesystem implementations for RTEMS. It includes
- the In-Memory FileSystem (IMFS), the mini-IMFS,
- and FAT filesystems.
+ This directory contains the various non-networked filesystem
+ implementations for RTEMS. It includes the In-Memory FileSystem (IMFS),
+ the mini-IMFS, and FAT filesystems.
``${RTEMS_ROOT}/cpukit/libi2c/``
This directory contains the RTEMS I2C framework.
``${RTEMS_ROOT}/cpukit/libmd/``
- This directory contains a port of the standard MD5
- checksum code.
+ This directory contains a port of the standard MD5 checksum code.
``${RTEMS_ROOT}/c/src/libmisc/``
- This directory contains support facilities which
- are RTEMS specific but otherwise unclassified. In
- general, they do not adhere to a standard API.
- Among the support facilities in this directory are
- a ``/dev/null`` device driver, the Stack
- Overflow Checker, a mini-shell, the CPU and
- rate monotonic period usage monitoring libraries,
- and a utility to "dump a buffer" in a nicely
- formatted way similar to many ROM monitors.
+ This directory contains support facilities which are RTEMS specific but
+ otherwise unclassified. In general, they do not adhere to a standard API.
+ Among the support facilities in this directory are a ``/dev/null`` device
+ driver, the Stack Overflow Checker, a mini-shell, the CPU and rate
+ monotonic period usage monitoring libraries, and a utility to "dump a
+ buffer" in a nicely formatted way similar to many ROM monitors.
``${RTEMS_ROOT}/cpukit/libnetworking/``
- This directory contains the port of the FreeBSD
- TCP/IP stack to RTEMS.
+ This directory contains the port of the FreeBSD TCP/IP stack to RTEMS.
``${RTEMS_ROOT}/cpukit/librpc/``
- This directory contains the port of the FreeBSD
- RPC/XDR source to RTEMS.
+ This directory contains the port of the FreeBSD RPC/XDR source to RTEMS.
``${RTEMS_ROOT}/cpukit/libpci/``
This directory contains RTEMS PCI Library.
``${RTEMS_ROOT}/cpukit/posix/``
- This directory contains the RTEMS implementation
- of the threading portions of the POSIX API.
+ This directory contains the RTEMS implementation of the threading portions
+ of the POSIX API.
``${RTEMS_ROOT}/cpukit/pppd/``
- This directory contains a port of the free implementation
- of the PPPD network protocol.
+ This directory contains a port of the free implementation of the PPPD
+ network protocol.
``${RTEMS_ROOT}/cpukit/rtems/``
- This directory contains the implementation of the
- Classic API.
+ This directory contains the implementation of the Classic API.
``${RTEMS_ROOT}/cpukit/sapi/``
- This directory contains the implementation of RTEMS
- services which are required but beyond the realm
- of any standardization efforts. It includes
+ This directory contains the implementation of RTEMS services which are
+ required but beyond the realm of any standardization efforts. It includes
initialization, shutdown, and IO services.
``${RTEMS_ROOT}/cpukit/score/``
- This directory contains the "SuperCore" of RTEMS.
- All APIs are implemented in terms of SuperCore services.
- For example, Classic API tasks and POSIX threads
- are all implemented in terms of SuperCore threads.
- This provides a common infrastructure and a high degree
- of interoperability between the APIs. For example,
- services from all APIs may be used by any task/thread
- independent of the API used to create it.
- Within the ``score/`` directory the CPU dependent modules are found.
- The ``score/cpu/`` subdirectory contains a subdirectory for each
- target CPU supported by this release of the RTEMS
- executive. Each processor directory contains the CPU dependent
- code necessary to host RTEMS. The ``no_cpu`` directory provides a
- starting point for developing a new port to an unsupported
- processor. The files contained within the ``no_cpu`` directory
- may also be used as a reference for the other ports to specific
- processors.
+ This directory contains the "SuperCore" of RTEMS. All APIs are implemented
+ in terms of SuperCore services. For example, Classic API tasks and POSIX
+ threads are all implemented in terms of SuperCore threads. This provides a
+ common infrastructure and a high degree of interoperability between the
+ APIs. For example, services from all APIs may be used by any task/thread
+ independent of the API used to create it. Within the ``score/`` directory
+ the CPU dependent modules are found. The ``score/cpu/`` subdirectory
+ contains a subdirectory for each target CPU supported by this release of
+ the RTEMS executive. Each processor directory contains the CPU dependent
+ code necessary to host RTEMS. The ``no_cpu`` directory provides a starting
+ point for developing a new port to an unsupported processor. The files
+ contained within the ``no_cpu`` directory may also be used as a reference
+ for the other ports to specific processors.
``${RTEMS_ROOT}/cpukit/shttpd/``
- This directory contains the port of the Simple HTTPD
- web server to RTEMS.
+ This directory contains the port of the Simple HTTPD web server to RTEMS.
``${RTEMS_ROOT}/cpukit/telnetd/``
This directory contains the RTEMS telnetd server.
``${RTEMS_ROOT}/cpukit/wrapup/``
- This directory is responsible for taking the individual
- libraries and objects built in each of the components
- in the RTEMS CPU Kit source tree and bundling them
- together to form the single RTEMS library ``librtemscpu.a``. This
- library contains all BSP and CPU model specific software.
+ This directory is responsible for taking the individual libraries and
+ objects built in each of the components in the RTEMS CPU Kit source tree
+ and bundling them together to form the single RTEMS library
+ ``librtemscpu.a``. This library contains all BSP and CPU model specific
+ software.
``${RTEMS_ROOT}/cpukit/zlib/``
- This directory contains a port of the GNU Zlib compression
- library to RTEMS.
-
-.. COMMENT: testsuites/ Test Suites
+ This directory contains a port of the GNU Zlib compression library to
+ RTEMS.
testsuites/ Test Suites
=======================
-This directory provides all of the RTEMS Test Suite
-except those for the Classic API Ada95 binding
-This includes the single processor tests, multiprocessor tests,
-timing tests, library tests, and sample tests. Additionally,
-subdirectories for support functions and test related header
-files are provided. The following table lists the test suites
-currently included with the RTEMS and the directory in which
-they may be located:
+This directory provides all of the RTEMS Test Suite except those for the
+Classic API Ada95 binding This includes the single processor tests,
+multiprocessor tests, timing tests, library tests, and sample tests.
+Additionally, subdirectories for support functions and test related header
+files are provided. The following table lists the test suites currently
+included with the RTEMS and the directory in which they may be located:
``${RTEMS_ROOT}/testsuites/libtests/``
- This directory contains the test suite for the
- various RTEMS support components.
+ This directory contains the test suite for the various RTEMS support
+ components.
``${RTEMS_ROOT}/testsuites/mptests/``
- This directory contains the test suite for the
- multiprocessor support in the Classic API.
- The tests provided address two node configurations
- and provide coverage for the multiprocessor code found
- in RTEMS.
+ This directory contains the test suite for the multiprocessor support in
+ the Classic API. The tests provided address two node configurations and
+ provide coverage for the multiprocessor code found in RTEMS.
``${RTEMS_ROOT}/testsuites/psxtests/``
- This directory contains the test suite for the
- RTEMS POSIX API.
+ This directory contains the test suite for the RTEMS POSIX API.
``${RTEMS_ROOT}/testsuites/samples/``
- This directory provides sample application tests
- which aid in the testing a newly built RTEMS environment, a new
- BSP, or as starting points for the development of an application
- using the RTEMS executive. They are discussed in `Sample Applications`_.
+ This directory provides sample application tests which aid in the testing a
+ newly built RTEMS environment, a new BSP, or as starting points for the
+ development of an application using the RTEMS executive. They are
+ discussed in `Sample Applications`_.
``${RTEMS_ROOT}/testsuites/sptests/``
- This directory contains the test suite for the RTEMS
- Classic API when executing on a single processor.
- The tests were originally designed to provide
- near complete test coverage for the entire
- executive code. With the addition of multiple APIs,
- this is no longer the case as some SuperCore functionality
- is not available through the Classic API. Thus
- some functionality in the SuperCore is only covered
- by tests in the POSIX API Test Suites.
+ This directory contains the test suite for the RTEMS Classic API when
+ executing on a single processor. The tests were originally designed to
+ provide near complete test coverage for the entire executive code. With
+ the addition of multiple APIs, this is no longer the case as some SuperCore
+ functionality is not available through the Classic API. Thus some
+ functionality in the SuperCore is only covered by tests in the POSIX API
+ Test Suites.
``${RTEMS_ROOT}/testsuites/support/``
- This directory contains support software and header files
- for the various test suites.
+ This directory contains support software and header files for the various
+ test suites.
``${RTEMS_ROOT}/testsuites/tmtests/``
- This directory contains the timing test suite for
- the RTEMS Classic API. This include tests that
- benchmark each directive in the Classic API
- as well as a set of critical SuperCore functions.
- These tests are important for helping to verify
- that RTEMS performs as expected on your target hardware.
- It is not uncommon to discover mistakes in board
- initialization such as caching being disabled as
- a side-effect of analyzing the results of these tests.
+ This directory contains the timing test suite for the RTEMS Classic API.
+ This include tests that benchmark each directive in the Classic API as well
+ as a set of critical SuperCore functions. These tests are important for
+ helping to verify that RTEMS performs as expected on your target hardware.
+ It is not uncommon to discover mistakes in board initialization such as
+ caching being disabled as a side-effect of analyzing the results of these
+ tests.
``${RTEMS_ROOT}/testsuites/tools/``
- This directory contains tools which execute on
- the development host and aid in executing and
- evaluating the results of the test suite. The
- tools ``difftest`` compares the output of one
- or more tests with the expected output. If you
- place the output of all the ``tmtests/`` in
- a single file, then the utility ``sorttimes``
- will be able to produce a report organizing the
- execution times by manager.
-
-.. COMMENT: Documentation Directory
+ This directory contains tools which execute on the development host and aid
+ in executing and evaluating the results of the test suite. The tools
+ ``difftest`` compares the output of one or more tests with the expected
+ output. If you place the output of all the ``tmtests/`` in a single file,
+ then the utility ``sorttimes`` will be able to produce a report organizing
+ the execution times by manager.
Documentation Directory
=======================
-This directory contains the source code for all RTEMS documentation
-in ``TexInfo`` format as well as utilities used in the generation
-of the RTEMS documentation set. This source code is used to produce
-the RTEMS documentation in various formats including PDF, HTML,
-and PostScript.
+This directory contains the source code for all RTEMS documentation in
+``TexInfo`` format as well as utilities used in the generation of the RTEMS
+documentation set. This source code is used to produce the RTEMS documentation
+in various formats including PDF, HTML, and PostScript.
``${RTEMS_ROOT}/doc/ada_user/``
- This directory contains the source code for the *RTEMS
- Applications Ada User's Guide* which documents the Ada95
- binding to the Classic API. This manual is produced from
- from the same source base as the *RTEMS Application
+ This directory contains the source code for the *RTEMS Applications Ada
+ User's Guide* which documents the Ada95 binding to the Classic API. This
+ manual is produced from from the same source base as the *RTEMS Application
C User's Guide*.
``${RTEMS_ROOT}/doc/bsp_howto/``
- This directory contains the source code for the*RTEMS BSP and Device Driver Development Guide*.
+ This directory contains the source code for the*RTEMS BSP and Device Driver
+ Development Guide*.
``${RTEMS_ROOT}/doc/common/``
- This directory contains the source code for the files which
- are shared across multiple manuals in the RTEMS Documentation Set.
- This includes the copyright page as well as the timing
- tables which can be filled in on a per BSP basis in the
- CPU supplements.
+ This directory contains the source code for the files which are shared
+ across multiple manuals in the RTEMS Documentation Set. This includes the
+ copyright page as well as the timing tables which can be filled in on a per
+ BSP basis in the CPU supplements.
``${RTEMS_ROOT}/doc/cpu_supplement/``
- This directory contains the source code for the
- RTEMS CPU Supplement.
+ This directory contains the source code for the RTEMS CPU Supplement.
``${RTEMS_ROOT}/doc/develenv/``
- This directory contains the source code for the*RTEMS Development Environment Guide*. This is
- the document you are currently reading.
+ This directory contains the source code for the*RTEMS Development
+ Environment Guide*. This is the document you are currently reading.
``${RTEMS_ROOT}/doc/filesystem/``
- This directory contains the source code for the*RTEMS Filesystem Design Guide*. This manual
- is a continuous work in process as it attempts to
- capture the design of the interface between system
- calls and filesystem implementations as well as the
- information required by those implementing filesystems.
+ This directory contains the source code for the*RTEMS Filesystem Design
+ Guide*. This manual is a continuous work in process as it attempts to
+ capture the design of the interface between system calls and filesystem
+ implementations as well as the information required by those implementing
+ filesystems.
``${RTEMS_ROOT}/doc/images/``
- This directory contains the source code for the graphics
- used in the HTML version of the RTEMS Documentation.
+ This directory contains the source code for the graphics used in the HTML
+ version of the RTEMS Documentation.
``${RTEMS_ROOT}/doc/networking/``
This directory contains the source code for the*RTEMS Network Supplement*.
``${RTEMS_ROOT}/doc/new_chapters/``
This directory contains the source code for the new documentation
- components which have not yet been collected into a new manual or
- merged into an existing document. Currently, this primarily
- contains draft documentation for some portions of
- the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``.
+ components which have not yet been collected into a new manual or merged
+ into an existing document. Currently, this primarily contains draft
+ documentation for some portions of the facilities implemented in
+ ``${RTEMS_ROOT}/c/src/libmisc/``.
``${RTEMS_ROOT}/doc/porting/``
This directory contains the source code for the*RTEMS Porting Guide*.
``${RTEMS_ROOT}/doc/posix1003.1/``
- This directory contains the source code for the*RTEMS POSIX 1003.1 Compliance Guide*.
+ This directory contains the source code for the*RTEMS POSIX 1003.1
+ Compliance Guide*.
``${RTEMS_ROOT}/doc/posix_users/``
- This directory contains the source code for the*RTEMS POSIX API User's Guide*. It is important to
- note that RTEMS' support for POSIX is a combination of
- functionality provided by RTEMS and the Newlib C Library
- so some functionality is documented by Newlib.
+ This directory contains the source code for the*RTEMS POSIX API User's
+ Guide*. It is important to note that RTEMS' support for POSIX is a
+ combination of functionality provided by RTEMS and the Newlib C Library so
+ some functionality is documented by Newlib.
``${RTEMS_ROOT}/doc/relnotes/``
- This directory contains the source code for a formally
- release notes document. This has not been used for
- recent RTEMS releases.
+ This directory contains the source code for a formally release notes
+ document. This has not been used for recent RTEMS releases.
``${RTEMS_ROOT}/doc/started/``
- This directory contains the source code for the*Getting Started with RTEMS for C/C++ Users* manual.
+ This directory contains the source code for the*Getting Started with RTEMS
+ for C/C++ Users* manual.
``${RTEMS_ROOT}/doc/tools/``
- This directory contains the source code for the tools
- used on the development host to assist in producing the
- RTEMS Documentation. The most important of these tools
- is ``bmenu`` which generates the hierarchical node
- linking commands based upon chapter, section, and
- subsection organization.
+ This directory contains the source code for the tools used on the
+ development host to assist in producing the RTEMS Documentation. The most
+ important of these tools is ``bmenu`` which generates the hierarchical node
+ linking commands based upon chapter, section, and subsection organization.
``${RTEMS_ROOT}/doc/user/``
- This directory contains the source code for the *RTEMS
- Applications C User's Guide* which documents the Classic API.
-
-.. COMMENT: COPYRIGHT (c) 1989-2007.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
-
+ This directory contains the source code for the *RTEMS Applications C
+ User's Guide* which documents the Classic API.
diff --git a/develenv/index.rst b/develenv/index.rst
index c9fc25d..5702b1f 100644
--- a/develenv/index.rst
+++ b/develenv/index.rst
@@ -4,47 +4,42 @@
RTEMS Development Environment Guide
===================================
-COPYRIGHT (c) 1988 - 2015.
-
-On-Line Applications Research Corporation (OAR).
-
-The authors have used their best efforts in preparing
-this material. These efforts include the development, research,
-and testing of the theories and programs to determine their
-effectiveness. No warranty of any kind, expressed or implied,
-with regard to the software or the material contained in this
-document is provided. No liability arising out of the
-application or use of any product described in this document is
-assumed. The authors reserve the right to revise this material
-and to make changes from time to time in the content hereof
-without obligation to notify anyone of such revision or changes.
-
-The RTEMS Project is hosted at http://www.rtems.org. Any
-inquiries concerning RTEMS, its related support components, or its
-documentation should be directed to the Community Project hosted athttp://www.rtems.org.
-
-Any inquiries for commercial services including training, support, custom
-development, application development assistance should be directed tohttp://www.rtems.com.
-
-
-Table of Contents
------------------
-
-.. toctree::
-
- introduction
-
+ | COPYRIGHT (c) 1988 - 2015.
+ | On-Line Applications Research Corporation (OAR).
+
+The authors have used their best efforts in preparing this material. These
+efforts include the development, research, and testing of the theories and
+programs to determine their effectiveness. No warranty of any kind, expressed
+or implied, with regard to the software or the material contained in this
+document is provided. No liability arising out of the application or use of
+any product described in this document is assumed. The authors reserve the
+right to revise this material and to make changes from time to time in the
+content hereof without obligation to notify anyone of such revision or changes.
+
+The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning
+RTEMS, its related support components, or its documentation should be directed
+to the Community Project hosted at http://www.rtems.org/.
+
+.. topic:: RTEMS Online Resources
+
+ ================ =============================
+ Home https://www.rtems.org/
+ Developers https://devel.rtems.org/
+ Documentation https://docs.rtems.org/
+ Bug Reporting https://devel.rtems.org/query
+ Mailing Lists https://lists.rtems.org/
+ Git Repositories https://git.rtems.org/
+ ================ =============================
.. toctree::
:maxdepth: 3
:numbered:
-
+ introduction
directory
sample
utilities
command
-
* :ref:`genindex`
* :ref:`search`
diff --git a/develenv/introduction.rst b/develenv/introduction.rst
index 8bb701e..3332bee 100644
--- a/develenv/introduction.rst
+++ b/develenv/introduction.rst
@@ -1,56 +1,46 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1989-2010.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
============
Introduction
============
-This document describes the RTEMS development
-environment. Discussions are provided for the following topics:
+This document describes the RTEMS development environment. Discussions are
+provided for the following topics:
- the directory structure used by RTEMS,
-- usage of the GNU Make utility within the RTEMS
- development environment,
+- usage of the GNU Make utility within the RTEMS development environment,
- sample applications, and
- the RTEMS specific utilities.
-RTEMS was designed as a reusable software component.
-Highly reusable software such as RTEMS is typically distributed
-in the form of source code without providing any support tools.
-RTEMS is the foundation for a complex family of facilities
-including board support packages, device drivers, and support
-libraries. The RTEMS Development Environment is not a CASE
-tool. It is a collection of tools designed to reduce the
-complexity of using and enhancing the RTEMS family. Tools are
-provided which aid in the management of the development,
-maintenance, and usage of RTEMS, its run-time support
-facilities, and applications which utilize the executive.
-
-A key component of the RTEMS development environment
-is the GNU family of free tools. This is robust set of
-development and POSIX compatible tools for which source code is
-freely available. The primary compilers, assemblers, linkers,
-and make utility used by the RTEMS development team are the GNU
-tools. They are highly portable supporting a wide variety of
-host computers and, in the case of the development tools, a wide
-variety of target processors.
-
-It is recommended that the RTEMS developer become
-familiar with the RTEMS Development Environment before
-proceeding with any modifications to the executive source tree.
-The source code for the executive is very modular and source
-code is divided amongst directories based upon functionality as
-well as dependencies on CPU and target board. This organization
-is aimed at isolating and minimizing non-portable code. This
-has the immediate result that adding support for a new CPU or
-target board requires very little "wandering" around the source
-tree.
-
-.. COMMENT: COPYRIGHT (c) 1989-2010.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+RTEMS was designed as a reusable software component. Highly reusable software
+such as RTEMS is typically distributed in the form of source code without
+providing any support tools. RTEMS is the foundation for a complex family of
+facilities including board support packages, device drivers, and support
+libraries. The RTEMS Development Environment is not a CASE tool. It is a
+collection of tools designed to reduce the complexity of using and enhancing
+the RTEMS family. Tools are provided which aid in the management of the
+development, maintenance, and usage of RTEMS, its run-time support facilities,
+and applications which utilize the executive.
+
+A key component of the RTEMS development environment is the GNU family of free
+tools. This is robust set of development and POSIX compatible tools for which
+source code is freely available. The primary compilers, assemblers, linkers,
+and make utility used by the RTEMS development team are the GNU tools. They
+are highly portable supporting a wide variety of host computers and, in the
+case of the development tools, a wide variety of target processors.
+
+It is recommended that the RTEMS developer become familiar with the RTEMS
+Development Environment before proceeding with any modifications to the
+executive source tree. The source code for the executive is very modular and
+source code is divided amongst directories based upon functionality as well as
+dependencies on CPU and target board. This organization is aimed at isolating
+and minimizing non-portable code. This has the immediate result that adding
+support for a new CPU or target board requires very little "wandering" around
+the source tree.
diff --git a/develenv/sample.rst b/develenv/sample.rst
index b3ddc1b..fadbc90 100644
--- a/develenv/sample.rst
+++ b/develenv/sample.rst
@@ -6,151 +6,145 @@ Sample Applications
Introduction
============
-The RTEMS source distribution includes a set of sample applications
-that are located in the ``${RTEMS_ROOT}/testsuites/samples/``
-directory. These applications are intended to illustrate the
-basic format of RTEMS single and multiple processor
-applications and the use of some features. In addition, these
-relatively simple applications can be used to test locally
-developed board support packages and device drivers as they
-exercise a critical subset of RTEMS functionality that is often
-broken in new BSPs.
-
-Some of the following sample applications will be covered in
-more detail in subsequent sections:
+The RTEMS source distribution includes a set of sample applications that are
+located in the ``${RTEMS_ROOT}/testsuites/samples/`` directory. These
+applications are intended to illustrate the basic format of RTEMS single and
+multiple processor applications and the use of some features. In addition,
+these relatively simple applications can be used to test locally developed
+board support packages and device drivers as they exercise a critical subset of
+RTEMS functionality that is often broken in new BSPs.
+
+Some of the following sample applications will be covered in more detail in
+subsequent sections:
*Hello World*
- The RTEMS Hello World test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``.
- This test is helpful when testing new RTEMS development environment.
+ The RTEMS Hello World test is provided in the subdirectory
+ ``${RTEMS_ROOT}/testsuites/samples/hello/``. This test is helpful when
+ testing new RTEMS development environment.
*Clock Tick*
- The ``${RTEMS_ROOT}/testsuites/samples/ticker/``
- subdirectory provides a test for verification of clock chip
- device drivers of BSPs.
+ The ``${RTEMS_ROOT}/testsuites/samples/ticker/`` subdirectory provides a
+ test for verification of clock chip device drivers of BSPs.
*Base Single Processor*
- A simple single processor test similar to those in the
- single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
+ A simple single processor test similar to those in the single processor
+ test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
*Base Multiple Processor*
- A simple two node multiprocessor test capable of testing an newly
- developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
+ A simple two node multiprocessor test capable of testing an newly developed
+ MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
*Capture*
- The RTEMS Capture test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``.
- This is an interactive test which demonstrates the capabilities
- of the RTEMS Capture Engine. It includes a few test threads
- which generate interesting execution patterns. Look at the
- file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
+ The RTEMS Capture test is provided in the subdirectory
+ ``${RTEMS_ROOT}/testsuites/samples/capture/``. This is an interactive test
+ which demonstrates the capabilities of the RTEMS Capture Engine. It
+ includes a few test threads which generate interesting execution patterns.
+ Look at the file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
for a sample session.
*Constructor/Destructor C++ Test*
- The ``${RTEMS_ROOT}/testsuites/samples/cdtest/``
- subdirectory provides a simple C++ application using
- constructors and destructors. It is only built when
- C++ is enabled and its primary purpose is to demonstrate
- that global constructors and destructors work. Since this
- requires that the linker script for your BSP be correct, this is
- an important test.
+ The ``${RTEMS_ROOT}/testsuites/samples/cdtest/`` subdirectory provides a
+ simple C++ application using constructors and destructors. It is only
+ built when C++ is enabled and its primary purpose is to demonstrate that
+ global constructors and destructors work. Since this requires that the
+ linker script for your BSP be correct, this is an important test.
*File IO*
- The RTEMS File IO test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``.
- This is an interactive test which allows the user to interact with
- an ATA/IDE device. It will read the partition table and allow the
- user to dynamically mount one of the FAT32 partitions it finds.
- Commands are also provided to write and read files on the disk.
+ The RTEMS File IO test is provided in the subdirectory
+ ``${RTEMS_ROOT}/testsuites/samples/fileio/``. This is an interactive test
+ which allows the user to interact with an ATA/IDE device. It will read the
+ partition table and allow the user to dynamically mount one of the FAT32
+ partitions it finds. Commands are also provided to write and read files on
+ the disk.
*IO Stream*
- The RTEMS IO Stream test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``.
- This test is a simple C++ application which demonstrates that
- C++ iostreams are functional. This requires that the RTEMS C++
- run-time support is functioning properly. This test is only
- build when C++ is enabled.
+ The RTEMS IO Stream test is provided in the subdirectory
+ ``${RTEMS_ROOT}/testsuites/samples/iostream/``. This test is a simple C++
+ application which demonstrates that C++ iostreams are functional. This
+ requires that the RTEMS C++ run-time support is functioning properly. This
+ test is only build when C++ is enabled.
*Network Loopback Test*
- The ``${RTEMS_ROOT}/testsuites/samples/loopback/``
- directory contains a sample test that demonstrates the use of
- sockets and the loopback network device. It does not require
- the presence of network hardware in order to run.
- It is only built if RTEMS was configured with networking enabled.
+ The ``${RTEMS_ROOT}/testsuites/samples/loopback/`` directory contains a
+ sample test that demonstrates the use of sockets and the loopback network
+ device. It does not require the presence of network hardware in order to
+ run. It is only built if RTEMS was configured with networking enabled.
*Minimum Size Test*
- The directory``${RTEMS_ROOT}/testsuites/samples/minimum/``
- contains a simple RTEMS program that results in a non-functional
- executable. It is intended to show the size of a minimum footprint
- application based upon the current RTEMS configuration.
+ The directory ``${RTEMS_ROOT}/testsuites/samples/minimum/`` contains a
+ simple RTEMS program that results in a non-functional executable. It is
+ intended to show the size of a minimum footprint application based upon the
+ current RTEMS configuration.
*Nanoseconds*
- The RTEMS Nanoseconds test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``.
- This test demonstrates that the BSP has support for nanosecond
- timestamp granularity. It prints the time of day and uptime multiple
- times as quickly as possible. It should be possible from the output
- to determine if your BSP has nanosecond accurate clock support
- and it is functional.
+
+ The RTEMS Nanoseconds test is provided in the subdirectory
+ ``${RTEMS_ROOT}/testsuites/samples/nsecs/``. This test demonstrates that
+ the BSP has support for nanosecond timestamp granularity. It prints the
+ time of day and uptime multiple times as quickly as possible. It should be
+ possible from the output to determine if your BSP has nanosecond accurate
+ clock support and it is functional.
*Paranoia Floating Point Test*
- The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/``
- contains the public domain floating point and math library test.
+ The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/`` contains the
+ public domain floating point and math library test.
*Point-to-Point Protocol Daemon*
- The RTEMS Point-to-Point Protocol Daemon test is provided in
- the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``.
- This test primarily serves as the baseline for a user application
- using the PPP protocol.
+ The RTEMS Point-to-Point Protocol Daemon test is provided in the
+ subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``. This test
+ primarily serves as the baseline for a user application using the PPP
+ protocol.
*Unlimited Object Allocation*
- The ``${RTEMS_ROOT}/testsuites/samples/unlimited/``
- directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS.
+ The ``${RTEMS_ROOT}/testsuites/samples/unlimited/`` directory contains a
+ sample test that demonstrates the use of the*unlimited* object allocation
+ configuration option to RTEMS.
-The sample tests are written using the Classic API so the reader
-should be familiar with the terms used and
-material presented in the *RTEMS Applications Users Guide*.
+The sample tests are written using the Classic API so the reader should be
+familiar with the terms used and material presented in the *RTEMS Applications
+Users Guide*.
Hello World
===========
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/hello/
-It provides a rudimentary test of the BSP start up
-code and the console output routine. The C version of this
-sample application uses the printf function from the RTEMS
-Standard C Library to output messages. The Ada version of this
-sample uses the TEXT_IO package to output the hello messages.
-The following messages are printed:
-.. code:: c
+It provides a rudimentary test of the BSP start up code and the console output
+routine. The C version of this sample application uses the printf function
+from the RTEMS Standard C Library to output messages. The Ada version of this
+sample uses the TEXT_IO package to output the hello messages. The following
+messages are printed:
- *** HELLO WORLD TEST \***
+.. code-block:: c
+
+ *** HELLO WORLD TEST ***
Hello World
- \*** END OF HELLO WORLD TEST \***
+ *** END OF HELLO WORLD TEST ***
-These messages are printed from the application's
-single initialization task. If the above messages are not
-printed correctly, then either the BSP start up code or the
-console output routine is not operating properly.
+These messages are printed from the application's single initialization task.
+If the above messages are not printed correctly, then either the BSP start up
+code or the console output routine is not operating properly.
Clock Tick
==========
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/ticker/
-This application is designed as a simple test of the
-clock tick device driver. In addition, this application also
-tests the printf function from the RTEMS Standard C Library by
-using it to output the following messages:
-.. code:: c
+This application is designed as a simple test of the clock tick device driver.
+In addition, this application also tests the printf function from the RTEMS
+Standard C Library by using it to output the following messages:
+
+.. code-block:: c
- *** CLOCK TICK TEST \***
+ *** CLOCK TICK TEST ***
TA1 - tm_get - 09:00:00 12/31/1988
TA2 - tm_get - 09:00:00 12/31/1988
TA3 - tm_get - 09:00:00 12/31/1988
@@ -165,110 +159,109 @@ using it to output the following messages:
TA1 - tm_get - 09:00:30 12/31/1988
TA2 - tm_get - 09:00:30 12/31/1988
TA3 - tm_get - 09:00:30 12/31/1988
- \*** END OF CLOCK TICK TEST \***
-
-The clock tick sample application utilizes a single
-initialization task and three copies of the single application
-task. The initialization task prints the test herald, sets the
-time and date, and creates and starts the three application
-tasks before deleting itself. The three application tasks
-generate the rest of the output. Every five seconds, one or
-more of the tasks will print the current time obtained via the
-tm_get directive. The first task, TA1, executes every five
-seconds, the second task, TA2, every ten seconds, and the third
-task, TA3, every fifteen seconds. If the time printed does not
-match the above output, then the clock device driver is not
-operating properly.
+ *** END OF CLOCK TICK TEST ***
+
+The clock tick sample application utilizes a single initialization task and
+three copies of the single application task. The initialization task prints
+the test herald, sets the time and date, and creates and starts the three
+application tasks before deleting itself. The three application tasks generate
+the rest of the output. Every five seconds, one or more of the tasks will
+print the current time obtained via the tm_get directive. The first task, TA1,
+executes every five seconds, the second task, TA2, every ten seconds, and the
+third task, TA3, every fifteen seconds. If the time printed does not match the
+above output, then the clock device driver is not operating properly.
Base Single Processor Application
=================================
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/base_sp/
-It provides a framework from which a single processor
-RTEMS application can be developed. The use of the task argument
-is illustrated. This sample application uses the printf
-function from the RTEMS Standard C Library or TEXT_IO functions
-when using the Ada version to output the following messages:
-.. code:: c
+It provides a framework from which a single processor RTEMS application can be
+developed. The use of the task argument is illustrated. This sample
+application uses the printf function from the RTEMS Standard C Library or
+TEXT_IO functions when using the Ada version to output the following messages:
+
+.. code-block:: c
- *** SAMPLE SINGLE PROCESSOR APPLICATION \***
+ *** SAMPLE SINGLE PROCESSOR APPLICATION ***
Creating and starting an application task
Application task was invoked with argument (0) and has id of 0x10002
- \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \***
+ *** END OF SAMPLE SINGLE PROCESSOR APPLICATION ***
-The first two messages are printed from the
-application's single initialization task. The final messages
-are printed from the single application task.
+The first two messages are printed from the application's single initialization
+task. The final messages are printed from the single application task.
Base Multiple Processor Application
===================================
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/base_mp/
-It provides a framework from which a multiprocessor
-RTEMS application can be developed. This directory has a
-subdirectory for each node in the multiprocessor system. The
-task argument is used to distinguish the node on which the
-application task is executed. The first node will print the
+It provides a framework from which a multiprocessor RTEMS application can be
+developed. This directory has a subdirectory for each node in the
+multiprocessor system. The task argument is used to distinguish the node on
+which the application task is executed. The first node will print the
following messages:
-.. code:: c
- *** SAMPLE MULTIPROCESSOR APPLICATION \***
+.. code-block:: c
+
+ *** SAMPLE MULTIPROCESSOR APPLICATION ***
Creating and starting an application task
This task was invoked with the node argument (1)
This task has the id of 0x10002
- \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
+ *** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
The second node will print the following messages:
-.. code:: c
- *** SAMPLE MULTIPROCESSOR APPLICATION \***
+.. code-block:: c
+
+ *** SAMPLE MULTIPROCESSOR APPLICATION ***
Creating and starting an application task
This task was invoked with the node argument (2)
This task has the id of 0x20002
- \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
+ *** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
-The herald is printed from the application's single
-initialization task on each node. The final messages are
-printed from the single application task on each node.
+The herald is printed from the application's single initialization task on each
+node. The final messages are printed from the single application task on each
+node.
-In this sample application, all source code is shared
-between the nodes except for the node dependent configuration
-files. These files contains the definition of the node number
-used in the initialization of the RTEMS Multiprocessor
-Configuration Table. This file is not shared because the node
-number field in the RTEMS Multiprocessor Configuration Table
-must be unique on each node.
+In this sample application, all source code is shared between the nodes except
+for the node dependent configuration files. These files contains the
+definition of the node number used in the initialization of the RTEMS
+Multiprocessor Configuration Table. This file is not shared because the node
+number field in the RTEMS Multiprocessor Configuration Table must be unique on
+each node.
Constructor/Destructor C++ Application
======================================
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/cdtest/
-This sample application demonstrates that RTEMS is
-compatible with C++ applications. It uses constructors,
-destructor, and I/O stream output in testing these various
-capabilities. The board support package responsible for this
-application must support a C++ environment.
+This sample application demonstrates that RTEMS is compatible with C++
+applications. It uses constructors, destructor, and I/O stream output in
+testing these various capabilities. The board support package responsible for
+this application must support a C++ environment.
+
+This sample application uses the printf function from the RTEMS Standard C
+Library to output the following messages:
-This sample application uses the printf function from
-the RTEMS Standard C Library to output the following messages:
-.. code:: c
+.. code-block:: c
Hey I'M in base class constructor number 1 for 0x400010cc.
Hey I'M in base class constructor number 2 for 0x400010d4.
Hey I'M in derived class constructor number 3 for 0x400010d4.
- \*** CONSTRUCTOR/DESTRUCTOR TEST \***
+ *** CONSTRUCTOR/DESTRUCTOR TEST ***
Hey I'M in base class constructor number 4 for 0x4009ee08.
Hey I'M in base class constructor number 5 for 0x4009ee10.
Hey I'M in base class constructor number 6 for 0x4009ee18.
@@ -285,7 +278,7 @@ the RTEMS Standard C Library to output the following messages:
Instantiation order 5
Hey I'M in base class constructor number 4 for 0x4009ee08.
Instantiation order 5
- \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \***
+ *** END OF CONSTRUCTOR/DESTRUCTOR TEST ***
Hey I'M in base class constructor number 3 for 0x400010d4.
Hey I'M in base class constructor number 2 for 0x400010d4.
Hey I'M in base class constructor number 1 for 0x400010cc.
@@ -294,30 +287,29 @@ Minimum Size Test
=================
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/minimum/
-This sample application is designed to produce the
-minimum code space required for any RTEMS application
-based upon the current RTEMS configuration and
-BSP. In many situations, the bulk of this executable
-consists of hardware and RTEMS initialization, basic
-infrastructure such as malloc(), and RTEMS and
-hardware shutdown support.
+This sample application is designed to produce the minimum code space required
+for any RTEMS application based upon the current RTEMS configuration and BSP.
+In many situations, the bulk of this executable consists of hardware and RTEMS
+initialization, basic infrastructure such as malloc(), and RTEMS and hardware
+shutdown support.
Nanosecond Granularity Application
==================================
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/nsecs/
-This sample application exercises the Clock Driver
-for this BSP and demonstrates its ability to generate
-accurate timestamps. This application does this by
-exercising the time subsystem in three ways:
+This sample application exercises the Clock Driver for this BSP and
+demonstrates its ability to generate accurate timestamps. This application
+does this by exercising the time subsystem in three ways:
- Obtain Time of Day Twice Back to Back
@@ -325,11 +317,11 @@ exercising the time subsystem in three ways:
- Use System Up Time to Measure Loops
-The following is an example of what the output of this
-test may appear like:
-.. code:: c
+The following is an example of what the output of this test may appear like:
+
+.. code-block:: c
- *** NANOSECOND CLOCK TEST \***
+ *** NANOSECOND CLOCK TEST ***
10 iterations of getting TOD
Start: Sat Mar 24 11:15:00 2007:540000
Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000
@@ -373,42 +365,35 @@ test may appear like:
loop of 80000 0:151519000 0:153260000 --> 0:1741000
loop of 90000 0:156145000 0:158099000 --> 0:1954000
loop of 100000 0:160770000 0:162942000 --> 0:2172000
- \*** END OF NANOSECOND CLOCK TEST \***
+ *** END OF NANOSECOND CLOCK TEST ***
Paranoia Floating Point Application
===================================
This sample application is in the following directory:
-.. code:: c
+
+.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/paranoia/
-This sample application uses a public domain floating
-point and math library test to verify these capabilities of the
-RTEMS executive. Deviations between actual and expected results
-are reported to the screen. This is a very extensive test which
-tests all mathematical and number conversion functions.
-Paranoia is also very large and requires a long period of time
-to run. Problems which commonly prevent this test from
-executing to completion include stack overflow and FPU exception
-handlers not installed.
+This sample application uses a public domain floating point and math library
+test to verify these capabilities of the RTEMS executive. Deviations between
+actual and expected results are reported to the screen. This is a very
+extensive test which tests all mathematical and number conversion functions.
+Paranoia is also very large and requires a long period of time to run.
+Problems which commonly prevent this test from executing to completion include
+stack overflow and FPU exception handlers not installed.
Network Loopback Test
=====================
This sample application is in the following directory:
-.. code:: c
- ${RTEMS_ROOT}/testsuites/samples/loopback/
-
-This sample application uses the network loopback device to
-demonstrate the use of the RTEMS TCP/IP stack. This sample
-test illustrates the basic configuration and initialization
-of the TCP/IP stack as well as simple socket usage.
-
-.. COMMENT: COPYRIGHT (c) 1989-2007.
+.. code-block:: c
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
+ ${RTEMS_ROOT}/testsuites/samples/loopback/
+This sample application uses the network loopback device to demonstrate the use
+of the RTEMS TCP/IP stack. This sample test illustrates the basic
+configuration and initialization of the TCP/IP stack as well as simple socket
+usage.
diff --git a/develenv/utilities.rst b/develenv/utilities.rst
index a5e37a3..70e493e 100644
--- a/develenv/utilities.rst
+++ b/develenv/utilities.rst
@@ -3,25 +3,22 @@
RTEMS Specific Utilities
########################
-This section describes the additional commands
-available within the *RTEMS Development Environment*. Although
-some of these commands are of general use, most are included to
-provide some capability necessary to perform a required function
-in the development of the RTEMS executive, one of its support
+This section describes the additional commands available within the *RTEMS
+Development Environment*. Although some of these commands are of general use,
+most are included to provide some capability necessary to perform a required
+function in the development of the RTEMS executive, one of its support
components, or an RTEMS based application.
-Some of the commands are implemented as C programs.
-However, most commands are implemented as Bourne shell scripts.
-Even if the current user has selected a different shell, the
-scripts will automatically invoke the Bourne shell during their
-execution lifetime.
+Some of the commands are implemented as C programs. However, most commands are
+implemented as Bourne shell scripts. Even if the current user has selected a
+different shell, the scripts will automatically invoke the Bourne shell during
+their execution lifetime.
-The commands are presented in UNIX manual page style
-for compatibility and convenience. A standard set of paragraph
-headers were used for all of the command descriptions. If a
-section contained no data, the paragraph header was omitted to
-conserve space. Each of the permissible paragraph headers and
-their contents are described below:
+The commands are presented in UNIX manual page style for compatibility and
+convenience. A standard set of paragraph headers were used for all of the
+command descriptions. If a section contained no data, the paragraph header was
+omitted to conserve space. Each of the permissible paragraph headers and their
+contents are described below:
``SYNOPSIS``
describes the command syntax
@@ -47,21 +44,18 @@ their contents are described below:
``SEE ALSO``
lists any relevant commands which can be consulted
-Most environment variables referenced by the commands
-are defined for the RTEMS Development Environment during the
-login procedure. During login, the user selects a default RTEMS
-environment through the use of the Modules package. This tool
-effectively sets the environment variables to provide a
-consistent development environment for a specific user.
-Additional environment variables within the RTEMS environment
-were set by the system administrator during installation. When
-specifying paths, a command description makes use of these
+Most environment variables referenced by the commands are defined for the RTEMS
+Development Environment during the login procedure. During login, the user
+selects a default RTEMS environment through the use of the Modules package.
+This tool effectively sets the environment variables to provide a consistent
+development environment for a specific user. Additional environment variables
+within the RTEMS environment were set by the system administrator during
+installation. When specifying paths, a command description makes use of these
environment variables.
-When referencing other commands in the SEE ALSO
-paragraph, the following notation is used: command(code).
-Where command is the name of a related command, and code is a
-section number. Valid section numbers are as follows:
+When referencing other commands in the SEE ALSO paragraph, the following
+notation is used: command(code). Where command is the name of a related
+command, and code is a section number. Valid section numbers are as follows:
``1``
Section 1 of the standard UNIX documentation
@@ -72,31 +66,27 @@ section number. Valid section numbers are as follows:
``1R``
a manual page from this document, the RTEMS Development Environment Guide
-For example, ls(1) means see the standard ls command
-in section 1 of the UNIX documentation. gcc020(1G) means see
-the description of gcc020 in section 1 of the GNU documentation.
-
-.. COMMENT: packhex
+For example, ``ls(1)`` means see the standard ls command in section 1 of the
+UNIX documentation. gcc020(1G) means see the description of gcc020 in section
+1 of the GNU documentation.
packhex - Compress Hexadecimal File
===================================
**SYNOPSIS**
-.. code:: c
+.. code-block:: c
packhex <source >destination
**DESCRIPTION**
-packhex accepts Intel Hexadecimal or Motorola Srecord
-on its standard input and attempts to pack as many contiguous
-bytes as possible into a single hexadecimal record. Many
-programs output hexadecimal records which are less than 80 bytes
-long (for human viewing). The overhead required by each
-unnecessary record is significant and packhex can often reduce
-the size of the download image by 20%. packhex attempts to
-output records which are as long as the hexadecimal format
+packhex accepts Intel Hexadecimal or Motorola Srecord on its standard input and
+attempts to pack as many contiguous bytes as possible into a single hexadecimal
+record. Many programs output hexadecimal records which are less than 80 bytes
+long (for human viewing). The overhead required by each unnecessary record is
+significant and packhex can often reduce the size of the download image by 20%.
+packhex attempts to output records which are as long as the hexadecimal format
allows.
**OPTIONS**
@@ -105,41 +95,37 @@ This command has no options.
**EXAMPLES**
-Assume the current directory contains the Motorola
-Srecord file download.sr. Then executing the command:
-.. code:: c
+Assume the current directory contains the Motorola Srecord file
+download.sr. Then executing the command:
+
+.. code-block:: c
packhex <download.sr >packed.sr
-will generate the file packed.sr which is usually
-smaller than download.sr.
+will generate the file packed.sr which is usually smaller than download.sr.
**CREDITS**
-The source for packhex first appeared in the May 1993
-issue of Embedded Systems magazine. The code was downloaded
-from their BBS. Unfortunately, the author's name was not
-provided in the listing.
-
-.. COMMENT: unhex
+The source for packhex first appeared in the May 1993 issue of Embedded Systems
+magazine. The code was downloaded from their BBS. Unfortunately, the author's
+name was not provided in the listing.
unhex - Convert Hexadecimal File into Binary Equivalent
=======================================================
**SYNOPSIS**
-.. code:: c
+.. code-block:: c
- unhex \[-valF] \[-o file] \[file \[file ...] ]
+ unhex [-valF] [-o file] [file [file ...] ]
**DESCRIPTION**
-unhex accepts Intel Hexadecimal, Motorola Srecord, or
-TI 'B' records and converts them to their binary equivalent.
-The output may sent to standout or may be placed in a specified
-file with the -o option. The designated output file may not be
-an input file. Multiple input files may be specified with their
-outputs logically concatenated into the output file.
+unhex accepts Intel Hexadecimal, Motorola Srecord, or TI 'B' records and
+converts them to their binary equivalent. The output may sent to standout or
+may be placed in a specified file with the -o option. The designated output
+file may not be an input file. Multiple input files may be specified with
+their outputs logically concatenated into the output file.
**OPTIONS**
@@ -149,8 +135,7 @@ This command has the following options:
Verbose
``a base``
- First byte of output corresponds with base
- address
+ First byte of output corresponds with base address
``l``
Linear Output
@@ -163,10 +148,9 @@ This command has the following options:
**EXAMPLES**
-The following command will create a binary equivalent
-file for the two Motorola S record files in the specified output
-file binary.bin:
-.. code:: c
+The following command will create a binary equivalent file for the two Motorola
+S record files in the specified output file binary.bin:
- unhex -o binary.bin downloadA.sr downloadB.sr
+.. code-block:: c
+ unhex -o binary.bin downloadA.sr downloadB.sr