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

Turned on concept and function name indexing.

Browse Source
This commit is contained in:
Joel Sherrill
1999-10-11 19:03:05 +00:00
parent 0de83594a6
commit 169502ea55
23 changed files with 770 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
doc/user/Makefile
View File

@@ -36,21 +36,21 @@ info: dirs $(PROJECT)
$(PROJECT): $(FILES)
$(MAKEINFO) $(PROJECT).texi
dvi: $(PROJECT).dvi
dvi: dirs $(PROJECT).dvi
ps: dirs $(PROJECT).ps
pdf: dirs $(PROJECT).pdf
$(PROJECT).pdf: $(FILES)
$(TEXI2PDF) $(PROJECT).texi
cp $(PROJECT).pdf $(PDF_INSTALL)
cp $(PROJECT).pdf $(WWW_INSTALL)/$(PROJECT)
$(PROJECT).ps: $(PROJECT).dvi
dvips -o $(PROJECT).ps $(PROJECT).dvi
cp $(PROJECT).ps $(PS_INSTALL)
cp $(PROJECT).ps $(WWW_INSTALL)/$(PROJECT)
$(PROJECT).dvi: $(FILES)
# $(TEXI2DVI) $(PROJECT).texi
texi2dvi -V $(PROJECT).texi
$(TEXI2DVI) $(PROJECT).texi
cp $(PROJECT).dvi $(WWW_INSTALL)/$(PROJECT)
html: dirs $(FILES)
-mkdir -p $(WWW_INSTALL)/$(PROJECT)
@@ -58,6 +58,10 @@ html: dirs $(FILES)
$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
$(PROJECT).texi
index:
texindex $(PROJECT).cp $(PROJECT).vr $(PROJECT).fn \
$(PROJECT).tp $(PROJECT).pg $(PROJECT).ky
clean:
rm -f *.o $(PROG) *.txt core *.html $(PROJECT).pdf
rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)

5
doc/user/bsp.t
View File

@@ -8,8 +8,13 @@
@chapter Board Support Packages
@cindex Board Support Packages
@cindex BSPs
@section Introduction
@cindex BSP, definition
A board support package (BSP) is a collection of
user-provided facilities which interface RTEMS and an
application with a specific hardware platform. These facilities

10
doc/user/c_user.texi
View File

@@ -37,6 +37,7 @@ END-INFO-DIR-ENTRY
@end ifinfo
@end ignore
@c @syncodeindex fn cp
@c variable substitution info:
@c
@set is-C
@@ -154,15 +155,16 @@ This is the online version of the RTEMS C User's Guide.
@node Command and Variable Index, Concept Index, Glossary, Top
@unnumbered Command and Variable Index
There are currently no Command and Variable Index entries.
@printindex fn
@c There are currently no Command and Variable Index entries.
@c @printindex fn
@node Concept Index, , Command and Variable Index, Top
@unnumbered Concept Index
There are currently no Concept Index entries.
@c @printindex cp
@c There are currently no Concept Index entries.
@printindex cp
@contents
@bye

23
doc/user/clock.t
View File

@@ -8,6 +8,8 @@
@chapter Clock Manager
@cindex clock
@section Introduction
The clock manager provides support for time of day
@@ -218,13 +220,18 @@ A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
@c
@c
@c
@page
@subsection CLOCK_SET - Set system date and time
@subheading CALLING SEQUENCE:
@cindex set the time of day
@ifset is-C
@c @findex rtems_clock_set
@findex rtems_clock_set
@example
rtems_status_code rtems_clock_set(
rtems_time_of_day *time_buffer
@@ -269,13 +276,18 @@ to be reset to an uninitialized state. Another call to
@code{@value{DIRPREFIX}clock_set} is required to re-initialize
the system date and time to application specific specifications.
@c
@c
@c
@page
@subsection CLOCK_GET - Get system date and time information
@cindex obtain the time of day
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_clock_get
@findex rtems_clock_get
@example
rtems_status_code rtems_clock_get(
rtems_clock_get_options option,
@@ -360,13 +372,18 @@ time to be reset to an uninitialized state. Another call to
@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
system date and time to application specific specifications.
@c
@c
@c
@page
@subsection CLOCK_TICK - Announce a clock tick
@cindex clock tick
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_clock_tick
@findex rtems_clock_tick
@example
rtems_status_code rtems_clock_tick( void );
@end example

12
doc/user/concepts.t
View File

@@ -23,6 +23,8 @@ one with these concepts.
@section Objects
@cindex objects
RTEMS provides directives which can be used to
dynamically create, delete, and manipulate a set of predefined
object types. These types include tasks, message queues,
@@ -41,6 +43,8 @@ reflect the object's use in the application. Conversely, object
IDs are designed to facilitate efficient object manipulation by
the executive.
@cindex object name
An object name is an unsigned thirty-two bit entity
associated with the object by the user. Although not required
by RTEMS, object names are typically composed of four ASCII
@@ -55,6 +59,8 @@ assign meaningful ASCII names to each task. A more convenient
approach would be to name them the binary values one through
one-hundred, respectively.
@cindex object ID
@need 3000
An object ID is a unique unsigned thirty-two bit
@@ -179,6 +185,8 @@ user applications.
@section Communication and Synchronization
@cindex communication and synchronization
In real-time multitasking applications, the ability
for cooperating execution threads to communicate and synchronize
with each other is imperative. A real-time executive should
@@ -220,6 +228,8 @@ for exception handling.
@section Time
@cindex time
The development of responsive real-time applications
requires an understanding of how RTEMS maintains and supports
time-related operations. The basic unit of time in RTEMS is
@@ -267,6 +277,8 @@ provided by a real time clock or counter/timer device.
@section Memory Management
@cindex memory management
RTEMS memory management facilities can be grouped
into two classes: dynamic memory allocation and address
translation. Dynamic memory allocation is required by

22
doc/user/conf.t
View File

@@ -31,6 +31,9 @@
@section Automatic Generation of System Configuration
@cindex confdefs.h
@fnindex confdefs.h
RTEMS provides the @code{confdefs.h} C language header file that
based on the setting of a variety of macros can automatically
produce nearly all of the configuration tables required
@@ -62,6 +65,9 @@ can be easily configured using the @code{confdefs.h} mechanism.
@section Configuration Table
@cindex Configuration Table
@cindex RTEMS Configuration Table
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.
@@ -268,6 +274,8 @@ and NULL if the POSIX API is not configured.
@section RTEMS API Configuration Table
@cindex RTEMS API Configuration Table
The RTEMS API Configuration Table is used to configure the
managers which constitute the RTEMS API for a particular application.
For example, the user can configure the maximum number of tasks for
@@ -443,6 +451,8 @@ to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
@section POSIX API Configuration Table
@cindex POSIX API Configuration Table
The POSIX API Configuration Table is used to configure the
managers which constitute the POSIX API for a particular application.
For example, the user can configure the maximum number of threads for
@@ -601,6 +611,8 @@ to the address of the @code{POSIX_Initialization_threads} structure.
@section CPU Dependent Information Table
@cindex CPU Dependent Information Table
The CPU Dependent Information Table is used to
describe processor dependent information required by RTEMS.
This table is generally used to supply RTEMS with information
@@ -614,6 +626,8 @@ table. It is normally filled in by the Board Support Package.
@section Initialization Task Table
@cindex Initialization Tasks Table
The Initialization Task Table is used to describe
each of the user initialization tasks to the Initialization
Manager. The table contains one entry for each initialization
@@ -738,6 +752,8 @@ Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
@section Driver Address Table
@cindex Device Driver Table
The Device Driver Table is used to inform the I/O
Manager of the set of entry points for each device driver
configured in the system. The table contains one entry for each
@@ -832,6 +848,8 @@ chapter.
@section User Extensions Table
@cindex User Extensions Table
The User Extensions Table is used to inform RTEMS of
the optional user-supplied static extension set. This table
contains one entry for each possible extension. The entries are
@@ -991,6 +1009,8 @@ provided in the User Extensions chapter.
@section Multiprocessor Configuration Table
@cindex Multiprocessor Configuration Table
The Multiprocessor Configuration Table contains
information needed when using RTEMS in a multiprocessor
configuration. Many of the details associated with configuring
@@ -1112,6 +1132,8 @@ address of the table named @code{MPCI_table}.
@section Multiprocessor Communications Interface Table
@cindex Multiprocessor Communications Interface Table
This table defines the set of callouts that must be provided by
an Multiprocessor Communications Interface implementation.

43
doc/user/dpmem.t
View File

@@ -8,6 +8,9 @@
@chapter Dual-Ported Memory Manager
@cindex ports
@cindex dual ported memory
@section Introduction
The dual-ported memory manager provides a mechanism
@@ -25,6 +28,10 @@ The directives provided by the dual-ported memory manager are:
@section Background
@cindex dual ported memory, definition
@cindex external addresses, definition
@cindex internal addresses, definition
A dual-ported memory area (DPMA) is an contiguous
block of RAM owned by a particular processor but which can be
accessed by other processors in the system. The owner accesses
@@ -92,13 +99,18 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection PORT_CREATE - Create a port
@cindex create a port
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_port_create
@findex rtems_port_create
@example
rtems_status_code rtems_port_create(
rtems_name name,
@@ -150,13 +162,19 @@ must be on a four byte boundary.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection PORT_IDENT - Get ID of a port
@cindex get ID of a port
@cindex obtain ID of a port
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_port_ident
@findex rtems_port_ident
@example
rtems_status_code rtems_port_ident(
rtems_name name,
@@ -193,13 +211,18 @@ other dual-ported memory area related directives.
This directive will not cause the running task to be
preempted.
@c
@c
@c
@page
@subsection PORT_DELETE - Delete a port
@cindex delete a port
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_port_delete
@findex rtems_port_delete
@example
rtems_status_code rtems_port_delete(
rtems_id id
@@ -235,13 +258,18 @@ The calling task does not have to be the task that
created the port. Any local task that knows the port id can
delete the port.
@c
@c
@c
@page
@subsection PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
@cindex convert external to internal address
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_port_external_to_internal
@findex rtems_port_external_to_internal
@example
rtems_status_code rtems_port_external_to_internal(
rtems_id id,
@@ -280,13 +308,18 @@ This directive is callable from an ISR.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
@cindex convert internal to external address
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_port_internal_to_external
@findex rtems_port_internal_to_external
@example
rtems_status_code rtems_port_internal_to_external(
rtems_id id,

21
doc/user/event.t
View File

@@ -8,6 +8,8 @@
@chapter Event Manager
@cindex events
@section Introduction
The event manager provides a high performance method
@@ -23,6 +25,8 @@ provided by the event manager are:
@subsection Event Sets
@cindex event set, definition
An event flag is used by a task (or ISR) to inform
another task of the occurrence of a significant situation.
Thirty-two event flags are associated with each task. A
@@ -60,6 +64,9 @@ is satisfied when every requested event is posted.
@subsection Building an Event Set or Condition
@cindex event condition, building
@cindex event set, building
An event set or condition is built by a bitwise OR of
the desired events. The set of valid events is @code{@value{RPREFIX}EVENT_0} through
@code{@value{RPREFIX}EVENT_31}. If an event is not explicitly specified in the set or
@@ -184,13 +191,18 @@ A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
@c
@c
@c
@page
@subsection EVENT_SEND - Send event set to a task
@cindex send event set to a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_event_send
@findex rtems_event_send
@example
rtems_status_code rtems_event_send (
rtems_id id,
@@ -241,13 +253,18 @@ Sending an event set to a global task which does not
reside on the local node will generate a request telling the
remote node to send the event set to the appropriate task.
@c
@c
@c
@page
@subsection EVENT_RECEIVE - Receive event condition
@cindex receive event condition
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_event_receive
@findex rtems_event_receive
@example
rtems_status_code rtems_event_receive (
rtems_event_set event_in,

14
doc/user/fatal.t
View File

@@ -8,6 +8,8 @@
@chapter Fatal Error Manager
@cindex fatal errors
@section Introduction
The fatal error manager processes all fatal or
@@ -20,6 +22,10 @@ manager is:
@section Background
@cindex fatal error detection
@cindex fatal error processing
@cindex fatal error user extension
The fatal error manager is called upon detection of
an irrecoverable error condition by either RTEMS or the
application software. Fatal errors can be detected from three
@@ -110,13 +116,19 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection FATAL_ERROR_OCCURRED - Invoke the fatal error handler
@cindex announce fatal error
@cindex fatal error, announce
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_fatal_error_occurred
@findex rtems_fatal_error_occurred
@example
void volatile rtems_fatal_error_occurred(
rtems_unsigned32 the_error

21
doc/user/init.t
View File

@@ -29,6 +29,8 @@ directives provided by the initialization manager are:
@subsection Initialization Tasks
@cindex initialization tasks
Initialization task(s) are the mechanism by which
RTEMS transfers initial control to the user's application.
Initialization tasks differ from other application tasks in that
@@ -190,10 +192,12 @@ constants, usage, and status codes.
@page
@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS
@cindex initialize RTEMS
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_initialize_executive
@findex rtems_initialize_executive
@example
void rtems_initialize_executive(
rtems_configuration_table *configuration_table,
@@ -254,10 +258,12 @@ with no intervening actions.
@page
@subsection INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking
@cindex initialize RTEMS
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_initialize_executive_early
@findex rtems_initialize_executive_early
@example
rtems_interrupt_level rtems_initialize_executive_early(
rtems_configuration_table *configuration_table,
@@ -307,10 +313,13 @@ initialization sequences:
@page
@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking
@cindex initialize RTEMS
@cindex start multitasking
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_initialize_executive_late
@findex rtems_initialize_executive_late
@example
void rtems_initialize_executive_late(
rtems_interrupt_level bsp_level
@@ -357,7 +366,7 @@ a fatal error is generated.
The application must use only one of the two
initialization sequences:
@code{@value{DIRPREFIX}initialize_executive} or
@code{@value{DIRPREFIX}nitialize_executive_early} and
@code{@value{DIRPREFIX}initialize_executive_early} and
@code{@value{DIRPREFIX}initialize_executive_late}.
@@ -365,10 +374,12 @@ initialization sequences:
@page
@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS
@cindex shutdown RTEMS
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_shutdown_executive
@findex rtems_shutdown_executive
@example
void rtems_shutdown_executive(
rtems_unsigned32 result

43
doc/user/intr.t
View File

@@ -31,6 +31,8 @@ directive:
@subsection Processing an Interrupt
@cindex interrupt processing
The interrupt manager allows the application to
connect a function to a hardware interrupt vector. When an
interrupt occurs, the processor will automatically vector to
@@ -98,7 +100,6 @@ RTEMS directive.}
@end itemize
Consider a processor which allows a numerically low
interrupt level to interrupt a numerically greater interrupt
level. In this example, if an RTEMS directive is used in a
@@ -113,6 +114,8 @@ outermost ISR terminates will the postponed dispatching occur.
@subsection RTEMS Interrupt Levels
@cindex interrupt levels
Many processors support multiple interrupt levels or
priorities. The exact number of interrupt levels is processor
dependent. RTEMS internally supports 256 interrupt levels which
@@ -124,6 +127,8 @@ target processor.
@subsection Disabling of Interrupts by RTEMS
@cindex disabling interrupts
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables all maskable interrupts before the
@@ -225,13 +230,19 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection INTERRUPT_CATCH - Establish an ISR
@cindex establish an ISR
@cindex install an ISR
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_interrupt_catch
@findex rtems_interrupt_catch
@example
rtems_status_code rtems_interrupt_catch(
rtems_isr_entry new_isr_handler,
@@ -277,13 +288,18 @@ will be ignored.
This directive will not cause the calling task to be preempted.
@c
@c
@c
@page
@subsection INTERRUPT_DISABLE - Disable Interrupts
@cindex disable interrupts
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_interrupt_disable
@findex rtems_interrupt_disable
@example
void rtems_interrupt_disable(
rtems_interrupt_level level
@@ -320,13 +336,18 @@ This directive will not cause the calling task to be preempted.
parameter.}
@end ifset
@c
@c
@c
@page
@subsection INTERRUPT_ENABLE - Enable Interrupts
@cindex enable interrupts
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_interrupt_enable
@findex rtems_interrupt_enable
@example
void rtems_interrupt_enable(
rtems_interrupt_level level
@@ -360,13 +381,18 @@ and will be enabled when this directive returns to the caller.
This directive will not cause the calling task to be preempted.
@c
@c
@c
@page
@subsection INTERRUPT_FLASH - Flash Interrupts
@cindex flash interrupts
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_interrupt_flash
@findex rtems_interrupt_flash
@example
void rtems_interrupt_flash(
rtems_interrupt_level level
@@ -399,13 +425,18 @@ and will be redisabled when this directive returns to the caller.
This directive will not cause the calling task to be preempted.
@c
@c
@c
@page
@subsection INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
@cindex is interrupt in progress
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_interrupt_is_in_progress
@findex rtems_interrupt_is_in_progress
@example
rtems_boolean rtems_interrupt_is_in_progress( void );
@end example

69
doc/user/io.t
View File

@@ -8,6 +8,9 @@
@chapter I/O Manager
@cindex device drivers
@cindex IO Manager
@section Introduction
The input/output interface manager provides a
@@ -30,6 +33,8 @@ directives provided by the I/O manager are:
@subsection Device Driver Table
@cindex Device Driver Table
Each application utilizing the RTEMS I/O manager must
specify the address of a Device Driver Table in its
Configuration Table. This table contains each device driver's
@@ -54,6 +59,9 @@ driver entry points.
@subsection Major and Minor Device Numbers
@cindex major device number
@cindex minor device number
Each call to the I/O manager must provide a device's
major and minor numbers as arguments. The major number is the
index of the requested driver's entry points in the Device
@@ -64,6 +72,8 @@ controlled by the same driver.
@subsection Device Names
@cindex device names
The I/O Manager provides facilities to associate a
name with a particular device. Directives are provided to
register the name of a device and to look up the major/minor
@@ -101,6 +111,8 @@ construction or operation of a device driver.
@subsection Device Driver Interface
@cindex device driver interface
When an application invokes an I/O manager directive,
RTEMS determines which device driver entry point must be
invoked. The information passed by the application to RTEMS is
@@ -198,13 +210,18 @@ subsection is dedicated to each of this manager's directives and
describes the calling sequence, related constants, usage, and
status codes.
@c
@c
@c
@page
@subsection IO_INITIALIZE - Initialize a device driver
@cindex initialize a device driver
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_initialize
@findex rtems_io_initialize
@example
rtems_status_code rtems_io_initialize(
rtems_device_major_number major,
@@ -249,13 +266,18 @@ This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
initialized.
@c
@c
@c
@page
@subsection IO_REGISTER_NAME - Register a device
@cindex register device
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_register_name
@findex rtems_io_register_name
@example
rtems_status_code rtems_io_register_name(
char *name,
@@ -290,13 +312,18 @@ major/minor number pair.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection IO_LOOKUP_NAME - Lookup a device
@cindex lookup device major and minor number
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_lookup_name
@findex rtems_io_lookup_name
@example
rtems_status_code rtems_io_lookup_name(
const char *name,
@@ -329,13 +356,18 @@ associated with the given device name in device_info.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection IO_OPEN - Open a device
@cindex open a devive
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_open
@findex rtems_io_open
@example
rtems_status_code rtems_io_open(
rtems_device_major_number major,
@@ -374,13 +406,18 @@ This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
@c
@c
@c
@page
@subsection IO_CLOSE - Close a device
@cindex close a device
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_close
@findex rtems_io_close
@example
rtems_status_code rtems_io_close(
rtems_device_major_number major,
@@ -419,13 +456,18 @@ This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
@c
@c
@c
@page
@subsection IO_READ - Read from a device
@cindex read from a device
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_read
@findex rtems_io_read
@example
rtems_status_code rtems_io_read(
rtems_device_major_number major,
@@ -465,13 +507,18 @@ This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
@c
@c
@c
@page
@subsection IO_WRITE - Write to a device
@cindex write to a device
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_write
@findex rtems_io_write
@example
rtems_status_code rtems_io_write(
rtems_device_major_number major,
@@ -511,13 +558,19 @@ This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
@c
@c
@c
@page
@subsection IO_CONTROL - Special device services
@cindex special device services
@cindex IO Control
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_io_control
@findex rtems_io_control
@example
rtems_status_code rtems_io_control(
rtems_device_major_number major,

33
doc/user/mp.t
View File

@@ -8,6 +8,8 @@
@chapter Multiprocessing Manager
@cindex multiprocessing
@section Introduction
In multiprocessor real-time systems, new
@@ -43,6 +45,8 @@ software, to be viewed logically as a single system.
@section Background
@cindex multiprocessing topologies
RTEMS makes no assumptions regarding the connection
media or topology of a multiprocessor system. The tasks which
compose a particular application can be spread among as many
@@ -70,10 +74,13 @@ heterogeneous processing required is isolated in the MPCI layer.
@subsection Nodes
@cindex nodes, definition
A processor in a RTEMS system is referred to as a
node. Each node is assigned a unique non-zero node number by
the application designer. RTEMS assumes that node numbers are
assigned consecutively from one to maximum_nodes. The node
assigned consecutively from one to the @code{maximum_nodes}
configuration parameter. The node
number, node, and the maximum number of nodes, maximum_nodes, in
a system are found in the Multiprocessor Configuration Table.
The maximum_nodes field and the number of global objects,
@@ -87,6 +94,8 @@ able to route messages based on the node number.
@subsection Global Objects
@cindex global objects, definition
All RTEMS objects which are created with the GLOBAL
attribute will be known on all other nodes. Global objects can
be referenced from any node in the system, although certain
@@ -101,6 +110,8 @@ relocation is not supported by RTEMS.
@subsection Global Object Table
@cindex global objects table
RTEMS maintains two tables containing object
information on every node in a multiprocessor system: a local
object table and a global object table. The local object table
@@ -123,6 +134,8 @@ of a global object.
@subsection Remote Operations
@cindex MPCI and remote operations
When an application performs an operation on a remote
global object, RTEMS must generate a Remote Request (RQ) message
and send it to the appropriate node. After completing the
@@ -191,6 +204,8 @@ the MPCI and makes no attempt to detect or correct errors.
@subsection Proxies
@cindex proxy, definition
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
@@ -229,6 +244,8 @@ assumed that if the execution mode and/or interrupt level are
altered by the MPCI layer, that they will be restored prior to
returning to RTEMS.
@cindex MPCI, definition
The MPCI layer is responsible for managing a pool of
buffers called packets and for sending these packets between
system nodes. Packet buffers contain the messages sent between
@@ -237,6 +254,8 @@ packet within an envelope which contains the information needed
by the MPCI layer. The number of packets available is dependent
on the MPCI layer implementation.
@cindex MPCI entry points
The entry points to the routines in the user's MPCI
layer should be placed in the Multiprocessor Communications
Interface Table. The user must provide entry points for each of
@@ -250,8 +269,7 @@ the following table entries in a multiprocessor system:
@item receive_packet called to get an arrived packet
@end itemize
A packet is sent by RTEMS in each of the following
situations:
A packet is sent by RTEMS in each of the following situations:
@itemize @bullet
@item an RQ is generated on an originating node;
@@ -457,6 +475,8 @@ heterogeneous system.
@subsection Supporting Heterogeneous Environments
@cindex heterogeneous multiprocessing
Developing an MPCI layer for a heterogeneous system
requires a thorough understanding of the differences between the
processors which comprise the system. One difficult problem is
@@ -554,13 +574,18 @@ subsection is dedicated to each of this manager's directives and
describes the calling sequence, related constants, usage, and
status codes.
@c
@c
@c
@page
@subsection MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
@cindex announce arrival of package
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_multiprocessing_announce
@findex rtems_multiprocessing_announce
@example
void rtems_multiprocessing_announce( void );
@end example

68
doc/user/msg.t
View File

@@ -8,6 +8,9 @@
@chapter Message Manager
@cindex messages
@cindex message queues
@section Introduction
The message manager provides communication and
@@ -54,6 +57,8 @@ on a per message queue basis.
@subsection Building a Message Queue Attribute Set
@cindex message queue attributes
In general, an attribute set is built by a bitwise OR
of the desired attribute components. The set of valid message
queue attributes is provided in the following table:
@@ -211,13 +216,18 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_CREATE - Create a queue
@cindex create a message queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_create
@findex rtems_message_queue_create
@example
rtems_status_code rtems_message_queue_create(
rtems_name name,
@@ -297,13 +307,18 @@ The total number of global objects, including message
queues, is limited by the maximum_global_objects field in the
configuration table.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue
@cindex get ID of a message queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_ident
@findex rtems_message_queue_ident
@example
rtems_status_code rtems_message_queue_ident(
rtems_name name,
@@ -355,13 +370,18 @@ This directive does not generate activity on remote
nodes. It accesses only the local copy of the global object
table.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_DELETE - Delete a queue
@cindex delete a message queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_delete
@findex rtems_message_queue_delete
@example
rtems_status_code rtems_message_queue_delete(
rtems_id id
@@ -417,13 +437,18 @@ deletion from the local copy of the global object table.
Proxies, used to represent remote tasks, are
reclaimed when the message queue is deleted.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue
@cindex send message to a queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_send
@findex rtems_message_queue_send
@example
rtems_status_code rtems_message_queue_send(
rtems_id id,
@@ -476,13 +501,18 @@ node from the message queue, then the message is forwarded to
the appropriate node, the waiting task is unblocked, and the
proxy used to represent the task is reclaimed.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue
@cindex put message at front of queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_urgent
@findex rtems_message_queue_urgent
@example
rtems_status_code rtems_message_queue_urgent(
rtems_id id,
@@ -536,13 +566,18 @@ node from the message queue, then the message is forwarded to
the appropriate node, the waiting task is unblocked, and the
proxy used to represent the task is reclaimed.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
@cindex broadcast message to a queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_broadcast
@findex rtems_message_queue_broadcast
@example
rtems_status_code rtems_message_queue_broadcast(
rtems_id id,
@@ -600,13 +635,18 @@ node from the message queue, a copy of the message is forwarded
to the appropriate node, the waiting task is unblocked, and the
proxy used to represent the task is reclaimed.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue
@cindex receive message from a queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_receive
@findex rtems_message_queue_receive
@example
rtems_status_code rtems_message_queue_receive(
rtems_id id,
@@ -687,13 +727,18 @@ message is posted.
A clock tick is required to support the timeout functionality of
this directive.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue
@cindex get number of pending messages
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_get_number_pending
@findex rtems_message_queue_get_number_pending
@example
rtems_status_code rtems_message_queue_get_number_pending(
rtems_id id,
@@ -730,13 +775,18 @@ remote node to actually obtain the pending message count for
the specified message queue.
@c
@c
@c
@page
@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
@cindex flush messages on a queue
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_message_queue_flush
@findex rtems_message_queue_flush
@example
rtems_status_code rtems_message_queue_flush(
rtems_id id,

46
doc/user/part.t
View File

@@ -8,6 +8,8 @@
@chapter Partition Manager
@cindex partitions
@section Introduction
The partition manager provides facilities to
@@ -26,10 +28,14 @@ provided by the partition manager are:
@subsection Partition Manager Definitions
@cindex partition, definition
A partition is a physically contiguous memory area
divided into fixed-size buffers that can be dynamically
allocated and deallocated.
@cindex buffers, definition
Partitions are managed and maintained as a list of
buffers. Buffers are obtained from the front of the partition's
free buffer chain and returned to the rear of the same chain.
@@ -42,6 +48,8 @@ adjacent allocated buffer.
@subsection Building a Partition Attribute Set
@cindex partition attribute set, building
In general, an attribute set is built by a bitwise OR
of the desired attribute components. The set of valid partition
attributes is provided in the following table:
@@ -51,7 +59,6 @@ attributes is provided in the following table:
@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
@@ -123,13 +130,18 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection PARTITION_CREATE - Create a partition
@cindex create a partition
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_partition_create
@findex rtems_partition_create
@example
rtems_status_code rtems_partition_create(
rtems_name name,
@@ -210,13 +222,19 @@ The total number of global objects, including
partitions, is limited by the maximum_global_objects field in
the Configuration Table.
@c
@c
@c
@page
@subsection PARTITION_IDENT - Get ID of a partition
@cindex get ID of a partition
@cindex obtain ID of a partition
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_partition_ident
@findex rtems_partition_ident
@example
rtems_status_code rtems_partition_ident(
rtems_name name,
@@ -268,13 +286,18 @@ This directive does not generate activity on remote
nodes. It accesses only the local copy of the global object
table.
@c
@c
@c
@page
@subsection PARTITION_DELETE - Delete a partition
@cindex delete a partition
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_partition_delete
@findex rtems_partition_delete
@example
rtems_status_code rtems_partition_delete(
rtems_id id
@@ -320,13 +343,19 @@ 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 @code{@value{RPREFIX}GLOBAL} option.
@c
@c
@c
@page
@subsection PARTITION_GET_BUFFER - Get buffer from a partition
@cindex get buffer from partition
@cindex obtain buffer from partition
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_partition_get_buffer
@findex rtems_partition_get_buffer
@example
rtems_status_code rtems_partition_get_buffer(
rtems_id id,
@@ -369,13 +398,18 @@ Getting a buffer from a global partition which does
not reside on the local node will generate a request telling the
remote node to allocate a buffer from the specified partition.
@c
@c
@c
@page
@subsection PARTITION_RETURN_BUFFER - Return buffer to a partition
@cindex return buffer to partitition
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_partition_return_buffer
@findex rtems_partition_return_buffer
@example
rtems_status_code rtems_partition_return_buffer(
rtems_id id,

58
doc/user/region.t
View File

@@ -8,6 +8,8 @@
@chapter Region Manager
@cindex regions
@section Introduction
The region manager provides facilities to dynamically
@@ -28,6 +30,9 @@ provided by the region manager are:
@subsection Region Manager Definitions
@cindex region, definition
@cindex segment, definition
A region makes up a physically contiguous memory
space with user-defined boundaries from which variable-sized
segments are dynamically allocated and deallocated. A segment
@@ -55,6 +60,8 @@ the largest possible unused block.
@subsection Building an Attribute Set
@cindex region attribute set, building
In general, an attribute set is built by a bitwise OR
of the desired attribute components. The set of valid region
attributes is provided in the following table:
@@ -214,13 +221,18 @@ A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
@c
@c
@c
@page
@subsection REGION_CREATE - Create a region
@cindex create a region
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_create
@findex rtems_region_create
@example
rtems_status_code rtems_region_create(
rtems_name name,
@@ -293,13 +305,19 @@ by RTEMS:
@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
@end itemize
@c
@c
@c
@page
@subsection REGION_IDENT - Get ID of a region
@cindex get ID of a region
@cindex obtain ID of a region
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_ident
@findex rtems_region_ident
@example
rtems_status_code rtems_region_ident(
rtems_name name,
@@ -336,13 +354,18 @@ access this region in other region manager directives.
This directive will not cause the running task to be preempted.
@c
@c
@c
@page
@subsection REGION_DELETE - Delete a region
@cindex delete a region
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_delete
@findex rtems_region_delete
@example
rtems_status_code rtems_region_delete(
rtems_id id
@@ -380,13 +403,19 @@ The calling task does not have to be the task that
created the region. Any local task that knows the region id can
delete the region.
@c
@c
@c
@page
@subsection REGION_EXTEND - Add memory to a region
@cindex add memory to a region
@cindex region, add memory
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_extend
@findex rtems_region_extend
@example
rtems_status_code rtems_region_extend(
rtems_id id,
@@ -426,13 +455,18 @@ The calling task does not have to be the task that
created the region. Any local task that knows the region id can
extend the region.
@c
@c
@c
@page
@subsection REGION_GET_SEGMENT - Get segment from a region
@cindex get segment from region
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_get_segment
@findex rtems_region_get_segment
@example
rtems_status_code rtems_region_get_segment(
rtems_id id,
@@ -514,13 +548,18 @@ are defined by RTEMS:
A clock tick is required to support the timeout functionality of
this directive.
@c
@c
@c
@page
@subsection REGION_RETURN_SEGMENT - Return segment to a region
@cindex return segment to region
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_return_segment
@findex rtems_region_return_segment
@example
rtems_status_code rtems_region_return_segment(
rtems_id id,
@@ -568,13 +607,18 @@ and the following conditions exist:
is less than or equal to the size of the segment returned.
@end itemize
@c
@c
@c
@page
@subsection REGION_GET_SEGMENT_SIZE - Obtain size of a segment
@cindex get size of segment
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_region_get_segment_size
@findex rtems_region_get_segment_size
@example
rtems_status_code rtems_region_get_segment_size(
rtems_id id,

65
doc/user/rtmon.t
View File

@@ -14,6 +14,9 @@
@chapter Rate Monotonic Manager
@cindex rate mononitonic tasks
@cindex periodic tasks
@section Introduction
The rate monotonic manager provides facilities to
@@ -46,6 +49,8 @@ A clock tick is required to support the functionality provided by this manager.
@subsection Rate Monotonic Manager Definitions
@cindex periodic task, definition
A periodic task is one which must be executed at a
regular interval. The interval between successive iterations of
the task is referred to as its period. Periodic tasks can be
@@ -61,12 +66,16 @@ the execution time may be the average, worst, or best case, the
worst-case execution time is more appropriate for use when
analyzing system behavior under transient overload conditions.
@cindex aperiodic task, definition
In contrast, an aperiodic task executes at irregular
intervals and has only a soft deadline. In other words, the
deadlines for aperiodic tasks are not rigid, but adequate
response times are desirable. For example, an aperiodic task
may process user input from a terminal.
@cindex sporadic task, definition
Finally, a sporadic task is an aperiodic task with a
hard deadline and minimum interarrival time. The minimum
interarrival time is the minimum period of time which exists
@@ -78,6 +87,9 @@ but the missile must be launched by a hard deadline.
@subsection Rate Monotonic Scheduling Algorithm
@cindex Rate Monotonic Scheduling Algorithm, definition
@cindex RMS Algorithm, definition
The Rate Monotonic Scheduling Algorithm (RMS) is
important to real-time systems designers because it allows one
to guarantee that a set of tasks is schedulable. A set of tasks
@@ -196,6 +208,8 @@ schedulability is only guaranteed for the critical task set.
@subsection Schedulability Analysis
@cindex RMS schedulability analysis
RMS allows application designers to insure that tasks
can meet all deadlines, even under transient overload, without
knowing exactly when any given task will execute by applying
@@ -233,6 +247,8 @@ side-effects accounted for.
@subsection Processor Utilization Rule
@cindex RMS Processor Utilization Rule
The Processor Utilization Rule requires that
processor utilization be calculated based upon the period and
execution time of each task. The fraction of processor time
@@ -347,6 +363,8 @@ this task set is guaranteed to be schedulable using RMS.
@subsection First Deadline Rule
@cindex RMS First Deadline Rule
If a given set of tasks do exceed the processor
utilization upper limit imposed by the Processor Utilization
Rule, they can still be guaranteed to meet all their deadlines
@@ -828,13 +846,18 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period
@cindex create a period
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_rate_monotonic_create
@findex rtems_rate_monotonic_create
@example
rtems_status_code rtems_rate_monotonic_create(
rtems_name name,
@@ -872,13 +895,19 @@ initializes it.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_IDENT - Get ID of a period
@cindex get ID of a period
@cindex obtain ID of a period
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_rate_monotonic_ident
@findex rtems_rate_monotonic_ident
@example
rtems_status_code rtems_rate_monotonic_ident(
rtems_name name,
@@ -915,13 +944,18 @@ access this period in other rate monotonic manager directives.
This directive will not cause the running task to be
preempted.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_CANCEL - Cancel a period
@cindex cancel a period
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_rate_monotonic_cancel
@findex rtems_rate_monotonic_cancel
@example
rtems_status_code rtems_rate_monotonic_cancel(
rtems_id id
@@ -957,13 +991,18 @@ preempted.
The rate monotonic period specified by id must have
been created by the calling task.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period
@cindex delete a period
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_rate_monotonic_delete
@findex rtems_rate_monotonic_delete
@example
rtems_status_code rtems_rate_monotonic_delete(
rtems_id id
@@ -998,13 +1037,20 @@ preempted.
A rate monotonic period can be deleted by a task
other than the task which created the period.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period
@cindex conclude current period
@cindex start current period
@cindex period initiation
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_rate_monotonic_period
@findex rtems_rate_monotonic_period
@example
rtems_status_code rtems_rate_monotonic_period(
rtems_id id,
@@ -1049,14 +1095,19 @@ the state or period of the period.
This directive will not cause the running task to be preempted.
---------------------
@c
@c
@c
@page
@subsection RATE_MONOTONIC_GET_STATUS - Obtain status information on period
@cindex get status of period
@cindex obtain status of period
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_rate_monotonic_get_status
@findex rtems_rate_monotonic_get_status
@example
rtems_status_code rtems_rate_monotonic_get_status(
rtems_id id,

18
doc/user/schedule.t
View File

@@ -13,6 +13,9 @@
@chapter Scheduling Concepts
@cindex scheduling
@cindex task scheduling
@section Introduction
The concept of scheduling in real-time systems
@@ -49,6 +52,8 @@ events.
@section Scheduling Mechanisms
@cindex scheduling mechanisms
RTEMS provides four mechanisms which allow the user
to impact the task scheduling process:
@@ -74,6 +79,8 @@ description.
@subsection Task Priority and Scheduling
@cindex task priority
The most significant of these mechanisms is the
ability for the user to assign a priority level to each
individual task when it is created and to alter a task's
@@ -95,6 +102,8 @@ to a task.}
@subsection Preemption
@cindex preemption
Another way the user can alter the basic scheduling
algorithm is by manipulating the preemption mode flag
(@code{@value{RPREFIX}PREEMPT_MASK}) of individual tasks. If preemption is disabled
@@ -108,6 +117,9 @@ control of the processor.
@subsection Timeslicing
@cindex timeslicing
@cindex round robin scheduling
Timeslicing or round-robin scheduling is an
additional method which can be used to alter the basic
scheduling algorithm. Like preemption, timeslicing is specified
@@ -127,6 +139,8 @@ entire timeslice.
@subsection Manual Round-Robin
@cindex manual round robin
The final mechanism for altering the RTEMS scheduling
algorithm is called manual round-robin. Manual round-robin is
invoked by using the @code{@value{DIRPREFIX}task_wake_after}
@@ -139,6 +153,8 @@ of the processor.
@subsection Dispatching Tasks
@cindex dispatching
The dispatcher is the RTEMS component responsible for
allocating the processor to a ready task. In order to allocate
the processor to one task, it must be deallocated or retrieved
@@ -167,6 +183,8 @@ the last task to utilize the coprocessor.
@section Task State Transitions
@cindex task state transitions
Tasks in an RTEMS system must always be in one of the
five allowable task states. These states are: executing, ready,
blocked, dormant, and non-existent.

141
doc/user/sem.t
View File

@@ -8,6 +8,11 @@
@chapter Semaphore Manager
@cindex semaphores
@cindex binary semaphores
@cindex counting semaphores
@cindex mutual exclusion
@section Introduction
The semaphore manager utilizes standard Dijkstra
@@ -209,16 +214,15 @@ 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 @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}
because @code{@value{RPREFIX}LOCAL} is the default for all created tasks. If a
similar semaphore were to be known globally, then the
attribute_set parameter would be
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
@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} because @code{@value{RPREFIX}LOCAL} is the
default for all created tasks. If a similar semaphore were to be known
globally, then the attribute_set parameter would be
@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.
@subsection Building a SEMAPHORE_OBTAIN Option Set
@@ -233,13 +237,12 @@ in the following table:
@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
@end itemize
Option 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 option listed as a default is not
required to appear in the 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
Option 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 option
listed as a default is not required to appear in the 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.
This example demonstrates the option parameter needed
@@ -302,8 +305,8 @@ one of the following situations applies:
@item By default, the calling task will wait forever to
acquire the semaphore.
@item Specifying @code{@value{RPREFIX}NO_WAIT} forces an immediate return with an
error status code.
@item Specifying @code{@value{RPREFIX}NO_WAIT} 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.
@@ -327,7 +330,8 @@ be elevated.
The @code{@value{DIRPREFIX}semaphore_release} directive is used to release
the specified semaphore. A simplified version of the
@code{@value{DIRPREFIX}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
@@ -360,13 +364,18 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection SEMAPHORE_CREATE - Create a semaphore
@cindex create a semaphore
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_semaphore_create
@findex rtems_semaphore_create
@example
rtems_status_code rtems_semaphore_create(
rtems_name name,
@@ -462,13 +471,19 @@ The total number of global objects, including
semaphores, is limited by the maximum_global_objects field in
the Configuration Table.
@c
@c
@c
@page
@subsection SEMAPHORE_IDENT - Get ID of a semaphore
@cindex get ID of a semaphore
@cindex obtain ID of a semaphore
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_semaphore_ident
@findex rtems_semaphore_ident
@example
rtems_status_code rtems_semaphore_ident(
rtems_name name,
@@ -520,13 +535,18 @@ This directive does not generate activity on remote
nodes. It accesses only the local copy of the global object
table.
@c
@c
@c
@page
@subsection SEMAPHORE_DELETE - Delete a semaphore
@cindex delete a semaphore
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_semaphore_delete
@findex rtems_semaphore_delete
@example
rtems_status_code rtems_semaphore_delete(
rtems_id id
@@ -579,13 +599,19 @@ the semaphore was created with the @code{@value{RPREFIX}GLOBAL} option.
Proxies, used to represent remote tasks, are
reclaimed when the semaphore is deleted.
@c
@c
@c
@page
@subsection SEMAPHORE_OBTAIN - Acquire a semaphore
@cindex obtain a semaphore
@cindex lock a semaphore
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_semaphore_obtain
@findex rtems_semaphore_obtain
@example
rtems_status_code rtems_semaphore_obtain(
rtems_id id,
@@ -624,31 +650,30 @@ semaphore is not currently available. With either @code{@value{RPREFIX}WAIT} or
decremented by one and the semaphore is successfully acquired by
returning immediately with a successful return code.
If the calling task chooses to return immediately and
the current semaphore count is zero or negative, then a status
code is returned indicating that the semaphore is not available.
If the calling task chooses to wait for a semaphore and the
current semaphore count is zero or negative, then it is
decremented by one and the calling task is placed on the
semaphore's wait queue and blocked. If the semaphore was
created with the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is
inserted into the queue according to its priority. However, if
the semaphore was created with the @code{@value{RPREFIX}FIFO} attribute, then the
calling task is placed at the rear of the wait queue. If the
binary semaphore was created with the @code{@value{RPREFIX}INHERIT_PRIORITY}
attribute, then the priority of the task currently holding the
binary semaphore is guaranteed to be greater than or equal to
that of the blocking task. If the binary semaphore was created
with the @code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully obtains
the semaphore, and the priority of that task is greater than the
ceiling priority for this semaphore, then the priority of the
task obtaining the semaphore is elevated to that of the ceiling.
If the calling task chooses to return immediately and the current
semaphore count is zero or negative, then a status code is returned
indicating that the semaphore is not available. If the calling task
chooses to wait for a semaphore and the current semaphore count is zero or
negative, then it is decremented by one and the calling task is placed on
the semaphore's wait queue and blocked. If the semaphore was created with
the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is
inserted into the queue according to its priority. However, if the
semaphore was created with the @code{@value{RPREFIX}FIFO} attribute, then
the calling task is placed at the rear of the wait queue. If the binary
semaphore was created with the @code{@value{RPREFIX}INHERIT_PRIORITY}
attribute, then the priority of the task currently holding the binary
semaphore is guaranteed to be greater than or equal to that of the
blocking task. If the binary semaphore was created with the
@code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully
obtains the semaphore, and the priority of that task is greater than the
ceiling priority for this semaphore, then the priority of the task
obtaining the semaphore is elevated to that of the ceiling.
The timeout parameter specifies the maximum interval
the calling task is willing to be blocked waiting for the
semaphore. If it is set to @code{@value{RPREFIX}NO_TIMEOUT}, then the calling task
will wait forever. If the semaphore is available or the @code{@value{RPREFIX}NO_WAIT}
option component is set, then timeout is ignored.
The timeout parameter specifies the maximum interval the calling task is
willing to be blocked waiting for the semaphore. If it is set to
@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever.
If the semaphore is available or the @code{@value{RPREFIX}NO_WAIT} option
component is set, then timeout is ignored.
@subheading NOTES:
The following semaphore acquisition option constants
@@ -659,23 +684,29 @@ are defined by RTEMS:
@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
@end itemize
Attempting to obtain a global semaphore which does not reside on
the local node will generate a request to the remote node to
access the semaphore. If the semaphore is not available and
@code{@value{RPREFIX}NO_WAIT} was not specified, then the task must be blocked until
the semaphore is released. A proxy is allocated on the remote
node to represent the task until the semaphore is released.
Attempting to obtain a global semaphore which does not reside on the local
node will generate a request to the remote node to access the semaphore.
If the semaphore is not available and @code{@value{RPREFIX}NO_WAIT} was
not specified, then the task must be blocked until the semaphore is
released. A proxy is allocated on the remote node to represent the task
until the semaphore is released.
A clock tick is required to support the timeout functionality of
this directive.
@c
@c
@c
@page
@subsection SEMAPHORE_RELEASE - Release a semaphore
@cindex release a semaphore
@cindex unlock a semaphore
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_semaphore_release
@findex rtems_semaphore_release
@example
rtems_status_code rtems_semaphore_release(
rtems_id id

27
doc/user/signal.t
View File

@@ -8,6 +8,8 @@
@chapter Signal Manager
@cindex signals
@section Introduction
The signal manager provides the capabilities required
@@ -23,6 +25,9 @@ signal manager are:
@subsection Signal Manager Definitions
@cindex asynchronous signal routine
@cindex ASR
The signal manager allows a task to optionally define
an asynchronous signal routine (ASR). An ASR is to a task what
an ISR is to an application's set of tasks. When the processor
@@ -43,6 +48,9 @@ with a valid ASR, but has not been processed by that task's ASR.
@subsection A Comparison of ASRs and ISRs
@cindex ASR vs. ISR
@cindex ISR vs. ASR
The format of an ASR is similar to that of an ISR
with the following exceptions:
@@ -65,6 +73,8 @@ result, does not have a task mode.
@subsection Building a Signal Set
@cindex signal set, building
A signal set is built by a bitwise OR of the desired
signals. The set of valid signals is @code{@value{RPREFIX}SIGNAL_0} through
@code{@value{RPREFIX}SIGNAL_31}. If a signal is not explicitly specified in the
@@ -84,6 +94,8 @@ to the @code{@value{DIRPREFIX}signal_send} directive should be
@subsection Building an ASR Mode
@cindex ASR mode, building
In general, an ASR's mode is built by a bitwise OR of
the desired mode components. The set of valid mode components
is the same as those allowed with the task_create and task_mode
@@ -230,13 +242,19 @@ A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
@c
@c
@c
@page
@subsection SIGNAL_CATCH - Establish an ASR
@cindex establish an ASR
@cindex install an ASR
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_signal_catch
@findex rtems_signal_catch
@example
rtems_status_code rtems_signal_catch(
rtems_asr_entry asr_handler,
@@ -302,13 +320,18 @@ The following task mode constants are defined by RTEMS:
@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
@end itemize
@c
@c
@c
@page
@subsection SIGNAL_SEND - Send signal set to a task
@cindex send signal set
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_signal_send
@findex rtems_signal_send
@example
rtems_status_code rtems_signal_send(
rtems_id id,

91
doc/user/task.t
View File

@@ -8,6 +8,8 @@
@chapter Task Manager
@cindex tasks
@section Introduction
The task manager provides a comprehensive set of directives to
@@ -35,6 +37,8 @@ by the task manager are:
@subsection Task Definition
@cindex 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
@@ -87,6 +91,8 @@ the task's TCB.
@subsection Task States
@cindex task states
A task may exist in one of the following five states:
@itemize @bullet
@@ -109,6 +115,9 @@ current state and priority.
@subsection Task Priority
@cindex task priority
@cindex priority, task
A task's priority determines its importance in relation to the
other tasks executing on the same processor. RTEMS supports 255
levels of priority ranging from 1 to 255. Tasks of numerically
@@ -130,6 +139,8 @@ processor execution time.
@subsection Task Mode
@cindex task mode
A task's mode is a combination of the following four components:
@itemize @bullet
@@ -142,6 +153,8 @@ 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.
@cindex preemption
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
@@ -151,6 +164,8 @@ priority task is made ready. If preemption is enabled
then the processor will be taken away from the current task immediately and
given to the higher priority task.
@cindex timeslicing
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
@@ -171,6 +186,8 @@ 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.
@cindex interrupt level, task
The interrupt level component is used to determine which
interrupts will be enabled when the task is executing.
@code{@value{RPREFIX}INTERRUPT_LEVEL(n)}
@@ -189,6 +206,8 @@ specifies that the task will execute at interrupt level n.
@subsection Accessing Task Arguments
@cindex task arguments
All RTEMS tasks are invoked with a single argument which is
specified when they are started or restarted. The argument is
commonly used to communicate startup information to the task.
@@ -216,6 +235,8 @@ single argument as an index into an array of parameter blocks.
@subsection Floating Point Considerations
@cindex floating point
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
@@ -267,6 +288,8 @@ generally result in an exception condition.
@subsection Building a Task Attribute Set
@cindex task attributes, building
In general, an attribute set is built by a bitwise OR of the
desired components. The set of valid task attribute components
is listed below:
@@ -298,6 +321,8 @@ coprocessor, then the attribute_set parameter would be
@subsection Building a Mode and Mask
@cindex task mode, building
In general, a mode and its corresponding mask is built by a
bitwise OR of the desired components. The set of valid mode
constants and each mode's corresponding mask constant is
@@ -598,10 +623,12 @@ status codes.
@subsection TASK_CREATE - Create a task
@cindex create a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_create
@findex rtems_task_create
@example
rtems_status_code rtems_task_create(
rtems_name name,
@@ -708,10 +735,12 @@ by the maximum_global_objects field in the Configuration Table.
@subsection TASK_IDENT - Get ID of a task
@cindex get ID of a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_ident
@findex rtems_task_ident
@example
rtems_status_code rtems_task_ident(
rtems_name name,
@@ -764,10 +793,12 @@ accesses only the local copy of the global object table.
@subsection TASK_START - Start a task
@cindex starting a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_start
@findex rtems_task_start
@example
rtems_status_code rtems_task_start(
rtems_id id,
@@ -815,10 +846,12 @@ the @code{@value{DIRPREFIX}task_start} directive.
@subsection TASK_RESTART - Restart a task
@cindex restarting a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_restart
@findex rtems_task_restart
@example
rtems_status_code rtems_task_restart(
rtems_id id,
@@ -878,10 +911,12 @@ created with the @code{@value{RPREFIX}GLOBAL} option.
@subsection TASK_DELETE - Delete a task
@cindex deleting a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_delete
@findex rtems_task_delete
@example
rtems_status_code rtems_task_delete(
rtems_id id
@@ -936,10 +971,12 @@ created with the @code{@value{RPREFIX}GLOBAL} option.
@subsection TASK_SUSPEND - Suspend a task
@cindex suspending a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_suspend
@findex rtems_task_suspend
@example
rtems_status_code rtems_task_suspend(
rtems_id id
@@ -986,10 +1023,12 @@ If the task specified by id is already suspended, then the
@subsection TASK_RESUME - Resume a task
@cindex resuming a task
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_resume
@findex rtems_task_resume
@example
rtems_status_code rtems_task_resume(
rtems_id id
@@ -1033,10 +1072,12 @@ If the task specified by id is not suspended, then the
@subsection TASK_IS_SUSPENDED - Determine if a task is Suspended
@cindex is task suspended
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_is_suspended
@findex rtems_task_is_suspended
@example
rtems_status_code rtems_task_is_suspended(
rtems_id id
@@ -1072,10 +1113,15 @@ This operation is not currently supported on remote tasks.
@subsection TASK_SET_PRIORITY - Set task priority
@findex rtems_task_set_priority
@cindex current task priority
@cindex set task priority
@cindex get task priority
@cindex obtain task priority
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_set_priority
@example
rtems_status_code rtems_task_set_priority(
rtems_id id,
@@ -1136,10 +1182,17 @@ binary semaphores.
@subsection TASK_MODE - Change the current task mode
@cindex current task mode
@cindex set task mode
@cindex get task mode
@cindex set task preemption mode
@cindex get task preemption mode
@cindex obtain task mode
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_mode
@findex rtems_task_mode
@example
rtems_status_code rtems_task_mode(
rtems_mode mode_set,
@@ -1292,10 +1345,12 @@ mask constant is provided in the following table:
@subsection TASK_GET_NOTE - Get task notepad entry
@cindex get task notepad entry
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_get_note
@findex rtems_task_get_note
@example
rtems_status_code rtems_task_get_note(
rtems_id id,
@@ -1346,10 +1401,12 @@ the notepad entry of the specified task.
@subsection TASK_SET_NOTE - Set task notepad entry
@cindex set task notepad entry
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_set_note
@findex rtems_task_set_note
@example
rtems_status_code rtems_task_set_note(
rtems_id id,
@@ -1400,10 +1457,13 @@ node to set the specified notepad entry.
@subsection TASK_WAKE_AFTER - Wake up after interval
@cindex delay a task for an interval
@cindex wake up after an interval
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_wake_after
@findex rtems_task_wake_after
@example
rtems_status_code rtems_task_wake_after(
rtems_interval ticks
@@ -1446,10 +1506,13 @@ A clock tick is required to support the functionality of this directive.
@subsection TASK_WAKE_WHEN - Wake up when specified
@cindex delay a task until a wall time
@cindex wake up at a wall time
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_task_wake_when
@findex rtems_task_wake_when
@example
rtems_status_code rtems_task_wake_when(
rtems_time_of_day *time_buffer

51
doc/user/timer.t
View File

@@ -8,6 +8,8 @@
@chapter Timer Manager
@cindex timers
@section Introduction
The timer manager provides support for timer
@@ -152,13 +154,18 @@ A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
@c
@c
@c
@page
@subsection TIMER_CREATE - Create a timer
@cindex create a timer
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_create
@findex rtems_timer_create
@example
rtems_status_code rtems_timer_create(
rtems_name name,
@@ -195,13 +202,18 @@ and initializes it.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection TIMER_IDENT - Get ID of a timer
@cindex obtain the ID of a timer
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_ident
@findex rtems_timer_ident
@example
rtems_status_code rtems_timer_ident(
rtems_name name,
@@ -238,13 +250,18 @@ other timer related directives.
This directive will not cause the running task to be
preempted.
@c
@c
@c
@page
@subsection TIMER_CANCEL - Cancel a timer
@cindex cancel a timer
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_cancel
@findex rtems_timer_cancel
@example
rtems_status_code rtems_timer_cancel(
rtems_id id
@@ -276,13 +293,18 @@ be reinitiated by the next invocation of @code{@value{DIRPREFIX}timer_reset},
This directive will not cause the running task to be preempted.
@c
@c
@c
@page
@subsection TIMER_DELETE - Delete a timer
@cindex delete a timer
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_delete
@findex rtems_timer_delete
@example
rtems_status_code rtems_timer_delete(
rtems_id id
@@ -317,13 +339,18 @@ preempted.
A timer can be deleted by a task other than the task
which created the timer.
@c
@c
@c
@page
@subsection TIMER_FIRE_AFTER - Fire timer after interval
@cindex fire a timer after an interval
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_fire_after
@findex rtems_timer_fire_after
@example
rtems_status_code rtems_timer_fire_after(
rtems_id id,
@@ -365,13 +392,18 @@ argument user_data.
This directive will not cause the running task to be
preempted.
@c
@c
@c
@page
@subsection TIMER_FIRE_WHEN - Fire timer when specified
@cindex fire a timer at wall time
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_fire_when
@findex rtems_timer_fire_when
@example
rtems_status_code rtems_timer_fire_when(
rtems_id id,
@@ -414,13 +446,18 @@ user_data.
This directive will not cause the running task to be
preempted.
@c
@c
@c
@page
@subsection TIMER_RESET - Reset an interval timer
@cindex reset a timer
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_timer_reset
@findex rtems_timer_reset
@example
rtems_status_code rtems_timer_reset(
rtems_id id

28
doc/user/userext.t
View File

@@ -8,6 +8,8 @@
@chapter User Extensions Manager
@cindex user extensions
@section Introduction
The RTEMS User Extensions Manager allows the
@@ -44,6 +46,8 @@ arguments that are appropriate to the system event.
@subsection Extension Sets
@cindex extension set
An extension set is defined as a set of routines
which are invoked at each of the critical system events at which
user extension routines are invoked. Together a set of these
@@ -118,6 +122,8 @@ naming restrictions on the user.
@subsection TCB Extension Area
@cindex TCB extension area
RTEMS provides for a pointer to a user-defined data
area for each extension set to be linked to each task's control
block. This set of pointers is an extension of the TCB and can
@@ -525,13 +531,18 @@ directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
@c
@c
@c
@page
@subsection EXTENSION_CREATE - Create a extension set
@cindex create an extension set
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_extension_create
@findex rtems_extension_create
@example
rtems_status_code rtems_extension_create(
rtems_name name,
@@ -571,13 +582,19 @@ it.
This directive will not cause the calling task to be
preempted.
@c
@c
@c
@page
@subsection EXTENSION_IDENT - Get ID of a extension set
@cindex get ID of an extension set
@cindex obtain ID of an extension set
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_extension_ident
@findex rtems_extension_ident
@example
rtems_status_code rtems_extension_ident(
rtems_name name,
@@ -615,13 +632,18 @@ extension set in other extension set related directives.
This directive will not cause the running task to be
preempted.
@c
@c
@c
@page
@subsection EXTENSION_DELETE - Delete a extension set
@cindex delete an extension set
@subheading CALLING SEQUENCE:
@ifset is-C
@c @findex rtems_extension_delete
@findex rtems_extension_delete
@example
rtems_status_code rtems_extension_delete(
rtems_id id