rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-04 16:57:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

Clean ups.

Browse Source
This commit is contained in:
Chris Johns 2016-01-27 17:50:19 +11:00 committed by Amar Takhar
parent eccd84e752
commit 8ef6ea80ef
12 changed files with 2604 additions and 2454 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

405
c_user/barrier_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Barrier Manager
###############
@ -6,85 +10,84 @@ Barrier Manager
Introduction
============
The barrier manager provides a unique synchronization
capability which can be used to have a set of tasks block
and be unblocked as a set. The directives provided by the
barrier manager are:
The barrier manager provides a unique synchronization capability which can be
used to have a set of tasks block and be unblocked as a set. The directives
provided by the barrier manager are:
- ``rtems_barrier_create`` - Create a barrier
- rtems_barrier_create_ - Create a barrier
- ``rtems_barrier_ident`` - Get ID of a barrier
- rtems_barrier_ident_ - Get ID of a barrier
- ``rtems_barrier_delete`` - Delete a barrier
- rtems_barrier_delete_ - Delete a barrier
- ``rtems_barrier_wait`` - Wait at a barrier
- rtems_barrier_wait_ - Wait at a barrier
- ``rtems_barrier_release`` - Release a barrier
- rtems_barrier_release_ - Release a barrier
Background
==========
A barrier can be viewed as a gate at which tasks wait until
the gate is opened. This has many analogies in the real world.
Horses and other farm animals may approach a closed gate and
gather in front of it, waiting for someone to open the gate so
they may proceed. Similarly, cticket holders gather at the gates
of arenas before concerts or sporting events waiting for the
arena personnel to open the gates so they may enter.
A barrier can be viewed as a gate at which tasks wait until the gate is opened.
This has many analogies in the real world. Horses and other farm animals may
approach a closed gate and gather in front of it, waiting for someone to open
the gate so they may proceed. Similarly, cticket holders gather at the gates
of arenas before concerts or sporting events waiting for the arena personnel to
open the gates so they may enter.
Barriers are useful during application initialization. Each
application task can perform its local initialization before
waiting for the application as a whole to be initialized. Once
all tasks have completed their independent initializations,
the "application ready" barrier can be released.
Barriers are useful during application initialization. Each application task
can perform its local initialization before waiting for the application as a
whole to be initialized. Once all tasks have completed their independent
initializations, the "application ready" barrier can be released.
Automatic Versus Manual Barriers
--------------------------------
Just as with a real-world gate, barriers may be configured to
be manually opened or automatically opened. All tasks
calling the ``rtems_barrier_wait`` directive
will block until a controlling task invokes the``rtems_barrier_release`` directive.
Just as with a real-world gate, barriers may be configured to be manually
opened or automatically opened. All tasks calling the ``rtems_barrier_wait``
directive will block until a controlling task invokes
the ``rtems_barrier_release`` directive.
Automatic barriers are created with a limit to the number of
tasks which may simultaneously block at the barrier. Once
this limit is reached, all of the tasks are released. For
example, if the automatic limit is ten tasks, then the first
nine tasks calling the ``rtems_barrier_wait`` directive
will block. When the tenth task calls the``rtems_barrier_wait`` directive, the nine
blocked tasks will be released and the tenth task returns
to the caller without blocking.
Automatic barriers are created with a limit to the number of tasks which may
simultaneously block at the barrier. Once this limit is reached, all of the
tasks are released. For example, if the automatic limit is ten tasks, then the
first nine tasks calling the ``rtems_barrier_wait`` directive will block. When
the tenth task calls the``rtems_barrier_wait`` directive, the nine blocked
tasks will be released and the tenth task returns to the caller without
blocking.
Building a Barrier Attribute Set
--------------------------------
In general, an attribute set is built by a bitwise OR
of the desired attribute components. The following table lists
the set of valid barrier attributes:
In general, an attribute set is built by a bitwise OR of the desired attribute
components. The following table lists the set of valid barrier attributes:
- ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - automatically
release the barrier when the configured number of tasks are blocked
``RTEMS_BARRIER_AUTOMATIC_RELEASE``
automatically release the barrier when the configured number of tasks are
blocked
- ``RTEMS_BARRIER_MANUAL_RELEASE`` - only release
the barrier when the application invokes the``rtems_barrier_release`` directive. (default)
``RTEMS_BARRIER_MANUAL_RELEASE``
only release the barrier when the application invokes the
``rtems_barrier_release`` directive. (default)
*NOTE*: Barriers only support FIFO blocking order because all
waiting tasks are released as a set. Thus the released tasks
will all become ready to execute at the same time and compete
for the processor based upon their priority.
.. note::
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``RTEMS_DEFAULT_ATTRIBUTES`` should be
specified on this call.
Barriers only support FIFO blocking order because all waiting tasks are
released as a set. Thus the released tasks will all become ready to execute
at the same time and compete for the processor based upon their priority.
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 ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
call.
This example demonstrates the attribute_set parameter needed to create a
barrier with the automatic release policy. The``attribute_set`` parameter passed to the``rtems_barrier_create`` directive will be``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the
user must also specify the *maximum_waiters* parameter.
barrier with the automatic release policy. The ``attribute_set`` parameter
passed to the ``rtems_barrier_create`` directive will be
``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the user must also specify
the ``maximum_waiters`` parameter.
Operations
==========
@ -92,24 +95,22 @@ Operations
Creating a Barrier
------------------
The ``rtems_barrier_create`` directive creates
a barrier with a user-specified name and the desired attributes.
RTEMS allocates a Barrier Control Block (BCB) from the BCB free list.
This data structure is used by RTEMS to manage the newly created
barrier. Also, a unique barrier ID is generated and returned to
The ``rtems_barrier_create`` directive creates a barrier with a user-specified
name and the desired attributes. RTEMS allocates a Barrier Control Block (BCB)
from the BCB free list. This data structure is used by RTEMS to manage the
newly created barrier. Also, a unique barrier ID is generated and returned to
the calling task.
Obtaining Barrier IDs
---------------------
When a barrier is created, RTEMS generates a unique
barrier ID and assigns it to the created barrier until it is
deleted. The barrier ID may be obtained by either of two
methods. First, as the result of an invocation of the``rtems_barrier_create`` directive, the
barrier ID is stored in a user provided location. Second,
the barrier ID may be obtained later using the``rtems_barrier_ident`` directive. The barrier ID is
used by other barrier manager directives to access this
barrier.
When a barrier is created, RTEMS generates a unique barrier ID and assigns it
to the created barrier until it is deleted. The barrier ID may be obtained by
either of two methods. First, as the result of an invocation of
the``rtems_barrier_create`` directive, the barrier ID is stored in a user
provided location. Second, the barrier ID may be obtained later using the
``rtems_barrier_ident`` directive. The barrier ID is used by other barrier
manager directives to access this barrier.
Waiting at a Barrier
--------------------
@ -120,42 +121,40 @@ the task may wait forever for the barrier to be released or it may
specify a timeout. Specifying a timeout limits the interval the task will
wait before returning with an error status code.
If the barrier is configured as automatic and there are already
one less then the maximum number of waiters, then the call will
unblock all tasks waiting at the barrier and the caller will
return immediately.
If the barrier is configured as automatic and there are already one less then
the maximum number of waiters, then the call will unblock all tasks waiting at
the barrier and the caller will return immediately.
When the task does wait to acquire the barrier, then it
is placed in the barrier's task wait queue in FIFO order.
All tasks waiting on a barrier are returned an error
code when the barrier is deleted.
When the task does wait to acquire the barrier, then it is placed in the
barrier's task wait queue in FIFO order. All tasks waiting on a barrier are
returned an error code when the barrier is deleted.
Releasing a Barrier
-------------------
The ``rtems_barrier_release`` directive is used to release
the specified barrier. When the ``rtems_barrier_release``
is invoked, all tasks waiting at the barrier are immediately made ready
to execute and begin to compete for the processor to execute.
The ``rtems_barrier_release`` directive is used to release the specified
barrier. When the ``rtems_barrier_release`` is invoked, all tasks waiting at
the barrier are immediately made ready to execute and begin to compete for the
processor to execute.
Deleting a Barrier
------------------
The ``rtems_barrier_delete`` directive removes a barrier
from the system and frees its control block. A barrier can be
deleted by any local task that knows the barrier's ID. As a
result of this directive, all tasks blocked waiting for the
barrier to be released, will be readied and returned a status code which
indicates that the barrier was deleted. Any subsequent
references to the barrier's name and ID are invalid.
The ``rtems_barrier_delete`` directive removes a barrier from the system and
frees its control block. A barrier can be deleted by any local task that knows
the barrier's ID. As a result of this directive, all tasks blocked waiting for
the barrier to be released, will be readied and returned a status code which
indicates that the barrier was deleted. Any subsequent references to the
barrier's name and ID are invalid.
Directives
==========
This section details the barrier manager's
directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
This section details the barrier manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_barrier_create:
BARRIER_CREATE - Create a barrier
---------------------------------
@ -171,37 +170,49 @@ BARRIER_CREATE - Create a barrier
rtems_name name,
rtems_attribute attribute_set,
uint32_t maximum_waiters,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - barrier created successfully
``RTEMS_INVALID_NAME`` - invalid barrier name
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_TOO_MANY`` - too many barriers created
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- barrier created successfully
* - ``RTEMS_INVALID_NAME``
- invalid barrier name
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_TOO_MANY``
- too many barriers created
**DESCRIPTION:**
This directive creates a barrier which resides on
the local node. The created barrier has the user-defined name
specified in ``name`` and the initial count specified in ``count``. For
control and maintenance of the barrier, RTEMS allocates and
initializes a BCB. The RTEMS-assigned barrier id is returned
in ``id``. This barrier id is used with other barrier related
directives to access the barrier.
This directive creates a barrier which resides on the local node. The created
barrier has the user-defined name specified in ``name`` and the initial count
specified in ``count``. For control and maintenance of the barrier, RTEMS
allocates and initializes a BCB. The RTEMS-assigned barrier id is returned in
``id``. This barrier id is used with other barrier related directives to
access the barrier.
``RTEMS_BARRIER_MANUAL_RELEASE`` - only release
.. list-table::
:class: rtems-table
Specifying ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` in``attribute_set`` causes tasks calling the``rtems_barrier_wait`` directive to block until
there are ``maximum_waiters - 1`` tasks waiting at the barrier.
When the ``maximum_waiters`` task invokes the``rtems_barrier_wait`` directive, the previous``maximum_waiters - 1`` tasks are automatically released
and the caller returns.
* - ``RTEMS_BARRIER_MANUAL_RELEASE``
- only release
In contrast, when the ``RTEMS_BARRIER_MANUAL_RELEASE``
attribute is specified, there is no limit on the number of
tasks that will block at the barrier. Only when the``rtems_barrier_release`` directive is invoked,
are the tasks waiting at the barrier unblocked.
Specifying ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` in ``attribute_set`` causes
tasks calling the ``rtems_barrier_wait`` directive to block until there are
``maximum_waiters - 1`` tasks waiting at the barrier. When the
``maximum_waiters`` task invokes the ``rtems_barrier_wait`` directive, the
previous ``maximum_waiters - 1`` tasks are automatically released and the
caller returns.
In contrast, when the ``RTEMS_BARRIER_MANUAL_RELEASE`` attribute is specified,
there is no limit on the number of tasks that will block at the barrier. Only
when the ``rtems_barrier_release`` directive is invoked, are the tasks waiting
at the barrier unblocked.
**NOTES:**
@ -209,11 +220,17 @@ This directive will not cause the calling task to be preempted.
The following barrier attribute constants are defined by RTEMS:
- ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - automatically
release the barrier when the configured number of tasks are blocked
.. list-table::
:class: rtems-table
- ``RTEMS_BARRIER_MANUAL_RELEASE`` - only release
the barrier when the application invokes the``rtems_barrier_release`` directive. (default)
* - ``RTEMS_BARRIER_AUTOMATIC_RELEASE``
- automatically release the barrier when the configured number of tasks are
blocked
* - ``RTEMS_BARRIER_MANUAL_RELEASE``
- only release the barrier when the application invokes
the ``rtems_barrier_release`` directive. (default)
.. _rtems_barrier_ident:
BARRIER_IDENT - Get ID of a barrier
-----------------------------------
@ -228,28 +245,34 @@ BARRIER_IDENT - Get ID of a barrier
rtems_status_code rtems_barrier_ident(
rtems_name name,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - barrier identified successfully
``RTEMS_INVALID_NAME`` - barrier name not found
``RTEMS_INVALID_NODE`` - invalid node id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- barrier identified successfully
* - ``RTEMS_INVALID_NAME``
- barrier name not found
* - ``RTEMS_INVALID_NODE``
- invalid node id
**DESCRIPTION:**
This directive obtains the barrier id associated
with the barrier name. If the barrier name is not unique,
then the barrier id will match one of the barriers with that
name. However, this barrier id is not guaranteed to
correspond to the desired barrier. The barrier id is used
by other barrier related directives to access the barrier.
This directive obtains the barrier id associated with the barrier name. If the
barrier name is not unique, then the barrier id will match one of the barriers
with that name. However, this barrier id is not guaranteed to correspond to
the desired barrier. The barrier id is used by other barrier related
directives to access the barrier.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
.. _rtems_barrier_delete:
BARRIER_DELETE - Delete a barrier
---------------------------------
@ -267,30 +290,32 @@ BARRIER_DELETE - Delete a barrier
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - barrier deleted successfully
``RTEMS_INVALID_ID`` -c invalid barrier id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- barrier deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid barrier id
**DESCRIPTION:**
This directive deletes the barrier specified by ``id``.
All tasks blocked waiting for the barrier to be released will be
readied and returned a status code which indicates that the
barrier was deleted. The BCB for this barrier is reclaimed
by RTEMS.
This directive deletes the barrier specified by ``id``. All tasks blocked
waiting for the barrier to be released will be readied and returned a status
code which indicates that the barrier was deleted. The BCB for this barrier is
reclaimed by RTEMS.
**NOTES:**
The calling task will be preempted if it is enabled
by the task's execution mode and a higher priority local task is
waiting on the deleted barrier. The calling task will NOT be
preempted if all of the tasks that are waiting on the barrier
are remote tasks.
The calling task will be preempted if it is enabled by the task's execution
mode and a higher priority local task is waiting on the deleted barrier. The
calling task will NOT be preempted if all of the tasks that are waiting on the
barrier are remote tasks.
The calling task does not have to be the task that
created the barrier. Any local task that knows the barrier
id can delete the barrier.
The calling task does not have to be the task that created the barrier. Any
local task that knows the barrier id can delete the barrier.
.. COMMENT: Barrier Obtain
.. _rtems_barrier_wait:
BARRIER_OBTAIN - Acquire a barrier
----------------------------------
@ -310,48 +335,59 @@ BARRIER_OBTAIN - Acquire a barrier
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - barrier released and task unblocked
``RTEMS_UNSATISFIED`` - barrier not available
``RTEMS_TIMEOUT`` - timed out waiting for barrier
``RTEMS_OBJECT_WAS_DELETED`` - barrier deleted while waiting
``RTEMS_INVALID_ID`` - invalid barrier id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- barrier released and task unblocked
* - ``RTEMS_UNSATISFIED``
- barrier not available
* - ``RTEMS_TIMEOUT``
- timed out waiting for barrier
* - ``RTEMS_OBJECT_WAS_DELETED``
- barrier deleted while waiting
* - ``RTEMS_INVALID_ID``
- invalid barrier id
**DESCRIPTION:**
This directive acquires the barrier specified by
id. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT``
components of the options parameter indicate whether the calling task
wants to wait for the barrier to become available or return immediately
if the barrier is not currently available. With either``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``,
if the current barrier count is positive, then it is
decremented by one and the barrier is successfully acquired by
This directive acquires the barrier specified by ``id``. The ``RTEMS_WAIT``
and ``RTEMS_NO_WAIT`` components of the options parameter indicate whether the
calling task wants to wait for the barrier to become available or return
immediately if the barrier is not currently available. With either
``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current barrier count is positive,
then it is decremented by one and the barrier is successfully acquired by
returning immediately with a successful return code.
Conceptually, the calling task should always be thought
of as blocking when it makes this call and being unblocked when
the barrier is released. If the barrier is configured for
manual release, this rule of thumb will always be valid.
If the barrier is configured for automatic release, all callers
will block except for the one which is the Nth task which trips
the automatic release condition.
Conceptually, the calling task should always be thought of as blocking when it
makes this call and being unblocked when the barrier is released. If the
barrier is configured for manual release, this rule of thumb will always be
valid. If the barrier is configured for automatic release, all callers will
block except for the one which is the Nth task which trips the automatic
release condition.
The timeout parameter specifies the maximum interval the calling task is
willing to be blocked waiting for the barrier. If it is set to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
If the barrier is available or the ``RTEMS_NO_WAIT`` option
component is set, then timeout is ignored.
willing to be blocked waiting for the barrier. If it is set to
``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the barrier
is available or the ``RTEMS_NO_WAIT`` option component is set, then timeout is
ignored.
**NOTES:**
The following barrier acquisition option constants are defined by RTEMS:
- ``RTEMS_WAIT`` - task will wait for barrier (default)
.. list-table::
:class: rtems-table
- ``RTEMS_NO_WAIT`` - task should not wait
* - ``RTEMS_WAIT``
- task will wait for barrier (default)
* - ``RTEMS_NO_WAIT``
- task should not wait
A clock tick is required to support the timeout functionality of
this directive.
A clock tick is required to support the timeout functionality of this
directive.
.. COMMENT: Release Barrier
.. _rtems_barrier_release:
BARRIER_RELEASE - Release a barrier
-----------------------------------
@ -366,29 +402,26 @@ BARRIER_RELEASE - Release a barrier
rtems_status_code rtems_barrier_release(
rtems_id id,
uint32_t \*released
uint32_t *released
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - barrier released successfully
``RTEMS_INVALID_ID`` - invalid barrier id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- barrier released successfully
* - ``RTEMS_INVALID_ID``
- invalid barrier id
**DESCRIPTION:**
This directive releases the barrier specified by id.
All tasks waiting at the barrier will be unblocked.
If the running task's preemption mode is enabled and one of
the unblocked tasks has a higher priority than the running task.
This directive releases the barrier specified by id. All tasks waiting at the
barrier will be unblocked. If the running task's preemption mode is enabled
and one of the unblocked tasks has a higher priority than the running task.
**NOTES:**
The calling task may be preempted if it causes a
higher priority task to be made ready for execution.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
The calling task may be preempted if it causes a higher priority task to be
made ready for execution.

358
c_user/board_support_packages.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Board Support Packages
######################
@ -8,87 +12,80 @@ Introduction
============
.. index:: 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
may include hardware initialization, device drivers, user
extensions, and a Multiprocessor Communications Interface
(MPCI). However, a minimal BSP need only support processor
reset and initialization and, if needed, a clock tick.
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 may include hardware initialization, device drivers, user
extensions, and a Multiprocessor Communications Interface (MPCI). However, a
minimal BSP need only support processor reset and initialization and, if
needed, a clock tick.
Reset and Initialization
========================
An RTEMS based application is initiated or
re-initiated when the processor is reset. This initialization
code is responsible for preparing the target platform for the
RTEMS application. Although the exact actions performed by the
initialization code are highly processor and target dependent,
the logical functionality of these actions are similar across a
variety of processors and target platforms.
An RTEMS based application is initiated or re-initiated when the processor is
reset. This initialization code is responsible for preparing the target
platform for the RTEMS application. Although the exact actions performed by
the initialization code are highly processor and target dependent, the logical
functionality of these actions are similar across a variety of processors and
target platforms.
Normally, the BSP and some of the application initialization is
intertwined in the RTEMS initialization sequence controlled by
the shared function ``boot_card()``.
Normally, the BSP and some of the application initialization is intertwined in
the RTEMS initialization sequence controlled by the shared function
``boot_card()``.
The reset application initialization code is executed
first when the processor is reset. All of the hardware must be
initialized to a quiescent state by this software before
initializing RTEMS. When in quiescent state, devices do not
generate any interrupts or require any servicing by the
application. Some of the hardware components may be initialized
in this code as well as any application initialization that does
not involve calls to RTEMS directives.
The reset application initialization code is executed first when the processor
is reset. All of the hardware must be initialized to a quiescent state by this
software before initializing RTEMS. When in quiescent state, devices do not
generate any interrupts or require any servicing by the application. Some of
the hardware components may be initialized in this code as well as any
application initialization that does not involve calls to RTEMS directives.
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 context switch to the first task,
the Interrupt Vector Table MUST be set before this directive is invoked
to ensure correct interrupt vectoring. The processor's Interrupt Vector
Table must be accessible by RTEMS as it will be modified by the when
installing user Interrupt Service Routines (ISRs) 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 any RTEMS initialization routines has the
following requirements:
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 context switch to the first task, the Interrupt Vector Table MUST
be set before this directive is invoked to ensure correct interrupt vectoring.
The processor's Interrupt Vector Table must be accessible by RTEMS as it will
be modified by the when installing user Interrupt Service Routines (ISRs) 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 any RTEMS initialization routines has
the following requirements:
- Must not make any blocking RTEMS directive calls.
- If the processor supports multiple privilege levels, must leave
the processor in the most privileged, or supervisory, state.
- If the processor supports multiple privilege levels, must leave the processor
in the most privileged, or supervisory, state.
- Must allocate a stack of sufficient size to execute the initialization
and shutdown of the system. This stack area will NOT be used by any task
once the system is initialized. This stack is often reserved via the
linker script or in the assembly language start up file.
- Must allocate a stack of sufficient size to execute the initialization and
shutdown of the system. This stack area will NOT be used by any task once
the system is initialized. This stack is often reserved via the linker
script or in the assembly language start up file.
- Must initialize the stack pointer for the initialization process to
that allocated.
- Must initialize the stack pointer for the initialization process to that
allocated.
- Must initialize the processor's Interrupt Vector Table.
- Must disable all maskable interrupts.
- If the processor supports a separate interrupt stack, must allocate
the interrupt stack and initialize the interrupt stack pointer.
- If the processor supports a separate interrupt stack, must allocate the
interrupt stack and initialize the interrupt stack pointer.
At the end of the initialization sequence, RTEMS does not return to the
BSP initialization code, but instead context switches to the highest
priority task to begin application execution. This task is typically
a User Initialization Task which is responsible for performing both
local and global application initialization which is dependent on RTEMS
facilities. It is also responsible for initializing any higher level
RTEMS services the application uses such as networking and blocking
device drivers.
At the end of the initialization sequence, RTEMS does not return to the BSP
initialization code, but instead context switches to the highest priority task
to begin application execution. This task is typically a User Initialization
Task which is responsible for performing both local and global application
initialization which is dependent on RTEMS facilities. It is also responsible
for initializing any higher level RTEMS services the application uses such as
networking and blocking device drivers.
Interrupt Stack Requirements
----------------------------
The worst-case stack usage by interrupt service
routines must be taken into account when designing an
application. If the processor supports interrupt nesting, the
stack usage must include the deepest nest level. The worst-case
The worst-case stack usage by interrupt service routines must be taken into
account when designing an application. If the processor supports interrupt
nesting, the stack usage must include the deepest nest level. The worst-case
stack usage must account for the following requirements:
- Processor's interrupt stack frame
@ -101,51 +98,47 @@ stack usage must account for the following requirements:
- Application subroutine calls
The size of the interrupt stack must be greater than or equal to the
confugured minimum stack size.
The size of the interrupt stack must be greater than or equal to the confugured
minimum stack size.
Processors with a Separate Interrupt Stack
------------------------------------------
Some processors support a separate stack for interrupts. When an
interrupt is vectored and the interrupt is not nested, the processor
will automatically switch from the current stack to the interrupt stack.
The size of this stack is based solely on the worst-case stack usage by
interrupt service routines.
Some processors support a separate stack for interrupts. When an interrupt is
vectored and the interrupt is not nested, the processor will automatically
switch from the current stack to the interrupt stack. The size of this stack
is based solely on the worst-case stack usage by interrupt service routines.
The dedicated interrupt stack for the entire application on some
architectures is supplied and initialized by the reset and initialization
code of the user's Board Support Package. Whether allocated and
initialized by the BSP or RTEMS, since all ISRs use this stack, the
stack size must take into account the worst case stack usage by any
combination of nested ISRs.
The dedicated interrupt stack for the entire application on some architectures
is supplied and initialized by the reset and initialization code of the user's
Board Support Package. Whether allocated and initialized by the BSP or RTEMS,
since all ISRs use this stack, the stack size must take into account the worst
case stack usage by any combination of nested ISRs.
Processors Without a Separate Interrupt Stack
---------------------------------------------
Some processors do not support a separate stack for interrupts. In this
case, without special assistance every task's stack must include
enough space to handle the task's worst-case stack usage as well as
the worst-case interrupt stack usage. This is necessary because the
worst-case interrupt nesting could occur while any task is executing.
Some processors do not support a separate stack for interrupts. In this case,
without special assistance every task's stack must include enough space to
handle the task's worst-case stack usage as well as the worst-case interrupt
stack usage. This is necessary because the worst-case interrupt nesting could
occur while any task is executing.
On many processors without dedicated hardware managed interrupt stacks,
RTEMS manages a dedicated interrupt stack in software. If this capability
is supported on a CPU, then it is logically equivalent to the processor
supporting a separate interrupt stack in hardware.
On many processors without dedicated hardware managed interrupt stacks, RTEMS
manages a dedicated interrupt stack in software. If this capability is
supported on a CPU, then it is logically equivalent to the processor supporting
a separate interrupt stack in hardware.
Device Drivers
==============
Device drivers consist of control software for
special peripheral devices and provide a logical interface for
the application developer. The RTEMS I/O manager provides
directives which allow applications to access these device
drivers in a consistent fashion. A Board Support Package may
include device drivers to access the hardware on the target
platform. These devices typically include serial and parallel
ports, counter/timer peripherals, real-time clocks, disk
interfaces, and network controllers.
Device drivers consist of control software for special peripheral devices and
provide a logical interface for the application developer. The RTEMS I/O
manager provides directives which allow applications to access these device
drivers in a consistent fashion. A Board Support Package may include device
drivers to access the hardware on the target platform. These devices typically
include serial and parallel ports, counter/timer peripherals, real-time clocks,
disk interfaces, and network controllers.
For more information on device drivers, refer to the
I/O Manager chapter.
@ -153,42 +146,37 @@ I/O Manager chapter.
Clock Tick Device Driver
------------------------
Most RTEMS applications will include a clock tick
device driver which invokes the ``rtems_clock_tick``
directive at regular intervals. The clock tick is necessary if
the application is to utilize timeslicing, the clock manager, the
Most RTEMS applications will include a clock tick device driver which invokes
the ``rtems_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 from a counter/timer
or a real-time clock device. When a counter/timer is used to provide the
clock tick, the device is typically programmed to operate in continuous
mode. This mode selection causes the device to automatically reload the
initial count and continue the countdown without programmer intervention.
This reduces the overhead required to manipulate the counter/timer in
the clock tick ISR and increases the 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 ``rtems_clock_tick`` on the
configured ``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.
The clock tick is usually provided as an interrupt from a counter/timer or a
real-time clock device. When a counter/timer is used to provide the clock
tick, the device is typically programmed to operate in continuous mode. This
mode selection causes the device to automatically reload the initial count and
continue the countdown without programmer intervention. This reduces the
overhead required to manipulate the counter/timer in the clock tick ISR and
increases the 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 ``rtems_clock_tick`` on the configured
``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.
It is important to note that the interval between
clock ticks directly impacts the granularity of RTEMS timing
operations. In addition, the frequency of clock ticks is an
important factor in the overall level of system overhead. A
high clock tick frequency results in less processor time being
available for task execution due to the increased number of
clock tick ISRs.
It is important to note that the interval between clock ticks directly impacts
the granularity of RTEMS timing operations. In addition, the frequency of
clock ticks is an important factor in the overall level of system overhead. A
high clock tick frequency results in less processor time being available for
task execution due to the increased number of clock tick ISRs.
User Extensions
===============
RTEMS allows the application developer to augment
selected features by invoking user-supplied extension routines
when the following system events occur:
RTEMS allows the application developer to augment selected features by invoking
user-supplied extension routines when the following system events occur:
- Task creation
@ -208,109 +196,85 @@ when the following system events occur:
- Fatal error detection
User extensions can be used to implement a wide variety of
functions including execution profiling, non-standard
coprocessor support, debug support, and error detection and
recovery. For example, the context of a non-standard numeric
coprocessor may be maintained via the user extensions. In this
example, the task creation and deletion extensions are
responsible for allocating and deallocating the context area,
the task initiation and reinitiation extensions would be
responsible for priming the context area, and the task context
switch extension would save and restore the context of the
device.
User extensions can be used to implement a wide variety of functions including
execution profiling, non-standard coprocessor support, debug support, and error
detection and recovery. For example, the context of a non-standard numeric
coprocessor may be maintained via the user extensions. In this example, the
task creation and deletion extensions are responsible for allocating and
deallocating the context area, the task initiation and reinitiation extensions
would be responsible for priming the context area, and the task context switch
extension would save and restore the context of the device.
For more information on user extensions, refer to `User Extensions Manager`_.
Multiprocessor Communications Interface (MPCI)
==============================================
RTEMS requires that an MPCI layer be provided when a
multiple node application is developed. This MPCI layer must
provide an efficient and reliable communications mechanism
between the multiple nodes. Tasks on different nodes
communicate and synchronize with one another via the MPCI. Each
MPCI layer must be tailored to support the architecture of the
target platform.
RTEMS requires that an MPCI layer be provided when a multiple node application
is developed. This MPCI layer must provide an efficient and reliable
communications mechanism between the multiple nodes. Tasks on different nodes
communicate and synchronize with one another via the MPCI. Each MPCI layer
must be tailored to support the architecture of the target platform.
For more information on the MPCI, refer to the
Multiprocessing Manager chapter.
For more information on the MPCI, refer to the Multiprocessing Manager chapter.
Tightly-Coupled Systems
-----------------------
A tightly-coupled system is a multiprocessor
configuration in which the processors communicate solely via
shared global memory. The MPCI can simply place the RTEMS
packets in the shared memory space. The two primary
considerations when designing an MPCI for a tightly-coupled
system are data consistency and informing another node of a
packet.
A tightly-coupled system is a multiprocessor configuration in which the
processors communicate solely via shared global memory. The MPCI can simply
place the RTEMS packets in the shared memory space. The two primary
considerations when designing an MPCI for a tightly-coupled system are data
consistency and informing another node of a packet.
The data consistency problem may be solved using
atomic "test and set" operations to provide a "lock" in the
shared memory. It is important to minimize the length of time
any particular processor locks a shared data structure.
The data consistency problem may be solved using atomic "test and set"
operations to provide a "lock" in the shared memory. It is important to
minimize the length of time any particular processor locks a shared data
structure.
The problem of informing another node of a packet can
be addressed using one of two techniques. The first technique
is to use an interprocessor interrupt capability to cause an
interrupt on the receiving node. This technique requires that
special support hardware be provided by either the processor
itself or the target platform. The second technique is to have
a node poll for arrival of packets. The drawback to this
technique is the overhead associated with polling.
The problem of informing another node of a packet can be addressed using one of
two techniques. The first technique is to use an interprocessor interrupt
capability to cause an interrupt on the receiving node. This technique
requires that special support hardware be provided by either the processor
itself or the target platform. The second technique is to have a node poll for
arrival of packets. The drawback to this technique is the overhead associated
with polling.
Loosely-Coupled Systems
-----------------------
A loosely-coupled system is a multiprocessor
configuration in which the processors communicate via some type
of communications link which is not shared global memory. The
MPCI sends the RTEMS packets across the communications link to
the destination node. The characteristics of the communications
link vary widely and have a significant impact on the MPCI
layer. For example, the bandwidth of the communications link
has an obvious impact on the maximum MPCI throughput.
A loosely-coupled system is a multiprocessor configuration in which the
processors communicate via some type of communications link which is not shared
global memory. The MPCI sends the RTEMS packets across the communications link
to the destination node. The characteristics of the communications link vary
widely and have a significant impact on the MPCI layer. For example, the
bandwidth of the communications link has an obvious impact on the maximum MPCI
throughput.
The characteristics of a shared network, such as
Ethernet, lend themselves to supporting an MPCI layer. These
networks provide both the point-to-point and broadcast
capabilities which are expected by RTEMS.
The characteristics of a shared network, such as Ethernet, lend themselves to
supporting an MPCI layer. These networks provide both the point-to-point and
broadcast capabilities which are expected by RTEMS.
Systems with Mixed Coupling
---------------------------
A mixed-coupling system is a multiprocessor
configuration in which the processors communicate via both
shared memory and communications links. A unique characteristic
of mixed-coupling systems is that a node may not have access to
all communication methods. There may be multiple shared memory
areas and communication links. Therefore, one of the primary
functions of the MPCI layer is to efficiently route RTEMS
packets between nodes. This routing may be based on numerous
algorithms. In addition, the router may provide alternate
communications paths in the event of an overload or a partial
failure.
A mixed-coupling system is a multiprocessor configuration in which the
processors communicate via both shared memory and communications links. A
unique characteristic of mixed-coupling systems is that a node may not have
access to all communication methods. There may be multiple shared memory areas
and communication links. Therefore, one of the primary functions of the MPCI
layer is to efficiently route RTEMS packets between nodes. This routing may be
based on numerous algorithms. In addition, the router may provide alternate
communications paths in the event of an overload or a partial failure.
Heterogeneous Systems
---------------------
Designing an MPCI layer for a heterogeneous system
requires special considerations by the developer. RTEMS is
designed to eliminate many of the problems associated with
sharing data in a heterogeneous environment. The MPCI layer
need only address the representation of thirty-two (32) bit
unsigned quantities.
For more information on supporting a heterogeneous
system, refer the Supporting Heterogeneous Environments in the
Multiprocessing Manager chapter.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Designing an MPCI layer for a heterogeneous system requires special
considerations by the developer. RTEMS is designed to eliminate many of the
problems associated with sharing data in a heterogeneous environment. The MPCI
layer need only address the representation of thirty-two (32) bit unsigned
quantities.
For more information on supporting a heterogeneous system, refer the Supporting
Heterogeneous Environments in the Multiprocessing Manager chapter.

259
c_user/dual_ports_memory_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Dual-Ported Memory Manager
##########################
@ -7,20 +11,19 @@ Dual-Ported Memory Manager
Introduction
============
The dual-ported memory manager provides a mechanism
for converting addresses between internal and external
representations for multiple dual-ported memory areas (DPMA).
The directives provided by the dual-ported memory manager are:
The dual-ported memory manager provides a mechanism for converting addresses
between internal and external representations for multiple dual-ported memory
areas (DPMA). The directives provided by the dual-ported memory manager are:
- ``rtems_port_create`` - Create a port
- rtems_port_create_ - Create a port
- ``rtems_port_ident`` - Get ID of a port
- rtems_port_ident_ - Get ID of a port
- ``rtems_port_delete`` - Delete a port
- rtems_port_delete_ - Delete a port
- ``rtems_port_external_to_internal`` - Convert external to internal address
- rtems_port_external_to_internal_ - Convert external to internal address
- ``rtems_port_internal_to_external`` - Convert internal to external address
- rtems_port_internal_to_external_ - Convert internal to external address
Background
==========
@ -28,21 +31,18 @@ Background
.. index:: external addresses, definition
.. index:: 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
the memory using internal addresses, while other processors must
use external addresses. RTEMS defines a port as a particular
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 the memory using internal addresses, while other
processors must use external addresses. RTEMS defines a port as a particular
mapping of internal and external addresses.
There are two system configurations in which
dual-ported memory is commonly found. The first is
tightly-coupled multiprocessor computer systems where the
dual-ported memory is shared between all nodes and is used for
inter-node communication. The second configuration is computer
systems with intelligent peripheral controllers. These
controllers typically utilize the DPMA for high-performance data
transfers.
There are two system configurations in which dual-ported memory is commonly
found. The first is tightly-coupled multiprocessor computer systems where the
dual-ported memory is shared between all nodes and is used for inter-node
communication. The second configuration is computer systems with intelligent
peripheral controllers. These controllers typically utilize the DPMA for
high-performance data transfers.
Operations
==========
@ -50,54 +50,49 @@ Operations
Creating a Port
---------------
The ``rtems_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
(DPCB) from the DPCB free list to maintain the newly created
DPMA. RTEMS also generates a unique dual-ported memory port ID
which is returned to the calling task. RTEMS does not
initialize the dual-ported memory area or access any memory
within it.
The ``rtems_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 (DPCB) from the DPCB free list to maintain the
newly created DPMA. RTEMS also generates a unique dual-ported memory port ID
which is returned to the calling task. RTEMS does not initialize the
dual-ported memory area or access any memory within it.
Obtaining Port IDs
------------------
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``rtems_port_create`` directive, the task
ID is stored in a user provided location. Second, the port ID
may be obtained later using the``rtems_port_ident`` directive. The port
ID is used by other dual-ported memory manager directives to
access this port.
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``rtems_port_create``
directive, the task ID is stored in a user provided location. Second, the port
ID may be obtained later using the``rtems_port_ident`` directive. The port ID
is used by other dual-ported memory manager directives to access this port.
Converting an Address
---------------------
The ``rtems_port_external_to_internal`` directive is used to
convert an address from external to internal representation for
the specified port.
The ``rtems_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
the address to be converted will be returned.
The ``rtems_port_external_to_internal`` directive is used to convert an address
from external to internal representation for the specified port. The
``rtems_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 the
address to be converted will be returned.
Deleting a DPMA Port
--------------------
A port can be removed from the system and returned to
RTEMS with the ``rtems_port_delete`` directive. When a port is deleted,
its control block is returned to the DPCB free list.
A port can be removed from the system and returned to RTEMS with the
``rtems_port_delete`` directive. When a port is deleted, its control block is
returned to the DPCB free list.
Directives
==========
This section details the dual-ported memory manager's
directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
This section details the dual-ported memory manager's directives. A subsection
is dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_port_create:
PORT_CREATE - Create a port
---------------------------
@ -111,40 +106,47 @@ PORT_CREATE - Create a port
rtems_status_code rtems_port_create(
rtems_name name,
void \*internal_start,
void \*external_start,
void *internal_start,
void *external_start,
uint32_t length,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - port created successfully
``RTEMS_INVALID_NAME`` - invalid port name
``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_TOO_MANY`` - too many DP memory areas created
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- port created successfully
* - ``RTEMS_INVALID_NAME``
- invalid port name
* - ``RTEMS_INVALID_ADDRESS``
- address not on four byte boundary
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_TOO_MANY``
- too many DP memory areas created
**DESCRIPTION:**
This directive creates a port which resides on the
local node for the specified DPMA. The assigned port id is
returned in id. This port id is used as an argument to other
dual-ported memory manager directives to convert addresses
This directive creates a port which resides on the local node for the specified
DPMA. The assigned port id is returned in id. This port id is used as an
argument to other dual-ported memory manager directives to convert addresses
within this DPMA.
For control and maintenance of the port, RTEMS
allocates and initializes an DPCB from the DPCB free pool. Thus
memory from the dual-ported memory area is not used to store the
DPCB.
For control and maintenance of the port, RTEMS allocates and initializes an
DPCB from the DPCB free pool. Thus memory from the dual-ported memory area is
not used to store the DPCB.
**NOTES:**
The internal_address and external_address parameters
must be on a four byte boundary.
The internal_address and external_address parameters must be on a four byte
boundary.
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
.. _rtems_port_ident:
PORT_IDENT - Get ID of a port
-----------------------------
@ -164,23 +166,29 @@ PORT_IDENT - Get ID of a port
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - port identified successfully
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_INVALID_NAME`` - port name not found
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- port identified successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_NAME``
- port name not found
**DESCRIPTION:**
This directive obtains the port id associated with
the specified name to be acquired. If the port name is not
unique, then the port id will match one of the DPMAs with that
name. However, this port id is not guaranteed to correspond to
the desired DPMA. The port id is used to access this DPMA in
This directive obtains the port id associated with the specified name to be
acquired. If the port name is not unique, then the port id will match one of
the DPMAs with that name. However, this port id is not guaranteed to
correspond to the desired DPMA. The port id is used to access this DPMA in
other dual-ported memory area related directives.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
.. _rtems_port_delete:
PORT_DELETE - Delete a port
---------------------------
@ -198,23 +206,27 @@ PORT_DELETE - Delete a port
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - port deleted successfully
``RTEMS_INVALID_ID`` - invalid port id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- port deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid port id
**DESCRIPTION:**
This directive deletes the dual-ported memory area
specified by id. The DPCB for the deleted dual-ported memory
area is reclaimed by RTEMS.
This directive deletes the dual-ported memory area specified by id. The DPCB
for the deleted dual-ported memory area is reclaimed by RTEMS.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
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.
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.
.. _rtems_port_external_to_internal:
PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
----------------------------------------------------------------
@ -228,29 +240,34 @@ PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
rtems_status_code rtems_port_external_to_internal(
rtems_id id,
void \*external,
void \**internal
void *external,
void **internal
);
**DIRECTIVE STATUS CODES:**
``RTEMS_INVALID_ADDRESS`` - ``internal`` is NULL
``RTEMS_SUCCESSFUL`` - successful conversion
.. list-table::
:class: rtems-table
* - ``RTEMS_INVALID_ADDRESS``
- ``internal`` is NULL
* - ``RTEMS_SUCCESSFUL``
- successful conversion
**DESCRIPTION:**
This directive converts a dual-ported memory address
from external to internal representation for the specified port.
If the given external address is invalid for the specified
port, then the internal address is set to the given external
address.
This directive converts a dual-ported memory address from external to internal
representation for the specified port. If the given external address is
invalid for the specified port, then the internal address is set to the given
external address.
**NOTES:**
This directive is callable from an ISR.
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
.. _rtems_port_internal_to_external:
PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
----------------------------------------------------------------
@ -264,33 +281,29 @@ PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
rtems_status_code rtems_port_internal_to_external(
rtems_id id,
void \*internal,
void \**external
void *internal,
void **external
);
**DIRECTIVE STATUS CODES:**
``RTEMS_INVALID_ADDRESS`` - ``external`` is NULL
``RTEMS_SUCCESSFUL`` - successful conversion
.. list-table::
:class: rtems-table
* - ``RTEMS_INVALID_ADDRESS``
- ``external`` is NULL
* - ``RTEMS_SUCCESSFUL``
- successful conversion
**DESCRIPTION:**
This directive converts a dual-ported memory address
from internal to external representation so that it can be
passed to owner of the DPMA represented by the specified port.
If the given internal address is an invalid dual-ported address,
then the external address is set to the given internal address.
This directive converts a dual-ported memory address from internal to external
representation so that it can be passed to owner of the DPMA represented by the
specified port. If the given internal address is an invalid dual-ported
address, then the external address is set to the given internal address.
**NOTES:**
This directive is callable from an ISR.
This directive will not cause the calling task to be
preempted.
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
This directive will not cause the calling task to be preempted.

321
c_user/event_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Event Manager
#############
@ -6,13 +10,11 @@ Event Manager
Introduction
============
The event manager provides a high performance method
of intertask communication and synchronization. The directives
provided by the event manager are:
The event manager provides a high performance method of intertask communication
and synchronization. The directives provided by the event manager are:
- ``rtems_event_send`` - Send event set to a task
- ``rtems_event_receive`` - Receive event condition
- rtems_event_send_ - Send event set to a task
- rtems_event_receive_ - Receive event condition
Background
==========
@ -23,16 +25,13 @@ Event Sets
.. index:: event set, definition
.. index:: rtems_event_set
An event flag is used by a task (or ISR) to inform
another task of the occurrence of a significant situation.
Thirty-two event flags are associated with each task. A
collection of one or more event flags is referred to as an event
set. The data type ``rtems_event_set`` is used to manage
event sets.
An event flag is used by a task (or ISR) to inform another task of the
occurrence of a significant situation. Thirty-two event flags are associated
with each task. A collection of one or more event flags is referred to as an
event set. The data type ``rtems_event_set`` is used to manage event sets.
The application developer should remember the following
key characteristics of event operations when utilizing the event
manager:
The application developer should remember the following key characteristics of
event operations when utilizing the event manager:
- Events provide a simple synchronization facility.
@ -44,65 +43,69 @@ manager:
- Events do not hold or transport data.
- Events are not queued. In other words, if an event is
sent more than once to a task before being received, the second and
subsequent send operations to that same task have no effect.
- Events are not queued. In other words, if an event is sent more than once to
a task before being received, the second and subsequent send operations to
that same task have no effect.
An event set is posted when it is directed (or sent) to a task. A
pending event is an event that has been posted but not received. An event
condition is used to specify the event set which the task desires to receive
and the algorithm which will be used to determine when the request is
satisfied. An event condition is satisfied based upon one of two
algorithms which are selected by the user. The``RTEMS_EVENT_ANY`` algorithm states that an event condition
is satisfied when at least a single requested event is posted. The``RTEMS_EVENT_ALL`` algorithm states that an event condition
is satisfied when every requested event is posted.
An event set is posted when it is directed (or sent) to a task. A pending
event is an event that has been posted but not received. An event condition is
used to specify the event set which the task desires to receive and the
algorithm which will be used to determine when the request is satisfied. An
event condition is satisfied based upon one of two algorithms which are
selected by the user. The ``RTEMS_EVENT_ANY`` algorithm states that an event
condition is satisfied when at least a single requested event is posted. The
``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when
every requested event is posted.
Building an Event Set or Condition
----------------------------------
.. index:: event condition, building
.. index:: event set, building
An event set or condition is built by a bitwise OR of
the desired events. The set of valid events is ``RTEMS_EVENT_0`` through``RTEMS_EVENT_31``. If an event is not explicitly specified in the set or
condition, then it is not present. Events are specifically
designed to be mutually exclusive, therefore bitwise OR and
addition operations are equivalent as long as each event appears
An event set or condition is built by a bitwise OR of the desired events. The
set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``. If an
event is not explicitly specified in the set or condition, then it is not
present. Events are specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations are equivalent as long as each event appears
exactly once in the event set list.
For example, when sending the event set consisting of``RTEMS_EVENT_6``, ``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``,
the event parameter to the ``rtems_event_send``
directive should be ``RTEMS_EVENT_6 |
RTEMS_EVENT_15 | RTEMS_EVENT_31``.
For example, when sending the event set consisting of ``RTEMS_EVENT_6``,
``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``, the event parameter to the
``rtems_event_send`` directive should be ``RTEMS_EVENT_6 | RTEMS_EVENT_15 |
RTEMS_EVENT_31``.
Building an EVENT_RECEIVE Option Set
------------------------------------
In general, an option is built by a bitwise OR of the
desired option components. The set of valid options for the``rtems_event_receive`` directive are listed
in the following table:
In general, an option is built by a bitwise OR of the desired option
components. The set of valid options for the ``rtems_event_receive`` directive
are listed in the following table:
- ``RTEMS_WAIT`` - task will wait for event (default)
.. list-table::
:class: rtems-table
- ``RTEMS_NO_WAIT`` - task should not wait
* - ``RTEMS_WAIT``
- task will wait for event (default)
* - ``RTEMS_NO_WAIT``
- task should not wait
* - ``RTEMS_EVENT_ALL``
- return after all events (default)
* - ``RTEMS_EVENT_ANY``
- return after any events
- ``RTEMS_EVENT_ALL`` - return after all events (default)
Option values are specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations 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
``RTEMS_DEFAULT_OPTIONS`` should be specified on this call.
- ``RTEMS_EVENT_ANY`` - return after any events
Option values are specifically designed to be
mutually exclusive, therefore bitwise OR and addition operations
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 ``RTEMS_DEFAULT_OPTIONS`` should be
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``rtems_event_receive`` directive should be either``RTEMS_EVENT_ALL | RTEMS_NO_WAIT``
or ``RTEMS_NO_WAIT``. The option parameter can be set to``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the
default condition for ``rtems_event_receive``.
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
``rtems_event_receive`` directive should be either ``RTEMS_EVENT_ALL |
RTEMS_NO_WAIT`` or ``RTEMS_NO_WAIT``. The option parameter can be set to
``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the default condition for
``rtems_event_receive``.
Operations
==========
@ -110,18 +113,17 @@ Operations
Sending an Event Set
--------------------
The ``rtems_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:
The ``rtems_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:
- Target Task is Blocked Waiting for Events
- If the waiting task's input event condition is
satisfied, then the task is made ready for execution.
- If the waiting task's input event condition is satisfied, then the task is
made ready for execution.
- If the waiting task's input event condition is not
satisfied, then the event set is posted but left pending and the
task remains blocked.
- If the waiting task's input event condition is not satisfied, then the
event set is posted but left pending and the task remains blocked.
- Target Task is Not Waiting for Events
@ -130,50 +132,49 @@ the target task, one of the following situations applies:
Receiving an Event Set
----------------------
The ``rtems_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.
If the requested event condition is satisfied by pending
events, then a successful return code and the satisfying event
set are returned immediately. If the condition is not
satisfied, then one of the following situations applies:
The ``rtems_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. If the requested event condition is satisfied by pending events,
then a successful return code and the satisfying event set are returned
immediately. If the condition is not satisfied, then one of the following
situations applies:
- By default, the calling task will wait forever for the
event condition to be satisfied.
- By default, the calling task will wait forever for the event condition to be
satisfied.
- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return
- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an
error status code.
- Specifying a timeout limits the period the task will wait before returning
with an error status code.
- Specifying a timeout limits the period the task will
wait before returning with an error status code.
Determining the Pending Event Set
---------------------------------
A task can determine the pending event set by calling
the ``rtems_event_receive`` directive with a value of``RTEMS_PENDING_EVENTS`` for the input event condition.
The pending events are returned to the calling task but the event
set is left unaltered.
A task can determine the pending event set by calling the
``rtems_event_receive`` directive with a value of ``RTEMS_PENDING_EVENTS`` for
the input event condition. The pending events are returned to the calling task
but the event set is left unaltered.
Receiving all Pending Events
----------------------------
A task can receive all of the currently pending
events by calling the ``rtems_event_receive``
directive with a value of ``RTEMS_ALL_EVENTS``
for the input event condition and``RTEMS_NO_WAIT | RTEMS_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
pending then the ``RTEMS_UNSATISFIED`` status code will be returned.
A task can receive all of the currently pending events by calling the
``rtems_event_receive`` directive with a value of ``RTEMS_ALL_EVENTS`` for the
input event condition and ``RTEMS_NO_WAIT | RTEMS_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 pending then the ``RTEMS_UNSATISFIED`` status code
will be returned.
Directives
==========
This section details the event manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
This section details the event manager's directives. A subsection is dedicated
to each of this manager's directives and describes the calling sequence,
related constants, usage, and status codes.
.. _rtems_event_send:
EVENT_SEND - Send event set to a task
-------------------------------------
@ -192,36 +193,40 @@ EVENT_SEND - Send event set to a task
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - event set sent successfully
``RTEMS_INVALID_ID`` - invalid task id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- event set sent successfully
* - ``RTEMS_INVALID_ID``
- invalid task id
**DESCRIPTION:**
This directive sends an event set, event_in, to the
task specified by id. If a blocked task's input event condition
is satisfied by this directive, then it will be made ready. If
its input event condition is not satisfied, then the events
satisfied are updated and the events not satisfied are left
pending. If the task specified by id is not blocked waiting for
events, then the events sent are left pending.
This directive sends an event set, event_in, to the task specified by id. If a
blocked task's input event condition is satisfied by this directive, then it
will be made ready. If its input event condition is not satisfied, then the
events satisfied are updated and the events not satisfied are left pending. If
the task specified by id is not blocked waiting for events, then the events
sent are left pending.
**NOTES:**
Specifying ``RTEMS_SELF`` for id results in the event set being
sent to the calling task.
Specifying ``RTEMS_SELF`` for id results in the event set being 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 ``rtems_event_receive``
has no effect.
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
``rtems_event_receive`` has no effect.
The calling task will be preempted if it has
preemption enabled and a higher priority task is unblocked as
the result of this directive.
The calling task will be preempted if it has preemption enabled and a higher
priority task is unblocked as the result of this directive.
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.
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.
.. _rtems_event_receive:
EVENT_RECEIVE - Receive event condition
---------------------------------------
@ -237,62 +242,64 @@ EVENT_RECEIVE - Receive event condition
rtems_event_set event_in,
rtems_option option_set,
rtems_interval ticks,
rtems_event_set \*event_out
rtems_event_set *event_out
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - event received successfully
``RTEMS_UNSATISFIED`` - input event not satisfied (``RTEMS_NO_WAIT``)
``RTEMS_INVALID_ADDRESS`` - ``event_out`` is NULL
``RTEMS_TIMEOUT`` - timed out waiting for event
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- event received successfully
* - ``RTEMS_UNSATISFIED``
- input event not satisfied (``RTEMS_NO_WAIT``)
* - ``RTEMS_INVALID_ADDRESS``
- ``event_out`` is NULL
* - ``RTEMS_TIMEOUT``
- timed out waiting for event
**DESCRIPTION:**
This directive attempts to receive the event
condition specified in event_in. If event_in is set to``RTEMS_PENDING_EVENTS``, then the current pending events are returned in
event_out and left pending. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options in the
option_set parameter are used to specify whether or not the task
is willing to wait for the event condition to be satisfied.``RTEMS_EVENT_ANY`` and ``RTEMS_EVENT_ALL`` are used in the option_set parameter are
used to specify whether a single event or the complete event set
is necessary to satisfy the event condition. The event_out
parameter is returned to the calling task with the value that
corresponds to the events in event_in that were satisfied.
This directive attempts to receive the event condition specified in event_in.
If event_in is set to ``RTEMS_PENDING_EVENTS``, then the current pending events
are returned in event_out and left pending. The ``RTEMS_WAIT`` and
``RTEMS_NO_WAIT`` options in the option_set parameter are used to specify
whether or not the task is willing to wait for the event condition to be
satisfied. ``RTEMS_EVENT_ANY`` and ``RTEMS_EVENT_ALL`` are used in the
option_set parameter are used to specify whether a single event or the complete
event set is necessary to satisfy the event condition. The event_out parameter
is returned to the calling task with the value that corresponds to the events
in event_in that were satisfied.
If pending events satisfy the event condition, then
event_out is set to the satisfied events and the pending events
in the event condition are cleared. If the event condition is
not satisfied and ``RTEMS_NO_WAIT`` is specified, then event_out is set to
the currently satisfied events. If the calling task chooses to
wait, then it will block waiting for the event condition.
If pending events satisfy the event condition, then event_out is set to the
satisfied events and the pending events in the event condition are cleared. If
the event condition is not satisfied and ``RTEMS_NO_WAIT`` is specified, then
event_out is set to the currently satisfied events. If the calling task
chooses to wait, then it will block waiting for the event condition.
If the calling task must wait for the event condition
to be satisfied, then the timeout parameter is used to specify
the maximum interval to wait. If it is set to ``RTEMS_NO_TIMEOUT``, then
the calling task will wait forever.
If the calling task must wait for the event condition to be satisfied, then the
timeout parameter is used to specify the maximum interval to wait. If it is
set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
**NOTES:**
This directive only affects the events specified in
event_in. Any pending events that do not correspond to any of
the events specified in event_in will be left pending.
This directive only affects the events specified in event_in. Any pending
events that do not correspond to any of the events specified in event_in will
be left pending.
The following event receive option constants are defined by
RTEMS:
The following event receive option constants are defined by RTEMS:
- ``RTEMS_WAIT`` task will wait for event (default)
.. list-table::
:class: rtems-table
- ``RTEMS_NO_WAIT`` task should not wait
- ``RTEMS_EVENT_ALL`` return after all events (default)
- ``RTEMS_EVENT_ANY`` return after any events
* - ``RTEMS_WAIT``
- task will wait for event (default)
* - ``RTEMS_NO_WAIT``
- task should not wait
* - ``RTEMS_EVENT_ALL``
- return after all events (default)
* - ``RTEMS_EVENT_ANY``
- return after any events
A clock tick is required to support the functionality of this directive.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

169
c_user/fatal_error.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Fatal Error Manager
###################
@ -7,12 +11,18 @@ Introduction
============
The fatal error manager processes all fatal or irrecoverable errors and other
sources of system termination (for example after exit()). The directives
sources of system termination (for example after ``exit()``). The directives
provided by the fatal error manager are:
- ``rtems_fatal_error_occurred`` - Invoke the fatal error handler
- rtems_fatal_error_occurred_ - Invoke the fatal error handler
- ``rtems_fatal`` - Invoke the fatal error handler with error source
- rtems_fatal_ - Invoke the fatal error handler with error source
- rtems_exception_frame_print_ - Print the CPU exception frame
- rtems_fatal_source_text_ - Return the falet source text
- rtems_internal_error_text_ - Return the error code text
Background
==========
@ -20,10 +30,9 @@ Background
.. index:: fatal error processing
.. index:: 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
sources:
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 sources:
- the executive (RTEMS)
@ -31,85 +40,74 @@ sources:
- user application code
RTEMS automatically invokes the fatal error manager
upon detection of an error it considers to be fatal. Similarly,
the user should invoke the fatal error manager upon detection of
a fatal error.
RTEMS automatically invokes the fatal error manager upon detection of an error
it considers to be fatal. Similarly, the user should invoke the fatal error
manager upon detection of a fatal error.
Each static or dynamic user extension set may include
a fatal error handler. The fatal error handler in the static
extension set can be used to provide access to debuggers and
monitors which may be present on the target hardware. If any
user-supplied fatal error handlers are installed, the fatal
error manager will invoke them. If no user handlers are
configured or if all the user handler return control to the
fatal error manager, then the RTEMS default fatal error handler
is invoked. If the default fatal error handler is invoked, then
the system state is marked as failed.
Each static or dynamic user extension set may include a fatal error handler.
The fatal error handler in the static extension set can be used to provide
access to debuggers and monitors which may be present on the target hardware.
If any user-supplied fatal error handlers are installed, the fatal error
manager will invoke them. If no user handlers are configured or if all the
user handler return control to the fatal error manager, then the RTEMS default
fatal error handler is invoked. If the default fatal error handler is invoked,
then the system state is marked as failed.
Although the precise behavior of the default fatal
error handler is processor specific, in general, it will disable
all maskable interrupts, place the error code in a known
processor dependent place (generally either on the stack or in a
register), and halt the processor. The precise actions of the
RTEMS fatal error are discussed in the Default Fatal Error
Processing chapter of the Applications Supplement document for
a specific target processor.
Although the precise behavior of the default fatal error handler is processor
specific, in general, it will disable all maskable interrupts, place the error
code in a known processor dependent place (generally either on the stack or in
a register), and halt the processor. The precise actions of the RTEMS fatal
error are discussed in the Default Fatal Error Processing chapter of the
Applications Supplement document for a specific target processor.
Operations
==========
Announcing a Fatal Error
------------------------
.. index:: _Internal_errors_What_happened
The ``rtems_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``rtems_fatal_error_occurred``
directive stores useful information in the
variable ``_Internal_errors_What_happened``. This structure
The ``rtems_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 ``rtems_fatal_error_occurred`` directive stores useful
information in the variable ``_Internal_errors_What_happened``. This structure
contains three pieces of information:
- the source of the error (API or executive core),
- whether the error was generated internally by the
executive, and a
- whether the error was generated internally by the executive, and a
- a numeric code to indicate the error type.
The error type indicator is dependent on the source
of the error and whether or not the error was internally
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 cpukit/rtems/include/rtems/rtems/status.h. Those
for the POSIX API can be found in <errno.h>.
The error type indicator is dependent on the source of the error and whether or
not the error was internally 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
cpukit/rtems/include/rtems/rtems/status.h. Those for the POSIX API can be
found in <errno.h>.
The ``rtems_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.
The ``rtems_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.
Occasionally, an application requires more
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``rtems_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
handler will halt execution on the processor where the error
occurred.
Occasionally, an application requires more 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 ``rtems_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 handler will halt execution on the processor where the error occurred.
Directives
==========
This section details the fatal error manager's
directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
This section details the fatal error manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_fatal_error_occurred:
FATAL_ERROR_OCCURRED - Invoke the fatal error handler
-----------------------------------------------------
@ -132,24 +130,24 @@ NONE
**DESCRIPTION:**
This directive processes fatal errors. If the FATAL
error extension is defined in the configuration table, then the
user-defined error extension is called. If configured and the
provided FATAL error extension returns, then the RTEMS default
error handler is invoked. This directive can be invoked by
RTEMS or by the user's application code including initialization
tasks, other tasks, and ISRs.
This directive processes fatal errors. If the FATAL error extension is defined
in the configuration table, then the user-defined error extension is called.
If configured and the provided FATAL error extension returns, then the RTEMS
default error handler is invoked. This directive can be invoked by RTEMS or by
the user's application code including initialization tasks, other tasks, and
ISRs.
**NOTES:**
This directive supports local operations only.
Unless the user-defined error extension takes special
actions such as restarting the calling task, this directive WILL
NOT RETURN to the caller.
Unless the user-defined error extension takes special actions such as
restarting the calling task, this directive WILL NOT RETURN to the caller.
The user-defined extension for this directive may
wish to initiate a global shutdown.
The user-defined extension for this directive may wish to initiate a global
shutdown.
.. _rtems_fatal:
FATAL - Invoke the fatal error handler with error source
--------------------------------------------------------
@ -176,6 +174,8 @@ NONE
This directive invokes the internal error handler with is internal set to
false. See also ``rtems_fatal_error_occurred``.
.. _rtems_exception_frame_print:
EXCEPTION_FRAME_PRINT - Prints the exception frame
--------------------------------------------------
.. index:: exception frame
@ -187,7 +187,7 @@ EXCEPTION_FRAME_PRINT - Prints the exception frame
.. code:: c
void rtems_exception_frame_print(
const rtems_exception_frame \*frame
const rtems_exception_frame *frame
);
**DIRECTIVE STATUS CODES**
@ -196,7 +196,9 @@ NONE
**DESCRIPTION:**
Prints the exception frame via printk().
Prints the exception frame via ``printk()``.
.. _rtems_fatal_source_text:
FATAL_SOURCE_TEXT - Returns a text for a fatal source
-----------------------------------------------------
@ -208,7 +210,7 @@ FATAL_SOURCE_TEXT - Returns a text for a fatal source
.. code:: c
const char \*rtems_fatal_source_text(
const char *rtems_fatal_source_text(
rtems_fatal_source source
);
@ -221,6 +223,8 @@ The fatal source text or "?" in case the passed fatal source is invalid.
Returns a text for a fatal source. The text for fatal source is the enumerator
constant.
.. _rtems_internal_error_text:
INTERNAL_ERROR_TEXT - Returns a text for an internal error code
---------------------------------------------------------------
.. index:: fatal error
@ -231,7 +235,7 @@ INTERNAL_ERROR_TEXT - Returns a text for an internal error code
.. code:: c
const char \*rtems_internal_error_text(
const char *rtems_internal_error_text(
rtems_fatal_code error
);
@ -243,10 +247,3 @@ The error code text or "?" in case the passed error code is invalid.
Returns a text for an internal error code. The text for each internal error
code is the enumerator constant.
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

496
c_user/io_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
I/O Manager
###########
@ -7,30 +11,29 @@ I/O Manager
Introduction
============
The input/output interface manager provides a
well-defined mechanism for accessing device drivers and a
structured methodology for organizing device drivers. The
directives provided by the I/O manager are:
The input/output interface manager provides a well-defined mechanism for
accessing device drivers and a structured methodology for organizing device
drivers. The directives provided by the I/O manager are:
- ``rtems_io_initialize`` - Initialize a device driver
- rtems_io_initialize_ - Initialize a device driver
- ``rtems_io_register_driver`` - Register a device driver
- rtems_io_register_driver_ - Register a device driver
- ``rtems_io_unregister_driver`` - Unregister a device driver
- rtems_io_unregister_driver_ - Unregister a device driver
- ``rtems_io_register_name`` - Register a device name
- rtems_io_register_name_ - Register a device name
- ``rtems_io_lookup_name`` - Look up a device name
- rtems_io_lookup_name_ - Look up a device name
- ``rtems_io_open`` - Open a device
- rtems_io_open_ - Open a device
- ``rtems_io_close`` - Close a device
- rtems_io_close_ - Close a device
- ``rtems_io_read`` - Read from a device
- rtems_io_read_ - Read from a device
- ``rtems_io_write`` - Write to a device
- rtems_io_write_ - Write to a device
- ``rtems_io_control`` - Special device services
- rtems_io_control_ - Special device services
Background
==========
@ -39,11 +42,10 @@ Device Driver Table
-------------------
.. index:: 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 entry points that is to be initialised by
RTEMS during initialization. Each device driver may contain the
following entry points:
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 entry points that is to be initialised by RTEMS during initialization.
Each device driver may contain the following entry points:
- Initialization
@ -57,143 +59,135 @@ following entry points:
- Control
If the device driver does not support a particular
entry point, then that entry in the Configuration Table should
be NULL. RTEMS will return``RTEMS_SUCCESSFUL`` as the executive's and
zero (0) as the device driver's return code for these device
driver 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
``RTEMS_SUCCESSFUL`` as the executive's and zero (0) as the device driver's
return code for these device driver entry points.
Applications can register and unregister drivers with the RTEMS I/O
manager avoiding the need to have all drivers statically defined and
linked into this table.
Applications can register and unregister drivers with the RTEMS I/O manager
avoiding the need to have all drivers statically defined and linked into this
table.
The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures
the number of driver slots available to the application.
The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures the
number of driver slots available to the application.
Major and Minor Device Numbers
------------------------------
.. index:: major device number
.. index:: 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
Driver Table, and is used to select a specific device driver.
The exact usage of the minor number is driver specific, but is
commonly used to distinguish between a number of devices
controlled by the same driver... index:: rtems_device_major_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 Driver Table, and is used to select a specific device
driver. The exact usage of the minor number is driver specific, but is
commonly used to distinguish between a number of devices controlled by the same
driver.
.. index:: rtems_device_major_number
.. index:: rtems_device_minor_number
The data types ``rtems_device_major_number`` and``rtems_device_minor_number`` are used to
manipulate device major and minor numbers, respectively.
The data types ``rtems_device_major_number`` and ``rtems_device_minor_number``
are used to manipulate device major and minor numbers, respectively.
Device Names
------------
.. index:: 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
number pair associated with a device name.
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 number pair associated with a device name.
Device Driver Environment
-------------------------
Application developers, as well as device driver
developers, must be aware of the following regarding the RTEMS
I/O Manager:
Application developers, as well as device driver developers, must be aware of
the following regarding the RTEMS I/O Manager:
- A device driver routine executes in the context of the
invoking task. Thus if the driver blocks, the invoking task
blocks.
- A device driver routine executes in the context of the invoking task. Thus
if the driver blocks, the invoking task blocks.
- The device driver is free to change the modes of the
invoking task, although the driver should restore them to their
original values.
- The device driver is free to change the modes of the invoking task, although
the driver should restore them to their original values.
- Device drivers may be invoked from ISRs.
- Only local device drivers are accessible through the I/O
manager.
- Only local device drivers are accessible through the I/O manager.
- A device driver routine may invoke all other RTEMS
directives, including I/O directives, on both local and global
objects.
- A device driver routine may invoke all other RTEMS directives, including I/O
directives, on both local and global objects.
Although the RTEMS I/O manager provides a framework
for device drivers, it makes no assumptions regarding the
construction or operation of a device driver.
Although the RTEMS I/O manager provides a framework for device drivers, it
makes no assumptions regarding the construction or operation of a device
driver.
Runtime Driver Registration
---------------------------
.. index:: runtime driver registration
Board support package and application developers can select wether a
device driver is statically entered into the default device table or
registered at runtime.
Board support package and application developers can select wether a device
driver is statically entered into the default device table or registered at
runtime.
Dynamic registration helps applications where:
# The BSP and kernel libraries are common to a range of applications
for a specific target platform. An application may be built upon a
common library with all drivers. The application selects and registers
the drivers. Uniform driver name lookup protects the application.
- The BSP and kernel libraries are common to a range of applications for a
specific target platform. An application may be built upon a common library
with all drivers. The application selects and registers the drivers. Uniform
driver name lookup protects the application.
# The type and range of drivers may vary as the application probes a
bus during initialization.
- The type and range of drivers may vary as the application probes a bus during
initialization.
# Support for hot swap bus system such as Compact PCI.
- Support for hot swap bus system such as Compact PCI.
# Support for runtime loadable driver modules.
- Support for runtime loadable driver modules.
Device Driver Interface
-----------------------
.. index:: 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
then passed to the correct device driver entry point. RTEMS
will invoke each device driver entry point assuming it is
compatible with the following prototype:
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 then passed to the correct device driver entry point.
RTEMS will invoke each device driver entry point assuming it is compatible with
the following prototype:
.. code:: c
rtems_device_driver io_entry(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument_block
void *argument_block
);
The format and contents of the parameter block are
device driver and entry point dependent.
The format and contents of the parameter block are device driver and entry
point dependent.
It is recommended that a device driver avoid
generating error codes which conflict with those used by
application components. A common technique used to generate
driver specific error codes is to make the most significant part
of the status indicate a driver specific code.
It is recommended that a device driver avoid generating error codes which
conflict with those used by application components. A common technique used to
generate driver specific error codes is to make the most significant part of
the status indicate a driver specific code.
Device Driver Initialization
----------------------------
RTEMS automatically initializes all device drivers
when multitasking is initiated via the``rtems_initialize_executive``
directive. RTEMS initializes the device drivers by invoking
each device driver initialization entry point with the following
parameters:
RTEMS automatically initializes all device drivers when multitasking is
initiated via the ``rtems_initialize_executive`` directive. RTEMS initializes
the device drivers by invoking each device driver initialization entry point
with the following parameters:
major
``major``
the major device number for this device driver.
minor
``minor``
zero.
argument_block
``argument_block``
will point to the Configuration Table.
The returned status will be ignored by RTEMS. If the driver
cannot successfully initialize the device, then it should invoke
the fatal_error_occurred directive.
The returned status will be ignored by RTEMS. If the driver cannot
successfully initialize the device, then it should invoke the
fatal_error_occurred directive.
Operations
==========
@ -201,33 +195,31 @@ Operations
Register and Lookup Name
------------------------
The ``rtems_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 ``rtems_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
major numbers in a particular application. No device naming
conventions are dictated by RTEMS.
The ``rtems_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 ``rtems_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 major numbers in a particular
application. No device naming conventions are dictated by RTEMS.
Accessing an Device Driver
--------------------------
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``rtems_io_initialize``,``rtems_io_open``,``rtems_io_close``,``rtems_io_read``,``rtems_io_write``, and``rtems_io_control``
and the underlying device driver entry points.
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 ``rtems_io_initialize``,
``rtems_io_open``, ``rtems_io_close``, ``rtems_io_read``, ``rtems_io_write``,
and ``rtems_io_control`` and the underlying device driver entry points.
Directives
==========
This section details the I/O manager's directives. A
subsection is dedicated to each of this manager's directives and
describes the calling sequence, related constants, usage, and
status codes.
This section details the I/O manager's directives. A subsection is dedicated
to each of this manager's directives and describes the calling sequence,
related constants, usage, and status codes.
.. _rtems_io_register_driver:
IO_REGISTER_DRIVER - Register a device driver
---------------------------------------------
@ -241,39 +233,51 @@ IO_REGISTER_DRIVER - Register a device driver
rtems_status_code rtems_io_register_driver(
rtems_device_major_number major,
rtems_driver_address_table \*driver_table,
rtems_device_major_number \*registered_major
rtems_driver_address_table *driver_table,
rtems_device_major_number *registered_major
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully registered
``RTEMS_INVALID_ADDRESS`` - invalid registered major pointer
``RTEMS_INVALID_ADDRESS`` - invalid driver table
``RTEMS_INVALID_NUMBER`` - invalid major device number
``RTEMS_TOO_MANY`` - no available major device table slot
``RTEMS_RESOURCE_IN_USE`` - major device number entry in use
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully registered
* - ``RTEMS_INVALID_ADDRESS``
- invalid registered major pointer
* - ``RTEMS_INVALID_ADDRESS``
- invalid driver table
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
* - ``RTEMS_TOO_MANY``
- no available major device table slot
* - ``RTEMS_RESOURCE_IN_USE``
- major device number entry in use
**DESCRIPTION:**
This directive attempts to add a new device driver to the Device Driver
Table. The user can specify a specific major device number via the
directive's ``major`` parameter, or let the registration routine find
the next available major device number by specifing a major number of``0``. The selected major device number is returned via the``registered_major`` directive parameter. The directive automatically
allocation major device numbers from the highest value down.
Table. The user can specify a specific major device number via the directive's
``major`` parameter, or let the registration routine find the next available
major device number by specifing a major number of ``0``. The selected major
device number is returned via the ``registered_major`` directive parameter. The
directive automatically allocation major device numbers from the highest value
down.
This directive automatically invokes the IO_INITIALIZE directive if
the driver address table has an initialization and open entry.
This directive automatically invokes the ``IO_INITIALIZE`` directive if the
driver address table has an initialization and open entry.
The directive returns RTEMS_TOO_MANY if Device Driver Table is
full, and RTEMS_RESOURCE_IN_USE if a specific major device
number is requested and it is already in use.
The directive returns ``RTEMS_TOO_MANY`` if Device Driver Table is full, and
``RTEMS_RESOURCE_IN_USE`` if a specific major device number is requested and it
is already in use.
**NOTES:**
The Device Driver Table size is specified in the Configuration Table
condiguration. This needs to be set to maximum size the application
requires.
condiguration. This needs to be set to maximum size the application requires.
.. _rtems_io_unregister_driver:
IO_UNREGISTER_DRIVER - Unregister a device driver
-------------------------------------------------
@ -291,8 +295,13 @@ IO_UNREGISTER_DRIVER - Unregister a device driver
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully registered
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully registered
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
@ -302,6 +311,8 @@ This directive removes a device driver from the Device Driver Table.
Currently no specific checks are made and the driver is not closed.
.. _rtems_io_initialize:
IO_INITIALIZE - Initialize a device driver
------------------------------------------
.. index:: initialize a device driver
@ -315,32 +326,36 @@ IO_INITIALIZE - Initialize a device driver
rtems_status_code rtems_io_initialize(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument
void *argument
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
This directive calls the device driver initialization
routine specified in the Device Driver Table for this major
number. This directive is automatically invoked for each device
driver when multitasking is initiated via the
This directive calls the device driver initialization routine specified in the
Device Driver Table for this major number. This directive is automatically
invoked for each device driver when multitasking is initiated via the
initialize_executive directive.
A device driver initialization module is responsible
for initializing all hardware and data structures associated
with a device. If necessary, it can allocate memory to be used
during other operations.
A device driver initialization module is responsible for initializing all
hardware and data structures associated with a device. If necessary, it can
allocate memory to be used during other operations.
**NOTES:**
This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
initialized.
This directive may or may not cause the calling task to be preempted. This is
dependent on the device driver being initialized.
.. _rtems_io_register_name:
IO_REGISTER_NAME - Register a device
------------------------------------
@ -353,25 +368,30 @@ IO_REGISTER_NAME - Register a device
.. code:: c
rtems_status_code rtems_io_register_name(
const char \*name,
const char *name,
rtems_device_major_number major,
rtems_device_minor_number minor
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_TOO_MANY`` - too many devices registered
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_TOO_MANY``
- too many devices registered
**DESCRIPTION:**
This directive associates name with the specified
major/minor number pair.
This directive associates name with the specified major/minor number pair.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
.. _rtems_io_lookup_name:
IO_LOOKUP_NAME - Lookup a device
--------------------------------
@ -384,24 +404,30 @@ IO_LOOKUP_NAME - Lookup a device
.. code:: c
rtems_status_code rtems_io_lookup_name(
const char \*name,
rtems_driver_name_t \*device_info
const char *name,
rtems_driver_name_t *device_info
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_UNSATISFIED`` - name not registered
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_UNSATISFIED``
- name not registered
**DESCRIPTION:**
This directive returns the major/minor number pair
associated with the given device name in ``device_info``.
This directive returns the major/minor number pair associated with the given
device name in ``device_info``.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
.. _rtems_io_open:
IO_OPEN - Open a device
-----------------------
@ -416,26 +442,31 @@ IO_OPEN - Open a device
rtems_status_code rtems_io_open(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument
void *argument
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
This directive calls the device driver open routine
specified in the Device Driver Table for this major number. The
open entry point is commonly used by device drivers to provide
exclusive access to a device.
This directive calls the device driver open routine specified in the Device
Driver Table for this major number. The open entry point is commonly used by
device drivers to provide exclusive access to a device.
**NOTES:**
This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
This directive may or may not cause the calling task to be preempted. This is
dependent on the device driver being invoked.
.. _rtems_io_close:
IO_CLOSE - Close a device
-------------------------
@ -450,26 +481,31 @@ IO_CLOSE - Close a device
rtems_status_code rtems_io_close(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument
void *argument
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
This directive calls the device driver close routine
specified in the Device Driver Table for this major number. The
close entry point is commonly used by device drivers to
relinquish exclusive access to a device.
This directive calls the device driver close routine specified in the Device
Driver Table for this major number. The close entry point is commonly used by
device drivers to relinquish exclusive access to a device.
**NOTES:**
This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
This directive may or may not cause the calling task to be preempted. This is
dependent on the device driver being invoked.
.. _rtems_io_read:
IO_READ - Read from a device
----------------------------
@ -484,27 +520,32 @@ IO_READ - Read from a device
rtems_status_code rtems_io_read(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument
void *argument
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
This directive calls the device driver read routine
specified in the Device Driver Table for this major number.
Read operations typically require a buffer address as part of
the argument parameter block. The contents of this buffer will
be replaced with data from the device.
This directive calls the device driver read routine specified in the Device
Driver Table for this major number. Read operations typically require a buffer
address as part of the argument parameter block. The contents of this buffer
will be replaced with data from the device.
**NOTES:**
This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
This directive may or may not cause the calling task to be preempted. This is
dependent on the device driver being invoked.
.. _rtems_io_write:
IO_WRITE - Write to a device
----------------------------
@ -519,27 +560,32 @@ IO_WRITE - Write to a device
rtems_status_code rtems_io_write(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument
void *argument
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
This directive calls the device driver write routine
specified in the Device Driver Table for this major number.
Write operations typically require a buffer address as part of
the argument parameter block. The contents of this buffer will
be sent to the device.
This directive calls the device driver write routine specified in the Device
Driver Table for this major number. Write operations typically require a
buffer address as part of the argument parameter block. The contents of this
buffer will be sent to the device.
**NOTES:**
This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
This directive may or may not cause the calling task to be preempted. This is
dependent on the device driver being invoked.
.. _rtems_io_control:
IO_CONTROL - Special device services
------------------------------------
@ -555,34 +601,30 @@ IO_CONTROL - Special device services
rtems_status_code rtems_io_control(
rtems_device_major_number major,
rtems_device_minor_number minor,
void \*argument
void *argument
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - successfully initialized
``RTEMS_INVALID_NUMBER`` - invalid major device number
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- successfully initialized
* - ``RTEMS_INVALID_NUMBER``
- invalid major device number
**DESCRIPTION:**
This directive calls the device driver I/O control
routine specified in the Device Driver Table for this major
number. The exact functionality of the driver entry called by
this directive is driver dependent. It should not be assumed
that the control entries of two device drivers are compatible.
For example, an RS-232 driver I/O control operation may change
the baud rate of a serial line, while an I/O control operation
for a floppy disk driver may cause a seek operation.
This directive calls the device driver I/O control routine specified in the
Device Driver Table for this major number. The exact functionality of the
driver entry called by this directive is driver dependent. It should not be
assumed that the control entries of two device drivers are compatible. For
example, an RS-232 driver I/O control operation may change the baud rate of a
serial line, while an I/O control operation for a floppy disk driver may cause
a seek operation.
**NOTES:**
This directive may or may not cause the calling task
to be preempted. This is dependent on the device driver being
invoked.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
This directive may or may not cause the calling task to be preempted. This is
dependent on the device driver being invoked.

803
c_user/message_manager.rst
View File

File diff suppressed because it is too large Load Diff

411
c_user/partition_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Partition Manager
#################
@ -6,19 +10,18 @@ Partition Manager
Introduction
============
The partition manager provides facilities to
dynamically allocate memory in fixed-size units. The directives
provided by the partition manager are:
The partition manager provides facilities to dynamically allocate memory in
fixed-size units. The directives provided by the partition manager are:
- ``rtems_partition_create`` - Create a partition
- rtems_partition_create_ - Create a partition
- ``rtems_partition_ident`` - Get ID of a partition
- rtems_partition_ident_ - Get ID of a partition
- ``rtems_partition_delete`` - Delete a partition
- rtems_partition_delete_ - Delete a partition
- ``rtems_partition_get_buffer`` - Get buffer from a partition
- rtems_partition_get_buffer_ - Get buffer from a partition
- ``rtems_partition_return_buffer`` - Return buffer to a partition
- rtems_partition_return_buffer_ - Return buffer to a partition
Background
==========
@ -27,41 +30,43 @@ Partition Manager Definitions
-----------------------------
.. index:: partition, definition
A partition is a physically contiguous memory area
divided into fixed-size buffers that can be dynamically
allocated and deallocated... index:: buffers, definition
A partition is a physically contiguous memory area divided into fixed-size
buffers that can be dynamically allocated and deallocated.
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.
When a buffer is on the free buffer chain, RTEMS uses two
pointers of memory from each buffer as the free buffer chain.
When a buffer is allocated, the entire buffer is available for application use.
Therefore, modifying memory that is outside of an allocated
buffer could destroy the free buffer chain or the contents of an
adjacent allocated buffer.
.. index:: 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. When a buffer is on the free buffer chain, RTEMS
uses two pointers of memory from each buffer as the free buffer chain. When a
buffer is allocated, the entire buffer is available for application use.
Therefore, modifying memory that is outside of an allocated buffer could
destroy the free buffer chain or the contents of an adjacent allocated buffer.
Building a Partition Attribute Set
----------------------------------
.. index:: 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:
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:
- ``RTEMS_LOCAL`` - local partition (default)
.. list-table::
:class: rtems-table
- ``RTEMS_GLOBAL`` - global partition
* - ``RTEMS_LOCAL``
- local partition (default)
* - ``RTEMS_GLOBAL``
- global partition
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``RTEMS_DEFAULT_ATTRIBUTES`` should be
specified on this call. The attribute_set parameter should be``RTEMS_GLOBAL`` to indicate that the partition
is to be known globally.
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 ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
call. The attribute_set parameter should be ``RTEMS_GLOBAL`` to indicate that
the partition is to be known globally.
Operations
==========
@ -69,62 +74,60 @@ Operations
Creating a Partition
--------------------
The ``rtems_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``rtems_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
specified partition length and buffer size. If successful,the
unique partition ID is returned to the calling task.
The ``rtems_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 ``rtems_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 specified partition
length and buffer size. If successful,the unique partition ID is returned to
the calling task.
Obtaining Partition IDs
-----------------------
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``rtems_partition_create`` directive, the partition
ID is stored in a user provided location. Second, the partition
ID may be obtained later using the ``rtems_partition_ident``
directive. The partition ID is used by other partition manager directives
to access this partition.
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 ``rtems_partition_create`` directive, the partition ID is stored in a user
provided location. Second, the partition ID may be obtained later using the
``rtems_partition_ident`` directive. The partition ID is used by other
partition manager directives to access this partition.
Acquiring a Buffer
------------------
A buffer can be obtained by calling the``rtems_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
become available.
A buffer can be obtained by calling the ``rtems_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 become
available.
Releasing a Buffer
------------------
Buffers are returned to a partition's free buffer
chain with the ``rtems_partition_return_buffer`` directive. This
directive returns an error status code if the returned buffer
was not previously allocated from this partition.
Buffers are returned to a partition's free buffer chain with the
``rtems_partition_return_buffer`` directive. This directive returns an error
status code if the returned buffer was not previously allocated from this
partition.
Deleting a Partition
--------------------
The ``rtems_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
task attempting to do so will be returned an error status code.
The ``rtems_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 task attempting to do so will be returned an error
status code.
Directives
==========
This section details the partition manager's
directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
This section details the partition manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_partition_create:
PARTITION_CREATE - Create a partition
-------------------------------------
@ -138,74 +141,87 @@ PARTITION_CREATE - Create a partition
rtems_status_code rtems_partition_create(
rtems_name name,
void \*starting_address,
void *starting_address,
uint32_t length,
uint32_t buffer_size,
rtems_attribute attribute_set,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - partition created successfully
``RTEMS_INVALID_NAME`` - invalid partition name
``RTEMS_TOO_MANY`` - too many partitions created
``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary
``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_INVALID_SIZE`` - length or buffer size is 0
``RTEMS_INVALID_SIZE`` - length is less than the buffer size
``RTEMS_INVALID_SIZE`` - buffer size not a multiple of 4
``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured
``RTEMS_TOO_MANY`` - too many global objects
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- partition created successfully
* - ``RTEMS_INVALID_NAME``
- invalid partition name
* - ``RTEMS_TOO_MANY``
- too many partitions created
* - ``RTEMS_INVALID_ADDRESS``
- address not on four byte boundary
* - ``RTEMS_INVALID_ADDRESS``
- ``starting_address`` is NULL
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_SIZE``
- length or buffer size is 0
* - ``RTEMS_INVALID_SIZE``
- length is less than the buffer size
* - ``RTEMS_INVALID_SIZE``
- buffer size not a multiple of 4
* - ``RTEMS_MP_NOT_CONFIGURED``
- multiprocessing not configured
* - ``RTEMS_TOO_MANY``
- too many global objects
**DESCRIPTION:**
This directive creates a partition of fixed size
buffers from a physically contiguous memory space which starts
at starting_address and is length bytes in size. Each allocated
buffer is to be of ``buffer_size`` in bytes. The assigned
partition id is returned in ``id``. This partition id is used to
access the partition with other partition related directives.
For control and maintenance of the partition, RTEMS allocates a
PTCB from the local PTCB free pool and initializes it.
This directive creates a partition of fixed size buffers from a physically
contiguous memory space which starts at starting_address and is length bytes in
size. Each allocated buffer is to be of ``buffer_size`` in bytes. The
assigned partition id is returned in ``id``. This partition id is used to
access the partition with other partition related directives. For control and
maintenance of the partition, RTEMS allocates a PTCB from the local PTCB free
pool and initializes it.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
The ``starting_address`` must be properly aligned for the
target architecture.
The ``starting_address`` must be properly aligned for the target architecture.
The ``buffer_size`` parameter must be a multiple of
the CPU alignment factor. Additionally, ``buffer_size``
must be large enough to hold two pointers on the target
architecture. This is required for RTEMS to manage the
buffers when they are free.
The ``buffer_size`` parameter must be a multiple of the CPU alignment factor.
Additionally, ``buffer_size`` must be large enough to hold two pointers on the
target architecture. This is required for RTEMS to manage the buffers when
they are free.
Memory from the partition is not used by RTEMS to
store the Partition Control Block.
Memory from the partition is not used by RTEMS to store the Partition Control
Block.
The following partition attribute constants are
defined by RTEMS:
The following partition attribute constants are defined by RTEMS:
- ``RTEMS_LOCAL`` - local partition (default)
.. list-table::
:class: rtems-table
- ``RTEMS_GLOBAL`` - global partition
* - ``RTEMS_LOCAL``
- local partition (default)
* - ``RTEMS_GLOBAL``
- global partition
The PTCB for a global partition is allocated on the
local node. The memory space used for the partition must reside
in shared memory. Partitions should not be made global unless
remote tasks must interact with the partition. This is to avoid
the overhead incurred by the creation of a global partition.
When a global partition is created, the partition's name and id
must be transmitted to every node in the system for insertion in
the local copy of the global object table.
The PTCB for a global partition is allocated on the local node. The memory
space used for the partition must reside in shared memory. Partitions should
not be made global unless remote tasks must interact with the partition. This
is to avoid the overhead incurred by the creation of a global partition. When
a global partition is created, the partition's name and id must be transmitted
to every node in the system for insertion in the local copy of the global
object table.
The total number of global objects, including
partitions, is limited by the maximum_global_objects field in
the Configuration Table.
The total number of global objects, including partitions, is limited by the
maximum_global_objects field in the Configuration Table.
.. _rtems_partition_ident:
PARTITION_IDENT - Get ID of a partition
---------------------------------------
@ -221,41 +237,46 @@ PARTITION_IDENT - Get ID of a partition
rtems_status_code rtems_partition_ident(
rtems_name name,
uint32_t node,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - partition identified successfully
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_INVALID_NAME`` - partition name not found
``RTEMS_INVALID_NODE`` - invalid node id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- partition identified successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_NAME``
- partition name not found
* - ``RTEMS_INVALID_NODE``
- invalid node id
**DESCRIPTION:**
This directive obtains the partition id associated
with the partition name. If the partition name is not unique,
then the partition id will match one of the partitions with that
name. However, this partition id is not guaranteed to
correspond to the desired partition. The partition id is used
with other partition related directives to access the partition.
This directive obtains the partition id associated with the partition name. If
the partition name is not unique, then the partition id will match one of the
partitions with that name. However, this partition id is not guaranteed to
correspond to the desired partition. The partition id is used with other
partition related directives to access the partition.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched
with the local node being searched first. All other nodes are
searched with the lowest numbered node searched first.
If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the local
node being searched first. All other nodes are searched with the lowest
numbered node searched first.
If node is a valid node number which does not
represent the local node, then only the partitions exported by
the designated node are searched.
If node is a valid node number which does not represent the local node, then
only the partitions exported by the designated node are searched.
This directive does not generate activity on remote
nodes. It accesses only the local copy of the global object
table.
This directive does not generate activity on remote nodes. It accesses only
the local copy of the global object table.
.. _rtems_partition_delete:
PARTITION_DELETE - Delete a partition
-------------------------------------
@ -273,33 +294,39 @@ PARTITION_DELETE - Delete a partition
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - partition deleted successfully
``RTEMS_INVALID_ID`` - invalid partition id
``RTEMS_RESOURCE_IN_USE`` - buffers still in use
``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote partition
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- partition deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_RESOURCE_IN_USE``
- buffers still in use
* - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- cannot delete remote partition
**DESCRIPTION:**
This directive deletes the partition specified by id.
The partition cannot be deleted if any of its buffers are still
allocated. The PTCB for the deleted partition is reclaimed by
RTEMS.
This directive deletes the partition specified by id. The partition cannot be
deleted if any of its buffers are still allocated. The PTCB for the deleted
partition is reclaimed by RTEMS.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
The calling task does not have to be the task that
created the partition. Any local task that knows the partition
id can delete the partition.
The calling task does not have to be the task that created the partition. Any
local task that knows the partition id can delete the partition.
When a global partition is deleted, the partition id
must be transmitted to every node in the system for deletion
from the local copy of the global object table.
When a global partition is deleted, the partition id 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 ``RTEMS_GLOBAL`` option.
The partition must reside on the local node, even if the partition was created
with the ``RTEMS_GLOBAL`` option.
.. _rtems_partition_get_buffer:
PARTITION_GET_BUFFER - Get buffer from a partition
--------------------------------------------------
@ -314,34 +341,41 @@ PARTITION_GET_BUFFER - Get buffer from a partition
rtems_status_code rtems_partition_get_buffer(
rtems_id id,
void \**buffer
void **buffer
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - buffer obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
``RTEMS_INVALID_ID`` - invalid partition id
``RTEMS_UNSATISFIED`` - all buffers are allocated
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- buffer obtained successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``buffer`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_UNSATISFIED``
- all buffers are allocated
**DESCRIPTION:**
This directive allows a buffer to be obtained from
the partition specified in id. The address of the allocated
buffer is returned in buffer.
This directive allows a buffer to be obtained from the partition specified
in id. The address of the allocated buffer is returned in buffer.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
All buffers begin on a four byte boundary.
A task cannot wait on a buffer to become available.
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.
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.
.. _rtems_partition_return_buffer:
PARTITION_RETURN_BUFFER - Return buffer to a partition
------------------------------------------------------
@ -355,36 +389,35 @@ PARTITION_RETURN_BUFFER - Return buffer to a partition
rtems_status_code rtems_partition_return_buffer(
rtems_id id,
void \*buffer
void *buffer
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - buffer returned successfully
``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL
``RTEMS_INVALID_ID`` - invalid partition id
``RTEMS_INVALID_ADDRESS`` - buffer address not in partition
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- buffer returned successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``buffer`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_INVALID_ADDRESS``
- buffer address not in partition
**DESCRIPTION:**
This directive returns the buffer specified by buffer
to the partition specified by id.
This directive returns the buffer specified by buffer to the partition
specified by id.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
Returning a buffer to a global partition which does
not reside on the local node will generate a request telling the
remote node to return the buffer to the specified partition.
Returning a buffer to a global partition which does not reside on the local
node will generate a request telling the remote node to return the buffer to
the specified partition.
Returning a buffer multiple times is an error. It will corrupt the internal
state of the partition.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

640
c_user/region_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Region Manager
##############
@ -6,25 +10,24 @@ Region Manager
Introduction
============
The region manager provides facilities to dynamically
allocate memory in variable sized units. The directives
provided by the region manager are:
The region manager provides facilities to dynamically allocate memory in
variable sized units. The directives provided by the region manager are:
- ``rtems_region_create`` - Create a region
- rtems_region_create_ - Create a region
- ``rtems_region_ident`` - Get ID of a region
- rtems_region_ident_ - Get ID of a region
- ``rtems_region_delete`` - Delete a region
- rtems_region_delete_ - Delete a region
- ``rtems_region_extend`` - Add memory to a region
- rtems_region_extend_ - Add memory to a region
- ``rtems_region_get_segment`` - Get segment from a region
- rtems_region_get_segment_ - Get segment from a region
- ``rtems_region_return_segment`` - Return segment to a region
- rtems_region_return_segment_ - Return segment to a region
- ``rtems_region_get_segment_size`` - Obtain size of a segment
- rtems_region_get_segment_size_ - Obtain size of a segment
- ``rtems_region_resize_segment`` - Change size of a segment
- rtems_region_resize_segment_ - Change size of a segment
Background
==========
@ -34,80 +37,79 @@ Region Manager Definitions
.. index:: region, definition
.. index:: 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
is a variable size section of memory which is allocated in
multiples of a user-defined page size. This page size is
required to be a multiple of four greater than or equal to four.
For example, if a request for a 350-byte segment is made in a
region with 256-byte pages, then a 512-byte segment is allocated.
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 is a variable size section of memory which is allocated
in multiples of a user-defined page size. This page size is required to be a
multiple of four greater than or equal to four. For example, if a request for
a 350-byte segment is made in a region with 256-byte pages, then a 512-byte
segment is allocated.
Regions are organized as doubly linked chains of
variable sized memory blocks. Memory requests are allocated
using a first-fit algorithm. If available, the requester
receives the number of bytes requested (rounded up to the next
page size). RTEMS requires some overhead from the region's
memory for each segment that is allocated. Therefore, an
application should only modify the memory of a segment that has
been obtained from the region. The application should NOT
modify the memory outside of any obtained segments and within
the region's boundaries while the region is currently active in
the system.
Regions are organized as doubly linked chains of variable sized memory blocks.
Memory requests are allocated using a first-fit algorithm. If available, the
requester receives the number of bytes requested (rounded up to the next page
size). RTEMS requires some overhead from the region's memory for each segment
that is allocated. Therefore, an application should only modify the memory of
a segment that has been obtained from the region. The application should NOT
modify the memory outside of any obtained segments and within the region's
boundaries while the region is currently active in the system.
Upon return to the region, the free block is
coalesced with its neighbors (if free) on both sides to produce
the largest possible unused block.
Upon return to the region, the free block is coalesced with its neighbors (if
free) on both sides to produce the largest possible unused block.
Building an Attribute Set
-------------------------
.. index:: 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:
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:
- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
.. list-table::
:class: rtems-table
- ``RTEMS_PRIORITY`` - tasks wait by priority
* - ``RTEMS_FIFO``
- tasks wait by FIFO (default)
* - ``RTEMS_PRIORITY``
- tasks wait by priority
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``RTEMS_DEFAULT_ATTRIBUTES`` should be
specified on this call.
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 ``RTEMS_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``rtems_region_create``
directive should be ``RTEMS_PRIORITY``.
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 ``rtems_region_create`` directive should be ``RTEMS_PRIORITY``.
Building an Option Set
----------------------
In general, an option is built by a bitwise OR of the
desired option components. The set of valid options for the``rtems_region_get_segment`` directive are
listed in the following table:
In general, an option is built by a bitwise OR of the desired option
components. The set of valid options for the ``rtems_region_get_segment``
directive are listed in the following table:
- ``RTEMS_WAIT`` - task will wait for segment (default)
.. list-table::
:class: rtems-table
- ``RTEMS_NO_WAIT`` - task should not wait
* - ``RTEMS_WAIT``
- task will wait for segment (default)
* - ``RTEMS_NO_WAIT``
- task should not wait
Option values are specifically designed to be
mutually exclusive, therefore bitwise OR and addition operations
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``RTEMS_DEFAULT_OPTIONS`` should be
specified on this call.
Option values are specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations 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 ``RTEMS_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``rtems_region_get_segment`` directive should
be ``RTEMS_NO_WAIT``.
This example demonstrates the option parameter needed to poll for a segment.
The option parameter passed to the ``rtems_region_get_segment`` directive
should be ``RTEMS_NO_WAIT``.
Operations
==========
@ -115,121 +117,112 @@ Operations
Creating a Region
-----------------
The ``rtems_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
list to maintain the newly created region. RTEMS also generates
a unique region ID which is returned to the calling task.
The ``rtems_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 list to maintain the newly created region. RTEMS
also generates a unique region ID which is returned to the calling task.
It is not possible to calculate the exact number of
bytes available to the user since RTEMS requires overhead for
each segment allocated. For example, a region with one segment
that is the size of the entire region has more available bytes
than a region with two segments that collectively are the size
of the entire region. This is because the region with one
segment requires only the overhead for one segment, while the
other region requires the overhead for two segments.
It is not possible to calculate the exact number of bytes available to the user
since RTEMS requires overhead for each segment allocated. For example, a
region with one segment that is the size of the entire region has more
available bytes than a region with two segments that collectively are the size
of the entire region. This is because the region with one segment requires
only the overhead for one segment, while the other region requires the overhead
for two segments.
Due to automatic coalescing, the number of segments
in the region dynamically changes. Therefore, the total
overhead required by RTEMS dynamically changes.
Due to automatic coalescing, the number of segments in the region dynamically
changes. Therefore, the total overhead required by RTEMS dynamically changes.
Obtaining Region IDs
--------------------
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``rtems_region_create`` directive,
the region ID is stored in a user
provided location. Second, the region ID may be obtained later
using the ``rtems_region_ident`` directive.
The region ID is used by other region manager directives to
access this region.
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
``rtems_region_create`` directive, the region ID is stored in a user provided
location. Second, the region ID may be obtained later using the
``rtems_region_ident`` directive. The region ID is used by other region
manager directives to access this region.
Adding Memory to a Region
-------------------------
The ``rtems_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.
The ``rtems_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.
NOTE: Please see the release notes or RTEMS source
code for information regarding restrictions on the location of
the memory being added in relation to memory already in the
region.
.. note::
Please see the release notes or RTEMS source code for information regarding
restrictions on the location of the memory being added in relation to memory
already in the region.
Acquiring a Segment
-------------------
The ``rtems_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
following situations applies:
The ``rtems_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 following situations applies:
- By default, the calling task will wait forever to acquire the segment.
- Specifying the ``RTEMS_NO_WAIT`` option forces
an immediate return with an error status code.
- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an
error status code.
- Specifying a timeout limits the interval the task will
wait before returning with an error status code.
- Specifying a timeout limits the interval the task will wait before returning
with an error status code.
If the task waits for the segment, then it is placed
in the region's task wait queue in either FIFO or task priority
order. All tasks waiting on a region are returned an error when
the message queue is deleted.
If the task waits for the segment, then it is placed in the region's task wait
queue in either FIFO or task priority order. All tasks waiting on a region are
returned an error when the message queue is deleted.
Releasing a Segment
-------------------
When a segment is returned to a region by the``rtems_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
segment and unblocked. This process is repeated until the first
task's segment request cannot be satisfied.
When a segment is returned to a region by the ``rtems_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 segment and
unblocked. This process is repeated until the first task's segment request
cannot be satisfied.
Obtaining the Size of a Segment
-------------------------------
The ``rtems_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.
The ``rtems_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.
Changing the Size of a Segment
------------------------------
The ``rtems_region_resize_segment`` directive is used
to change the size in bytes of the specified segment. The size may be
increased or decreased. When increasing the size of a segment, it is
possible that the request cannot be satisfied. This directive provides
functionality similar to the ``realloc()`` function in the Standard
C Library.
The ``rtems_region_resize_segment`` directive is used to change the size in
bytes of the specified segment. The size may be increased or decreased. When
increasing the size of a segment, it is possible that the request cannot be
satisfied. This directive provides functionality similar to the ``realloc()``
function in the Standard C Library.
Deleting a Region
-----------------
A region can be removed from the system and returned
to RTEMS with the ``rtems_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
error. As a result of this directive, all tasks blocked waiting
to obtain a segment from the region will be readied and returned
a status code which indicates that the region was deleted.
A region can be removed from the system and returned to RTEMS with the
``rtems_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
error. As a result of this directive, all tasks blocked waiting to obtain a
segment from the region will be readied and returned a status code which
indicates that the region was deleted.
Directives
==========
This section details the region manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
This section details the region manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_region_create:
REGION_CREATE - Create a region
-------------------------------
@ -243,58 +236,70 @@ REGION_CREATE - Create a region
rtems_status_code rtems_region_create(
rtems_name name,
void \*starting_address,
void *starting_address,
intptr_t length,
uint32_t page_size,
rtems_attribute attribute_set,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - region created successfully
``RTEMS_INVALID_NAME`` - invalid region name
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL
``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary
``RTEMS_TOO_MANY`` - too many regions created
``RTEMS_INVALID_SIZE`` - invalid page size
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- region created successfully
* - ``RTEMS_INVALID_NAME``
- invalid region name
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_ADDRESS``
- ``starting_address`` is NULL
* - ``RTEMS_INVALID_ADDRESS``
- address not on four byte boundary
* - ``RTEMS_TOO_MANY``
- too many regions created
* - ``RTEMS_INVALID_SIZE``
- invalid page size
**DESCRIPTION:**
This directive creates a region from a physically
contiguous memory space which starts at starting_address and is
length bytes long. Segments allocated from the region will be a
multiple of page_size bytes in length. The assigned region id
is returned in id. This region id is used as an argument to
other region related directives to access the region.
This directive creates a region from a physically contiguous memory space which
starts at starting_address and is length bytes long. Segments allocated from
the region will be a multiple of page_size bytes in length. The assigned
region id is returned in id. This region id is used as an argument to other
region related directives to access the region.
For control and maintenance of the region, RTEMS
allocates and initializes an RNCB from the RNCB free pool. Thus
memory from the region is not used to store the RNCB. However,
some overhead within the region is required by RTEMS each time a
segment is constructed in the region.
For control and maintenance of the region, RTEMS allocates and initializes an
RNCB from the RNCB free pool. Thus memory from the region is not used to store
the RNCB. However, some overhead within the region is required by RTEMS each
time a segment is constructed in the region.
Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks
waiting for a segment to be serviced according to task priority.
Specifying ``RTEMS_FIFO`` in attribute_set or selecting``RTEMS_DEFAULT_ATTRIBUTES`` will cause waiting tasks to
be serviced in First In-First Out order.
Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a
segment to be serviced according to task priority. Specifying ``RTEMS_FIFO``
in attribute_set or selecting ``RTEMS_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
of four greater than or equal to eight.
The ``starting_address`` parameter must be aligned on a four byte boundary.
The ``page_size`` parameter must be a multiple of four greater than or equal to
eight.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
The following region attribute constants are defined
by RTEMS:
The following region attribute constants are defined by RTEMS:
- ``RTEMS_FIFO`` - tasks wait by FIFO (default)
.. list-table::
:class: rtems-table
- ``RTEMS_PRIORITY`` - tasks wait by priority
* - ``RTEMS_FIFO``
- tasks wait by FIFO (default)
* - ``RTEMS_PRIORITY``
- tasks wait by priority
.. _rtems_region_ident:
REGION_IDENT - Get ID of a region
---------------------------------
@ -309,28 +314,35 @@ REGION_IDENT - Get ID of a region
rtems_status_code rtems_region_ident(
rtems_name name,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - region identified successfully
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL
``RTEMS_INVALID_NAME`` - region name not found
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- region identified successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_NAME``
- region name not found
**DESCRIPTION:**
This directive obtains the region id associated with
the region name to be acquired. If the region name is not
unique, then the region id will match one of the regions with
that name. However, this region id is not guaranteed to
correspond to the desired region. The region id is used to
access this region in other region manager directives.
This directive obtains the region id associated with the region name to be
acquired. If the region name is not unique, then the region id will match one
of the regions with that name. However, this region id is not guaranteed to
correspond to the desired region. The region id is used to access this region
in other region manager directives.
**NOTES:**
This directive will not cause the running task to be preempted.
.. _rtems_region_delete:
REGION_DELETE - Delete a region
-------------------------------
.. index:: delete a region
@ -347,24 +359,30 @@ REGION_DELETE - Delete a region
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - region deleted successfully
``RTEMS_INVALID_ID`` - invalid region id
``RTEMS_RESOURCE_IN_USE`` - segments still in use
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- region deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid region id
* - ``RTEMS_RESOURCE_IN_USE``
- segments still in use
**DESCRIPTION:**
This directive deletes the region specified by id.
The region cannot be deleted if any of its segments are still
allocated. The RNCB for the deleted region is reclaimed by
RTEMS.
This directive deletes the region specified by id. The region cannot be
deleted if any of its segments are still allocated. The RNCB for the deleted
region is reclaimed by RTEMS.
**NOTES:**
This directive will not cause the calling task to be preempted.
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.
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.
.. _rtems_region_extend:
REGION_EXTEND - Add memory to a region
--------------------------------------
@ -379,29 +397,37 @@ REGION_EXTEND - Add memory to a region
rtems_status_code rtems_region_extend(
rtems_id id,
void \*starting_address,
void *starting_address,
intptr_t length
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - region extended successfully
``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL
``RTEMS_INVALID_ID`` - invalid region id
``RTEMS_INVALID_ADDRESS`` - invalid address of area to add
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- region extended successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``starting_address`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid region id
* - ``RTEMS_INVALID_ADDRESS``
- invalid address of area to add
**DESCRIPTION:**
This directive adds the memory which starts at
starting_address for length bytes to the region specified by id.
This directive adds the memory which starts at starting_address for length
bytes to the region specified by id.
**NOTES:**
This directive will not cause the calling task to be preempted.
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.
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.
.. _rtems_region_get_segment:
REGION_GET_SEGMENT - Get segment from a region
----------------------------------------------
@ -418,64 +444,72 @@ REGION_GET_SEGMENT - Get segment from a region
intptr_t size,
rtems_option option_set,
rtems_interval timeout,
void \**segment
void **segment
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - segment obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
``RTEMS_INVALID_ID`` - invalid region id
``RTEMS_INVALID_SIZE`` - request is for zero bytes or exceeds
the size of maximum segment which is possible for this region
``RTEMS_UNSATISFIED`` - segment of requested size not available
``RTEMS_TIMEOUT`` - timed out waiting for segment
``RTEMS_OBJECT_WAS_DELETED`` - region deleted while waiting
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- segment obtained successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``segment`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid region id
* - ``RTEMS_INVALID_SIZE``
- request is for zero bytes or exceeds the size of maximum segment which is
possible for this region
* - ``RTEMS_UNSATISFIED``
- segment of requested size not available
* - ``RTEMS_TIMEOUT``
- timed out waiting for segment
* - ``RTEMS_OBJECT_WAS_DELETED``
- region deleted while waiting
**DESCRIPTION:**
This directive obtains a variable size segment from
the region specified by id. The address of the allocated
segment is returned in segment. The ``RTEMS_WAIT``
and ``RTEMS_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
sufficiently sized segment is available, then the segment is
successfully acquired by returning immediately with the``RTEMS_SUCCESSFUL`` status code.
This directive obtains a variable size segment from the region specified by
``id``. The address of the allocated segment is returned in segment. The
``RTEMS_WAIT`` and ``RTEMS_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 sufficiently sized segment is available, then the segment is successfully
acquired by returning immediately with the ``RTEMS_SUCCESSFUL`` status code.
If the calling task chooses to return immediately and
a segment large enough is not available, then an error code
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 ``RTEMS_PRIORITY`` option, then the calling
task is inserted into the
wait queue according to its priority. However, if the region
was created with the ``RTEMS_FIFO`` option, then the calling
task is placed at the rear of the wait queue.
If the calling task chooses to return immediately and a segment large enough is
not available, then an error code 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 ``RTEMS_PRIORITY`` option,
then the calling task is inserted into the wait queue according to its
priority. However, if the region was created with the ``RTEMS_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 ``RTEMS_NO_TIMEOUT``, then the
The timeout parameter specifies the maximum interval that a task is willing to
wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``, then the
calling task will wait forever.
**NOTES:**
The actual length of the allocated segment may be
larger than the requested size because a segment size is always
a multiple of the region's page size.
The actual length of the allocated segment may be larger than the requested
size because a segment size is always a multiple of the region's page size.
The following segment acquisition option constants
are defined by RTEMS:
The following segment acquisition option constants are defined by RTEMS:
- ``RTEMS_WAIT`` - task will wait for segment (default)
.. list-table::
:class: rtems-table
- ``RTEMS_NO_WAIT`` - task should not wait
* - ``RTEMS_WAIT``
- task will wait for segment (default)
* - ``RTEMS_NO_WAIT``
- task should not wait
A clock tick is required to support the timeout functionality of
this directive.
A clock tick is required to support the timeout functionality of this
directive.
.. _rtems_region_return_segment:
REGION_RETURN_SEGMENT - Return segment to a region
--------------------------------------------------
@ -489,36 +523,43 @@ REGION_RETURN_SEGMENT - Return segment to a region
rtems_status_code rtems_region_return_segment(
rtems_id id,
void \*segment
void *segment
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - segment returned successfully
``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
``RTEMS_INVALID_ID`` - invalid region id
``RTEMS_INVALID_ADDRESS`` - segment address not in region
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- segment returned successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``segment`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid region id
* - ``RTEMS_INVALID_ADDRESS``
- segment address not in region
**DESCRIPTION:**
This directive returns the segment specified by
segment to the region specified by id. The returned segment is
merged with its 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
segment and unblocked. This process is repeated until the first
task's segment request cannot be satisfied.
This directive returns the segment specified by segment to the region specified
by id. The returned segment is merged with its 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 segment and
unblocked. This process is repeated until the first task's segment request
cannot be satisfied.
**NOTES:**
This directive will cause the calling task to be
preempted if one or more local tasks are waiting for a segment
and the following conditions exist:
This directive will cause the calling task to be preempted if one or more local
tasks are waiting for a segment and the following conditions exist:
- a waiting task has a higher priority than the calling task
- the size of the segment required by the waiting task
is less than or equal to the size of the segment returned.
- the size of the segment required by the waiting task is less than or equal to
the size of the segment returned.
.. _rtems_region_get_segment_size:
REGION_GET_SEGMENT_SIZE - Obtain size of a segment
--------------------------------------------------
@ -532,17 +573,25 @@ REGION_GET_SEGMENT_SIZE - Obtain size of a segment
rtems_status_code rtems_region_get_segment_size(
rtems_id id,
void \*segment,
ssize_t \*size
void *segment,
ssize_t *size
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - segment obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
``RTEMS_INVALID_ADDRESS`` - ``size`` is NULL
``RTEMS_INVALID_ID`` - invalid region id
``RTEMS_INVALID_ADDRESS`` - segment address not in region
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- segment obtained successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``segment`` is NULL
* - ``RTEMS_INVALID_ADDRESS``
- ``size`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid region id
* - ``RTEMS_INVALID_ADDRESS``
- segment address not in region
**DESCRIPTION:**
@ -550,9 +599,10 @@ This directive obtains the size in bytes of the specified segment.
**NOTES:**
The actual length of the allocated segment may be
larger than the requested size because a segment size is always
a multiple of the region's page size.
The actual length of the allocated segment may be larger than the requested
size because a segment size is always a multiple of the region's page size.
.. _rtems_region_resize_segment:
REGION_RESIZE_SEGMENT - Change size of a segment
------------------------------------------------
@ -566,36 +616,38 @@ REGION_RESIZE_SEGMENT - Change size of a segment
rtems_status_code rtems_region_resize_segment(
rtems_id id,
void \*segment,
void *segment,
ssize_t size,
ssize_t \*old_size
ssize_t *old_size
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - segment obtained successfully
``RTEMS_INVALID_ADDRESS`` - ``segment`` is NULL
``RTEMS_INVALID_ADDRESS`` - ``old_size`` is NULL
``RTEMS_INVALID_ID`` - invalid region id
``RTEMS_INVALID_ADDRESS`` - segment address not in region``RTEMS_UNSATISFIED`` - unable to make segment larger
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- segment obtained successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``segment`` is NULL
* - ``RTEMS_INVALID_ADDRESS``
- ``old_size`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid region id
* - ``RTEMS_INVALID_ADDRESS``
- segment address not in region
* - ``RTEMS_UNSATISFIED``
- unable to make segment larger
**DESCRIPTION:**
This directive is used to increase or decrease the size of
a segment. When increasing the size of a segment, it
is possible that there is not memory available contiguous
to the segment. In this case, the request is unsatisfied.
This directive is used to increase or decrease the size of a segment. When
increasing the size of a segment, it is possible that there is not memory
available contiguous to the segment. In this case, the request is unsatisfied.
**NOTES:**
If an attempt to increase the size of a segment fails, then
the application may want to allocate a new segment of the desired
size, copy the contents of the original segment to the new, larger
segment and then return the original segment.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
If an attempt to increase the size of a segment fails, then the application may
want to allocate a new segment of the desired size, copy the contents of the
original segment to the new, larger segment and then return the original
segment.

10
c_user/semaphore_manager.rst
View File

@ -634,9 +634,9 @@ This directive acquires the semaphore specified by id. The ``RTEMS_WAIT`` and
``RTEMS_NO_WAIT`` components of the options parameter indicate whether the
calling task wants to wait for the semaphore to become available or return
immediately if the semaphore is not currently available. With either
``RTEMS_WAIT`` or``RTEMS_NO_WAIT``, if the current semaphore count is positive,
then it is decremented by one and the semaphore is successfully acquired by
returning immediately with a successful return code.
``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current semaphore count is
positive, then it is 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
@ -656,8 +656,8 @@ 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``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the
willing to be blocked waiting for the semaphore. If it is set to
``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the
semaphore is available or the ``RTEMS_NO_WAIT`` option component is set, then
timeout is ignored.

371
c_user/signal_manager.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Signal Manager
##############
@ -6,13 +10,12 @@ Signal Manager
Introduction
============
The signal manager provides the capabilities required
for asynchronous communication. The directives provided by the
signal manager are:
The signal manager provides the capabilities required for asynchronous
communication. The directives provided by the signal manager are:
- ``rtems_signal_catch`` - Establish an ASR
- rtems_signal_catch_ - Establish an ASR
- ``rtems_signal_send`` - Send signal set to a task
- rtems_signal_send_ - Send signal set to a task
Background
==========
@ -22,107 +25,102 @@ Signal Manager Definitions
.. index:: asynchronous signal routine
.. index:: 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
is interrupted, the execution of an application is also
interrupted and an ISR is given control. Similarly, when a
signal is sent to a task, that task's execution path will be
"interrupted" by the ASR. Sending a signal to a task has no
effect on the receiving task's current execution state... index:: rtems_signal_set
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 is interrupted, the execution of an application is
also interrupted and an ISR is given control. Similarly, when a signal is sent
to a task, that task's execution path will be "interrupted" by the ASR.
Sending a signal to a task has no effect on the receiving task's current
execution state.
A signal flag is used by a task (or ISR) to inform
another task of the occurrence of a significant situation.
Thirty-two signal flags are associated with each task. A
collection of one or more signals is referred to as a signal
set. The data type ``rtems_signal_set``
is used to manipulate signal sets.
.. index:: rtems_signal_set
A signal set is posted when it is directed (or sent) to a
task. A pending signal is a signal that has been sent to a task
with a valid ASR, but has not been processed by that task's ASR.
A signal flag is used by a task (or ISR) to inform another task of the
occurrence of a significant situation. Thirty-two signal flags are associated
with each task. A collection of one or more signals is referred to as a signal
set. The data type ``rtems_signal_set`` is used to manipulate signal sets.
A signal set is posted when it is directed (or sent) to a task. A pending
signal is a signal that has been sent to a task with a valid ASR, but has not
been processed by that task's ASR.
A Comparison of ASRs and ISRs
-----------------------------
.. index:: ASR vs. ISR
.. index:: ISR vs. ASR
The format of an ASR is similar to that of an ISR
with the following exceptions:
The format of an ASR is similar to that of an ISR with the following
exceptions:
- ISRs are scheduled by the processor hardware. ASRs are
scheduled by RTEMS.
- ISRs are scheduled by the processor hardware. ASRs are scheduled by RTEMS.
- ISRs do not execute in the context of a task and may
invoke only a subset of directives. ASRs execute in the context
of a task and may execute any directive.
- ISRs do not execute in the context of a task and may invoke only a subset of
directives. ASRs execute in the context of a task and may execute any
directive.
- When an ISR is invoked, it is passed the vector number
as its argument. When an ASR is invoked, it is passed the
signal set as its argument.
- When an ISR is invoked, it is passed the vector number as its argument. When
an ASR is invoked, it is passed the signal set as its argument.
- An ASR has a task mode which can be different from that
of the task. An ISR does not execute as a task and, as a
result, does not have a task mode.
- An ASR has a task mode which can be different from that of the task. An ISR
does not execute as a task and, as a result, does not have a task mode.
Building a Signal Set
---------------------
.. index:: signal set, building
A signal set is built by a bitwise OR of the desired
signals. The set of valid signals is ``RTEMS_SIGNAL_0`` through``RTEMS_SIGNAL_31``. If a signal is not explicitly specified in the
signal set, then it is not present. Signal values are
specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations are equivalent as long as
each signal appears exactly once in the component list.
A signal set is built by a bitwise OR of the desired signals. The set of valid
signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not
explicitly specified in the signal set, then it is not present. Signal values
are specifically designed to be mutually exclusive, therefore 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``RTEMS_SIGNAL_6``,``RTEMS_SIGNAL_15``, and``RTEMS_SIGNAL_31``. The signal parameter provided
to the ``rtems_signal_send`` directive should be``RTEMS_SIGNAL_6 |
RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
This example demonstrates the signal parameter used when sending the signal set
consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``.
The signal parameter provided to the ``rtems_signal_send`` directive should be
``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
Building an ASR Mode
--------------------
.. index:: 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
directives. A complete list of mode options is provided in the
following table:
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 directives. A complete list of mode options is
provided in the following table:
- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption
.. list-table::
:class: rtems-table
- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption
* - ``RTEMS_PREEMPT``
- is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
* - ``RTEMS_NO_PREEMPT``
- is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
* - ``RTEMS_NO_TIMESLICE``
- is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
* - ``RTEMS_TIMESLICE``
- is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
* - ``RTEMS_ASR``
- is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
* - ``RTEMS_NO_ASR``
- is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
* - ``RTEMS_INTERRUPT_LEVEL(0)``
- is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
* - ``RTEMS_INTERRUPT_LEVEL(n)``
- is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing
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 list, although it is a good programming
practice to specify default components. If all defaults are desired, the mode
``DEFAULT_MODES`` should be specified on this call.
- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing
- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing
- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing
- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts
- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
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 list, although it is a good
programming practice to specify default components. If all
defaults are desired, the mode DEFAULT_MODES should be specified
on this call.
This example demonstrates the mode parameter used
with the ``rtems_signal_catch``
to establish an ASR which executes at
interrupt level three and is non-preemptible. The mode should
be set to``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT``
to indicate the
desired processor mode and interrupt level.
This example demonstrates the mode parameter used with the
``rtems_signal_catch`` to establish an ASR which executes at interrupt level
three and is non-preemptible. The mode should be set to
``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired
processor mode and interrupt level.
Operations
==========
@ -130,71 +128,62 @@ Operations
Establishing an ASR
-------------------
The ``rtems_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 ``rtems_signal_catch`` the first time,
its ASR is invalid, and no signal sets can be sent to the task.
The ``rtems_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 ``rtems_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 ``rtems_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 invalidate its ASR and discard all pending signals by calling
``rtems_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 (``RTEMS_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.
A task may disable ASR processing (``RTEMS_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 ``rtems_signal_catch``
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 ``rtems_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,
the ASR must be reentrant.
Normally, signal processing is disabled for the ASR's execution mode, but if
signal processing is enabled for the ASR, the ASR must be reentrant.
Sending a Signal Set
--------------------
The ``rtems_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``rtems_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
next time the task is dispatched to run. The ASR is executed
immediately before the task is dispatched. If the currently
running task sends a signal to itself or is sent a signal from
an ISR, its ASR is immediately dispatched to run provided signal
processing is enabled.
The ``rtems_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
``rtems_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 next time the task is dispatched to run. The ASR is executed immediately
before the task is dispatched. If the currently running task sends a signal to
itself or is sent a signal from an ISR, its ASR is immediately dispatched to
run provided signal processing is enabled.
If an ASR with signals enabled is preempted by
another task or an ISR and a new signal set is sent, then a new
copy of the ASR will be invoked, nesting the preempted ASR.
Upon completion of processing the new signal set, control will
return to the preempted ASR. In this situation, the ASR must be
reentrant.
If an ASR with signals enabled is preempted by another task or an ISR and a new
signal set is sent, then a new copy of the ASR will be invoked, nesting the
preempted ASR. Upon completion of processing the new signal set, control will
return to the preempted ASR. In this situation, the ASR must be reentrant.
Like events, identical signals sent to a task are not
queued. In other words, sending the same signal multiple times
to a task (without any intermediate signal processing occurring
for the task), has the same result as sending that signal to
that task once.
Like events, identical signals sent to a task are not queued. In other words,
sending the same signal multiple times to a task (without any intermediate
signal processing occurring for the task), has the same result as sending that
signal to that task once.
Processing an ASR
-----------------
Asynchronous signals were designed to provide the
capability to generate software interrupts. The processing of
software interrupts parallels that of hardware interrupts. As a
result, the differences between the formats of ASRs and ISRs is
limited to the meaning of the single argument passed to an ASR.
The ASR should have the following calling sequence and adhere to
C calling conventions:.. index:: rtems_asr
Asynchronous signals were designed to provide the capability to generate
software interrupts. The processing of software interrupts parallels that of
hardware interrupts. As a result, the differences between the formats of ASRs
and ISRs is limited to the meaning of the single argument passed to an ASR.
The ASR should have the following calling sequence and adhere to C calling
conventions:
.. index:: rtems_asr
.. code:: c
@ -202,17 +191,17 @@ C calling conventions:.. index:: rtems_asr
rtems_signal_set signals
);
When the ASR returns to RTEMS the mode and execution
path of the interrupted task (or ASR) is restored to the context
prior to entering the ASR.
When the ASR returns to RTEMS the mode and execution path of the interrupted
task (or ASR) is restored to the context prior to entering the ASR.
Directives
==========
This section details the signal manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
This section details the signal manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_signal_catch:
SIGNAL_CATCH - Establish an ASR
-------------------------------
@ -232,41 +221,49 @@ SIGNAL_CATCH - Establish an ASR
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - always successful
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- always successful
**DESCRIPTION:**
This directive establishes an asynchronous signal
routine (ASR) for the calling task. The asr_handler parameter
specifies the entry point of the ASR. If asr_handler is NULL,
the ASR for the calling task is invalidated and all pending
signals are cleared. Any signals sent to a task with an invalid
ASR are discarded. The mode parameter specifies the execution
mode for the ASR. This execution mode supersedes the task's
execution mode while the ASR is executing.
This directive establishes an asynchronous signal routine (ASR) for the calling
task. The asr_handler parameter specifies the entry point of the ASR. If
asr_handler is NULL, the ASR for the calling task is invalidated and all
pending signals are cleared. Any signals sent to a task with an invalid ASR
are discarded. The mode parameter specifies the execution mode for the ASR.
This execution mode supersedes the task's execution mode while the ASR is
executing.
**NOTES:**
This directive will not cause the calling task to be
preempted.
This directive will not cause the calling task to be preempted.
The following task mode constants are defined by RTEMS:
- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption
.. list-table::
:class: rtems-table
- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption
* - ``RTEMS_PREEMPT``
- is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
* - ``RTEMS_NO_PREEMPT``
- is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
* - ``RTEMS_NO_TIMESLICE``
- is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
* - ``RTEMS_TIMESLICE``
- is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
* - ``RTEMS_ASR``
- is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
* - ``RTEMS_NO_ASR``
- is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
* - ``RTEMS_INTERRUPT_LEVEL(0)``
- is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
* - ``RTEMS_INTERRUPT_LEVEL(n)``
- is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing
- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing
- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing
- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing
- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts
- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
.. _rtems_signal_send:
SIGNAL_SEND - Send signal set to a task
---------------------------------------
@ -285,40 +282,36 @@ SIGNAL_SEND - Send signal set to a task
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - signal sent successfully
``RTEMS_INVALID_ID`` - task id invalid
``RTEMS_INVALID_NUMBER`` - empty signal set
``RTEMS_NOT_DEFINED`` - ASR invalid
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- signal sent successfully
* - ``RTEMS_INVALID_ID``
- task id invalid
* - ``RTEMS_INVALID_NUMBER``
- empty signal set
* - ``RTEMS_NOT_DEFINED``
- ASR invalid
**DESCRIPTION:**
This directive sends a signal set to the task
specified in id. The signal_set parameter contains the signal
set to be sent to the task.
This directive sends a signal set to the task specified in id. The signal_set
parameter contains the signal set to be sent to the task.
If a caller sends a signal set to a task with an
invalid ASR, then an error code is returned to the caller. If a
caller sends a signal set to a task whose ASR is valid but
disabled, then the signal set will be caught and left pending
for the ASR to process when it is enabled. If a caller sends a
signal set to a task with an ASR that is both valid and enabled,
then the signal set is caught and the ASR will execute the next
time the task is dispatched to run.
If a caller sends a signal set to a task with an invalid ASR, then an error
code is returned to the caller. If a caller sends a signal set to a task whose
ASR is valid but disabled, then the signal set will be caught and left pending
for the ASR to process when it is enabled. If a caller sends a signal set to a
task with an ASR that is both valid and enabled, then the signal set is caught
and the ASR will execute the next time the task is dispatched to run.
**NOTES:**
Sending a signal set to a task has no effect on that
task's state. If a signal set is sent to a blocked task, then
the task will remain blocked and the signals will be processed
when the task becomes the running task.
Sending a signal set to a global task which does not
reside on the local node will generate a request telling the
remote node to send the signal set to the specified task.
.. COMMENT: COPYRIGHT (c) 1988-2010.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Sending a signal set to a task has no effect on that task's state. If a signal
set is sent to a blocked task, then the task will remain blocked and the
signals will be processed when the task becomes the running task.
Sending a signal set to a global task which does not reside on the local node
will generate a request telling the remote node to send the signal set to the
specified task.

605
c_user/user_extensions.rst
View File

@ -1,3 +1,7 @@
.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
User Extensions Manager
#######################
@ -6,23 +10,21 @@ User Extensions Manager
Introduction
============
The RTEMS User Extensions Manager allows the
application developer to augment the executive by allowing them
to supply extension routines which are invoked at critical
system events. The directives provided by the user extensions
The RTEMS User Extensions Manager allows the application developer to augment
the executive by allowing them to supply extension routines which are invoked
at critical system events. The directives provided by the user extensions
manager are:
- ``rtems_extension_create`` - Create an extension set
- rtems_extension_create_ - Create an extension set
- ``rtems_extension_ident`` - Get ID of an extension set
- rtems_extension_ident_ - Get ID of an extension set
- ``rtems_extension_delete`` - Delete an extension set
- rtems_extension_delete_ - Delete an extension set
Background
==========
User extension routines are invoked when the
following system events occur:
User extension routines are invoked when the following system events occur:
- Task creation
@ -42,20 +44,19 @@ following system events occur:
- Fatal error detection
These extensions are invoked as a function with
arguments that are appropriate to the system event.
These extensions are invoked as a function with arguments that are appropriate
to the system event.
Extension Sets
--------------
.. index:: 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
routines typically perform a specific functionality such as
performance monitoring or debugger support. RTEMS is informed of
the entry points which constitute an extension set via the
following structure:.. index:: rtems_extensions_table
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 routines typically perform a specific functionality
such as performance monitoring or debugger support. RTEMS is informed of the
entry points which constitute an extension set via the following
structure:.. index:: rtems_extensions_table
.. code:: c
@ -70,283 +71,269 @@ following structure:.. index:: rtems_extensions_table
rtems_fatal_extension fatal;
} rtems_extensions_table;
RTEMS allows the user to have multiple extension sets
active at the same time. First, a single static extension set
may be defined as the application's User Extension Table which
is included as part of the Configuration Table. This extension
set is active for the entire life of the system and may not be
deleted. This extension set is especially important because it
is the only way the application can provided a FATAL error
extension which is invoked if RTEMS fails during the
initialize_executive directive. The static extension set is
optional and may be configured as NULL if no static extension
set is required.
RTEMS allows the user to have multiple extension sets active at the same time.
First, a single static extension set may be defined as the application's User
Extension Table which is included as part of the Configuration Table. This
extension set is active for the entire life of the system and may not be
deleted. This extension set is especially important because it is the only way
the application can provided a FATAL error extension which is invoked if RTEMS
fails during the initialize_executive directive. The static extension set is
optional and may be configured as NULL if no static extension set is required.
Second, the user can install dynamic extensions using
the ``rtems_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
initialize_executive directive successfully completes execution.
Dynamic extensions are useful for encapsulating the
functionality of an extension set. For example, the application
could use extensions to manage a special coprocessor, do
performance monitoring, and to do stack bounds checking. Each
of these extension sets could be written and installed
Second, the user can install dynamic extensions using the
``rtems_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 initialize_executive directive successfully completes
execution. Dynamic extensions are useful for encapsulating the functionality
of an extension set. For example, the application could use extensions to
manage a special coprocessor, do performance monitoring, and to do stack bounds
checking. Each of these extension sets could be written and installed
independently of the others.
All user extensions are optional and RTEMS places no
naming restrictions on the user. The user extension entry points
are copied into an internal RTEMS structure. This means the user
does not need to keep the table after creating it, and changing the
handler entry points dynamically in a table once created has no
effect. Creating a table local to a function can save space in
space limited applications.
All user extensions are optional and RTEMS places no naming restrictions on the
user. The user extension entry points are copied into an internal RTEMS
structure. This means the user does not need to keep the table after creating
it, and changing the handler entry points dynamically in a table once created
has no effect. Creating a table local to a function can save space in space
limited applications.
Extension switches do not effect the context switch overhead if
no switch handler is installed.
Extension switches do not effect the context switch overhead if no switch
handler is installed.
TCB Extension Area
------------------
.. index:: 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
be used to store additional data required by the user's
extension functions.
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 be used to store additional data required by the
user's extension functions.
The TCB extension is an array of pointers in the TCB. The
index into the table can be obtained from the extension id
returned when the extension is created:.. index:: rtems extensions table index
The TCB extension is an array of pointers in the TCB. The index into the table
can be obtained from the extension id returned when the extension is
created:
.. index:: rtems extensions table index
.. code:: c
index = rtems_object_id_get_index(extension_id);
The number of pointers in the area is the same as the number of
user extension sets configured. This allows an application to
augment the TCB with user-defined information. For example, an
application could implement task profiling by storing timing
statistics in the TCB's extended memory area. When a task
context switch is being executed, the TASK_SWITCH extension
could read a real-time clock to calculate how long the task
being swapped out has run as well as timestamp the starting time
for the task being swapped in.
The number of pointers in the area is the same as the number of user extension
sets configured. This allows an application to augment the TCB with
user-defined information. For example, an application could implement task
profiling by storing timing statistics in the TCB's extended memory area. When
a task context switch is being executed, the ``TASK_SWITCH`` extension could
read a real-time clock to calculate how long the task being swapped out has run
as well as timestamp the starting time for the task being swapped in.
If used, the extended memory area for the TCB should
be allocated and the TCB extension pointer should be set at the
time the task is created or started by either the TASK_CREATE or
TASK_START extension. The application is responsible for
managing this extended memory area for the TCBs. The memory may
be reinitialized by the TASK_RESTART extension and should be
deallocated by the TASK_DELETE extension when the task is
deleted. Since the TCB extension buffers would most likely be
of a fixed size, the RTEMS partition manager could be used to
manage the application's extended memory area. The application
could create a partition of fixed size TCB extension buffers and
use the partition manager's allocation and deallocation
directives to obtain and release the extension buffers.
If used, the extended memory area for the TCB should be allocated and the TCB
extension pointer should be set at the time the task is created or started by
either the ``TASK_CREATE`` or ``TASK_START`` extension. The application is
responsible for managing this extended memory area for the TCBs. The memory
may be reinitialized by the ``TASK_RESTART`` extension and should be
deallocated by the ``TASK_DELETE`` extension when the task is deleted. Since
the TCB extension buffers would most likely be of a fixed size, the RTEMS
partition manager could be used to manage the application's extended memory
area. The application could create a partition of fixed size TCB extension
buffers and use the partition manager's allocation and deallocation directives
to obtain and release the extension buffers.
Extensions
----------
The sections that follow will contain a description
of each extension. Each section will contain a prototype of a
function with the appropriate calling sequence for the
corresponding extension. The names given for the C
function and
its arguments are all defined by the user. The names used in
the examples were arbitrarily chosen and impose no naming
conventions on the user.
The sections that follow will contain a description of each extension. Each
section will contain a prototype of a function with the appropriate calling
sequence for the corresponding extension. The names given for the C function
and its arguments are all defined by the user. The names used in the examples
were arbitrarily chosen and impose no naming conventions on the user.
TASK_CREATE Extension
~~~~~~~~~~~~~~~~~~~~~
The TASK_CREATE extension directly corresponds to the``rtems_task_create`` directive. If this extension
is defined in any
static or dynamic extension set and a task is being created,
then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:.. index:: rtems_task_create_extension
The TASK_CREATE extension directly corresponds to the ``rtems_task_create``
directive. If this extension is defined in any static or dynamic extension set
and a task is being created, then the extension routine will automatically be
invoked by RTEMS. The extension should have a prototype similar to the
following:
.. index:: rtems_task_create_extension
.. index:: rtems_extension
.. code:: c
bool user_task_create(
rtems_tcb \*current_task,
rtems_tcb \*new_task
rtems_tcb *current_task,
rtems_tcb *new_task
);
where ``current_task`` can be used to access the TCB for
the currently executing task, and new_task can be used to access
the TCB for the new task being created. This extension is
invoked from the ``rtems_task_create``
directive after ``new_task`` has been
completely initialized, but before it is placed on a ready TCB
chain.
where ``current_task`` can be used to access the TCB for the currently
executing task, and new_task can be used to access the TCB for the new task
being created. This extension is invoked from the ``rtems_task_create``
directive after ``new_task`` has been completely initialized, but before it is
placed on a ready TCB chain.
The user extension is expected to return the boolean
value ``true`` if it successfully executed and``false`` otherwise. A task create user extension
will frequently attempt to allocate resources. If this
allocation fails, then the extension should return``false`` and the entire task create operation
will fail.
The user extension is expected to return the boolean value ``true`` if it
successfully executed and ``false`` otherwise. A task create user extension
will frequently attempt to allocate resources. If this allocation fails, then
the extension should return ``false`` and the entire task create operation will
fail.
TASK_START Extension
~~~~~~~~~~~~~~~~~~~~
The TASK_START extension directly corresponds to the
task_start directive. If this extension is defined in any
static or dynamic extension set and a task is being started,
then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:.. index:: rtems_task_start_extension
The ``TASK_START`` extension directly corresponds to the task_start directive.
If this extension is defined in any static or dynamic extension set and a task
is being started, then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the following:
.. index:: rtems_task_start_extension
.. code:: c
void user_task_start(
rtems_tcb \*current_task,
rtems_tcb \*started_task
rtems_tcb *current_task,
rtems_tcb *started_task
);
where current_task can be used to access the TCB for
the currently executing task, and started_task can be used to
access the TCB for the dormant task being started. This
extension is invoked from the task_start directive after
started_task has been made ready to start execution, but before
it is placed on a ready TCB chain.
where current_task can be used to access the TCB for the currently executing
task, and started_task can be used to access the TCB for the dormant task being
started. This extension is invoked from the task_start directive after
started_task has been made ready to start execution, but before it is placed on
a ready TCB chain.
TASK_RESTART Extension
~~~~~~~~~~~~~~~~~~~~~~
The TASK_RESTART extension directly corresponds to
the task_restart directive. If this extension is defined in any
static or dynamic extension set and a task is being restarted,
then the extension should have a prototype similar to the
following:.. index:: rtems_task_restart_extension
The ``TASK_RESTART`` extension directly corresponds to the task_restart
directive. If this extension is defined in any static or dynamic extension set
and a task is being restarted, then the extension should have a prototype
similar to the following:
.. index:: rtems_task_restart_extension
.. code:: c
void user_task_restart(
rtems_tcb \*current_task,
rtems_tcb \*restarted_task
rtems_tcb *current_task,
rtems_tcb *restarted_task
);
where current_task can be used to access the TCB for
the currently executing task, and restarted_task can be used to
access the TCB for the task being restarted. This extension is
invoked from the task_restart directive after restarted_task has
been made ready to start execution, but before it is placed on a
ready TCB chain.
where current_task can be used to access the TCB for the currently executing
task, and restarted_task can be used to access the TCB for the task being
restarted. This extension is invoked from the task_restart directive after
restarted_task has been made ready to start execution, but before it is placed
on a ready TCB chain.
TASK_DELETE Extension
~~~~~~~~~~~~~~~~~~~~~
The TASK_DELETE extension is associated with the
task_delete directive. If this extension is defined in any
static or dynamic extension set and a task is being deleted,
then the extension routine will automatically be invoked by
The ``TASK_DELETE`` extension is associated with the task_delete directive. If
this extension is defined in any static or dynamic extension set and a task is
being deleted, then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:.. index:: rtems_task_delete_extension
following:
.. index:: rtems_task_delete_extension
.. code:: c
void user_task_delete(
rtems_tcb \*current_task,
rtems_tcb \*deleted_task
rtems_tcb *current_task,
rtems_tcb *deleted_task
);
where current_task can be used to access the TCB for
the currently executing task, and deleted_task can be used to
access the TCB for the task being deleted. This extension is
invoked from the task_delete directive after the TCB has been
removed from a ready TCB chain, but before all its resources
including the TCB have been returned to their respective free
pools. This extension should not call any RTEMS directives if a
task is deleting itself (current_task is equal to deleted_task).
where current_task can be used to access the TCB for the currently executing
task, and deleted_task can be used to access the TCB for the task being
deleted. This extension is invoked from the task_delete directive after the TCB
has been removed from a ready TCB chain, but before all its resources including
the TCB have been returned to their respective free pools. This extension
should not call any RTEMS directives if a task is deleting itself (current_task
is equal to deleted_task).
TASK_SWITCH Extension
~~~~~~~~~~~~~~~~~~~~~
The TASK_SWITCH extension corresponds to a task
context switch. If this extension is defined in any static or
dynamic extension set and a task context switch is in progress,
then the extension routine will automatically be invoked by
RTEMS. The extension should have a prototype similar to the
following:.. index:: rtems_task_switch_extension
The ``TASK_SWITCH`` extension corresponds to a task context switch. If this
extension is defined in any static or dynamic extension set and a task context
switch is in progress, then the extension routine will automatically be invoked
by RTEMS. The extension should have a prototype similar to the following:
.. index:: rtems_task_switch_extension
.. code:: c
void user_task_switch(
rtems_tcb \*current_task,
rtems_tcb \*heir_task
rtems_tcb *current_task,
rtems_tcb *heir_task
);
where current_task can be used to access the TCB for
the task that is being swapped out, and heir_task can be used to
access the TCB for the task being swapped in. This extension is
invoked from RTEMS' dispatcher routine after the current_task
context has been saved, but before the heir_task context has
been restored. This extension should not call any RTEMS
directives.
where current_task can be used to access the TCB for the task that is being
swapped out, and heir_task can be used to access the TCB for the task being
swapped in. This extension is invoked from RTEMS' dispatcher routine after the
current_task context has been saved, but before the heir_task context has been
restored. This extension should not call any RTEMS directives.
TASK_BEGIN Extension
~~~~~~~~~~~~~~~~~~~~
The TASK_BEGIN extension is invoked when a task
begins execution. It is invoked immediately before the body of
the starting procedure and executes in the context in the task.
This user extension have a prototype similar to the following:.. index:: rtems_task_begin_extension
The ``TASK_BEGIN`` extension is invoked when a task begins execution. It is
invoked immediately before the body of the starting procedure and executes in
the context in the task. This user extension have a prototype similar to the
following:
.. index:: rtems_task_begin_extension
.. code:: c
void user_task_begin(
rtems_tcb \*current_task
rtems_tcb *current_task
);
where current_task can be used to access the TCB for
the currently executing task which has begun. The distinction
between the TASK_BEGIN and TASK_START extension is that the
TASK_BEGIN extension is executed in the context of the actual
task while the TASK_START extension is executed in the context
of the task performing the task_start directive. For most
extensions, this is not a critical distinction.
where current_task can be used to access the TCB for the currently executing
task which has begun. The distinction between the ``TASK_BEGIN`` and
TASK_START extension is that the ``TASK_BEGIN`` extension is executed in the
context of the actual task while the TASK_START extension is executed in the
context of the task performing the task_start directive. For most extensions,
this is not a critical distinction.
TASK_EXITTED Extension
~~~~~~~~~~~~~~~~~~~~~~
The TASK_EXITTED extension is invoked when a task
exits the body of the starting procedure by either an implicit
or explicit return statement. This user extension have a
prototype similar to the following:.. index:: rtems_task_exitted_extension
The ``TASK_EXITTED`` extension is invoked when a task exits the body of the
starting procedure by either an implicit or explicit return statement. This
user extension have a prototype similar to the following:
.. index:: rtems_task_exitted_extension
.. code:: c
void user_task_exitted(
rtems_tcb \*current_task
rtems_tcb *current_task
);
where current_task can be used to access the TCB for
the currently executing task which has just exitted.
where current_task can be used to access the TCB for the currently executing
task which has just exitted.
Although exiting of task is often considered to be a
fatal error, this extension allows recovery by either restarting
or deleting the exiting task. If the user does not wish to
recover, then a fatal error may be reported. If the user does
not provide a TASK_EXITTED extension or the provided handler
returns control to RTEMS, then the RTEMS default handler will be
used. This default handler invokes the directive
fatal_error_occurred with the ``RTEMS_TASK_EXITTED`` directive status.
Although exiting of task is often considered to be a fatal error, this
extension allows recovery by either restarting or deleting the exiting task.
If the user does not wish to recover, then a fatal error may be reported. If
the user does not provide a ``TASK_EXITTED`` extension or the provided handler
returns control to RTEMS, then the RTEMS default handler will be used. This
default handler invokes the directive fatal_error_occurred with the
``RTEMS_TASK_EXITTED`` directive status.
FATAL Error Extension
~~~~~~~~~~~~~~~~~~~~~
The FATAL error extension is associated with the
fatal_error_occurred directive. If this extension is defined in
any static or dynamic extension set and the fatal_error_occurred
directive has been invoked, then this extension will be called.
This extension should have a prototype similar to the following:.. index:: rtems_fatal_extension
The ``FATAL`` error extension is associated with the fatal_error_occurred
directive. If this extension is defined in any static or dynamic extension set
and the fatal_error_occurred directive has been invoked, then this extension
will be called. This extension should have a prototype similar to the
following:
.. index:: rtems_fatal_extension
.. code:: c
@ -356,62 +343,55 @@ This extension should have a prototype similar to the following:.. index:: rtems
uint32_t the_error
);
where the_error is the error code passed to the
fatal_error_occurred directive. This extension is invoked from
the fatal_error_occurred directive.
where the_error is the error code passed to the fatal_error_occurred
directive. This extension is invoked from the fatal_error_occurred directive.
If defined, the user's FATAL error extension is
invoked before RTEMS' default fatal error routine is invoked and
the processor is stopped. For example, this extension could be
used to pass control to a debugger when a fatal error occurs.
This extension should not call any RTEMS directives.
If defined, the user's ``FATAL`` error extension is invoked before RTEMS'
default fatal error routine is invoked and the processor is stopped. For
example, this extension could be used to pass control to a debugger when a
fatal error occurs. This extension should not call any RTEMS directives.
Order of Invocation
-------------------
When one of the critical system events occur, the
user extensions are invoked in either "forward" or "reverse"
order. Forward order indicates that the static extension set is
invoked followed by the dynamic extension sets in the order in
which they were created. Reverse order means that the dynamic
extension sets are invoked in the opposite of the order in which
they were created followed by the static extension set. By
invoking the extension sets in this order, extensions can be
built upon one another. At the following system events, the
extensions are invoked in forward order:
When one of the critical system events occur, the user extensions are invoked
in either "forward" or "reverse" order. Forward order indicates that the
static extension set is invoked followed by the dynamic extension sets in the
order in which they were created. Reverse order means that the dynamic
extension sets are invoked in the opposite of the order in which they were
created followed by the static extension set. By invoking the extension sets
in this order, extensions can be built upon one another. At the following
system events, the extensions are invoked in forward order:
- Task creation
#. Task creation
- Task initiation
#. Task initiation
- Task reinitiation
#. Task reinitiation
- Task deletion
#. Task deletion
- Task context switch
#. Task context switch
- Post task context switch
#. Post task context switch
- Task begins to execute
#. Task begins to execute
At the following system events, the extensions are
invoked in reverse order:
At the following system events, the extensions are invoked in reverse order:
- Task deletion
#. Task deletion
- Fatal error detection
#. Fatal error detection
At these system events, the extensions are invoked in
reverse order to insure that if an extension set is built upon
another, the more complicated extension is invoked before the
extension set it is built upon. For example, by invoking the
static extension set last it is known that the "system" fatal
error extension will be the last fatal error extension executed.
Another example is use of the task delete extension by the
Standard C Library. Extension sets which are installed after
the Standard C Library will operate correctly even if they
utilize the C Library because the C Library's TASK_DELETE
extension is invoked after that of the other extensions.
At these system events, the extensions are invoked in reverse order to insure
that if an extension set is built upon another, the more complicated extension
is invoked before the extension set it is built upon. For example, by invoking
the static extension set last it is known that the "system" fatal error
extension will be the last fatal error extension executed. Another example is
use of the task delete extension by the Standard C Library. Extension sets
which are installed after the Standard C Library will operate correctly even if
they utilize the C Library because the C Library's ``TASK_DELETE`` extension is
invoked after that of the other extensions.
Operations
==========
@ -419,44 +399,40 @@ Operations
Creating an Extension Set
-------------------------
The ``rtems_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
are immediately installed and are invoked upon the next system
The ``rtems_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 are immediately installed and are invoked upon the next system
even supporting an extension.
Obtaining Extension Set IDs
---------------------------
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 ``rtems_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 ``rtems_extension_ident``
directive. The extension set ID is used by other directives
to manipulate this extension set.
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 ``rtems_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 ``rtems_extension_ident`` directive. The extension
set ID is used by other directives to manipulate this extension set.
Deleting an Extension Set
-------------------------
The ``rtems_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
extension set. Any subsequent references to the extension's
name and ID are invalid.
The ``rtems_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 extension set. Any subsequent references to the extension's name
and ID are invalid.
Directives
==========
This section details the user extension manager's
directives. A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.
This section details the user extension manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. _rtems_extension_create:
EXTENSION_CREATE - Create a extension set
-----------------------------------------
@ -470,30 +446,36 @@ EXTENSION_CREATE - Create a extension set
rtems_status_code rtems_extension_create(
rtems_name name,
rtems_extensions_table \*table,
rtems_id \*id
rtems_extensions_table *table,
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - extension set created successfully
``RTEMS_INVALID_NAME`` - invalid extension set name
``RTEMS_TOO_MANY`` - too many extension sets created
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- extension set created successfully
* - ``RTEMS_INVALID_NAME``
- invalid extension set name
* - ``RTEMS_TOO_MANY``
- too many extension sets created
**DESCRIPTION:**
This directive creates a extension set. The assigned
extension set id is returned in id. This id is used to access
the extension set with other user extension manager directives.
For control and maintenance of the extension set, RTEMS
allocates an ESCB from the local ESCB free pool and initializes
it.
This directive creates a extension set. The assigned extension set id is
returned in id. This id is used to access the extension set with other user
extension manager directives. For control and maintenance of the extension
set, RTEMS allocates an ESCB from the local ESCB free pool and initializes it.
**NOTES:**
This directive will not cause the calling task to be
preempted.
.. _rtems_extension_ident:
EXTENSION_IDENT - Get ID of a extension set
-------------------------------------------
.. index:: get ID of an extension set
@ -507,28 +489,33 @@ EXTENSION_IDENT - Get ID of a extension set
rtems_status_code rtems_extension_ident(
rtems_name name,
rtems_id \*id
rtems_id *id
);
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - extension set identified successfully
``RTEMS_INVALID_NAME`` - extension set name not found
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- extension set identified successfully
* - ``RTEMS_INVALID_NAME``
- extension set name not found
**DESCRIPTION:**
This directive obtains the extension set id
associated with the extension set name to be acquired. If the
extension set name is not unique, then the extension set id will
match one of the extension sets with that name. However, this
extension set id is not guaranteed to correspond to the desired
extension set. The extension set id is used to access this
extension set in other extension set related directives.
This directive obtains the extension set id associated with the extension set
name to be acquired. If the extension set name is not unique, then the
extension set id will match one of the extension sets with that name. However,
this extension set id is not guaranteed to correspond to the desired extension
set. The extension set id is used to access this extension set in other
extension set related directives.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
.. _rtems_extension_delete:
EXTENSION_DELETE - Delete a extension set
-----------------------------------------
@ -546,47 +533,27 @@ EXTENSION_DELETE - Delete a extension set
**DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - extension set deleted successfully
``RTEMS_INVALID_ID`` - invalid extension set id
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- extension set deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid extension set id
**DESCRIPTION:**
This directive deletes the extension set specified by
id. If the extension set is running, it is automatically
canceled. The ESCB for the deleted extension set is reclaimed
by RTEMS.
This directive deletes the extension set specified by ``id``. If the extension
set is running, it is automatically canceled. The ESCB for the deleted
extension set is reclaimed by RTEMS.
**NOTES:**
This directive will not cause the running task to be
preempted.
This directive will not cause the running task to be preempted.
A extension set can be deleted by a task other than
the task which created the extension set.
A extension set can be deleted by a task other than the task which created the
extension set.
**NOTES:**
This directive will not cause the running task to be
preempted.
.. COMMENT: COPYRIGHT (c) 1988-2015.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. COMMENT: TODO:
.. COMMENT: + Ensure all macros are documented.
.. COMMENT: + Verify which structures may actually be defined by a user
.. COMMENT: + Add Go configuration.
.. COMMENT: Questions:
.. COMMENT: + Should there be examples of defining your own
.. COMMENT: Device Driver Table, Init task table, etc.?
This directive will not cause the running task to be preempted.