source: rtems/doc/user/intr.t @ 0c7aab8

4.104.114.84.95
Last change on this file since 0c7aab8 was 0c7aab8, checked in by Joel Sherrill <joel.sherrill@…>, on 10/01/99 at 18:05:42

Changed rtems_isr_level to rtems_interrupt_level per Chris Johns'
<ccj@…> suggestion.

  • Property mode set to 100644
File size: 12.0 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
268To release an interrupt vector, pass the old handler's address obtained
269when the vector was first capture.
270
271@ifset is-C
272Passing a NULL pointer as the @code{old_handler} address and this parameter
273will be ignored.
274@endif
275
276@subheading NOTES:
277
278This directive will not cause the calling task to be preempted.
279
280@page
281@subsection INTERRUPT_DISABLE - Disable Interrupts
282
283@subheading CALLING SEQUENCE:
284
285@ifset is-C
286@c @findex rtems_interrupt_disable
287@example
288void rtems_interrupt_disable(
289  rtems_interrupt_level  level
290);
291
292/* this is implemented as a macro and sets level as a side-effect */
293@end example
294@end ifset
295
296@ifset is-Ada
297@example
298function Interrupt_Disable
299return RTEMS.ISR_Level;
300@end example
301@end ifset
302
303@subheading DIRECTIVE STATUS CODES:
304
305NONE
306
307@subheading DESCRIPTION:
308
309This directive disables all maskable interrupts and returns
310the previous @code{level}.  A later invocation of the
311@code{@value{DIRPREFIX}interrupt_enable} directive should be used to
312restore the interrupt level.
313
314@subheading NOTES:
315
316This directive will not cause the calling task to be preempted.
317
318@ifset is-C
319@b{This directive is implemented as a macro which modifies the @code{level}
320parameter.}
321@end ifset
322
323@page
324@subsection INTERRUPT_ENABLE - Enable Interrupts
325
326@subheading CALLING SEQUENCE:
327
328@ifset is-C
329@c @findex rtems_interrupt_enable
330@example
331void rtems_interrupt_enable(
332  rtems_interrupt_level  level
333);
334@end example
335@end ifset
336
337@ifset is-Ada
338@example
339procedure Interrupt_Enable (
340   Level : in     RTEMS.ISR_Level
341);
342@end example
343@end ifset
344
345@subheading DIRECTIVE STATUS CODES:
346
347NONE
348
349@subheading DESCRIPTION:
350
351This directive enables maskable interrupts to the @code{level}
352which was returned by a previous call to
353@code{@value{DIRPREFIX}interrupt_disable}.
354Immediately prior to invoking this directive, maskable interrupts should
355be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable}
356and will be enabled when this directive returns to the caller.
357
358@subheading NOTES:
359
360This directive will not cause the calling task to be preempted.
361
362
363@page
364@subsection INTERRUPT_FLASH - Flash Interrupts
365
366@subheading CALLING SEQUENCE:
367
368@ifset is-C
369@c @findex rtems_interrupt_flash
370@example
371void rtems_interrupt_flash(
372  rtems_interrupt_level level
373);
374@end example
375@end ifset
376
377@ifset is-Ada
378@example
379procedure Interrupt_Flash (
380   Level : in     RTEMS.ISR_Level
381);
382@end example
383@end ifset
384
385@subheading DIRECTIVE STATUS CODES:
386
387NONE
388
389@subheading DESCRIPTION:
390
391This directive temporarily enables maskable interrupts to the @code{level}
392which was returned by a previous call to
393@code{@value{DIRPREFIX}interrupt_disable}. 
394Immediately prior to invoking this directive, maskable interrupts should
395be disabled by a call to @code{@value{DIRPREFIX}interrupt_disable}
396and will be redisabled when this directive returns to the caller.
397
398@subheading NOTES:
399
400This directive will not cause the calling task to be preempted.
401
402@page
403@subsection INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
404
405@subheading CALLING SEQUENCE:
406
407@ifset is-C
408@c @findex rtems_interrupt_is_in_progress
409@example
410rtems_boolean rtems_interrupt_is_in_progress( void );
411@end example
412@end ifset
413
414@ifset is-Ada
415@example
416function Interrupt_Is_In_Progress
417return RTEMS.Boolean;
418@end example
419@end ifset
420
421@subheading DIRECTIVE STATUS CODES:
422
423NONE
424
425@subheading DESCRIPTION:
426
427This directive returns @code{TRUE} if the processor is currently
428servicing an interrupt and @code{FALSE} otherwise.  A return value
429of @code{TRUE} indicates that the caller is an interrupt service
430routine, @b{NOT} a task.  The directives available to an interrupt
431service routine are restricted.
432
433@subheading NOTES:
434
435This directive will not cause the calling task to be preempted.
436
Note: See TracBrowser for help on using the repository browser.