Imagelibrary/rtems
1
0
Fork 1
mirror of https://gitlab.rtems.org/rtems/rtos/rtems.git synced 2025-12-05 15:15:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Numerous changes based on comments from Stephan Wilms <Stephan.Wilms@CWA.de>

Browse Source 
including a new section in the Getting Started called "Where to
Go From Here", lots of index entries added, and more configuration
table information.
This commit is contained in:
Joel Sherrill
2000-05-04 19:45:17 +00:00
parent 223b64f331
commit adee597960
31 changed files with 508 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
doc/FAQ/debug.t
View File

@@ -10,6 +10,51 @@
The questions in this category are hints that can ease debugging.
@section 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.
@section Malloc
@subsection Is malloc reentrant?

16
doc/TODO
View File

@@ -7,6 +7,10 @@ manuals.
General Issues
==============
Need a Roadmap
Need a description of hello world and writing an application.
More automatic handling of version, date, revision, release, etc.
Eliminate use of gifs.
@@ -18,6 +22,18 @@ Getting Started (C and Ada versions)
====================================
Produce PDF
Classic Users Guide
===================
Add Primitive Data Types Chapter
Add descriptions for confdefs.h macros in configuring a system
chapter.
Add defaults for all confdefs.h values.
Replace example configuration
POSIX User Notes
================

2
doc/networking/testing.t
View File

@@ -61,7 +61,7 @@ is a list of them:
There are commented out calls to @code{printf} in the file
@code{sys/mbuf.h} in the network stack code. Uncommenting
these lines results in output when mbuf's are allocated
and freed. This is very useful for findind memory leaks.
and freed. This is very useful for finding memory leaks.
@item TX and RX queuing

4
doc/posix_users/message.t
View File

@@ -56,7 +56,8 @@ established for the passing of messages. Synchronization is needed when a
task waits for a message to arrive at a queue. Also, a task may poll a
queue for the arrival of a message.
The message queue descriptor mqd_t mq represents the message queue. It is
@findex mqd_t
The message queue descriptor @code{mqd_t} represents the message queue. It is
passed as an argument to all of the message queue functions.
@subsection Building a Message Queue Attribute Set
@@ -64,6 +65,7 @@ passed as an argument to all of the message queue functions.
The mq_attr structure is used to define the characteristics of the message
queue.
@findex mq_attr
@example
@group
typedef struct mq_attr@{

7
doc/posix_users/semaphores.t
View File

@@ -42,11 +42,14 @@ returned to the semaphore. If there is more than one task waiting for a
semaphore, the tasks will be placed in the queue.
@subsection "sem_t" Structure
The "sem_t" structure is used to represent semaphores. It is passed as an
@findex sem_t
The @code{sem_t} structure is used to represent semaphores. It is passed as an
argument to the semaphore directives and is defined as follows:
@example
typedef int sem_t
typedef int sem_t;
@end example
@subsection Building a Semaphore Attribute Set

11
doc/started/Makefile.am
View File

@@ -17,7 +17,7 @@ include $(top_srcdir)/project.am
COMMON_FILES=$(top_srcdir)/common/cpright.texi $(top_builddir)/common/setup.texi
GENERATED_FILES= binaries.texi buildc.texi buildrt.texi gdb.texi intro.texi \
nt.texi require.texi sample.texi
nt.texi require.texi nextstep.texi sample.texi
FILES= tversions.texi
@@ -30,7 +30,7 @@ intro.texi: intro.t tversions.texi
-n "Requirements" $<
require.texi: require.t tversions.texi
$(BMENU) -c -p "EGCS Mailing List" \
$(BMENU) -c -p "GCC Mailing Lists" \
-u "Top" \
-n "Prebuilt Toolset Executables" $<
@@ -56,11 +56,16 @@ sample.texi: sample.t tversions.texi
gdb.texi: gdb.t tversions.texi
$(BMENU) -c -p "Application Executable" \
-u "Top" \
-n "Where To Go From Here" $<
nextstep.texi: nextstep.t tversions.texi
$(BMENU) -c -p "GDB for DINK32" \
-u "Top" \
-n "Using MS-Windows as a Development Host" $<
nt.texi: nt.t tversions.texi
$(BMENU) -c -p "GDB for DINK32" \
$(BMENU) -c -p "Where To Go From Here" \
-u "Top" \
-n "" $<

100
doc/started/buildc.t
View File

@@ -157,10 +157,9 @@ which aid in building the tools and RTEMS. They are:
@end itemize
When the @code{bit} script is executed later in this process,
it will automatically create two other subdirectories:
it will automatically create this subdirectory:
@itemize @bullet
@item src
@item build-$@{CPU@}-tools
@end itemize
@@ -195,7 +194,6 @@ The tree should look something like the following figure:
@value{BINUTILS-UNTAR}/
@value{GCC-UNTAR}/
@value{NEWLIB-UNTAR}/
@value{RTEMS-UNTAR}/
bit
bit_gdb
bit_rtems
@@ -250,12 +248,25 @@ to at least GNU fileutile version 3.16 to resolve this problem.
Each of the tools in the GNU development suite comes with documentation.
It is in the reader's and tool maintainers' interest that one read the
documentation before posting a problem to a mailing list or news group.
Much of that documentation is available on-line. The following is
a list of URLs where can find HTML versions of the manuals.
@table @b
GCC Documentation
http://gcc.gnu.org/onlinedocs
Newlib Documentation
Not currently online at http://sourceware.cygnus.com/newlib
Binutils Documentation
Not currently online at http://sourceware.cygnus.com/binutils
@end table
@c
@c EGCS patches
@c GCC patches
@c
@section Apply RTEMS Patch to EGCS
@section Apply RTEMS Patch to GCC
@ifclear GCC-RTEMSPATCH
No RTEMS specific patches are required for @value{GCC-VERSION} to
@@ -396,7 +407,9 @@ NEWLIB=@value{NEWLIB-UNTAR}
@end example
@item BUILD_DOCS
is set to "yes" if you want to install documentation.
is set to "yes" if you want to install documentation. This requires
that tools supporting documentation production be installed. This
currently is limited to the GNU texinfo package.
For example:
@example
@@ -405,7 +418,10 @@ BUILD_DOCS=yes
@item BUILD_OTHER_LANGUAGES
is set to "yes" if you want to build languages other than C and C++. At
the current time, this enables Fortan and Objective-C.
the current time, the set of alternative languages includes Java, Fortran,
and Objective-C. These alternative languages do not always build cross.
Hence this option defaults to "no".
For example:
@example
@@ -427,9 +443,28 @@ At this time, this feature is not supported by the UNIX ports of RTEMS
and is forced to "no" for those targets. This corresponds to the
@code{configure} option @code{--enable-posix}.
@item ENABLE_RTEMS_ITRON
is set to "yes" if you want to enable the RTEMS ITRON API support.
At this time, this feature is not supported by the UNIX ports of RTEMS
and is forced to "no" for those targets. This corresponds to the
@code{configure} option @code{--enable-itron}.
@item ENABLE_RTEMS_MP
is set to "yes" if you want to enable the RTEMS multiprocessing
support. This feature is not supported by all RTEMS BSPs and
is automatically forced to "no" for those BSPs. This corresponds to the
@code{configure} option @code{--enable-multiprocessing}.
@item ENABLE_RTEMS_CXX
is set to "yes" if you want to build the RTEMS C++ support including
the C++ Wrapper for the Classic API. This corresponds to the
@code{configure} option @code{--enable-cxx}.
@item ENABLE_RTEMS_TESTS
is set to "yes" if you want to build the RTEMS Test Suite. If this
is set to "no", then only the Sample Tests will be built.
is set to "no", then only the Sample Tests will be built. Setting
this option to "yes" significantly increases the amount of disk
space required to build RTEMS.
This corresponds to the @code{configure} option @code{--enable-tests}.
@item ENABLE_RTEMS_TCPIP
@@ -438,10 +473,36 @@ particular BSP does not support TCP/IP, then this feature is automatically
disabled. This corresponds to the @code{configure} option
@code{--enable-tcpip}.
@item ENABLE_RTEMS_CXX
is set to "yes" if you want to build the RTEMS C++ support including
the C++ Wrapper for the Classic API. This corresponds to the
@code{configure} option @code{--enable-cxx}.
@item ENABLE_RTEMS_NONDEBUG
is set to "yes" if you want to build RTEMS in a fully optimized
state. This corresponds to executing @code{make} after configuring
the source tree.
@item ENABLE_RTEMS_DEBUG
is set to "yes" if you want to build RTEMS in a debug version.
When built for debug, RTEMS will include run-time code to
perform consistency checks such as heap consistency checks.
Although the precise compilation arguments are BSP dependent,
the debug version of RTEMS is usually built at a lower optimization
level. This is usually done to reduce inlining which can make
tracing code execution difficult. This corresponds to executing
@code{make VARIANT=debug} after configuring
the source tree.
@item INSTALL_RTEMS
is set to "yes" if you want to install RTEMS after building it.
This corresponds to executing @code{make install} after configuring
and building the source tree.
@item ENABLE_RTEMS_MAINTAINER_MODE
is set to "yes" if you want to enabled maintainer mode functionality
in the RTEMS Makefile. This is disabled by default and it is not
expected that most users will want to enable this. When this option
is enabled, the build process may attempt to regenerate files that
require tools not required when this option is disabled.
This corresponds to the @code{configure} option
@code{--enable-maintainer-mode}.
@end table
@section Running the bit Script
@@ -470,12 +531,21 @@ Where <target configuration> is one of the following:
@item sparc
@end itemize
The build process can take a while to complete. Many users find it
handy to run the build process in the background, capture the output
in a file, and monitor the output. This can be done as follows:
@example
./bit_ada <target configuration> >bit.log 2>&1 &
tail -f bit.log
@end example
If no errors are encountered, the @code{bit} script will conclude by
printing messages similar to the following:
@example
The src and build-i386-tools subdirectory may now be removed.
The build-i386-tools subdirectory may now be removed.
Started: Fri Apr 10 10:14:07 CDT 1998
Finished: Fri Apr 10 12:01:33 CDT 1998
@@ -523,6 +593,10 @@ in your PATH. As a general rule, including "." in your PATH
is a security risk and should be avoided. Remove "." from
your PATH.
NOTE: In some environments, it may be difficult remove "."
completely from your PATH. In this case, make sure that "."
is after the system directories containing "as" and "ld".
@subsection Error Messages Indicating Configuration Problems
If you see error messages like the following,

6
doc/started/buildrt.t
View File

@@ -102,6 +102,8 @@ tools/@value{RTEMS-UNTAR}/README.configure
in the RTEMS source tree. If the BSP parameter is not specified,
then all supported BSPs for the selected CPU family will be built.
@b{NOTE:} The POSIX API must be enabled to use GNAT/RTEMS.
@subsection Using the RTEMS configure Script Directly
Make a build directory under tools and build the RTEMS product in this
@@ -112,6 +114,10 @@ comes with the RTEMS distribution. In the installation described in the
section "Unpack the RTEMS source", these configuration options can be found
in the file tools/@value{RTEMS-UNTAR}/README.configure.
The GNAT/RTEMS run-time implementation is based on the POSIX API. Thus
the RTEMS configuration for a GNAT/RTEMS environment MUST include the
@code{--enable-posix} flag.
The following shows the command sequence required to configure,
compile, and install RTEMS with the POSIX API, FreeBSD TCP/IP,
and C++ support disabled. RTEMS will be built to target

14
doc/started/intro.t
View File

@@ -149,15 +149,11 @@ The crossgcc FAQ as well as a number of patches and utiliities
of interest to cross development system users are available
at ftp://ftp.cygnus.com/pub/embedded/crossgcc.
@subsection EGCS Mailing List
@subsection GCC Mailing Lists
egcs@@cygnus.com
See http://gcc.gnu.org for details.
This mailing list is dedicated to the EGCS Project which was
formed to speed the development and integration of the various
GNU languages. The RTEMS and Linux communities were among those
initially targetted by the EGCS Project as being important
for its success. Numerous RTEMS users have made contributions
to this project. Subscribe by sending a message with
the one line "subscribe" to egcs-request@@cygnus.com.
The GCC Project maintains multiple mailing lists. They
are described at the above web site along with subscription
information.

10
doc/started/nt.t
View File

@@ -267,16 +267,16 @@ the Cygwin32 environment with the new path.
@end enumerate
@c
@c EGCS
@c GCC
@c
@section Installing EGCS AND NEWLIB
@section Installing GCC AND NEWLIB
@enumerate
@item Unarchive and patch @value{EGCS-TAR} and @value{NEWLIB-TAR}
@item Unarchive and patch @value{GCC-TAR} and @value{NEWLIB-TAR}
following the instructions in @ref{Unarchiving the Tools}.
Apply the appropriate RTEMS specific patches as detailed in
@ref{Apply RTEMS Patch to EGCS} and @ref{Apply RTEMS Patch to newlib}.
@ref{Apply RTEMS Patch to GCC} and @ref{Apply RTEMS Patch to newlib}.
@b{NOTE}: See @ref{Bug in Patch Utility}.
@@ -291,7 +291,7 @@ or Objective-C as Cygwin32 cross-compilers):
@b{NOTE}: See @ref{Bug in Patch Utility}.
@item Link the following directories from Newlib to the main EGCS directory,
@item Link the following directories from Newlib to the main GCC directory,
/source/@value{GCC-UNTAR}/ :
@itemize @bullet

34
doc/started/require.t
View File

@@ -16,18 +16,38 @@ assessing the amount of disk space required for your installation:
+------------------------------------+--------------------------+
| Component | Disk Space Required |
+------------------------------------+--------------------------+
| archive directory | 30 Mbytes |
| tools src unzipped | 100 Mbytes |
| each individual build directory | 300 Mbytes worst case |
| each installation directory | 20-400 Mbytes |
| archive directory | 35 Mbytes |
| tools src unarchived | 150 Mbytes |
| each individual build directory | 300 Mbytes |
| each installation directory | 20-200 Mbytes |
+------------------------------------+--------------------------+
@end example
The disk space required for each installation directory depends
primarily on the number of RTEMS BSPs which are to be installed.
If a single BSP is installed, then the size of each install directory
It is important to understand that the above requirements only address
the GNU C/C++ Cross Compiler Tools themselves. Adding additional
languages such as Fortran or Objective-C can increase the size
of the build and installation directories. Also, the unarchived
source and build directories can be removed after the tools are
installed.
After the tools themselves are installed, RTEMS must be built
and installed for each Board Support Package that you wish
to use. Thus the precise amount of disk space required
for each installation directory depends highly on the number
of RTEMS BSPs which are to be installed. If a single BSP is
installed, then the additional size of each install directory
will tend to be in the 40-60 Mbyte range.
There are a number of factors which must be taken into
account in oreder to estimate the amount of disk space required
to build RTEMS itself. Attempting to build multiple BSPs in
a single step increases the disk space requirements. Similarly
enabling optional features increases the build and install
space requirements. In particular, enabling and building
the RTEMS tests results in a significant increase in build
space requirements but since the test are not installed has
no impact on installation requirements.
The instructions in this manual should work on any computer running
a UNIX variant. Some native GNU tools are used by this procedure
including:

2
doc/started/started.texi
View File

@@ -74,6 +74,7 @@ END-INFO-DIR-ENTRY
@include buildrt.texi
@include sample.texi
@include gdb.texi
@include nextstep.texi
@include nt.texi
@ifinfo
@@ -90,6 +91,7 @@ This is the online version of the Getting Started with RTEMS for C/C++ Users.
* Building RTEMS::
* Building the Sample Application::
* Building the GNU Debugger::
* Where To Go From Here::
* Using MS-Windows as a Development Host::
@end menu

26
doc/started/tversions.texi
View File

@@ -27,7 +27,7 @@
@set GCC-FTPSITE gcc.gnu.org
@set GCC-FTPDIR /pub/gcc/gcc-2.95.2
@set GCC-HTTPDIR /pub/gcc/releases/index.html
@set GCC-RTEMSPATCH gcc-2.95.2-rtems-20000106.diff
@set GCC-RTEMSPATCH gcc-2.95.2-rtems-20000427.diff.gz
@c
@c BINUTILS Version
@@ -42,12 +42,12 @@
@c @set BINUTILS-RTEMSPATCH binutils-2.9.1-rtems-diff-19981012.gz
@c The "official" Linux binutils
@set BINUTILS-VERSION binutils 2.9.5.0.22
@set BINUTILS-TAR binutils-2.9.5.0.22.tar.gz
@set BINUTILS-UNTAR binutils-2.9.5.0.22
@set BINUTILS-VERSION binutils 2.9.5.0.24
@set BINUTILS-TAR binutils-2.9.5.0.24.tar.gz
@set BINUTILS-UNTAR binutils-2.9.5.0.24
@set BINUTILS-FTPSITE ftp.varesearch.com
@set BINUTILS-FTPDIR /pub/support/hjl/binutils
@set BINUTILS-RTEMSPATCH binutils-2.9.5.0.22-rtems-20000114.diff
@set BINUTILS-RTEMSPATCH binutils-2.9.5.0.24-rtems-20000207.diff.gz
@c When forced to use a snapshot
@c @set BINUTILS-VERSION gas 980314
@@ -61,12 +61,13 @@
@c NEWLIB Version
@c
@set NEWLIB-VERSION newlib 1.8.2
@set NEWLIB-TAR newlib-1.8.2.tar.gz
@set NEWLIB-UNTAR newlib-1.8.2
@set NEWLIB-FTPSITE sourceware.cygnus.com
@set NEWLIB-FTPDIR /pub/newlib
@set NEWLIB-RTEMSPATCH newlib-1.8.2-rtems-20000104.diff
@set NEWLIB-RTEMSPATCH newlib-1.8.2-rtems-20000501.diff.gz
@c
@c GDB Version
@@ -77,16 +78,17 @@
@set GDB-UNTAR gdb-4.18
@set GDB-FTPSITE ftp.gnu.org
@set GDB-FTPDIR /pub/gnu/gdb
@set GDB-RTEMSPATCH gdb-4.18-rtems-20000107.diff
@set GDB-RTEMSPATCH gdb-4.18-rtems-20000502.diff.gz
@c
@c RTEMS Version
@c
@set RTEMS-VERSION RTEMS 4.5.0-beta
@set RTEMS-TAR rtems-4.5.0-beta.tgz
@set RTEMS-UNTAR rtems-4.5.0-beta
@set RTEMS-VERSION RTEMS 4.5.0-beta2
@set RTEMS-TAR rtems-4.5.0-beta2.tgz
@set RTEMS-UNTAR rtems-4.5.0-beta2
@set RTEMS-FTPSITE ftp.OARcorp.com
@set RTEMS-FTPDIR /pub/rtems/releases/4.5.0-beta
@set BUILDTOOLS-TAR c_build_scripts-20000104.tgz
@set RTEMS-FTPDIR /pub/rtems/betas/4.5.0-beta
@set BUILDTOOLS-TAR c_build_scripts-4.5.0-beta2.tgz

89
doc/started_ada/buildada.t
View File

@@ -211,7 +211,6 @@ The directory tree should look something like the following figure:
@value{GCC-UNTAR}/
@value{GNAT-UNTAR}/
@value{NEWLIB-UNTAR}/
@value{RTEMS-UNTAR}/
bit_ada
bit_gdb
bit_rtems
@@ -398,13 +397,16 @@ cd tools/@value{GNAT-UNTAR}/src
cp -r ada ../../@value{GCC-UNTAR}
@end example
===================================================================
@c
@c Localizing the Configuration
@c
@section Localizing the Configuration
Edit the @code{user.cfg} file to alter the settings of various
Edit the @code{user.cfg} file to alter the settings of various
variables which are used to tailor the build process.
Each of the variables set in @code{user.cfg} may be modified
as described below:
@@ -416,12 +418,12 @@ RTEMS to be built. It is recommended that the directory chosen to receive
these tools be named so that it is clear from which egcs distribution it
was generated and for which target system the tools are to produce code for.
@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory
@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory
under the build directory. The build directory will be removed
automatically upon successful completion of the build procedure.
@item BINUTILS
is the directory under tools that contains @value{BINUTILS-UNTAR}.
is the directory under tools that contains @value{BINUTILS-UNTAR}.
For example:
@example
@@ -448,7 +450,9 @@ NEWLIB=@value{NEWLIB-UNTAR}
@end example
@item BUILD_DOCS
is set to "yes" if you want to install documentation.
is set to "yes" if you want to install documentation. This requires
that tools supporting documentation production be installed. This
currently is limited to the GNU texinfo package.
For example:
@example
@@ -457,13 +461,22 @@ BUILD_DOCS=yes
@item BUILD_OTHER_LANGUAGES
is set to "yes" if you want to build languages other than C and C++. At
the current time, this enables Fortan and Objective-C.
the current time, the set of alternative languages includes Java, Fortran,
and Objective-C. These alternative languages do not always build cross.
Hence this option defaults to "no".
For example:
@example
BUILD_OTHER_LANGUAGES=yes
@end example
@b{NOTE:} Based upon the version of the compiler being used, it may not
be possible to build languages other than C and C++ cross. In many cases,
the language run-time support libraries are not "multilib'ed". Thus the
executable code in these libraries will be for the default compiler settings
and not necessarily be correct for your CPU model.
@item RTEMS
is the directory under tools that contails @value{RTEMS-UNTAR}.
@@ -475,9 +488,28 @@ and is forced to "no" for those targets. This corresponds to the
This must be enabled to support the GNAT/RTEMS run-time.
@item ENABLE_RTEMS_ITRON
is set to "yes" if you want to enable the RTEMS ITRON API support.
At this time, this feature is not supported by the UNIX ports of RTEMS
and is forced to "no" for those targets. This corresponds to the
@code{configure} option @code{--enable-itron}.
@item ENABLE_RTEMS_MP
is set to "yes" if you want to enable the RTEMS multiprocessing
support. This feature is not supported by all RTEMS BSPs and
is automatically forced to "no" for those BSPs. This corresponds to the
@code{configure} option @code{--enable-multiprocessing}.
@item ENABLE_RTEMS_CXX
is set to "yes" if you want to build the RTEMS C++ support including
the C++ Wrapper for the Classic API. This corresponds to the
@code{configure} option @code{--enable-cxx}.
@item ENABLE_RTEMS_TESTS
is set to "yes" if you want to build the RTEMS Test Suite. If this
is set to "no", then only the Sample Tests will be built.
is set to "no", then only the Sample Tests will be built. Setting
this option to "yes" significantly increases the amount of disk
space required to build RTEMS.
This corresponds to the @code{configure} option @code{--enable-tests}.
@item ENABLE_RTEMS_TCPIP
@@ -486,10 +518,36 @@ particular BSP does not support TCP/IP, then this feature is automatically
disabled. This corresponds to the @code{configure} option
@code{--enable-tcpip}.
@item ENABLE_RTEMS_CXX
is set to "yes" if you want to build the RTEMS C++ support including
the C++ Wrapper for the Classic API. This corresponds to the
@code{configure} option @code{--enable-cxx}.
@item ENABLE_RTEMS_NONDEBUG
is set to "yes" if you want to build RTEMS in a fully optimized
state. This corresponds to executing @code{make} after configuring
the source tree.
@item ENABLE_RTEMS_DEBUG
is set to "yes" if you want to build RTEMS in a debug version.
When built for debug, RTEMS will include run-time code to
perform consistency checks such as heap consistency checks.
Although the precise compilation arguments are BSP dependent,
the debug version of RTEMS is usually built at a lower optimization
level. This is usually done to reduce inlining which can make
tracing code execution difficult. This corresponds to executing
@code{make VARIANT=debug} after configuring
the source tree.
@item INSTALL_RTEMS
is set to "yes" if you want to install RTEMS after building it.
This corresponds to executing @code{make install} after configuring
and building the source tree.
@item ENABLE_RTEMS_MAINTAINER_MODE
is set to "yes" if you want to enabled maintainer mode functionality
in the RTEMS Makefile. This is disabled by default and it is not
expected that most users will want to enable this. When this option
is enabled, the build process may attempt to regenerate files that
require tools not required when this option is disabled.
This corresponds to the @code{configure} option
@code{--enable-maintainer-mode}.
@end table
@section Running the bit_ada Script
@@ -522,6 +580,15 @@ NOTE: The above list of target configurations is the list of RTEMS supported
targets. Only a subset of these have been tested with GNAT/RTEMS. For more
information, contact your GNAT/RTEMS representative.
The build process can take a while to complete. Many users find it
handy to run the build process in the background, capture the output
in a file, and monitor the output. This can be done as follows:
@example
./bit_ada <target configuration> >bit.log 2>&1 &
tail -f bit.log
@end example
If no errors are encountered, the @code{bit_ada} script will conclude by
printing messages similar to the following:

32
doc/started_ada/require.t
View File

@@ -16,18 +16,38 @@ assessing the amount of disk space required for your installation:
+------------------------------------+--------------------------+
| Component | Disk Space Required |
+------------------------------------+--------------------------+
| archive directory | 30 Mbytes |
| tools src unzipped | 100 Mbytes |
| archive directory | 40 Mbytes |
| tools src unarchived | 200 Mbytes |
| each individual build directory | 300 Mbytes worst case |
| each installation directory | 20-130 Mbytes |
| each installation directory | 20-200 Mbytes |
+------------------------------------+--------------------------+
@end example
The disk space required for each installation directory depends
primarily on the number of RTEMS BSPs which are to be installed.
If a single BSP is installed, then the size of each install directory
It is important to understand that the above requirements only address
the GNU C/C++ Cross Compiler Tools themselves. Adding additional
languages such as Fortran or Objective-C can increase the size
of the build and installation directories. Also, the unarchived
source and build directories can be removed after the tools are
installed.
After the tools themselves are installed, RTEMS must be built
and installed for each Board Support Package that you wish
to use. Thus the precise amount of disk space required
for each installation directory depends highly on the number
of RTEMS BSPs which are to be installed. If a single BSP is
installed, then the additional size of each install directory
will tend to be in the 40-60 Mbyte range.
There are a number of factors which must be taken into
account in oreder to estimate the amount of disk space required
to build RTEMS itself. Attempting to build multiple BSPs in
a single step increases the disk space requirements. Similarly
enabling optional features increases the build and install
space requirements. In particular, enabling and building
the RTEMS tests results in a significant increase in build
space requirements but since the test are not installed has
no impact on installation requirements.
The instructions in this manual should work on any computer running
a UNIX variant. Some native GNU tools are used by this procedure
including:

34
doc/started_ada/tversions.texi
View File

@@ -26,18 +26,18 @@
@set GCC-UNTAR gcc-2.8.1
@set GCC-FTPSITE ftp.gnu.org
@set GCC-FTPDIR /pub/gnu
@set GCC-RTEMSPATCH gcc-2.8.1-rtems-diff-19980527.gz
@set GCC-RTEMSPATCH gcc-2.8.1-rtems-gnat-3.12p-20000429.diff.gz
@c
@c GNAT Version
@c
@set GNAT-VERSION gnat 3.11b
@set GNAT-TAR gnat-3.11b-src.tar.gz
@set GNAT-UNTAR gnat-3.11b-src
@set GNAT-VERSION gnat 3.12p
@set GNAT-TAR gnat-3.12p-src.tar.gz
@set GNAT-UNTAR gnat-3.12p-src
@set GNAT-FTPSITE NONE
@set GNAT-FTPDIR NO_DIRECTORY
@set GNAT-RTEMSPATCH gnat-3.11b-rtems-diff-19981105.gz
@set GNAT-RTEMSPATCH gnat-3.12p-rtems-20000429.diff.gz
@c
@c BINUTILS Version
@@ -49,7 +49,7 @@
@set BINUTILS-UNTAR binutils-2.9.1
@set BINUTILS-FTPSITE ftp.gnu.org
@set BINUTILS-FTPDIR /pub/gnu
@set BINUTILS-RTEMSPATCH binutils-2.9.1-rtems-diff-19981027.gz
@set BINUTILS-RTEMSPATCH binutils-2.9.1-rtems-gnat-3.12p-20000429.diff.gz
@c When forced to use a snapshot
@c @set BINUTILS-VERSION gas 980314
@@ -63,12 +63,12 @@
@c NEWLIB Version
@c
@set NEWLIB-VERSION newlib 1.8.1
@set NEWLIB-TAR newlib-1.8.1.tar.gz
@set NEWLIB-UNTAR newlib-1.8.1
@set NEWLIB-VERSION newlib 1.8.2
@set NEWLIB-TAR newlib-1.8.2.tar.gz
@set NEWLIB-UNTAR newlib-1.8.2
@set NEWLIB-FTPSITE ftp.cygnus.com
@set NEWLIB-FTPDIR /pub/newlib
@set NEWLIB-RTEMSPATCH newlib-1.8.1-rtems-diff-19980121.gz
@set NEWLIB-RTEMSPATCH newlib-1.8.2-rtems-20000501.diff.gz
@c
@c GDB Version
@@ -79,18 +79,18 @@
@set GDB-UNTAR gdb-4.17
@set GDB-FTPSITE ftp.gnu.org
@set GDB-FTPDIR /pub/gnu
@set GDB-RTEMSPATCH gdb-4.17-rtems-diff-19981027.gz
@set GDB-RTEMSPATCH gdb-4.17-rtems-gnat-3.12p-20000429.diff
@c @set GDB-GNATPATCH gdb-ada-patch-1.17.8.gz
@c
@c RTEMS Version
@c
@set RTEMS-VERSION RTEMS 4.0.0
@set RTEMS-TAR rtems-4.0.0.tgz
@set RTEMS-UNTAR rtems-4.0.0
@set RTEMS-FTPSITE ftp.OARcorp.com
@set RTEMS-FTPDIR /pub/rtems/4.0.0
@set BUILDTOOLS-TAR ada_build_scripts-4.0.0.tgz
@set RTEMS-VERSION RTEMS 4.5.0-beta2
@set RTEMS-TAR rtems-4.5.0-beta2.tgz
@set RTEMS-UNTAR rtems-4.5.0-beta2
@set RTEMS-FTPSITE ftp.OARcorp.com
@set RTEMS-FTPDIR /pub/rtems/betas/4.5.0-beta
@set BUILDTOOLS-TAR c_build_scripts-4.5.0-beta2.tgz

22
doc/user/clock.t
View File

@@ -42,7 +42,9 @@ The clock facilities of the clock manager operate
upon calendar time. These directives utilize the following date
and time @value{STRUCTURE} for the native time and date format:
@ifset is-C
@findex rtems_time_of_day
@example
struct rtems_tod_control @{
rtems_unsigned32 year; /* greater than 1987 */
@@ -108,6 +110,8 @@ seconds since the RTEMS epoch of January 1, 1988.
@subsection Clock Tick and Timeslicing
@cindex timeslicing
Timeslicing is a task scheduling discipline in which
tasks of equal priority are executed for a specific period of
time before control of the CPU is passed to another task. It is
@@ -129,6 +133,8 @@ ready task of equal priority.
@subsection Delays
@cindex delays
A sleep timer allows a task to delay for a given
interval or up until a given time, and then wake and continue
execution. This type of timer is created automatically by the
@@ -140,6 +146,8 @@ sleep timer at a time.
@subsection Timeouts
@cindex timeouts
Timeouts are a special type of timer automatically
created when the timeout option is used on the
@code{@value{DIRPREFIX}message_queue_receive},
@@ -190,8 +198,12 @@ the number of seconds since the RTEMS epoch, the number of ticks
since the executive was initialized, and the number of ticks per
second. The information returned by the
@code{@value{DIRPREFIX}clock_get} directive is
dependent on the option selected by the caller. The following
options are available:
dependent on the option selected by the caller. This
is specified using one of the following constants
associated with the enumerated type
@code{@value{DIRPREFIX}clock_get_options}:
@findex rtems_clock_get_options
@itemize @bullet
@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
@@ -325,8 +337,12 @@ The caller can always obtain the number of ticks per second (option is
ticks since the executive was initialized option is
@code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
The data type expected for time_buffer is indicated below:
The @code{option} argument may taken on any value of the enumerated
type @code{rtems_clock_get_options}. The data type expected for
@code{time_buffer} is based on the value of @code{option} as
indicated below:
@findex rtems_clock_get_options
@ifset is-C
@itemize @bullet
@item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *)

42
doc/user/concepts.t
View File

@@ -43,15 +43,32 @@ reflect the object's use in the application. Conversely, object
IDs are designed to facilitate efficient object manipulation by
the executive.
@subsection Object Names
@cindex object name
@findex rtems_object_name
An object name is an unsigned thirty-two bit entity
associated with the object by the user. Although not required
by RTEMS, object names are typically composed of four ASCII
characters which help identify that object. For example, a task
which causes a light to blink might be called "LITE". Utilities
are provided to build an object name from four ASCII characters
and to decompose an object name into four ASCII characters.
associated with the object by the user. The data type
@code{@value{DIRPREFIX}name} is used to store object names.
@findex rtems_build_name
Although not required by RTEMS, object names are often
composed of four ASCII characters which help identify that object.
For example, a task which causes a light to blink might be
called "LITE". The @code{@value{DIRPREFIX}build_name} routine
is provided to build an object name from four ASCII characters.
@ifset is-C
The following example illustrates this:
@example
rtems_object_name my_name;
my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
@end example
@end ifset
However, it is not required that the application use ASCII
characters to build object names. For example, if an
application requires one-hundred tasks, it would be difficult to
@@ -59,13 +76,18 @@ assign meaningful ASCII names to each task. A more convenient
approach would be to name them the binary values one through
one-hundred, respectively.
@subsection Object IDs
@cindex object ID
@cindex object ID composition
@findex rtems_id
@need 3000
An object ID is a unique unsigned thirty-two bit
entity composed of three parts: object class, node, and index.
The data type @code{@value{DIRPREFIX}id} is used to store object IDs.
@ifset use-ascii
@example
@@ -259,6 +281,8 @@ known as a tick. The frequency of clock ticks is completely
application dependent and determines the granularity and
accuracy of all interval and calendar time operations.
@findex rtems_interval
By tracking time in units of ticks, RTEMS is capable
of supporting interval timing functions such as task delays,
timeouts, timeslicing, the delayed execution of timer service
@@ -267,6 +291,8 @@ interval is defined as a number of ticks relative to the current
time. For example, when a task delays for an interval of ten
ticks, it is implied that the task will not execute until ten
clock ticks have occurred.
All intervals are specified using data type
@code{@value{DIRPREFIX}interval}.
A characteristic of interval timing is that the
actual interval period may be a fraction of a tick less than the
@@ -291,6 +317,10 @@ date and time. This allows selected time operations to be
scheduled at an actual calendar date and time. For example, a
task could request to delay until midnight on New Year's Eve
before lowering the ball at Times Square.
The data type @code{@value{DIRPREFIX}time_of_day} is used to specify
calendar time in RTEMS services.
@xref{Clock Manager Time and Date Data Structures, , Time and Date Data Structures}.
@findex rtems_time_of_day
Obviously, the directives which use intervals or wall
time cannot operate without some external mechanism which

25
doc/user/conf.t
View File

@@ -204,6 +204,7 @@ The RTEMS Configuration Table
is defined in the following @value{LANGUAGE} @value{STRUCTURE}:
@ifset is-C
@findex rtems_configuration_table
@example
@group
typedef struct @{
@@ -262,7 +263,10 @@ RTEMS will invoke the fatal error handler during
@code{@value{DIRPREFIX}initialize_executive}.
When using the @code{confdefs.h} mechanism for configuring
an RTEMS application, the value for this field corresponds
to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}
which defaults to @code{NULL}. Normally, this field should be
configured as @code{NULL} as BSPs will assign memory for the
RTEMS RAM Workspace as part of system initialization.
@item work_space_size
is the calculated size of the
@@ -278,9 +282,9 @@ is number of microseconds per clock tick.
When using the @code{confdefs.h} mechanism for configuring
an RTEMS application, the value for this field corresponds
to the setting of the macro @code{CONFIGURE_MICROSECONDS_PER_TICK}.
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TASKS}
macro defaults to 10.
XXX
If not defined by the application, then the
@code{CONFIGURE_MICROSECONDS_PER_TICK} macro defaults to 10000
(10 milliseconds).
@item ticks_per_timeslice
is the number of clock ticks for a timeslice.
@@ -374,8 +378,8 @@ configuration. This field must be NULL when RTEMS is used in a
single processor configuration.
When using the @code{confdefs.h} mechanism for configuring
an RTEMS application, the Multiprocessor Configuration Table
is automatically generated when the @code{CONFIGURE_MPTEST}
is defined. If @code{CONFIGURE_MPTEST} is not defined, the this
is automatically generated when the @code{CONFIGURE_MP_APPLICATION}
is defined. If @code{CONFIGURE_MP_APPLICATION} is not defined, the this
entry is set to NULL. The generated table has the name
@code{Multiprocessing_configuration}.
@@ -412,6 +416,7 @@ this application. The RTEMS API Configuration Table is defined in
the following @value{LANGUAGE} @value{STRUCTURE}:
@ifset is-C
@findex rtems_api_configuration_table
@example
@group
typedef struct @{
@@ -590,6 +595,8 @@ this application. The POSIX API Configuration Table is defined in
the following @value{LANGUAGE} @value{STRUCTURE}:
@ifset is-C
@findex posix_initialization_threads_table
@findex posix_api_configuration_table
@example
@group
typedef struct @{
@@ -774,6 +781,7 @@ Initialization Task Table is defined in the following @value{LANGUAGE}
@value{STRUCTURE}:
@ifset is-C
@findex rtems_initialization_tasks_table
@example
typedef struct @{
rtems_name name;
@@ -897,6 +905,7 @@ Driver Table is defined in
the following @value{LANGUAGE} @value{STRUCTURE}:
@ifset is-C
@findex rtems_driver_address_table
@example
typedef struct @{
rtems_device_driver_entry initialization;
@@ -1164,9 +1173,9 @@ Multiprocessing chapter.
When using the @code{confdefs.h} mechanism for configuring
an RTEMS application, the macro @code{CONFIGURE_MPTEST} must
an RTEMS application, the macro @code{CONFIGURE_MP_APPLICATION} must
be defined to automatically generate the Multiprocessor Configuration Table.
If @code{CONFIGURE_MPTEST}, is not defined, then a NULL pointer
If @code{CONFIGURE_MP_APPLICATION}, is not defined, then a NULL pointer
is configured as the address of this table.
The format of the Multiprocessor Configuration Table is defined in

9
doc/user/event.t
View File

@@ -25,13 +25,18 @@ provided by the event manager are:
@subsection Event Sets
@cindex event flag, definition
@cindex event set, definition
@findex rtems_event_set
An event flag is used by a task (or ISR) to inform
another task of the occurrence of a significant situation.
Thirty-two event flags are associated with each task. A
collection of one or more event flags is referred to as an event
set. The application developer should remember the following
set. The data type @code{@value{DIRPREFIX}event_set} is used to manage
event sets.
The application developer should remember the following
key characteristics of event operations when utilizing the event
manager:
@@ -53,7 +58,7 @@ subsequent send operations to that same task have no effect.
An event set is posted when it is directed (or sent) to a task. A
pending event is an event that has been posted but not received. An event
condition is used to specify the events which the task desires to receive
condition is used to specify the event set which the task desires to receive
and the algorithm which will be used to determine when the request is
satisfied. An event condition is satisfied based upon one of two
algorithms which are selected by the user. The

9
doc/user/example.texi
View File

@@ -18,8 +18,11 @@
* application. It contains a Configuration Table, a
* user initialization task, and a simple task.
*
* This example assumes that a board support package exists
* and invokes the initialize_executive() directive.
* This example assumes that a board support package exists.
*
* Most applications will actually use the confdefs.h method
* to generate their configuration. This is provided primarily
* for reference.
*/
#include "rtems.h"
@@ -40,7 +43,7 @@ rtems_initialization_tasks_table init_task = @{
@};
rtems_configuration_table User_Configuration_Table = @{
NULL, /* filled in by the BSP */
NULL, /* dynamically assigned by the BSP */
65536, /* executive RAM size */
2, /* maximum tasks */
0, /* maximum timers */

2
doc/user/fatal.t
View File

@@ -66,6 +66,8 @@ a specific target processor.
@subsection Announcing a Fatal Error
@findex _Internal_errors_What_happened
The @code{@value{DIRPREFIX}fatal_error_occurred} directive is invoked when a
fatal error is detected. Before invoking any user-supplied
fatal error handlers or the RTEMS fatal error handler, the

6
doc/user/init.t
View File

@@ -87,7 +87,7 @@ other task is made ready to execute.
@subsection Initialization Manager Failure
The fatal_error_occurred directive will be called
The @code{@value{DIRPREFIX}ifatal_error_occurred} directive will be called
from @code{@value{DIRPREFIX}initialize_executive}
for any of the following reasons:
@@ -307,8 +307,8 @@ be the same one passed to
The application must use only one of the two
initialization sequences:
@code{@value{DIRPREFIX}initialize_executive} or
@code{@value{DIRPREFIX}nitialize_executive_early} and
@code{@value{DIRPREFIX}nitialize_executive_late}.
@code{@value{DIRPREFIX}initialize_executive_early} and
@code{@value{DIRPREFIX}initialize_executive_late}.
@page
@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking

9
doc/user/intr.t
View File

@@ -43,13 +43,20 @@ processor and invokes the user's ISR. The user's ISR is
responsible for processing the interrupt, clearing the interrupt
if necessary, and device specific manipulation.
@findex rtems_vector_number
The @code{@value{DIRPREFIX}interrupt_catch}
directive connects a procedure to
an interrupt vector. The interrupt service routine is assumed
an interrupt vector. The vector number is managed using
the @code{@value{DIRPREFIX}vector_number} data type.
The interrupt service routine is assumed
to abide by these conventions and have a prototype similar to
the following:
@ifset is-C
@findex rtems_isr
@example
rtems_isr user_isr(
rtems_vector_number vector

7
doc/user/io.t
View File

@@ -70,6 +70,13 @@ The exact usage of the minor number is driver specific, but is
commonly used to distinguish between a number of devices
controlled by the same driver.
@findex rtems_device_major_number
@findex rtems_device_minor_number
The data types @code{@value{DIRPREFIX}device_major_number} and
@code{@value{DIRPREFIX}device_minor_number} are used to
manipulate device major and minor numbers, respectively.
@subsection Device Names
@cindex device names

9
doc/user/mp.t
View File

@@ -301,6 +301,7 @@ been initialized. This component should be adhere to the
following prototype:
@ifset is-C
@findex rtems_mpci_entry
@example
@group
rtems_mpci_entry user_mpci_initialization(
@@ -465,13 +466,15 @@ MPCI layers will be built upon hardware which support a
broadcast mechanism, others may be required to generate a copy
of the packet for each node in the system.
Many MPCI layers use the packet_length field of the MP_packet_prefix
@c XXX packet_prefix structure needs to be defined in this document
Many MPCI layers use the @code{packet_length} field of the
@code{@value{DIRPREFIX}packet_prefix} portion
of the packet to avoid sending unnecessary data. This is especially
useful if the media connecting the nodes is relatively slow.
The to_convert field of the MP_packet_prefix portion of the packet indicates
how much of the packet (in unsigned32's) may require conversion in a
heterogeneous system.
how much of the packet (in @code{@value{DIRPREFIX}unsigned32}'s) may require
conversion in a heterogeneous system.
@subsection Supporting Heterogeneous Environments

5
doc/user/rtmon.t
View File

@@ -1137,11 +1137,12 @@ This directive returns status information associated with
the rate monotonic period id in the following data @value{STRUCTURE}:
@ifset is-C
@findex rtems_rate_monotonic_period_status
@example
typedef struct @{
rtems_rate_monotonic_period_states state;
unsigned32 ticks_since_last_period;
unsigned32 ticks_executed_since_last_period;
rtems_unsigned32 ticks_since_last_period;
rtems_unsigned32 ticks_executed_since_last_period;
@} rtems_rate_monotonic_period_status;
@end example
@end ifset

8
doc/user/signal.t
View File

@@ -37,11 +37,16 @@ signal is sent to a task, that task's execution path will be
"interrupted" by the ASR. Sending a signal to a task has no
effect on the receiving task's current execution state.
@findex rtems_signal_set
A signal flag is used by a task (or ISR) to inform
another task of the occurrence of a significant situation.
Thirty-two signal flags are associated with each task. A
collection of one or more signals is referred to as a signal
set. A signal set is posted when it is directed (or sent) to a
set. The data type @code{@value{DIRPREFIX}signal_set}
is used to manipulate signal sets.
A signal set is posted when it is directed (or sent) to a
task. A pending signal is a signal that has been sent to a task
with a valid ASR, but has not been processed by that task's ASR.
@@ -216,6 +221,7 @@ The ASR should have the following calling sequence and adhere to
@value{LANGUAGE} calling conventions:
@ifset is-C
@findex rtems_asr
@example
rtems_asr user_routine(
rtems_signal_set signals

30
doc/user/task.t
View File

@@ -120,10 +120,15 @@ current state and priority.
@cindex task priority
@cindex priority, task
@findex rtems_task_priority
A task's priority determines its importance in relation to the
other tasks executing on the same processor. RTEMS supports 255
levels of priority ranging from 1 to 255. Tasks of numerically
levels of priority ranging from 1 to 255. The data type
@code{@value{DIRPREFIX}task_priority} is used to store task
priorities.
Tasks of numerically
smaller priority values are more important tasks than tasks of
numerically larger priority values. For example, a task at
priority level 5 is of higher privilege than a task at priority
@@ -143,8 +148,10 @@ processor execution time.
@subsection Task Mode
@cindex task mode
@findex rtems_task_mode
A task's mode is a combination of the following four components:
A task's execution mode is a combination of the following
four components:
@itemize @bullet
@item preemption
@@ -154,7 +161,9 @@ A task's mode is a combination of the following four components:
@end itemize
It is used to modify RTEMS' scheduling process and to alter the
execution environment of the task.
execution environment of the task. The data type
@code{@value{DIRPREFIX}task_mode} is used to manage the task
execution mode.
@cindex preemption
@@ -210,6 +219,7 @@ specifies that the task will execute at interrupt level n.
@subsection Accessing Task Arguments
@cindex task arguments
@cindex task prototype
All RTEMS tasks are invoked with a single argument which is
specified when they are started or restarted. The argument is
@@ -218,6 +228,8 @@ The simplest manner in which to define a task which accesses it
argument is:
@ifset is-C
@findex rtems_task
@example
rtems_task user_task(
rtems_task_argument argument
@@ -240,7 +252,8 @@ single argument as an index into an array of parameter blocks.
@cindex floating point
Creating a task with the @code{@value{RPREFIX}FLOATING_POINT} flag results
Creating a task with the @code{@value{RPREFIX}FLOATING_POINT} attribute
flag results
in additional memory being allocated for the TCB to store the state of the
numeric coprocessor during task switches. This additional memory is
@b{NOT} allocated for @code{@value{RPREFIX}NO_FLOATING_POINT} tasks. Saving
@@ -726,10 +739,6 @@ This directive will not cause the calling task to be preempted.
Valid task priorities range from a high of 1 to a low of 255.
RTEMS supports a maximum of 256 interrupt levels which are
mapped onto the interrupt levels actually supported by the
target processor.
The requested stack size should be at least
@code{@value{RPREFIX}MINIMUM_STACK_SIZE}
bytes. The value of @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
@@ -760,6 +769,11 @@ The following task mode constants are defined by RTEMS:
@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} - execute at interrupt level n
@end itemize
The interrupt level portion of the task execution mode
supports a maximum of 256 interrupt levels. These levels are
mapped onto the interrupt levels actually supported by the
target processor in a processor dependent fashion.
Tasks should not be made global unless remote tasks must
interact with them. This avoids the system overhead incurred by
the creation of a global task. When a global task is created,

1
doc/user/timer.t
View File

@@ -58,6 +58,7 @@ The timer service routine should adhere to @value{LANGUAGE} calling
conventions and have a prototype similar to the following:
@ifset is-C
@findex rtems_timer_service_routine
@example
rtems_timer_service_routine user_routine(
rtems_id timer_id,

32
doc/user/userext.t
View File

@@ -56,6 +56,7 @@ performance monitoring or debugger support. RTEMS is informed of
the entry points which constitute an extension set via the
following @value{STRUCTURE}:
@findex rtems_extensions_table
@ifset is-C
@example
@group
@@ -68,7 +69,7 @@ typedef struct @{
rtems_task_begin_extension thread_begin;
rtems_task_exitted_extension thread_exitted;
rtems_fatal_extension fatal;
@} User_extensions_Table;
@} rtems_extensions_table;
@end group
@end example
@end ifset
@@ -169,7 +170,7 @@ its arguments are all defined by the user. The names used in
the examples were arbitrarily chosen and impose no naming
conventions on the user.
@subsection TASK_CREATE Extension
@subsubsection TASK_CREATE Extension
The TASK_CREATE extension directly corresponds to the
task_create directive. If this extension is defined in any
@@ -178,6 +179,8 @@ then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:
@findex rtems_task_create_extension
@findex rtems_extension
@ifset is-C
@example
rtems_extension user_task_create(
@@ -203,7 +206,7 @@ invoked from the task_create directive after new_task has been
completely initialized, but before it is placed on a ready TCB
chain.
@subsection TASK_START Extension
@subsubsection TASK_START Extension
The TASK_START extension directly corresponds to the
task_start directive. If this extension is defined in any
@@ -212,6 +215,7 @@ then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:
@findex rtems_task_start_extension
@ifset is-C
@example
rtems_extension user_task_start(
@@ -237,7 +241,7 @@ extension is invoked from the task_start directive after
started_task has been made ready to start execution, but before
it is placed on a ready TCB chain.
@subsection TASK_RESTART Extension
@subsubsection TASK_RESTART Extension
The TASK_RESTART extension directly corresponds to
the task_restart directive. If this extension is defined in any
@@ -245,6 +249,7 @@ static or dynamic extension set and a task is being restarted,
then the extension should have a prototype similar to the
following:
@findex rtems_task_restart_extension
@ifset is-C
@example
rtems_extension user_task_restart(
@@ -270,7 +275,7 @@ invoked from the task_restart directive after restarted_task has
been made ready to start execution, but before it is placed on a
ready TCB chain.
@subsection TASK_DELETE Extension
@subsubsection TASK_DELETE Extension
The TASK_DELETE extension is associated with the
task_delete directive. If this extension is defined in any
@@ -279,6 +284,7 @@ then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:
@findex rtems_task_delete_extension
@ifset is-C
@example
rtems_extension user_task_delete(
@@ -306,7 +312,7 @@ including the TCB have been returned to their respective free
pools. This extension should not call any RTEMS directives if a
task is deleting itself (current_task is equal to deleted_task).
@subsection TASK_SWITCH Extension
@subsubsection TASK_SWITCH Extension
The TASK_SWITCH extension corresponds to a task
context switch. If this extension is defined in any static or
@@ -315,6 +321,7 @@ then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:
@findex rtems_task_switch_extension
@ifset is-C
@example
rtems_extension user_task_switch(
@@ -341,13 +348,14 @@ context has been saved, but before the heir_task context has
been restored. This extension should not call any RTEMS
directives.
@subsection TASK_BEGIN Extension
@subsubsection TASK_BEGIN Extension
The TASK_BEGIN extension is invoked when a task
begins execution. It is invoked immediately before the body of
the starting procedure and executes in the context in the task.
This user extension have a prototype similar to the following:
@findex rtems_task_begin_extension
@ifset is-C
@example
rtems_extension user_task_begin(
@@ -372,13 +380,14 @@ task while the TASK_START extension is executed in the context
of the task performing the task_start directive. For most
extensions, this is not a critical distinction.
@subsection TASK_EXITTED Extension
@subsubsection TASK_EXITTED Extension
The TASK_EXITTED extension is invoked when a task
exits the body of the starting procedure by either an implicit
or explicit return statement. This user extension have a
prototype similar to the following:
@findex rtems_task_exitted_extension
@ifset is-C
@example
rtems_extension user_task_exitted(
@@ -407,9 +416,7 @@ returns control to RTEMS, then the RTEMS default handler will be
used. This default handler invokes the directive
fatal_error_occurred with the @code{@value{RPREFIX}TASK_EXITTED} directive status.
@lowersections
@subsection FATAL Error Extension
@subsubsection FATAL Error Extension
The FATAL error extension is associated with the
fatal_error_occurred directive. If this extension is defined in
@@ -417,6 +424,7 @@ any static or dynamic extension set and the fatal_error_occurred
directive has been invoked, then this extension will be called.
This extension should have a prototype similar to the following:
@findex rtems_fatal_extension
@ifset is-C
@example
rtems_extension user_fatal_error(
@@ -445,8 +453,6 @@ the processor is stopped. For example, this extension could be
used to pass control to a debugger when a fatal error occurs.
This extension should not call any RTEMS directives.
@raisesections
@subsection Order of Invocation
When one of the critical system events occur, the