rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-05 01:03:55 +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

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

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

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

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

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

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

839
c_user/message_manager.rst
View File

File diff suppressed because it is too large Load Diff

429
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 Partition Manager
################# #################
@ -6,19 +10,18 @@ Partition Manager
Introduction Introduction
============ ============
The partition manager provides facilities to The partition manager provides facilities to dynamically allocate memory in
dynamically allocate memory in fixed-size units. The directives fixed-size units. The directives provided by the partition manager are:
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 Background
========== ==========
@ -27,41 +30,43 @@ Partition Manager Definitions
----------------------------- -----------------------------
.. index:: partition, definition .. index:: partition, definition
A partition is a physically contiguous memory area A partition is a physically contiguous memory area divided into fixed-size
divided into fixed-size buffers that can be dynamically buffers that can be dynamically allocated and deallocated.
allocated and deallocated... index:: buffers, definition
Partitions are managed and maintained as a list of .. index:: buffers, definition
buffers. Buffers are obtained from the front of the partition's
free buffer chain and returned to the rear of the same chain. Partitions are managed and maintained as a list of buffers. Buffers are
When a buffer is on the free buffer chain, RTEMS uses two obtained from the front of the partition's free buffer chain and returned to
pointers of memory from each buffer as the free buffer chain. the rear of the same chain. When a buffer is on the free buffer chain, RTEMS
When a buffer is allocated, the entire buffer is available for application use. uses two pointers of memory from each buffer as the free buffer chain. When a
Therefore, modifying memory that is outside of an allocated buffer is allocated, the entire buffer is available for application use.
buffer could destroy the free buffer chain or the contents of an Therefore, modifying memory that is outside of an allocated buffer could
adjacent allocated buffer. destroy the free buffer chain or the contents of an adjacent allocated buffer.
Building a Partition Attribute Set Building a Partition Attribute Set
---------------------------------- ----------------------------------
.. index:: partition attribute set, building .. index:: partition attribute set, building
In general, an attribute set is built by a bitwise OR In general, an attribute set is built by a bitwise OR of the desired attribute
of the desired attribute components. The set of valid partition components. The set of valid partition attributes is provided in the following
attributes is provided in the following table: 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 Attribute values are specifically designed to be mutually exclusive, therefore
mutually exclusive, therefore bitwise OR and addition operations bitwise OR and addition operations are equivalent as long as each attribute
are equivalent as long as each attribute appears exactly once in appears exactly once in the component list. An attribute listed as a default
the component list. An attribute listed as a default is not is not required to appear in the attribute list, although it is a good
required to appear in the attribute list, although it is a good programming practice to specify default attributes. If all defaults are
programming practice to specify default attributes. If all desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
defaults are desired, the attribute``RTEMS_DEFAULT_ATTRIBUTES`` should be call. The attribute_set parameter should be ``RTEMS_GLOBAL`` to indicate that
specified on this call. The attribute_set parameter should be``RTEMS_GLOBAL`` to indicate that the partition the partition is to be known globally.
is to be known globally.
Operations Operations
========== ==========
@ -69,62 +74,60 @@ Operations
Creating a Partition Creating a Partition
-------------------- --------------------
The ``rtems_partition_create`` directive creates a partition The ``rtems_partition_create`` directive creates a partition with a
with a user-specified name. The partition's name, starting user-specified name. The partition's name, starting address, length and buffer
address, length and buffer size are all specified to the``rtems_partition_create`` directive. size are all specified to the ``rtems_partition_create`` directive. RTEMS
RTEMS allocates a Partition Control allocates a Partition Control Block (PTCB) from the PTCB free list. This data
Block (PTCB) from the PTCB free list. This data structure is structure is used by RTEMS to manage the newly created partition. The number
used by RTEMS to manage the newly created partition. The number of buffers in the partition is calculated based upon the specified partition
of buffers in the partition is calculated based upon the length and buffer size. If successful,the unique partition ID is returned to
specified partition length and buffer size. If successful,the the calling task.
unique partition ID is returned to the calling task.
Obtaining Partition IDs Obtaining Partition IDs
----------------------- -----------------------
When a partition is created, RTEMS generates a unique When a partition is created, RTEMS generates a unique partition ID and assigned
partition ID and assigned it to the created partition until it it to the created partition until it is deleted. The partition ID may be
is deleted. The partition ID may be obtained by either of two obtained by either of two methods. First, as the result of an invocation of
methods. First, as the result of an invocation of the``rtems_partition_create`` directive, the partition the ``rtems_partition_create`` directive, the partition ID is stored in a user
ID is stored in a user provided location. Second, the partition provided location. Second, the partition ID may be obtained later using the
ID may be obtained later using the ``rtems_partition_ident`` ``rtems_partition_ident`` directive. The partition ID is used by other
directive. The partition ID is used by other partition manager directives partition manager directives to access this partition.
to access this partition.
Acquiring a Buffer Acquiring a Buffer
------------------ ------------------
A buffer can be obtained by calling the``rtems_partition_get_buffer`` directive. A buffer can be obtained by calling the ``rtems_partition_get_buffer``
If a buffer is available, then directive. If a buffer is available, then it is returned immediately with a
it is returned immediately with a successful return code. successful return code. Otherwise, an unsuccessful return code is returned
Otherwise, an unsuccessful return code is returned immediately immediately to the caller. Tasks cannot block to wait for a buffer to become
to the caller. Tasks cannot block to wait for a buffer to available.
become available.
Releasing a Buffer Releasing a Buffer
------------------ ------------------
Buffers are returned to a partition's free buffer Buffers are returned to a partition's free buffer chain with the
chain with the ``rtems_partition_return_buffer`` directive. This ``rtems_partition_return_buffer`` directive. This directive returns an error
directive returns an error status code if the returned buffer status code if the returned buffer was not previously allocated from this
was not previously allocated from this partition. partition.
Deleting a Partition Deleting a Partition
-------------------- --------------------
The ``rtems_partition_delete`` directive allows a partition to The ``rtems_partition_delete`` directive allows a partition to be removed and
be removed and returned to RTEMS. When a partition is deleted, returned to RTEMS. When a partition is deleted, the PTCB for that partition is
the PTCB for that partition is returned to the PTCB free list. returned to the PTCB free list. A partition with buffers still allocated
A partition with buffers still allocated cannot be deleted. Any cannot be deleted. Any task attempting to do so will be returned an error
task attempting to do so will be returned an error status code. status code.
Directives Directives
========== ==========
This section details the partition manager's This section details the partition manager's directives. A subsection is
directives. A subsection is dedicated to each of this manager's dedicated to each of this manager's directives and describes the calling
directives and describes the calling sequence, related sequence, related constants, usage, and status codes.
constants, usage, and status codes.
.. _rtems_partition_create:
PARTITION_CREATE - Create a partition PARTITION_CREATE - Create a partition
------------------------------------- -------------------------------------
@ -137,75 +140,88 @@ PARTITION_CREATE - Create a partition
.. code:: c .. code:: c
rtems_status_code rtems_partition_create( rtems_status_code rtems_partition_create(
rtems_name name, rtems_name name,
void \*starting_address, void *starting_address,
uint32_t length, uint32_t length,
uint32_t buffer_size, uint32_t buffer_size,
rtems_attribute attribute_set, rtems_attribute attribute_set,
rtems_id \*id rtems_id *id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - partition created successfully .. list-table::
``RTEMS_INVALID_NAME`` - invalid partition name :class: rtems-table
``RTEMS_TOO_MANY`` - too many partitions created
``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary * - ``RTEMS_SUCCESSFUL``
``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL - partition created successfully
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL * - ``RTEMS_INVALID_NAME``
``RTEMS_INVALID_SIZE`` - length or buffer size is 0 - invalid partition name
``RTEMS_INVALID_SIZE`` - length is less than the buffer size * - ``RTEMS_TOO_MANY``
``RTEMS_INVALID_SIZE`` - buffer size not a multiple of 4 - too many partitions created
``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured * - ``RTEMS_INVALID_ADDRESS``
``RTEMS_TOO_MANY`` - too many global objects - 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:** **DESCRIPTION:**
This directive creates a partition of fixed size This directive creates a partition of fixed size buffers from a physically
buffers from a physically contiguous memory space which starts contiguous memory space which starts at starting_address and is length bytes in
at starting_address and is length bytes in size. Each allocated size. Each allocated buffer is to be of ``buffer_size`` in bytes. The
buffer is to be of ``buffer_size`` in bytes. The assigned assigned partition id is returned in ``id``. This partition id is used to
partition id is returned in ``id``. This partition id is used to access the partition with other partition related directives. For control and
access the partition with other partition related directives. maintenance of the partition, RTEMS allocates a PTCB from the local PTCB free
For control and maintenance of the partition, RTEMS allocates a pool and initializes it.
PTCB from the local PTCB free pool and initializes it.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be This directive will not cause the calling task to be preempted.
preempted.
The ``starting_address`` must be properly aligned for the The ``starting_address`` must be properly aligned for the target architecture.
target architecture.
The ``buffer_size`` parameter must be a multiple of The ``buffer_size`` parameter must be a multiple of the CPU alignment factor.
the CPU alignment factor. Additionally, ``buffer_size`` Additionally, ``buffer_size`` must be large enough to hold two pointers on the
must be large enough to hold two pointers on the target target architecture. This is required for RTEMS to manage the buffers when
architecture. This is required for RTEMS to manage the they are free.
buffers when they are free.
Memory from the partition is not used by RTEMS to Memory from the partition is not used by RTEMS to store the Partition Control
store the Partition Control Block. Block.
The following partition attribute constants are The following partition attribute constants are defined by RTEMS:
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 The PTCB for a global partition is allocated on the local node. The memory
local node. The memory space used for the partition must reside space used for the partition must reside in shared memory. Partitions should
in shared memory. Partitions should not be made global unless not be made global unless remote tasks must interact with the partition. This
remote tasks must interact with the partition. This is to avoid is to avoid the overhead incurred by the creation of a global partition. When
the overhead incurred by the creation of a global partition. a global partition is created, the partition's name and id must be transmitted
When a global partition is created, the partition's name and id to every node in the system for insertion in the local copy of the global
must be transmitted to every node in the system for insertion in object table.
the local copy of the global object table.
The total number of global objects, including The total number of global objects, including partitions, is limited by the
partitions, is limited by the maximum_global_objects field in maximum_global_objects field in the Configuration Table.
the Configuration Table.
.. _rtems_partition_ident:
PARTITION_IDENT - Get ID of a partition PARTITION_IDENT - Get ID of a partition
--------------------------------------- ---------------------------------------
@ -219,43 +235,48 @@ PARTITION_IDENT - Get ID of a partition
.. code:: c .. code:: c
rtems_status_code rtems_partition_ident( rtems_status_code rtems_partition_ident(
rtems_name name, rtems_name name,
uint32_t node, uint32_t node,
rtems_id \*id rtems_id *id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - partition identified successfully .. list-table::
``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL :class: rtems-table
``RTEMS_INVALID_NAME`` - partition name not found
``RTEMS_INVALID_NODE`` - invalid node id * - ``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:** **DESCRIPTION:**
This directive obtains the partition id associated This directive obtains the partition id associated with the partition name. If
with the partition name. If the partition name is not unique, the partition name is not unique, then the partition id will match one of the
then the partition id will match one of the partitions with that partitions with that name. However, this partition id is not guaranteed to
name. However, this partition id is not guaranteed to correspond to the desired partition. The partition id is used with other
correspond to the desired partition. The partition id is used partition related directives to access the partition.
with other partition related directives to access the partition.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the local
with the local node being searched first. All other nodes are node being searched first. All other nodes are searched with the lowest
searched with the lowest numbered node searched first. numbered node searched first.
If node is a valid node number which does not If node is a valid node number which does not represent the local node, then
represent the local node, then only the partitions exported by only the partitions exported by the designated node are searched.
the designated node are searched.
This directive does not generate activity on remote This directive does not generate activity on remote nodes. It accesses only
nodes. It accesses only the local copy of the global object the local copy of the global object table.
table.
.. _rtems_partition_delete:
PARTITION_DELETE - Delete a partition PARTITION_DELETE - Delete a partition
------------------------------------- -------------------------------------
@ -268,38 +289,44 @@ PARTITION_DELETE - Delete a partition
.. code:: c .. code:: c
rtems_status_code rtems_partition_delete( rtems_status_code rtems_partition_delete(
rtems_id id rtems_id id
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - partition deleted successfully .. list-table::
``RTEMS_INVALID_ID`` - invalid partition id :class: rtems-table
``RTEMS_RESOURCE_IN_USE`` - buffers still in use
``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote partition * - ``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:** **DESCRIPTION:**
This directive deletes the partition specified by id. This directive deletes the partition specified by id. The partition cannot be
The partition cannot be deleted if any of its buffers are still deleted if any of its buffers are still allocated. The PTCB for the deleted
allocated. The PTCB for the deleted partition is reclaimed by partition is reclaimed by RTEMS.
RTEMS.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be This directive will not cause the calling task to be preempted.
preempted.
The calling task does not have to be the task that The calling task does not have to be the task that created the partition. Any
created the partition. Any local task that knows the partition local task that knows the partition id can delete the partition.
id can delete the partition.
When a global partition is deleted, the partition id When a global partition is deleted, the partition id must be transmitted to
must be transmitted to every node in the system for deletion every node in the system for deletion from the local copy of the global object
from the local copy of the global object table. table.
The partition must reside on the local node, even if The partition must reside on the local node, even if the partition was created
the partition was created with the ``RTEMS_GLOBAL`` option. with the ``RTEMS_GLOBAL`` option.
.. _rtems_partition_get_buffer:
PARTITION_GET_BUFFER - Get buffer from a partition PARTITION_GET_BUFFER - Get buffer from a partition
-------------------------------------------------- --------------------------------------------------
@ -313,35 +340,42 @@ PARTITION_GET_BUFFER - Get buffer from a partition
.. code:: c .. code:: c
rtems_status_code rtems_partition_get_buffer( rtems_status_code rtems_partition_get_buffer(
rtems_id id, rtems_id id,
void \**buffer void **buffer
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - buffer obtained successfully .. list-table::
``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL :class: rtems-table
``RTEMS_INVALID_ID`` - invalid partition id
``RTEMS_UNSATISFIED`` - all buffers are allocated * - ``RTEMS_SUCCESSFUL``
- buffer obtained successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``buffer`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_UNSATISFIED``
- all buffers are allocated
**DESCRIPTION:** **DESCRIPTION:**
This directive allows a buffer to be obtained from This directive allows a buffer to be obtained from the partition specified
the partition specified in id. The address of the allocated in id. The address of the allocated buffer is returned in buffer.
buffer is returned in buffer.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
All buffers begin on a four byte boundary. All buffers begin on a four byte boundary.
A task cannot wait on a buffer to become available. A task cannot wait on a buffer to become available.
Getting a buffer from a global partition which does Getting a buffer from a global partition which does not reside on the local
not reside on the local node will generate a request telling the node will generate a request telling the remote node to allocate a buffer from
remote node to allocate a buffer from the specified partition. the specified partition.
.. _rtems_partition_return_buffer:
PARTITION_RETURN_BUFFER - Return buffer to a partition PARTITION_RETURN_BUFFER - Return buffer to a partition
------------------------------------------------------ ------------------------------------------------------
@ -354,37 +388,36 @@ PARTITION_RETURN_BUFFER - Return buffer to a partition
.. code:: c .. code:: c
rtems_status_code rtems_partition_return_buffer( rtems_status_code rtems_partition_return_buffer(
rtems_id id, rtems_id id,
void \*buffer void *buffer
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - buffer returned successfully .. list-table::
``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL :class: rtems-table
``RTEMS_INVALID_ID`` - invalid partition id
``RTEMS_INVALID_ADDRESS`` - buffer address not in partition * - ``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:** **DESCRIPTION:**
This directive returns the buffer specified by buffer This directive returns the buffer specified by buffer to the partition
to the partition specified by id. specified by id.
**NOTES:** **NOTES:**
This directive will not cause the running task to be This directive will not cause the running task to be preempted.
preempted.
Returning a buffer to a global partition which does Returning a buffer to a global partition which does not reside on the local
not reside on the local node will generate a request telling the node will generate a request telling the remote node to return the buffer to
remote node to return the buffer to the specified partition. the specified partition.
Returning a buffer multiple times is an error. It will corrupt the internal Returning a buffer multiple times is an error. It will corrupt the internal
state of the partition. state of the partition.
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

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

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 ``RTEMS_NO_WAIT`` components of the options parameter indicate whether the
calling task wants to wait for the semaphore to become available or return calling task wants to wait for the semaphore to become available or return
immediately if the semaphore is not currently available. With either immediately if the semaphore is not currently available. With either
``RTEMS_WAIT`` or``RTEMS_NO_WAIT``, if the current semaphore count is positive, ``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current semaphore count is
then it is decremented by one and the semaphore is successfully acquired by positive, then it is decremented by one and the semaphore is successfully
returning immediately with a successful return code. acquired by returning immediately with a successful return code.
If the calling task chooses to return immediately and the current semaphore 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 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. elevated to that of the ceiling.
The timeout parameter specifies the maximum interval the calling task is The timeout parameter specifies the maximum interval the calling task is
willing to be blocked waiting for the semaphore. If it is set willing to be blocked waiting for the semaphore. If it is set to
to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the ``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 semaphore is available or the ``RTEMS_NO_WAIT`` option component is set, then
timeout is ignored. timeout is ignored.

381
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 Signal Manager
############## ##############
@ -6,13 +10,12 @@ Signal Manager
Introduction Introduction
============ ============
The signal manager provides the capabilities required The signal manager provides the capabilities required for asynchronous
for asynchronous communication. The directives provided by the communication. The directives provided by the signal manager are:
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 Background
========== ==========
@ -22,107 +25,102 @@ Signal Manager Definitions
.. index:: asynchronous signal routine .. index:: asynchronous signal routine
.. index:: ASR .. index:: ASR
The signal manager allows a task to optionally define The signal manager allows a task to optionally define an asynchronous signal
an asynchronous signal routine (ASR). An ASR is to a task what routine (ASR). An ASR is to a task what an ISR is to an application's set of
an ISR is to an application's set of tasks. When the processor tasks. When the processor is interrupted, the execution of an application is
is interrupted, the execution of an application is also also interrupted and an ISR is given control. Similarly, when a signal is sent
interrupted and an ISR is given control. Similarly, when a to a task, that task's execution path will be "interrupted" by the ASR.
signal is sent to a task, that task's execution path will be Sending a signal to a task has no effect on the receiving task's current
"interrupted" by the ASR. Sending a signal to a task has no execution state.
effect on the receiving task's current execution state... index:: rtems_signal_set
A signal flag is used by a task (or ISR) to inform .. index:: rtems_signal_set
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 A signal flag is used by a task (or ISR) to inform another task of the
task. A pending signal is a signal that has been sent to a task occurrence of a significant situation. Thirty-two signal flags are associated
with a valid ASR, but has not been processed by that task's ASR. 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 A Comparison of ASRs and ISRs
----------------------------- -----------------------------
.. index:: ASR vs. ISR .. index:: ASR vs. ISR
.. index:: ISR vs. ASR .. index:: ISR vs. ASR
The format of an ASR is similar to that of an ISR The format of an ASR is similar to that of an ISR with the following
with the following exceptions: exceptions:
- ISRs are scheduled by the processor hardware. ASRs are - ISRs are scheduled by the processor hardware. ASRs are scheduled by RTEMS.
scheduled by RTEMS.
- ISRs do not execute in the context of a task and may - ISRs do not execute in the context of a task and may invoke only a subset of
invoke only a subset of directives. ASRs execute in the context directives. ASRs execute in the context of a task and may execute any
of a task and may execute any directive. directive.
- When an ISR is invoked, it is passed the vector number - When an ISR is invoked, it is passed the vector number as its argument. When
as its argument. When an ASR is invoked, it is passed the an ASR is invoked, it is passed the signal set as its argument.
signal set as its argument.
- An ASR has a task mode which can be different from that - An ASR has a task mode which can be different from that of the task. An ISR
of the task. An ISR does not execute as a task and, as a does not execute as a task and, as a result, does not have a task mode.
result, does not have a task mode.
Building a Signal Set Building a Signal Set
--------------------- ---------------------
.. index:: signal set, building .. index:: signal set, building
A signal set is built by a bitwise OR of the desired A signal set is built by a bitwise OR of the desired signals. The set of valid
signals. The set of valid signals is ``RTEMS_SIGNAL_0`` through``RTEMS_SIGNAL_31``. If a signal is not explicitly specified in the signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not
signal set, then it is not present. Signal values are explicitly specified in the signal set, then it is not present. Signal values
specifically designed to be mutually exclusive, therefore are specifically designed to be mutually exclusive, therefore bitwise OR and
bitwise OR and addition operations are equivalent as long as addition operations are equivalent as long as each signal appears exactly once
each signal appears exactly once in the component list. in the component list.
This example demonstrates the signal parameter used This example demonstrates the signal parameter used when sending the signal set
when sending the signal set consisting of``RTEMS_SIGNAL_6``,``RTEMS_SIGNAL_15``, and``RTEMS_SIGNAL_31``. The signal parameter provided consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``.
to the ``rtems_signal_send`` directive should be``RTEMS_SIGNAL_6 | The signal parameter provided to the ``rtems_signal_send`` directive should be
RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``. ``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
Building an ASR Mode Building an ASR Mode
-------------------- --------------------
.. index:: ASR mode, building .. index:: ASR mode, building
In general, an ASR's mode is built by a bitwise OR of In general, an ASR's mode is built by a bitwise OR of the desired mode
the desired mode components. The set of valid mode components components. The set of valid mode components is the same as those allowed with
is the same as those allowed with the task_create and task_mode the task_create and task_mode directives. A complete list of mode options is
directives. A complete list of mode options is provided in the provided in the following table:
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 This example demonstrates the mode parameter used with the
``rtems_signal_catch`` to establish an ASR which executes at interrupt level
- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing three and is non-preemptible. The mode should be set to
``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired
- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing processor mode and interrupt level.
- ``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.
Operations Operations
========== ==========
@ -130,89 +128,80 @@ Operations
Establishing an ASR Establishing an ASR
------------------- -------------------
The ``rtems_signal_catch`` directive establishes an ASR for the The ``rtems_signal_catch`` directive establishes an ASR for the calling task.
calling task. The address of the ASR and its execution mode are The address of the ASR and its execution mode are specified to this directive.
specified to this directive. The ASR's mode is distinct from The ASR's mode is distinct from the task's mode. For example, the task may
the task's mode. For example, the task may allow preemption, allow preemption, while that task's ASR may have preemption disabled. Until a
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
task calls ``rtems_signal_catch`` the first time, signal sets can be sent to the task.
its ASR is invalid, and no signal sets can be sent to the task.
A task may invalidate its ASR and discard all pending A task may invalidate its ASR and discard all pending signals by calling
signals by calling ``rtems_signal_catch`` ``rtems_signal_catch`` with a value of NULL for the ASR's address. When a
with a value of NULL for the ASR's address. When a task's task's ASR is invalid, new signal sets sent to this task are discarded.
ASR is invalid, new signal sets sent to this task are discarded.
A task may disable ASR processing (``RTEMS_NO_ASR``) via the A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode
task_mode directive. When a task's ASR is disabled, the signals directive. When a task's ASR is disabled, the signals sent to it are left
sent to it are left pending to be processed later when the ASR pending to be processed later when the ASR is enabled.
is enabled.
Any directive that can be called from a task can also Any directive that can be called from a task can also be called from an ASR. A
be called from an ASR. A task is only allowed one active ASR. task is only allowed one active ASR. Thus, each call to ``rtems_signal_catch``
Thus, each call to ``rtems_signal_catch``
replaces the previous one. replaces the previous one.
Normally, signal processing is disabled for the ASR's Normally, signal processing is disabled for the ASR's execution mode, but if
execution mode, but if signal processing is enabled for the ASR, signal processing is enabled for the ASR, the ASR must be reentrant.
the ASR must be reentrant.
Sending a Signal Set Sending a Signal Set
-------------------- --------------------
The ``rtems_signal_send`` directive allows both The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals
tasks and ISRs to send signals to a target task. The target task and to a target task. The target task and a set of signals are specified to the
a set of signals are specified to the``rtems_signal_send`` directive. The sending ``rtems_signal_send`` directive. The sending of a signal to a task has no
of a signal to a task has no effect on the execution state of effect on the execution state of that task. If the task is not the currently
that task. If the task is not the currently running task, then running task, then the signals are left pending and processed by the task's ASR
the signals are left pending and processed by the task's ASR the the next time the task is dispatched to run. The ASR is executed immediately
next time the task is dispatched to run. The ASR is executed before the task is dispatched. If the currently running task sends a signal to
immediately before the task is dispatched. If the currently itself or is sent a signal from an ISR, its ASR is immediately dispatched to
running task sends a signal to itself or is sent a signal from run provided signal processing is enabled.
an ISR, its ASR is immediately dispatched to run provided signal
processing is enabled.
If an ASR with signals enabled is preempted by If an ASR with signals enabled is preempted by another task or an ISR and a new
another task or an ISR and a new signal set is sent, then a new signal set is sent, then a new copy of the ASR will be invoked, nesting the
copy of the ASR will be invoked, nesting the preempted ASR. preempted ASR. Upon completion of processing the new signal set, control will
Upon completion of processing the new signal set, control will return to the preempted ASR. In this situation, the ASR must be reentrant.
return to the preempted ASR. In this situation, the ASR must be
reentrant.
Like events, identical signals sent to a task are not Like events, identical signals sent to a task are not queued. In other words,
queued. In other words, sending the same signal multiple times sending the same signal multiple times to a task (without any intermediate
to a task (without any intermediate signal processing occurring signal processing occurring for the task), has the same result as sending that
for the task), has the same result as sending that signal to signal to that task once.
that task once.
Processing an ASR Processing an ASR
----------------- -----------------
Asynchronous signals were designed to provide the Asynchronous signals were designed to provide the capability to generate
capability to generate software interrupts. The processing of software interrupts. The processing of software interrupts parallels that of
software interrupts parallels that of hardware interrupts. As a hardware interrupts. As a result, the differences between the formats of ASRs
result, the differences between the formats of ASRs and ISRs is and ISRs is limited to the meaning of the single argument passed to an ASR.
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
The ASR should have the following calling sequence and adhere to conventions:
C calling conventions:.. index:: rtems_asr
.. index:: rtems_asr
.. code:: c .. code:: c
rtems_asr user_routine( rtems_asr user_routine(
rtems_signal_set signals rtems_signal_set signals
); );
When the ASR returns to RTEMS the mode and execution When the ASR returns to RTEMS the mode and execution path of the interrupted
path of the interrupted task (or ASR) is restored to the context task (or ASR) is restored to the context prior to entering the ASR.
prior to entering the ASR.
Directives Directives
========== ==========
This section details the signal manager's directives. This section details the signal manager's directives. A subsection is
A subsection is dedicated to each of this manager's directives dedicated to each of this manager's directives and describes the calling
and describes the calling sequence, related constants, usage, sequence, related constants, usage, and status codes.
and status codes.
.. _rtems_signal_catch:
SIGNAL_CATCH - Establish an ASR SIGNAL_CATCH - Establish an ASR
------------------------------- -------------------------------
@ -226,47 +215,55 @@ SIGNAL_CATCH - Establish an ASR
.. code:: c .. code:: c
rtems_status_code rtems_signal_catch( rtems_status_code rtems_signal_catch(
rtems_asr_entry asr_handler, rtems_asr_entry asr_handler,
rtems_mode mode rtems_mode mode
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - always successful .. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- always successful
**DESCRIPTION:** **DESCRIPTION:**
This directive establishes an asynchronous signal This directive establishes an asynchronous signal routine (ASR) for the calling
routine (ASR) for the calling task. The asr_handler parameter task. The asr_handler parameter specifies the entry point of the ASR. If
specifies the entry point of the ASR. If asr_handler is NULL, asr_handler is NULL, the ASR for the calling task is invalidated and all
the ASR for the calling task is invalidated and all pending pending signals are cleared. Any signals sent to a task with an invalid ASR
signals are cleared. Any signals sent to a task with an invalid are discarded. The mode parameter specifies the execution mode for the ASR.
ASR are discarded. The mode parameter specifies the execution This execution mode supersedes the task's execution mode while the ASR is
mode for the ASR. This execution mode supersedes the task's executing.
execution mode while the ASR is executing.
**NOTES:** **NOTES:**
This directive will not cause the calling task to be This directive will not cause the calling task to be preempted.
preempted.
The following task mode constants are defined by RTEMS: 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_signal_send:
- ``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
SIGNAL_SEND - Send signal set to a task SIGNAL_SEND - Send signal set to a task
--------------------------------------- ---------------------------------------
@ -279,46 +276,42 @@ SIGNAL_SEND - Send signal set to a task
.. code:: c .. code:: c
rtems_status_code rtems_signal_send( rtems_status_code rtems_signal_send(
rtems_id id, rtems_id id,
rtems_signal_set signal_set rtems_signal_set signal_set
); );
**DIRECTIVE STATUS CODES:** **DIRECTIVE STATUS CODES:**
``RTEMS_SUCCESSFUL`` - signal sent successfully .. list-table::
``RTEMS_INVALID_ID`` - task id invalid :class: rtems-table
``RTEMS_INVALID_NUMBER`` - empty signal set
``RTEMS_NOT_DEFINED`` - ASR invalid * - ``RTEMS_SUCCESSFUL``
- signal sent successfully
* - ``RTEMS_INVALID_ID``
- task id invalid
* - ``RTEMS_INVALID_NUMBER``
- empty signal set
* - ``RTEMS_NOT_DEFINED``
- ASR invalid
**DESCRIPTION:** **DESCRIPTION:**
This directive sends a signal set to the task This directive sends a signal set to the task specified in id. The signal_set
specified in id. The signal_set parameter contains the signal parameter contains the signal set to be sent to the task.
set to be sent to the task.
If a caller sends a signal set to a task with an If a caller sends a signal set to a task with an invalid ASR, then an error
invalid ASR, then an error code is returned to the caller. If a code is returned to the caller. If a caller sends a signal set to a task whose
caller sends a signal set to a task whose ASR is valid but ASR is valid but disabled, then the signal set will be caught and left pending
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
for the ASR to process when it is enabled. If a caller sends a task with an ASR that is both valid and enabled, then the signal set is caught
signal set to a task with an ASR that is both valid and enabled, and the ASR will execute the next time the task is dispatched to run.
then the signal set is caught and the ASR will execute the next
time the task is dispatched to run.
**NOTES:** **NOTES:**
Sending a signal set to a task has no effect on that Sending a signal set to a task has no effect on that task's state. If a signal
task's state. If a signal set is sent to a blocked task, then set is sent to a blocked task, then the task will remain blocked and the
the task will remain blocked and the signals will be processed signals will be processed when the task becomes the running task.
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 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.

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