summaryrefslogtreecommitdiffstats
path: root/doc/user/signal.t
blob: 759e249b4eb91b43c6caa5bbbcf605fd227fe12d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@ifinfo
@node Signal Manager, Signal Manager Introduction, EVENT_RECEIVE - Receive event condition, Top
@end ifinfo
@chapter Signal Manager
@ifinfo
@menu
* Signal Manager Introduction::
* Signal Manager Background::
* Signal Manager Operations::
* Signal Manager Directives::
@end menu
@end ifinfo

@ifinfo
@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager
@end ifinfo
@section Introduction

The signal manager provides the capabilities required
for asynchronous communication.  The directives provided by the
signal manager are:

@itemize @bullet
@item @code{signal_catch} - Establish an ASR
@item @code{signal_send} - Send signal set to a task
@end itemize

@ifinfo
@node Signal Manager Background, Signal Manager Definitions, Signal Manager Introduction, Signal Manager
@end ifinfo
@section Background
@ifinfo
@menu
* Signal Manager Definitions::
* A Comparison of ASRs and ISRs::
* Building a Signal Set::
* Building an ASR's Mode::
@end menu
@end ifinfo

@ifinfo
@node Signal Manager Definitions, A Comparison of ASRs and ISRs, Signal Manager Background, Signal Manager Background
@end ifinfo
@subsection 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.

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.  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.


@ifinfo
@node A Comparison of ASRs and ISRs, Building a Signal Set, Signal Manager Definitions, Signal Manager Background
@end ifinfo
@subsection A Comparison of ASRs and ISRs

The format of an ASR is similar to that of an ISR
with the following exceptions:

@itemize @bullet
@item ISRs are scheduled by the processor hardware.  ASRs are
scheduled by RTEMS.

@item 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.

@item 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.

@item 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.
@end itemize

@ifinfo
@node Building a Signal Set, Building an ASR's Mode, A Comparison of ASRs and ISRs, Signal Manager Background
@end ifinfo
@subsection Building a Signal Set

A signal set is built by a bitwise OR of the desired
signals.  The set of valid signals is @code{SIGNAL_0} through
@code{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 
@code{SIGNAL_6}, @code{SIGNAL_15}, and @code{SIGNAL_31}.  
The signal parameter provided to the signal_send directive should be
@code{@value{RPREFIX}SIGNAL_6 @value{OR} 
@value{RPREFIX}SIGNAL_15 @value{OR} @value{RPREFIX}SIGNAL_31}.

@ifinfo
@node Building an ASR's Mode, Signal Manager Operations, Building a Signal Set, Signal Manager Background
@end ifinfo
@subsection Building an ASR's 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:

@itemize @bullet
@item @code{PREEMPT} is masked by
@code{PREEMPT_MASK} and enables preemption

@item @code{NO_PREEMPT} is masked by
@code{PREEMPT_MASK} and disables preemption

@item @code{NO_TIMESLICE} is masked by
@code{TIMESLICE_MASK} and disables timeslicing

@item @code{TIMESLICE} is masked by
@code{TIMESLICE_MASK} and enables timeslicing

@item @code{ASR} is masked by
@code{ASR_MASK} and enables ASR processing

@item @code{NO_ASR} is masked by
@code{ASR_MASK} and disables ASR processing

@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
@code{INTERRUPT_MASK} and enables all interrupts

@item @code{@value{RPREFIX}INTERRUPT_LEVEL}(n)} is masked by
@code{INTERRUPT_MASK} and sets interrupts level n
@end itemize

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 signal_catch to establish an ASR which executes at
interrupt level three and is non-preemptible.  The mode should
be set to
@code{@value{RPREFIX}INTERRUPT_LEVEL(3) @value{OR} @value{RPREFIX}NO_PREEMPT}
to indicate the
desired processor mode and interrupt level.

@ifinfo
@node Signal Manager Operations, Establishing an ASR, Building an ASR's Mode, Signal Manager
@end ifinfo
@section Operations
@ifinfo
@menu
* Establishing an ASR::
* Sending a Signal Set::
* Processing an ASR::
@end menu
@end ifinfo

@ifinfo
@node Establishing an ASR, Sending a Signal Set, Signal Manager Operations, Signal Manager Operations
@end ifinfo
@subsection Establishing an ASR

The 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 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 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 (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 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.

@ifinfo
@node Sending a Signal Set, Processing an ASR, Establishing an ASR, Signal Manager Operations
@end ifinfo
@subsection Sending a Signal Set

The 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 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.

@ifinfo
@node Processing an ASR, Signal Manager Directives, Sending a Signal Set, Signal Manager Operations
@end ifinfo
@subsection 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
@value{LANGUAGE} calling conventions:

@ifset is-C
@example
rtems_asr user_routine(
  rtems_signal_set signals
);
@end example
@end ifset

@ifset is-Ada
@example
procedure User_Routine (
  Signals : in     RTEMS.Signal_Set
);
@end example
@end ifset

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.

@ifinfo
@node Signal Manager Directives, SIGNAL_CATCH - Establish an ASR, Processing an ASR, Signal Manager
@end ifinfo
@section Directives
@ifinfo
@menu
* SIGNAL_CATCH - Establish an ASR::
* SIGNAL_SEND - Send signal set to a task::
@end menu
@end ifinfo

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.

@page
@ifinfo
@node SIGNAL_CATCH - Establish an ASR, SIGNAL_SEND - Send signal set to a task, Signal Manager Directives, Signal Manager Directives
@end ifinfo
@subsection SIGNAL_CATCH - Establish an ASR

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_signal_catch(
  rtems_asr_entry  asr_handler,
  rtems_mode mode
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Signal_Catch (
   ASR_Handler : in     RTEMS.ASR_Handler;
   Mode_Set    : in     RTEMS.Mode;
   Result      :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - always successful

@subheading 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.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

The following task mode constants are defined by RTEMS:

@itemize @bullet
@item @code{PREEMPT} is masked by
@code{PREEMPT_MASK} and enables preemption

@item @code{NO_PREEMPT} is masked by
@code{PREEMPT_MASK} and disables preemption

@item @code{NO_TIMESLICE} is masked by
@code{TIMESLICE_MASK} and disables timeslicing

@item @code{TIMESLICE} is masked by
@code{TIMESLICE_MASK} and enables timeslicing

@item @code{ASR} is masked by
@code{ASR_MASK} and enables ASR processing

@item @code{NO_ASR} is masked by
@code{ASR_MASK} and disables ASR processing

@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
@code{INTERRUPT_MASK} and enables all interrupts

@item @code{@value{RPREFIX}INTERRUPT_LEVEL}(n)} is masked by
@code{INTERRUPT_MASK} and sets interrupts level n
@end itemize

@page
@ifinfo
@node SIGNAL_SEND - Send signal set to a task, Partition Manager, SIGNAL_CATCH - Establish an ASR, Signal Manager Directives
@end ifinfo
@subsection SIGNAL_SEND - Send signal set to a task

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_signal_send(
  rtems_id         id,
  rtems_signal_set signal_set
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Signal_Send (
   ID         : in     RTEMS.ID;
   Signal_Set : in     RTEMS.Signal_Set;
   Result     :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - signal sent successfully@*
@code{INVALID_ID} - task id invalid@*
@code{NOT_DEFINED} - ASR invalid

@subheading 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.

@subheading 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.