diff --git a/c/src/lib/libbsp/i386/pc386/ide/.cvsignore b/c/src/lib/libbsp/i386/pc386/ide/.cvsignore new file mode 100644 index 0000000000..3dda72986f --- /dev/null +++ b/c/src/lib/libbsp/i386/pc386/ide/.cvsignore @@ -0,0 +1,2 @@ +Makefile.in +Makefile diff --git a/c/src/lib/libbsp/powerpc/mbx8xx/ide/.cvsignore b/c/src/lib/libbsp/powerpc/mbx8xx/ide/.cvsignore new file mode 100644 index 0000000000..3dda72986f --- /dev/null +++ b/c/src/lib/libbsp/powerpc/mbx8xx/ide/.cvsignore @@ -0,0 +1,2 @@ +Makefile.in +Makefile diff --git a/doc/develenv/direct.t b/doc/develenv/direct.t new file mode 100644 index 0000000000..50de20f42c --- /dev/null +++ b/doc/develenv/direct.t @@ -0,0 +1,696 @@ +@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 @i{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: + +@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 +@section 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 +@subsection 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/ +This directory contains the directories @code{libbsp} +and @code{libcpu/} which contain the source code for +the Board Support Packages (BSPs) and CPU Model +specific source code for RTEMS. + +The @code{libbsp/} is organized based upon the CPU +family and boards BSPs. The contents of @code{libbsp/} +are discussed briefly in +@ref{Directory Structure c/src/lib/libbsp BSP Directory} +and presented in detail in the +@b{RTEMS BSP and Device Driver Development Guide}. + +The @code{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. + +@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++/ +This directory contains C++ classes which map to the RTEMS +Classic API. + +@item $@{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. + +@item $@{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 @code{E_NOTCONFIGURED}. + +@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 c/src/tests/ Test Suites} section. + +@item $@{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 @code{librtemsbsp.a}. This +library contains all BSP and CPU model specific software. + +@end table + +@c +@c c/src/lib/libbsp BSP Directory +@c + +@subsubsection 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 +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 + +@c @ifset use-ascii +@example +@group + Each BSP + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +clock console include shmsupp startup timer +@end group +@end example +@c @end ifset + +@c +@c c/src/tests/ Test Suites +@c +@subsection c/src/tests/ 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: + +@table @code + +@item $@{RTEMS_ROOT@}/c/src/tests/itrontests/ +This directory contains the test suite for the +RTEMS ITRON API. + +@item $@{RTEMS_ROOT@}/c/src/tests/libtests/ +This directory contains the test suite for the +various RTEMS support components. + +@item $@{RTEMS_ROOT@}/c/src/tests/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. + +@item $@{RTEMS_ROOT@}/c/src/tests/psxtests/ +This directory contains the test suite for the +RTEMS POSIX API. + +@item $@{RTEMS_ROOT@}/c/src/tests/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 +@ref{Sample Applications}. + +@item $@{RTEMS_ROOT@}/c/src/tests/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 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 and ITRON API Test Suites. + +@item $@{RTEMS_ROOT@}/c/src/tests/support/ +This directory contains support software and header files +for the various test suites. + +@item $@{RTEMS_ROOT@}/c/src/tests/tmitrontests/ +This directory contains the timing test suite for +the RTEMS ITRON API. + +@item $@{RTEMS_ROOT@}/c/src/tests/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. + +@item $@{RTEMS_ROOT@}/c/src/tests/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 @code{difftest} compares the output of one +or more tests with the expected output. If you +place the output of all the @code{tmtests/} in +a single file, then the utility @code{sorttimes} +will be able to produce a report organizing the +execution times by manager. + +@end table + + +@c +@c CPUKit Directory +@c +@section CPUKit Directory + +@c The @code{cpukit/} directory structure is as follows: + +@c +@c CPUKit Tree +@c + +@c @ifset use-ascii +@c @example +@c @group +@c CPUKit +@c | +@c +-----------+----------+-----------+----------+ +@c | | | | | +@c posix rtems sapi score wrapup +@c @end group +@c @end example +@c @end ifset + +The @code{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. @code{score/} directory) +source code files are separated into distinct directory trees. + +The following is a description of each of the subdirectories +under @code{cpukit/}: + +@table @code + +@item $@{RTEMS_ROOT@}/cpukit/aclocal/ +This directory contains the custom M4 macros which are available to +the various GNU autoconf @code{configure.ac} scripts throughout +the CPU Kit portion of 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@}/cpukit/ada/ +This directory contains the Ada95 language bindings to the +RTEMS Classic API. + +@item $@{RTEMS_ROOT@}/cpukit/automake/ +This directory contains files which are "Makefile fragments." +They are included as required by the various @code{Makefile.am} +files throughout the CPU Kit portion of the RTEMS source tree. + +@item $@{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. + +@item $@{RTEMS_ROOT@}/cpukit/itron/ +This directory contains the implementation of the +ITRON API. + +@item $@{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. + +@item $@{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. + +@item $@{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. + +@item $@{RTEMS_ROOT@}/cpukit/libnetworking/ +This directory contains the port of the FreeBSD +TCP/IP stack to RTEMS. + +@item $@{RTEMS_ROOT@}/cpukit/librpc/ +This directory contains the port of the FreeBSD +RPC/XDR source to RTEMS. + +@item $@{RTEMS_ROOT@}/cpukit/posix/ +This directory contains the RTEMS implementation +of the threading portions of the POSIX API. + +@item $@{RTEMS_ROOT@}/cpukit/rtems/ +This directory contains the implementation of the +Classic API. + +@item $@{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 +initialization, shutdown, and IO services. + +@item $@{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, POSIX threads, and ITRON +tasks 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 @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 @code{no_cpu} directory provides a +starting point for developing a new port to an unsupported +processor. The files contained within the @code{no_cpu} directory +may also be used as a reference for the other ports to specific +processors. + +@item $@{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 @code{librtemscpu.a}. This +library contains all BSP and CPU model specific software. + +@end table + +@c +@c Documentation Directory +@c +@section Documentation Directory + +This directory contains the source code for all RTEMS documentation +in @code{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. + +@table @code + +@item $@{RTEMS_ROOT@}/doc/FAQ/ +This directory contains the source code for the @cite{RTEMS Frequently Asked +Questions (FAQ) Collection}. + +@item $@{RTEMS_ROOT@}/doc/user/ +This directory contains the source code for the @cite{RTEMS +Applications C User's Guide} which documents the Classic API. + +@item $@{RTEMS_ROOT@}/doc/ada_user/ +This directory contains the source code for the @cite{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 @cite{RTEMS Application +C User's Guide}. + +@item $@{RTEMS_ROOT@}/doc/bsp_howto/ +This directory contains the source code for the +@cite{RTEMS BSP and Device Driver Development Guide}. + +@item $@{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. + +@item $@{RTEMS_ROOT@}/doc/develenv/ +This directory contains the source code for the +@cite{RTEMS Development Environment Guide}. This is +the document you are currently reading. + +@item $@{RTEMS_ROOT@}/doc/filesystem/ +This directory contains the source code for the +@cite{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. + +@item $@{RTEMS_ROOT@}/doc/gnu_docs/ +This directory contains the scripts which assist in +generating HTML for the GNU tools in the RTEMS Cross +Development Environment set. + +@item $@{RTEMS_ROOT@}/doc/images/ +This directory contains the source code for the graphics +used in the HTML version of the RTEMS Documentation. + +@item $@{RTEMS_ROOT@}/doc/itron3.0/ +This directory contains the source code for the +@cite{RTEMS ITRON 3.0 API User's Guide}. + +@item $@{RTEMS_ROOT@}/doc/networking/ +This directory contains the source code for the +@cite{RTEMS Network Supplement}. + +@item $@{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 @code{$@{RTEMS_ROOT@}/c/src/libmisc/}. + +@item $@{RTEMS_ROOT@}/doc/porting/ +This directory contains the source code for the +@cite{RTEMS Porting Guide}. + +@item $@{RTEMS_ROOT@}/doc/posix1003.1/ +This directory contains the source code for the +@cite{RTEMS POSIX 1003.1 Compliance Guide}. + +@item $@{RTEMS_ROOT@}/doc/posix_users/ +This directory contains the source code for the +@cite{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. + +@item $@{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. + +@item $@{RTEMS_ROOT@}/doc/rgdb_specs/ +This directory contains the source code for the +@cite{RTEMS Remote Debugger Server Specifications}. + +@item $@{RTEMS_ROOT@}/doc/rtems_gdb/ +This directory contains the source code for the +@cite{RTEMS/GDB User's Guide}. + +@item $@{RTEMS_ROOT@}/doc/started/ +This directory contains the source code for the +@cite{Getting Started with RTEMS for C/C++ Users} manual. + +@item $@{RTEMS_ROOT@}/doc/started_ada/ +This directory contains the source code for the +@cite{Getting Started with RTEMS for Ada Users} manual. + +@item $@{RTEMS_ROOT@}/doc/supplements/ +This directory contains the source code for the various +RTEMS CPU Supplements. +the + +@item $@{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 @code{bmenu} which generates the hierarchical node +linking commands based upon chapter, section, and +subsection organization. + +@end table diff --git a/doc/develenv/sample.t b/doc/develenv/sample.t new file mode 100644 index 0000000000..7bb6ecc167 --- /dev/null +++ b/doc/develenv/sample.t @@ -0,0 +1,328 @@ +@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 + +The RTEMS source distribution includes a set of sample applications +that are located in the @code{$@{RTEMS_ROOT@}/c/src/tests/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. + +Each of the following sample applications will be listed in +more detail in the following sections: + +@table @b +@item Hello World +The RTEMS Hello World test is provided in +the subdirectory @code{$@{RTEMS_ROOT@}/c/src/tests/samples/hello/}. +This test is helpful when testing new +versions of RTEMS, BSPs, or modifications to any portion of the +RTEMS development environment. + +@item Clock Tick +The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/ticker/} +subdirectory provides a test for verification of clock chip +device drivers of BSPs. + +@item Base Single Processor +A simple single processor test similar to those in the +single processor test suite is provided in +@code{$@{RTEMS_ROOT@}/c/src/tests/samples/base_sp/}. + +@item Base Multiple Processor +A simple two node multiprocessor test capable of testing an newly +developed MPCI layer is provided in +@code{$@{RTEMS_ROOT@}/c/src/tests/samples/base_mp/}. + +@item Constructor/Destructor C++ Test +The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/cdtest/} +subdirectory provides a simple C++ application using +constructors and destructors. It is only built when +C++ is enabled. + + +@item Paranoia Floating Point Test +The directory @code{$@{RTEMS_ROOT@}/c/src/tests/samples/paranoia/} +contains the public domain floating point and math library test. + +@item Minimum Size Test +The directory +@code{$@{RTEMS_ROOT@}/c/src/tests/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. + +@item Unlimited Object Allocation +The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/unlimited/} +directory contains a sample test that demonstrates the use of the +@i{unlimited} object allocation configuration option to RTEMS. + +@item Network Loopback Test +The @code{$@{RTEMS_ROOT@}/c/src/tests/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. + +@end table + +The sample tests are written using the Classic API so the reader +should be familiar with the terms used and +material presented in the @b{RTEMS Applications Users Guide}. + +@section Hello World + +This sample application is in the following directory: + +@example +$@{RTEMS_ROOT@}/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_ROOT@}/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_ROOT@}/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_ROOT@}/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_ROOT@}/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 Minimum Size Test + +This sample application is in the following directory: + +@example +$@{RTEMS_ROOT@}/tests/samples/minimum/ +@end example + +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. + +@section Paranoia Floating Point Application + +This sample application is in the following directory: + +@example +$@{RTEMS_ROOT@}/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. + +@section Network Loopback Test + +This sample application is in the following directory: + +@example +$@{RTEMS_ROOT@}/tests/samples/loopback/ +@end example + +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/doc/develenv/utils.t b/doc/develenv/utils.t new file mode 100644 index 0000000000..13029a2e14 --- /dev/null +++ b/doc/develenv/utils.t @@ -0,0 +1,260 @@ +@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 @b{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. + +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. + +@c +@c packhex +@c +@section 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. + +@c +@c unhex +@c +@section 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 + +@c +@c size_rtems +@c +@section 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) + +