2004-07-31 Ralf Corsepius <ralf_corsepius@rtems.org>

	* FAQ/basic.texi, FAQ/bsp.texi, FAQ/build45.texi, FAQ/concepts.texi,
	FAQ/debug.texi, FAQ/endoftime.texi, FAQ/freesw.texi,
	FAQ/hwdebugaids.texi, FAQ/projects.texi, FAQ/tools.texi,
	FAQ/version.texi: New.

11 files changed, 1904 insertions, 0 deletions

diff --git a/doc/FAQ/basic.texi b/doc/FAQ/basic.texi
new file mode 100644
index 0000000000..205c8f18f5
--- /dev/null
+++ b/doc/FAQ/basic.texi
@@ -0,0 +1,268 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node Basic Information, What does RTEMS stand for?, Top, Top
+
+@chapter Basic Information
+@ifinfo
+@menu
+* What does RTEMS stand for?::
+* What is RTEMS?::
+* What standards does RTEMS support?::
+* What processors is RTEMS available for?::
+* Executive vs. Kernel vs. Operating System (RTOS)::
+* Where/why was it developed?::
+* Are there no similar commercial products?::
+* How can I get RTEMS?::
+* What about support?::
+* Are there any mailing lists?::
+* Are there any license restrictions?::
+* Are there any export restrictions?::
+@end menu
+@end ifinfo
+
+The questions in this category are basic questions about RTEMS.  Where
+did it come from, why is it, what is it, when should you use it, etc.?
+
+
+@node What does RTEMS stand for?, What is RTEMS?, Basic Information, Basic Information
+
+@section What does RTEMS stand for?
+
+RTEMS is an an acronym for the Real-Time Executive for Multiprocessor
+Systems.
+
+Initially RTEMS stood for the Real-Time Executive for Missile Systems
+but as it became clear that the application domains that could use
+RTEMS extended far beyond missiles, the "M" changed to mean Military.
+At one point, there were both Ada and C implementations of RTEMS.  The
+C version changed the "M" to mean Multiprocessor while the Ada version
+remained with the "M" meaning Military.
+
+
+@node What is RTEMS?, What standards does RTEMS support?, What does RTEMS stand for?, Basic Information
+
+@section What is RTEMS?
+
+RTEMS is a real-time executive which provides a high performance
+environment for embedded military applications including many
+features. The following is just a short list of the features
+available in RTEMS.  If you are interested in something that
+is not on this list, please contact the RTEMS Team.  Features
+are being added continuously.
+
+@itemize @bullet
+
+@item Standards Compliant
+@itemize @bullet
+@item POSIX 1003.1b API including threads
+@item RTEID/ORKID based Classic API
+@end itemize
+
+@item TCP/IP Stack
+@itemize @bullet
+@item high performance port of FreeBSD TCP/IP stack
+@item UDP, TCP
+@item ICMP, DHCP, RARP
+@item TFTP
+@item RPC
+@item FTPD
+@item HTTPD
+@item CORBA
+@end itemize
+
+@item Debugging
+@itemize @bullet
+@item GNU debugger (gdb)
+@item DDD GUI interface to GDB
+@item thread aware
+@item debug over Ethernet
+@item debug over Serial Port
+@end itemize
+
+@item Filesystem Support
+@itemize @bullet
+@item In-Memory Filesystem (IMFS)
+@item TFTP Client Filesystem
+@end itemize
+
+@item Basic Kernel Features
+@itemize @bullet
+@item multitasking capabilities
+@item homogeneous and heterogeneous multiprocessor systems
+@item event-driven, priority-based, preemptive scheduling
+@item optional rate monotonic scheduling
+@item intertask communication and synchronization
+@item priority inheritance
+@item responsive interrupt management
+@item dynamic memory allocation
+@item high level of user configurability
+@end itemize
+
+@end itemize
+
+
+
+@node What standards does RTEMS support?, What processors is RTEMS available for?, What is RTEMS?, Basic Information
+
+@section What standards does RTEMS support?
+
+The original "Classic" RTEMS API is based on the Real-Time Executive
+Interface Definition (RTEID) and the Open Real-Time Kernel Interface
+Definition (ORKID).  RTEMS also includes support for POSIX threads
+and real-time extensions.
+
+With the addition of file system infrastructure, RTEMS supports
+about 70% of the POSIX 1003.1b-1996 standard.  This standard
+defines the programming interfaces of standard UNIX.   This means
+that much source code that works on UNIX, also works on RTEMS.
+
+
+@node What processors is RTEMS available for?, Executive vs. Kernel vs. Operating System (RTOS), What standards does RTEMS support?, Basic Information
+
+@section What processors is RTEMS available for?
+
+RTEMS is available for the following processor families:
+
+@itemize @bullet
+@item Motorola MC68xxx
+@item Motorola MC683xx
+@item Motorola ColdFire
+@item ARM
+@item Hitachi H8/300
+@item Hitachi SH
+@item Intel i386
+@item Intel i960
+@item MIPS
+@item PowerPC
+@item SPARC
+@item Texas Instruments C3x/C4x
+@item OpenCores OR32
+@end itemize
+
+In addition, there is a port to UNIX which can be used as a prototyping
+and simulation environment.
+
+
+@node Executive vs. Kernel vs. Operating System (RTOS), Where/why was it developed?, What processors is RTEMS available for?, Basic Information
+
+@section Executive vs. Kernel vs. Operating System (RTOS)
+
+The developers of RTEMS developers use the terms executive and kernel
+interchangeably.  In the embedded system community, the terms executive
+or kernel are generally used to refer to small operating systems.
+So we consider it proper to refer to RTEMS as an executive, a kernel,
+or an operating system.
+
+
+@node Where/why was it developed?, Are there no similar commercial products?, Executive vs. Kernel vs. Operating System (RTOS), Basic Information
+
+@section Where/why was it developed?
+
+RTEMS was developed by On-Line Applications Research Corporation (OAR)
+for the U.S. Army Missile Command prior to that organizations merger
+with the Aviation Command that resulted in the new command, U. S. Army
+Aviation and Missile command (AMCOM).  The original goal of RTEMS was
+to provide a portable, standards-based real-time executive for which
+source code was available and royalties were paid.
+
+In other words, RTEMS was open source before open source was cool.
+
+Since the initial release to the world, the RTEMS Community has
+grown enormously and contributed significantly to RTEMS.  Important
+additions such as the TCP/IP stack, FAT filesystem, multiple ports,
+device drivers, and most BSPs have come from users like yourself.
+
+
+@node Are there no similar commercial products?, How can I get RTEMS?, Where/why was it developed?, Basic Information
+
+@section Are there no similar commercial products?
+
+Yes, but not all are based on standards and the open source philosophy.
+
+
+@node How can I get RTEMS?, What about support?, Are there no similar commercial products?, Basic Information
+
+@section How can I get RTEMS?
+
+RTEMS is distributed from @uref{@value{RTEMSHTTPURL},@value{RTEMSHTTPURL}}.
+This is a server dedicated to the RTEMS Project which was donated by and
+hosted by @uref{http://www.oarcorp.com,OAR Corporation} to provide
+a focal point for all RTEMS activities.  Point your
+favorite browser at the following URL and following the link:
+
+@uref{@value{RTEMSHTTPURL},@value{RTEMSHTTPURL}}
+
+But if you are already reading this, you probably already found it. :)
+
+
+@node What about support?, Are there any mailing lists?, How can I get RTEMS?, Basic Information
+
+@section What about support?
+
+RTEMS development and support services are available from a number
+of firms.  See
+@uref{@value{RTEMSHTTPURL}/support.html,@value{RTEMSHTTPURL}/support.html}
+for the current list of RTEMS service providers.
+
+Remember that RTEMS maintenance is funded by users.  If you are
+using RTEMS on a commercial project, please get support.
+
+
+@node Are there any mailing lists?, Are there any license restrictions?, What about support?, Basic Information
+
+@section Are there any mailing lists?
+
+The primary RTEMS mailing list is @code{@value{RTEMSUSERS}}.  This
+list is for general RTEMS discussions, questions, design help, advice,
+etc..  Subscribe by sending an empty mail
+message to @code{@value{RTEMSUSERSSUBSCRIBE}}.  This
+mailing list is archived at:
+
+@example
+http://www.rtems.com/ml/rtems-users
+@end example
+
+The @code{@value{RTEMSSNAPSHOTS}} mailing list is for those
+interested in taking a more active role in the design, development,
+and maintenance of RTEMS.  Discussions on this list tend to focus
+on problems in the development source, design of new features, problem
+reports, etc..  Subscribe by sending an empty mail
+message to @code{@value{RTEMSSNAPSHOTSSUBSCRIBE}}.
+mailing list is archived at:
+
+@example
+http://www.rtems.com/ml/rtems-snapshots
+@end example
+
+The archives for both mailing lists include discussions back
+to 1997.
+
+
+@node Are there any license restrictions?, Are there any export restrictions?, Are there any mailing lists?, Basic Information
+
+@section Are there any license restrictions?
+
+RTEMS is licensed under a modified version of the GNU General Public License
+(GPL).  The modification places no restrictions on the applications which
+use RTEMS but protects the interests of those who work on RTEMS.
+
+The TCP/IP network stack included with RTEMS is a port of the FreeBSD
+network stack and is licensed under different terms that also do not
+place restrictions on the application.
+
+
+@node Are there any export restrictions?, , Are there any license restrictions?, Basic Information
+
+@section Are there any export restrictions?
+
+No.
+
+
+
diff --git a/doc/FAQ/bsp.texi b/doc/FAQ/bsp.texi
new file mode 100644
index 0000000000..4018c367cf
--- /dev/null
+++ b/doc/FAQ/bsp.texi
@@ -0,0 +1,51 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node BSP Questions, What is a BSP?, , Top
+
+@chapter BSP Questions
+@ifinfo
+@menu
+* What is a BSP?::
+* What has to be in a BSP?::
+@end menu
+@end ifinfo
+
+The items in this category provide answers to questions
+commonly asked about BSPs.
+
+
+@node What is a BSP?, What has to be in a BSP?, BSP Questions, BSP Questions
+
+@section What is a BSP?
+
+BSP is an acronym for Board Support Package.
+
+A BSP is a collection of device drivers, startup code, linker scripts,
+and compiler support files (specs files) that tailor RTEMS for a
+particular target hardware environment.
+
+
+@node What has to be in a BSP?, , What is a BSP?, BSP Questions
+
+@section What has to be in a BSP?
+
+The basic set of items is the linker script, bsp_specs, and startup code.
+If you want standard IO, then you need a console driver. This is needed
+to run any of the RTEMS tests.  If you want to measure passage of time,
+you need a clock tick driver.  This driver is needed for all RTEMS tests
+EXCEPT hello world and the timing tests.  The timer driver is a benchmark
+timer and is needed for the tmtests (timing tests).  Sometimes you will
+see a shmsupp directory which is for shared memory multiprocessing
+systems.  The network driver and real-time clock drivers are optional
+and not required by any RTEMS tests.
+
+
+
+
diff --git a/doc/FAQ/build45.texi b/doc/FAQ/build45.texi
new file mode 100644
index 0000000000..507b257803
--- /dev/null
+++ b/doc/FAQ/build45.texi
@@ -0,0 +1,602 @@
+@c
+@c  $Id$
+@c
+
+
+@node Building RTEMS, Required Tools, , Top
+
+@chapter Building RTEMS
+@ifinfo
+@menu
+* Required Tools::
+* Issues when building RTEMS::
+* Host Operating Systems and RTEMS::
+* Development related questions::
+@end menu
+@end ifinfo
+
+Building any package in a cross-compilation fashion can be difficult,
+but configuring and building a real-time operating system that
+supports many CPU families and target boards can be confusing.  The
+RTEMS development team has made every effort to make this process as
+straight forward as possible but there are going to be questions.
+
+Moreover, between RTEMS 4.0 and 4.5, the configure and Makefile system in RTEMS
+was changed to be more compatible with GNU standards.  This transition
+has lead to a number of subtle differences.
+
+This section of the FAQ tries to address the more frequently asked
+questions about building RTEMS.  Thanks to Ralf Corsepius for
+compiling this section from excerpts from various postings to the
+rtems-users mailing list.
+
+
+@node Required Tools, Which tools are required to build RTEMS?, Building RTEMS, Building RTEMS
+
+@section Required Tools
+@ifinfo
+@menu
+* Which tools are required to build RTEMS?::
+* Do I need autoconf and automake to build RTEMS?::
+* Do I need a native gcc on my host?::
+* Can I use a non-gcc cross-toolchain?::
+* Do I need gcc-2.9x for cross compilation?::
+* Where to get autoconf automake ld gcc etc.?::
+@end menu
+@end ifinfo
+
+
+@node Which tools are required to build RTEMS?, Do I need autoconf and automake to build RTEMS?, Required Tools, Required Tools
+
+@subsection Which tools are required to build RTEMS?
+
+@itemize @bullet
+
+@item A native C-Toolchain, gcc prefered
+@item GNU-Bash and shell utils
+@item GNU-make.
+@item A target (typically cross) C- and (optional) C++-Toolchain.
+@item autoconf/automake (optional, recommended)
+@item Perl (optional, recommended, needed by automake and some tools within RTEMS)
+@item m4 (optional, recommended, needed by autoconf, GNU-m4 preferred)
+
+@end itemize
+
+
+@node Do I need autoconf and automake to build RTEMS?, Do I need a native gcc on my host?, Which tools are required to build RTEMS?, Required Tools
+
+@subsection Do I need autoconf and automake to build RTEMS?
+
+No, you don't.  Or to be more accurate, you won't need them until you
+modify something in RTEMS's Makefile.ams/configure.acs or start to develop
+with RTEMS.
+
+I.e.  you won't need them to get started, but you will need them when getting
+serious.
+
+
+@node Do I need a native gcc on my host?, Can I use a non-gcc cross-toolchain?, Do I need autoconf and automake to build RTEMS?, Required Tools
+
+@subsection Do I need a native gcc on my host?
+
+No, you should be able to use any native, ansi-compliant C-compiler, but
+using a native gcc is highly recommended.
+
+
+@node Can I use a non-gcc cross-toolchain?, Do I need gcc-2.9x for cross compilation?, Do I need a native gcc on my host?, Required Tools
+
+@subsection Can I use a non-gcc cross-toolchain?
+
+Generally speaking, it should be possible.
+However, most RTEMS development has taken place using gcc, therefore
+getting it working may not be easy.
+
+
+@node Do I need gcc-2.9x for cross compilation?, Where to get autoconf automake ld gcc etc.?, Can I use a non-gcc cross-toolchain?, Required Tools
+
+@subsection Do I need gcc-2.9x for cross compilation?
+
+[FIXME: Partially obsolete]
+
+Not necessarily, but gcc-2.9x is highly recommended, because most development
+has taken place using gcc-2.9x and previous versions of gcc are not actively
+supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}).
+
+
+@node Where to get autoconf automake ld gcc etc.?, Issues when building RTEMS, Do I need gcc-2.9x for cross compilation?, Required Tools
+
+@subsection Where to get autoconf automake ld gcc etc.?
+
+The sources of all gnutools are available at any
+@uref{ftp://ftp.gnu.org,GNU} mirror.
+Native Linux binaries should come with any Linux distribution.
+Native Cygwin binaries should be available at Cygnus.
+
+GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required
+to build them from source are available from
+@uref{@value{RTEMSFTPURL},the RTEMS ftp site}.
+
+
+
+@node Issues when building RTEMS, When running ./configure weird thing start to happen, Where to get autoconf automake ld gcc etc.?, Building RTEMS
+
+@section Issues when building RTEMS
+@ifinfo
+@menu
+* When running ./configure weird thing start to happen::
+* When running bootstrap weird thing start to happen::
+* configure xxx cannot create executables::
+* Why can I not build RTEMS inside of the source tree?::
+* Which environment variables to set?::
+* Compiler /Assembler /Linker report errors::
+* How to set up $PATH?::
+* Can I build RTEMS Canadian Cross?::
+* Building RTEMS is slow::
+* Building my pre-4.5.x BSPs does not work anymore::
+* make debug_install / make profile_install::
+* make debug / make profile::
+* Building RTEMS does not honor XXX_FOR_TARGET::
+* Editing Makefile.in Makefile configure::
+* Editing auto* generated files::
+@end menu
+@end ifinfo
+
+
+@node When running ./configure weird thing start to happen, When running bootstrap weird thing start to happen, Issues when building RTEMS, Issues when building RTEMS
+
+@subsection When running ./configure weird thing start to happen
+
+You are probably trying to build within the source-tree.
+RTEMS requires a separate build directory.  I.e.  if the
+sources are located at @code{/usr/local/src/rtems-@value{VERSION}},
+use something similar to this to configure RTEMS:
+
+@example
+cd somewhere
+mkdir build
+cd build
+/usr/local/src/rtems-@value{VERSION}/configure [options]
+@end example
+
+
+@node When running bootstrap weird thing start to happen, configure xxx cannot create executables, When running ./configure weird thing start to happen, Issues when building RTEMS
+
+@subsection When running bootstrap weird thing start to happen
+
+Many possibile causes: Most likely one of these:
+@itemize @bullet
+@item You are trying to build RTEMS with insufficient or incompatible
+versions of autoconf and automake.
+@item The autotools can't be found because your $PATH might not be set up
+correctly (Cf. @ref{How to set up $PATH?})
+@item You have used configure-script options which interfer with RTEMS
+configuration (Cf. @ref{configure --program-[prefix|suffix|transform-name]})
+@item You have tripped over a bug in RTEMS ;)
+@end itemize
+
+
+@node configure xxx cannot create executables, Why can I not build RTEMS inside of the source tree?, When running bootstrap weird thing start to happen, Issues when building RTEMS
+
+@subsection configure xxx cannot create executables
+
+While running a configure script, you see a message like this:
+@example
+checking for m68k-rtems-gcc... (cached) m68k-rtems-gcc
+checking for C compiler default output... configure: error: C compiler cannot create executables
+configure: error: /bin/sh '../../../../rtems-ss-@value{VERSION}/c/make/configure'
+failed for c/make
+@end example
+This kind of error message typically indicates a broken toolchain, broken
+toolchain installation or broken user environment.
+
+Examinating the @code{config.log} corresponding to the the failing
+configure script should provide further information of what
+actually goes wrong (In the example above: @code{<target>/c/<BSP>/make/config.log})
+
+
+@node Why can I not build RTEMS inside of the source tree?, Which environment variables to set?, configure xxx cannot create executables, Issues when building RTEMS
+
+@subsection Why can I not build RTEMS inside of the source tree?
+
+The build-directory hierarchy is setup dynamically at configuration time.
+
+Configuring inside of the source tree would prevent being able to configure
+for multiple targets simultaneously.
+
+Using a separate build-tree simplifies Makefiles and configure scripts
+significantly.
+
+Adaptation to GNU/Cygnus conventions.
+
+
+@node Which environment variables to set?, Compiler /Assembler /Linker report errors, Why can I not build RTEMS inside of the source tree?, Issues when building RTEMS
+
+@subsection Which environment variables to set?
+
+None.  Unlike for previous releases, it is not recommended anymore to set any
+RTEMS related environment variable (Exception: $PATH, cf.
+@ref{How to set up $PATH?}).
+
+
+
+@node Compiler /Assembler /Linker report errors, How to set up $PATH?, Which environment variables to set?, Issues when building RTEMS
+
+@subsection Compiler /Assembler /Linker report errors
+
+If you see a bunch of the error messages related to invalid instructions
+or similar, then probably your @code{$PATH} environment variable is not
+set up correctly (cf.  @ref{How to set up $PATH?}).  Otherwise you might
+have found a bug either in RTEMS or parts of the toolchain.
+
+
+@node How to set up $PATH?, Can I build RTEMS Canadian Cross?, Compiler /Assembler /Linker report errors, Issues when building RTEMS
+
+@subsection How to set up $PATH?
+
+All target tools are supposed to be prefixed with a target-canonicalization
+prefix, eg.  i386-rtems-gcc, m68k-rtems-ld are target tools.
+
+Host tools are supposed not to be prefixed.
+e.g.: cc, ld, gcc, autoconf, automake, aclocal etc.
+
+If using the pre-built tool binaries provided by the RTEMS project,
+simply prepend @code{@value{RTEMSPREFIX}} to @code{$PATH}.
+
+
+@node Can I build RTEMS Canadian Cross?, Building RTEMS is slow, How to set up $PATH?, Issues when building RTEMS
+
+@subsection Can I build RTEMS Canadian Cross?
+
+RTEMS >= 4.6.0 configuration is prepared for building RTEMS Canadian Cross,
+however building RTEMS Canadian Cross is known to be in its infancy, so
+your mileage may vary (See @code{README.cdn-X} in the toplevel directory of
+RTEMS's source tree for details.)
+
+
+@node Building RTEMS is slow, Building my pre-4.5.x BSPs does not work anymore, Can I build RTEMS Canadian Cross?, Issues when building RTEMS
+
+@subsection Building RTEMS is slow
+
+RTEMS has become fairly large :).
+
+In comparison to building previous versions, building RTEMS is slow,
+ but that's the tradeoff to pay for simplier and safer configuration.
+
+If using Cygwin, remember that Cygwin is emulating one OS ontop of another
+ -- this necessarily must be significantly slower than using U*nix on the
+ same hardware.
+
+
+@node Building my pre-4.5.x BSPs does not work anymore, make debug_install / make profile_install, Building RTEMS is slow, Issues when building RTEMS
+
+@subsection Building my pre-4.5.x BSPs does not work anymore
+
+See @ref{How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?}.
+
+
+@node make debug_install / make profile_install, make debug / make profile, Building my pre-4.5.x BSPs does not work anymore, Issues when building RTEMS
+
+@subsection make debug_install / make profile_install
+
+[FIXME:Partially obsolete]
+
+These make targets are not supported anymore.  Instead, use:
+
+@example
+make VARIANT=DEBUG install
+make VARIANT=PROFILE install
+@end example
+
+
+@node make debug / make profile, Building RTEMS does not honor XXX_FOR_TARGET, make debug_install / make profile_install, Issues when building RTEMS
+
+@subsection make debug / make profile
+
+[FIXME:Partially obsolete]
+
+These make targets are not supported anymore.
+Instead, use:
+
+@example
+make VARIANT=DEBUG all
+make VARIANT=PROFILE all
+@end example
+
+
+
+@node Building RTEMS does not honor XXX_FOR_TARGET, Editing Makefile.in Makefile configure, make debug / make profile, Issues when building RTEMS
+
+@subsection Building RTEMS does not honor XXX_FOR_TARGET
+
+RTEMS < 4.6.0 did not support passing flags from the environment.
+If using RTEMS < 4.6.0, editing your BSP's @code{make/custom/mybsp.cfg} and
+setting appropriate flags there is required.
+
+RTEMS >= 4.6.0 honors several XXX_FOR_TARGET environment variables.
+Run @code{<path-to-rtems>/configure --help} for a full list of supported variables.
+
+
+@node Editing Makefile.in Makefile configure, Editing auto* generated files, Building RTEMS does not honor XXX_FOR_TARGET, Issues when building RTEMS
+
+@subsection Editing Makefile.in Makefile configure
+
+These files are generated by auto* tools, cf.
+@ref{Editing auto* generated files}).
+
+
+@node Editing auto* generated files, Host Operating Systems and RTEMS, Editing Makefile.in Makefile configure, Issues when building RTEMS
+
+@subsection Editing auto* generated files
+
+RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever}
+edit Makefile.ins, Makefiles, configure or other auto* generated files.
+Changes to them will be swapped away soon and will get lost.
+
+Instead edit the sources (eg.: Makefile.ams, configure.acs) auto* generated
+files are generated from directly.
+
+If sending patches always send Makefile.ams and configure.acs.
+Sending Makefile.ins, Makefiles and configure scripts is pretty much useless.
+If sending larger patches, consider removing all auto* generated files
+by running @code{bootstrap -c} (cf. See @ref{./bootstrap})
+before running diff to cut a patch.
+
+If you don't understand what this is all about, try start getting familiar
+with auto* tools by reading autoconf.info and automake.info, or feel free
+to ask for assistance on the RTEMS Mailing List
+(See @ref{Are there any mailing lists?}.
+
+
+@node Host Operating Systems and RTEMS, Can I use Windows or DOS?, Editing auto* generated files, Building RTEMS
+
+@section Host Operating Systems and RTEMS
+@ifinfo
+@menu
+* Can I use Windows or DOS?::
+* Do I need Linux?::
+* Which Linux distribution is recommended?::
+@end menu
+@end ifinfo
+
+
+@node Can I use Windows or DOS?, Do I need Linux?, Host Operating Systems and RTEMS, Host Operating Systems and RTEMS
+
+@subsection Can I use Windows or DOS?
+
+
+No, plain DOS and plain Win will not work, but Cygwin should.
+Other U*nix emulations, such as Mingw and DJGPP are not supported and very
+likely will not work.
+Cywin / WinNT is known to work, but at the time of writing this, there
+seem to persist non-RTEMS related issues with Cygwin under Win9x which
+seem to prevent success on those systems.
+
+
+@node Do I need Linux?, Which Linux distribution is recommended?, Can I use Windows or DOS?, Host Operating Systems and RTEMS
+
+@subsection Do I need Linux?
+
+
+No, you should be able to build RTEMS on any U*ix OS and under Cygwin/NT
+(cf. @ref{Can I use Windows or DOS?}).
+
+
+@node Which Linux distribution is recommended?, Development related questions, Do I need Linux?, Host Operating Systems and RTEMS
+
+@subsection Which Linux distribution is recommended?
+
+None, any recent U*nix should work, i.e.
+any recent Linux distribution should work, too.
+
+
+@node Development related questions, How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?, Which Linux distribution is recommended?, Building RTEMS
+
+@section Development related questions
+@ifinfo
+@menu
+* How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?::
+* What is no_bsp / no_cpu?::
+* What is the bare-BSP?::
+* What is the cpukit?::
+* Multilib vs.  RTEMS CPU-variants::
+* Keeping auto* generated files in CVS::
+* Importing RTEMS into CVS/RCS::
+* ./bootstrap::
+* configure --enable-maintainer-mode::
+* configure --program-[prefix|suffix|transform-name]::
+* configure.ac vs. configure.in::
+* Reporting bugs::
+@end menu
+@end ifinfo
+
+
+@node How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?, What is no_bsp / no_cpu?, Development related questions, Development related questions
+
+@subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?
+
+[FIXME:Partially obsolete]
+
+The simple answer is that between 4.0 and 4.5.0, RTEMS has moved to automake
+and greater compliance with GNU conventions.
+In 4.0, there was a single configure script at the top of the tree.
+Now RTEMS is configured more like other GNU tools -- as a collection of
+configurable entities.
+
+Each BSP now has its own configure script.
+I highly recommend you look at the Makefile.am's, configure.ac, of a similar
+BSP.  You might even want to consider running "bootstrap -c" from the top of
+the tree and looking at what is left.  bootstrap (cf. @ref{./bootstrap})
+generates/removes all automatically generated files.
+
+
+@node What is no_bsp / no_cpu?, What is the bare-BSP?, How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?, Development related questions
+
+@subsection What is no_bsp / no_cpu?
+
+@code{no_bsp} is a fictional BSP for a fictional CPU of type
+@code{no_cpu}.  @code{no_cpu/no_bsp} support files in RTEMS can be used as
+templates when implementing BSPs or porting RTEMS to new CPUs.
+
+
+@node What is the bare-BSP?, What is the cpukit?, What is no_bsp / no_cpu?, Development related questions
+
+@subsection What is the bare-BSP?
+
+At the time being RTEMS is build per BSP, with all support files being build
+separately for each BSP.  This can become unhandy when using several similar
+but not identical boards (e.g.  a PC with different peripherial cards plugged
+in), because this in general requires to implement a BSP for each setup.
+The bare BSP is a general, setup independent BSP which can be used when
+keeping all BSP specific parts external from RTEMS.
+
+At present time the bare BSP is in its infancy.
+It is known that it can be build for most CPUs RTEMS supports.
+It is also known to work in individual cases, but your mileage may vary.
+
+
+@node What is the cpukit?, Multilib vs.  RTEMS CPU-variants, What is the bare-BSP?, Development related questions
+
+@subsection What is the cpukit?
+
+[FIXME:To be extended]
+
+One major change having been introduced to RTEMS-4.6.0 is the cpukit,
+located below the directory @code{cpukit/} in RTEMS's toplevel directory.
+
+
+@node Multilib vs.  RTEMS CPU-variants, Keeping auto* generated files in CVS, What is the cpukit?, Development related questions
+
+@subsection Multilib vs.  RTEMS CPU-variants
+
+The GNU toolchain applies a specific classification of similar CPUs into
+CPU variants (eg.  SH1, SH2 etc.) to provide better support for each CPU variant.
+
+RTEMS uses a different classification because it internally requires more
+details about a specific CPU than the GNU toolchain's multilib classification
+provides.
+
+
+@node Keeping auto* generated files in CVS, Importing RTEMS into CVS/RCS, Multilib vs.  RTEMS CPU-variants, Development related questions
+
+@subsection Keeping auto* generated files in CVS
+
+When using CVS to archive source code, problems arise from keeping generated
+files in CVS.  In general, two possible solutions exist:
+
+@itemize @bullet
+
+@item Find a way to get correct timestamps after checking out the sources
+from CVS.  Some people try to achieve this by
+
+@itemize @bullet
+@item carefully checking in files into CVS in appropriate order
+@item applying scripts to fix timestamps accordingling (eg.  by applying
+@code{touch} and @code{find}).
+@end itemize
+
+@item Not keeping generated files in CVS, but regenerate them after
+having checked them out from CVS.
+
+@end itemize
+
+RTEMS favors the the latter variant, because it appears to be less error-prone
+and easier to handle (cf. @ref{./bootstrap} for details).
+
+
+@node Importing RTEMS into CVS/RCS, ./bootstrap, Keeping auto* generated files in CVS, Development related questions
+
+@subsection Importing RTEMS into CVS/RCS
+
+When importing RTEMS into CVS/RCS or similar, we recommend not to import
+auto* generated files (cf. @ref{Keeping auto* generated files in CVS}).
+
+To remove them before importing, run
+
+@example
+./bootstrap -c
+@end example
+
+from the toplevel directory of the source tree (cf. @ref{./bootstrap}).
+
+
+@node ./bootstrap, configure --enable-maintainer-mode, Importing RTEMS into CVS/RCS, Development related questions
+
+@subsection ./bootstrap
+
+
+@code{bootstrap} is a simple shell script which automatically generates all
+auto* generated files within RTEMS's source tree (Other packages use the name
+@code{autogen.sh} for similar scripts).  You will need to have autoconf,
+automake and further underlying packages installed to apply it.
+
+It typically should be applied when having:
+
+@itemize @bullet
+
+@item checked out RTEMS sources from a CVS repository which does
+not contain generated files.
+
+@item added new automake / autoconf files to the source tree (eg.
+having added a new BSP), and when not being sure about what needs to be
+updated.
+
+@end itemize
+
+Once all autoconf/automake generated files are present, you will rarely
+need to run @code{bootstrap}, because automake automatically updates
+generated files when it detects some files need to be updated (Cf.
+@ref{configure --enable-maintainer-mode}).
+
+
+@node configure --enable-maintainer-mode, configure --program-[prefix|suffix|transform-name], ./bootstrap, Development related questions
+
+@subsection configure --enable-maintainer-mode
+
+When working within the source-tree, consider to append
+@code{--enable-maintainer-mode} to the options passed to configure RTEMS.
+
+@example
+<path>/rtems-@value{VERSION}/configure <options> --enable-maintainer-mode
+@end example
+
+This will enable the maintainer-mode in automake generated Makefiles, which
+will let automake take care about dependencies between auto* generated
+files.  I.e.  auto* generated files will get automatically updated.
+
+Configuring RTEMS in maintainer-mode will require to have autoconf, automake
+and underlying tools installed (Cf. @ref{Required Tools}).
+
+
+@node configure --program-[prefix|suffix|transform-name], configure.ac vs. configure.in, configure --enable-maintainer-mode, Development related questions
+
+@subsection configure --program-[prefix|suffix|transform-name]
+
+These are generic configure script options automatically added by autoconf.
+RTEMS configuration does not support these, worse, they interfer with
+RTEMS's configuration -- i.e. @b{do not use them}.
+
+
+@node configure.ac vs. configure.in, Reporting bugs, configure --program-[prefix|suffix|transform-name], Development related questions
+
+@subsection configure.ac vs. configure.in
+
+autoconf < 2.50 used the name @code{configure.in} for it's input files.
+autoconf >= 2.50 recommends using the name @code{configure.ac}, instead.
+
+RTEMS > 4.5.0 applies autoconf >= 2.50, therefore all former RTEMS's
+@code{configure.in}'s have been renamed into @code{configure.ac} and
+have been adapted to autoconf >= 2.50 demands.
+
+
+@node Reporting bugs, , configure.ac vs. configure.in, Development related questions
+
+@subsection Reporting bugs
+
+Several possibilities (In decreasing preference):
+@itemize @bullet
+@item File a bug report at @uref{@value{RTEMSGNATS},RTEMS's GNATS}
+@item Send an email to @uref{mailto:@value{RTEMSBUGS},@value{RTEMSBUGS}}
+@item Report your problem to one of the RTEMS mailing lists
+(Cf. @ref{Are there any mailing lists?}).
+@end itemize
+
diff --git a/doc/FAQ/concepts.texi b/doc/FAQ/concepts.texi
new file mode 100644
index 0000000000..5ca11524c4
--- /dev/null
+++ b/doc/FAQ/concepts.texi
@@ -0,0 +1,31 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node RTEMS Concepts, RTEMS Workspace versus Program Heap, , Top
+
+@chapter RTEMS Concepts
+@ifinfo
+@menu
+* RTEMS Workspace versus Program Heap::
+@end menu
+@end ifinfo
+
+The questions in this category are hints that help basic understanding.
+
+
+@node RTEMS Workspace versus Program Heap, , RTEMS Concepts, RTEMS Concepts
+
+@section RTEMS Workspace versus Program Heap
+
+The RTEMS Workspace is used to allocate space for objects created
+by RTEMS such as tasks, semaphores, message queues, etc..  It is
+primarily used during system initialization although task stacks
+and message buffer areas are also allocated from here.
+@ref{How do I determine how much memory is left?}.
+
diff --git a/doc/FAQ/debug.texi b/doc/FAQ/debug.texi
new file mode 100644
index 0000000000..1b46eb8c3d
--- /dev/null
+++ b/doc/FAQ/debug.texi
@@ -0,0 +1,214 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node Debugging Hints, Executable Size, , Top
+
+@chapter Debugging Hints
+@ifinfo
+@menu
+* Executable Size::
+* Malloc::
+* How do I determine how much memory is left?::
+* How do I convert an executable to IEEE-695?::
+@end menu
+@end ifinfo
+
+The questions in this category are hints that can ease debugging.
+
+
+@node Executable Size, Why is my executable so big?, Debugging Hints, Debugging Hints
+
+@section Executable Size
+@ifinfo
+@menu
+* Why is my executable so big?::
+@end menu
+@end ifinfo
+
+
+@node Why is my executable so big?, Malloc, Executable Size, Executable Size
+
+@subsection Why is my executable so big?
+
+There are two primary causes for this.  The most common is that
+you are doing an @code{ls -l} and looking at the actual file
+size -- not the size of the code in the target image.  This
+file could be in an object format such as ELF or COFF and
+contain debug information.  If this is the case, it could
+be an order of magnitude larger than the required code space.
+Use the strip command in your cross toolset to remove debugging
+information.
+
+The following example was done using the i386-rtems cross toolset
+and the pc386 BSP.  Notice that with symbolic information included
+the file @code{hello.exe} is almost a megabyte and would barely fit
+on a boot floppy.  But there is actually only about 93K of code
+and initialized data.  The other 800K is symbolic information
+which is not required to execute the application.
+
+@example
+$ ls -l hello.exe
+-rwxrwxr-x    1 joel     users      930515 May  2 09:50 hello.exe
+$ i386-rtems-size hello.exe
+   text	   data	    bss	    dec	    hex	filename
+  88605	   3591	  11980	 104176	  196f0	hello.exe
+$ i386-rtems-strip hello.exe
+$ ls -l hello.exe
+-rwxrwxr-x    1 joel     users      106732 May  2 10:02 hello.exe
+$ i386-rtems-size hello.exe
+   text	   data	    bss	    dec	    hex	filename
+  88605	   3591	  11980	 104176	  196f0	hello.exe
+@end example
+
+Another alternative is that the executable file is in an ASCII
+format such as Motorola Srecords.  In this case, there is
+no debug information in the file but each byte in the target
+image requires two bytes to represent.  On top of that, there
+is some overhead required to specify the addresses where the image
+is to be placed in target memory as well as checksum information.
+In this case, it is not uncommon to see executable files
+that are between two and three times larger than the actual
+space required in target memory.
+
+Remember, the debugging information is required to do symbolic
+debugging with gdb.  Normally gdb obtains its symbolic information
+from the same file that it gets the executable image from.  However,
+gdb does not require that the executable image and symbolic
+information be obtained from the same file.  So you might
+want to create a @code{hello_with_symbols.exe}, copy that
+file to @code{hello_without_symbols.exe}, and strip
+@code{hello_without_symbols.exe}.  Then gdb would have to
+be told to read symbol information from @code{hello_with_symbols.exe}.
+The gdb command line option @code{-symbols} or command
+@code{symbol-file} may be used to specify the file read
+for symbolic information.
+
+
+
+@node Malloc, Is malloc reentrant?, Why is my executable so big?, Debugging Hints
+
+@section Malloc
+@ifinfo
+@menu
+* Is malloc reentrant?::
+* When is malloc initialized?::
+@end menu
+@end ifinfo
+
+
+@node Is malloc reentrant?, When is malloc initialized?, Malloc, Malloc
+
+@subsection Is malloc reentrant?
+
+Yes.  The RTEMS Malloc implementation is reentrant.  It is
+implemented as calls to the Region Manager in the Classic API.
+
+
+@node When is malloc initialized?, How do I determine how much memory is left?, Is malloc reentrant?, Malloc
+
+@subsection When is malloc initialized?
+
+During BSP initialization, the @code{bsp_libc_init} routine
+is called.  This routine initializes the heap as well as
+the RTEMS system call layer (open, read, write, etc.) and
+the RTEMS reentrancy support for the Cygnus newlib Standard C
+Library.
+
+The @code{bsp_libc_init} routine is passed the size and starting
+address of the memory area to be used for the program heap as well
+as the amount of memory to ask @code{sbrk} for when the heap is
+exhausted.  For most BSPs, all memory available is placed in the
+program heap thus it can not be extended dynamically by calls to
+@code{sbrk}.
+
+
+@node How do I determine how much memory is left?, How much memory is left in the RTEMS Workspace?, When is malloc initialized?, Debugging Hints
+
+@section How do I determine how much memory is left?
+@ifinfo
+@menu
+* How much memory is left in the RTEMS Workspace?::
+* How much memory is left in the Heap?::
+@end menu
+@end ifinfo
+
+First there are two types of memory: RTEMS Workspace and Program Heap.
+The RTEMS Workspace is the memory used by RTEMS to allocate control
+structures for system objects like tasks and semaphores, task
+stacks, and some system data structures like the ready chains.
+The Program Heap is where "malloc'ed" memory comes from.
+
+Both are essentially managed as heaps based on the Heap Manager
+in the RTEMS SuperCore.  The RTEMS Workspace uses the Heap Manager
+directly while the Program Heap is actually based on an RTEMS Region
+from the Classic API.  RTEMS Regions are in turn based on the Heap
+Manager in the SuperCore.
+
+
+@node How much memory is left in the RTEMS Workspace?, How much memory is left in the Heap?, How do I determine how much memory is left?, How do I determine how much memory is left?
+
+@subsection How much memory is left in the RTEMS Workspace?
+
+An executive workspace overage can be fairly easily spotted with a
+debugger.  Look at _Workspace_Area.  If first == last, then there is only
+one free block of memory in the workspace (very likely if no task
+deletions).  Then do this:
+
+(gdb) p *(Heap_Block *)_Workspace_Area->first
+$3 = @{back_flag = 1, front_flag = 68552, next = 0x1e260, previous = 0x1e25c@}
+
+In this case, I had 68552 bytes left in the workspace.
+
+
+@node How much memory is left in the Heap?, How do I convert an executable to IEEE-695?, How much memory is left in the RTEMS Workspace?, How do I determine how much memory is left?
+
+@subsection How much memory is left in the Heap?
+
+The C heap is a region so this should work:
+
+(gdb) p *((Region_Control *)_Region_Information->local_table[1])->Memory->first
+$9 = @{back_flag = 1, front_flag = 8058280, next = 0x7ea5b4,
+  previous = 0x7ea5b0@}
+
+In this case, the first block on the C Heap has 8,058,280 bytes left.
+
+
+@node How do I convert an executable to IEEE-695?, , How much memory is left in the Heap?, Debugging Hints
+
+@section How do I convert an executable to IEEE-695?
+
+This section is based on an email from Andrew Bythell
+<abythell@@nortelnetworks.com> in July 1999.
+
+Using Objcopy to convert m68k-coff to IEEE did not work.  The new IEEE
+object could not be read by tools like the XRay BDM Debugger.
+
+The exact nature of this problem is beyond me, but I did narrow it down to a
+problem with objcopy in binutils 2-9.1.  To no surprise, others have
+discovered this problem as well, as it has been fixed in later releases.
+
+I compiled a snapshot of the development sources from 07/26/99 and
+everything now works as it should.  The development sources are at
+@uref{http://sourceware.cygnus.com/binutils} (thanks Ian!)
+
+Additional notes on converting an m68k-coff object for use with XRay (and
+others):
+
+@enumerate
+
+
+@item The m68k-coff object must be built with the -gstabs+ flag.  The -g flag
+alone didn't work for me.
+
+@item Run Objcopy with the --debugging flag to copy debugging information.
+
+@end enumerate
+
+
+
diff --git a/doc/FAQ/endoftime.texi b/doc/FAQ/endoftime.texi
new file mode 100644
index 0000000000..4664235baf
--- /dev/null
+++ b/doc/FAQ/endoftime.texi
@@ -0,0 +1,135 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node Date/Time Issues in Systems Using RTEMS, Hardware Issues, , Top
+
+@chapter Date/Time Issues in Systems Using RTEMS
+@ifinfo
+@menu
+* Hardware Issues::
+* RTEMS Specific Issues::
+* Language Specific Issues::
+* Date/Time Conclusion::
+@end menu
+@end ifinfo
+
+This section provides technical information regarding
+date/time representation issues and RTEMS.  The Y2K problem has
+lead numerous people to ask these questions.  The answer to
+these questions are actually more complicated than most
+people asking the question expect.  RTEMS supports multiple
+standards and each of these standards has its own epoch and
+time representation.  These standards include both programming
+API and programming language standards.
+
+In addition to the issues inside RTEMS
+itself, there is the complicating factor that the Board
+Support Package or application itself may interface with hardware
+or software that has its own set of date/time representation
+issues.
+
+In conclusion, viewing date/time representation as "the Y2K problem"
+is very short-sighted.  Date/time representation should be viewed as
+a systems level issue for the system you are building.  Each software
+and hardware component in the system as well as the systems being
+connected to is a factor in the equation.
+
+
+@node Hardware Issues, RTEMS Specific Issues, Date/Time Issues in Systems Using RTEMS, Date/Time Issues in Systems Using RTEMS
+
+@section Hardware Issues
+
+Numerous Real-Time Clock (RTC) controllers provide only a two-digit
+Binary Coded Decimal (BCD) representation for the current year.  Without
+software correction, these chips are a classic example of the Y2K problem.
+When the RTC rolls the year register over from 99 to 00, the device
+has no idea whether the year is 1900 or 2000.  It is the responsibility
+of the device driver to recognize this condition and correct for it.
+The most common technique used is to assume that all years prior
+to either the existence of the board or RTEMS are past 2000.  The
+starting year (epoch) for RTEMS is 1988.  Thus,
+
+@itemize @bullet
+@item Chip year values 88-99 are interpreted as years 1988-2002.
+@item Chip year values 00-87 are interpreted as years 2000-2087.
+@end itemize
+
+Using this technique, a RTC using a
+two-digit BCD representation of the current year will overflow on
+January 1, 2088.
+
+
+@node RTEMS Specific Issues, Language Specific Issues, Hardware Issues, Date/Time Issues in Systems Using RTEMS
+
+@section RTEMS Specific Issues
+
+Internally, RTEMS uses an unsigned thirty-two bit integer to represent the
+number of seconds since midnight January 1, 1988.  This counter will
+overflow on February 5, 2124.
+
+The time/date services in the Classic API will overflow when the
+RTEMS internal date/time representation overflows.
+
+The POSIX API uses the type @i{time_t} to represent the number of
+seconds since January 1, 1970.  Many traditional UNIX systems as
+well as RTEMS define @i{time_t} as a signed thirty-two bit integer.
+This representation overflows on January 18, 2038.  The solution
+usually proposed is to define @i{time_t} as a sixty-four bit
+integer.  This solution is appropriate for for UNIX workstations
+as many of them already support sixty-four bit integers natively.
+At this time, this imposes a burden on embedded systems which are
+still primarily using processors with native integers of thirty-two
+bits or less.
+
+
+@node Language Specific Issues, Date/Time Conclusion, RTEMS Specific Issues, Date/Time Issues in Systems Using RTEMS
+
+@section Language Specific Issues
+
+The Ada95 Language Reference Manual requires that the @i{Ada.Calendar}
+package support years through the year 2099.  However, just as the
+hardware is layered on top of hardware and may inherit its limits,
+the Ada tasking and run-time support is layered on top of an operating
+system.  Thus, if the operating system or underlying hardware fail
+to correctly report dates after 2099, then it is possible for the
+@i{Ada.Calendar} package to fail prior to 2099.
+
+
+@node Date/Time Conclusion, , Language Specific Issues, Date/Time Issues in Systems Using RTEMS
+
+@section Date/Time Conclusion
+
+Each embedded system could be impacted by a variety of date/time
+representation issues.  Even whether a particular date/time
+representation issue impacts a system is questionable.  A system
+using only the RTEMS Classic API is not impacted by the
+date/time representation issues in POSIX.  A system not using
+date/time at all is not impacted by any of these issues.  Also
+the planned end of life for a system may make these issues
+moot.
+
+The following is a timeline of the date/time representation
+issues presented in this section:
+
+@itemize @bullet
+
+@item 2000 - Two BCD Digit Real-Time Clock Rollover
+
+@item 2038 - POSIX @i{time_t} Rollover
+
+@item 2088 - Correction for Two BCD Digit Real-Time Clock Rollover
+
+@item 2099 - Ada95 @i{Ada.Calendar} Rollover
+
+@item 2124 - RTEMS Internal Seconds Counter Rollover
+
+@end itemize
+
+
+
diff --git a/doc/FAQ/freesw.texi b/doc/FAQ/freesw.texi
new file mode 100644
index 0000000000..5f082c69a0
--- /dev/null
+++ b/doc/FAQ/freesw.texi
@@ -0,0 +1,213 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node Free Software that Works with RTEMS, Development Tools, , Top
+
+@chapter Free Software that Works with RTEMS
+@ifinfo
+@menu
+* Development Tools::
+* omniORB::
+* TCL::
+* ncurses::
+* zlib::
+@end menu
+@end ifinfo
+
+This section describes other free software packages that are known to work
+with RTEMS.
+
+
+@node Development Tools, Basic Development Environment, Free Software that Works with RTEMS, Free Software that Works with RTEMS
+
+@section Development Tools
+@ifinfo
+@menu
+* Basic Development Environment::
+* GNU Ada::
+* DDD - Data Display Debugger::
+@end menu
+@end ifinfo
+
+
+@node Basic Development Environment, GNU Ada, Development Tools, Development Tools
+
+@subsection Basic Development Environment
+
+The standard RTEMS development environment consists of the following GNU
+components:
+
+@itemize @bullet
+
+@item gcc
+@item binutils
+@item gdb
+
+@end itemize
+
+Although not from the Free Software Foundation, the Cygnus newlib C
+library integrates well with the GNU tools and is a standard part of the
+RTEMS development environment.
+
+
+@node GNU Ada, DDD - Data Display Debugger, Basic Development Environment, Development Tools
+
+@subsection GNU Ada
+
+For those interested in using the Ada95 programming language, the GNU Ada
+compiler (GNAT) is available and has excellent support for RTEMS.
+
+
+@node DDD - Data Display Debugger, omniORB, GNU Ada, Development Tools
+
+@subsection DDD - Data Display Debugger
+
+By far the easiest way to use DDD if you are on a Redhat or SuSE Linux system
+is to retrieve the RPM package for your OS version.  In general, it is
+easier to install a static binary since doing so avoids all problems
+with dynamic library versions.
+
+Some versions of DDD have had trouble with Lesstif.  If you
+are using Lesstif, you will need version 0.88 or newer.  It
+is also available as an RPM at the popular sites.  Another Motif
+clone is Motive and versions 1.2 and newer known to work with DDD
+on popular distributions of Linux including RedHat and Slackware.
+
+Installed as RPMs, DDD in conjunction with either Lesstif or Motive
+should work out-of-the-box.
+
+User comments indicate that both Lesstif and DDD can be built
+from scratch without any problems.  Instructions on installing DDD
+are at @uref{http://www.cs.tu-bs.de/softech/ddd/}.  They
+indicate that
+
+@itemize @bullet
+LessTif should be used in (default) Motif 1.2 compatibility mode.
+
+The Motif 2.0 compatibility mode of LessTif is still incomplete.
+@end itemize
+
+So configure lesstif with --enable-default-12.
+
+The configure script is broken (see  www.lesstif.org --> known problems)
+for 0.88.1. I didn't fix the script as they show, so I just have links
+in /usr/local/lib (also shown).
+
+Watch out: Lesstif installs its libraries in /usr/local/Lesstif. You
+will need to update /etc/ld.so.conf and regenerate the cache of shared
+library paths to point to the Motif 1.2 library.
+
+The following notes are from an RTEMS user who uses DDD in conjunction
+with Lesstif.  Configure DDD "--with-motif-libraries=/usr/local/lib
+--with-motif-includes=/usr/local/include" DDD needs gnuplot 3.7.
+@uref{ftp://ftp.dartmouth.edu/pub/gnuplot/gnuplot-3.7.tar.gz}. Build and
+install from scratch.
+
+DDD can be started from a script that specifies the cross debugger.
+This simplifies the invocation.  The following example shows what
+a script doing this looks like.
+
+@example
+#!/bin/bash
+ddd --debugger m68k-elf-gdb $1
+@end example
+
+Under many flavors of UNIX, you will likely have to relax permissions.
+
+On Linux, to get gdb to use the serial ports while running as a
+normal user, edit /etc/security/console.perms, and create a <serial>
+class (call it whatever you want).
+
+@example
+<serial>=/dev/ttyS* /dev/cua*
+@end example
+
+Now enable the change of ownership of these devices when users log in
+from the console:
+
+@example
+<console> 0600 <serial> 0600 root
+@end example
+
+Users report using minicom to communicate with the target to initiate a TFTP
+download. They then suspend minicom, launch DDD, and begin debugging.
+
+The procedure should be the same on other platforms, modulo the choice
+of terminal emulator program and the scheme used to access the serial
+ports. From problem reports on the cygwin mailing list, it appears that
+GDB has some problems communicating over serial lines on that platform.
+
+NOTE: GDB does not like getting lots of input from the program under test
+over the serial line. Actually, it does not care, but it looses
+characters. It would appear that flow control is not re-enabled when it
+resumes program execution. At times, it looked like the test were
+failing, but everything was OK. We modified the MVME167 serial driver to
+send test output to another serial port.  Using two serial ports is
+usually the easiest way to get test output while retaining a reliable debug
+connection regardless of the debugger/target combination.
+
+NOTE: Enabling gdb's remote cache might prevent this (Observed with SH1
+boards, but may also be valid for targets):
+@example
+gdb > set remotecache
+@end example
+
+Information provided by Charles-Antoine Gauthier (charles.gauthier@@iit.nrc.ca)
+Jiri Gaisler (jgais@@ws.estec.esa.nl) and Ralf Cors@'epius
+(corsepiu@@faw.uni-ulm.de)
+
+
+
+@node omniORB, TCL, DDD - Data Display Debugger, Free Software that Works with RTEMS
+
+@section omniORB
+
+omniORB is a GPL'ed CORBA which has been ported to RTEMS.  It is
+available from
+(@uref{http://www.uk.research.att.com/omniORB/omniORB.html,http://www.uk.research.att.com/omniORB/omniORB.html})
+.
+
+For information on the RTEMS port of omniORB to RTEMS, see the following
+URL
+(@uref{http://www.connecttel.com/corba/rtems_omni.html,http://www.connecttel.com/corba/rtems_omni.html}).
+
+C++ exceptions must work properly on your target for omniORB to work.
+
+The port of omniORB to RTEMS was done by Rosimildo DaSilva
+<rdasilva@@connecttel.com>.
+
+
+@node TCL, ncurses, omniORB, Free Software that Works with RTEMS
+
+@section TCL
+
+Tool Command Language.
+
+ditto
+
+
+@node ncurses, zlib, TCL, Free Software that Works with RTEMS
+
+@section ncurses
+
+Free version of curses.
+
+ditto
+
+
+
+@node zlib, , ncurses, Free Software that Works with RTEMS
+
+@section zlib
+
+Free compression/decompression library.
+
+ditto
+
+
diff --git a/doc/FAQ/hwdebugaids.texi b/doc/FAQ/hwdebugaids.texi
new file mode 100644
index 0000000000..635b7285ac
--- /dev/null
+++ b/doc/FAQ/hwdebugaids.texi
@@ -0,0 +1,126 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node Hardware to Ease Debugging, MC683xx BDM Support for GDB, , Top
+
+@chapter Hardware to Ease Debugging
+@ifinfo
+@menu
+* MC683xx BDM Support for GDB::
+* MPC8xx BDM Support for GDB::
+@end menu
+@end ifinfo
+
+The items in this category provide information on various hardware
+debugging assistants that are available.
+
+
+@node MC683xx BDM Support for GDB, MPC8xx BDM Support for GDB, Hardware to Ease Debugging, Hardware to Ease Debugging
+
+@section MC683xx BDM Support for GDB
+
+Eric Norum (eric@@skatter.usask.ca) has a driver for a parallel
+port interface to a BDM module.  This driver has a long history
+and is based on a driver by Gunter Magin (magin@@skil.camelot.de)
+which in turn was based on BD32 for DOS by Scott Howard.  Eric Norum
+and Chris Johns (ccj@@acm.org) have put together a package containing
+everything you need to use this BDM driver including software, PCB layouts,
+and machining drawings.  From the README:
+
+"This package contains everything you need to be able to run GDB on
+Linux and control a Motorola CPU32+ (68360) or Coldfire (5206, 5206e, or
+5207) target through a standard PC parallel port."
+
+Information on this BDM driver is available at the following URL:
+
+@example
+http://www.calm.hw.ac.uk/davidf/coldfire/gdb-bdm-linux.htm
+@end example
+
+The package is officially hosted at Eric Norum's ftp site:
+
+@example
+ftp://skatter.usask.ca/pub/eric/BDM-Linux-gdb/
+@end example
+
+Peter Shoebridge (peter@@zeecube.com) has ported the Linux
+parallel port BDM driver from Eric Norum to Windows NT.  It is
+available at http://www.zeecube.com/bdm.
+
+The efi332 project has a home-built BDM module and gdb backend for
+Linux.  See http://efi332.eng.ohio-state.edu/efi332/hardware.html)
+for details.  The device driver and gdb backend are based on those
+by Gunter Magin (magin@@skil.camelot.de) available from
+ftp.lpr.e-technik.tu-muenchen.de.
+
+Pavel Pisa (pisa@@cmp.felk.cvut.cz) has one available at
+http://cmp.felk.cvut.cz/~pisa/m683xx/bdm_driver.html.
+
+Huntsville Microsystems (HMI) has GDB support for their BDM module
+available upon request.  It is also available from their ftp site:
+ftp://ftp.hmi.com/pub/gdb
+
+The Macraigor OCD BDM module has a driver for Linux
+written by Gunter Magin (magin@@skil.camelot.de).
+No URLs yet.
+
+Finally, there is a overview of BDM at the following URL:
+http://cmp.felk.cvut.cz/~pisa/m683xx/bdm_driver.html.
+
+Information in this section from:
+
+@itemize @bullet
+@item Brendan Simon <brendan@@dgs.monash.edu.au>
+@item W Gerald Hicks <wghicks@@bellsouth.net>
+@item Chris Johns <ccj@@acm.org>
+@item Eric Norum <eric@@skatter.usask.ca>
+@item Gunter Magin <magin@@skil.camelot.de>
+
+@end itemize
+
+
+
+@node MPC8xx BDM Support for GDB, , MC683xx BDM Support for GDB, Hardware to Ease Debugging
+
+@section MPC8xx BDM Support for GDB
+
+@c "Adrian Bocaniciu" <a.bocaniciu@computer.org> has a driver
+@c for NT and is willing to share it but he needs to be emailed
+@c privately since he needs to explain somethings about it.
+@c It has been used for over a year as of 08/18/99.
+
+Christian Haan <chn@@intego.de> has written a driver for FreeBSD
+based for"a slightly changed ICD BDM module (because of changes
+in the BDM interface on the PowerPC)" that "probably will work with
+the PD module too."  His work is based on the M68K BDM work by
+Gunter Magin (Gunter.Magin@@skil.camelot.de) and
+the PPC BDM for Linux work by Sergey Drazhnikov (swd@@agua.comptek.ru).
+This is not yet publicly available.
+
+Sergey Drazhnikov (swd@@agua.comptek.ru) has written a PPC BDM driver for
+Linux.  Information is available at http://cyclone.parad.ru/ppcbdm.
+
+Huntsville Microsystems (HMI) has GDB support for their BDM module
+available upon request.  It is also available from their ftp site:
+ftp://ftp.hmi.com/pub/gdb
+
+GDB includes support for a set of primitives to support the Macraigor
+Wiggler (OCD BDM).  Unfortunately, this requires the use of a
+proprietary interface and is supported only on Windows.  This forces
+one to use CYGWIN.  Reports are that this results in a slow
+interface.  Scott Howard (http://www.objsw.com) has announced
+that support for the gdb+wiggler combination under DJGPP which should
+run significantly faster.
+
+@itemize @bullet
+@item Leon Pollak <leonp@@plris.com>
+@item Christian Haan <chn@@intego.de>
+@end itemize
+
+
diff --git a/doc/FAQ/projects.texi b/doc/FAQ/projects.texi
new file mode 100644
index 0000000000..8a370338db
--- /dev/null
+++ b/doc/FAQ/projects.texi
@@ -0,0 +1,169 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node RTEMS Projects, Other Filesystems, , Top
+
+@chapter RTEMS Projects
+@ifinfo
+@menu
+* Other Filesystems::
+* Java::
+* CORBA::
+* APIs::
+@end menu
+@end ifinfo
+
+The questions in this category are regarding things that people
+are working on or that the RTEMS community would like to see work on.
+
+There are multiple ways to support the RTEMS Project.  Financial support
+is always welcomed.  This can be via sponsorship of a specific project
+such as one of the ones listed here or via volunteering in some
+capacity.
+
+
+@node Other Filesystems, Java, RTEMS Projects, RTEMS Projects
+
+@section Other Filesystems
+
+This is a list of the filesystems that would be nice to have support
+for in RTEMS.  For each filsystem, status and contact information is
+provided for those who have expressed interest in helping out or are actively
+working on it.
+
+@itemize @bullet
+@item TFTP client - read only, no write capability
+@itemize @bullet
+@item No Contact
+@end itemize
+
+@item DOS Filesystem - ???
+@itemize @bullet
+@item Peter Shoebridge <peter@@zeecube.com>
+@item Victor V. Vengerov <vvv@@tepkom.ru>
+@end itemize
+
+@item CD-ROM Filesystem - ???
+@itemize @bullet
+@item Peter Shoebridge <peter@@zeecube.com>
+@end itemize
+
+@item Flash Filesystem(s) - ???
+@itemize @bullet
+@item Rod Barman <rodb@@ieee.org>
+@item Victor V. Vengerov <vvv@@tepkom.ru>
+@end itemize
+
+@item Remote Host Filesystem - ???
+@itemize @bullet
+@item Wayne Bullaughey <wayne@@wmi.com>
+@end itemize
+
+@item NFS client - ???
+@itemize @bullet
+@item No Contact
+@end itemize
+
+@end itemize
+
+
+@node Java, Kaffe, Other Filesystems, RTEMS Projects
+
+@section Java
+@ifinfo
+@menu
+* Kaffe::
+* GNU Java Compiler (gjc)::
+@end menu
+@end ifinfo
+
+
+@node Kaffe, GNU Java Compiler (gjc), Java, Java
+
+@subsection Kaffe
+
+This porting effort is underway and active.
+
+@itemize @bullet
+@item Jiri Gaisler <jgais@@ws.estec.esa.nl>
+@item Oscar Martinez de la Torre <omt@@wm.estec.esa.nl>
+@end itemize
+
+NOTE: An older version of Kaffe was ported to a pre-4.0 version of RTEMS.
+The network support in RTEMS was immature at that port and Kaffe had
+portability problems.  Together these resulted in an unclean port which
+was never merged.
+
+
+@node GNU Java Compiler (gjc), CORBA, Kaffe, Java
+
+@subsection GNU Java Compiler (gjc)
+
+This porting effort is underway and active.
+
+@itemize @bullet
+@item Charles-Antoine Gauthier <charles.gauthier@@iit.nrc.ca>
+@end itemize
+
+
+@node CORBA, TAO, GNU Java Compiler (gjc), RTEMS Projects
+
+@section CORBA
+@ifinfo
+@menu
+* TAO::
+@end menu
+@end ifinfo
+
+
+@node TAO, APIs, CORBA, CORBA
+
+@subsection TAO
+
+This porting effort is pending testing.  Erik ported the code but then
+discovered that his target board did not have enough memory to run
+any TAO tests.
+
+@itemize @bullet
+@item Erik Ivanenko <erik.ivanenko@@utoronto.ca>
+@end itemize
+
+
+@node APIs, POSIX 1003.1b, TAO, RTEMS Projects
+
+@section APIs
+@ifinfo
+@menu
+* POSIX 1003.1b::
+* ITRON 3.0::
+@end menu
+@end ifinfo
+
+
+@node POSIX 1003.1b, ITRON 3.0, APIs, APIs
+
+@subsection POSIX 1003.1b
+
+Support for POSIX 1003.1b is mature but there are a few remaining
+items including a handful of services, performance tests, and
+documentation.  Please refer to the Status chapter of the
+@i{POSIX API User's Guide} for more details.
+
+
+@node ITRON 3.0, , POSIX 1003.1b, APIs
+
+@subsection ITRON 3.0
+
+Support for ITRON 3.0 is in its beginning stages.  There are
+numerous managers left to implement, both functional and
+performance tests to write, and much documentation remaining.
+Please refer to the Status chapter of the @i{ITRON 3.0 API User's Guide}
+for specific details.
+
+
diff --git a/doc/FAQ/tools.texi b/doc/FAQ/tools.texi
new file mode 100644
index 0000000000..0b6509f06f
--- /dev/null
+++ b/doc/FAQ/tools.texi
@@ -0,0 +1,91 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@node General Development Tool Hints, What is GNU?, Top, Top
+
+@chapter General Development Tool Hints
+@ifinfo
+@menu
+* What is GNU?::
+* How do I generate a patch?::
+* How do I apply a patch?::
+@end menu
+@end ifinfo
+
+The questions in this category are related to the GNU development tools
+in a non-language specific way.
+
+
+@node What is GNU?, How do I generate a patch?, General Development Tool Hints, General Development Tool Hints
+
+@section What is GNU?
+
+Take a look at @uref{http://www.gnu.org,http://www.gnu.org} for information on the GNU Project.
+
+
+@node How do I generate a patch?, How do I apply a patch?, What is GNU?, General Development Tool Hints
+
+@section How do I generate a patch?
+
+The RTEMS patches to the development tools are generated using a
+command like this
+
+@example
+diff -N -P -r -c TOOL-original-image TOOL-with-changes >PATCHFILE
+@end example
+
+where the options are:
+
+@itemize @bullet
+
+@item -N and -P take care of adding and removing files (be careful not to
+include junk files like file.mybackup)
+
+@item -r tells diff to recurse through subdirectories
+
+@item -c is a context diff (easy to read for humans)
+
+@end itemize
+
+Please look at the generated PATCHFILE and make sure it does not
+contain anything you did not intend to send to the maintainers.
+It is easy to accidentally leave a backup file in the modified
+source tree or have a spurious change that should not be
+in the PATCHFILE.
+
+If you end up with the entire contents of a file in the patch
+and can't figure out why, you may have different CR/LF scheme
+in the two source files.  The GNU open-source packages usually have
+UNIX style CR/LF.  If you edit on a Windows platform, the line
+terminators may have been transformed by the editor into Windows
+style.
+
+
+@node How do I apply a patch?, , How do I generate a patch?, General Development Tool Hints
+
+@section How do I apply a patch?
+
+Patches generated with the @code{diff} program are fed into the
+@code{patch} program as follows:
+
+@example
+patch -p1 <PATCHFILE
+@end example
+
+where the options are:
+
+@itemize @bullet
+
+@item -pNUM tells @code{patch} to strip off NUM slashes from the
+pathname.
+
+@end itemize
+
+If @code{patch} prompts for a file to patch, you may need to adjust NUM.
+
diff --git a/doc/FAQ/version.texi b/doc/FAQ/version.texi
new file mode 100644
index 0000000000..ee10d7c24e
--- /dev/null
+++ b/doc/FAQ/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 5 March 2004
+@set UPDATED-MONTH March 2004
+@set EDITION 4.6.99.1
+@set VERSION 4.6.99.1