source: rtems/doc/user/signal.t @ d4696eb

4.104.114.84.95
Last change on this file since d4696eb was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on 01/17/02 at 21:47:47

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • Property mode set to 100644
File size: 12.6 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Signal Manager
10
11@cindex signals
12
13@section Introduction
14
15The signal manager provides the capabilities required
16for asynchronous communication.  The directives provided by the
17signal manager are:
18
19@itemize @bullet
20@item @code{@value{DIRPREFIX}signal_catch} - Establish an ASR
21@item @code{@value{DIRPREFIX}signal_send} - Send signal set to a task
22@end itemize
23
24@section Background
25
26@subsection Signal Manager Definitions
27
28@cindex asynchronous signal routine
29@cindex ASR
30
31The signal manager allows a task to optionally define
32an asynchronous signal routine (ASR).  An ASR is to a task what
33an ISR is to an application's set of tasks.  When the processor
34is interrupted, the execution of an application is also
35interrupted and an ISR is given control.  Similarly, when a
36signal is sent to a task, that task's execution path will be
37"interrupted" by the ASR.  Sending a signal to a task has no
38effect on the receiving task's current execution state.
39
40@findex rtems_signal_set
41
42A signal flag is used by a task (or ISR) to inform
43another task of the occurrence of a significant situation.
44Thirty-two signal flags are associated with each task.  A
45collection of one or more signals is referred to as a signal
46set.  The data type @code{@value{DIRPREFIX}signal_set}
47is used to manipulate signal sets.
48
49A signal set is posted when it is directed (or sent) to a
50task. A pending signal is a signal that has been sent to a task
51with a valid ASR, but has not been processed by that task's ASR.
52
53
54@subsection A Comparison of ASRs and ISRs
55
56@cindex ASR vs. ISR
57@cindex ISR vs. ASR
58
59The format of an ASR is similar to that of an ISR
60with the following exceptions:
61
62@itemize @bullet
63@item ISRs are scheduled by the processor hardware.  ASRs are
64scheduled by RTEMS.
65
66@item ISRs do not execute in the context of a task and may
67invoke only a subset of directives.  ASRs execute in the context
68of a task and may execute any directive.
69
70@item When an ISR is invoked, it is passed the vector number
71as its argument.  When an ASR is invoked, it is passed the
72signal set as its argument.
73
74@item An ASR has a task mode which can be different from that
75of the task.  An ISR does not execute as a task and, as a
76result, does not have a task mode.
77@end itemize
78
79@subsection Building a Signal Set
80
81@cindex signal set, building
82
83A signal set is built by a bitwise OR of the desired
84signals.  The set of valid signals is @code{@value{RPREFIX}SIGNAL_0} through
85@code{@value{RPREFIX}SIGNAL_31}.  If a signal is not explicitly specified in the
86signal set, then it is not present.  Signal values are
87specifically designed to be mutually exclusive, therefore
88bitwise OR and addition operations are equivalent as long as
89each signal appears exactly once in the component list.
90
91This example demonstrates the signal parameter used
92when sending the signal set consisting of
93@code{@value{RPREFIX}SIGNAL_6},
94@code{@value{RPREFIX}SIGNAL_15}, and
95@code{@value{RPREFIX}SIGNAL_31}.  The signal parameter provided
96to the @code{@value{DIRPREFIX}signal_send} directive should be
97@code{@value{RPREFIX}SIGNAL_6 @value{OR}
98@value{RPREFIX}SIGNAL_15 @value{OR} @value{RPREFIX}SIGNAL_31}.
99
100@subsection Building an ASR Mode
101
102@cindex ASR mode, building
103
104In general, an ASR's mode is built by a bitwise OR of
105the desired mode components.  The set of valid mode components
106is the same as those allowed with the task_create and task_mode
107directives.  A complete list of mode options is provided in the
108following table:
109
110@itemize @bullet
111@item @code{@value{RPREFIX}PREEMPT} is masked by
112@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
113
114@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
115@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
116
117@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
118@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
119
120@item @code{@value{RPREFIX}TIMESLICE} is masked by
121@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
122
123@item @code{@value{RPREFIX}ASR} is masked by
124@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
125
126@item @code{@value{RPREFIX}NO_ASR} is masked by
127@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
128
129@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
130@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
131
132@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
133@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
134@end itemize
135
136Mode values are specifically designed to be mutually
137exclusive, therefore bitwise OR and addition operations are
138equivalent as long as each mode appears exactly once in the
139component list.  A mode component listed as a default is not
140required to appear in the mode list, although it is a good
141programming practice to specify default components.  If all
142defaults are desired, the mode DEFAULT_MODES should be specified
143on this call.
144
145This example demonstrates the mode parameter used
146with the @code{@value{DIRPREFIX}signal_catch}
147to establish an ASR which executes at
148interrupt level three and is non-preemptible.  The mode should
149be set to
150@code{@value{RPREFIX}INTERRUPT_LEVEL(3) @value{OR} @value{RPREFIX}NO_PREEMPT}
151to indicate the
152desired processor mode and interrupt level.
153
154@section Operations
155
156@subsection Establishing an ASR
157
158The @code{@value{DIRPREFIX}signal_catch} directive establishes an ASR for the
159calling task.  The address of the ASR and its execution mode are
160specified to this directive.  The ASR's mode is distinct from
161the task's mode.  For example, the task may allow preemption,
162while that task's ASR may have preemption disabled.  Until a
163task calls @code{@value{DIRPREFIX}signal_catch} the first time,
164its ASR is invalid, and no signal sets can be sent to the task.
165
166A task may invalidate its ASR and discard all pending
167signals by calling @code{@value{DIRPREFIX}signal_catch}
168with a value of NULL for the ASR's address.  When a task's
169ASR is invalid, new signal sets sent to this task are discarded.
170
171A task may disable ASR processing (@code{@value{RPREFIX}NO_ASR}) via the
172task_mode directive.  When a task's ASR is disabled, the signals
173sent to it are left pending to be processed later when the ASR
174is enabled.
175
176Any directive that can be called from a task can also
177be called from an ASR.  A task is only allowed one active ASR.
178Thus, each call to @code{@value{DIRPREFIX}signal_catch}
179replaces the previous one.
180
181Normally, signal processing is disabled for the ASR's
182execution mode, but if signal processing is enabled for the ASR,
183the ASR must be reentrant.
184
185@subsection Sending a Signal Set
186
187The @code{@value{DIRPREFIX}signal_send} directive allows both
188tasks and ISRs to send signals to a target task.  The target task and
189a set of signals are specified to the
190@code{@value{DIRPREFIX}signal_send} directive.  The sending
191of a signal to a task has no effect on the execution state of
192that task.  If the task is not the currently running task, then
193the signals are left pending and processed by the task's ASR the
194next time the task is dispatched to run.  The ASR is executed
195immediately before the task is dispatched.  If the currently
196running task sends a signal to itself or is sent a signal from
197an ISR, its ASR is immediately dispatched to run provided signal
198processing is enabled.
199
200If an ASR with signals enabled is preempted by
201another task or an ISR and a new signal set is sent, then a new
202copy of the ASR will be invoked, nesting the preempted ASR.
203Upon completion of processing the new signal set, control will
204return to the preempted ASR.  In this situation, the ASR must be
205reentrant.
206
207Like events, identical signals sent to a task are not
208queued.  In other words, sending the same signal multiple times
209to a task (without any intermediate signal processing occurring
210for the task), has the same result as sending that signal to
211that task once.
212
213@subsection Processing an ASR
214
215Asynchronous signals were designed to provide the
216capability to generate software interrupts.  The processing of
217software interrupts parallels that of hardware interrupts.  As a
218result, the differences between the formats of ASRs and ISRs is
219limited to the meaning of the single argument passed to an ASR.
220The ASR should have the following calling sequence and adhere to
221@value{LANGUAGE} calling conventions:
222
223@ifset is-C
224@findex rtems_asr
225@example
226rtems_asr user_routine(
227  rtems_signal_set signals
228);
229@end example
230@end ifset
231
232@ifset is-Ada
233@example
234procedure User_Routine (
235  Signals : in     RTEMS.Signal_Set
236);
237@end example
238@end ifset
239
240When the ASR returns to RTEMS the mode and execution
241path of the interrupted task (or ASR) is restored to the context
242prior to entering the ASR.
243
244@section Directives
245
246This section details the signal manager's directives.
247A subsection is dedicated to each of this manager's directives
248and describes the calling sequence, related constants, usage,
249and status codes.
250
251@c
252@c
253@c
254@page
255@subsection SIGNAL_CATCH - Establish an ASR
256
257@cindex establish an ASR
258@cindex install an ASR
259
260@subheading CALLING SEQUENCE:
261
262@ifset is-C
263@findex rtems_signal_catch
264@example
265rtems_status_code rtems_signal_catch(
266  rtems_asr_entry  asr_handler,
267  rtems_mode mode
268);
269@end example
270@end ifset
271
272@ifset is-Ada
273@example
274procedure Signal_Catch (
275   ASR_Handler : in     RTEMS.ASR_Handler;
276   Mode_Set    : in     RTEMS.Mode;
277   Result      :    out RTEMS.Status_Codes
278);
279@end example
280@end ifset
281
282@subheading DIRECTIVE STATUS CODES:
283@code{@value{RPREFIX}SUCCESSFUL} - always successful
284
285@subheading DESCRIPTION:
286
287This directive establishes an asynchronous signal
288routine (ASR) for the calling task.  The asr_handler parameter
289specifies the entry point of the ASR.  If asr_handler is NULL,
290the ASR for the calling task is invalidated and all pending
291signals are cleared.  Any signals sent to a task with an invalid
292ASR are discarded.  The mode parameter specifies the execution
293mode for the ASR.  This execution mode supersedes the task's
294execution mode while the ASR is executing.
295
296@subheading NOTES:
297
298This directive will not cause the calling task to be
299preempted.
300
301The following task mode constants are defined by RTEMS:
302
303@itemize @bullet
304@item @code{@value{RPREFIX}PREEMPT} is masked by
305@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
306
307@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
308@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
309
310@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
311@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
312
313@item @code{@value{RPREFIX}TIMESLICE} is masked by
314@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
315
316@item @code{@value{RPREFIX}ASR} is masked by
317@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
318
319@item @code{@value{RPREFIX}NO_ASR} is masked by
320@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
321
322@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
323@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
324
325@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
326@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
327@end itemize
328
329@c
330@c
331@c
332@page
333@subsection SIGNAL_SEND - Send signal set to a task
334
335@cindex send signal set
336
337@subheading CALLING SEQUENCE:
338
339@ifset is-C
340@findex rtems_signal_send
341@example
342rtems_status_code rtems_signal_send(
343  rtems_id         id,
344  rtems_signal_set signal_set
345);
346@end example
347@end ifset
348
349@ifset is-Ada
350@example
351procedure Signal_Send (
352   ID         : in     RTEMS.ID;
353   Signal_Set : in     RTEMS.Signal_Set;
354   Result     :    out RTEMS.Status_Codes
355);
356@end example
357@end ifset
358
359@subheading DIRECTIVE STATUS CODES:
360@code{@value{RPREFIX}SUCCESSFUL} - signal sent successfully@*
361@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
362@code{@value{RPREFIX}NOT_DEFINED} - ASR invalid
363
364@subheading DESCRIPTION:
365
366This directive sends a signal set to the task
367specified in id.  The signal_set parameter contains the signal
368set to be sent to the task.
369
370If a caller sends a signal set to a task with an
371invalid ASR, then an error code is returned to the caller.  If a
372caller sends a signal set to a task whose ASR is valid but
373disabled, then the signal set will be caught and left pending
374for the ASR to process when it is enabled. If a caller sends a
375signal set to a task with an ASR that is both valid and enabled,
376then the signal set is caught and the ASR will execute the next
377time the task is dispatched to run.
378
379@subheading NOTES:
380
381Sending a signal set to a task has no effect on that
382task's state.  If a signal set is sent to a blocked task, then
383the task will remain blocked and the signals will be processed
384when the task becomes the running task.
385
386Sending a signal set to a global task which does not
387reside on the local node will generate a request telling the
388remote node to send the signal set to the specified task.
389
Note: See TracBrowser for help on using the repository browser.