source: rtems-docs/c-user/signal_manager.rst @ 969e60e

5
Last change on this file since 969e60e was 3384994, checked in by Chris Johns <chrisj@…>, on 11/13/17 at 02:25:18

Clean up sphinx warnings.

  • Fix minor formatting issues.
  • Fix reference the gloassary TLS using ':term:'.
  • Make sure nothing is between an anchor and the heading where ':ref:' references the anchor. This meant moving all the recently added '.. index::' entries.

Update #3232.
Update #3229.

  • Property mode set to 100644
File size: 11.9 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7.. index:: signals
8
9Signal Manager
10**************
11
12Introduction
13============
14
15The signal manager provides the capabilities required for asynchronous
16communication.  The directives provided by the signal manager are:
17
18- rtems_signal_catch_ - Establish an ASR
19
20- rtems_signal_send_ - Send signal set to a task
21
22Background
23==========
24
25.. index:: asynchronous signal routine
26.. index:: ASR
27
28Signal Manager Definitions
29--------------------------
30
31The signal manager allows a task to optionally define an asynchronous signal
32routine (ASR).  An ASR is to a task what an ISR is to an application's set of
33tasks.  When the processor is interrupted, the execution of an application is
34also interrupted and an ISR is given control.  Similarly, when a signal is sent
35to a task, that task's execution path will be "interrupted" by the ASR.
36Sending a signal to a task has no effect on the receiving task's current
37execution state.
38
39.. index:: rtems_signal_set
40
41A signal flag is used by a task (or ISR) to inform another task of the
42occurrence of a significant situation.  Thirty-two signal flags are associated
43with each task.  A collection of one or more signals is referred to as a signal
44set.  The data type ``rtems_signal_set`` is used to manipulate signal sets.
45
46A signal set is posted when it is directed (or sent) to a task. A pending
47signal is a signal that has been sent to a task with a valid ASR, but has not
48been processed by that task's ASR.
49
50.. index:: ASR vs. ISR
51.. index:: ISR vs. ASR
52
53A Comparison of ASRs and ISRs
54-----------------------------
55
56The format of an ASR is similar to that of an ISR with the following
57exceptions:
58
59- ISRs are scheduled by the processor hardware.  ASRs are scheduled by RTEMS.
60
61- ISRs do not execute in the context of a task and may invoke only a subset of
62  directives.  ASRs execute in the context of a task and may execute any
63  directive.
64
65- When an ISR is invoked, it is passed the vector number as its argument.  When
66  an ASR is invoked, it is passed the signal set as its argument.
67
68- An ASR has a task mode which can be different from that of the task.  An ISR
69  does not execute as a task and, as a result, does not have a task mode.
70
71.. index:: signal set, building
72
73Building a Signal Set
74---------------------
75
76A signal set is built by a bitwise OR of the desired signals.  The set of valid
77signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``.  If a signal is not
78explicitly specified in the signal set, then it is not present.  Signal values
79are specifically designed to be mutually exclusive, therefore bitwise OR and
80addition operations are equivalent as long as each signal appears exactly once
81in the component list.
82
83This example demonstrates the signal parameter used when sending the signal set
84consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``.
85The signal parameter provided to the ``rtems_signal_send`` directive should be
86``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
87
88.. index:: ASR mode, building
89
90Building an ASR Mode
91--------------------
92
93In general, an ASR's mode is built by a bitwise OR of the desired mode
94components.  The set of valid mode components is the same as those allowed with
95the task_create and task_mode directives.  A complete list of mode options is
96provided in the following table:
97
98.. list-table::
99 :class: rtems-table
100
101 * - ``RTEMS_PREEMPT``
102   - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
103 * - ``RTEMS_NO_PREEMPT``
104   - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
105 * - ``RTEMS_NO_TIMESLICE``
106   - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
107 * - ``RTEMS_TIMESLICE``
108   - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
109 * - ``RTEMS_ASR``
110   - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
111 * - ``RTEMS_NO_ASR``
112   - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
113 * - ``RTEMS_INTERRUPT_LEVEL(0)``
114   - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
115 * - ``RTEMS_INTERRUPT_LEVEL(n)``
116   - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
117
118Mode values are specifically designed to be mutually exclusive, therefore
119bitwise OR and addition operations are equivalent as long as each mode appears
120exactly once in the component list.  A mode component listed as a default is
121not required to appear in the mode list, although it is a good programming
122practice to specify default components.  If all defaults are desired, the mode
123``DEFAULT_MODES`` should be specified on this call.
124
125This example demonstrates the mode parameter used with the
126``rtems_signal_catch`` to establish an ASR which executes at interrupt level
127three and is non-preemptible.  The mode should be set to
128``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired
129processor mode and interrupt level.
130
131Operations
132==========
133
134Establishing an ASR
135-------------------
136
137The ``rtems_signal_catch`` directive establishes an ASR for the calling task.
138The address of the ASR and its execution mode are specified to this directive.
139The ASR's mode is distinct from the task's mode.  For example, the task may
140allow preemption, while that task's ASR may have preemption disabled.  Until a
141task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no
142signal sets can be sent to the task.
143
144A task may invalidate its ASR and discard all pending signals by calling
145``rtems_signal_catch`` with a value of NULL for the ASR's address.  When a
146task's ASR is invalid, new signal sets sent to this task are discarded.
147
148A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode
149directive.  When a task's ASR is disabled, the signals sent to it are left
150pending to be processed later when the ASR is enabled.
151
152Any directive that can be called from a task can also be called from an ASR.  A
153task is only allowed one active ASR.  Thus, each call to ``rtems_signal_catch``
154replaces the previous one.
155
156Normally, signal processing is disabled for the ASR's execution mode, but if
157signal processing is enabled for the ASR, the ASR must be reentrant.
158
159Sending a Signal Set
160--------------------
161
162The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals
163to a target task.  The target task and a set of signals are specified to the
164``rtems_signal_send`` directive.  The sending of a signal to a task has no
165effect on the execution state of that task.  If the task is not the currently
166running task, then the signals are left pending and processed by the task's ASR
167the next time the task is dispatched to run.  The ASR is executed immediately
168before the task is dispatched.  If the currently running task sends a signal to
169itself or is sent a signal from an ISR, its ASR is immediately dispatched to
170run provided signal processing is enabled.
171
172If an ASR with signals enabled is preempted by another task or an ISR and a new
173signal set is sent, then a new copy of the ASR will be invoked, nesting the
174preempted ASR.  Upon completion of processing the new signal set, control will
175return to the preempted ASR.  In this situation, the ASR must be reentrant.
176
177Like events, identical signals sent to a task are not queued.  In other words,
178sending the same signal multiple times to a task (without any intermediate
179signal processing occurring for the task), has the same result as sending that
180signal to that task once.
181
182.. index:: rtems_asr
183
184Processing an ASR
185-----------------
186
187Asynchronous signals were designed to provide the capability to generate
188software interrupts.  The processing of software interrupts parallels that of
189hardware interrupts.  As a result, the differences between the formats of ASRs
190and ISRs is limited to the meaning of the single argument passed to an ASR.
191The ASR should have the following calling sequence and adhere to C calling
192conventions:
193
194.. code-block:: c
195
196    rtems_asr user_routine(
197        rtems_signal_set signals
198    );
199
200When the ASR returns to RTEMS the mode and execution path of the interrupted
201task (or ASR) is restored to the context prior to entering the ASR.
202
203Directives
204==========
205
206This section details the signal manager's directives.  A subsection is
207dedicated to each of this manager's directives and describes the calling
208sequence, related constants, usage, and status codes.
209
210.. raw:: latex
211
212   \clearpage
213
214.. index:: establish an ASR
215.. index:: install an ASR
216.. index:: rtems_signal_catch
217
218.. _rtems_signal_catch:
219
220SIGNAL_CATCH - Establish an ASR
221-------------------------------
222
223CALLING SEQUENCE:
224    .. code-block:: c
225
226        rtems_status_code rtems_signal_catch(
227            rtems_asr_entry  asr_handler,
228            rtems_mode       mode
229        );
230
231DIRECTIVE STATUS CODES:
232    .. list-table::
233     :class: rtems-table
234
235     * - ``RTEMS_SUCCESSFUL``
236       - always successful
237
238DESCRIPTION:
239    This directive establishes an asynchronous signal routine (ASR) for the
240    calling task.  The asr_handler parameter specifies the entry point of the
241    ASR.  If asr_handler is NULL, the ASR for the calling task is invalidated
242    and all pending signals are cleared.  Any signals sent to a task with an
243    invalid ASR are discarded.  The mode parameter specifies the execution mode
244    for the ASR.  This execution mode supersedes the task's execution mode
245    while the ASR is executing.
246
247NOTES:
248    This directive will not cause the calling task to be preempted.
249
250    The following task mode constants are defined by RTEMS:
251
252    .. list-table::
253     :class: rtems-table
254
255     * - ``RTEMS_PREEMPT``
256       - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
257     * - ``RTEMS_NO_PREEMPT``
258       - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
259     * - ``RTEMS_NO_TIMESLICE``
260       - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
261     * - ``RTEMS_TIMESLICE``
262       - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
263     * - ``RTEMS_ASR``
264       - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
265     * - ``RTEMS_NO_ASR``
266       - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
267     * - ``RTEMS_INTERRUPT_LEVEL(0)``
268       - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
269     * - ``RTEMS_INTERRUPT_LEVEL(n)``
270       - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
271
272.. raw:: latex
273
274   \clearpage
275
276.. index:: send signal set
277.. index:: rtems_signal_send
278
279.. _rtems_signal_send:
280
281SIGNAL_SEND - Send signal set to a task
282---------------------------------------
283
284CALLING SEQUENCE:
285    .. code-block:: c
286
287        rtems_status_code rtems_signal_send(
288            rtems_id         id,
289            rtems_signal_set signal_set
290        );
291
292DIRECTIVE STATUS CODES:
293    .. list-table::
294     :class: rtems-table
295
296     * - ``RTEMS_SUCCESSFUL``
297       - signal sent successfully
298     * - ``RTEMS_INVALID_ID``
299       - task id invalid
300     * - ``RTEMS_INVALID_NUMBER``
301       - empty signal set
302     * - ``RTEMS_NOT_DEFINED``
303       - ASR invalid
304
305DESCRIPTION:
306    This directive sends a signal set to the task specified in id.  The
307    signal_set parameter contains the signal set to be sent to the task.
308
309    If a caller sends a signal set to a task with an invalid ASR, then an error
310    code is returned to the caller.  If a caller sends a signal set to a task
311    whose ASR is valid but disabled, then the signal set will be caught and
312    left pending for the ASR to process when it is enabled. If a caller sends a
313    signal set to a task with an ASR that is both valid and enabled, then the
314    signal set is caught and the ASR will execute the next time the task is
315    dispatched to run.
316
317NOTES:
318    Sending a signal set to a task has no effect on that task's state.  If a
319    signal set is sent to a blocked task, then the task will remain blocked and
320    the signals will be processed when the task becomes the running task.
321
322    Sending a signal set to a global task which does not reside on the local
323    node will generate a request telling the remote node to send the signal set
324    to the specified task.
Note: See TracBrowser for help on using the repository browser.