[PATCH v2 12/16] c-user: Split up signal manager

Sebastian Huber sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:06 UTC 2020


This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.
---
 c-user/index.rst               |   2 +-
 c-user/signal/background.rst   | 112 ++++++++++++
 c-user/signal/directives.rst   | 126 +++++++++++++
 c-user/signal/index.rst        |  15 ++
 c-user/signal/introduction.rst |  13 ++
 c-user/signal/operations.rst   |  75 ++++++++
 c-user/signal_manager.rst      | 322 ---------------------------------
 7 files changed, 342 insertions(+), 323 deletions(-)
 create mode 100644 c-user/signal/background.rst
 create mode 100644 c-user/signal/directives.rst
 create mode 100644 c-user/signal/index.rst
 create mode 100644 c-user/signal/introduction.rst
 create mode 100644 c-user/signal/operations.rst
 delete mode 100644 c-user/signal_manager.rst

diff --git a/c-user/index.rst b/c-user/index.rst
index 7bd6017..3628634 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -39,7 +39,7 @@ RTEMS Classic API Guide (|version|).
 	barrier/index
 	message/index
 	event/index
-	signal_manager
+	signal/index
 	partition/index
 	region/index
 	dual-ported-memory/index
diff --git a/c-user/signal/background.rst b/c-user/signal/background.rst
new file mode 100644
index 0000000..5ba5eeb
--- /dev/null
+++ b/c-user/signal/background.rst
@@ -0,0 +1,112 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+.. index:: asynchronous signal routine
+.. index:: ASR
+
+Signal Manager Definitions
+--------------------------
+
+The signal manager allows a task to optionally define an asynchronous signal
+routine (ASR).  An ASR is to a task what an ISR is to an application's set of
+tasks.  When the processor is interrupted, the execution of an application is
+also interrupted and an ISR is given control.  Similarly, when a signal is sent
+to a task, that task's execution path will be "interrupted" by the ASR.
+Sending a signal to a task has no effect on the receiving task's current
+execution state.
+
+.. index:: rtems_signal_set
+
+A signal flag is used by a task (or ISR) to inform another task of the
+occurrence of a significant situation.  Thirty-two signal flags are associated
+with each task.  A collection of one or more signals is referred to as a signal
+set.  The data type ``rtems_signal_set`` is used to manipulate signal sets.
+
+A signal set is posted when it is directed (or sent) to a task. A pending
+signal is a signal that has been sent to a task with a valid ASR, but has not
+been processed by that task's ASR.
+
+.. index:: ASR vs. ISR
+.. index:: ISR vs. ASR
+
+A Comparison of ASRs and ISRs
+-----------------------------
+
+The format of an ASR is similar to that of an ISR with the following
+exceptions:
+
+- ISRs are scheduled by the processor hardware.  ASRs are scheduled by RTEMS.
+
+- ISRs do not execute in the context of a task and may invoke only a subset of
+  directives.  ASRs execute in the context of a task and may execute any
+  directive.
+
+- When an ISR is invoked, it is passed the vector number as its argument.  When
+  an ASR is invoked, it is passed the signal set as its argument.
+
+- An ASR has a task mode which can be different from that of the task.  An ISR
+  does not execute as a task and, as a result, does not have a task mode.
+
+.. index:: signal set, building
+
+Building a Signal Set
+---------------------
+
+A signal set is built by a bitwise OR of the desired signals.  The set of valid
+signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``.  If a signal is not
+explicitly specified in the signal set, then it is not present.  Signal values
+are specifically designed to be mutually exclusive, therefore bitwise OR and
+addition operations are equivalent as long as each signal appears exactly once
+in the component list.
+
+This example demonstrates the signal parameter used when sending the signal set
+consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``.
+The signal parameter provided to the ``rtems_signal_send`` directive should be
+``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
+
+.. index:: ASR mode, building
+
+Building an ASR Mode
+--------------------
+
+In general, an ASR's mode is built by a bitwise OR of the desired mode
+components.  The set of valid mode components is the same as those allowed with
+the task_create and task_mode directives.  A complete list of mode options is
+provided in the following table:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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
+
+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.
diff --git a/c-user/signal/directives.rst b/c-user/signal/directives.rst
new file mode 100644
index 0000000..2479681
--- /dev/null
+++ b/c-user/signal/directives.rst
@@ -0,0 +1,126 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+This section details the signal manager's directives.  A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: establish an ASR
+.. index:: install an ASR
+.. index:: rtems_signal_catch
+
+.. _rtems_signal_catch:
+
+SIGNAL_CATCH - Establish an ASR
+-------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_signal_catch(
+            rtems_asr_entry  asr_handler,
+            rtems_mode       mode
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - always successful
+
+DESCRIPTION:
+    This directive establishes an asynchronous signal routine (ASR) for the
+    calling task.  The asr_handler parameter specifies the entry point of the
+    ASR.  If asr_handler is NULL, the ASR for the calling task is invalidated
+    and all pending signals are cleared.  Any signals sent to a task with an
+    invalid ASR are discarded.  The mode parameter specifies the execution mode
+    for the ASR.  This execution mode supersedes the task's execution mode
+    while the ASR is executing.
+
+NOTES:
+    This directive will not cause the calling task to be preempted.
+
+    The following task mode constants are defined by RTEMS:
+
+    .. list-table::
+     :class: rtems-table
+
+     * - ``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
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: send signal set
+.. index:: rtems_signal_send
+
+.. _rtems_signal_send:
+
+SIGNAL_SEND - Send signal set to a task
+---------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_signal_send(
+            rtems_id         id,
+            rtems_signal_set signal_set
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - signal sent successfully
+     * - ``RTEMS_INVALID_ID``
+       - task id invalid
+     * - ``RTEMS_INVALID_NUMBER``
+       - empty signal set
+     * - ``RTEMS_NOT_DEFINED``
+       - ASR invalid
+
+DESCRIPTION:
+    This directive sends a signal set to the task specified in id.  The
+    signal_set parameter contains the signal set to be sent to the task.
+
+    If a caller sends a signal set to a task with an invalid ASR, then an error
+    code is returned to the caller.  If a caller sends a signal set to a task
+    whose ASR is valid but disabled, then the signal set will be caught and
+    left pending for the ASR to process when it is enabled. If a caller sends a
+    signal set to a task with an ASR that is both valid and enabled, then the
+    signal set is caught and the ASR will execute the next time the task is
+    dispatched to run.
+
+NOTES:
+    Sending a signal set to a task has no effect on that task's state.  If a
+    signal set is sent to a blocked task, then the task will remain blocked and
+    the signals will be processed when the task becomes the running task.
+
+    Sending a signal set to a global task which does not reside on the local
+    node will generate a request telling the remote node to send the signal set
+    to the specified task.
diff --git a/c-user/signal/index.rst b/c-user/signal/index.rst
new file mode 100644
index 0000000..ad28b9f
--- /dev/null
+++ b/c-user/signal/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: signals
+
+Signal Manager
+**************
+
+.. toctree::
+
+    introduction
+    background
+    operations
+    directives
diff --git a/c-user/signal/introduction.rst b/c-user/signal/introduction.rst
new file mode 100644
index 0000000..292db52
--- /dev/null
+++ b/c-user/signal/introduction.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The signal manager provides the capabilities required for asynchronous
+communication.  The directives provided by the signal manager are:
+
+- :ref:`rtems_signal_catch`
+
+- :ref:`rtems_signal_send`
diff --git a/c-user/signal/operations.rst b/c-user/signal/operations.rst
new file mode 100644
index 0000000..967b35f
--- /dev/null
+++ b/c-user/signal/operations.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Establishing an ASR
+-------------------
+
+The ``rtems_signal_catch`` directive establishes an ASR for the calling task.
+The address of the ASR and its execution mode are specified to this directive.
+The ASR's mode is distinct from the task's mode.  For example, the task may
+allow preemption, while that task's ASR may have preemption disabled.  Until a
+task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no
+signal sets can be sent to the task.
+
+A task may invalidate its ASR and discard all pending signals by calling
+``rtems_signal_catch`` with a value of NULL for the ASR's address.  When a
+task's ASR is invalid, new signal sets sent to this task are discarded.
+
+A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode
+directive.  When a task's ASR is disabled, the signals sent to it are left
+pending to be processed later when the ASR is enabled.
+
+Any directive that can be called from a task can also be called from an ASR.  A
+task is only allowed one active ASR.  Thus, each call to ``rtems_signal_catch``
+replaces the previous one.
+
+Normally, signal processing is disabled for the ASR's execution mode, but if
+signal processing is enabled for the ASR, the ASR must be reentrant.
+
+Sending a Signal Set
+--------------------
+
+The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals
+to a target task.  The target task and a set of signals are specified to the
+``rtems_signal_send`` directive.  The sending of a signal to a task has no
+effect on the execution state of that task.  If the task is not the currently
+running task, then the signals are left pending and processed by the task's ASR
+the next time the task is dispatched to run.  The ASR is executed immediately
+before the task is dispatched.  If the currently running task sends a signal to
+itself or is sent a signal from an ISR, its ASR is immediately dispatched to
+run provided signal processing is enabled.
+
+If an ASR with signals enabled is preempted by another task or an ISR and a new
+signal set is sent, then a new copy of the ASR will be invoked, nesting the
+preempted ASR.  Upon completion of processing the new signal set, control will
+return to the preempted ASR.  In this situation, the ASR must be reentrant.
+
+Like events, identical signals sent to a task are not queued.  In other words,
+sending the same signal multiple times to a task (without any intermediate
+signal processing occurring for the task), has the same result as sending that
+signal to that task once.
+
+.. index:: rtems_asr
+
+Processing an ASR
+-----------------
+
+Asynchronous signals were designed to provide the capability to generate
+software interrupts.  The processing of software interrupts parallels that of
+hardware interrupts.  As a result, the differences between the formats of ASRs
+and ISRs is limited to the meaning of the single argument passed to an ASR.
+The ASR should have the following calling sequence and adhere to C calling
+conventions:
+
+.. code-block:: c
+
+    rtems_asr user_routine(
+        rtems_signal_set signals
+    );
+
+When the ASR returns to RTEMS the mode and execution path of the interrupted
+task (or ASR) is restored to the context prior to entering the ASR.
diff --git a/c-user/signal_manager.rst b/c-user/signal_manager.rst
deleted file mode 100644
index 8cf1101..0000000
--- a/c-user/signal_manager.rst
+++ /dev/null
@@ -1,322 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-
-.. index:: signals
-
-Signal Manager
-**************
-
-Introduction
-============
-
-The signal manager provides the capabilities required for asynchronous
-communication.  The directives provided by the signal manager are:
-
-- rtems_signal_catch_ - Establish an ASR
-
-- rtems_signal_send_ - Send signal set to a task
-
-Background
-==========
-
-.. index:: asynchronous signal routine
-.. index:: ASR
-
-Signal Manager Definitions
---------------------------
-
-The signal manager allows a task to optionally define an asynchronous signal
-routine (ASR).  An ASR is to a task what an ISR is to an application's set of
-tasks.  When the processor is interrupted, the execution of an application is
-also interrupted and an ISR is given control.  Similarly, when a signal is sent
-to a task, that task's execution path will be "interrupted" by the ASR.
-Sending a signal to a task has no effect on the receiving task's current
-execution state.
-
-.. index:: rtems_signal_set
-
-A signal flag is used by a task (or ISR) to inform another task of the
-occurrence of a significant situation.  Thirty-two signal flags are associated
-with each task.  A collection of one or more signals is referred to as a signal
-set.  The data type ``rtems_signal_set`` is used to manipulate signal sets.
-
-A signal set is posted when it is directed (or sent) to a task. A pending
-signal is a signal that has been sent to a task with a valid ASR, but has not
-been processed by that task's ASR.
-
-.. index:: ASR vs. ISR
-.. index:: ISR vs. ASR
-
-A Comparison of ASRs and ISRs
------------------------------
-
-The format of an ASR is similar to that of an ISR with the following
-exceptions:
-
-- ISRs are scheduled by the processor hardware.  ASRs are scheduled by RTEMS.
-
-- ISRs do not execute in the context of a task and may invoke only a subset of
-  directives.  ASRs execute in the context of a task and may execute any
-  directive.
-
-- When an ISR is invoked, it is passed the vector number as its argument.  When
-  an ASR is invoked, it is passed the signal set as its argument.
-
-- An ASR has a task mode which can be different from that of the task.  An ISR
-  does not execute as a task and, as a result, does not have a task mode.
-
-.. index:: signal set, building
-
-Building a Signal Set
----------------------
-
-A signal set is built by a bitwise OR of the desired signals.  The set of valid
-signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``.  If a signal is not
-explicitly specified in the signal set, then it is not present.  Signal values
-are specifically designed to be mutually exclusive, therefore bitwise OR and
-addition operations are equivalent as long as each signal appears exactly once
-in the component list.
-
-This example demonstrates the signal parameter used when sending the signal set
-consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``.
-The signal parameter provided to the ``rtems_signal_send`` directive should be
-``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
-
-.. index:: ASR mode, building
-
-Building an ASR Mode
---------------------
-
-In general, an ASR's mode is built by a bitwise OR of the desired mode
-components.  The set of valid mode components is the same as those allowed with
-the task_create and task_mode directives.  A complete list of mode options is
-provided in the following table:
-
-.. list-table::
- :class: rtems-table
-
- * - ``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
-
-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
-==========
-
-Establishing an ASR
--------------------
-
-The ``rtems_signal_catch`` directive establishes an ASR for the calling task.
-The address of the ASR and its execution mode are specified to this directive.
-The ASR's mode is distinct from the task's mode.  For example, the task may
-allow preemption, while that task's ASR may have preemption disabled.  Until a
-task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no
-signal sets can be sent to the task.
-
-A task may invalidate its ASR and discard all pending signals by calling
-``rtems_signal_catch`` with a value of NULL for the ASR's address.  When a
-task's ASR is invalid, new signal sets sent to this task are discarded.
-
-A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode
-directive.  When a task's ASR is disabled, the signals sent to it are left
-pending to be processed later when the ASR is enabled.
-
-Any directive that can be called from a task can also be called from an ASR.  A
-task is only allowed one active ASR.  Thus, each call to ``rtems_signal_catch``
-replaces the previous one.
-
-Normally, signal processing is disabled for the ASR's execution mode, but if
-signal processing is enabled for the ASR, the ASR must be reentrant.
-
-Sending a Signal Set
---------------------
-
-The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals
-to a target task.  The target task and a set of signals are specified to the
-``rtems_signal_send`` directive.  The sending of a signal to a task has no
-effect on the execution state of that task.  If the task is not the currently
-running task, then the signals are left pending and processed by the task's ASR
-the next time the task is dispatched to run.  The ASR is executed immediately
-before the task is dispatched.  If the currently running task sends a signal to
-itself or is sent a signal from an ISR, its ASR is immediately dispatched to
-run provided signal processing is enabled.
-
-If an ASR with signals enabled is preempted by another task or an ISR and a new
-signal set is sent, then a new copy of the ASR will be invoked, nesting the
-preempted ASR.  Upon completion of processing the new signal set, control will
-return to the preempted ASR.  In this situation, the ASR must be reentrant.
-
-Like events, identical signals sent to a task are not queued.  In other words,
-sending the same signal multiple times to a task (without any intermediate
-signal processing occurring for the task), has the same result as sending that
-signal to that task once.
-
-.. index:: rtems_asr
-
-Processing an ASR
------------------
-
-Asynchronous signals were designed to provide the capability to generate
-software interrupts.  The processing of software interrupts parallels that of
-hardware interrupts.  As a result, the differences between the formats of ASRs
-and ISRs is limited to the meaning of the single argument passed to an ASR.
-The ASR should have the following calling sequence and adhere to C calling
-conventions:
-
-.. code-block:: c
-
-    rtems_asr user_routine(
-        rtems_signal_set signals
-    );
-
-When the ASR returns to RTEMS the mode and execution path of the interrupted
-task (or ASR) is restored to the context prior to entering the ASR.
-
-Directives
-==========
-
-This section details the signal manager's directives.  A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: establish an ASR
-.. index:: install an ASR
-.. index:: rtems_signal_catch
-
-.. _rtems_signal_catch:
-
-SIGNAL_CATCH - Establish an ASR
--------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        rtems_status_code rtems_signal_catch(
-            rtems_asr_entry  asr_handler,
-            rtems_mode       mode
-        );
-
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
-
-     * - ``RTEMS_SUCCESSFUL``
-       - always successful
-
-DESCRIPTION:
-    This directive establishes an asynchronous signal routine (ASR) for the
-    calling task.  The asr_handler parameter specifies the entry point of the
-    ASR.  If asr_handler is NULL, the ASR for the calling task is invalidated
-    and all pending signals are cleared.  Any signals sent to a task with an
-    invalid ASR are discarded.  The mode parameter specifies the execution mode
-    for the ASR.  This execution mode supersedes the task's execution mode
-    while the ASR is executing.
-
-NOTES:
-    This directive will not cause the calling task to be preempted.
-
-    The following task mode constants are defined by RTEMS:
-
-    .. list-table::
-     :class: rtems-table
-
-     * - ``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
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: send signal set
-.. index:: rtems_signal_send
-
-.. _rtems_signal_send:
-
-SIGNAL_SEND - Send signal set to a task
----------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        rtems_status_code rtems_signal_send(
-            rtems_id         id,
-            rtems_signal_set signal_set
-        );
-
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
-
-     * - ``RTEMS_SUCCESSFUL``
-       - signal sent successfully
-     * - ``RTEMS_INVALID_ID``
-       - task id invalid
-     * - ``RTEMS_INVALID_NUMBER``
-       - empty signal set
-     * - ``RTEMS_NOT_DEFINED``
-       - ASR invalid
-
-DESCRIPTION:
-    This directive sends a signal set to the task specified in id.  The
-    signal_set parameter contains the signal set to be sent to the task.
-
-    If a caller sends a signal set to a task with an invalid ASR, then an error
-    code is returned to the caller.  If a caller sends a signal set to a task
-    whose ASR is valid but disabled, then the signal set will be caught and
-    left pending for the ASR to process when it is enabled. If a caller sends a
-    signal set to a task with an ASR that is both valid and enabled, then the
-    signal set is caught and the ASR will execute the next time the task is
-    dispatched to run.
-
-NOTES:
-    Sending a signal set to a task has no effect on that task's state.  If a
-    signal set is sent to a blocked task, then the task will remain blocked and
-    the signals will be processed when the task becomes the running task.
-
-    Sending a signal set to a global task which does not reside on the local
-    node will generate a request telling the remote node to send the signal set
-    to the specified task.
-- 
2.26.2



More information about the devel mailing list