summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1998-03-27 16:47:53 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1998-03-27 16:47:53 +0000
commit75e22db0d500f02e6a1c0304ead2bff4f0790139 (patch)
treeca305e8aaeae1be3a5453ed607451fe8f577e27b /doc/user
parentShould have included <rtems.h> before checking for ifdef RTEMS_UNIX. (diff)
downloadrtems-75e22db0d500f02e6a1c0304ead2bff4f0790139.tar.bz2
Completed sweep adding directive and constant prefixes.
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/bsp.t33
-rw-r--r--doc/user/clock.t100
-rw-r--r--doc/user/conf.t34
-rw-r--r--doc/user/dpmem.t15
-rw-r--r--doc/user/event.t32
-rw-r--r--doc/user/example.texi2
-rw-r--r--doc/user/fatal.t16
-rw-r--r--doc/user/glossary.texi10
-rw-r--r--doc/user/init.t79
-rw-r--r--doc/user/intr.t20
-rw-r--r--doc/user/io.t19
-rw-r--r--doc/user/mp.t18
-rw-r--r--doc/user/msg.t64
-rw-r--r--doc/user/part.t39
-rw-r--r--doc/user/region.t61
-rw-r--r--doc/user/rtmon.t82
-rw-r--r--doc/user/schedule.t89
-rw-r--r--doc/user/sem.t141
-rw-r--r--doc/user/signal.t35
-rw-r--r--doc/user/task.t480
-rw-r--r--doc/user/timer.t58
-rw-r--r--doc/user/userext.t16
22 files changed, 830 insertions, 613 deletions
diff --git a/doc/user/bsp.t b/doc/user/bsp.t
index dcef8a073e..06c81458f0 100644
--- a/doc/user/bsp.t
+++ b/doc/user/bsp.t
@@ -55,14 +55,16 @@ variety of processors and target platforms.
Normally, the application's initialization is
performed at two separate times: before the call to
-initialize_executive (reset application initialization) and
-after initialize_executive in the user's initialization tasks
+@code{@value{DIRPREFIX}initialize_executive}
+(reset application initialization) and
+after @code{@value{DIRPREFIX}initialize_executive}
+in the user's initialization tasks
(local and global application initialization). The order of the
startup procedure is as follows:
@enumerate
@item Reset application initialization.
-@item Call to initialize_executive
+@item Call to @code{@value{DIRPREFIX}initialize_executive}
@item Local and global application initialization.
@end enumerate
@@ -79,15 +81,17 @@ The processor's Interrupt Vector Table which will be
used by the application may need to be set to the required value
by the reset application initialization code. Because
interrupts are enabled automatically by RTEMS as part of the
-initialize_executive directive, the Interrupt Vector Table MUST
+@code{@value{DIRPREFIX}initialize_executive} directive,
+the Interrupt Vector Table MUST
be set before this directive is invoked to insure correct
interrupt vectoring. The processor's Interrupt Vector Table
must be accessible by RTEMS as it will be modified by the
-interrupt_catch directive. On some CPUs, RTEMS installs it's
+@code{@value{DIRPREFIX}interrupt_catch} directive.
+On some CPUs, RTEMS installs it's
own Interrupt Vector Table as part of initialization and thus
these requirements are met automatically. The reset code which
-is executed before the call to initialize_executive has the
-following requirements:
+is executed before the call to @code{@value{DIRPREFIX}initialize_executive}
+has the following requirements:
@itemize @bullet
@item Must not make any RTEMS directive calls.
@@ -98,7 +102,7 @@ state.
@item Must allocate a stack of at least @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
bytes and initialize the stack pointer for the
-initialize_executive directive.
+@code{@value{DIRPREFIX}initialize_executive} directive.
@item Must initialize the processor's Interrupt Vector Table.
@@ -109,7 +113,7 @@ must allocate the interrupt stack and initialize the interrupt
stack pointer.
@end itemize
-The initialize_executive directive does not return to
+The @code{@value{DIRPREFIX}initialize_executive} directive does not return to
the initialization code, but causes the highest priority
initialization task to begin execution. Initialization tasks
are used to perform both local and global application
@@ -208,10 +212,10 @@ I/O Manager chapter.
@subsection Clock Tick Device Driver
Most RTEMS applications will include a clock tick
-device driver which invokes the clock_tick directive at regular
-intervals. The clock tick is necessary if the application is to
-utilize timeslicing, the clock manager, the timer manager, the
-rate monotonic manager, or the timeout option on blocking
+device driver which invokes the @code{@value{DIRPREFIX}clock_tick}
+directive at regular intervals. The clock tick is necessary if
+the application is to utilize timeslicing, the clock manager, the
+timer manager, the rate monotonic manager, or the timeout option on blocking
directives.
The clock tick is usually provided as an interrupt
@@ -226,7 +230,8 @@ accuracy of tick occurrences. The initial count can be based on
the microseconds_per_tick field in the RTEMS Configuration
Table. An alternate approach is to set the initial count for a
fixed time period (such as one millisecond) and have the ISR
-invoke clock_tick on the microseconds_per_tick boundaries.
+invoke @code{@value{DIRPREFIX}clock_tick}
+on the microseconds_per_tick boundaries.
Obviously, this can induce some error if the configured
microseconds_per_tick is not evenly divisible by the chosen
clock interrupt quantum.
diff --git a/doc/user/clock.t b/doc/user/clock.t
index e3d5ebcf20..256713d5e8 100644
--- a/doc/user/clock.t
+++ b/doc/user/clock.t
@@ -56,7 +56,8 @@ the clock manager are:
For the features provided by the clock manager to be
utilized, periodic timer interrupts are required. Therefore, a
real-time clock or hardware timer is necessary to create the
-timer interrupts. The clock_tick directive is normally called
+timer interrupts. The @code{@value{DIRPREFIX}clock_tick}
+directive is normally called
by the timer ISR to announce to RTEMS that a system clock tick
has occurred. Elapsed time is measured in ticks. A tick is
defined to be an integral number of microseconds which is
@@ -105,9 +106,10 @@ type Time_Of_Day is
The native date and time format is the only format
supported when setting the system date and time using the
-clock_get directive. Some applications expect to operate on a
-"UNIX-style" date and time data structure. The clock_get
-directive can optionally return the current date and time in the
+@code{@value{DIRPREFIX}clock_get} directive. Some applications
+expect to operate on a "UNIX-style" date and time data structure. The
+@code{@value{DIRPREFIX}clock_get} directive can optionally return
+the current date and time in the
following @value{STRUCTURE}:
@ifset is-C
@@ -151,7 +153,8 @@ number of ticks, and is specified in the Configuration Table.
The timeslice is defined for the entire system of tasks, but
timeslicing is enabled and disabled on a per task basis.
-The clock_tick directive implements timeslicing by
+The @code{@value{DIRPREFIX}clock_tick}
+directive implements timeslicing by
decrementing the running task's time-remaining counter when both
timeslicing and preemption are enabled. If the task's timeslice
has expired, then that task will be preempted if there exists a
@@ -165,7 +168,8 @@ ready task of equal priority.
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
-task_wake_after and task_wake_when directives and, as a result,
+@code{@value{DIRPREFIX}task_wake_after}
+and @code{@value{DIRPREFIX}task_wake_when} directives and, as a result,
does not have an RTEMS ID. Once activated, a sleep timer cannot
be explicitly deleted. Each task may activate one and only one
sleep timer at a time.
@@ -177,10 +181,12 @@ sleep timer at a time.
Timeouts are a special type of timer automatically
created when the timeout option is used on the
-message_queue_receive, event_receive, semaphore_obtain and
-region_get_segment directives. Each task may have one and only
-one timeout active at a time. When a timeout expires, it
-unblocks the task with a timeout status code.
+@code{@value{DIRPREFIX}message_queue_receive},
+@code{@value{DIRPREFIX}event_receive},
+@code{@value{DIRPREFIX}semaphore_obtain} and
+@code{@value{DIRPREFIX}region_get_segment} directives.
+Each task may have one and only one timeout active at a time.
+When a timeout expires, it unblocks the task with a timeout status code.
@ifinfo
@node Clock Manager Operations, Announcing a Tick, Timeouts, Clock Manager
@@ -199,18 +205,22 @@ unblocks the task with a timeout status code.
@end ifinfo
@subsection Announcing a Tick
-RTEMS provides the clock_tick directive which is
+RTEMS provides the @code{@value{DIRPREFIX}clock_tick} directive which is
called from the user's real-time clock ISR to inform RTEMS that
a tick has elapsed. The tick frequency value, defined in
microseconds, is a configuration parameter found in the
Configuration Table. RTEMS divides one million microseconds
(one second) by the number of microseconds per tick to determine
-the number of calls to the clock_tick directive per second. The
-frequency of clock_tick calls determines the resolution
+the number of calls to the
+@code{@value{DIRPREFIX}clock_tick} directive per second. The
+frequency of @code{@value{DIRPREFIX}clock_tick}
+calls determines the resolution
(granularity) for all time dependent RTEMS actions. For
-example, calling clock_tick ten times per second yields a higher
-resolution than calling clock_tick two times per second. The
-clock_tick directive is responsible for maintaining both
+example, calling @code{@value{DIRPREFIX}clock_tick}
+ten times per second yields a higher
+resolution than calling @code{@value{DIRPREFIX}clock_tick}
+two times per second. The @code{@value{DIRPREFIX}clock_tick}
+directive is responsible for maintaining both
calendar time and the dynamic set of timers.
@ifinfo
@@ -218,41 +228,43 @@ calendar time and the dynamic set of timers.
@end ifinfo
@subsection Setting the Time
-The clock_set directive allows a task or an ISR to
+The @code{@value{DIRPREFIX}clock_set} directive allows a task or an ISR to
set the date and time maintained by RTEMS. If setting the date
and time causes any outstanding timers to pass their deadline,
then the expired timers will be fired during the invocation of
-the clock_set directive.
+the @code{@value{DIRPREFIX}clock_set} directive.
@ifinfo
@node Obtaining the Time, Clock Manager Directives, Setting the Time, Clock Manager Operations
@end ifinfo
@subsection Obtaining the Time
-The clock_get directive allows a task or an ISR to
+The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to
obtain the current date and time or date and time related
information. The current date and time can be returned in
either native or UNIX-style format. Additionally, the
application can obtain date and time related information such as
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 clock_get directive is
+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:
@itemize @bullet
@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
-@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style date and time
+@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style
+date and time
@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks
since RTEMS was initialized
-@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number of seconds
-since RTEMS epoch
+@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number
+of seconds since RTEMS epoch
-@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock ticks
-per second
+@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock
+ticks per second
@end itemize
@@ -326,8 +338,8 @@ clock tick.
Re-initializing RTEMS causes the system date and time
to be reset to an uninitialized state. Another call to
-clock_set is required to re-initialize the system date and time
-to application specific specifications.
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize
+the system date and time to application specific specifications.
@page
@ifinfo
@@ -365,12 +377,15 @@ procedure Clock_Get (
This directive obtains the system date and time. If
the caller is attempting to obtain the date and time (i.e.
option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH},
-@code{@value{RPREFIX}CLOCK_GET_TOD}, or @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
-has not been set with a previous call to clock_set, then the
-@code{@value{RPREFIX}NOT_DEFINED} status code is returned. The caller can always
-obtain the number of ticks per second (option is
-@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of ticks since the
-executive was initialized option is @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
+@code{@value{RPREFIX}CLOCK_GET_TOD}, or
+@code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
+has not been set with a previous call to
+@code{@value{DIRPREFIX}clock_set}, then the
+@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
+The caller can always obtain the number of ticks per second (option is
+@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of
+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:
@@ -391,19 +406,20 @@ The data type expected for time_buffer is indicated below:
@ifset is-Ada
@itemize @bullet
-@item @code{@value{RPREFIX}CLOCK_GET_TOD} - Address of an variable of type RTEMS.Time_Of_Day
+@item @code{@value{RPREFIX}CLOCK_GET_TOD} - Address of an variable of
+type RTEMS.Time_Of_Day
@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - Address of an variable of
type RTEMS.Clock_Time_Value
-@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - Address of an variable of
-type RTEMS.Interval
+@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - Address of an
+variable of type RTEMS.Interval
-@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - Address of an variable of
-type RTEMS.Interval
+@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - Address of an
+variable of type RTEMS.Interval
-@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - Address of an variable of
-type RTEMS.Interval
+@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - Address of an
+variable of type RTEMS.Interval
@end itemize
@end ifset
@@ -415,8 +431,8 @@ This directive is callable from an ISR.
This directive will not cause the running task to be
preempted. Re-initializing RTEMS causes the system date and
time to be reset to an uninitialized state. Another call to
-clock_set is required to re-initialize the system date and time
-to application specific specifications.
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
+system date and time to application specific specifications.
@page
@ifinfo
diff --git a/doc/user/conf.t b/doc/user/conf.t
index 02cccf3bc5..af0d419444 100644
--- a/doc/user/conf.t
+++ b/doc/user/conf.t
@@ -35,8 +35,9 @@ The RTEMS Configuration Table is used to tailor an
application for its specific needs. For example, the user can
configure the number of device drivers or which APIs may be used.
THe address of the user-defined Configuration Table is passed as an
-argument to the initialize_executive directive, which MUST be
-the first RTEMS directive called. The RTEMS Configuration Table
+argument to the @code{@value{DIRPREFIX}initialize_executive}
+directive, which MUST be the first RTEMS directive called.
+The RTEMS Configuration Table
is defined in the following @value{LANGUAGE} @value{STRUCTURE}:
@ifset is-C
@@ -90,7 +91,7 @@ This area contains items such as the
various object control blocks (TCBs, QCBs, ...) and task stacks.
If the address is not aligned on a four-word boundary, then
RTEMS will invoke the fatal error handler during
-initialize_executive.
+@code{@value{DIRPREFIX}initialize_executive}.
@item work_space_size
is the calculated size of the
@@ -524,23 +525,24 @@ type Driver_Address_Table_Pointer is access all Driver_Address_Table;
@table @b
@item initialization
-is the address of the entry point called by io_initialize
+is the address of the entry point called by
+@code{@value{DIRPREFIX}io_initialize}
to initialize a device driver and its associated devices.
@item open
-is the address of the entry point called by io_open.
+is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
@item close
-is the address of the entry point called by io_close.
+is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
@item read
-is the address of the entry point called by io_read.
+is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
@item write
-is the address of the entry point called by io_write.
+is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
@item control
-is the address of the entry point called by io_control.
+is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
@end table
@@ -690,12 +692,13 @@ subroutine which is invoked when a task exits. This procedure
is responsible for some action which will allow the system to
continue execution (i.e. delete or restart the task) or to
terminate with a fatal error. If this field is set to NULL, the
-default RTEMS task_exitted handler will be invoked.
+default RTEMS TASK_EXITTED handler will be invoked.
@item fatal
is the address of the user-supplied
subroutine for the FATAL extension. This RTEMS extension of
-fatal error handling is called from the fatal_error_occurred
+fatal error handling is called from the
+@code{@value{DIRPREFIX}fatal_error_occurred}
directive. If the user's fatal error handler returns or if this
entry is NULL then the default RTEMS fatal error handler will be
executed.
@@ -971,8 +974,10 @@ the RTEMS RAM Workspace.
The starting address of the RTEMS RAM Workspace must
be aligned on a four-byte boundary. Failure to properly align
-the workspace area will result in the fatal_error_occurred
-directive being invoked with the @code{@value{RPREFIX}INVALID_ADDRESS} error code.
+the workspace area will result in the
+@code{@value{DIRPREFIX}fatal_error_occurred}
+directive being invoked with the
+@code{@value{RPREFIX}INVALID_ADDRESS} error code.
A worksheet is provided in the Memory Requirements
chapter of the Applications Supplement document for a specific
@@ -1000,5 +1005,6 @@ each time one of the following events occurs:
@end itemize
Failure to provide enough space in the RTEMS RAM
-Workspace will result in the fatal_error_occurred directive
+Workspace will result in the
+@code{@value{DIRPREFIX}fatal_error_occurred} directive
being invoked with the appropriate error code.
diff --git a/doc/user/dpmem.t b/doc/user/dpmem.t
index 28c689e665..23d92e44a2 100644
--- a/doc/user/dpmem.t
+++ b/doc/user/dpmem.t
@@ -76,7 +76,7 @@ transfers.
@end ifinfo
@subsection Creating a Port
-The port_create directive creates a port into a DPMA
+The @code{@value{DIRPREFIX}port_create} directive creates a port into a DPMA
with the user-defined name. The user specifies the association
between internal and external representations for the port being
created. RTEMS allocates a Dual-Ported Memory Control Block
@@ -94,9 +94,11 @@ within it.
When a port is created, RTEMS generates a unique port
ID and assigns it to the created port until it is deleted. The
port ID may be obtained by either of two methods. First, as the
-result of an invocation of the port_create directive, the task
+result of an invocation of the
+@code{@value{DIRPREFIX}port_create} directive, the task
ID is stored in a user provided location. Second, the port ID
-may be obtained later using the port_ident directive. The port
+may be obtained later using the
+@code{@value{DIRPREFIX}port_ident} directive. The port
ID is used by other dual-ported memory manager directives to
access this port.
@@ -105,9 +107,10 @@ access this port.
@end ifinfo
@subsection Converting an Address
-The port_external_to_internal directive is used to
+The @code{@value{DIRPREFIX}port_external_to_internal} directive is used to
convert an address from external to internal representation for
-the specified port. The port_internal_to_external directive is
+the specified port.
+The @code{@value{DIRPREFIX}port_internal_to_external} directive is
used to convert an address from internal to external
representation for the specified port. If an attempt is made to
convert an address which lies outside the specified DPMA, then
@@ -119,7 +122,7 @@ the address to be converted will be returned.
@subsection Deleting a DPMA Port
A port can be removed from the system and returned to
-RTEMS with the port_delete directive. When a port is deleted,
+RTEMS with the @code{@value{DIRPREFIX}port_delete} directive. When a port is deleted,
its control block is returned to the DPCB free list.
@ifinfo
diff --git a/doc/user/event.t b/doc/user/event.t
index 231d81bfba..aebcc215bc 100644
--- a/doc/user/event.t
+++ b/doc/user/event.t
@@ -100,8 +100,8 @@ exactly once in the event set list.
For example, when sending the event set consisting of
@code{@value{RPREFIX}EVENT_6}, @code{@value{RPREFIX}EVENT_15}, and @code{@value{RPREFIX}EVENT_31},
-the event parameter to the event_send directive should be
-@code{@value{RPREFIX}EVENT_6 @value{OR}
+the event parameter to the @code{@value{DIRPREFIX}event_send}
+directive should be @code{@value{RPREFIX}EVENT_6 @value{OR}
@value{RPREFIX}EVENT_15 @value{OR} @value{RPREFIX}EVENT_31}.
@ifinfo
@@ -111,7 +111,8 @@ the event parameter to the event_send directive should be
In general, an option is built by a bitwise OR of the
desired option components. The set of valid options for the
-event_receive directive are listed in the following table:
+@code{@value{DIRPREFIX}event_receive} directive are listed
+in the following table:
@itemize @bullet
@item @code{@value{RPREFIX}WAIT} - task will wait for event (default)
@@ -131,12 +132,12 @@ specified on this call.
This example demonstrates the option parameter needed
to poll for all events in a particular event condition to
-arrive. The option parameter passed to the event_receive
-directive should be either
+arrive. The option parameter passed to the
+@code{@value{DIRPREFIX}event_receive} directive should be either
@code{@value{RPREFIX}EVENT_ALL @value{OR} @value{RPREFIX}NO_WAIT}
or @code{@value{RPREFIX}NO_WAIT}. The option parameter can be set to
@code{@value{RPREFIX}NO_WAIT} because @code{@value{RPREFIX}EVENT_ALL} is the
-default condition for event_receive.
+default condition for @code{@value{DIRPREFIX}event_receive}.
@ifinfo
@node Event Manager Operations, Sending an Event Set, Building an EVENT_RECEIVE Option Set, Event Manager
@@ -156,7 +157,7 @@ default condition for event_receive.
@end ifinfo
@subsection Sending an Event Set
-The event_send directive allows a task (or an ISR) to
+The @code{@value{DIRPREFIX}event_send} directive allows a task (or an ISR) to
direct an event set to a target task. Based upon the state of
the target task, one of the following situations applies:
@@ -187,7 +188,7 @@ task remains blocked.
@end ifinfo
@subsection Receiving an Event Set
-The event_receive directive is used by tasks to
+The @code{@value{DIRPREFIX}event_receive} directive is used by tasks to
accept a specific input event condition. The task also
specifies whether the request is satisfied when all requested
events are available or any single requested event is available.
@@ -213,9 +214,10 @@ wait before returning with an error status code.
@subsection Determining the Pending Event Set
A task can determine the pending event set by calling
-the event_receive directive with a value of PENDING_EVENTS for
-the input event condition. The pending events are returned to
-the calling task but the event set is left unaltered.
+the @code{@value{DIRPREFIX}event_receive} directive with a value of
+@code{@value{RPREFIX}PENDING_EVENTS} for the input event condition.
+The pending events are returned to the calling task but the event
+set is left unaltered.
@ifinfo
@node Receiving all Pending Events, Event Manager Directives, Determining the Pending Event Set, Event Manager Operations
@@ -223,8 +225,9 @@ the calling task but the event set is left unaltered.
@subsection Receiving all Pending Events
A task can receive all of the currently pending
-events by calling the event_receive directive with a value of
-@code{@value{RPREFIX}ALL_EVENTS} for the input event condition and
+events by calling the @code{@value{DIRPREFIX}event_receive}
+directive with a value of @code{@value{RPREFIX}ALL_EVENTS}
+for the input event condition and
@code{@value{RPREFIX}NO_WAIT @value{OR} @value{RPREFIX}EVENT_ANY}
for the option set. The pending events are returned to the
calling task and the event set is cleared. If no events are
@@ -294,7 +297,8 @@ sent to the calling task.
Identical events sent to a task are not queued. In
other words, the second, and subsequent, posting of an event to
-a task before it can perform an event_receive has no effect.
+a task before it can perform an @code{@value{DIRPREFIX}event_receive}
+has no effect.
The calling task will be preempted if it has
preemption enabled and a higher priority task is unblocked as
diff --git a/doc/user/example.texi b/doc/user/example.texi
index b2df877ffa..683777511d 100644
--- a/doc/user/example.texi
+++ b/doc/user/example.texi
@@ -26,7 +26,7 @@
rtems_task init_task();
-#define INIT_NAME build_name( 'A', 'B', 'C', ' ' ' )
+#define INIT_NAME rtems_build_name( 'A', 'B', 'C', ' ' ' )
rtems_initialization_tasks_table init_task = @{
@{ INIT_NAME, /* init task name "ABC" */
diff --git a/doc/user/fatal.t b/doc/user/fatal.t
index f51549a6b7..0c07a184ba 100644
--- a/doc/user/fatal.t
+++ b/doc/user/fatal.t
@@ -88,10 +88,11 @@ a specific target processor.
@end ifinfo
@subsection Announcing a Fatal Error
-The fatal_error_occurred directive is invoked when a
+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
-fatal_error_occurred directive stores useful information in the
+@code{@value{DIRPREFIX}fatal_error_occurred}
+directive stores useful information in the
variable @code{_Internal_errors_What_happened}. This @value{STRUCTURE}
contains three pieces of information:
@@ -106,9 +107,13 @@ executive, and a
The error type indicator is dependent on the source
of the error and whether or not the error was internally
-generated by the executive.
+generated by the executive. If the error was generated
+from an API, then the error code will be of that API's
+error or status codes. The status codes for the RTEMS
+API are in c/src/exec/rtems/headers/status.h. Those
+for the POSIX API can be found in <errno.h>.
-The fatal_error_directive directive is responsible
+The @code{@value{DIRPREFIX}fatal_error_occurred} directive is responsible
for invoking an optional user-supplied fatal error handler
and/or the RTEMS fatal error handler. All fatal error handlers
are passed an error code to describe the error detected.
@@ -118,7 +123,8 @@ sophisticated fatal error processing such as passing control to
a debugger. For these cases, a user-supplied fatal error
handler can be specified in the RTEMS configuration table. The
User Extension Table field fatal contains the address of the
-fatal error handler to be executed when the fatal_error_occurred
+fatal error handler to be executed when the
+@code{@value{DIRPREFIX}fatal_error_occurred}
directive is called. If the field is set to NULL or if the
configured fatal error handler returns to the executive, then
the default handler provided by RTEMS is executed. This default
diff --git a/doc/user/glossary.texi b/doc/user/glossary.texi
index c4016c525c..1f3794e994 100644
--- a/doc/user/glossary.texi
+++ b/doc/user/glossary.texi
@@ -573,7 +573,8 @@ access must be controlled.
@item resume
Removing a task from the suspend state. If
-the task's state is ready following a call to the task_resume
+the task's state is ready following a call to the
+@code{@value{DIRPREFIX}task_resume}
directive, then the task is available for scheduling.
@item return code
@@ -657,8 +658,8 @@ value.
@item suspend
A term used to describe a task that is not
-competing for the CPU because it has had a task_suspend
-directive.
+competing for the CPU because it has had a
+@code{@value{DIRPREFIX}task_suspend} directive.
@item synchronous
Related in order or timing to other
@@ -691,7 +692,8 @@ An acronym for Task Control Block.
@item tick
The basic unit of time used by RTEMS. It is a
user-configurable number of microseconds. The current tick
-expires when the clock_tick directive is invoked.
+expires when the @code{@value{DIRPREFIX}clock_tick}
+directive is invoked.
@item tightly-coupled
A multiprocessor configuration
diff --git a/doc/user/init.t b/doc/user/init.t
index 4f11d70667..3cd79e18b0 100644
--- a/doc/user/init.t
+++ b/doc/user/init.t
@@ -123,7 +123,8 @@ other task is made ready to execute.
@subsection Initialization Manager Failure
The fatal_error_occurred directive will be called
-from initialize_executive for any of the following reasons:
+from @code{@value{DIRPREFIX}initialize_executive}
+for any of the following reasons:
@itemize @bullet
@item If either the Configuration Table or the CPU Dependent
@@ -170,11 +171,13 @@ created or started successfully.
@end ifinfo
@subsection Initializing RTEMS
-The initialize_executive directive is called by the
+The @code{@value{DIRPREFIX}initialize_executive}
+directive is called by the
board support package at the completion of its initialization
sequence. RTEMS assumes that the board support package
successfully completed its initialization activities. The
-initialize_executive directive completes the initialization
+@code{@value{DIRPREFIX}initialize_executive}
+directive completes the initialization
sequence by performing the following actions:
@itemize @bullet
@@ -188,7 +191,8 @@ sequence by performing the following actions:
This directive MUST be called before any other RTEMS
directives. The effect of calling any RTEMS directives before
-initialize_executive is unpredictable. Many of RTEMS actions
+@code{@value{DIRPREFIX}initialize_executive}
+is unpredictable. Many of RTEMS actions
during initialization are based upon the contents of the
Configuration Table and CPU Dependent Information Table. For
more information regarding the format and contents of these
@@ -198,17 +202,22 @@ The final step in the initialization sequence is the
initiation of multitasking. When the scheduler and dispatcher
are enabled, the highest priority, ready task will be dispatched
to run. Control will not be returned to the board support
-package after multitasking is enabled until shutdown_executive
+package after multitasking is enabled until
+@code{@value{DIRPREFIX}shutdown_executive}
the directive is called.
-The initialize_executive directive provides a
+The @code{@value{DIRPREFIX}initialize_executive}
+directive provides a
conceptually simple way to initialize RTEMS. However, in
certain cases, this mechanism cannot be used. The
-initialize_executive_early and initialize_executive_late
+@code{@value{DIRPREFIX}initialize_executive_early}
+and @code{@value{DIRPREFIX}initialize_executive_late}
directives are provided as an alternative mechanism for
-initializing RTEMS. The initialize_executive_early directive
+initializing RTEMS. The
+@code{@value{DIRPREFIX}initialize_executive_early} directive
returns to the caller BEFORE initiating multitasking. The
-initialize_executive_late directive is invoked to start
+@code{@value{DIRPREFIX}initialize_executive_late}
+directive is invoked to start
multitasking. It is critical that only one of the RTEMS
initialization sequences be used in an application.
@@ -217,11 +226,11 @@ initialization sequences be used in an application.
@end ifinfo
@subsection Shutting Down RTEMS
-The shutdown_executive directive is invoked by the
+The @code{@value{DIRPREFIX}shutdown_executive} directive is invoked by the
application to end multitasking and return control to the board
support package. The board support package resumes execution at
the code immediately following the invocation of the
-initialize_executive directive.
+@code{@value{DIRPREFIX}initialize_executive} directive.
@ifinfo
@node Initialization Manager Directives, INITIALIZE_EXECUTIVE - Initialize RTEMS, Shutting Down RTEMS, Initialization Manager
@@ -281,13 +290,15 @@ Information Table, User Initialization Tasks Table, Device
Driver Table, User Extension Table, Multiprocessor Configuration
Table, and the Multiprocessor Communications Interface (MPCI)
Table. This directive starts multitasking and does not return
-to the caller until the shutdown_executive directive is invoked.
+to the caller until the @code{@value{DIRPREFIX}shutdown_executive}
+directive is invoked.
@subheading NOTES:
This directive MUST be the first RTEMS directive
called and it DOES NOT RETURN to the caller until the
-shutdown_executive is invoked.
+@code{@value{DIRPREFIX}shutdown_executive}
+is invoked.
This directive causes all nodes in the system to
verify that certain configuration parameters are the same as
@@ -295,11 +306,15 @@ those of the local node. If an inconsistency is detected, then
a fatal error is generated.
The application must use only one of the two
-initialization sequences: initialize_executive or
-initialize_executive_early and initialize_executive_late. The
-initialize_executive directive is logically equivalent to
-invoking initialize_executive_early and
-initialize_executive_late with no intervening actions.
+initialization sequences:
+@code{@value{DIRPREFIX}initialize_executive} or
+@code{@value{DIRPREFIX}initialize_executive_early} and
+@code{@value{DIRPREFIX}initialize_executive_late}. The
+@code{@value{DIRPREFIX}initialize_executive}
+directive is logically equivalent to invoking
+@code{@value{DIRPREFIX}initialize_executive_early} and
+@code{@value{DIRPREFIX}initialize_executive_late}
+with no intervening actions.
@page
@ifinfo
@@ -345,13 +360,16 @@ Table. This directive returns to the caller after completing
the basic RTEMS initialization but before multitasking is
initiated. The interrupt level in place when the directive is
invoked is returned to the caller. This interrupt level should
-be the same one passed to initialize_executive_late.
+be the same one passed to
+@code{@value{DIRPREFIX}initialize_executive_late}.
@subheading NOTES:
The application must use only one of the two
-initialization sequences: initialize_executive or
-initialize_executive_early and initialize_executive_late.
+initialization sequences:
+@code{@value{DIRPREFIX}initialize_executive} or
+@code{@value{DIRPREFIX}nitialize_executive_early} and
+@code{@value{DIRPREFIX}nitialize_executive_late}.
@page
@ifinfo
@@ -384,18 +402,21 @@ NONE
@subheading DESCRIPTION:
This directive is called after the
-initialize_executive_early directive has been called to complete
+@code{@value{DIRPREFIX}initialize_executive_early}
+directive has been called to complete
the RTEMS initialization sequence and initiate multitasking.
-The interrupt level returned by the initialize_executive_early
+The interrupt level returned by the
+@code{@value{DIRPREFIX}initialize_executive_early}
directive should be in bsp_level and this value is restored as
part of this directive returning to the caller after the
-shutdown_executive directive is invoked.
+@code{@value{DIRPREFIX}shutdown_executive}
+directive is invoked.
@subheading NOTES:
This directive MUST be the second RTEMS directive
called and it DOES NOT RETURN to the caller until the
-shutdown_executive is invoked.
+@code{@value{DIRPREFIX}shutdown_executive} is invoked.
This directive causes all nodes in the system to
verify that certain configuration parameters are the same as
@@ -403,8 +424,10 @@ those of the local node. If an inconsistency is detected, then
a fatal error is generated.
The application must use only one of the two
-initialization sequences: initialize_executive or
-initialize_executive_early and initialize_executive_late.
+initialization sequences:
+@code{@value{DIRPREFIX}initialize_executive} or
+@code{@value{DIRPREFIX}nitialize_executive_early} and
+@code{@value{DIRPREFIX}initialize_executive_late}.
@@ -442,7 +465,7 @@ This directive is called when the application wishes
to shutdown RTEMS and return control to the board support
package. The board support package resumes execution at the
code immediately following the invocation of the
-initialize_executive directive.
+@code{@value{DIRPREFIX}initialize_executive} directive.
@subheading NOTES:
diff --git a/doc/user/intr.t b/doc/user/intr.t
index 2bf25a0369..ffd27bc475 100644
--- a/doc/user/intr.t
+++ b/doc/user/intr.t
@@ -68,7 +68,8 @@ 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.
-The interrupt_catch directive connects a procedure to
+The @code{@value{DIRPREFIX}interrupt_catch}
+directive connects a procedure to
an interrupt vector. The interrupt service routine is assumed
to abide by these conventions and have a prototype similar to
the following:
@@ -190,7 +191,8 @@ execute as non-maskable interrupts.
@end ifinfo
@subsection Establishing an ISR
-The interrupt_catch directive establishes an ISR for
+The @code{@value{DIRPREFIX}interrupt_catch}
+directive establishes an ISR for
the system. The address of the ISR and its associated CPU
vector number are specified to this directive. This directive
installs the RTEMS interrupt wrapper in the processor's
@@ -403,10 +405,11 @@ NONE
@subheading DESCRIPTION:
This directive enables maskable interrupts to the @code{level}
-which was returned by a previous call to @code{@value{DIRPREFIX}interrupt_disable}.
+which was returned by a previous call to
+@code{@value{DIRPREFIX}interrupt_disable}.
Immediately prior to invoking this directive, maskable interrupts should
-be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable} and will be enabled
-when this directive returns to the caller.
+be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable}
+and will be enabled when this directive returns to the caller.
@subheading NOTES:
@@ -444,10 +447,11 @@ NONE
@subheading DESCRIPTION:
This directive temporarily enables maskable interrupts to the @code{level}
-which was returned by a previous call to @code{@value{DIRPREFIX}interrupt_disable}.
+which was returned by a previous call to
+@code{@value{DIRPREFIX}interrupt_disable}.
Immediately prior to invoking this directive, maskable interrupts should
-be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable} and will be redisabled
-when this directive returns to the caller.
+be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable}
+and will be redisabled when this directive returns to the caller.
@subheading NOTES:
diff --git a/doc/user/io.t b/doc/user/io.t
index c301547d84..7710b50f4c 100644
--- a/doc/user/io.t
+++ b/doc/user/io.t
@@ -79,7 +79,8 @@ entry points:
If the device driver does not support a particular
entry point, then that entry in the Configuration Table should
-be NULL. RTEMS will return @code{@value{RPREFIX}SUCCESSFUL} as the executive's and
+be NULL. RTEMS will return
+@code{@value{RPREFIX}SUCCESSFUL} as the executive's and
zero (0) as the device driver's return code for these device
driver entry points.
@@ -223,10 +224,11 @@ the fatal_error_occurred directive.
@end ifinfo
@subsection Register and Lookup Name
-The io_register directive associates a name with the
+The @code{@value{DIRPREFIX}io_register} directive associates a name with the
specified device (i.e. major/minor number pair). Device names
are typically registered as part of the device driver
-initialization sequence. The io_lookup directive is used to
+initialization sequence. The @code{@value{DIRPREFIX}io_lookup}
+directive is used to
determine the major/minor number pair associated with the
specified device name. The use of these directives frees the
application from being dependent on the arbitrary assignment of
@@ -241,9 +243,14 @@ conventions are dictated by RTEMS.
The I/O manager provides directives which enable the
application program to utilize device drivers in a standard
manner. There is a direct correlation between the RTEMS I/O
-manager directives io_initialize, io_open, io_close, io_read,
-io_write, and io_control and the underlying device driver entry
-points.
+manager directives
+@code{@value{DIRPREFIX}io_initialize},
+@code{@value{DIRPREFIX}io_open},
+@code{@value{DIRPREFIX}io_close},
+@code{@value{DIRPREFIX}io_read},
+@code{@value{DIRPREFIX}io_write}, and
+@code{@value{DIRPREFIX}io_control}
+and the underlying device driver entry points.
@ifinfo
@node I/O Manager Directives, IO_INITIALIZE - Initialize a device driver, Accessing an Device Driver, I/O Manager
diff --git a/doc/user/mp.t b/doc/user/mp.t
index cec866063f..244550cd73 100644
--- a/doc/user/mp.t
+++ b/doc/user/mp.t
@@ -204,16 +204,16 @@ task.
@item The MPCI layer on the destination node senses the
arrival of a packet (commonly in an ISR), and calls the
-multiprocessing_announce directive. This directive readies the
-Multiprocessing Server.
+@code{@value{DIRPREFIX}multiprocessing_announce}
+directive. This directive readies the Multiprocessing Server.
@item The Multiprocessing Server calls the user-provided
MPCI routine RECEIVE_PACKET, performs the requested operation,
builds an RR message, and returns it to the originating node.
@item The MPCI layer on the originating node senses the
-arrival of a packet (typically via an interrupt), and calls the
-RTEMS multiprocessing_announce directive. This directive
+arrival of a packet (typically via an interrupt), and calls the RTEMS
+@code{@value{DIRPREFIX}multiprocessing_announce} directive. This directive
readies the Multiprocessing Server.
@item The Multiprocessing Server calls the user-provided
@@ -237,7 +237,8 @@ the MPCI and makes no attempt to detect or correct errors.
A proxy is an RTEMS data structure which resides on a
remote node and is used to represent a task which must block as
part of a remote operation. This action can occur as part of the
-semaphore_obtain and message_queue_receive directives. If the
+@code{@value{DIRPREFIX}semaphore_obtain} and
+@code{@value{DIRPREFIX}message_queue_receive} directives. If the
object were local, the task's control block would be available
for modification to indicate it was blocking on a message queue
or semaphore. However, the task's control block resides only on
@@ -323,7 +324,8 @@ situations:
If the target hardware supports it, the arrival of a
packet at a node may generate an interrupt. Otherwise, the
real-time clock ISR can check for the arrival of a packet. In
-any case, the multiprocessing_announce directive must be called
+any case, the
+@code{@value{DIRPREFIX}multiprocessing_announce} directive must be called
to announce the arrival of a packet. After exiting the ISR,
control will be passed to the Multiprocessing Server to process
the packet. The Multiprocessing Server will call the get_packet
@@ -336,7 +338,7 @@ copy the message into the buffer obtained.
@subsection INITIALIZATION
The INITIALIZATION component of the user-provided
-MPCI layer is called as part of the initialize_executive
+MPCI layer is called as part of the @code{@value{DIRPREFIX}initialize_executive}
directive to initialize the MPCI layer and associated hardware.
It is invoked immediately after all of the device drivers have
been initialized. This component should be adhere to the
@@ -627,7 +629,7 @@ data component of the packet.
@end ifinfo
@subsection Announcing a Packet
-The multiprocessing_announce directive is called by
+The @code{@value{DIRPREFIX}multiprocessing_announce} directive is called by
the MPCI layer to inform RTEMS that a packet has arrived from
another node. This directive can be called from an interrupt
service routine or from within a polling routine.
diff --git a/doc/user/msg.t b/doc/user/msg.t
index 62953311d2..38e65e34ce 100644
--- a/doc/user/msg.t
+++ b/doc/user/msg.t
@@ -37,7 +37,7 @@ directives provided by the message manager are:
@item @code{@value{DIRPREFIX}message_queue_broadcast} - Broadcast N messages to a queue
@item @code{@value{DIRPREFIX}message_queue_receive} - Receive message from a queue
@item @code{@value{DIRPREFIX}message_queue_get_number_pending} - Get number of messages pending on a queue
-@item @code{message_queue_flush} - Flush all messages on a queue
+@item @code{@value{DIRPREFIX}message_queue_flush} - Flush all messages on a queue
@end itemize
@ifinfo
@@ -71,8 +71,9 @@ user-defined and can be actual data, pointer(s), or empty.
A message queue permits the passing of messages among
tasks and ISRs. Message queues can contain a variable number of
messages. Normally messages are sent to and received from the
-queue in FIFO order using the message_queue_send directive.
-However, the message_queue_urgent directive can be used to place
+queue in FIFO order using the @code{@value{DIRPREFIX}message_queue_send}
+directive. However, the @code{@value{DIRPREFIX}message_queue_urgent}
+directive can be used to place
messages at the head of a queue in LIFO order.
Synchronization can be accomplished when a task can
@@ -99,22 +100,21 @@ queue attributes is provided in the following table:
@end itemize
-
An attribute listed as a default is not required to
appear in the attribute list, although it is a good programming
practice to specify default attributes. If all defaults are
-desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be specified on
-this call.
+desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES}
+should be specified on this call.
This example demonstrates the attribute_set parameter
needed to create a local message queue with the task priority
waiting queue discipline. The attribute_set parameter to the
-message_queue_create directive could be either
+@code{@value{DIRPREFIX}message_queue_create} directive could be either
@code{@value{RPREFIX}PRIORITY} or
@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}PRIORITY}.
The attribute_set parameter can be set to @code{@value{RPREFIX}PRIORITY}
-because @code{@value{RPREFIX}LOCAL} is the default for all created message queues. If
-a similar message queue were to be known globally, then the
+because @code{@value{RPREFIX}LOCAL} is the default for all created
+message queues. If a similar message queue were to be known globally, then the
attribute_set parameter would be
@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.
@@ -125,8 +125,8 @@ attribute_set parameter would be
In general, an option is built by a bitwise OR of the
desired option components. The set of valid options for the
-message_queue_receive directive are listed in the following
-table:
+@code{@value{DIRPREFIX}message_queue_receive} directive are
+listed in the following table:
@itemize @bullet
@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default)
@@ -136,12 +136,13 @@ table:
An option listed as a default is not required to
appear in the option OR list, although it is a good programming
practice to specify default options. If all defaults are
-desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should be specified on this
-call.
+desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should
+be specified on this call.
This example demonstrates the option parameter needed
to poll for a message to arrive. The option parameter passed to
-the message_queue_receive directive should be @code{@value{RPREFIX}NO_WAIT}.
+the @code{@value{DIRPREFIX}message_queue_receive} directive should
+be @code{@value{RPREFIX}NO_WAIT}.
@ifinfo
@node Message Manager Operations, Creating a Message Queue, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager
@@ -163,7 +164,7 @@ the message_queue_receive directive should be @code{@value{RPREFIX}NO_WAIT}.
@end ifinfo
@subsection Creating a Message Queue
-The message_queue_create directive creates a message
+The @code{@value{DIRPREFIX}message_queue_create} directive creates a message
queue with the user-defined name. The user specifies the
maximum message size and maximum number of messages which can be
placed in the message queue at one time. The user may select
@@ -186,18 +187,18 @@ capable of transmitting.
When a message queue is created, RTEMS generates a
unique message queue ID. The message queue ID may be obtained
by either of two methods. First, as the result of an invocation
-of the message_queue_create directive, the queue ID is stored in
-a user provided location. Second, the queue ID may be obtained
-later using the message_queue_ident directive. The queue ID is
-used by other message manager directives to access this message
-queue.
+of the @code{@value{DIRPREFIX}message_queue_create} directive, the
+queue ID is stored in a user provided location. Second, the queue
+ID may be obtained later using the @code{@value{DIRPREFIX}message_queue_ident}
+directive. The queue ID is used by other message manager
+directives to access this message queue.
@ifinfo
@node Receiving a Message, Sending a Message, Obtaining Message Queue IDs, Message Manager Operations
@end ifinfo
@subsection Receiving a Message
-The message_queue_receive directive attempts to
+The @code{@value{DIRPREFIX}message_queue_receive} directive attempts to
retrieve a message from the specified message queue. If at
least one message is in the queue, then the message is removed
from the queue, copied to the caller's message buffer, and
@@ -227,15 +228,17 @@ returned an error code when the message queue is deleted.
@subsection Sending a Message
Messages can be sent to a queue with the
-message_queue_send and message_queue_urgent directives. These
+@code{@value{DIRPREFIX}message_queue_send} and
+@code{@value{DIRPREFIX}message_queue_urgent} directives. These
directives work identically when tasks are waiting to receive a
message. A task is removed from the task waiting queue,
unblocked, and the message is copied to a waiting task's
message buffer.
When no tasks are waiting at the queue,
-message_queue_send places the message at the rear of the message
-queue, while message_queue_urgent places the message at the
+@code{@value{DIRPREFIX}message_queue_send} places the
+message at the rear of the message queue, while
+@code{@value{DIRPREFIX}message_queue_urgent} places the message at the
front of the queue. The message is copied to a message buffer
from this message queue's buffer pool and then placed in the
message queue. Neither directive can successfully send a
@@ -247,7 +250,7 @@ messages.
@end ifinfo
@subsection Broadcasting a Message
-The message_queue_broadcast directive sends the same
+The @code{@value{DIRPREFIX}message_queue_broadcast} directive sends the same
message to every task waiting on the specified message queue as
an atomic operation. The message is copied to each waiting
task's message buffer and each task is unblocked. The number of
@@ -258,7 +261,7 @@ tasks which were unblocked is returned to the caller.
@end ifinfo
@subsection Deleting a Message Queue
-The message_queue_delete directive removes a message
+The @code{@value{DIRPREFIX}message_queue_delete} directive removes a message
queue from the system and frees its control block as well as the
memory associated with this message queue's message buffer pool.
A message queue can be deleted by any local task that knows the
@@ -681,7 +684,7 @@ the result of this directive.
The execution time of this directive is directly
related to the number of tasks waiting on the message queue,
although it is more efficient than the equivalent number of
-invocations of message_queue_send.
+invocations of @code{@value{DIRPREFIX}message_queue_send}.
Broadcasting a message to a global message queue
which does not reside on the local node will generate a request
@@ -749,9 +752,10 @@ the queue is empty, then a status code indicating this condition
is returned. If the calling task chooses to wait at the message
queue and the queue is empty, then the calling task is placed on
the message wait queue and blocked. If the queue was created
-with the @code{@value{RPREFIX}PRIORITY} option specified, then the calling task is
-inserted into the wait queue according to its priority. But, if
-the queue was created with the @code{@value{RPREFIX}FIFO} option specified, then the
+with the @code{@value{RPREFIX}PRIORITY} option specified, then
+the calling task is inserted into the wait queue according to
+its priority. But, if the queue was created with the
+@code{@value{RPREFIX}FIFO} option specified, then the
calling task is placed at the rear of the wait queue.
A task choosing to wait at the queue can optionally
diff --git a/doc/user/part.t b/doc/user/part.t
index 140888420f..d19c5f22d9 100644
--- a/doc/user/part.t
+++ b/doc/user/part.t
@@ -76,21 +76,22 @@ of the desired attribute components. The set of valid partition
attributes is provided in the following table:
@itemize @bullet
-@item LOCAL - local task (default)
-@item GLOBAL - global task
+@item @code{@value{RPREFIX}LOCAL} - local task (default)
+@item @code{@value{RPREFIX}GLOBAL} - global task
@end itemize
-
Attribute values are specifically designed to be
mutually exclusive, therefore bitwise OR and addition operations
are equivalent as long as each attribute appears exactly once in
the component list. An attribute listed as a default is not
required to appear in the attribute list, although it is a good
programming practice to specify default attributes. If all
-defaults are desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
+defaults are desired, the attribute
+@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
specified on this call. The attribute_set parameter should be
-GLOBAL to indicate that the partition is to be known globally.
+@code{@value{RPREFIX}GLOBAL} to indicate that the partition
+is to be known globally.
@ifinfo
@node Partition Manager Operations, Creating a Partition, Building a Partition's Attribute Set, Partition Manager
@@ -111,10 +112,11 @@ GLOBAL to indicate that the partition is to be known globally.
@end ifinfo
@subsection Creating a Partition
-The partition_create directive creates a partition
+The @code{@value{DIRPREFIX}partition_create} directive creates a partition
with a user-specified name. The partition's name, starting
address, length and buffer size are all specified to the
-partition_create directive. RTEMS allocates a Partition Control
+@code{@value{DIRPREFIX}partition_create} directive.
+RTEMS allocates a Partition Control
Block (PTCB) from the PTCB free list. This data structure is
used by RTEMS to manage the newly created partition. The number
of buffers in the partition is calculated based upon the
@@ -130,11 +132,11 @@ When a partition is created, RTEMS generates a unique
partition ID and assigned it to the created partition until it
is deleted. The partition ID may be obtained by either of two
methods. First, as the result of an invocation of the
-partition_create directive, the partition ID is stored in a user
-provided location. Second, the partition ID may be obtained
-later using the partition_ident directive. The partition ID is
-used by other partition manager directives to access this
-partition.
+@code{@value{DIRPREFIX}partition_create} directive, the partition
+ID is stored in a user provided location. Second, the partition
+ID may be obtained later using the @code{@value{DIRPREFIX}partition_ident}
+directive. The partition ID is used by other partition manager directives
+to access this partition.
@ifinfo
@node Acquiring a Buffer, Releasing a Buffer, Obtaining Partition IDs, Partition Manager Operations
@@ -142,7 +144,8 @@ partition.
@subsection Acquiring a Buffer
A buffer can be obtained by calling the
-partition_get_buffer directive. If a buffer is available, then
+@code{@value{DIRPREFIX}partition_get_buffer} directive.
+If a buffer is available, then
it is returned immediately with a successful return code.
Otherwise, an unsuccessful return code is returned immediately
to the caller. Tasks cannot block to wait for a buffer to
@@ -154,7 +157,7 @@ become available.
@subsection Releasing a Buffer
Buffers are returned to a partition's free buffer
-chain with the partition_return_buffer directive. This
+chain with the @code{@value{DIRPREFIX}partition_return_buffer} directive. This
directive returns an error status code if the returned buffer
was not previously allocated from this partition.
@@ -163,7 +166,7 @@ was not previously allocated from this partition.
@end ifinfo
@subsection Deleting a Partition
-The partition_delete directive allows a partition to
+The @code{@value{DIRPREFIX}partition_delete} directive allows a partition to
be removed and returned to RTEMS. When a partition is deleted,
the PTCB for that partition is returned to the PTCB free list.
A partition with buffers still allocated cannot be deleted. Any
@@ -260,8 +263,8 @@ The following partition attribute constants are
defined by RTEMS:
@itemize @bullet
-@item LOCAL - local task (default)
-@item GLOBAL - global task
+@item @code{@value{RPREFIX}LOCAL} - local task (default)
+@item @code{@value{RPREFIX}GLOBAL} - global task
@end itemize
The PTCB for a global partition is allocated on the
@@ -389,7 +392,7 @@ must be transmitted to every node in the system for deletion
from the local copy of the global object table.
The partition must reside on the local node, even if
-the partition was created with the GLOBAL option.
+the partition was created with the @code{@value{RPREFIX}GLOBAL} option.
@page
@ifinfo
diff --git a/doc/user/region.t b/doc/user/region.t
index 3768d94ca2..0f3a53eed9 100644
--- a/doc/user/region.t
+++ b/doc/user/region.t
@@ -100,12 +100,14 @@ are equivalent as long as each attribute appears exactly once in
the component list. An attribute listed as a default is not
required to appear in the attribute list, although it is a good
programming practice to specify default attributes. If all
-defaults are desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
+defaults are desired, the attribute
+@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
specified on this call.
This example demonstrates the attribute_set parameter
needed to create a region with the task priority waiting queue
-discipline. The attribute_set parameter to the region_create
+discipline. The attribute_set parameter to the
+@code{@value{DIRPREFIX}region_create}
directive should be @code{@value{RPREFIX}PRIORITY}.
@ifinfo
@@ -115,7 +117,8 @@ directive should be @code{@value{RPREFIX}PRIORITY}.
In general, an option is built by a bitwise OR of the
desired option components. The set of valid options for the
-region_get_segment directive are listed in the following table:
+@code{@value{DIRPREFIX}region_get_segment} directive are
+listed in the following table:
@itemize @bullet
@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
@@ -128,12 +131,14 @@ are equivalent as long as each option appears exactly once in
the component list. An option listed as a default is not
required to appear in the option list, although it is a good
programming practice to specify default options. If all
-defaults are desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should be
+defaults are desired, the option
+@code{@value{RPREFIX}DEFAULT_OPTIONS} should be
specified on this call.
This example demonstrates the option parameter needed
to poll for a segment. The option parameter passed to the
-region_get_segment directive should be @code{@value{RPREFIX}NO_WAIT}.
+@code{@value{DIRPREFIX}region_get_segment} directive should
+be @code{@value{RPREFIX}NO_WAIT}.
@ifinfo
@node Region Manager Operations, Creating a Region, Building an Option Set, Region Manager
@@ -156,7 +161,7 @@ region_get_segment directive should be @code{@value{RPREFIX}NO_WAIT}.
@end ifinfo
@subsection Creating a Region
-The region_create directive creates a region with the
+The @code{@value{DIRPREFIX}region_create} directive creates a region with the
user-defined name. The user may select FIFO or task priority as
the method for placing waiting tasks in the task wait queue.
RTEMS allocates a Region Control Block (RNCB) from the RNCB free
@@ -185,17 +190,19 @@ When a region is created, RTEMS generates a unique
region ID and assigns it to the created region until it is
deleted. The region ID may be obtained by either of two
methods. First, as the result of an invocation of the
-region_create directive, the region ID is stored in a user
+@code{@value{DIRPREFIX}region_create} directive,
+the region ID is stored in a user
provided location. Second, the region ID may be obtained later
-using the region_ident directive. The region ID is used by
-other region manager directives to access this region.
+using the @code{@value{DIRPREFIX}region_ident} directive.
+The region ID is used by other region manager directives to
+access this region.
@ifinfo
@node Adding Memory to a Region, Acquiring a Segment, Obtaining Region IDs, Region Manager Operations
@end ifinfo
@subsection Adding Memory to a Region
-The region_extend directive may be used to add memory
+The @code{@value{DIRPREFIX}region_extend} directive may be used to add memory
to an existing region. The caller specifies the size in bytes
and starting address of the memory being added.
@@ -209,7 +216,7 @@ region.
@end ifinfo
@subsection Acquiring a Segment
-The region_get_segment directive attempts to acquire
+The @code{@value{DIRPREFIX}region_get_segment} directive attempts to acquire
a segment from a specified region. If the region has enough
available free memory, then a segment is returned successfully
to the caller. When the segment cannot be allocated, one of the
@@ -218,8 +225,8 @@ following situations applies:
@itemize @bullet
@item By default, the calling task will wait forever to acquire the segment.
-@item Specifying the @code{@value{RPREFIX}NO_WAIT} option forces an immediate return
-with an error status code.
+@item Specifying the @code{@value{RPREFIX}NO_WAIT} option forces
+an immediate return with an error status code.
@item Specifying a timeout limits the interval the task will
wait before returning with an error status code.
@@ -236,7 +243,7 @@ the message queue is deleted.
@subsection Releasing a Segment
When a segment is returned to a region by the
-region_return_segment directive, it is merged with its
+@code{@value{DIRPREFIX}region_return_segment} directive, it is merged with its
unallocated neighbors to form the largest possible segment. The
first task on the wait queue is examined to determine if its
segment request can now be satisfied. If so, it is given a
@@ -248,7 +255,7 @@ task's segment request cannot be satisfied.
@end ifinfo
@subsection Obtaining the Size of a Segment
-The region_get_segment_size directive returns the
+The @code{@value{DIRPREFIX}region_get_segment_size} directive returns the
size in bytes of the specified segment. The size returned
includes any "extra" memory included in the segment because of
rounding up to a page size boundary.
@@ -259,7 +266,8 @@ rounding up to a page size boundary.
@subsection Deleting a Region
A region can be removed from the system and returned
-to RTEMS with the region_delete directive. When a region is
+to RTEMS with the @code{@value{DIRPREFIX}region_delete}
+directive. When a region is
deleted, its control block is returned to the RNCB free list. A
region with segments still allocated is not allowed to be
deleted. Any task attempting to do so will be returned an
@@ -349,8 +357,8 @@ segment is constructed in the region.
Specifying @code{@value{RPREFIX}PRIORITY} in attribute_set causes tasks
waiting for a segment to be serviced according to task priority.
Specifying @code{@value{RPREFIX}FIFO} in attribute_set or selecting
-@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} will cause waiting tasks to be serviced in
-First In-First Out order.
+@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} will cause waiting tasks to
+be serviced in First In-First Out order.
The starting_address parameter must be aligned on a
four byte boundary. The page_size parameter must be a multiple
@@ -365,8 +373,8 @@ The following region attribute constants are defined
by RTEMS:
@itemize @bullet
-@item FIFO - tasks wait by FIFO (default)
-@item PRIORITY - tasks wait by priority
+@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
+@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
@end itemize
@page
@@ -555,7 +563,8 @@ the size of maximum segment which is possible for this region@*
This directive obtains a variable size segment from
the region specified by id. The address of the allocated
-segment is returned in segment. The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} components
+segment is returned in segment. The @code{@value{RPREFIX}WAIT}
+and @code{@value{RPREFIX}NO_WAIT} components
of the options parameter are used to specify whether the calling
tasks wish to wait for a segment to become available or return
immediately if no segment is available. For either option, if a
@@ -569,14 +578,16 @@ indicating this fact is returned. If the calling task chooses
to wait for the segment and a segment large enough is not
available, then the calling task is placed on the region's
segment wait queue and blocked. If the region was created with
-the @code{@value{RPREFIX}PRIORITY} option, then the calling task is inserted into the
+the @code{@value{RPREFIX}PRIORITY} option, then the calling
+task is inserted into the
wait queue according to its priority. However, if the region
-was created with the @code{@value{RPREFIX}FIFO} option, then the calling task is
-placed at the rear of the wait queue.
+was created with the @code{@value{RPREFIX}FIFO} option, then the calling
+task is placed at the rear of the wait queue.
The timeout parameter specifies the maximum interval
that a task is willing to wait to obtain a segment. If timeout
-is set to @code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever.
+is set to @code{@value{RPREFIX}NO_TIMEOUT}, then the
+calling task will wait forever.
@subheading NOTES:
diff --git a/doc/user/rtmon.t b/doc/user/rtmon.t
index 6c6c437cfa..1dc8c56d6a 100644
--- a/doc/user/rtmon.t
+++ b/doc/user/rtmon.t
@@ -696,7 +696,7 @@ review." @b{Software Engineering Journal}. May 1991. pp. 116-128.}
@end ifinfo
@subsection Creating a Rate Monotonic Period
-The rate_monotonic_create directive creates a rate
+The @code{@value{DIRPREFIX}rate_monotonic_create} directive creates a rate
monotonic period which is to be used by the calling task to
delineate a period. RTEMS allocates a Period Control Block
(PCB) from the PCB free list. This data structure is used by
@@ -710,11 +710,11 @@ monotonic period.
@end ifinfo
@subsection Manipulating a Period
-The rate_monotonic_period directive is used to
+The @code{@value{DIRPREFIX}rate_monotonic_period} directive is used to
establish and maintain periodic execution utilizing a previously
created rate monotonic period. Once initiated by the
-rate_monotonic_period directive, the period is said to run until
-it either expires or is reinitiated. The state of the rate
+@code{@value{DIRPREFIX}rate_monotonic_period} directive, the period is
+said to run until it either expires or is reinitiated. The state of the rate
monotonic period results in one of the following scenarios:
@itemize @bullet
@@ -728,9 +728,10 @@ and has not expired, it is initiated with a length of period
ticks and the calling task returns immediately.
@item If the rate monotonic period has expired before the task
-invokes the rate_monotonic_period directive, the period will be
-initiated with a length of period ticks and the calling task
+invokes the @code{@value{DIRPREFIX}rate_monotonic_period} directive,
+the period will be initiated with a length of period ticks and the calling task
returns immediately with a timeout error status.
+
@end itemize
@ifinfo
@@ -738,11 +739,12 @@ returns immediately with a timeout error status.
@end ifinfo
@subsection Obtaining a Period's Status
-If the rate_monotonic_period directive is invoked
-with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the current state of the
-specified rate monotonic period will be returned. The following
+If the @code{@value{DIRPREFIX}rate_monotonic_period} directive is invoked
+with a period of @code{@value{RPREFIX}PERIOD_STATUS} ticks, the current
+state of the specified rate monotonic period will be returned. The following
table details the relationship between the period's status and
-the directive status code returned by the rate_monotonic_period
+the directive status code returned by the
+@code{@value{DIRPREFIX}rate_monotonic_period}
directive:
@itemize @bullet
@@ -761,17 +763,17 @@ not alter the state or length of that period.
@end ifinfo
@subsection Canceling a Period
-The rate_monotonic_cancel directive is used to stop
+The @code{@value{DIRPREFIX}rate_monotonic_cancel} directive is used to stop
the period maintained by the specified rate monotonic period.
The period is stopped and the rate monotonic period can be
-reinitiated using the rate_monotonic_period directive.
+reinitiated using the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
@ifinfo
@node Deleting a Rate Monotonic Period, Examples, Canceling a Period, Rate Monotonic Manager Operations
@end ifinfo
@subsection Deleting a Rate Monotonic Period
-The rate_monotonic_delete directive is used to delete
+The @code{@value{DIRPREFIX}rate_monotonic_delete} directive is used to delete
a rate monotonic period. If the period is running and has not
expired, the period is automatically canceled. The rate
monotonic period's control block is returned to the PCB free
@@ -802,7 +804,7 @@ rtems_task Periodic_task()
rtems_id period;
rtems_status_code status;
- name = build_name( 'P', 'E', 'R', 'D' );
+ name = rtems_build_name( 'P', 'E', 'R', 'D' );
(void) rate_monotonic_create( name, &period );
@@ -823,14 +825,16 @@ rtems_task Periodic_task()
The above task creates a rate monotonic period as
part of its initialization. The first time the loop is
-executed, the rate_monotonic_period directive will initiate the
-period for 100 ticks and return immediately. Subsequent
-invocations of the rate_monotonic_period directive will result
+executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
+directive will initiate the period for 100 ticks and return
+immediately. Subsequent invocations of the
+@code{@value{DIRPREFIX}rate_monotonic_period} directive will result
in the task blocking for the remainder of the 100 tick period.
If, for any reason, the body of the loop takes more than 100
-ticks to execute, the rate_monotonic_period directive will
-return the TIMEOUT status. If the above task misses its
-deadline, it will delete the rate monotonic period and itself.
+ticks to execute, the @code{@value{DIRPREFIX}rate_monotonic_period}
+directive will return the @code{@value{RPREFIX}TIMEOUT} status.
+If the above task misses its deadline, it will delete the rate
+monotonic period and itself.
@ifinfo
@node Task with Multiple Periods, Rate Monotonic Manager Directives, Simple Periodic Task, Rate Monotonic Manager Operations
@@ -853,8 +857,8 @@ task Periodic_task()
rtems_id period_1, period_2;
rtems_status_code status;
- name_1 = build_name( 'P', 'E', 'R', '1' );
- name_2 = build_name( 'P', 'E', 'R', '2' );
+ name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
+ name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
(void ) rate_monotonic_create( name_1, &period_1 );
(void ) rate_monotonic_create( name_2, &period_2 );
@@ -897,24 +901,27 @@ task Periodic_task()
The above task creates two rate monotonic periods as
part of its initialization. The first time the loop is
-executed, the rate_monotonic_period directive will initiate the
-period_1 period for 100 ticks and return immediately.
-Subsequent invocations of the rate_monotonic_period directive
+executed, the @code{@value{DIRPREFIX}rate_monotonic_period}
+directive will initiate the period_1 period for 100 ticks
+and return immediately. Subsequent invocations of the
+@code{@value{DIRPREFIX}rate_monotonic_period} directive
for period_1 will result in the task blocking for the remainder
of the 100 tick period. The period_2 period is used to control
the execution time of the two sets of actions within each 100
-tick period established by period_1. The rate_monotonic_cancel(
-period_2 ) call is performed to insure that the period_2 period
+tick period established by period_1. The
+@code{@value{DIRPREFIX}rate_monotonic_cancel( period_2 )}
+call is performed to insure that the period_2 period
does not expire while the task is blocked on the period_1
period. If this cancel operation were not performed, every time
-the rate_monotonic_period( period_1, 40 ) call is executed,
-except for the initial one, a directive status of TIMEOUT is
-returned. It is important to note that every time this call is
-made, the period_1 period will be initiated immediately and the
-task will not block.
+the @code{@value{DIRPREFIX}rate_monotonic_period( period_1, 40 )}
+call is executed, except for the initial one, a directive status
+of @code{@value{RPREFIX}TIMEOUT} is returned. It is important to
+note that every time this call is made, the period_1 period will be
+initiated immediately and the task will not block.
If, for any reason, the task misses any deadline, the
-rate_monotonic_period directive will return the TIMEOUT
+@code{@value{DIRPREFIX}rate_monotonic_period} directive will
+return the @code{@value{RPREFIX}TIMEOUT}
directive status. If the above task misses its deadline, it
will delete the rate monotonic periods and itself.
@@ -1063,7 +1070,7 @@ procedure Rate_Monotonic_Cancel (
This directive cancels the rate monotonic period id.
This period will be reinitiated by the next invocation of
-rate_monotonic_period with id.
+@code{@value{DIRPREFIX}rate_monotonic_period} with id.
@subheading NOTES:
@@ -1228,14 +1235,17 @@ type Rate_Monotonic_Period_Status is
@end example
@end ifset
+@c RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
+
If the period's state is @code{RATE_MONOTONIC_INACTIVE}, both
ticks_since_last_period and ticks_executed_since_last_period
will be set to 0. Otherwise, ticks_since_last_period will
contain the number of clock ticks which have occurred since
-the last invocation of the rtems_rate_monotonic_period directive.
+the last invocation of the
+@code{@value{DIRPREFIX}rate_monotonic_period} directive.
Also in this case, the ticks_executed_since_last_period will indicate
how much processor time the owning task has consumed since the invocation
-of the rtems_rate_monotonic_period directive.
+of the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
@subheading NOTES:
diff --git a/doc/user/schedule.t b/doc/user/schedule.t
index f3f8389cd4..80317082b4 100644
--- a/doc/user/schedule.t
+++ b/doc/user/schedule.t
@@ -166,8 +166,9 @@ entire timeslice.
The final mechanism for altering the RTEMS scheduling
algorithm is called manual round-robin. Manual round-robin is
-invoked by using the task_wake_after directive with a time
-interval of @code{@value{RPREFIX}YIELD_PROCESSOR}. This allows a task to give up the
+invoked by using the @code{@value{DIRPREFIX}task_wake_after}
+directive with a time interval of @code{@value{RPREFIX}YIELD_PROCESSOR}.
+This allows a task to give up the
processor and be immediately returned to the ready chain at the
end of its priority group. If no other tasks of the same
priority are ready to run, then the task does not lose control
@@ -195,8 +196,9 @@ saved or restored for a context switch is located either in the
TCB or on the task's stacks.
Tasks that utilize a numeric coprocessor and are
-created with the @code{@value{RPREFIX}FLOATING_POINT} attribute require additional
-operations during a context switch. These additional operations
+created with the @code{@value{RPREFIX}FLOATING_POINT} attribute
+require additional operations during a context switch. These
+additional operations
are necessary to save and restore the floating point context of
@code{@value{RPREFIX}FLOATING_POINT} tasks. To avoid unnecessary save and restore
operations, the state of the numeric coprocessor is only saved
@@ -288,17 +290,19 @@ blocked, dormant, and non-existent.
@end ifset
A task occupies the non-existent state before a
-task_create has been issued on its behalf. A task enters the
+@code{@value{DIRPREFIX}task_create} has been
+issued on its behalf. A task enters the
non-existent state from any other state in the system when it is
-deleted with the task_delete directive. While a task occupies
+deleted with the @code{@value{DIRPREFIX}task_delete}
+directive. While a task occupies
this state it does not have a TCB or a task ID assigned to it;
therefore, no other tasks in the system may reference this task.
-When a task is created via the task_create directive
+When a task is created via the @code{@value{DIRPREFIX}task_create} directive
it enters the dormant state. This state is not entered through
any other means. Although the task exists in the system, it
cannot actively compete for system resources. It will remain in
-the dormant state until it is started via the task_start
+the dormant state until it is started via the @code{@value{DIRPREFIX}task_start}
directive, at which time it enters the ready state. The task is
now permitted to be scheduled for the processor and to compete
for other system resources.
@@ -308,36 +312,36 @@ unable to be scheduled to run. A running task may block itself
or be blocked by other tasks in the system. The running task
blocks itself through voluntary operations that cause the task
to wait. The only way a task can block a task other than itself
-is with the task_suspend directive. A task enters the blocked
-state due to any of the following conditions:
+is with the @code{@value{DIRPREFIX}task_suspend} directive.
+A task enters the blocked state due to any of the following conditions:
@itemize @bullet
-@item A task issues a task_suspend directive which blocks
-either itself or another task in the system.
+@item A task issues a @code{@value{DIRPREFIX}task_suspend} directive
+which blocks either itself or another task in the system.
-@item The running task issues a message_queue_receive
+@item The running task issues a @code{@value{DIRPREFIX}message_queue_receive}
directive with the wait option and the message queue is empty.
-@item The running task issues an event_receive directive with
-the wait option and the currently pending events do not satisfy
-the request.
+@item The running task issues an @code{@value{DIRPREFIX}event_receive}
+directive with the wait option and the currently pending events do not
+satisfy the request.
-@item The running task issues a semaphore_obtain directive
-with the wait option and the requested semaphore is unavailable.
+@item The running task issues a @code{@value{DIRPREFIX}semaphore_obtain}
+directive with the wait option and the requested semaphore is unavailable.
-@item The running task issues a task_wake_after directive
-which blocks the task for the given time interval. If the time
+@item The running task issues a @code{@value{DIRPREFIX}task_wake_after}
+directive which blocks the task for the given time interval. If the time
interval specified is zero, the task yields the processor and
remains in the ready state.
-@item The running task issues a task_wake_when directive which
-blocks the task until the requested date and time arrives.
+@item The running task issues a @code{@value{DIRPREFIX}task_wake_when}
+directive which blocks the task until the requested date and time arrives.
-@item The running task issues a region_get_segment directive
-with the wait option and there is not an available segment large
+@item The running task issues a @code{@value{DIRPREFIX}region_get_segment}
+directive with the wait option and there is not an available segment large
enough to satisfy the task's request.
-@item The running task issues a rate_monotonic_period
+@item The running task issues a @code{@value{DIRPREFIX}rate_monotonic_period}
directive and must wait for the specified rate monotonic period
to conclude.
@end itemize
@@ -356,36 +360,37 @@ to any of the following conditions:
@itemize @bullet
-@item A running task issues a task_resume directive for a task
-that is suspended and the task is not blocked waiting on any
-resource.
+@item A running task issues a @code{@value{DIRPREFIX}task_resume}
+directive for a task that is suspended and the task is not blocked
+waiting on any resource.
-@item A running task issues a message_queue_send,
-message_queue_broadcast, or a message_queue_urgent directive
+@item A running task issues a @code{@value{DIRPREFIX}message_queue_send},
+@code{@value{DIRPREFIX}message_queue_broadcast}, or a
+@code{@value{DIRPREFIX}message_queue_urgent} directive
which posts a message to the queue on which the blocked task is
waiting.
-@item A running task issues an event_send directive which
-sends an event condition to a task which is blocked waiting on
-that event condition.
+@item A running task issues an @code{@value{DIRPREFIX}event_send}
+directive which sends an event condition to a task which is blocked
+waiting on that event condition.
-@item A running task issues a semaphore_release directive
-which releases the semaphore on which the blocked task is
+@item A running task issues a @code{@value{DIRPREFIX}semaphore_release}
+directive which releases the semaphore on which the blocked task is
waiting.
@item A timeout interval expires for a task which was blocked
-by a call to the task_wake_after directive.
+by a call to the @code{@value{DIRPREFIX}task_wake_after} directive.
@item A timeout period expires for a task which blocked by a
-call to the task_wake_when directive.
+call to the @code{@value{DIRPREFIX}task_wake_when} directive.
-@item A running task issues a region_return_segment directive
-which releases a segment to the region on which the blocked task
+@item A running task issues a @code{@value{DIRPREFIX}region_return_segment}
+directive which releases a segment to the region on which the blocked task
is waiting and a resulting segment is large enough to satisfy
the task's request.
@item A rate monotonic period expires for a task which blocked
-by a call to the rate_monotonic_period directive.
+by a call to the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
@item A timeout interval expires for a task which was blocked
waiting on a message, event, semaphore, or segment with a
@@ -395,8 +400,8 @@ timeout specified.
message queue, a semaphore, or a region on which the blocked
task is waiting.
-@item A running task issues a task_restart directive for the
-blocked task.
+@item A running task issues a @code{@value{DIRPREFIX}task_restart}
+directive for the blocked task.
@item The running task, with its preemption mode enabled, may
be made ready by issuing any of the directives that may unblock
diff --git a/doc/user/sem.t b/doc/user/sem.t
index 7ce4fb961a..9697da82e4 100644
--- a/doc/user/sem.t
+++ b/doc/user/sem.t
@@ -53,8 +53,10 @@ semaphore manager are:
@end ifinfo
A semaphore can be viewed as a protected variable
-whose value can be modified only with the semaphore_create,
-semaphore_obtain, and semaphore_release directives. RTEMS
+whose value can be modified only with the
+@code{@value{DIRPREFIX}semaphore_create},
+@code{@value{DIRPREFIX}semaphore_obtain}, and
+@code{@value{DIRPREFIX}semaphore_release} directives. RTEMS
supports both binary and counting semaphores. A binary semaphore
is restricted to values of zero or one, while a counting
semaphore can assume any non-negative integer value.
@@ -65,29 +67,30 @@ mutual exclusion for a critical section in user code. In this
instance, the semaphore would be created with an initial count
of one to indicate that no task is executing the critical
section of code. Upon entry to the critical section, a task
-must issue the semaphore_obtain directive to prevent other tasks
-from entering the critical section. Upon exit from the critical
-section, the task must issue the semaphore_release directive to
+must issue the @code{@value{DIRPREFIX}semaphore_obtain}
+directive to prevent other tasks from entering the critical section.
+Upon exit from the critical section, the task must issue the
+@code{@value{DIRPREFIX}semaphore_release} directive to
allow another task to execute the critical section.
A counting semaphore can be used to control access to
a pool of two or more resources. For example, access to three
printers could be administered by a semaphore created with an
initial count of three. When a task requires access to one of
-the printers, it issues the semaphore_obtain directive to obtain
-access to a printer. If a printer is not currently available,
-the task can wait for a printer to become available or return
+the printers, it issues the @code{@value{DIRPREFIX}semaphore_obtain}
+directive to obtain access to a printer. If a printer is not currently
+available, the task can wait for a printer to become available or return
immediately. When the task has completed printing, it should
-issue the semaphore_release directive to allow other tasks
-access to the printer.
+issue the @code{@value{DIRPREFIX}semaphore_release}
+directive to allow other tasks access to the printer.
Task synchronization may be achieved by creating a
semaphore with an initial count of zero. One task waits for the
-arrival of another task by issuing a semaphore_obtain directive
-when it reaches a synchronization point. The other task
-performs a corresponding semaphore_release operation when it
-reaches its synchronization point, thus unblocking the pending
-task.
+arrival of another task by issuing a @code{@value{DIRPREFIX}semaphore_obtain}
+directive when it reaches a synchronization point. The other task
+performs a corresponding @code{@value{DIRPREFIX}semaphore_release}
+operation when it reaches its synchronization point, thus unblocking
+the pending task.
@ifinfo
@node Nested Resource Access, Priority Inversion, Semaphore Manager Background, Semaphore Manager Background
@@ -103,10 +106,12 @@ execute again.
RTEMS addresses this problem by allowing the task
holding the binary semaphore to obtain the same binary semaphore
-multiple times in a nested manner. Each semaphore_obtain must
-be accompanied with a semaphore_release. The semaphore will
+multiple times in a nested manner. Each
+@code{@value{DIRPREFIX}semaphore_obtain} must be accompanied with a
+@code{@value{DIRPREFIX}semaphore_release}. The semaphore will
only be made available for acquisition by other tasks when the
-outermost semaphore_obtain is matched with a semaphore_release.
+outermost @code{@value{DIRPREFIX}semaphore_obtain} is matched with
+a @code{@value{DIRPREFIX}semaphore_release}.
@ifinfo
@@ -212,16 +217,28 @@ of the desired attribute components. The following table lists
the set of valid semaphore attributes:
@itemize @bullet
-@item FIFO - tasks wait by FIFO (default)
-@item PRIORITY - tasks wait by priority
-@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
-@item COUNTING_SEMAPHORE - no restriction on values
-@item NO_INHERIT_PRIORITY - do not use priority inheritance (default)
-@item INHERIT_PRIORITY - use priority inheritance
-@item PRIORITY_CEILING - use priority ceiling
-@item NO_PRIORITY_CEILING - do not use priority ceiling (default)
-@item LOCAL - local task (default)
-@item GLOBAL - global task
+@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
+
+@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
+
+@item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to
+0 and 1 (default)
+
+@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
+
+@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
+inheritance (default)
+
+@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
+
+@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
+
+@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
+ceiling (default)
+
+@item @code{@value{RPREFIX}LOCAL} - local task (default)
+
+@item @code{@value{RPREFIX}GLOBAL} - global task
@end itemize
Attribute values are specifically designed to be
@@ -230,13 +247,14 @@ are equivalent as long as each attribute appears exactly once in
the component list. An attribute listed as a default is not
required to appear in the attribute list, although it is a good
programming practice to specify default attributes. If all
-defaults are desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
+defaults are desired, the attribute
+@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
specified on this call.
This example demonstrates the attribute_set parameter
needed to create a local semaphore with the task priority
waiting queue discipline. The attribute_set parameter passed to
-the semaphore_create directive could be either
+the @code{@value{DIRPREFIX}semaphore_create} directive could be either
@code{@value{RPREFIX}PRIORITY} or
@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}PRIORITY}.
The attribute_set parameter can be set to @code{@value{RPREFIX}PRIORITY}
@@ -252,7 +270,8 @@ attribute_set parameter would be
In general, an option is built by a bitwise OR of the
desired option components. The set of valid options for the
-semaphore_obtain directive are listed in the following table:
+@code{@value{DIRPREFIX}semaphore_obtain} directive are listed
+in the following table:
@itemize @bullet
@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
@@ -270,7 +289,8 @@ specified on this call.
This example demonstrates the option parameter needed
to poll for a semaphore. The option parameter passed to the
-semaphore_obtain directive should be @code{@value{RPREFIX}NO_WAIT}.
+@code{@value{DIRPREFIX}semaphore_obtain}
+directive should be @code{@value{RPREFIX}NO_WAIT}.
@ifinfo
@node Semaphore Manager Operations, Creating a Semaphore, Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager
@@ -291,7 +311,7 @@ semaphore_obtain directive should be @code{@value{RPREFIX}NO_WAIT}.
@end ifinfo
@subsection Creating a Semaphore
-The semaphore_create directive creates a binary or
+The @code{@value{DIRPREFIX}semaphore_create} directive creates a binary or
counting semaphore with a user-specified name as well as an
initial count. If a binary semaphore is created with a count of
zero (0) to indicate that it has been allocated, then the task
@@ -317,9 +337,10 @@ When a semaphore is created, RTEMS generates a unique
semaphore ID and assigns it to the created semaphore until it is
deleted. The semaphore ID may be obtained by either of two
methods. First, as the result of an invocation of the
-semaphore_create directive, the semaphore ID is stored in a user
-provided location. Second, the semaphore ID may be obtained
-later using the semaphore_ident directive. The semaphore ID is
+@code{@value{DIRPREFIX}semaphore_create} directive, the
+semaphore ID is stored in a user provided location. Second,
+the semaphore ID may be obtained later using the
+@code{@value{DIRPREFIX}semaphore_ident} directive. The semaphore ID is
used by other semaphore manager directives to access this
semaphore.
@@ -328,9 +349,9 @@ semaphore.
@end ifinfo
@subsection Acquiring a Semaphore
-The semaphore_obtain directive is used to acquire the
+The @code{@value{DIRPREFIX}semaphore_obtain} directive is used to acquire the
specified semaphore. A simplified version of the
-semaphore_obtain directive can be described as follows:
+@code{@value{DIRPREFIX}semaphore_obtain} directive can be described as follows:
@example
if semaphore's count is greater than zero
@@ -373,9 +394,9 @@ be elevated.
@end ifinfo
@subsection Releasing a Semaphore
-The semaphore_release directive is used to release
+The @code{@value{DIRPREFIX}semaphore_release} directive is used to release
the specified semaphore. A simplified version of the
-semaphore_release directive can be described as follows:
+@code{@value{DIRPREFIX}semaphore_release} directive can be described as follows:
@example
if no tasks are waiting on this semaphore
@@ -388,15 +409,15 @@ return SUCCESSFUL
If this is the outermost release of a binary
semaphore that uses priority inheritance or priority ceiling and
the task does not currently hold any other binary semaphores,
-then the task performing the semaphore_release will have its
-priority restored to its normal value.
+then the task performing the @code{@value{DIRPREFIX}semaphore_release}
+will have its priority restored to its normal value.
@ifinfo
@node Deleting a Semaphore, Semaphore Manager Directives, Releasing a Semaphore, Semaphore Manager Operations
@end ifinfo
@subsection Deleting a Semaphore
-The semaphore_delete directive removes a semaphore
+The @code{@value{DIRPREFIX}semaphore_delete} directive removes a semaphore
from the system and frees its control block. A semaphore can be
deleted by any local task that knows the semaphore's ID. As a
result of this directive, all tasks blocked waiting to acquire
@@ -492,16 +513,28 @@ The following semaphore attribute constants are
defined by RTEMS:
@itemize @bullet
-@item FIFO - tasks wait by FIFO (default)
-@item PRIORITY - tasks wait by priority
-@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
-@item COUNTING_SEMAPHORE - no restriction on values
-@item NO_INHERIT_PRIORITY - do not use priority inheritance (default)
-@item INHERIT_PRIORITY - use priority inheritance
-@item PRIORITY_CEILING - use priority ceiling
-@item NO_PRIORITY_CEILING - do not use priority ceiling (default)
-@item LOCAL - local task (default)
-@item GLOBAL - global task
+@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
+
+@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
+
+@item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to
+0 and 1 (default)
+
+@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
+
+@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
+inheritance (default)
+
+@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
+
+@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
+
+@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
+ceiling (default)
+
+@item @code{@value{RPREFIX}LOCAL} - local task (default)
+
+@item @code{@value{RPREFIX}GLOBAL} - global task
@end itemize
Semaphores should not be made global unless remote
@@ -631,7 +664,7 @@ must be transmitted to every node in the system for deletion
from the local copy of the global object table.
The semaphore must reside on the local node, even if
-the semaphore was created with the GLOBAL option.
+the semaphore was created with the @code{@value{RPREFIX}GLOBAL} option.
Proxies, used to represent remote tasks, are
reclaimed when the semaphore is deleted.
diff --git a/doc/user/signal.t b/doc/user/signal.t
index 3f37a910d2..e11fa474a1 100644
--- a/doc/user/signal.t
+++ b/doc/user/signal.t
@@ -108,9 +108,11 @@ bitwise OR and addition operations are equivalent as long as
each signal appears exactly once in the component list.
This example demonstrates the signal parameter used
-when sending the signal set consisting of
-@code{@value{RPREFIX}SIGNAL_6}, @code{@value{RPREFIX}SIGNAL_15}, and @code{@value{RPREFIX}SIGNAL_31}.
-The signal parameter provided to the signal_send directive should be
+when sending the signal set consisting of
+@code{@value{RPREFIX}SIGNAL_6},
+@code{@value{RPREFIX}SIGNAL_15}, and
+@code{@value{RPREFIX}SIGNAL_31}. The signal parameter provided
+to the @code{@value{DIRPREFIX}signal_send} directive should be
@code{@value{RPREFIX}SIGNAL_6 @value{OR}
@value{RPREFIX}SIGNAL_15 @value{OR} @value{RPREFIX}SIGNAL_31}.
@@ -161,7 +163,8 @@ defaults are desired, the mode DEFAULT_MODES should be specified
on this call.
This example demonstrates the mode parameter used
-with the signal_catch to establish an ASR which executes at
+with the @code{@value{DIRPREFIX}signal_catch}
+to establish an ASR which executes at
interrupt level three and is non-preemptible. The mode should
be set to
@code{@value{RPREFIX}INTERRUPT_LEVEL(3) @value{OR} @value{RPREFIX}NO_PREEMPT}
@@ -185,27 +188,28 @@ desired processor mode and interrupt level.
@end ifinfo
@subsection Establishing an ASR
-The signal_catch directive establishes an ASR for the
+The @code{@value{DIRPREFIX}signal_catch} directive establishes an ASR for the
calling task. The address of the ASR and its execution mode are
specified to this directive. The ASR's mode is distinct from
the task's mode. For example, the task may allow preemption,
while that task's ASR may have preemption disabled. Until a
-task calls signal_catch the first time, its ASR is invalid, and
-no signal sets can be sent to the task.
+task calls @code{@value{DIRPREFIX}signal_catch} the first time,
+its ASR is invalid, and no signal sets can be sent to the task.
A task may invalidate its ASR and discard all pending
-signals by calling signal_catch with a value of NULL for the
-ASR's address. When a task's ASR is invalid, new signal sets
-sent to this task are discarded.
+signals by calling @code{@value{DIRPREFIX}signal_catch}
+with a value of NULL for the ASR's address. When a task's
+ASR is invalid, new signal sets sent to this task are discarded.
-A task may disable ASR processing (NO_ASR) via the
+A task may disable ASR processing (@code{@value{RPREFIX}NO_ASR}) via the
task_mode directive. When a task's ASR is disabled, the signals
sent to it are left pending to be processed later when the ASR
is enabled.
Any directive that can be called from a task can also
be called from an ASR. A task is only allowed one active ASR.
-Thus, each call to signal_catch replaces the previous one.
+Thus, each call to @code{@value{DIRPREFIX}signal_catch}
+replaces the previous one.
Normally, signal processing is disabled for the ASR's
execution mode, but if signal processing is enabled for the ASR,
@@ -216,9 +220,10 @@ the ASR must be reentrant.
@end ifinfo
@subsection Sending a Signal Set
-The signal_send directive allows both tasks and ISRs
-to send signals to a target task. The target task and a set of
-signals are specified to the signal_send directive. The sending
+The @code{@value{DIRPREFIX}signal_send} directive allows both
+tasks and ISRs to send signals to a target task. The target task and
+a set of signals are specified to the
+@code{@value{DIRPREFIX}signal_send} directive. The sending
of a signal to a task has no effect on the execution state of
that task. If the task is not the currently running task, then
the signals are left pending and processed by the task's ASR the
diff --git a/doc/user/task.t b/doc/user/task.t
index 5bab8fd463..84497e2f2d 100644
--- a/doc/user/task.t
+++ b/doc/user/task.t
@@ -73,13 +73,12 @@ by the task manager are:
@subsection Task Definition
-Many definitions of a task have been proposed in computer
-literature. Unfortunately, none of these definitions
-encompasses all facets of the concept in a manner which is
-operating system independent. Several of the more common
-definitions are provided to enable each user to select a
-definition which best matches their own experience and
-understanding of the task concept:
+Many definitions of a task have been proposed in computer literature.
+Unfortunately, none of these definitions encompasses all facets of the
+concept in a manner which is operating system independent. Several of the
+more common definitions are provided to enable each user to select a
+definition which best matches their own experience and understanding of the
+task concept:
@itemize @bullet
@item a "dispatchable" unit.
@@ -193,35 +192,34 @@ A task's mode is a combination of the following four components:
It is used to modify RTEMS' scheduling process and to alter the
execution environment of the task.
-The preemption component allows a task to determine when control
-of the processor is relinquished. If preemption is disabled
-(@code{@value{RPREFIX}NO_PREEMPT}), the task will retain control of the processor as
-long as it is in the executing state -- even if a higher
-priority task is made ready. If preemption is enabled (@code{@value{RPREFIX}PREEMPT})
-and a higher priority task is made ready, then the processor
-will be taken away from the current task immediately and given
-to the higher priority task.
-
-The timeslicing component is used by the RTEMS scheduler to
-determine how the processor is allocated to tasks of equal
-priority. If timeslicing is enabled (@code{@value{RPREFIX}TIMESLICE}), then RTEMS
-will limit the amount of time the task can execute before the
-processor is allocated to another ready task of equal priority.
-The length of the timeslice is application dependent and
-specified in the Configuration Table. If timeslicing is
-disabled (@code{@value{RPREFIX}NO_TIMESLICE}), then the task will be allowed to
-execute until a task of higher priority is made ready. If
-@code{@value{RPREFIX}NO_PREEMPT} is selected, then the timeslicing component is
-ignored by the scheduler.
-
-The asynchronous signal processing component is used to
-determine when received signals are to be processed by the task.
- If signal processing is enabled (@code{@value{RPREFIX}ASR}), then signals sent to the
-task will be processed the next time the task executes. If
-signal processing is disabled (@code{@value{RPREFIX}NO_ASR}), then all signals
-received by the task will remain posted until signal processing
-is enabled. This component affects only tasks which have
-established a routine to process asynchronous signals.
+The preemption component allows a task to determine when control of the
+processor is relinquished. If preemption is disabled
+(@code{@value{RPREFIX}NO_PREEMPT}), the task will retain control of the
+processor as long as it is in the executing state -- even if a higher
+priority task is made ready. If preemption is enabled
+(@code{@value{RPREFIX}PREEMPT}) and a higher priority task is made ready,
+then the processor will be taken away from the current task immediately and
+given to the higher priority task.
+
+The timeslicing component is used by the RTEMS scheduler to determine how
+the processor is allocated to tasks of equal priority. If timeslicing is
+enabled (@code{@value{RPREFIX}TIMESLICE}), then RTEMS will limit the amount
+of time the task can execute before the processor is allocated to another
+ready task of equal priority. The length of the timeslice is application
+dependent and specified in the Configuration Table. If timeslicing is
+disabled (@code{@value{RPREFIX}NO_TIMESLICE}), then the task will be
+allowed to execute until a task of higher priority is made ready. If
+@code{@value{RPREFIX}NO_PREEMPT} is selected, then the timeslicing
+component is ignored by the scheduler.
+
+The asynchronous signal processing component is used to determine when
+received signals are to be processed by the task.
+If signal processing is enabled (@code{@value{RPREFIX}ASR}), then signals
+sent to the task will be processed the next time the task executes. If
+signal processing is disabled (@code{@value{RPREFIX}NO_ASR}), then all
+signals received by the task will remain posted until signal processing is
+enabled. This component affects only tasks which have established a
+routine to process asynchronous signals.
The interrupt level component is used to determine which
interrupts will be enabled when the task is executing.
@@ -274,56 +272,54 @@ single argument as an index into an array of parameter blocks.
@end ifinfo
@subsection Floating Point Considerations
-Creating a task with the @code{@value{RPREFIX}FLOATING_POINT} 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 and restoring the context of a @code{@value{RPREFIX}FLOATING_POINT} task takes
-longer than that of a @code{@value{RPREFIX}NO_FLOATING_POINT} task because of the
-relatively large amount of time required for the numeric
-coprocessor to save or restore its computational state.
-
-Since RTEMS was designed specifically for embedded military
-applications which are floating point intensive, the executive
-is optimized to avoid unnecessarily saving and restoring the
-state of the numeric coprocessor. The state of the numeric
-coprocessor is only saved when a @code{@value{RPREFIX}FLOATING_POINT} task is
-dispatched and that task was not the last task to utilize the
-coprocessor. In a system with only one @code{@value{RPREFIX}FLOATING_POINT} task, the
-state of the numeric coprocessor will never be saved or
-restored.
-
-Although the overhead imposed by @code{@value{RPREFIX}FLOATING_POINT} tasks is
-minimal, some applications may wish to completely avoid the
-overhead associated with @code{@value{RPREFIX}FLOATING_POINT} tasks and still utilize
-a numeric coprocessor. By preventing a task from being
-preempted while performing a sequence of floating point
-operations, a @code{@value{RPREFIX}NO_FLOATING_POINT} task can utilize the numeric
-coprocessor without incurring the overhead of a @code{@value{RPREFIX}FLOATING_POINT}
-context switch. This approach also avoids the allocation of a
-floating point context area. However, if this approach is taken
-by the application designer, NO tasks should be created as
-@code{@value{RPREFIX}FLOATING_POINT} tasks. Otherwise, the floating point context
-will not be correctly maintained because RTEMS assumes that the
-state of the numeric coprocessor will not be altered by
-@code{@value{RPREFIX}NO_FLOATING_POINT} tasks.
+Creating a task with the @code{@value{RPREFIX}FLOATING_POINT} 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
+and restoring the context of a @code{@value{RPREFIX}FLOATING_POINT} task
+takes longer than that of a @code{@value{RPREFIX}NO_FLOATING_POINT} task
+because of the relatively large amount of time required for the numeric
+coprocessor to save or restore its computational state.
+
+Since RTEMS was designed specifically for embedded military applications
+which are floating point intensive, the executive is optimized to avoid
+unnecessarily saving and restoring the state of the numeric coprocessor.
+The state of the numeric coprocessor is only saved when a
+@code{@value{RPREFIX}FLOATING_POINT} task is dispatched and that task was
+not the last task to utilize the coprocessor. In a system with only one
+@code{@value{RPREFIX}FLOATING_POINT} task, the state of the numeric
+coprocessor will never be saved or restored.
+
+Although the overhead imposed by @code{@value{RPREFIX}FLOATING_POINT} tasks
+is minimal, some applications may wish to completely avoid the overhead
+associated with @code{@value{RPREFIX}FLOATING_POINT} tasks and still
+utilize a numeric coprocessor. By preventing a task from being preempted
+while performing a sequence of floating point operations, a
+@code{@value{RPREFIX}NO_FLOATING_POINT} task can utilize the numeric
+coprocessor without incurring the overhead of a
+@code{@value{RPREFIX}FLOATING_POINT} context switch. This approach also
+avoids the allocation of a floating point context area. However, if this
+approach is taken by the application designer, NO tasks should be created
+as @code{@value{RPREFIX}FLOATING_POINT} tasks. Otherwise, the floating
+point context will not be correctly maintained because RTEMS assumes that
+the state of the numeric coprocessor will not be altered by
+@code{@value{RPREFIX}NO_FLOATING_POINT} tasks.
If the supported processor type does not have hardware floating
-capabilities or a standard numeric coprocessor, RTEMS will not
-provide built-in support for hardware floating point on that
-processor. In this case, all tasks are considered
-@code{@value{RPREFIX}NO_FLOATING_POINT} whether created as @code{@value{RPREFIX}FLOATING_POINT} or
-@code{@value{RPREFIX}NO_FLOATING_POINT} tasks. A floating point emulation software
-library must be utilized for floating point operations.
-
-On some processors, it is possible to disable the floating point
-unit dynamically. If this capability is supported by the target
-processor, then RTEMS will utilize this capability to enable the
-floating point unit only for tasks which are created with the
-@code{@value{RPREFIX}FLOATING_POINT} attribute. The consequence of a
-@code{@value{RPREFIX}NO_FLOATING_POINT} task attempting to access the floating point
-unit is CPU dependent but will i general result in an exception
-condition.
+capabilities or a standard numeric coprocessor, RTEMS will not provide
+built-in support for hardware floating point on that processor. In this
+case, all tasks are considered @code{@value{RPREFIX}NO_FLOATING_POINT}
+whether created as @code{@value{RPREFIX}FLOATING_POINT} or
+@code{@value{RPREFIX}NO_FLOATING_POINT} tasks. A floating point emulation
+software library must be utilized for floating point operations.
+
+On some processors, it is possible to disable the floating point unit
+dynamically. If this capability is supported by the target processor, then
+RTEMS will utilize this capability to enable the floating point unit only
+for tasks which are created with the @code{@value{RPREFIX}FLOATING_POINT}
+attribute. The consequence of a @code{@value{RPREFIX}NO_FLOATING_POINT}
+task attempting to access the floating point unit is CPU dependent but will
+generally result in an exception condition.
@ifinfo
@node Building a Task's Attribute Set, Building a Mode and Mask, Floating Point Considerations, Task Manager Background
@@ -438,57 +434,53 @@ listed below:
<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
<TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
<TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
-<TR><TD ALIGN=center>PREEMPT</TD>
- <TD ALIGN=center>PREEMPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
+ <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
<TD ALIGN=center>enables preemption</TD></TR>
-<TR><TD ALIGN=center>NO_PREEMPT</TD>
- <TD ALIGN=center>PREEMPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
+ <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
<TD ALIGN=center>disables preemption</TD></TR>
-<TR><TD ALIGN=center>NO_TIMESLICE</TD>
- <TD ALIGN=center>TIMESLICE_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
+ <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
<TD ALIGN=center>disables timeslicing</TD></TR>
-<TR><TD ALIGN=center>TIMESLICE</TD>
- <TD ALIGN=center>TIMESLICE_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
+ <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
<TD ALIGN=center>enables timeslicing</TD></TR>
-<TR><TD ALIGN=center>ASR</TD>
- <TD ALIGN=center>ASR_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
+ <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
<TD ALIGN=center>enables ASR processing</TD></TR>
-<TR><TD ALIGN=center>NO_ASR</TD>
- <TD ALIGN=center>ASR_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
+ <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
<TD ALIGN=center>disables ASR processing</TD></TR>
-<TR><TD ALIGN=center>INTERRUPT_LEVEL(0)</TD>
- <TD ALIGN=center>INTERRUPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
+ <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
<TD ALIGN=center>enables all interrupts</TD></TR>
-<TR><TD ALIGN=center>INTERRUPT_LEVEL(n)</TD>
- <TD ALIGN=center>INTERRUPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
+ <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
<TD ALIGN=center>sets interrupts level n</TD></TR>
</TABLE>
</CENTER>
@end html
@end ifset
-
-
-
-Mode values are specifically designed to be mutually exclusive,
-therefore bitwise OR and addition operations are equivalent as
-long as each mode appears exactly once in the component list. A
-mode component listed as a default is not required to appear in
-the mode component list, although it is a good programming
-practice to specify default components. If all defaults are
-desired, the mode @code{@value{RPREFIX}DEFAULT_MODES} and the mask @code{@value{RPREFIX}ALL_MODE_MASKS}
-should be used.
-
-The following example demonstrates the mode and mask parameters
-used with the task_mode directive to place a task at interrupt
-level 3 and make it non-preemptible. The mode should be set to
-@code{@value{RPREFIX}INTERRUPT_LEVEL(3)
-@value{OR} @value{RPREFIX}NO_PREEMPT} to indicate the desired
-preemption mode and interrupt level, while the mask parameter
-should be set to
-@code{@value{RPREFIX}INTERRUPT_MASK @value{OR} @value{RPREFIX}NO_PREEMPT_MASK}
-to indicate that the calling task's interrupt level and preemption mode are
-being altered.
+Mode values are specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as each mode
+appears exactly once in the component list. A mode component listed as a
+default is not required to appear in the mode component list, although it
+is a good programming practice to specify default components. If all
+defaults are desired, the mode @code{@value{RPREFIX}DEFAULT_MODES} and the
+mask @code{@value{RPREFIX}ALL_MODE_MASKS} should be used.
+
+The following example demonstrates the mode and mask parameters used with
+the @code{@value{DIRPREFIX}task_mode}
+directive to place a task at interrupt level 3 and make it
+non-preemptible. The mode should be set to
+@code{@value{RPREFIX}INTERRUPT_LEVEL(3) @value{OR}
+@value{RPREFIX}NO_PREEMPT} to indicate the desired preemption mode and
+interrupt level, while the mask parameter should be set to
+@code{@value{RPREFIX}INTERRUPT_MASK @value{OR}
+@value{RPREFIX}NO_PREEMPT_MASK} to indicate that the calling task's
+interrupt level and preemption mode are being altered.
@ifinfo
@node Task Manager Operations, Creating Tasks, Building a Mode and Mask, Task Manager
@@ -515,7 +507,8 @@ being altered.
@end ifinfo
@subsection Creating Tasks
-The task_create directive creates a task by allocating a task
+The @code{@value{DIRPREFIX}task_create}
+directive creates a task by allocating a task
control block, assigning the task a user-specified name,
allocating it a stack and floating point context area, setting a
user-specified initial priority, setting a user-specified
@@ -531,9 +524,11 @@ execute in the most privileged mode of the processor.
When a task is created, RTEMS generates a unique task ID and
assigns it to the created task until it is deleted. The task ID
may be obtained by either of two methods. First, as the result
-of an invocation of the task_create directive, the task ID is
+of an invocation of the @code{@value{DIRPREFIX}task_create}
+directive, the task ID is
stored in a user provided location. Second, the task ID may be
-obtained later using the task_ident directive. The task ID is
+obtained later using the @code{@value{DIRPREFIX}task_ident}
+directive. The task ID is
used by other directives to manipulate this task.
@ifinfo
@@ -541,14 +536,16 @@ used by other directives to manipulate this task.
@end ifinfo
@subsection Starting and Restarting Tasks
-The task_start directive is used to place a dormant task in the
+The @code{@value{DIRPREFIX}task_start}
+directive is used to place a dormant task in the
ready state. This enables the task to compete, based on its
current priority, for the processor and other system resources.
Any actions, such as suspension or change of priority, performed
on a task prior to starting it are nullified when the task is
started.
-With the task_start directive the user specifies the task's
+With the @code{@value{DIRPREFIX}task_start}
+directive the user specifies the task's
starting address and argument. The argument is used to
communicate some startup information to the task. As part of
this directive, RTEMS initializes the task's stack based upon
@@ -556,7 +553,8 @@ the task's initial execution mode and start address. The
starting argument is passed to the task in accordance with the
target processor's calling convention.
-The task_restart directive restarts a task at its initial
+The @code{@value{DIRPREFIX}task_restart}
+directive restarts a task at its initial
starting address with its original priority and execution mode,
but with a possibly different argument. The new argument may be
used to distinguish between the original invocation of the task
@@ -573,13 +571,16 @@ restarted). All restarted tasks are placed in the ready state.
@end ifinfo
@subsection Suspending and Resuming Tasks
-The task_suspend directive is used to place either the caller or
+The @code{@value{DIRPREFIX}task_suspend}
+directive is used to place either the caller or
another task into a suspended state. The task remains suspended
-until a task_resume directive is issued. This implies that a
+until a @code{@value{DIRPREFIX}task_resume}
+directive is issued. This implies that a
task may be suspended as well as blocked waiting either to
acquire a resource or for the expiration of a timer.
-The task_resume directive is used to remove another task from
+The @code{@value{DIRPREFIX}task_resume}
+directive is used to remove another task from
the suspended state. If the task is not also blocked, resuming
it will place it in the ready state, allowing it to once again
compete for the processor and resources. If the task was
@@ -594,15 +595,17 @@ task which is not suspended is considered an error.
@end ifinfo
@subsection Delaying the Currently Executing Task
-The task_wake_after directive creates a sleep timer which allows
-a task to go to sleep for a specified interval. The task is
-blocked until the delay interval has elapsed, at which time the
-task is unblocked. A task calling the task_wake_after directive
-with a delay interval of @code{@value{RPREFIX}YIELD_PROCESSOR} ticks will yield the
-processor to any other ready task of equal or greater priority
-and remain ready to execute.
-
-The task_wake_when directive creates a sleep timer which allows
+The @code{@value{DIRPREFIX}task_wake_after} directive creates a sleep timer
+which allows a task to go to sleep for a specified interval. The task is
+blocked until the delay interval has elapsed, at which time the task is
+unblocked. A task calling the @code{@value{DIRPREFIX}task_wake_after}
+directive with a delay
+interval of @code{@value{RPREFIX}YIELD_PROCESSOR} ticks will yield the
+processor to any other ready task of equal or greater priority and remain
+ready to execute.
+
+The @code{@value{DIRPREFIX}task_wake_when}
+directive creates a sleep timer which allows
a task to go to sleep until a specified date and time. The
calling task is blocked until the specified date and time has
occurred, at which time the task is unblocked.
@@ -612,15 +615,18 @@ occurred, at which time the task is unblocked.
@end ifinfo
@subsection Changing Task Priority
-The task_set_priority directive is used to obtain or change the
+The @code{@value{DIRPREFIX}task_set_priority}
+directive is used to obtain or change the
current priority of either the calling task or another task. If
-the new priority requested is CURRENT_PRIORITY or the task's
+the new priority requested is
+@code{@value{RPREFIX}CURRENT_PRIORITY} or the task's
actual priority, then the current priority will be returned and
the task's priority will remain unchanged. If the task's
priority is altered, then the task will be scheduled according
to its new priority.
-The task_restart directive resets the priority of a task to its
+The @code{@value{DIRPREFIX}task_restart}
+directive resets the priority of a task to its
original value.
@ifinfo
@@ -628,12 +634,14 @@ original value.
@end ifinfo
@subsection Changing Task Mode
-The task_mode directive is used to obtain or change the current
+The @code{@value{DIRPREFIX}task_mode}
+directive is used to obtain or change the current
execution mode of the calling task. A task's execution mode is
used to enable preemption, timeslicing, ASR processing, and to
set the task's interrupt level.
-The task_restart directive resets the mode of a task to its
+The @code{@value{DIRPREFIX}task_restart}
+directive resets the mode of a task to its
original value.
@ifinfo
@@ -643,11 +651,15 @@ original value.
RTEMS provides sixteen notepad locations for each task. Each
notepad location may contain a note consisting of four bytes of
-information. RTEMS provides two directives, task_set_note and
-task_get_note, that enable a user to access and change the
-notepad locations. The task_set_note directive enables the user
+information. RTEMS provides two directives,
+@code{@value{DIRPREFIX}task_set_note} and
+@code{@value{DIRPREFIX}task_get_note}, that enable a user
+to access and change the
+notepad locations. The @code{@value{DIRPREFIX}task_set_note}
+directive enables the user
to set a task's notepad entry to a specified note. The
-task_get_note directive allows the user to obtain the note
+@code{@value{DIRPREFIX}task_get_note}
+directive allows the user to obtain the note
contained in any one of the sixteen notepads of a specified task.
@ifinfo
@@ -655,7 +667,8 @@ contained in any one of the sixteen notepads of a specified task.
@end ifinfo
@subsection Task Deletion
-RTEMS provides the task_delete directive to allow a task to
+RTEMS provides the @code{@value{DIRPREFIX}task_delete}
+directive to allow a task to
delete itself or any other task. This directive removes all
RTEMS references to the task, frees the task's control block,
removes it from resource wait queues, and deallocates its stack
@@ -665,8 +678,10 @@ references to either of them is invalid. In fact, RTEMS may
reuse the task ID for another task which is created later in the
application.
-Unexpired delay timers (i.e. those used by task_wake_after and
-task_wake_when) and timeout timers associated with the task are
+Unexpired delay timers (i.e. those used by
+@code{@value{DIRPREFIX}task_wake_after} and
+@code{@value{DIRPREFIX}task_wake_when}) and
+timeout timers associated with the task are
automatically deleted, however, other resources dynamically
allocated by the task are NOT automatically returned to RTEMS.
Therefore, before a task is deleted, all of its dynamically
@@ -757,15 +772,17 @@ This directive creates a task which resides on the local node.
It allocates and initializes a TCB, a stack, and an optional
floating point context area. The mode parameter contains values
which sets the task's initial execution mode. The
-@code{@value{RPREFIX}FLOATING_POINT} attribute should be specified if the created task
+@code{@value{RPREFIX}FLOATING_POINT} attribute should be
+specified if the created task
is to use a numeric coprocessor. For performance reasons, it is
recommended that tasks not using the numeric coprocessor should
-specify the @code{@value{RPREFIX}NO_FLOATING_POINT} attribute. If the GLOBAL
+specify the @code{@value{RPREFIX}NO_FLOATING_POINT} attribute.
+If the @code{@value{RPREFIX}GLOBAL}
attribute is specified, the task can be accessed from remote
nodes. The task id, returned in id, is used in other task
related directives to access the task. When created, a task is
placed in the dormant state and can only be made ready to
-execute using the directive task_start.
+execute using the directive @code{@value{DIRPREFIX}task_start}.
@subheading NOTES:
This directive will not cause the calling task to be preempted.
@@ -776,8 +793,10 @@ 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} is processor dependent.
+The requested stack size should be at least
+@code{@value{RPREFIX}MINIMUM_STACK_SIZE}
+bytes. The value of @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
+is processor dependent.
Application developers should consider the stack usage of the
device drivers when calculating the stack size required for
tasks which utilize the driver.
@@ -922,7 +941,7 @@ enabled and the task being started has a higher priority.
Any actions performed on a dormant task such as suspension or
change of priority are nullified when the task is initiated via
-the task_start directive.
+the @code{@value{DIRPREFIX}task_start} directive.
@page
@@ -968,9 +987,12 @@ dormant state.
The task's starting argument is contained in argument. This
argument can be a single value or an index into an array of
parameter blocks. This new argument may be used to distinguish
-between the initial task_start of the task and any ensuing calls
-to task_restart of the task. This can be beneficial in deleting
-a task. Instead of deleting a task using the task_delete
+between the initial @code{@value{DIRPREFIX}task_start}
+of the task and any ensuing calls
+to @code{@value{DIRPREFIX}task_restart}
+of the task. This can be beneficial in deleting
+a task. Instead of deleting a task using
+the @code{@value{DIRPREFIX}task_delete}
directive, a task can delete another task by restarting that
task, and allowing that task to release resources back to RTEMS
and then delete itself.
@@ -983,7 +1005,7 @@ The calling task will be preempted if its preemption mode is
enabled and the task being restarted has a higher priority.
The task must reside on the local node, even if the task was
-created with the GLOBAL option.
+created with the @code{@value{RPREFIX}GLOBAL} option.
@page
@@ -1042,7 +1064,7 @@ to every node in the system for deletion from the local copy of
the global object table.
The task must reside on the local node, even if the task was
-created with the GLOBAL option.
+created with the @code{@value{RPREFIX}GLOBAL} option.
@page
@@ -1079,7 +1101,8 @@ This directive suspends the task specified by id from further
execution by placing it in the suspended state. This state is
additive to any other blocked state that the task may already be
in. The task will not execute again until another task issues
-the task_resume directive for this task and any blocked state
+the @code{@value{DIRPREFIX}task_resume}
+directive for this task and any blocked state
has been removed.
@subheading NOTES:
@@ -1092,7 +1115,7 @@ will generate a request to the remote node to suspend the
specified task.
If the task specified by id is already suspended, then the
-ALREADY_SUSPENDED status code is returned.
+@code{@value{RPREFIX}ALREADY_SUSPENDED} status code is returned.
@page
@@ -1140,7 +1163,7 @@ will generate a request to the remote node to resume the
specified task.
If the task specified by id is not suspended, then the
-INCORRECT_STATE status code is returned.
+@code{@value{RPREFIX}INCORRECT_STATE} status code is returned.
@page
@@ -1178,10 +1201,12 @@ procedure Task_Set_Priority (
@subheading DESCRIPTION:
This directive manipulates the priority of the task specified by
-id. An id of @code{@value{RPREFIX}SELF} is used to indicate the calling task. When
-new_priority is not equal to CURRENT_PRIORITY, the specified
+id. An id of @code{@value{RPREFIX}SELF} is used to indicate
+the calling task. When new_priority is not equal to
+@code{@value{RPREFIX}CURRENT_PRIORITY}, the specified
task's previous priority is returned in old_priority. When
-new_priority is CURRENT_PRIORITY, the specified task's current
+new_priority is @code{@value{RPREFIX}CURRENT_PRIORITY},
+the specified task's current
priority is returned in old_priority. Valid priorities range
from a high of 1 to a low of 255.
@@ -1252,25 +1277,41 @@ a higher priority task is ready to run.
Enabling timeslicing has no effect if preemption is enabled.
A task can obtain its current execution mode, without modifying
-it, by calling this directive with a mask value of @code{@value{RPREFIX}CURRENT_MODE}.
+it, by calling this directive with a mask value of
+@code{@value{RPREFIX}CURRENT_MODE}.
To temporarily disable the processing of a valid ASR, a task
-should call this directive with the NO_ASR indicator specified
-in mode.
+should call this directive with the @code{@value{RPREFIX}NO_ASR}
+indicator specified in mode.
The set of task mode constants and each mode's corresponding
mask constant is provided in the following table:
@ifset use-ascii
@itemize @bullet
-@item PREEMPT is masked by PREEMPT_MASK and enables preemption
-@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
-@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
-@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
-@item ASR is masked by ASR_MASK and enables ASR processing
-@item NO_ASR is masked by ASR_MASK and disables ASR processing
-@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
-@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+@item @code{@value{RPREFIX}PREEMPT} is masked by
+@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
+
+@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
+@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
+
+@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
+@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
+
+@item @code{@value{RPREFIX}TIMESLICE} is masked by
+@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
+
+@item @code{@value{RPREFIX}ASR} is masked by
+@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
+
+@item @code{@value{RPREFIX}NO_ASR} is masked by
+@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
+
+@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
+@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
+
+@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
+@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
@end itemize
@end ifset
@@ -1279,14 +1320,29 @@ mask constant is provided in the following table:
@sp 1
@c this is temporary
@itemize @bullet
-@item PREEMPT is masked by PREEMPT_MASK and enables preemption
-@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption
-@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing
-@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing
-@item ASR is masked by ASR_MASK and enables ASR processing
-@item NO_ASR is masked by ASR_MASK and disables ASR processing
-@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts
-@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n
+@item @code{@value{RPREFIX}PREEMPT} is masked by
+@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
+
+@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
+@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
+
+@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
+@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
+
+@item @code{@value{RPREFIX}TIMESLICE} is masked by
+@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
+
+@item @code{@value{RPREFIX}ASR} is masked by
+@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
+
+@item @code{@value{RPREFIX}NO_ASR} is masked by
+@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
+
+@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
+@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
+
+@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
+@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
@end itemize
@@ -1301,29 +1357,29 @@ mask constant is provided in the following table:
<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
<TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
<TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
-<TR><TD ALIGN=center>PREEMPT</TD>
- <TD ALIGN=center>PREEMPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
+ <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
<TD ALIGN=center>enables preemption</TD></TR>
-<TR><TD ALIGN=center>NO_PREEMPT</TD>
- <TD ALIGN=center>PREEMPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
+ <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
<TD ALIGN=center>disables preemption</TD></TR>
-<TR><TD ALIGN=center>NO_TIMESLICE</TD>
- <TD ALIGN=center>TIMESLICE_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
+ <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
<TD ALIGN=center>disables timeslicing</TD></TR>
-<TR><TD ALIGN=center>TIMESLICE</TD>
- <TD ALIGN=center>TIMESLICE_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
+ <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
<TD ALIGN=center>enables timeslicing</TD></TR>
-<TR><TD ALIGN=center>ASR</TD>
- <TD ALIGN=center>ASR_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
+ <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
<TD ALIGN=center>enables ASR processing</TD></TR>
-<TR><TD ALIGN=center>NO_ASR</TD>
- <TD ALIGN=center>ASR_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
+ <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
<TD ALIGN=center>disables ASR processing</TD></TR>
-<TR><TD ALIGN=center>INTERRUPT_LEVEL(0)</TD>
- <TD ALIGN=center>INTERRUPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
+ <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
<TD ALIGN=center>enables all interrupts</TD></TR>
-<TR><TD ALIGN=center>INTERRUPT_LEVEL(n)</TD>
- <TD ALIGN=center>INTERRUPT_MASK</TD>
+<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
+ <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
<TD ALIGN=center>sets interrupts level n</TD></TR>
</TABLE>
</CENTER>
@@ -1371,7 +1427,8 @@ location of the task specified by id.
@subheading NOTES:
This directive will not cause the running task to be preempted.
-If id is set to @code{@value{RPREFIX}SELF}, the calling task accesses its own notepad.
+If id is set to @code{@value{RPREFIX}SELF},
+the calling task accesses its own notepad.
@c This version of the paragraph avoids the overfull hbox error.
@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
@@ -1423,8 +1480,8 @@ This directive sets the notepad entry for the task specified by
id to the value note.
@subheading NOTES:
-If id is set to @code{@value{RPREFIX}SELF}, the calling task accesses its own notepad
-locations.
+If id is set to @code{@value{RPREFIX}SELF}, the calling
+task accesses its own notepad locations.
This directive will not cause the running task to be preempted.
@@ -1470,12 +1527,13 @@ procedure Task_Wake_After (
@subheading DESCRIPTION:
This directive blocks the calling task for the specified number
of system clock ticks. When the requested interval has elapsed,
-the task is made ready. The clock_tick directive automatically
-updates the delay period.
+the task is made ready. The @code{@value{DIRPREFIX}clock_tick}
+directive automatically updates the delay period.
@subheading NOTES:
-Setting the system date and time with the clock_set directive
-has no effect on a task_wake_after blocked task.
+Setting the system date and time with the
+@code{@value{DIRPREFIX}clock_set} directive
+has no effect on a @code{@value{DIRPREFIX}task_wake_after} blocked task.
A task may give up the processor and remain in the ready state
by specifying a value of @code{@value{RPREFIX}YIELD_PROCESSOR} in ticks.
diff --git a/doc/user/timer.t b/doc/user/timer.t
index 2f4538a12b..bdfb6d1801 100644
--- a/doc/user/timer.t
+++ b/doc/user/timer.t
@@ -65,10 +65,11 @@ A clock tick is required to support the functionality provided by this manager.
A timer is an RTEMS object which allows the
application to schedule operations to occur at specific times in
the future. User supplied timer service routines are invoked by
-the clock_tick directive when the timer fires. Timer service
-routines may perform any operations or directives which normally
+the @code{@value{DIRPREFIX}clock_tick} directive
+when the timer fires. Timer service routines may perform
+any operations or directives which normally
would be performed by the application code which invoked the
-clock_tick directive.
+@code{@value{DIRPREFIX}clock_tick} directive.
The timer can be used to implement watchdog routines
which only fire to denote that an application error has
@@ -131,7 +132,7 @@ service routine. The argument user_data may be NULL.
@end ifinfo
@subsection Creating a Timer
-The timer_create directive creates a timer by
+The @code{@value{DIRPREFIX}timer_create} directive creates a timer by
allocating a Timer Control Block (TMCB), assigning the timer a
user-specified name, and assigning it a timer ID. Newly created
timers do not have a timer service routine associated with them
@@ -145,55 +146,58 @@ and are not active.
When a timer is created, RTEMS generates a unique
timer ID and assigns it to the created timer until it is
deleted. The timer ID may be obtained by either of two methods.
-First, as the result of an invocation of the timer_create
+First, as the result of an invocation of the
+@code{@value{DIRPREFIX}timer_create}
directive, the timer ID is stored in a user provided location.
-Second, the timer ID may be obtained later using the timer_ident
-directive. The timer ID is used by other directives to
-manipulate this timer.
+Second, the timer ID may be obtained later using the
+@code{@value{DIRPREFIX}timer_ident} directive. The timer ID
+is used by other directives to manipulate this timer.
@ifinfo
@node Initiating an Interval Timer, Initiating a Time of Day Timer, Obtaining Timer IDs, Timer Manager Operations
@end ifinfo
@subsection Initiating an Interval Timer
-The timer_fire_after directive initiates a timer to
+The @code{@value{DIRPREFIX}timer_fire_after} directive initiates a timer to
fire a user provided timer service routine after the specified
number of clock ticks have elapsed. When the interval has
elapsed, the timer service routine will be invoked from the
-clock_tick directive.
+@code{@value{DIRPREFIX}clock_tick} directive.
@ifinfo
@node Initiating a Time of Day Timer, Canceling a Timer, Initiating an Interval Timer, Timer Manager Operations
@end ifinfo
@subsection Initiating a Time of Day Timer
-The timer_fire_when directive initiates a timer to
+The @code{@value{DIRPREFIX}timer_fire_when} directive initiates a timer to
fire a user provided timer service routine when the specified
time of day has been reached. When the interval has elapsed,
-the timer service routine will be invoked from the clock_tick
-directive.
+the timer service routine will be invoked from the
+@code{@value{DIRPREFIX}clock_tick} directive.
@ifinfo
@node Canceling a Timer, Resetting a Timer, Initiating a Time of Day Timer, Timer Manager Operations
@end ifinfo
@subsection Canceling a Timer
-The timer_cancel directive is used to halt the
+The @code{@value{DIRPREFIX}timer_cancel} directive is used to halt the
specified timer. Once canceled, the timer service routine will
not fire unless the timer is reinitiated. The timer can be
-reinitiated using the timer_reset, timer_fire_after, and
-timer_fire_when directives.
+reinitiated using the @code{@value{DIRPREFIX}timer_reset},
+@code{@value{DIRPREFIX}timer_fire_after}, and
+@code{@value{DIRPREFIX}timer_fire_when} directives.
@ifinfo
@node Resetting a Timer, Deleting a Timer, Canceling a Timer, Timer Manager Operations
@end ifinfo
@subsection Resetting a Timer
-The timer_reset directive is used to restore an
+The @code{@value{DIRPREFIX}timer_reset} directive is used to restore an
interval timer initiated by a previous invocation of
-timer_fire_after to its original interval length. If the
+@code{@value{DIRPREFIX}timer_fire_after} to
+its original interval length. If the
timer has not been used or the last usage of this timer
-was by a timer_fire_when directive, then an error is
+was by a @code{@value{DIRPREFIX}timer_fire_when} directive, then an error is
returned. The timer service routine is not changed or
fired by this directive.
@@ -202,7 +206,7 @@ fired by this directive.
@end ifinfo
@subsection Deleting a Timer
-The timer_delete directive is used to delete a timer.
+The @code{@value{DIRPREFIX}timer_delete} directive is used to delete a timer.
If the timer is running and has not expired, the timer is
automatically canceled. The timer's control block is returned
to the TMCB free list when it is deleted. A timer can be
@@ -352,8 +356,9 @@ procedure Timer_Cancel (
@subheading DESCRIPTION:
This directive cancels the timer id. This timer will
-be reinitiated by the next invocation of timer_reset,
-timer_fire_after, or timer_fire_when with id.
+be reinitiated by the next invocation of @code{@value{DIRPREFIX}timer_reset},
+@code{@value{DIRPREFIX}timer_fire_after}, or
+@code{@value{DIRPREFIX}timer_fire_when} with id.
@subheading NOTES:
@@ -537,15 +542,18 @@ procedure Timer_Reset (
This directive resets the timer associated with id.
This timer must have been previously initiated with a
-timer_fire_after directive. If active the timer is canceled,
+@code{@value{DIRPREFIX}timer_fire_after}
+directive. If active the timer is canceled,
after which the timer is reinitiated using the same interval and
-timer service routine which the original timer_fire_after
+timer service routine which the original
+@code{@value{DIRPREFIX}timer_fire_after}
directive used.
@subheading NOTES:
If the timer has not been used or the last usage of this timer
-was by a timer_fire_when directive, then the NOT_DEFINED error is
+was by a @code{@value{DIRPREFIX}timer_fire_when}
+directive, then the @code{@value{RPREFIX}NOT_DEFINED} error is
returned.
Restarting a cancelled after timer results in the timer being
diff --git a/doc/user/userext.t b/doc/user/userext.t
index 4de1e2aa61..99cda16c10 100644
--- a/doc/user/userext.t
+++ b/doc/user/userext.t
@@ -138,7 +138,8 @@ optional and may be configured as NULL if no static extension
set is required.
Second, the user can install dynamic extensions using
-the extension_create directive. These extensions are RTEMS
+the @code{@value{DIRPREFIX}extension_create}
+directive. These extensions are RTEMS
objects in that they have a name, an ID, and can be dynamically
created and deleted. In contrast to the static extension set,
these extensions can only be created and installed after the
@@ -607,7 +608,7 @@ extension is invoked after that of the other extensions.
@end ifinfo
@subsection Creating an Extension Set
-The extension_create directive creates and installs
+The @code{@value{DIRPREFIX}extension_create} directive creates and installs
an extension set by allocating a Extension Set Control Block
(ESCB), assigning the extension set a user-specified name, and
assigning it an extension set ID. Newly created extension sets
@@ -623,18 +624,19 @@ When an extension set is created, RTEMS generates a
unique extension set ID and assigns it to the created extension
set until it is deleted. The extension ID may be obtained by
either of two methods. First, as the result of an invocation of
-the extension_create directive, the extension set ID is stored
+the @code{@value{DIRPREFIX}extension_create}
+directive, the extension set ID is stored
in a user provided location. Second, the extension set ID may
-be obtained later using the extension_ident directive. The
-extension set ID is used by other directives to manipulate this
-extension set.
+be obtained later using the @code{@value{DIRPREFIX}extension_ident}
+directive. The extension set ID is used by other directives
+to manipulate this extension set.
@ifinfo
@node Deleting an Extension Set, User Extensions Manager Directives, Obtaining Extension Set IDs, User Extensions Manager Operations
@end ifinfo
@subsection Deleting an Extension Set
-The extension_delete directive is used to delete an
+The @code{@value{DIRPREFIX}extension_delete} directive is used to delete an
extension set. The extension set's control block is returned to
the ESCB free list when it is deleted. An extension set can be
deleted by a task other than the task which created the