source: rtems/doc/user/intr.t @ 87ed029

4.104.114.84.95
Last change on this file since 87ed029 was 87ed029, checked in by Joel Sherrill <joel.sherrill@…>, on 04/02/98 at 16:18:26

Added "findex" for all directive pages but it turns out that this
blows up both makeinfo and texi2dvi. So I have commented them out.

  • Property mode set to 100644
File size: 11.7 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@chapter Interrupt Manager
10
11@section Introduction
12
13Any real-time executive must provide a mechanism for
14quick response to externally generated interrupts to satisfy the
15critical time constraints of the application.  The interrupt
16manager provides this mechanism for RTEMS.  This manager permits
17quick interrupt response times by providing the critical ability
18to alter task execution which allows a task to be preempted upon
19exit from an ISR.  The interrupt manager includes the following
20directive:
21
22@itemize @bullet
23@item @code{@value{DIRPREFIX}interrupt_catch} - Establish an ISR
24@item @code{@value{DIRPREFIX}interrupt_disable} - Disable Interrupts
25@item @code{@value{DIRPREFIX}interrupt_enable} - Enable Interrupts
26@item @code{@value{DIRPREFIX}interrupt_flash} - Flash Interrupt
27@item @code{@value{DIRPREFIX}interrupt_is_in_progress} - Is an ISR in Progress
28@end itemize
29
30@section Background
31
32@subsection Processing an Interrupt
33
34The interrupt manager allows the application to
35connect a function to a hardware interrupt vector.  When an
36interrupt occurs, the processor will automatically vector to
37RTEMS.  RTEMS saves and restores all registers which are not
38preserved by the normal @value{LANGUAGE} calling convention
39for the target
40processor and invokes the user's ISR.  The user's ISR is
41responsible for processing the interrupt, clearing the interrupt
42if necessary, and device specific manipulation.
43
44The @code{@value{DIRPREFIX}interrupt_catch}
45directive connects a procedure to
46an interrupt vector.  The interrupt service routine is assumed
47to abide by these conventions and have a prototype similar to
48the following:
49
50@ifset is-C
51@example
52rtems_isr user_isr(
53  rtems_vector_number vector
54);
55@end example
56@end ifset
57
58@ifset is-Ada
59@example
60procedure User_ISR (
61  vector : in     RTEMS.Vector_Number
62);
63@end example
64@end ifset
65
66The vector number argument is provided by RTEMS to
67allow the application to identify the interrupt source.  This
68could be used to allow a single routine to service interrupts
69from multiple instances of the same device.  For example, a
70single routine could service interrupts from multiple serial
71ports and use the vector number to identify which port requires
72servicing.
73
74To minimize the masking of lower or equal priority
75level interrupts, the ISR should perform the minimum actions
76required to service the interrupt.  Other non-essential actions
77should be handled by application tasks.  Once the user's ISR has
78completed, it returns control to the RTEMS interrupt manager
79which will perform task dispatching and restore the registers
80saved before the ISR was invoked.
81
82The RTEMS interrupt manager guarantees that proper
83task scheduling and dispatching are performed at the conclusion
84of an ISR.  A system call made by the ISR may have readied a
85task of higher priority than the interrupted task.  Therefore,
86when the ISR completes, the postponed dispatch processing must
87be performed.  No dispatch processing is performed as part of
88directives which have been invoked by an ISR.
89
90Applications must adhere to the following rule if
91proper task scheduling and dispatching is to be performed:
92
93@itemize @b{ }
94
95@item @b{The interrupt manager must be used for all ISRs which
96may be interrupted by the highest priority ISR which invokes an
97RTEMS directive.}
98
99@end itemize
100
101
102Consider a processor which allows a numerically low
103interrupt level to interrupt a numerically greater interrupt
104level.  In this example, if an RTEMS directive is used in a
105level 4 ISR, then all ISRs which execute at levels 0 through 4
106must use the interrupt manager.
107
108Interrupts are nested whenever an interrupt occurs
109during the execution of another ISR.  RTEMS supports efficient
110interrupt nesting by allowing the nested ISRs to terminate
111without performing any dispatch processing.  Only when the
112outermost ISR terminates will the postponed dispatching occur.
113
114@subsection RTEMS Interrupt Levels
115
116Many processors support multiple interrupt levels or
117priorities.  The exact number of interrupt levels is processor
118dependent.  RTEMS internally supports 256 interrupt levels which
119are mapped to the processor's interrupt levels.  For specific
120information on the mapping between RTEMS and the target
121processor's interrupt levels, refer to the Interrupt Processing
122chapter of the Applications Supplement document for a specific
123target processor.
124
125@subsection Disabling of Interrupts by RTEMS
126
127During the execution of directive calls, critical
128sections of code may be executed.  When these sections are
129encountered, RTEMS disables all maskable interrupts before the
130execution of the section and restores them to the previous level
131upon completion of the section.  RTEMS has been optimized to
132insure that interrupts are disabled for a minimum length of
133time.  The maximum length of time interrupts are disabled by
134RTEMS is processor dependent and is detailed in the Timing
135Specification chapter of the Applications Supplement document
136for a specific target processor.
137
138Non-maskable interrupts (NMI) cannot be disabled, and
139ISRs which execute at this level MUST NEVER issue RTEMS system
140calls.  If a directive is invoked, unpredictable results may
141occur due to the inability of RTEMS to protect its critical
142sections.  However, ISRs that make no system calls may safely
143execute as non-maskable interrupts.
144
145@section Operations
146
147@subsection Establishing an ISR
148
149The @code{@value{DIRPREFIX}interrupt_catch}
150directive establishes an ISR for
151the system.  The address of the ISR and its associated CPU
152vector number are specified to this directive.  This directive
153installs the RTEMS interrupt wrapper in the processor's
154Interrupt Vector Table and the address of the user's ISR in the
155RTEMS' Vector Table.  This directive returns the previous
156contents of the specified vector in the RTEMS' Vector Table.
157
158@subsection Directives Allowed from an ISR
159
160Using the interrupt manager insures that RTEMS knows
161when a directive is being called from an ISR.  The ISR may then
162use system calls to synchronize itself with an application task.
163The synchronization may involve messages, events or signals
164being passed by the ISR to the desired task.  Directives invoked
165by an ISR must operate only on objects which reside on the local
166node.  The following is a list of RTEMS system calls that may be
167made from an ISR:
168
169@itemize @bullet
170@item Task Management
171
172@itemize -
173@item task_get_note, task_set_note, task_suspend, task_resume
174@end itemize
175
176@item Clock Management
177
178@itemize -
179@item clock_get, clock_tick
180@end itemize
181
182@item Message, Event, and Signal Management
183
184@itemize -
185@item message_queue_send, message_queue_urgent
186@item event_send
187@item signal_send
188@end itemize
189
190@item Semaphore Management
191
192@itemize -
193@item semaphore_release
194@end itemize
195
196@item Dual-Ported Memory Management
197
198@itemize -
199@item port_external_to_internal, port_internal_to_external
200@end itemize
201
202@item IO Management
203
204@itemize -
205@item io_initialize, io_open, io_close, io_read, io_write, io_control
206@end itemize
207
208@item Fatal Error Management
209
210@itemize -
211@item fatal_error_occurred
212@end itemize
213
214@item Multiprocessing
215
216@itemize -
217@item multiprocessing_announce
218@end itemize
219@end itemize
220
221@section Directives
222
223This section details the interrupt manager's
224directives.  A subsection is dedicated to each of this manager's
225directives and describes the calling sequence, related
226constants, usage, and status codes.
227
228@page
229@subsection INTERRUPT_CATCH - Establish an ISR
230
231@subheading CALLING SEQUENCE:
232
233@ifset is-C
234@c @findex rtems_interrupt_catch
235@example
236rtems_status_code rtems_interrupt_catch(
237  rtems_isr_entry      new_isr_handler,
238  rtems_vector_number  vector,
239  rtems_isr_entry     *old_isr_handler
240);
241@end example
242@end ifset
243
244@ifset is-Ada
245@example
246procedure Interrupt_Catch (
247   New_ISR_handler : in     RTEMS.Address;
248   Vector          : in     RTEMS.Vector_Number;
249   Old_ISR_Handler :    out RTEMS.Address;
250   Result          :    out RTEMS.Status_Codes
251);
252@end example
253@end ifset
254
255@subheading DIRECTIVE STATUS CODES:
256@code{@value{RPREFIX}SUCCESSFUL} - ISR established successfully@*
257@code{@value{RPREFIX}INVALID_NUMBER} - illegal vector number@*
258@code{@value{RPREFIX}INVALID_ADDRESS} - illegal ISR entry point or invalid old_isr_handler
259
260@subheading DESCRIPTION:
261
262This directive establishes an interrupt service
263routine (ISR) for the specified interrupt vector number.  The
264@code{new_isr_handler} parameter specifies the entry point of the ISR.
265The entry point of the previous ISR for the specified vector is
266returned in @code{old_isr_handler}.
267
268@subheading NOTES:
269
270This directive will not cause the calling task to be preempted.
271
272@page
273@subsection INTERRUPT_DISABLE - Disable Interrupts
274
275@subheading CALLING SEQUENCE:
276
277@ifset is-C
278@c @findex rtems_interrupt_disable
279@example
280void rtems_interrupt_disable(
281  rtems_isr_level  level
282);
283@end example
284@end ifset
285
286@ifset is-Ada
287@example
288function Interrupt_Disable
289return RTEMS.ISR_Level;
290@end example
291@end ifset
292
293@subheading DIRECTIVE STATUS CODES:
294
295NONE
296
297@subheading DESCRIPTION:
298
299This directive disables all maskable interrupts and returns
300the previous @code{level}.  A later invocation of the
301@code{@value{DIRPREFIX}interrupt_enable} directive should be used to
302restore the interrupt level.
303
304@subheading NOTES:
305
306This directive will not cause the calling task to be preempted.
307
308@ifset is-C
309@b{This directive is implemented as a macro which modifies the @code{level}
310parameter.}
311@end ifset
312
313@page
314@subsection INTERRUPT_ENABLE - Enable Interrupts
315
316@subheading CALLING SEQUENCE:
317
318@ifset is-C
319@c @findex rtems_interrupt_enable
320@example
321void rtems_interrupt_enable(
322  rtems_isr_level  level
323);
324@end example
325@end ifset
326
327@ifset is-Ada
328@example
329procedure Interrupt_Enable (
330   Level : in     RTEMS.ISR_Level
331);
332@end example
333@end ifset
334
335@subheading DIRECTIVE STATUS CODES:
336
337NONE
338
339@subheading DESCRIPTION:
340
341This directive enables maskable interrupts to the @code{level}
342which was returned by a previous call to
343@code{@value{DIRPREFIX}interrupt_disable}.
344Immediately prior to invoking this directive, maskable interrupts should
345be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable}
346and will be enabled when this directive returns to the caller.
347
348@subheading NOTES:
349
350This directive will not cause the calling task to be preempted.
351
352
353@page
354@subsection INTERRUPT_FLASH - Flash Interrupts
355
356@subheading CALLING SEQUENCE:
357
358@ifset is-C
359@c @findex rtems_interrupt_flash
360@example
361void rtems_interrupt_flash(
362  rtems_isr_level level
363);
364@end example
365@end ifset
366
367@ifset is-Ada
368@example
369procedure Interrupt_Flash (
370   Level : in     RTEMS.ISR_Level
371);
372@end example
373@end ifset
374
375@subheading DIRECTIVE STATUS CODES:
376
377NONE
378
379@subheading DESCRIPTION:
380
381This directive temporarily enables maskable interrupts to the @code{level}
382which was returned by a previous call to
383@code{@value{DIRPREFIX}interrupt_disable}. 
384Immediately prior to invoking this directive, maskable interrupts should
385be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable}
386and will be redisabled when this directive returns to the caller.
387
388@subheading NOTES:
389
390This directive will not cause the calling task to be preempted.
391
392@page
393@subsection INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
394
395@subheading CALLING SEQUENCE:
396
397@ifset is-C
398@c @findex rtems_interrupt_is_in_progress
399@example
400rtems_boolean rtems_interrupt_is_in_progress( void );
401@end example
402@end ifset
403
404@ifset is-Ada
405@example
406function Interrupt_Is_In_Progress
407return RTEMS.Boolean;
408@end example
409@end ifset
410
411@subheading DIRECTIVE STATUS CODES:
412
413NONE
414
415@subheading DESCRIPTION:
416
417This directive returns @code{TRUE} if the processor is currently
418servicing an interrupt and @code{FALSE} otherwise.  A return value
419of @code{TRUE} indicates that the caller is an interrupt service
420routine, @b{NOT} a task.  The directives available to an interrupt
421service routine are restricted.
422
423@subheading NOTES:
424
425This directive will not cause the calling task to be preempted.
426
Note: See TracBrowser for help on using the repository browser.