From 2af46634a33fcd9aa89444f7279e80bdd86f862e Mon Sep 17 00:00:00 2001 From: Ralf Corsepius Date: Sat, 31 Jul 2004 03:27:44 +0000 Subject: 2004-07-31 Ralf Corsepius * 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. --- doc/FAQ/basic.texi | 268 +++++++++++++++++++++ doc/FAQ/bsp.texi | 51 ++++ doc/FAQ/build45.texi | 602 +++++++++++++++++++++++++++++++++++++++++++++++ doc/FAQ/concepts.texi | 31 +++ doc/FAQ/debug.texi | 214 +++++++++++++++++ doc/FAQ/endoftime.texi | 135 +++++++++++ doc/FAQ/freesw.texi | 213 +++++++++++++++++ doc/FAQ/hwdebugaids.texi | 126 ++++++++++ doc/FAQ/projects.texi | 169 +++++++++++++ doc/FAQ/tools.texi | 91 +++++++ doc/FAQ/version.texi | 4 + 11 files changed, 1904 insertions(+) create mode 100644 doc/FAQ/basic.texi create mode 100644 doc/FAQ/bsp.texi create mode 100644 doc/FAQ/build45.texi create mode 100644 doc/FAQ/concepts.texi create mode 100644 doc/FAQ/debug.texi create mode 100644 doc/FAQ/endoftime.texi create mode 100644 doc/FAQ/freesw.texi create mode 100644 doc/FAQ/hwdebugaids.texi create mode 100644 doc/FAQ/projects.texi create mode 100644 doc/FAQ/tools.texi create mode 100644 doc/FAQ/version.texi 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{/c//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{/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 +/rtems-@value{VERSION}/configure --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 + 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 +class (call it whatever you want). + +@example +=/dev/ttyS* /dev/cua* +@end example + +Now enable the change of ownership of these devices when users log in +from the console: + +@example + 0600 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 +. + + +@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 +@item W Gerald Hicks +@item Chris Johns +@item Eric Norum +@item Gunter Magin + +@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" 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 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 +@item Christian Haan +@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 +@item Victor V. Vengerov +@end itemize + +@item CD-ROM Filesystem - ??? +@itemize @bullet +@item Peter Shoebridge +@end itemize + +@item Flash Filesystem(s) - ??? +@itemize @bullet +@item Rod Barman +@item Victor V. Vengerov +@end itemize + +@item Remote Host Filesystem - ??? +@itemize @bullet +@item Wayne Bullaughey +@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 +@item Oscar Martinez de la Torre +@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 +@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 +@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