Split document into seperate files by section.

1 files changed, 324 insertions, 0 deletions

diff --git a/c_user/signal_manager.rst b/c_user/signal_manager.rst
new file mode 100644
index 0000000..2b671b1
--- /dev/null
+++ b/c_user/signal_manager.rst
@@ -0,0 +1,324 @@
+Signal Manager
+##############
+
+.. index:: signals
+
+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
+==========
+
+Signal Manager Definitions
+--------------------------
+.. index:: asynchronous signal routine
+.. index:: ASR
+
+The signal manager allows a task to optionally define
+an asynchronous signal routine (ASR).  An ASR is to a task what
+an ISR is to an application’s set of tasks.  When the processor
+is interrupted, the execution of an application is also
+interrupted and an ISR is given control.  Similarly, when a
+signal is sent to a task, that task’s execution path will be
+"interrupted" by the ASR.  Sending a signal to a task has no
+effect on the receiving task’s current execution state... index:: rtems_signal_set
+
+A signal flag is used by a task (or ISR) to inform
+another task of the occurrence of a significant situation.
+Thirty-two signal flags are associated with each task.  A
+collection of one or more signals is referred to as a signal
+set.  The data type ``rtems_signal_set``
+is used to manipulate signal sets.
+
+A signal set is posted when it is directed (or sent) to a
+task. A pending signal is a signal that has been sent to a task
+with a valid ASR, but has not been processed by that task’s ASR.
+
+A Comparison of ASRs and ISRs
+-----------------------------
+.. index:: ASR vs. ISR
+.. index:: ISR vs. ASR
+
+The format of an ASR is similar to that of an ISR
+with the following exceptions:
+
+- 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.
+
+Building a Signal Set
+---------------------
+.. index:: signal set, building
+
+A signal set is built by a bitwise OR of the desired
+signals.  The set of valid signals is ``RTEMS_SIGNAL_0`` through``RTEMS_SIGNAL_31``.  If a signal is not explicitly specified in the
+signal set, then it is not present.  Signal values are
+specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as
+each signal appears exactly once in the component list.
+
+This example demonstrates the signal parameter used
+when sending the signal set consisting of``RTEMS_SIGNAL_6``,``RTEMS_SIGNAL_15``, and``RTEMS_SIGNAL_31``.  The signal parameter provided
+to the ``rtems_signal_send`` directive should be``RTEMS_SIGNAL_6 |
+RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
+
+Building an ASR Mode
+--------------------
+.. index:: ASR mode, building
+
+In general, an ASR’s mode is built by a bitwise OR of
+the desired mode components.  The set of valid mode components
+is the same as those allowed with the task_create and task_mode
+directives.  A complete list of mode options is provided in the
+following table:
+
+- ``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.
+
+Processing an ASR
+-----------------
+
+Asynchronous signals were designed to provide the
+capability to generate software interrupts.  The processing of
+software interrupts parallels that of hardware interrupts.  As a
+result, the differences between the formats of ASRs and ISRs is
+limited to the meaning of the single argument passed to an ASR.
+The ASR should have the following calling sequence and adhere to
+C calling conventions:.. index:: rtems_asr
+
+.. code:: 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.
+
+SIGNAL_CATCH - Establish an ASR
+-------------------------------
+.. index:: establish an ASR
+.. index:: install an ASR
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_signal_catch
+
+.. code:: c
+
+    rtems_status_code rtems_signal_catch(
+    rtems_asr_entry  asr_handler,
+    rtems_mode mode
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``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:
+
+- ``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
+
+SIGNAL_SEND - Send signal set to a task
+---------------------------------------
+.. index:: send signal set
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_signal_send
+
+.. code:: c
+
+    rtems_status_code rtems_signal_send(
+    rtems_id         id,
+    rtems_signal_set signal_set
+    );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL`` - signal sent successfully
+``RTEMS_INVALID_ID`` - task id invalid
+``RTEMS_INVALID_NUMBER`` - empty signal set
+``RTEMS_NOT_DEFINED`` - ASR invalid
+
+**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.
+
+.. COMMENT: COPYRIGHT (c) 1988-2010.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+