rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-23 22:44:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

Fix develenv. Needs more fixes.

Browse Source
This commit is contained in:
Chris Johns 2016-10-27 16:12:50 -07:00
parent be428d186c
commit 9b53679540
6 changed files with 611 additions and 775 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
develenv/command.rst
View File

@ -4,6 +4,3 @@ Command and Variable Index
########################## ##########################
There are currently no Command and Variable Index entries. There are currently no Command and Variable Index entries.
.. COMMENT: @printindex fn

771
develenv/directory.rst
View File

@ -1,39 +1,38 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0 .. 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 Directory Structure
################### ###################
The RTEMS directory structure is designed to meet The RTEMS directory structure is designed to meet the following requirements:
the following requirements:
- encourage development of modular components. - encourage development of modular components.
- isolate processor and target dependent code, while - isolate processor and target dependent code, while allowing as much common
allowing as much common source code as possible to be shared source code as possible to be shared across multiple processors and target
across multiple processors and target boards. boards.
- allow multiple RTEMS users to perform simultaneous - allow multiple RTEMS users to perform simultaneous compilation of RTEMS and
compilation of RTEMS and its support facilities for different its support facilities for different processors and targets.
processors and targets.
The resulting directory structure has processor and The resulting directory structure has processor and board dependent source
board dependent source files isolated from generic files. When files isolated from generic files. When RTEMS is configured and built, object
RTEMS is configured and built, object directories and directories and an install point will be automatically created based upon the
an install point will be automatically created based upon target CPU family and BSP selected.
the target CPU family and BSP selected.
The placement of object files based upon the selected BSP name The placement of object files based upon the selected BSP name ensures that
ensures that object files are not mixed across CPUs or targets. object files are not mixed across CPUs or targets. This in combination with
This in combination with the makefiles allows the specific the makefiles allows the specific compilation options to be tailored for a
compilation options to be tailored for a particular target particular target board. For example, the efficiency of the memory subsystem
board. For example, the efficiency of the memory subsystem for for a particular target board may be sensitive to the alignment of data
a particular target board may be sensitive to the alignment of structures, while on another target board with the same processor memory may be
data structures, while on another target board with the same very limited. For the first target, the options could specify very strict
processor memory may be very limited. For the first target, the alignment requirements, while on the second the data structures could be
options could specify very strict alignment requirements, while *packed* to conserve memory. It is impossible to achieve this degree of
on the second the data structures could be *packed* to conserve flexibility without providing source code.
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: 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. - target board.
Each of the following sections will describe the Each of the following sections will describe the contents of the directories in
contents of the directories in the RTEMS source the RTEMS source tree. The top of the tree will be referenced as
tree. The top of the tree will be referenced ``${RTEMS_ROOT}`` in this discussion.
as ``${RTEMS_ROOT}`` in this discussion.
.. COMMENT: Top Level Tree .. code-block:: c
.. COMMENT: @ifset use-ascii
.. code:: c
rtems-VERSION rtems-VERSION
| |
@ -63,232 +58,192 @@ as ``${RTEMS_ROOT}`` in this discussion.
| | | | | | | | | | | | | | | | | |
aclocal automake c contrib cpukit doc make testsuites tools aclocal automake c contrib cpukit doc make testsuites tools
.. COMMENT: @end ifset
``${RTEMS_ROOT}/aclocal/`` ``${RTEMS_ROOT}/aclocal/``
This directory contains the custom M4 macros which are available to This directory contains the custom M4 macros which are available to the
the various GNU autoconf ``configure.ac`` scripts throughout various GNU autoconf ``configure.ac`` scripts throughout the RTEMS source
the RTEMS source tree. GNU autoconf interprets ``configure.ac`` tree. GNU autoconf interprets ``configure.ac`` files to produce the
files to produce the ``configure`` files used to tailor ``configure`` files used to tailor RTEMS build for a particular host and
RTEMS build for a particular host and target environment. The target environment. The contents of this directory will not be discussed
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. further in this document.
``${RTEMS_ROOT}/c/`` ``${RTEMS_ROOT}/automake/``
This directory is the root of the portions of the RTEMS source This directory contains the custom GNU automake fragments which are used to
tree which must be built tailored for a particular CPU model support the various ``Makefile.am`` files throughout the RTEMS source tree.
or BSP. The contents of this directory will be discussed The contents of this directory will not be discussed further in this
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.
``${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.
``${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.
``${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.
``${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.
``${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. document.
.. COMMENT: c/ Directions ``${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.
``${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.
``${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.
``${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.
``${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.
``${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.
``${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.
c/ Directory c/ Directory
============ ============
The ``${RTEMS_ROOT}/c/`` directory was formerly The ``${RTEMS_ROOT}/c/`` directory was formerly the root directory of all RTEMS
the root directory of all RTEMS source code. At this time, it contains source code. At this time, it contains the root directory for only those RTEMS
the root directory for only those RTEMS components components which must be compiled or linked in a way that is specific to a
which must be compiled or linked in a way that is specific to a particular CPU model or board. This directory contains the following
particular CPU model or board. This directory contains the subdirectories:
following subdirectories:
``${RTEMS_ROOT}/c/src/`` ``${RTEMS_ROOT}/c/src/``
This directory is logically the root for the RTEMS components This directory is logically the root for the RTEMS components which are CPU
which are CPU model or board dependent. Thus this directory model or board dependent. Thus this directory is the root for the BSPs and
is the root for the BSPs and the Ada Test Suites as well the Ada Test Suites as well as CPU model and BSP dependent libraries. The
as CPU model and BSP dependent libraries. The contents of contents of this directory are discussed in the `c/src/ Directory`_
this directory are discussed in the `c/src/ Directory`_ section. section.
.. COMMENT: c/src/ Directory
c/src/ Directory c/src/ Directory
---------------- ----------------
As mentioned previously, this directory is logically As mentioned previously, this directory is logically the root for the RTEMS
the root for the RTEMS components components which are CPU model or board dependent. The following is a list of
which are CPU model or board dependent. The the subdirectories in this directory and a description of each.
following is a list of the subdirectories in this
directory and a description of each.
``${RTEMS_ROOT}/c/src/aclocal/`` ``${RTEMS_ROOT}/c/src/aclocal/``
This directory contains the custom M4 macros which are available to This directory contains the custom M4 macros which are available to the
the various GNU autoconf ``configure.ac`` scripts throughout various GNU autoconf ``configure.ac`` scripts throughout this portion of
this portion of the RTEMS source tree. GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used the RTEMS source tree. GNU autoconf interprets``configure.ac`` files to
to tailor RTEMS build for a particular host and target environment. The produce the ``configure`` files used to tailor RTEMS build for a particular
contents of this directory will not be discussed further in this host and target environment. The contents of this directory will not be
document. discussed further in this document.
``${RTEMS_ROOT}/c/src/ada/`` ``${RTEMS_ROOT}/c/src/ada/``
This directory contains the Ada95 language bindings to the This directory contains the Ada95 language bindings to the RTEMS Classic
RTEMS Classic API. API.
``${RTEMS_ROOT}/c/src/ada-tests/`` ``${RTEMS_ROOT}/c/src/ada-tests/``
This directory contains the test suite for the Ada This directory contains the test suite for the Ada language bindings to the
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.
``${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.
``${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.
``${RTEMS_ROOT}/c/src/librtems++/``
This directory contains C++ classes which map to the RTEMS
Classic API. 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.
``${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.
``${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.
``${RTEMS_ROOT}/c/src/librtems++/``
This directory contains C++ classes which map to the RTEMS Classic API.
``${RTEMS_ROOT}/c/src/make/`` ``${RTEMS_ROOT}/c/src/make/``
This directory is used to generate the bulk of the supporting This directory is used to generate the bulk of the supporting rules files
rules files which are installed as part of the Application Makefiles. which are installed as part of the Application Makefiles. This file
This file contains settings for various Makefile variables to contains settings for various Makefile variables to tailor them to the
tailor them to the particular CPU model and BSP configured. particular CPU model and BSP configured.
``${RTEMS_ROOT}/c/src/nfsclient/`` ``${RTEMS_ROOT}/c/src/nfsclient/``
This directory contains a Network File System (NFS) client This directory contains a Network File System (NFS) client for RTEMS. With
for RTEMS. With this file system, a user's application can this file system, a user's application can access files on a remote
access files on a remote computer. computer.
``${RTEMS_ROOT}/c/src/optman/`` ``${RTEMS_ROOT}/c/src/optman/``
This directory contains stubs for the RTEMS Classic API This directory contains stubs for the RTEMS Classic API Managers which are
Managers which are considered optional and whose use considered optional and whose use may be explicitly forbidden by an
may be explicitly forbidden by an application. All of the application. All of the directive implementations in this Optional
directive implementations in this Optional Managers Managers return ``E_NOTCONFIGURED``.
return ``E_NOTCONFIGURED``.
``${RTEMS_ROOT}/c/src/support/`` ``${RTEMS_ROOT}/c/src/support/``
This directory exists solely to generate the RTEMS This directory exists solely to generate the RTEMS version string which
version string which includes the RTEMS version, includes the RTEMS version, CPU architecture, CPU model, and BSP name.
CPU architecture, CPU model, and BSP name.
``${RTEMS_ROOT}/c/src/wrapup/`` ``${RTEMS_ROOT}/c/src/wrapup/``
This directory is responsible for taking the individual This directory is responsible for taking the individual libraries and
libraries and objects built in each of the components objects built in each of the components in the RTEMS source tree and
in the RTEMS source tree and bundling them together to form bundling them together to form the single RTEMS library ``librtemsbsp.a``.
the single RTEMS library ``librtemsbsp.a``. This This library contains all BSP and CPU model specific software.
library contains all BSP and CPU model specific software.
.. COMMENT: c/src/lib/libbsp BSP Directory
c/src/lib/libbsp BSP Directory c/src/lib/libbsp BSP Directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The "libbsp" directory contains a directory for each CPU family supported The "libbsp" directory contains a directory for each CPU family supported by
by RTEMS. Beneath each CPU directory is a directory for each BSP for that RTEMS. Beneath each CPU directory is a directory for each BSP for that
processor family. 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.
The "libbsp" directory provides all the BSPs provided with this Below each CPU dependent directory is a directory for each target BSP supported
release of the RTEMS executive. The subdirectories are in this release.
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 Each BSP provides the modules which comprise an RTEMS BSP. The modules are
supported in this release. separated into the subdirectories "clock", "console", "include", "shmsupp",
"startup", and "timer" as shown in the following figure:
Each BSP provides the modules which comprise an RTEMS BSP. The .. code-block:: c
modules are separated into the subdirectories "clock", "console",
"include", "shmsupp", "startup", and "timer" as shown in the following
figure:
.. COMMENT: Tree 8 - Each BSP
.. COMMENT: @ifset use-ascii
.. code:: c
Each BSP Each BSP
| |
@ -296,346 +251,276 @@ figure:
| | | | | | | | | | | |
clock console include shmsupp startup timer clock console include shmsupp startup timer
.. COMMENT: @end ifset
.. COMMENT: CPU Kit Directory
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 cpukit
|
+-----------+----------+-----------+----------+
| | | | |
posix rtems sapi score wrapup
.. COMMENT: @example 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.
.. COMMENT: @group The following is a description of each of the subdirectories under ``cpukit/``:
.. COMMENT: cpukit
.. COMMENT: |
.. COMMENT: +-+-+-+-+
.. COMMENT: | | | | |
.. COMMENT: posix rtems sapi score wrapup
.. COMMENT: @end group
.. COMMENT: @end example
.. COMMENT: @end ifset
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/``:
``${RTEMS_ROOT}/cpukit/aclocal/`` ``${RTEMS_ROOT}/cpukit/aclocal/``
This directory contains the custom M4 macros which are available to This directory contains the custom M4 macros which are available to the
the various GNU autoconf ``configure.ac`` scripts throughout various GNU autoconf ``configure.ac`` scripts throughout the CPU Kit
the CPU Kit portion of the RTEMS source tree. portion of the RTEMS source tree. GNU autoconf interprets ``configure.ac``
GNU autoconf interprets ``configure.ac`` files to produce the ``configure`` files used to tailor RTEMS build for a
files to produce the ``configure`` files used to tailor particular host and target environment. The contents of this directory
RTEMS build for a particular host and target environment. The will not be discussed further in this document.
contents of this directory will not be discussed further in this
document.
``${RTEMS_ROOT}/cpukit/automake/`` ``${RTEMS_ROOT}/cpukit/automake/``
This directory contains files which are "Makefile fragments." This directory contains files which are "Makefile fragments." They are
They are included as required by the various ``Makefile.am`` included as required by the various ``Makefile.am`` files throughout the
files throughout the CPU Kit portion of the RTEMS source tree. CPU Kit portion of the RTEMS source tree.
``${RTEMS_ROOT}/cpukit/ftpd/`` ``${RTEMS_ROOT}/cpukit/ftpd/``
This directory contains the RTEMS ftpd server. This directory contains the RTEMS ftpd server.
``${RTEMS_ROOT}/cpukit/httpd/`` ``${RTEMS_ROOT}/cpukit/httpd/``
This directory contains the port of the GoAhead This directory contains the port of the GoAhead web server to RTEMS.
web server to RTEMS.
``${RTEMS_ROOT}/cpukit/include/`` ``${RTEMS_ROOT}/cpukit/include/``
This directory contains header files which are private to This directory contains header files which are private to RTEMS and not
RTEMS and not considered to be owned by any other component considered to be owned by any other component in the CPU Kit.
in the CPU Kit.
``${RTEMS_ROOT}/cpukit/libblock/`` ``${RTEMS_ROOT}/cpukit/libblock/``
This directory contains support code for using This directory contains support code for using Block Devices such as hard
Block Devices such as hard drives, floppies, and drives, floppies, and CD-ROMs. It includes the generic IO primitives for
CD-ROMs. It includes the generic IO primitives block device drivers, disk caching support, and a RAM disk block device
for block device drivers, disk caching support, driver.
and a RAM disk block device driver.
``${RTEMS_ROOT}/cpukit/libcsupport/`` ``${RTEMS_ROOT}/cpukit/libcsupport/``
This directory contains the RTEMS specific support routines This directory contains the RTEMS specific support routines for the Newlib
for the Newlib C Library. This includes what are referred C Library. This includes what are referred to as system calls and found in
to as system calls and found in section 2 of the traditional section 2 of the traditional UNIX manual. In addition, it contains a
UNIX manual. In addition, it contains a thread-safe thread-safe implementation of the Malloc family of routines as well as BSD
implementation of the Malloc family of routines as well and POSIX services not found in Newlib.
as BSD and POSIX services not found in Newlib.
``${RTEMS_ROOT}/cpukit/libfs/`` ``${RTEMS_ROOT}/cpukit/libfs/``
This directory contains the various non-networked This directory contains the various non-networked filesystem
filesystem implementations for RTEMS. It includes implementations for RTEMS. It includes the In-Memory FileSystem (IMFS),
the In-Memory FileSystem (IMFS), the mini-IMFS, the mini-IMFS, and FAT filesystems.
and FAT filesystems.
``${RTEMS_ROOT}/cpukit/libi2c/`` ``${RTEMS_ROOT}/cpukit/libi2c/``
This directory contains the RTEMS I2C framework. This directory contains the RTEMS I2C framework.
``${RTEMS_ROOT}/cpukit/libmd/`` ``${RTEMS_ROOT}/cpukit/libmd/``
This directory contains a port of the standard MD5 This directory contains a port of the standard MD5 checksum code.
checksum code.
``${RTEMS_ROOT}/c/src/libmisc/`` ``${RTEMS_ROOT}/c/src/libmisc/``
This directory contains support facilities which This directory contains support facilities which are RTEMS specific but
are RTEMS specific but otherwise unclassified. In otherwise unclassified. In general, they do not adhere to a standard API.
general, they do not adhere to a standard API. Among the support facilities in this directory are a ``/dev/null`` device
Among the support facilities in this directory are driver, the Stack Overflow Checker, a mini-shell, the CPU and rate
a ``/dev/null`` device driver, the Stack monotonic period usage monitoring libraries, and a utility to "dump a
Overflow Checker, a mini-shell, the CPU and buffer" in a nicely formatted way similar to many ROM monitors.
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/`` ``${RTEMS_ROOT}/cpukit/libnetworking/``
This directory contains the port of the FreeBSD This directory contains the port of the FreeBSD TCP/IP stack to RTEMS.
TCP/IP stack to RTEMS.
``${RTEMS_ROOT}/cpukit/librpc/`` ``${RTEMS_ROOT}/cpukit/librpc/``
This directory contains the port of the FreeBSD This directory contains the port of the FreeBSD RPC/XDR source to RTEMS.
RPC/XDR source to RTEMS.
``${RTEMS_ROOT}/cpukit/libpci/`` ``${RTEMS_ROOT}/cpukit/libpci/``
This directory contains RTEMS PCI Library. This directory contains RTEMS PCI Library.
``${RTEMS_ROOT}/cpukit/posix/`` ``${RTEMS_ROOT}/cpukit/posix/``
This directory contains the RTEMS implementation This directory contains the RTEMS implementation of the threading portions
of the threading portions of the POSIX API. of the POSIX API.
``${RTEMS_ROOT}/cpukit/pppd/`` ``${RTEMS_ROOT}/cpukit/pppd/``
This directory contains a port of the free implementation This directory contains a port of the free implementation of the PPPD
of the PPPD network protocol. network protocol.
``${RTEMS_ROOT}/cpukit/rtems/`` ``${RTEMS_ROOT}/cpukit/rtems/``
This directory contains the implementation of the This directory contains the implementation of the Classic API.
Classic API.
``${RTEMS_ROOT}/cpukit/sapi/`` ``${RTEMS_ROOT}/cpukit/sapi/``
This directory contains the implementation of RTEMS This directory contains the implementation of RTEMS services which are
services which are required but beyond the realm required but beyond the realm of any standardization efforts. It includes
of any standardization efforts. It includes
initialization, shutdown, and IO services. initialization, shutdown, and IO services.
``${RTEMS_ROOT}/cpukit/score/`` ``${RTEMS_ROOT}/cpukit/score/``
This directory contains the "SuperCore" of RTEMS. This directory contains the "SuperCore" of RTEMS. All APIs are implemented
All APIs are implemented in terms of SuperCore services. in terms of SuperCore services. For example, Classic API tasks and POSIX
For example, Classic API tasks and POSIX threads threads are all implemented in terms of SuperCore threads. This provides a
are all implemented in terms of SuperCore threads. common infrastructure and a high degree of interoperability between the
This provides a common infrastructure and a high degree APIs. For example, services from all APIs may be used by any task/thread
of interoperability between the APIs. For example, independent of the API used to create it. Within the ``score/`` directory
services from all APIs may be used by any task/thread the CPU dependent modules are found. The ``score/cpu/`` subdirectory
independent of the API used to create it. contains a subdirectory for each target CPU supported by this release of
Within the ``score/`` directory the CPU dependent modules are found. the RTEMS executive. Each processor directory contains the CPU dependent
The ``score/cpu/`` subdirectory contains a subdirectory for each code necessary to host RTEMS. The ``no_cpu`` directory provides a starting
target CPU supported by this release of the RTEMS point for developing a new port to an unsupported processor. The files
executive. Each processor directory contains the CPU dependent contained within the ``no_cpu`` directory may also be used as a reference
code necessary to host RTEMS. The ``no_cpu`` directory provides a for the other ports to specific processors.
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/`` ``${RTEMS_ROOT}/cpukit/shttpd/``
This directory contains the port of the Simple HTTPD This directory contains the port of the Simple HTTPD web server to RTEMS.
web server to RTEMS.
``${RTEMS_ROOT}/cpukit/telnetd/`` ``${RTEMS_ROOT}/cpukit/telnetd/``
This directory contains the RTEMS telnetd server. This directory contains the RTEMS telnetd server.
``${RTEMS_ROOT}/cpukit/wrapup/`` ``${RTEMS_ROOT}/cpukit/wrapup/``
This directory is responsible for taking the individual This directory is responsible for taking the individual libraries and
libraries and objects built in each of the components objects built in each of the components in the RTEMS CPU Kit source tree
in the RTEMS CPU Kit source tree and bundling them and bundling them together to form the single RTEMS library
together to form the single RTEMS library ``librtemscpu.a``. This ``librtemscpu.a``. This library contains all BSP and CPU model specific
library contains all BSP and CPU model specific software. software.
``${RTEMS_ROOT}/cpukit/zlib/`` ``${RTEMS_ROOT}/cpukit/zlib/``
This directory contains a port of the GNU Zlib compression This directory contains a port of the GNU Zlib compression library to
library to RTEMS. RTEMS.
.. COMMENT: testsuites/ Test Suites
testsuites/ Test Suites testsuites/ Test Suites
======================= =======================
This directory provides all of the RTEMS Test Suite This directory provides all of the RTEMS Test Suite except those for the
except those for the Classic API Ada95 binding Classic API Ada95 binding This includes the single processor tests,
This includes the single processor tests, multiprocessor tests, multiprocessor tests, timing tests, library tests, and sample tests.
timing tests, library tests, and sample tests. Additionally, Additionally, subdirectories for support functions and test related header
subdirectories for support functions and test related header files are provided. The following table lists the test suites currently
files are provided. The following table lists the test suites included with the RTEMS and the directory in which they may be located:
currently included with the RTEMS and the directory in which
they may be located:
``${RTEMS_ROOT}/testsuites/libtests/`` ``${RTEMS_ROOT}/testsuites/libtests/``
This directory contains the test suite for the This directory contains the test suite for the various RTEMS support
various RTEMS support components. components.
``${RTEMS_ROOT}/testsuites/mptests/`` ``${RTEMS_ROOT}/testsuites/mptests/``
This directory contains the test suite for the This directory contains the test suite for the multiprocessor support in
multiprocessor support in the Classic API. the Classic API. The tests provided address two node configurations and
The tests provided address two node configurations provide coverage for the multiprocessor code found in RTEMS.
and provide coverage for the multiprocessor code found
in RTEMS.
``${RTEMS_ROOT}/testsuites/psxtests/`` ``${RTEMS_ROOT}/testsuites/psxtests/``
This directory contains the test suite for the This directory contains the test suite for the RTEMS POSIX API.
RTEMS POSIX API.
``${RTEMS_ROOT}/testsuites/samples/`` ``${RTEMS_ROOT}/testsuites/samples/``
This directory provides sample application tests This directory provides sample application tests which aid in the testing a
which aid in the testing a newly built RTEMS environment, a new newly built RTEMS environment, a new BSP, or as starting points for the
BSP, or as starting points for the development of an application development of an application using the RTEMS executive. They are
using the RTEMS executive. They are discussed in `Sample Applications`_. discussed in `Sample Applications`_.
``${RTEMS_ROOT}/testsuites/sptests/`` ``${RTEMS_ROOT}/testsuites/sptests/``
This directory contains the test suite for the RTEMS This directory contains the test suite for the RTEMS Classic API when
Classic API when executing on a single processor. executing on a single processor. The tests were originally designed to
The tests were originally designed to provide provide near complete test coverage for the entire executive code. With
near complete test coverage for the entire the addition of multiple APIs, this is no longer the case as some SuperCore
executive code. With the addition of multiple APIs, functionality is not available through the Classic API. Thus some
this is no longer the case as some SuperCore functionality functionality in the SuperCore is only covered by tests in the POSIX API
is not available through the Classic API. Thus Test Suites.
some functionality in the SuperCore is only covered
by tests in the POSIX API Test Suites.
``${RTEMS_ROOT}/testsuites/support/`` ``${RTEMS_ROOT}/testsuites/support/``
This directory contains support software and header files This directory contains support software and header files for the various
for the various test suites. test suites.
``${RTEMS_ROOT}/testsuites/tmtests/`` ``${RTEMS_ROOT}/testsuites/tmtests/``
This directory contains the timing test suite for This directory contains the timing test suite for the RTEMS Classic API.
the RTEMS Classic API. This include tests that This include tests that benchmark each directive in the Classic API as well
benchmark each directive in the Classic API as a set of critical SuperCore functions. These tests are important for
as well as a set of critical SuperCore functions. helping to verify that RTEMS performs as expected on your target hardware.
These tests are important for helping to verify It is not uncommon to discover mistakes in board initialization such as
that RTEMS performs as expected on your target hardware. caching being disabled as a side-effect of analyzing the results of these
It is not uncommon to discover mistakes in board tests.
initialization such as caching being disabled as
a side-effect of analyzing the results of these tests.
``${RTEMS_ROOT}/testsuites/tools/`` ``${RTEMS_ROOT}/testsuites/tools/``
This directory contains tools which execute on This directory contains tools which execute on the development host and aid
the development host and aid in executing and in executing and evaluating the results of the test suite. The tools
evaluating the results of the test suite. The ``difftest`` compares the output of one or more tests with the expected
tools ``difftest`` compares the output of one output. If you place the output of all the ``tmtests/`` in a single file,
or more tests with the expected output. If you then the utility ``sorttimes`` will be able to produce a report organizing
place the output of all the ``tmtests/`` in the execution times by manager.
a single file, then the utility ``sorttimes``
will be able to produce a report organizing the
execution times by manager.
.. COMMENT: Documentation Directory
Documentation Directory Documentation Directory
======================= =======================
This directory contains the source code for all RTEMS documentation This directory contains the source code for all RTEMS documentation in
in ``TexInfo`` format as well as utilities used in the generation ``TexInfo`` format as well as utilities used in the generation of the RTEMS
of the RTEMS documentation set. This source code is used to produce documentation set. This source code is used to produce the RTEMS documentation
the RTEMS documentation in various formats including PDF, HTML, in various formats including PDF, HTML, and PostScript.
and PostScript.
``${RTEMS_ROOT}/doc/ada_user/`` ``${RTEMS_ROOT}/doc/ada_user/``
This directory contains the source code for the *RTEMS This directory contains the source code for the *RTEMS Applications Ada
Applications Ada User's Guide* which documents the Ada95 User's Guide* which documents the Ada95 binding to the Classic API. This
binding to the Classic API. This manual is produced from manual is produced from from the same source base as the *RTEMS Application
from the same source base as the *RTEMS Application
C User's Guide*. C User's Guide*.
``${RTEMS_ROOT}/doc/bsp_howto/`` ``${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/`` ``${RTEMS_ROOT}/doc/common/``
This directory contains the source code for the files which This directory contains the source code for the files which are shared
are shared across multiple manuals in the RTEMS Documentation Set. across multiple manuals in the RTEMS Documentation Set. This includes the
This includes the copyright page as well as the timing copyright page as well as the timing tables which can be filled in on a per
tables which can be filled in on a per BSP basis in the BSP basis in the CPU supplements.
CPU supplements.
``${RTEMS_ROOT}/doc/cpu_supplement/`` ``${RTEMS_ROOT}/doc/cpu_supplement/``
This directory contains the source code for the This directory contains the source code for the RTEMS CPU Supplement.
RTEMS CPU Supplement.
``${RTEMS_ROOT}/doc/develenv/`` ``${RTEMS_ROOT}/doc/develenv/``
This directory contains the source code for the*RTEMS Development Environment Guide*. This is This directory contains the source code for the*RTEMS Development
the document you are currently reading. Environment Guide*. This is the document you are currently reading.
``${RTEMS_ROOT}/doc/filesystem/`` ``${RTEMS_ROOT}/doc/filesystem/``
This directory contains the source code for the*RTEMS Filesystem Design Guide*. This manual This directory contains the source code for the*RTEMS Filesystem Design
is a continuous work in process as it attempts to Guide*. This manual is a continuous work in process as it attempts to
capture the design of the interface between system capture the design of the interface between system calls and filesystem
calls and filesystem implementations as well as the implementations as well as the information required by those implementing
information required by those implementing filesystems. filesystems.
``${RTEMS_ROOT}/doc/images/`` ``${RTEMS_ROOT}/doc/images/``
This directory contains the source code for the graphics This directory contains the source code for the graphics used in the HTML
used in the HTML version of the RTEMS Documentation. version of the RTEMS Documentation.
``${RTEMS_ROOT}/doc/networking/`` ``${RTEMS_ROOT}/doc/networking/``
This directory contains the source code for the*RTEMS Network Supplement*. This directory contains the source code for the*RTEMS Network Supplement*.
``${RTEMS_ROOT}/doc/new_chapters/`` ``${RTEMS_ROOT}/doc/new_chapters/``
This directory contains the source code for the new documentation This directory contains the source code for the new documentation
components which have not yet been collected into a new manual or components which have not yet been collected into a new manual or merged
merged into an existing document. Currently, this primarily into an existing document. Currently, this primarily contains draft
contains draft documentation for some portions of documentation for some portions of the facilities implemented in
the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``. ``${RTEMS_ROOT}/c/src/libmisc/``.
``${RTEMS_ROOT}/doc/porting/`` ``${RTEMS_ROOT}/doc/porting/``
This directory contains the source code for the*RTEMS Porting Guide*. This directory contains the source code for the*RTEMS Porting Guide*.
``${RTEMS_ROOT}/doc/posix1003.1/`` ``${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/`` ``${RTEMS_ROOT}/doc/posix_users/``
This directory contains the source code for the*RTEMS POSIX API User's Guide*. It is important to This directory contains the source code for the*RTEMS POSIX API User's
note that RTEMS' support for POSIX is a combination of Guide*. It is important to note that RTEMS' support for POSIX is a
functionality provided by RTEMS and the Newlib C Library combination of functionality provided by RTEMS and the Newlib C Library so
so some functionality is documented by Newlib. some functionality is documented by Newlib.
``${RTEMS_ROOT}/doc/relnotes/`` ``${RTEMS_ROOT}/doc/relnotes/``
This directory contains the source code for a formally This directory contains the source code for a formally release notes
release notes document. This has not been used for document. This has not been used for recent RTEMS releases.
recent RTEMS releases.
``${RTEMS_ROOT}/doc/started/`` ``${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/`` ``${RTEMS_ROOT}/doc/tools/``
This directory contains the source code for the tools This directory contains the source code for the tools used on the
used on the development host to assist in producing the development host to assist in producing the RTEMS Documentation. The most
RTEMS Documentation. The most important of these tools important of these tools is ``bmenu`` which generates the hierarchical node
is ``bmenu`` which generates the hierarchical node linking commands based upon chapter, section, and subsection organization.
linking commands based upon chapter, section, and
subsection organization.
``${RTEMS_ROOT}/doc/user/`` ``${RTEMS_ROOT}/doc/user/``
This directory contains the source code for the *RTEMS This directory contains the source code for the *RTEMS Applications C
Applications C User's Guide* which documents the Classic API. User's Guide* which documents the Classic API.
.. COMMENT: COPYRIGHT (c) 1989-2007.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

51
develenv/index.rst
View File

@ -4,47 +4,42 @@
RTEMS Development Environment Guide RTEMS Development Environment Guide
=================================== ===================================
COPYRIGHT (c) 1988 - 2015. | COPYRIGHT (c) 1988 - 2015.
| On-Line Applications Research Corporation (OAR).
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 authors have used their best efforts in preparing The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning
this material. These efforts include the development, research, RTEMS, its related support components, or its documentation should be directed
and testing of the theories and programs to determine their to the Community Project hosted at http://www.rtems.org/.
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 .. topic:: RTEMS Online Resources
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
================ =============================
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:: .. toctree::
:maxdepth: 3 :maxdepth: 3
:numbered: :numbered:
introduction
directory directory
sample sample
utilities utilities
command command
* :ref:`genindex` * :ref:`genindex`
* :ref:`search` * :ref:`search`

70
develenv/introduction.rst
View File

@ -1,56 +1,46 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0 .. 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 Introduction
============ ============
This document describes the RTEMS development This document describes the RTEMS development environment. Discussions are
environment. Discussions are provided for the following topics: provided for the following topics:
- the directory structure used by RTEMS, - the directory structure used by RTEMS,
- usage of the GNU Make utility within the RTEMS - usage of the GNU Make utility within the RTEMS development environment,
development environment,
- sample applications, and - sample applications, and
- the RTEMS specific utilities. - the RTEMS specific utilities.
RTEMS was designed as a reusable software component. RTEMS was designed as a reusable software component. Highly reusable software
Highly reusable software such as RTEMS is typically distributed such as RTEMS is typically distributed in the form of source code without
in the form of source code without providing any support tools. providing any support tools. RTEMS is the foundation for a complex family of
RTEMS is the foundation for a complex family of facilities facilities including board support packages, device drivers, and support
including board support packages, device drivers, and support libraries. The RTEMS Development Environment is not a CASE tool. It is a
libraries. The RTEMS Development Environment is not a CASE collection of tools designed to reduce the complexity of using and enhancing
tool. It is a collection of tools designed to reduce the the RTEMS family. Tools are provided which aid in the management of the
complexity of using and enhancing the RTEMS family. Tools are development, maintenance, and usage of RTEMS, its run-time support facilities,
provided which aid in the management of the development, and applications which utilize the executive.
maintenance, and usage of RTEMS, its run-time support
facilities, and applications which utilize the executive.
A key component of the RTEMS development environment A key component of the RTEMS development environment is the GNU family of free
is the GNU family of free tools. This is robust set of tools. This is robust set of development and POSIX compatible tools for which
development and POSIX compatible tools for which source code is source code is freely available. The primary compilers, assemblers, linkers,
freely available. The primary compilers, assemblers, linkers, and make utility used by the RTEMS development team are the GNU tools. They
and make utility used by the RTEMS development team are the GNU are highly portable supporting a wide variety of host computers and, in the
tools. They are highly portable supporting a wide variety of case of the development tools, a wide variety of target processors.
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.
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.

369
develenv/sample.rst
View File

@ -6,151 +6,145 @@ Sample Applications
Introduction Introduction
============ ============
The RTEMS source distribution includes a set of sample applications The RTEMS source distribution includes a set of sample applications that are
that are located in the ``${RTEMS_ROOT}/testsuites/samples/`` located in the ``${RTEMS_ROOT}/testsuites/samples/`` directory. These
directory. These applications are intended to illustrate the applications are intended to illustrate the basic format of RTEMS single and
basic format of RTEMS single and multiple processor multiple processor applications and the use of some features. In addition,
applications and the use of some features. In addition, these these relatively simple applications can be used to test locally developed
relatively simple applications can be used to test locally board support packages and device drivers as they exercise a critical subset of
developed board support packages and device drivers as they RTEMS functionality that is often broken in new BSPs.
exercise a critical subset of RTEMS functionality that is often
broken in new BSPs.
Some of the following sample applications will be covered in Some of the following sample applications will be covered in more detail in
more detail in subsequent sections: subsequent sections:
*Hello World* *Hello World*
The RTEMS Hello World test is provided in The RTEMS Hello World test is provided in the subdirectory
the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``. ``${RTEMS_ROOT}/testsuites/samples/hello/``. This test is helpful when
This test is helpful when testing new RTEMS development environment. testing new RTEMS development environment.
*Clock Tick* *Clock Tick*
The ``${RTEMS_ROOT}/testsuites/samples/ticker/`` The ``${RTEMS_ROOT}/testsuites/samples/ticker/`` subdirectory provides a
subdirectory provides a test for verification of clock chip test for verification of clock chip device drivers of BSPs.
device drivers of BSPs.
*Base Single Processor* *Base Single Processor*
A simple single processor test similar to those in the A simple single processor test similar to those in the single processor
single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``. test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
*Base Multiple Processor* *Base Multiple Processor*
A simple two node multiprocessor test capable of testing an newly A simple two node multiprocessor test capable of testing an newly developed
developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``. MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
*Capture* *Capture*
The RTEMS Capture test is provided in The RTEMS Capture test is provided in the subdirectory
the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``. ``${RTEMS_ROOT}/testsuites/samples/capture/``. This is an interactive test
This is an interactive test which demonstrates the capabilities which demonstrates the capabilities of the RTEMS Capture Engine. It
of the RTEMS Capture Engine. It includes a few test threads includes a few test threads which generate interesting execution patterns.
which generate interesting execution patterns. Look at the Look at the file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
for a sample session. for a sample session.
*Constructor/Destructor C++ Test* *Constructor/Destructor C++ Test*
The ``${RTEMS_ROOT}/testsuites/samples/cdtest/`` The ``${RTEMS_ROOT}/testsuites/samples/cdtest/`` subdirectory provides a
subdirectory provides a simple C++ application using simple C++ application using constructors and destructors. It is only
constructors and destructors. It is only built when built when C++ is enabled and its primary purpose is to demonstrate that
C++ is enabled and its primary purpose is to demonstrate global constructors and destructors work. Since this requires that the
that global constructors and destructors work. Since this linker script for your BSP be correct, this is an important test.
requires that the linker script for your BSP be correct, this is
an important test.
*File IO* *File IO*
The RTEMS File IO test is provided in The RTEMS File IO test is provided in the subdirectory
the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``. ``${RTEMS_ROOT}/testsuites/samples/fileio/``. This is an interactive test
This is an interactive test which allows the user to interact with which allows the user to interact with an ATA/IDE device. It will read the
an ATA/IDE device. It will read the partition table and allow the partition table and allow the user to dynamically mount one of the FAT32
user to dynamically mount one of the FAT32 partitions it finds. partitions it finds. Commands are also provided to write and read files on
Commands are also provided to write and read files on the disk. the disk.
*IO Stream* *IO Stream*
The RTEMS IO Stream test is provided in The RTEMS IO Stream test is provided in the subdirectory
the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``. ``${RTEMS_ROOT}/testsuites/samples/iostream/``. This test is a simple C++
This test is a simple C++ application which demonstrates that application which demonstrates that C++ iostreams are functional. This
C++ iostreams are functional. This requires that the RTEMS C++ requires that the RTEMS C++ run-time support is functioning properly. This
run-time support is functioning properly. This test is only test is only build when C++ is enabled.
build when C++ is enabled.
*Network Loopback Test* *Network Loopback Test*
The ``${RTEMS_ROOT}/testsuites/samples/loopback/`` The ``${RTEMS_ROOT}/testsuites/samples/loopback/`` directory contains a
directory contains a sample test that demonstrates the use of sample test that demonstrates the use of sockets and the loopback network
sockets and the loopback network device. It does not require device. It does not require the presence of network hardware in order to
the presence of network hardware in order to run. run. It is only built if RTEMS was configured with networking enabled.
It is only built if RTEMS was configured with networking enabled.
*Minimum Size Test* *Minimum Size Test*
The directory``${RTEMS_ROOT}/testsuites/samples/minimum/`` The directory ``${RTEMS_ROOT}/testsuites/samples/minimum/`` contains a
contains a simple RTEMS program that results in a non-functional simple RTEMS program that results in a non-functional executable. It is
executable. It is intended to show the size of a minimum footprint intended to show the size of a minimum footprint application based upon the
application based upon the current RTEMS configuration. current RTEMS configuration.
*Nanoseconds* *Nanoseconds*
The RTEMS Nanoseconds test is provided in
the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``. The RTEMS Nanoseconds test is provided in the subdirectory
This test demonstrates that the BSP has support for nanosecond ``${RTEMS_ROOT}/testsuites/samples/nsecs/``. This test demonstrates that
timestamp granularity. It prints the time of day and uptime multiple the BSP has support for nanosecond timestamp granularity. It prints the
times as quickly as possible. It should be possible from the output time of day and uptime multiple times as quickly as possible. It should be
to determine if your BSP has nanosecond accurate clock support possible from the output to determine if your BSP has nanosecond accurate
and it is functional. clock support and it is functional.
*Paranoia Floating Point Test* *Paranoia Floating Point Test*
The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/`` The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/`` contains the
contains the public domain floating point and math library test. public domain floating point and math library test.
*Point-to-Point Protocol Daemon* *Point-to-Point Protocol Daemon*
The RTEMS Point-to-Point Protocol Daemon test is provided in The RTEMS Point-to-Point Protocol Daemon test is provided in the
the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``. subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``. This test
This test primarily serves as the baseline for a user application primarily serves as the baseline for a user application using the PPP
using the PPP protocol. protocol.
*Unlimited Object Allocation* *Unlimited Object Allocation*
The ``${RTEMS_ROOT}/testsuites/samples/unlimited/`` The ``${RTEMS_ROOT}/testsuites/samples/unlimited/`` directory contains a
directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS. 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 The sample tests are written using the Classic API so the reader should be
should be familiar with the terms used and familiar with the terms used and material presented in the *RTEMS Applications
material presented in the *RTEMS Applications Users Guide*. Users Guide*.
Hello World Hello World
=========== ===========
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/hello/ ${RTEMS_ROOT}/testsuites/samples/hello/
It provides a rudimentary test of the BSP start up It provides a rudimentary test of the BSP start up code and the console output
code and the console output routine. The C version of this routine. The C version of this sample application uses the printf function
sample application uses the printf function from the RTEMS from the RTEMS Standard C Library to output messages. The Ada version of this
Standard C Library to output messages. The Ada version of this sample uses the TEXT_IO package to output the hello messages. The following
sample uses the TEXT_IO package to output the hello messages. messages are printed:
The following messages are printed:
.. code:: c
*** HELLO WORLD TEST \*** .. code-block:: c
*** HELLO WORLD TEST ***
Hello World Hello World
\*** END OF HELLO WORLD TEST \*** *** END OF HELLO WORLD TEST ***
These messages are printed from the application's These messages are printed from the application's single initialization task.
single initialization task. If the above messages are not If the above messages are not printed correctly, then either the BSP start up
printed correctly, then either the BSP start up code or the code or the console output routine is not operating properly.
console output routine is not operating properly.
Clock Tick Clock Tick
========== ==========
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/ticker/ ${RTEMS_ROOT}/testsuites/samples/ticker/
This application is designed as a simple test of the This application is designed as a simple test of the clock tick device driver.
clock tick device driver. In addition, this application also In addition, this application also tests the printf function from the RTEMS
tests the printf function from the RTEMS Standard C Library by Standard C Library by using it to output the following messages:
using it to output the following messages:
.. code:: c
*** CLOCK TICK TEST \*** .. code-block:: c
*** CLOCK TICK TEST ***
TA1 - tm_get - 09:00:00 12/31/1988 TA1 - tm_get - 09:00:00 12/31/1988
TA2 - 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 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 TA1 - tm_get - 09:00:30 12/31/1988
TA2 - 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 TA3 - tm_get - 09:00:30 12/31/1988
\*** END OF CLOCK TICK TEST \*** *** END OF CLOCK TICK TEST ***
The clock tick sample application utilizes a single The clock tick sample application utilizes a single initialization task and
initialization task and three copies of the single application three copies of the single application task. The initialization task prints
task. The initialization task prints the test herald, sets the the test herald, sets the time and date, and creates and starts the three
time and date, and creates and starts the three application application tasks before deleting itself. The three application tasks generate
tasks before deleting itself. The three application tasks the rest of the output. Every five seconds, one or more of the tasks will
generate the rest of the output. Every five seconds, one or print the current time obtained via the tm_get directive. The first task, TA1,
more of the tasks will print the current time obtained via the executes every five seconds, the second task, TA2, every ten seconds, and the
tm_get directive. The first task, TA1, executes every five third task, TA3, every fifteen seconds. If the time printed does not match the
seconds, the second task, TA2, every ten seconds, and the third above output, then the clock device driver is not operating properly.
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 Base Single Processor Application
================================= =================================
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/base_sp/ ${RTEMS_ROOT}/testsuites/samples/base_sp/
It provides a framework from which a single processor It provides a framework from which a single processor RTEMS application can be
RTEMS application can be developed. The use of the task argument developed. The use of the task argument is illustrated. This sample
is illustrated. This sample application uses the printf application uses the printf function from the RTEMS Standard C Library or
function from the RTEMS Standard C Library or TEXT_IO functions TEXT_IO functions when using the Ada version to output the following messages:
when using the Ada version to output the following messages:
.. code:: c
*** SAMPLE SINGLE PROCESSOR APPLICATION \*** .. code-block:: c
*** SAMPLE SINGLE PROCESSOR APPLICATION ***
Creating and starting an application task Creating and starting an application task
Application task was invoked with argument (0) and has id of 0x10002 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 The first two messages are printed from the application's single initialization
application's single initialization task. The final messages task. The final messages are printed from the single application task.
are printed from the single application task.
Base Multiple Processor Application Base Multiple Processor Application
=================================== ===================================
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/base_mp/ ${RTEMS_ROOT}/testsuites/samples/base_mp/
It provides a framework from which a multiprocessor It provides a framework from which a multiprocessor RTEMS application can be
RTEMS application can be developed. This directory has a developed. This directory has a subdirectory for each node in the
subdirectory for each node in the multiprocessor system. The multiprocessor system. The task argument is used to distinguish the node on
task argument is used to distinguish the node on which the which the application task is executed. The first node will print the
application task is executed. The first node will print the
following messages: following messages:
.. code:: c
*** SAMPLE MULTIPROCESSOR APPLICATION \*** .. code-block:: c
*** SAMPLE MULTIPROCESSOR APPLICATION ***
Creating and starting an application task Creating and starting an application task
This task was invoked with the node argument (1) This task was invoked with the node argument (1)
This task has the id of 0x10002 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: 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 Creating and starting an application task
This task was invoked with the node argument (2) This task was invoked with the node argument (2)
This task has the id of 0x20002 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 The herald is printed from the application's single initialization task on each
initialization task on each node. The final messages are node. The final messages are printed from the single application task on each
printed from the single application task on each node. node.
In this sample application, all source code is shared In this sample application, all source code is shared between the nodes except
between the nodes except for the node dependent configuration for the node dependent configuration files. These files contains the
files. These files contains the definition of the node number definition of the node number used in the initialization of the RTEMS
used in the initialization of the RTEMS Multiprocessor Multiprocessor Configuration Table. This file is not shared because the node
Configuration Table. This file is not shared because the node number field in the RTEMS Multiprocessor Configuration Table must be unique on
number field in the RTEMS Multiprocessor Configuration Table each node.
must be unique on each node.
Constructor/Destructor C++ Application Constructor/Destructor C++ Application
====================================== ======================================
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/cdtest/ ${RTEMS_ROOT}/testsuites/samples/cdtest/
This sample application demonstrates that RTEMS is This sample application demonstrates that RTEMS is compatible with C++
compatible with C++ applications. It uses constructors, applications. It uses constructors, destructor, and I/O stream output in
destructor, and I/O stream output in testing these various testing these various capabilities. The board support package responsible for
capabilities. The board support package responsible for this this application must support a C++ environment.
application must support a C++ environment.
This sample application uses the printf function from This sample application uses the printf function from the RTEMS Standard C
the RTEMS Standard C Library to output the following messages: 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 1 for 0x400010cc.
Hey I'M in base class constructor number 2 for 0x400010d4. Hey I'M in base class constructor number 2 for 0x400010d4.
Hey I'M in derived class constructor number 3 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 4 for 0x4009ee08.
Hey I'M in base class constructor number 5 for 0x4009ee10. Hey I'M in base class constructor number 5 for 0x4009ee10.
Hey I'M in base class constructor number 6 for 0x4009ee18. 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 Instantiation order 5
Hey I'M in base class constructor number 4 for 0x4009ee08. Hey I'M in base class constructor number 4 for 0x4009ee08.
Instantiation order 5 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 3 for 0x400010d4.
Hey I'M in base class constructor number 2 for 0x400010d4. Hey I'M in base class constructor number 2 for 0x400010d4.
Hey I'M in base class constructor number 1 for 0x400010cc. 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: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/minimum/ ${RTEMS_ROOT}/testsuites/samples/minimum/
This sample application is designed to produce the This sample application is designed to produce the minimum code space required
minimum code space required for any RTEMS application for any RTEMS application based upon the current RTEMS configuration and BSP.
based upon the current RTEMS configuration and In many situations, the bulk of this executable consists of hardware and RTEMS
BSP. In many situations, the bulk of this executable initialization, basic infrastructure such as malloc(), and RTEMS and hardware
consists of hardware and RTEMS initialization, basic shutdown support.
infrastructure such as malloc(), and RTEMS and
hardware shutdown support.
Nanosecond Granularity Application Nanosecond Granularity Application
================================== ==================================
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/nsecs/ ${RTEMS_ROOT}/testsuites/samples/nsecs/
This sample application exercises the Clock Driver This sample application exercises the Clock Driver for this BSP and
for this BSP and demonstrates its ability to generate demonstrates its ability to generate accurate timestamps. This application
accurate timestamps. This application does this by does this by exercising the time subsystem in three ways:
exercising the time subsystem in three ways:
- Obtain Time of Day Twice Back to Back - 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 - Use System Up Time to Measure Loops
The following is an example of what the output of this The following is an example of what the output of this test may appear like:
test may appear like:
.. code:: c
*** NANOSECOND CLOCK TEST \*** .. code-block:: c
*** NANOSECOND CLOCK TEST ***
10 iterations of getting TOD 10 iterations of getting TOD
Start: Sat Mar 24 11:15:00 2007:540000 Start: Sat Mar 24 11:15:00 2007:540000
Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000 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 80000 0:151519000 0:153260000 --> 0:1741000
loop of 90000 0:156145000 0:158099000 --> 0:1954000 loop of 90000 0:156145000 0:158099000 --> 0:1954000
loop of 100000 0:160770000 0:162942000 --> 0:2172000 loop of 100000 0:160770000 0:162942000 --> 0:2172000
\*** END OF NANOSECOND CLOCK TEST \*** *** END OF NANOSECOND CLOCK TEST ***
Paranoia Floating Point Application Paranoia Floating Point Application
=================================== ===================================
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/paranoia/ ${RTEMS_ROOT}/testsuites/samples/paranoia/
This sample application uses a public domain floating This sample application uses a public domain floating point and math library
point and math library test to verify these capabilities of the test to verify these capabilities of the RTEMS executive. Deviations between
RTEMS executive. Deviations between actual and expected results actual and expected results are reported to the screen. This is a very
are reported to the screen. This is a very extensive test which extensive test which tests all mathematical and number conversion functions.
tests all mathematical and number conversion functions. Paranoia is also very large and requires a long period of time to run.
Paranoia is also very large and requires a long period of time Problems which commonly prevent this test from executing to completion include
to run. Problems which commonly prevent this test from stack overflow and FPU exception handlers not installed.
executing to completion include stack overflow and FPU exception
handlers not installed.
Network Loopback Test Network Loopback Test
===================== =====================
This sample application is in the following directory: This sample application is in the following directory:
.. code:: c
.. code-block:: c
${RTEMS_ROOT}/testsuites/samples/loopback/ ${RTEMS_ROOT}/testsuites/samples/loopback/
This sample application uses the network loopback device to This sample application uses the network loopback device to demonstrate the use
demonstrate the use of the RTEMS TCP/IP stack. This sample of the RTEMS TCP/IP stack. This sample test illustrates the basic
test illustrates the basic configuration and initialization configuration and initialization of the TCP/IP stack as well as simple socket
of the TCP/IP stack as well as simple socket usage. usage.
.. COMMENT: COPYRIGHT (c) 1989-2007.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

122
develenv/utilities.rst
View File

@ -3,25 +3,22 @@
RTEMS Specific Utilities RTEMS Specific Utilities
######################## ########################
This section describes the additional commands This section describes the additional commands available within the *RTEMS
available within the *RTEMS Development Environment*. Although Development Environment*. Although some of these commands are of general use,
some of these commands are of general use, most are included to most are included to provide some capability necessary to perform a required
provide some capability necessary to perform a required function function in the development of the RTEMS executive, one of its support
in the development of the RTEMS executive, one of its support
components, or an RTEMS based application. components, or an RTEMS based application.
Some of the commands are implemented as C programs. Some of the commands are implemented as C programs. However, most commands are
However, most commands are implemented as Bourne shell scripts. implemented as Bourne shell scripts. Even if the current user has selected a
Even if the current user has selected a different shell, the different shell, the scripts will automatically invoke the Bourne shell during
scripts will automatically invoke the Bourne shell during their their execution lifetime.
execution lifetime.
The commands are presented in UNIX manual page style The commands are presented in UNIX manual page style for compatibility and
for compatibility and convenience. A standard set of paragraph convenience. A standard set of paragraph headers were used for all of the
headers were used for all of the command descriptions. If a command descriptions. If a section contained no data, the paragraph header was
section contained no data, the paragraph header was omitted to omitted to conserve space. Each of the permissible paragraph headers and their
conserve space. Each of the permissible paragraph headers and contents are described below:
their contents are described below:
``SYNOPSIS`` ``SYNOPSIS``
describes the command syntax describes the command syntax
@ -47,21 +44,18 @@ their contents are described below:
``SEE ALSO`` ``SEE ALSO``
lists any relevant commands which can be consulted lists any relevant commands which can be consulted
Most environment variables referenced by the commands Most environment variables referenced by the commands are defined for the RTEMS
are defined for the RTEMS Development Environment during the Development Environment during the login procedure. During login, the user
login procedure. During login, the user selects a default RTEMS selects a default RTEMS environment through the use of the Modules package.
environment through the use of the Modules package. This tool This tool effectively sets the environment variables to provide a consistent
effectively sets the environment variables to provide a development environment for a specific user. Additional environment variables
consistent development environment for a specific user. within the RTEMS environment were set by the system administrator during
Additional environment variables within the RTEMS environment installation. When specifying paths, a command description makes use of these
were set by the system administrator during installation. When
specifying paths, a command description makes use of these
environment variables. environment variables.
When referencing other commands in the SEE ALSO When referencing other commands in the SEE ALSO paragraph, the following
paragraph, the following notation is used: command(code). notation is used: command(code). Where command is the name of a related
Where command is the name of a related command, and code is a command, and code is a section number. Valid section numbers are as follows:
section number. Valid section numbers are as follows:
``1`` ``1``
Section 1 of the standard UNIX documentation Section 1 of the standard UNIX documentation
@ -72,31 +66,27 @@ section number. Valid section numbers are as follows:
``1R`` ``1R``
a manual page from this document, the RTEMS Development Environment Guide a manual page from this document, the RTEMS Development Environment Guide
For example, ls(1) means see the standard ls command For example, ``ls(1)`` means see the standard ls command in section 1 of the
in section 1 of the UNIX documentation. gcc020(1G) means see UNIX documentation. gcc020(1G) means see the description of gcc020 in section
the description of gcc020 in section 1 of the GNU documentation. 1 of the GNU documentation.
.. COMMENT: packhex
packhex - Compress Hexadecimal File packhex - Compress Hexadecimal File
=================================== ===================================
**SYNOPSIS** **SYNOPSIS**
.. code:: c .. code-block:: c
packhex <source >destination packhex <source >destination
**DESCRIPTION** **DESCRIPTION**
packhex accepts Intel Hexadecimal or Motorola Srecord packhex accepts Intel Hexadecimal or Motorola Srecord on its standard input and
on its standard input and attempts to pack as many contiguous attempts to pack as many contiguous bytes as possible into a single hexadecimal
bytes as possible into a single hexadecimal record. Many record. Many programs output hexadecimal records which are less than 80 bytes
programs output hexadecimal records which are less than 80 bytes long (for human viewing). The overhead required by each unnecessary record is
long (for human viewing). The overhead required by each significant and packhex can often reduce the size of the download image by 20%.
unnecessary record is significant and packhex can often reduce packhex attempts to output records which are as long as the hexadecimal format
the size of the download image by 20%. packhex attempts to
output records which are as long as the hexadecimal format
allows. allows.
**OPTIONS** **OPTIONS**
@ -105,41 +95,37 @@ This command has no options.
**EXAMPLES** **EXAMPLES**
Assume the current directory contains the Motorola Assume the current directory contains the Motorola Srecord file
Srecord file download.sr. Then executing the command: download.sr. Then executing the command:
.. code:: c
.. code-block:: c
packhex <download.sr >packed.sr packhex <download.sr >packed.sr
will generate the file packed.sr which is usually will generate the file packed.sr which is usually smaller than download.sr.
smaller than download.sr.
**CREDITS** **CREDITS**
The source for packhex first appeared in the May 1993 The source for packhex first appeared in the May 1993 issue of Embedded Systems
issue of Embedded Systems magazine. The code was downloaded magazine. The code was downloaded from their BBS. Unfortunately, the author's
from their BBS. Unfortunately, the author's name was not name was not provided in the listing.
provided in the listing.
.. COMMENT: unhex
unhex - Convert Hexadecimal File into Binary Equivalent unhex - Convert Hexadecimal File into Binary Equivalent
======================================================= =======================================================
**SYNOPSIS** **SYNOPSIS**
.. code:: c .. code-block:: c
unhex \[-valF] \[-o file] \[file \[file ...] ] unhex [-valF] [-o file] [file [file ...] ]
**DESCRIPTION** **DESCRIPTION**
unhex accepts Intel Hexadecimal, Motorola Srecord, or unhex accepts Intel Hexadecimal, Motorola Srecord, or TI 'B' records and
TI 'B' records and converts them to their binary equivalent. converts them to their binary equivalent. The output may sent to standout or
The output may sent to standout or may be placed in a specified may be placed in a specified file with the -o option. The designated output
file with the -o option. The designated output file may not be file may not be an input file. Multiple input files may be specified with
an input file. Multiple input files may be specified with their their outputs logically concatenated into the output file.
outputs logically concatenated into the output file.
**OPTIONS** **OPTIONS**
@ -149,8 +135,7 @@ This command has the following options:
Verbose Verbose
``a base`` ``a base``
First byte of output corresponds with base First byte of output corresponds with base address
address
``l`` ``l``
Linear Output Linear Output
@ -163,10 +148,9 @@ This command has the following options:
**EXAMPLES** **EXAMPLES**
The following command will create a binary equivalent The following command will create a binary equivalent file for the two Motorola
file for the two Motorola S record files in the specified output S record files in the specified output file binary.bin:
file binary.bin:
.. code:: c .. code-block:: c
unhex -o binary.bin downloadA.sr downloadB.sr unhex -o binary.bin downloadA.sr downloadB.sr