@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@ifinfo
@node Introduction, Introduction Supporting Tools, Top, Top
@end ifinfo
@chapter Introduction
@ifinfo
@menu
* Introduction Supporting Tools::
* Introduction Documentation::
@end menu
@end ifinfo

This document describes the contents, installation
procedure, and current status of Release @value{RELEASE} of the RTEMS
executive.  An installation procedure is provided which
describes the steps necessary to load and configure the RTEMS
environment, including the GNU Development Environment and the
Cygnus NEWLIB ANSI C Library, on a host computer.  The status of
the RTEMS environment is given, which includes supported
processors and target boards, versions of the GNU utilities
which were used by the RTEMS developers for this release,
support libraries status, features which are not implemented,
and any known existing problems.

This RTEMS release package contains the following general components:

@itemize @bullet
@item RTEMS C Executive

@item RTEMS C Documentation Set

@item RTEMS NEWLIB ANSI C Library

@item Patches to GNU Development Tools

@end itemize

There is a mailing list dedicated to RTEMS.  This is
a Majordomo style mailing list and may be subscribed to
by sending a message to rtems-list-request@@OARcorp.com with
the following line as the body:

@example
subscribe rtems_user@@your_email_goes_here.com
@end example

Please replace rtems_user@@your_email_goes_here.com with your
email address.

@ifinfo
@node Introduction Supporting Tools, GNU Development Tools, Introduction, Introduction
@end ifinfo
@section Supporting Tools
@ifinfo
@menu
* GNU Development Tools::
* ANSI C Libraries::
* GNU C Library::
* Cygnus NEWLIB C Library::
@end menu
@end ifinfo

This section discusses the freely available tools and
libraries which are part of the RTEMS Development Environment.
None of the tools discussed in this section were developed by
the RTEMS project, although many do include submissions from the
project.  All of the tools and libraries required to build RTEMS
are freely available.  The home ftp site for most of the non-RTEMS
specific tools is either prep.ai.mit.edu (18.71.0.38) or
ftp.cygnus.com (140.174.1.3).

Specifically of interest to embedded systems developers
using the GNU tools is the crossgcc mailing list.  This is
a Majordomo style mailing list and may be subscribed to
by sending a message to crossgcc-request@@cygnus.com with
the following line as the body:

@example
subscribe rtems_user@@your_email_goes_here.com
@end example

Please replace rtems_user@@your_email_goes_here.com with your
email address.  The FAQ for crossgcc is in the /pub/embedded/crossgcc
directory on ftp.cygnus.com (205.180.83.42).

@ifinfo
@node GNU Development Tools, ANSI C Libraries, Introduction Supporting Tools, Introduction Supporting Tools
@end ifinfo
@subsection GNU Development Tools

Numerous GNU tools are used in the RTEMS Development
Environment including C and Ada compilers, the GNU make program,
GNU m4, the GNU assembler and binary utilities (linker,
librarian, etc.), GNU tar, GNU zip, and the GNU debugger.  These
tools are distributed in source form and are all licensed under
the GNU Public License which allows for unrestricted
distribution under the condition that source code always be
available.  The Free Software Foundation is officially the
originator of most of the GNU tools although many individuals
have contributed to the GNU projects.  In keeping with the
spirit of the GPL,  most of the time the GNU tools are
distributed as source code without executables.  It is the
responsibility of the local site to install each tool.  Numerous
organizations and individuals supply executables for the GNU
tools.  All are required by the terms of the GPL to also make
the source code available to the end user.

The primary ftp site for the FSF GNU tools is
prep.ai.mit.edu (18.71.0.38) in the /pub/gnu directory.  These
tools are mirrored on numerous ftp sites.

Intel maintains a toolset for their i960 processor
family based on the GNU tools referred to as GNU/960.  The
source code for this toolset is available from ftp.intel.com
(143.185.65.2).  [NOTE: The GNU/960 toolset generally includes
an older version of GCC than that available from the FSF.  When
the FSF version of GNU C is significantly newer than that in the
GNU/960 release, the RTEMS developers replace the GCC in the
GNU/960 toolset with the FSF release.]

Cygnus maintains an ftp site -- ftp.cygnus.com
(205.180.83.42) -- which contains a source code which appeals to
embedded developers.  Of especial interest on this site are the
directories /pub/newlib and /pub/embedded.

@ifinfo
@node ANSI C Libraries, GNU C Library, GNU Development Tools, Introduction Supporting Tools
@end ifinfo
@subsection ANSI C Libraries

This section discusses the following freely
distributable ANSI C Libraries:

@itemize @bullet
@item GNU C Library, and

@item Cygnus NEWLIB
@end itemize

No C Library is included in the standard RTEMS
distribution.  It is the responsibility of the user to obtain
and install a C Library separately.

@ifinfo
@node GNU C Library, Cygnus NEWLIB C Library, ANSI C Libraries, Introduction Supporting Tools
@end ifinfo
@subsection GNU C Library

The GNU C Library is a robust and well-documented C
Library which is distributed under the terms of the Library GNU
Public License (LGPL).  This library was not designed for use in
real-time, embedded systems and the resource requirements of
some of the routines in this library are an obvious indication
of this.  Additionally, this library does not have support for
reentrancy in the sense that each task in a multitasking system
could safely invoke every routine in the library.  Finally, the
distribution terms of the LGPL are considered undesirable by
many embedded systems developers.  However, the GNU C Library is
very complete and is compliant with as many standards as
possible.  Because of this, it may be the only choice for many
developers.

There is currently no RTEMS support for the GNU C Library.

The primary ftp site for this library is
prep.ai.mit.edu (18.71.0.38).

@ifinfo
@node Cygnus NEWLIB C Library, Introduction Documentation, GNU C Library, Introduction Supporting Tools
@end ifinfo
@subsection Cygnus NEWLIB C Library

The Cygnus NEWLIB C Library was specifically designed
for real-time embedded systems.  It is a small, reasonably
documented Library with support for reentrancy.  This library is
a collection of freely distributable and public domain source
code and is freely distributable with as few restrictions as
possible placed on the end user.

The RTEMS specific support code for NEWLIB has been
submitted to the NEWLIB maintainers and should be included in a
future release.  Until that time, it is recommended that the
beta version of NEWLIB with RTEMS support added be used by the
application developer.  The beta version of NEWLIB with RTEMS
specific support is ONLY available on the OAR ftp site.  This
beta version is strictly tied to a particular RTEMS release.

The primary ftp site for this library is ftp.cygnus.com (205.180.83.42).

@ifinfo
@node Introduction Documentation, Installation Procedure, Cygnus NEWLIB C Library, Introduction
@end ifinfo
@section Documentation

The RTEMS Documentation Set is provided online at http://www.OARcorp.com/
as reference information for all levels of RTEMS users.  The set includes
the following documents:

@itemize @bullet
@item C Applications User's Guide

@item Intel i386 Applications Supplement

@item Intel i960CA Applications Supplement

@item Motorola MC68xxx Applications Supplement

@item Hewlett Packard PA-RISC 1.1 Applications Supplement

@item SPARC Applications Supplement

@item Development Environment Guide

@item Release Notes
@end itemize

The RTEMS documentation set is available in alternate formats to 
support customers.
