RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

Completed sweep adding directive and constant prefixes.

Browse Source
This commit is contained in:
Joel Sherrill
1998-03-27 16:47:53 +00:00
parent 3973e40a54
commit 75e22db0d5
22 changed files with 823 additions and 606 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
doc/user/bsp.t
View File

@@ -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.

100
doc/user/clock.t
View File

@@ -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

34
doc/user/conf.t
View File

@@ -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.

15
doc/user/dpmem.t
View File

@@ -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

32
doc/user/event.t
View File

@@ -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

2
doc/user/example.texi
View File

@@ -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" */

16
doc/user/fatal.t
View File

@@ -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

10
doc/user/glossary.texi
View File

@@ -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

79
doc/user/init.t
View File

@@ -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:

20
doc/user/intr.t
View File

@@ -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:

19
doc/user/io.t
View File

@@ -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

18
doc/user/mp.t
View File

@@ -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.

64
doc/user/msg.t
View File

@@ -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

39
doc/user/part.t
View File

@@ -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

61
doc/user/region.t
View File

@@ -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:

82
doc/user/rtmon.t
View File

@@ -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:

89
doc/user/schedule.t
View File

@@ -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

141
doc/user/sem.t
View File

@@ -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.

35
doc/user/signal.t
View File

@@ -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

466
doc/user/task.t
View File

@@ -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 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 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 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.
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.
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.
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.
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.
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.
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.
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 @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 task_wake_when directive creates a sleep timer which allows
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.

58
doc/user/timer.t
View File

@@ -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

16
doc/user/userext.t
View File

@@ -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