From 9b53679540443784bc0dba6426b1a8a2da9f6b37 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 27 Oct 2016 16:12:50 -0700 Subject: Fix develenv. Needs more fixes. --- develenv/command.rst | 3 - develenv/directory.rst | 739 +++++++++++++++++++--------------------------- develenv/index.rst | 59 ++-- develenv/introduction.rst | 74 ++--- develenv/sample.rst | 373 +++++++++++------------ develenv/utilities.rst | 122 ++++---- 6 files changed, 603 insertions(+), 767 deletions(-) (limited to 'develenv') 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 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 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 -- cgit v1.2.3