From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/signal_manager.rst | 324 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 c_user/signal_manager.rst (limited to 'c_user/signal_manager.rst') 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. + -- cgit v1.2.3