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