source: rtems/doc/user/signal.t @ 1e524995

4.104.114.84.95
Last change on this file since 1e524995 was 1e524995, checked in by Joel Sherrill <joel.sherrill@…>, on Feb 6, 1998 at 2:14:30 PM

Updated copyrights

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