From aa4142936ed9a010b5982630f4116023e77b3b1d Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 18 Feb 2003 16:16:12 +0000 Subject: 2003-02-18 Joel Sherrill * Makefile.am, develenv.texi: Relect generating .texi from .t's. * direct.t, sample.t, utils.t: New files. * direct.texi, sample.texi, utils.texi: Removed. Now generated from corresponding .t files which are in the process of being updated. This commit is a anspshot of the update effort. --- doc/develenv/ChangeLog | 7 + doc/develenv/Makefile.am | 19 +- doc/develenv/develenv.texi | 4 +- doc/develenv/direct.t | 660 ++++++++++++++++++++++++++++++++++++++++ doc/develenv/direct.texi | 730 --------------------------------------------- doc/develenv/sample.t | 252 ++++++++++++++++ doc/develenv/sample.texi | 287 ------------------ doc/develenv/utils.t | 267 +++++++++++++++++ doc/develenv/utils.texi | 312 ------------------- 9 files changed, 1206 insertions(+), 1332 deletions(-) create mode 100644 doc/develenv/direct.t delete mode 100644 doc/develenv/direct.texi create mode 100644 doc/develenv/sample.t delete mode 100644 doc/develenv/sample.texi create mode 100644 doc/develenv/utils.t delete mode 100644 doc/develenv/utils.texi diff --git a/doc/develenv/ChangeLog b/doc/develenv/ChangeLog index 9c167a1eea..db5672d973 100644 --- a/doc/develenv/ChangeLog +++ b/doc/develenv/ChangeLog @@ -1,3 +1,10 @@ +2003-02-18 Joel Sherrill + + * Makefile.am, develenv.texi: Relect generating .texi from .t's. + * direct.t, sample.t, utils.t: New files. + * direct.texi, sample.texi, utils.texi: Removed. Now generated from + corresponding .t files which are in the process of being updated. + This commit is a anspshot of the update effort. 2003-01-25 Ralf Corsepius * develenv.texi: Set @setfilename develenv.info. diff --git a/doc/develenv/Makefile.am b/doc/develenv/Makefile.am index 6e1e332681..c47f006b01 100644 --- a/doc/develenv/Makefile.am +++ b/doc/develenv/Makefile.am @@ -15,8 +15,25 @@ include $(top_srcdir)/main.am FILES = compile.texi direct.texi intro.texi sample.texi utils.texi +GENERATED_FILES = direct.texi sample.texi utils.texi + COMMON_FILES = $(top_srcdir)/common/setup.texi \ $(top_srcdir)/common/cpright.texi info_TEXINFOS = develenv.texi -develenv_TEXINFOS = $(FILES) $(COMMON_FILES) +develenv_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) + +$(srcdir)/direct.texi: direct.t + $(BMENU2) -p "Introduction" \ + -u "Top" \ + -n "Sample Applications" < $< > $@ + +$(srcdir)/sample.texi: sample.t + $(BMENU2) -p "Directory Structure Test Suite Source Directory" \ + -u "Top" \ + -n "RTEMS Specific Utilities" < $< > $@ + +$(srcdir)/utils.texi: utils.t + $(BMENU2) -p "Sample Applications Paranoia Floating Point Application" \ + -u "Top" \ + -n "Command and Variable Index" < $< > $@ diff --git a/doc/develenv/develenv.texi b/doc/develenv/develenv.texi index 58e46e4c8c..473611eccc 100644 --- a/doc/develenv/develenv.texi +++ b/doc/develenv/develenv.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename develenv.info +@setfilename develenv @setcontentsaftertitlepage @syncodeindex vr fn @synindex ky cp @@ -98,7 +98,7 @@ This is the online version of the RTEMS Development Environment Guide. @c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here @c -@node Command and Variable Index, Concept Index, RTEMS Specific Utilities Ada Language Specific Utilities, Top +@node Command and Variable Index, Concept Index, RTEMS Specific Utilities size_rtems - report RTEMS size information, Top @unnumbered Command and Variable Index There are currently no Command and Variable Index entries. diff --git a/doc/develenv/direct.t b/doc/develenv/direct.t new file mode 100644 index 0000000000..4be84aa9e8 --- /dev/null +++ b/doc/develenv/direct.t @@ -0,0 +1,660 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Directory Structure + +The RTEMS directory structure is designed to meet +the following requirements: + +@itemize @bullet +@item encourage development of modular components. + +@item isolate processor and target dependent code, while +allowing as much common source code as possible to be shared +across multiple processors and target boards. + +@item allow multiple RTEMS users to perform simultaneous +compilation of RTEMS and its support facilities for different +processors and targets. +@end itemize + +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. + +@c +@c Directory Organization +@c +@section Directory Organization + +The RTEMS source tree is organized based on the +following variables: + +@itemize @bullet + +@item functionality, +@item target processor family, +@item target processor model, +@item peripherals, and +@item target board. + +@end itemize + +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 @code{$@{RTEMS_ROOT@}} in this discussion. + +@c +@c Top Level Tree +@c + +@c @ifset use-ascii +@example +@group + rtems-VERSION + | + +--------+----+----+----+--+-----+---+------+-----+ + | | | | | | | | | +aclocal automake c contrib cpukit doc make scripts tools +@end group +@end example +@c @end ifset + +@ifset use-tex +@end ifset + +@ifset use-html +@html +@end html +@end ifset + +@table @code +@item $@{RTEMS_ROOT@}/aclocal/ +This directory contains the custom M4 macros which are available to +the various GNU autoconf @code{configure.ac} scripts throughout +the RTEMS source tree. GNU autoconf interprets @code{configure.ac} +files to produce the @code{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. + +@item $@{RTEMS_ROOT@}/automake/ +This directory contains the custom GNU automake fragments +which are used to support the various @code{Makefile.am} +files throughout the RTEMS source tree. The +contents of this directory will not be discussed +further in this document. + +@item $@{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 @ref{Directory Structure c/ Directory} section. + +@item $@{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 Cygwin and Solaris. The +cross-compilers produced using these specifications are then +used in a Canadian cross build procedure to produce the Cygwin +and Solaris hosted RTEMS toolsets on a GNU/Linux host. This +directory will not be discussed further in this document. + +@item $@{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 the +contents of this directory can be compiled like the +C Library (@code{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 @ref{Directory Structure CPUKit Directory} section. + +@item $@{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 @ref{Directory Structure Documentation Directory} section. + +@item $@{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 @code{custom/} +subdirectory. Each ".cfg" file in this directory +is associated with a specific BSP and describes +the CPU model, compiler flags, and procedure to +a produce an executable for the target board. +These files are described in detail in the +@b{RTEMS BSP and Device Driver Development Guide} +and will not be discussed further in this document. + +@item $@{RTEMS_ROOT@}/scripts/ +This directory contains the 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 including @code{binutils/}, @code{gcc3newlib/}, +and @code{gdb/}. This directory is configured, built, +and installed separately from the RTEMS executive +and tests. This directory will not be discussed further +in this document. + +@item $@{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 @ref{RTEMS Specific Utilities}. These are the +only components of this subtree that will be discussed in this +document. + +@end table + + + +@c +@c c/ Directions +@c +@subsection c/ Directory + +The @code{$@{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: + +@table @code +@item $@{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 various Test Suites as well +as CPU model and BSP dependent libraries. The contents of +this directory are discussed in the +@ref{Directory Structure c/src/ Directory} section. + +@item $@{RTEMS_ROOT@}/c/make/ +This directory is used to generate the file @code{target.cfg} +which is 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. + +@end table + +@c +@c c/src/ Directory +@c +@subsubsection 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 +directorie and a description of each. + +@table @code +@item $@{RTEMS_ROOT@}/c/src/ada-tests/ +This directory contains the test suite for the Ada +language bindings to the Classic API. + +@item $@{RTEMS_ROOT@}/c/src/lib/ + +@item $@{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, and real-time clocks. + +@item $@{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 @code{/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. + +@item $@{RTEMS_ROOT@}/c/src/libnetworking/ +This directory contains the networking components which +might be tailored based upon the particular BSP. This +includes the RTEMS telnetd, httpd, and ftpd servers. + +@item $@{RTEMS_ROOT@}/c/src/librdbg/ +This directory contains the Ethernet-based remote debugging +stub. This software must be built to be intimately aware +of a particular CPU model. + +@item $@{RTEMS_ROOT@}/c/src/librtems++/ + +@item $@{RTEMS_ROOT@}/c/src/make/ + +@item $@{RTEMS_ROOT@}/c/src/optman/ + +@item $@{RTEMS_ROOT@}/c/src/tests/ +This directory contains the test suites for the +various RTEMS APIs and support libraries. This +contents of this directory are discussed in the +@ref{Directory Structure Test Suites} section. + +@item $@{RTEMS_ROOT@}/c/src/wrapup/ + +@end table + +@c +@c Test Suites +@c +@lowersections +@subsubsection Test Suites + +The following table lists the test suites currently included with the +RTEMS and the directory in which they may be located: + +@table @code + +@item @{RTEMS_ROOT@}c/src/tests/itrontests +ITRON API Tests + +@item @{RTEMS_ROOT@}c/src/tests/libtests +Support Library Tests + +@item @{RTEMS_ROOT@}c/src/tests/mptests +Classic API Multiprocessor Tests + +@item @{RTEMS_ROOT@}c/src/tests/psxtests +POSIX API Tests + +@item @{RTEMS_ROOT@}c/src/tests/samples +Sample Applications + +@item @{RTEMS_ROOT@}c/src/tests/sptests +Classic API Single Processor Tests + +@item @{RTEMS_ROOT@}c/src/tests/support +Test Support Software + +@item @{RTEMS_ROOT@}c/src/tests/tmitrontests +ITRON API Timing Tests + +@item @{RTEMS_ROOT@}c/src/tests/tmtests +Classic API Timing Tests + +@item @{RTEMS_ROOT@}c/src/tests/tools +XXX + +@end table + +@raisesections + + +@c +@c CPUKit Directory +@c +@subsection CPUKit Directory + +The @code{cpukit/} directory structure is as follows: + +@c +@c CPUKit Tree +@c + +@ifset use-ascii +@example +@group + CPUKit + | + +-----------+----------+-----------+----------+ + | | | | | +posix rtems sapi score wrapup +@end group +@end example +@end ifset + +This 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. @code{score/} directory) +source code files are separated into +distinct directory trees. The @code{rtems/}, @code{posix/}, and +@code{itron/} subdirectories contain the C language source files for each +module comprising the respective API. Also included in this +directory are the subdirectories @code{sapi/} and @code{score/} which are +the SuperCore modules. Within the @code{score/} directory the CPU +dependent modules are found. + +The @code{score/cpu/} subdirectory contains a subdirectory for each +target CPU supported by the @value{RELEASE} 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. + + +@c +@c +@c +@subsection Documentation Directory + +XXX + +@c +@c +@c +@subsection Support Library Source Directory + +The "lib" directory contains the support libraries and BSPS. +Board support packages (BSPs), processor environment start up code, +C library support, the FreeBSD TCP/IP stack, common BSP header files, +and miscellaneous support functions are provided in the subdirectories. +These are combined with the RTEMS executive object to form the single +RTEMS library which installed. + +@c +@c Tree 6 - Libraries +@c + + +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. + +@c +@c Tree 7 - C BSP Library +@c + +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 breaking down into specific target board +environments. The "shmdr" subdirectory provides the +implementation of a shared memory driver which supports the +multiprocessing portion of the executive. In addition, two +starting point subdirectories are provided for reference. The +"no_cpu" subdirectory provides a template BSP which can be used +to develop a specific BSP for an unsupported target board. The +"stubdr" subdirectory provides stubbed out BSPs. These files +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. + +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: + +@c +@c Tree 8 - Each BSP +@c + +@ifset use-ascii +@example +@group + Each BSP + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +clock console include shmsupp startup timer +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 10.0em +\hskip 10.25em\hbox to 4.50em{\hss{Each BSP}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 10.0em +\hskip 12.50em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 1.25em\vrule width11.25em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width11.25em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 1.25em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 0.00em\hbox to 2.50em{\hss{clock}\hss}% +\hskip 1.50em\hbox to 3.50em{\hss{console}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{include}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{shmsupp}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{startup}\hss}% +\hskip 1.50em\hbox to 2.50em{\hss{timer}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html +@example +@group + Each BSP + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +clock console include ... startup timer +@end group +@end example +@html +@end html +@end ifset + +@c +@c +@c +@subsection Test Suite Source Directory + +The "tests" directory structure for the C +implementation is as follows: + +@c +@c Tree 9 - C Tests +@c + +@ifset use-ascii +@example +@group + C Tests + | + +----------+---------+----------+---------+---------+---------+ + | | | | | | | +libtests sptests support tmtests mptests psxtest samples +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 05.0em +\hskip 14.50em\hbox to 3.50em{\hss{C Tests}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 05.0em +\hskip 16.25em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width14.25em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width14.25em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 0.00em\hbox to 4.00em{\hss{libtests}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{sptests}\hss}% +\hskip 1.25em\hbox to 3.50em{\hss{support}\hss}% +\hskip 1.25em\hbox to 3.50em{\hss{tmtests}\hss}% +\hskip 1.25em\hbox to 3.50em{\hss{mptests}\hss}% +\hskip 1.75em\hbox to 2.50em{\hss{tools}\hss}% +\hskip 1.75em\hbox to 3.50em{\hss{samples}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html +@example +@group + C Tests + | + +----------+---------+----------+---------+---------+---------+ + | | | | | | | +libtests sptests support tmtests mptests tools samples +@end group +@end example +@html +@end html +@end ifset + +This directory provides the entire RTEMS Test Suite +which 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 "sptests" subdirectory consists of twenty-four +tests designed to cover the entire executive code. The +"spfatal" test will verify any code associated with the +occurrence of a fatal error. Also provided is a test which +will determine the size of the RTEMS executive. + +The multiprocessor test are provided in "mptests". +Fourteen tests are provided in this subdirectory which address +two node configurations and cover the multiprocessor code found +in RTEMS. + +Tests that time each directive and a set of critical +executive functions are provided in the "tmtests" subdirectory. +Within this subdirectory thirty-one tests are provided along +with a subdirectory to contain each targets timing results. + +The "samples" directory structure for the C +implementation is as follows: + +@c +@c Tree 10 - C Samples +@c + +@ifset use-ascii +@example +@group + C Samples + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +base_mp base_sp cdtest hello paranoia ticker +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 05.0em +\hskip 12.25em\hbox to 4.50em{\hss{C Samples}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 05.0em +\hskip 14.50em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width12.50em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width12.50em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 0.00em\hbox to 4.00em{\hss{base\_mp}\hss}% +\hskip 1.00em\hbox to 4.00em{\hss{base\_sp}\hss}% +\hskip 1.50em\hbox to 3.00em{\hss{cdtest}\hss}% +\hskip 2.25em\hbox to 2.50em{\hss{hello}\hss}% +\hskip 1.75em\hbox to 4.00em{\hss{paranoia}\hss}% +\hskip 1.50em\hbox to 3.00em{\hss{ticker}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html +@example +@group + C Samples + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +base_mp base_sp cdtest hello paranoia ticker +@end group +@end example +@html +@end html +@end ifset + +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. A Hello World test is provided in +the subdirectory "hello". This test is helpful when testing new +versions of RTEMS, BSPs, or modifications to any portion of the +RTEMS development environment. The "ticker" subdirectory +provides a test for verification of clock chip device drivers of +BSPs. A simple single processor test similar to those in the +single processor test suite is provided in "base_sp". A simple +two node multiprocessor test capable of testing an newly +developed MPCI layer is provided in "base_mp". The "cdtest" +subdirectory provides a simple C++ application using +constructors and destructors. The final sample test is a +public domain floating point and math library toolset test is +provided in "paranoia". diff --git a/doc/develenv/direct.texi b/doc/develenv/direct.texi deleted file mode 100644 index 5e5a3db64e..0000000000 --- a/doc/develenv/direct.texi +++ /dev/null @@ -1,730 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@ifinfo -@node Directory Structure, Directory Structure Suites, Introduction, Top -@end ifinfo -@chapter Directory Structure -@ifinfo -@menu -* Directory Structure Suites:: -@end menu -@end ifinfo - -The RTEMS directory structure is designed to meet -the following requirements: - -@itemize @bullet -@item encourage development of modular components. - -@item isolate processor and target dependent code, while -allowing as much common source code as possible to be shared -across multiple processors and targets. - -@item allow multiple RTEMS users to perform simultaneous -compilation of RTEMS and its support facilities for different -processors and targets. -@end itemize - -The resulting directory structure has processor and -target dependent source files isolated from generic files. When -RTEMS is built, object directories and an install point will be -automatically created based upon the target BSP selected. The -placement of object files based upon the selected BSP name -insures that object files are not mixed across CPUs or targets. -This in combination with the make files 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. -@ifinfo -@node Directory Structure Suites, C Suites, Directory Structure, Directory Structure -@end ifinfo -@section Suites -@ifinfo -@menu -* C Suites:: -* Executive Source Directory:: -* Support Library Source Directory:: -* Test Suite Source Directory:: -@end menu -@end ifinfo - -The RTEMS source tree is organized based on the -following four variables: - -@itemize @bullet -@item language, - -@item target processor, - -@item target board, and - -@item compiler vendor (Ada only). -@end itemize - -The language may be either C or Ada and there is -currently nothing shared between the source trees for these two -implementations of RTEMS. The user generally selects the -subdirectory for the implementation they are using and ignores -that for the other implementation. The only exceptions to this -normally occurs when comparing the source code for the two -implementations or when porting both to a new CPU or target -board. The following shows the top level RTEMS directory -structure which includes directories for each language -implementation and a language independent source documentation -directory. The source documentation directory is currently not -supported. - -@c -@c Tree 1 - Top Level -@c - -@ifset use-ascii -@example -@group - RTEMS - | -+-----------------------+-----------------------+ -| | -c doc -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 15.0em -\hskip 1.25em\hbox to 3.00em{\hss{RTEMS}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 15.0em -\hskip 2.75em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 15.0em -\hskip 0.25em\vrule width2.50em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width2.50em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 15.0em -\hskip 0.25em\vrule width.04em% -\hskip 4.92em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 15.0em -\hskip 0.00em\hbox to 0.50em{\hss{c}\hss}% -\hskip 1.50em\hbox to 1.50em{\hss{ }\hss}% -\hskip 1.00em\hbox to 1.50em{\hss{doc}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@c -@c for now continue to use the ascii -@c -@ifset use-html -@example -@group - RTEMS - | -+-----------------------+-----------------------+ -| | -c doc -@end group -@end example -@html -@end html -@end ifset - -Each of the following sections will describe the -contents of the directories in the RTEMS source -tree. - -@ifinfo -@node C Suites, Executive Source Directory, Directory Structure Suites, Directory Structure Suites -@end ifinfo -@subsection C Suites - -The following table lists the suites currently included with the -C implementation of RTEMS and the directory in which they may be located: - -@ifset use-texinfo-tables -@table @code -@item Support Libraries (BSPs, C library, CPU support) -$RTEMS_ROOT/c/src/lib - -@item Single Processor Tests -$RTEMS_ROOT/c/src/tests/sptests - -@item Timing Tests -$RTEMS_ROOT/c/src/tests/tmtests - -@item Multiprocessor Tests -$RTEMS_ROOT/c/src/tests/mptests - -@item Sample Applications -$RTEMS_ROOT/c/src/tests/samples - -@item RTEMS Build Tools -$RTEMS_SRC_BASE/c/build_tools - -@item Make Support -$RTEMS_ROOT/c/make -@end table -@end ifset - -@ifclear use-texinfo-tables -@html -
- - - - - - - - - - - - - - - -
Support Libraries (BSPs, C library, CPU support)$RTEMS_ROOT/c/src/lib
Single Processor Tests$RTEMS_ROOT/c/src/tests/sptests
Timing Tests$RTEMS_ROOT/c/src/tests/tmtests
Multiprocessor Tests$RTEMS_ROOT/c/src/tests/mptests
Sample Applications$RTEMS_ROOT/c/src/tests/samples
RTEMS Build Tools$RTEMS_SRC_BASE/c/build_tools
Make Support$RTEMS_ROOT/c/make
-
-@end html -@end ifclear - - -The top level directory structure for the C implementation of RTEMS -is as follows: - -@c -@c Tree 2 - Top C Level -@c - -@ifset use-ascii -@example -@group - C - | - +----------+-----------+----------+ - | | | | -build_tools make src update_tools -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 08.0em -\hskip 13.00em\hbox to 0.50em{\hss{C}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 08.0em -\hskip 13.25em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 08.0em -\hskip 1.75em\vrule width11.50em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width11.50em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 08.0em -\hskip 1.75em\vrule width.04em% -\hskip 5.71em\vrule width.04em% -\hskip 5.71em\vrule width.04em% -\hskip 5.71em\vrule width.04em% -\hskip 5.71em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 08.0em -\hskip 0.00em\hbox to 3.50em{\hss{Modules}\hss}% -\hskip 1.00em\hbox to 6.00em{\hss{build\_tools}\hss}% -\hskip 1.75em\hbox to 2.00em{\hss{make}\hss}% -\hskip 4.00em\hbox to 1.50em{\hss{src}\hss}% -\hskip 1.75em\hbox to 6.50em{\hss{update\_tools}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@ifset use-html -@example -@group - C - | - +----------+-----------+----------+ - | | | | -build_tools make src update_tools -@end group -@end example -@html -@end html -@end ifset - -This directory contains the subdirectories which -contain the entire C implementation of the RTEMS executive. -The "build-tools" directory contains an assortment of support tools -for the RTEMS development environment. Two subdirectories exist -under "build-tools" which contain scripts (executables) and -source for the support tools. The "make" directory contains -configuration files and subdirectories which provide a robust -host and cross-target makefile system supporting the building of -the executive for numerous application environments. The -"update_tools" directory contains utilities which aid in the -updating from a previous version to the current version of the -RTEMS executive. - -The "src" directory structure for the C implementation of RTEMS is as follows: - -@c -@c Tree 3 - Top C src Level -@c - -@ifset use-ascii -@example -@group - C Source - | - +-----------------------+-----------------------+ - | | | -exec lib tests -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 15.0em -\hskip 2.00em\hbox to 4.00em{\hss{C Source}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 15.0em -\hskip 4.00em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 15.0em -\hskip 1.00em\vrule width3.00em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width3.00em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 15.0em -\hskip 1.00em\vrule width.04em% -\hskip 2.96em\vrule width.04em% -\hskip 2.96em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 15.0em -\hskip 0.00em\hbox to 2.00em{\hss{exec}\hss}% -\hskip 1.25em\hbox to 1.50em{\hss{lib}\hss}% -\hskip 1.00em\hbox to 2.50em{\hss{tests}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@ifset use-html -@example -@group - C Source - | - +-----------------------+-----------------------+ - | | | -exec lib tests -@end group -@end example -@html -@end html -@end ifset - -This directory contains all source files that -comprises the RTEMS executive, supported target board support -packages, and the RTEMS Test Suite. - -@ifinfo -@node Executive Source Directory, Support Library Source Directory, C Suites, Directory Structure Suites -@end ifinfo -@subsection Executive Source Directory - -The "exec" directory structure for the C implementation is as follows: - -@c -@c Tree 4 - C Executive Tree -@c - -@ifset use-ascii -@example -@group - C Executive - | - +-----------+----------+-----------+----------+ - | | | | | -posix rtems sapi score wrapup -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 10.0em -\hskip 6.00em\hbox to 5.50em{\hss{C Executive}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 10.0em -\hskip 8.75em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 10.0em -\hskip 1.25em\vrule width7.50em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width7.50em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 10.0em -\hskip 1.25em\vrule width.04em% -\hskip 3.71em\vrule width.04em% -\hskip 3.71em\vrule width.04em% -\hskip 3.71em\vrule width.04em% -\hskip 3.71em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 10.0em -\hskip 0.00em\hbox to 2.50em{\hss{posix}\hss}% -\hskip 1.25em\hbox to 2.50em{\hss{rtems}\hss}% -\hskip 1.50em\hbox to 2.00em{\hss{sapi}\hss}% -\hskip 1.50em\hbox to 2.50em{\hss{score}\hss}% -\hskip 1.00em\hbox to 3.00em{\hss{wrapup}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@ifset use-html -@example -@group - C Executive - | - +-----------+----------+-----------+----------+ - | | | | | -posix rtems sapi score wrapup -@end group -@end example -@html -@end html -@end ifset - -This directory contains a set of subdirectories which -contains the source files comprising the executive portion of -the RTEMS development environment. At this point the API -specific and "supercore" source code files are separated into -distinct directory trees. The "rtems" and the "posix" -subdirectories contain the C language source files for each -module comprising the respective API. Also included in this -directory are the subdirectories "sapi" and "score" which are -the supercore modules. Within the "score" directory the CPU -dependent modules are found. - -The "cpu" directory contains a subdirectory for each -target CPU supported by the @value{RELEASE} 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. - -@ifinfo -@node Support Library Source Directory, Test Suite Source Directory, Executive Source Directory, Directory Structure Suites -@end ifinfo -@subsection Support Library Source Directory - -The "lib" directory contains the support libraries and BSPS. -Board support packages (BSPs), processor environment start up code, -C library support, the FreeBSD TCP/IP stack, common BSP header files, -and miscellaneous support functions are provided in the subdirectories. -These are combined with the RTEMS executive object to form the single -RTEMS library which installed. - -@c -@c Tree 6 - Libraries -@c - - -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. - -@c -@c Tree 7 - C BSP Library -@c - -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 breaking down into specific target board -environments. The "shmdr" subdirectory provides the -implementation of a shared memory driver which supports the -multiprocessing portion of the executive. In addition, two -starting point subdirectories are provided for reference. The -"no_cpu" subdirectory provides a template BSP which can be used -to develop a specific BSP for an unsupported target board. The -"stubdr" subdirectory provides stubbed out BSPs. These files -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. - -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: - -@c -@c Tree 8 - Each BSP -@c - -@ifset use-ascii -@example -@group - Each BSP - | - +-----------+----------+-----+-----+----------+----------+ - | | | | | | -clock console include shmsupp startup timer -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 10.0em -\hskip 10.25em\hbox to 4.50em{\hss{Each BSP}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 10.0em -\hskip 12.50em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 10.0em -\hskip 1.25em\vrule width11.25em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width11.25em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 10.0em -\hskip 1.25em\vrule width.04em% -\hskip 4.46em\vrule width.04em% -\hskip 4.46em\vrule width.04em% -\hskip 4.46em\vrule width.04em% -\hskip 4.46em\vrule width.04em% -\hskip 4.46em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 10.0em -\hskip 0.00em\hbox to 2.50em{\hss{clock}\hss}% -\hskip 1.50em\hbox to 3.50em{\hss{console}\hss}% -\hskip 1.00em\hbox to 3.50em{\hss{include}\hss}% -\hskip 1.00em\hbox to 3.50em{\hss{shmsupp}\hss}% -\hskip 1.00em\hbox to 3.50em{\hss{startup}\hss}% -\hskip 1.50em\hbox to 2.50em{\hss{timer}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@ifset use-html -@example -@group - Each BSP - | - +-----------+----------+-----+-----+----------+----------+ - | | | | | | -clock console include ... startup timer -@end group -@end example -@html -@end html -@end ifset - -@ifinfo -@node Test Suite Source Directory, Sample Applications, Support Library Source Directory, Directory Structure Suites -@end ifinfo -@subsection Test Suite Source Directory - -The "tests" directory structure for the C -implementation is as follows: - -@c -@c Tree 9 - C Tests -@c - -@ifset use-ascii -@example -@group - C Tests - | - +----------+---------+----------+---------+---------+---------+ - | | | | | | | -libtests sptests support tmtests mptests psxtest samples -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 05.0em -\hskip 14.50em\hbox to 3.50em{\hss{C Tests}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 05.0em -\hskip 16.25em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 05.0em -\hskip 2.00em\vrule width14.25em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width14.25em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 05.0em -\hskip 2.00em\vrule width.04em% -\hskip 4.71em\vrule width.04em% -\hskip 4.71em\vrule width.04em% -\hskip 4.71em\vrule width.04em% -\hskip 4.71em\vrule width.04em% -\hskip 4.71em\vrule width.04em% -\hskip 4.71em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 05.0em -\hskip 0.00em\hbox to 4.00em{\hss{libtests}\hss}% -\hskip 1.00em\hbox to 3.50em{\hss{sptests}\hss}% -\hskip 1.25em\hbox to 3.50em{\hss{support}\hss}% -\hskip 1.25em\hbox to 3.50em{\hss{tmtests}\hss}% -\hskip 1.25em\hbox to 3.50em{\hss{mptests}\hss}% -\hskip 1.75em\hbox to 2.50em{\hss{tools}\hss}% -\hskip 1.75em\hbox to 3.50em{\hss{samples}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@ifset use-html -@example -@group - C Tests - | - +----------+---------+----------+---------+---------+---------+ - | | | | | | | -libtests sptests support tmtests mptests tools samples -@end group -@end example -@html -@end html -@end ifset - -This directory provides the entire RTEMS Test Suite -which 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 "sptests" subdirectory consists of twenty-four -tests designed to cover the entire executive code. The -"spfatal" test will verify any code associated with the -occurrence of a fatal error. Also provided is a test which -will determine the size of the RTEMS executive. - -The multiprocessor test are provided in "mptests". -Fourteen tests are provided in this subdirectory which address -two node configurations and cover the multiprocessor code found -in RTEMS. - -Tests that time each directive and a set of critical -executive functions are provided in the "tmtests" subdirectory. -Within this subdirectory thirty-one tests are provided along -with a subdirectory to contain each targets timing results. - -The "samples" directory structure for the C -implementation is as follows: - -@c -@c Tree 10 - C Samples -@c - -@ifset use-ascii -@example -@group - C Samples - | - +-----------+----------+-----+-----+----------+----------+ - | | | | | | -base_mp base_sp cdtest hello paranoia ticker -@end group -@end example -@end ifset - -@ifset use-tex -@sp 1 - -@tex -{\parskip=0pt\offinterlineskip% -\hskip 05.0em -\hskip 12.25em\hbox to 4.50em{\hss{C Samples}\hss}% -\vrule width0em height1.972ex depth0.812ex\par\penalty10000 -\hskip 05.0em -\hskip 14.50em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 05.0em -\hskip 2.00em\vrule width12.50em height-0.407ex depth0.500ex% -\vrule width.04em\vrule width12.50em height-0.407ex depth0.500ex% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 05.0em -\hskip 2.00em\vrule width.04em% -\hskip 4.96em\vrule width.04em% -\hskip 4.96em\vrule width.04em% -\hskip 4.96em\vrule width.04em% -\hskip 4.96em\vrule width.04em% -\hskip 4.96em\vrule width.04em% -\vrule width0em height1.500ex depth0.500ex\par\penalty10000 -\hskip 05.0em -\hskip 0.00em\hbox to 4.00em{\hss{base\_mp}\hss}% -\hskip 1.00em\hbox to 4.00em{\hss{base\_sp}\hss}% -\hskip 1.50em\hbox to 3.00em{\hss{cdtest}\hss}% -\hskip 2.25em\hbox to 2.50em{\hss{hello}\hss}% -\hskip 1.75em\hbox to 4.00em{\hss{paranoia}\hss}% -\hskip 1.50em\hbox to 3.00em{\hss{ticker}\hss}% -\vrule width0em height1.972ex depth0.812ex\par} -@end tex -@end ifset - -@ifset use-html -@example -@group - C Samples - | - +-----------+----------+-----+-----+----------+----------+ - | | | | | | -base_mp base_sp cdtest hello paranoia ticker -@end group -@end example -@html -@end html -@end ifset - -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. A Hello World test is provided in -the subdirectory "hello". This test is helpful when testing new -versions of RTEMS, BSPs, or modifications to any portion of the -RTEMS development environment. The "ticker" subdirectory -provides a test for verification of clock chip device drivers of -BSPs. A simple single processor test similar to those in the -single processor test suite is provided in "base_sp". A simple -two node multiprocessor test capable of testing an newly -developed MPCI layer is provided in "base_mp". The "cdtest" -subdirectory provides a simple C++ application using -constructors and destructors. The final sample test is a -public domain floating point and math library toolset test is -provided in "paranoia". diff --git a/doc/develenv/sample.t b/doc/develenv/sample.t new file mode 100644 index 0000000000..b656cc52c7 --- /dev/null +++ b/doc/develenv/sample.t @@ -0,0 +1,252 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Sample Applications + +@section Introduction + +RTEMS is shipped with the following sample applications: + +@itemize @bullet +@item Hello World - C and Ada + +@item Clock Tick - C and Ada + +@item Base Single Processor - C and Ada + +@item Base Multiple Processor - C and Ada + +@item Constructor/Destructor C++ Test - C only if C++ +enabled + +@item Paranoia Floating Point Test - C only +@end itemize + +These applications are intended to illustrate the +basic format of RTEMS single and multiple processor +applications. In addition, these relatively simple applications +can be used to test locally developed board support packages and +device drivers. + +The reader should be familiar with the terms used and +material presented in the RTEMS Applications User's Guide. + +@section Hello World + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/hello +@end example + +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 use the TEXT_IO package to output the hello messages. +The following messages are printed: + +@example +@group +*** HELLO WORLD TEST *** +Hello World +*** END OF HELLO WORLD TEST *** +@end group +@end example + +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. + +@section Clock Tick + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/ticker +@end example + +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: + +@example +@group +*** 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 +TA1 - tm_get - 09:00:05 12/31/1988 +TA1 - tm_get - 09:00:10 12/31/1988 +TA2 - tm_get - 09:00:10 12/31/1988 +TA1 - tm_get - 09:00:15 12/31/1988 +TA3 - tm_get - 09:00:15 12/31/1988 +TA1 - tm_get - 09:00:20 12/31/1988 +TA2 - tm_get - 09:00:20 12/31/1988 +TA1 - tm_get - 09:00:25 12/31/1988 +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 *** +@end group +@end example + +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. + +@section Base Single Processor Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/base_sp +@end example + +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: + +@example +@group +*** 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 group +@end example + +The first two messages are printed from the +application's single initialization task. The final messages +are printed from the single application task. + +@section Base Multiple Processor Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/base_mp +@end example + +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: + +@example +@group +*** 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 group +@end example + +The second node will print the following messages: + +@example +@group +*** 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 group +@end example + +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. + +@section Constructor/Destructor C++ Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/cdtest +@end example + +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: + +@example +@group +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 *** +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. +Hey I'M in base class constructor number 7 for 0x4009ee20. +Hey I'M in derived class constructor number 8 for 0x4009ee20. +Testing a C++ I/O stream +Hey I'M in derived class constructor number 8 for 0x4009ee20. +Derived class - Instantiation order 8 +Hey I'M in base class constructor number 7 for 0x4009ee20. +Instantiation order 8 +Hey I'M in base class constructor number 6 for 0x4009ee18. +Instantiation order 6 +Hey I'M in base class constructor number 5 for 0x4009ee10. +Instantiation order 5 +Hey I'M in base class constructor number 4 for 0x4009ee08. +Instantiation order 5 +*** 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. +@end group +@end example + +@section Paranoia Floating Point Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/paranoia +@end example + +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. diff --git a/doc/develenv/sample.texi b/doc/develenv/sample.texi deleted file mode 100644 index 8e3092d2d0..0000000000 --- a/doc/develenv/sample.texi +++ /dev/null @@ -1,287 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@ifinfo -@node Sample Applications, Sample Applications Introduction, Test Suite Source Directory, Top -@end ifinfo -@chapter Sample Applications -@ifinfo -@menu -* Sample Applications Introduction:: -* Sample Applications Hello World:: -* Sample Applications Clock Tick:: -* Sample Applications Base Single Processor Application:: -* Sample Applications Base Multiple Processor Application:: -* Sample Applications Constructor/Destructor C++ Application:: -* Sample Applications Paranoia Floating Point Application:: -@end menu -@end ifinfo - -@ifinfo -@node Sample Applications Introduction, Sample Applications Hello World, Sample Applications, Sample Applications -@end ifinfo -@section Introduction - -RTEMS is shipped with the following sample applications: - -@itemize @bullet -@item Hello World - C and Ada - -@item Clock Tick - C and Ada - -@item Base Single Processor - C and Ada - -@item Base Multiple Processor - C and Ada - -@item Constructor/Destructor C++ Test - C only if C++ -enabled - -@item Paranoia Floating Point Test - C only -@end itemize - -These applications are intended to illustrate the -basic format of RTEMS single and multiple processor -applications. In addition, these relatively simple applications -can be used to test locally developed board support packages and -device drivers. - -The reader should be familiar with the terms used and -material presented in the RTEMS Applications User's Guide. - -@ifinfo -@node Sample Applications Hello World, Sample Applications Clock Tick, Sample Applications Introduction, Sample Applications -@end ifinfo -@section Hello World - -This sample application is in the following directory: - -@example -$RTEMS_SRC_BASE/tests/samples/hello -@end example - -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 use the TEXT_IO package to output the hello messages. -The following messages are printed: - -@example -@group -*** HELLO WORLD TEST *** -Hello World -*** END OF HELLO WORLD TEST *** -@end group -@end example - -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. - -@ifinfo -@node Sample Applications Clock Tick, Sample Applications Base Single Processor Application, Sample Applications Hello World, Sample Applications -@end ifinfo -@section Clock Tick - -This sample application is in the following directory: - -@example -$RTEMS_SRC_BASE/tests/samples/ticker -@end example - -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: - -@example -@group -*** 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 -TA1 - tm_get - 09:00:05 12/31/1988 -TA1 - tm_get - 09:00:10 12/31/1988 -TA2 - tm_get - 09:00:10 12/31/1988 -TA1 - tm_get - 09:00:15 12/31/1988 -TA3 - tm_get - 09:00:15 12/31/1988 -TA1 - tm_get - 09:00:20 12/31/1988 -TA2 - tm_get - 09:00:20 12/31/1988 -TA1 - tm_get - 09:00:25 12/31/1988 -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 *** -@end group -@end example - -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. - -@ifinfo -@node Sample Applications Base Single Processor Application, Sample Applications Base Multiple Processor Application, Sample Applications Clock Tick, Sample Applications -@end ifinfo -@section Base Single Processor Application - -This sample application is in the following directory: - -@example -$RTEMS_SRC_BASE/tests/samples/base_sp -@end example - -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: - -@example -@group -*** 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 group -@end example - -The first two messages are printed from the -application's single initialization task. The final messages -are printed from the single application task. - -@ifinfo -@node Sample Applications Base Multiple Processor Application, Sample Applications Constructor/Destructor C++ Application, Sample Applications Base Single Processor Application, Sample Applications -@end ifinfo -@section Base Multiple Processor Application - -This sample application is in the following directory: - -@example -$RTEMS_SRC_BASE/tests/samples/base_mp -@end example - -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: - -@example -@group -*** 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 group -@end example - -The second node will print the following messages: - -@example -@group -*** 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 group -@end example - -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. - -@ifinfo -@node Sample Applications Constructor/Destructor C++ Application, Sample Applications Paranoia Floating Point Application, Sample Applications Base Multiple Processor Application, Sample Applications -@end ifinfo -@section Constructor/Destructor C++ Application - -This sample application is in the following directory: - -@example -$RTEMS_SRC_BASE/tests/samples/cdtest -@end example - -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: - -@example -@group -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 *** -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. -Hey I'M in base class constructor number 7 for 0x4009ee20. -Hey I'M in derived class constructor number 8 for 0x4009ee20. -Testing a C++ I/O stream -Hey I'M in derived class constructor number 8 for 0x4009ee20. -Derived class - Instantiation order 8 -Hey I'M in base class constructor number 7 for 0x4009ee20. -Instantiation order 8 -Hey I'M in base class constructor number 6 for 0x4009ee18. -Instantiation order 6 -Hey I'M in base class constructor number 5 for 0x4009ee10. -Instantiation order 5 -Hey I'M in base class constructor number 4 for 0x4009ee08. -Instantiation order 5 -*** 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. -@end group -@end example - -@ifinfo -@node Sample Applications Paranoia Floating Point Application, RTEMS Specific Utilities, Sample Applications Constructor/Destructor C++ Application, Sample Applications -@end ifinfo -@section Paranoia Floating Point Application - -This sample application is in the following directory: - -@example -$RTEMS_SRC_BASE/tests/samples/paranoia -@end example - -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. diff --git a/doc/develenv/utils.t b/doc/develenv/utils.t new file mode 100644 index 0000000000..af560486bd --- /dev/null +++ b/doc/develenv/utils.t @@ -0,0 +1,267 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter 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 +components, or an RTEMS based application. The commands have +been classified into the following categories for clarity: + +@itemize @bullet +@item C Language Specific Utilities + +@item Ada Language Specific Utilities +@end itemize + +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: + +@table @code +@item SYNOPSIS +describes the command syntax + +@item DESCRIPTION +a full description of the command + +@item OPTIONS +describes each of the permissible options for the command + +@item NOTES +lists any special noteworthy comments about the command + +@item ENVIRONMENT +describes all environment variables utilized by the command + +@item EXAMPLES +illustrates the use of the command with specific examples + +@item FILES +provides a list of major files that the command references + +@item SEE ALSO +lists any relevant commands which can be consulted +@end table + +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: + +@table @code +@item 1 +Section 1 of the standard UNIX documentation + +@item 1G +Section 1 of the GNU documentation + +@item 1R +a manual page from this document, the RTEMS Development Environment Guide +@end table + +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. + +@section C Language Specific Utilities + +The C language utilities provide a powerful set of +tools which combine to allow operations within the RTEMS +Development Environment to be consistent and easy to use. Much +effort was devoted to providing as close to the standard UNIX +and GNU style of operations as possible. Each of these +utilities are described in the section below. + +@subsection packhex - Compress Hexadecimal File + +@subheading SYNOPSIS + +@example +packhex destination +@end example + +@subheading 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 +allows. + +@subheading OPTIONS + +This command has no options. + +@subheading EXAMPLES + +Assume the current directory contains the Motorola +Srecord file download.sr. Then executing the command: + +@example +packhex packed.sr +@end example + +will generate the file packed.sr which is usually +smaller than download.sr. + +@subheading 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. + +@subsection unhex - Convert Hexadecimal File into Binary Equivalent + +@subheading SYNOPSIS + +@example +unhex [-valF] [-o file] [file [file ...] ] +@end example + +@subheading 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. + +@subheading OPTIONS + +This command has the following options: + +@table @code +@item v +Verbose + +@item a base +First byte of output corresponds with base +address + +@item l +Linear Output + +@item o file +Output File + +@item F k_bits +Fill holes in input with 0xFFs up to k_bits * 1024 bits +@end table + +@subheading EXAMPLES + +The following command will create a binary equivalent +file for the two Motorola S record files in the specified output +file binary.bin: + +@example +unhex -o binary.bin downloadA.sr downloadB.sr +@end example + +@subsection size_rtems - report RTEMS size information + +@subheading SYNOPSIS + +@example +size_rtems +@end example + +@subheading DESCRIPTION + +size_rtems analyzes RTEMS and determines all of the +critical sizing information which is reported in the related +documentation. + +@subheading EXAMPLES + +To generate the RTEMS size report for the currently +configured processor, execute the following command: + +@example +size_rtems +@end example + +Although the actual size information will differ, a +report of the following format will be output: + +@example + RTEMS SIZE REPORT + +CODE DATA BSS +================== +MANAGERS: 15988 0 0 +CORE : 4568 0 0 +CPU : 364 0 0 +OVERALL : 20556 0 0 +MINIMUM : 8752 0 0 + +init : 1592 0 0 +tasks : 2440 0 0 +intr : 64 0 0 +clock : 2252 0 0 +sem : 876 0 0 +msg : 1624 0 0 +event : 604 0 0 +signal : 212 0 0 +part : 872 0 0 +region : 844 0 0 +dpmem : 532 0 0 +timer : 424 0 0 +io : 288 0 0 +fatal : 40 0 0 +rtmon : 764 0 0 +mp : 2984 0 0 + +sem : 4 0 0 +msg : 4 0 0 +event : 4 0 0 +signal : 4 0 0 +part : 4 0 0 +region : 4 0 0 +timer : 4 0 0 +dpmem : 4 0 0 +io : 4 0 0 +rtmon : 4 0 0 +mp : 8 0 0 +@end example + +@subheading SEE ALSO + +gsize020(1G), gsize386(1G), gsize960(1G) + + diff --git a/doc/develenv/utils.texi b/doc/develenv/utils.texi deleted file mode 100644 index 1ddf4c906e..0000000000 --- a/doc/develenv/utils.texi +++ /dev/null @@ -1,312 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@ifinfo -@node RTEMS Specific Utilities, RTEMS Specific Utilities C Language Specific Utilities, Sample Applications Paranoia Floating Point Application, Top -@end ifinfo -@chapter RTEMS Specific Utilities -@ifinfo -@menu -* RTEMS Specific Utilities C Language Specific Utilities:: -* RTEMS Specific Utilities Ada Language Specific Utilities:: -@end menu -@end ifinfo - -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. The commands have -been classified into the following categories for clarity: - -@itemize @bullet -@item C Language Specific Utilities - -@item Ada Language Specific Utilities -@end itemize - -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: - -@table @code -@item SYNOPSIS -describes the command syntax - -@item DESCRIPTION -a full description of the command - -@item OPTIONS -describes each of the permissible options for the command - -@item NOTES -lists any special noteworthy comments about the command - -@item ENVIRONMENT -describes all environment variables utilized by the command - -@item EXAMPLES -illustrates the use of the command with specific examples - -@item FILES -provides a list of major files that the command references - -@item SEE ALSO -lists any relevant commands which can be consulted -@end table - -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: - -@table @code -@item 1 -Section 1 of the standard UNIX documentation - -@item 1G -Section 1 of the GNU documentation - -@item 1R -a manual page from this document, the RTEMS Development Environment Guide -@end table - -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. - -@ifinfo -@node RTEMS Specific Utilities C Language Specific Utilities, packhex - Compress Hexadecimal File, RTEMS Specific Utilities, RTEMS Specific Utilities -@end ifinfo -@section C Language Specific Utilities -@ifinfo -@menu -* packhex - Compress Hexadecimal File:: -* unhex - Convert Hexadecimal File into Binary:: -* size_rtems - report RTEMS size information:: -@end menu -@end ifinfo - -The C language utilities provide a powerful set of -tools which combine to allow operations within the RTEMS -Development Environment to be consistent and easy to use. Much -effort was devoted to providing as close to the standard UNIX -and GNU style of operations as possible. Each of these -utilities are described in the section below. - -@ifinfo -@node packhex - Compress Hexadecimal File, unhex - Convert Hexadecimal File into Binary, RTEMS Specific Utilities C Language Specific Utilities, RTEMS Specific Utilities C Language Specific Utilities -@end ifinfo -@subsection packhex - Compress Hexadecimal File - -@subheading SYNOPSIS - -@example -packhex destination -@end example - -@subheading 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 -allows. - -@subheading OPTIONS - -This command has no options. - -@subheading EXAMPLES - -Assume the current directory contains the Motorola -Srecord file download.sr. Then executing the command: - -@example -packhex packed.sr -@end example - -will generate the file packed.sr which is usually -smaller than download.sr. - -@subheading 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. - -@ifinfo -@node unhex - Convert Hexadecimal File into Binary, size_rtems - report RTEMS size information, packhex - Compress Hexadecimal File, RTEMS Specific Utilities C Language Specific Utilities -@end ifinfo -@subsection unhex - Convert Hexadecimal File into Binary Equivalent - -@subheading SYNOPSIS - -@example -unhex [-valF] [-o file] [file [file ...] ] -@end example - -@subheading 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. - -@subheading OPTIONS - -This command has the following options: - -@table @code -@item v -Verbose - -@item a base -First byte of output corresponds with base -address - -@item l -Linear Output - -@item o file -Output File - -@item F k_bits -Fill holes in input with 0xFFs up to k_bits * 1024 bits -@end table - -@subheading EXAMPLES - -The following command will create a binary equivalent -file for the two Motorola S record files in the specified output -file binary.bin: - -@example -unhex -o binary.bin downloadA.sr downloadB.sr -@end example - -@ifinfo -@node size_rtems - report RTEMS size information, RTEMS Specific Utilities Ada Language Specific Utilities, unhex - Convert Hexadecimal File into Binary, RTEMS Specific Utilities C Language Specific Utilities -@end ifinfo -@subsection size_rtems - report RTEMS size information - -@subheading SYNOPSIS - -@example -size_rtems -@end example - -@subheading DESCRIPTION - -size_rtems analyzes RTEMS and determines all of the -critical sizing information which is reported in the related -documentation. - -@subheading EXAMPLES - -To generate the RTEMS size report for the currently -configured processor, execute the following command: - -@example -size_rtems -@end example - -Although the actual size information will differ, a -report of the following format will be output: - -@example - RTEMS SIZE REPORT - -CODE DATA BSS -================== -MANAGERS: 15988 0 0 -CORE : 4568 0 0 -CPU : 364 0 0 -OVERALL : 20556 0 0 -MINIMUM : 8752 0 0 - -init : 1592 0 0 -tasks : 2440 0 0 -intr : 64 0 0 -clock : 2252 0 0 -sem : 876 0 0 -msg : 1624 0 0 -event : 604 0 0 -signal : 212 0 0 -part : 872 0 0 -region : 844 0 0 -dpmem : 532 0 0 -timer : 424 0 0 -io : 288 0 0 -fatal : 40 0 0 -rtmon : 764 0 0 -mp : 2984 0 0 - -sem : 4 0 0 -msg : 4 0 0 -event : 4 0 0 -signal : 4 0 0 -part : 4 0 0 -region : 4 0 0 -timer : 4 0 0 -dpmem : 4 0 0 -io : 4 0 0 -rtmon : 4 0 0 -mp : 8 0 0 -@end example - -@subheading SEE ALSO - -gsize020(1G), gsize386(1G), gsize960(1G) - - -@ifinfo -@node RTEMS Specific Utilities Ada Language Specific Utilities, Command and Variable Index, size_rtems - report RTEMS size information, RTEMS Specific Utilities -@end ifinfo -@section Ada Language Specific Utilities - -The Ada language utilities provide a powerful set of -tools which combine to allow operations within the RTEMS -Development Environment to be consistent and easy to use. Much -effort was devoted to providing as close to the standard UNIX -and GNU style of operations as possible. Each of these -utilities are described in the section below. - -NOTE: The Ada implementation is not included in this -release. - - - -- cgit v1.2.3