1 | @c |
---|
2 | @c COPYRIGHT (c) 1996. |
---|
3 | @c On-Line Applications Research Corporation (OAR). |
---|
4 | @c All rights reserved. |
---|
5 | @c |
---|
6 | |
---|
7 | @ifinfo |
---|
8 | @node Interrupt Manager, Interrupt Manager Introduction, TASK_WAKE_WHEN - Wake up when specified, Top |
---|
9 | @end ifinfo |
---|
10 | @chapter Interrupt Manager |
---|
11 | @ifinfo |
---|
12 | @menu |
---|
13 | * Interrupt Manager Introduction:: |
---|
14 | * Interrupt Manager Background:: |
---|
15 | * Interrupt Manager Operations:: |
---|
16 | * Interrupt Manager Directives:: |
---|
17 | @end menu |
---|
18 | @end ifinfo |
---|
19 | |
---|
20 | @ifinfo |
---|
21 | @node Interrupt Manager Introduction, Interrupt Manager Background, Interrupt Manager, Interrupt Manager |
---|
22 | @end ifinfo |
---|
23 | @section Introduction |
---|
24 | |
---|
25 | Any real-time executive must provide a mechanism for |
---|
26 | quick response to externally generated interrupts to satisfy the |
---|
27 | critical time constraints of the application. The interrupt |
---|
28 | manager provides this mechanism for RTEMS. This manager permits |
---|
29 | quick interrupt response times by providing the critical ability |
---|
30 | to alter task execution which allows a task to be preempted upon |
---|
31 | exit from an ISR. The interrupt manager includes the following |
---|
32 | directive: |
---|
33 | |
---|
34 | @itemize @bullet |
---|
35 | @item @code{interrupt_catch} - Establish an ISR |
---|
36 | @end itemize |
---|
37 | |
---|
38 | @ifinfo |
---|
39 | @node Interrupt Manager Background, Processing an Interrupt, Interrupt Manager Introduction, Interrupt Manager |
---|
40 | @end ifinfo |
---|
41 | @section Background |
---|
42 | @ifinfo |
---|
43 | @menu |
---|
44 | * Processing an Interrupt:: |
---|
45 | * RTEMS Interrupt Levels:: |
---|
46 | * Disabling of Interrupts by RTEMS:: |
---|
47 | @end menu |
---|
48 | @end ifinfo |
---|
49 | |
---|
50 | @ifinfo |
---|
51 | @node Processing an Interrupt, RTEMS Interrupt Levels, Interrupt Manager Background, Interrupt Manager Background |
---|
52 | @end ifinfo |
---|
53 | @subsection Processing an Interrupt |
---|
54 | |
---|
55 | The interrupt manager allows the application to |
---|
56 | connect a function to a hardware interrupt vector. When an |
---|
57 | interrupt occurs, the processor will automatically vector to |
---|
58 | RTEMS. RTEMS saves and restores all registers which are not |
---|
59 | preserved by the normal @value{RTEMS-LANGUAGE} calling convention |
---|
60 | for the target |
---|
61 | processor and invokes the user's ISR. The user's ISR is |
---|
62 | responsible for processing the interrupt, clearing the interrupt |
---|
63 | if necessary, and device specific manipulation. |
---|
64 | |
---|
65 | The interrupt_catch directive connects a procedure to |
---|
66 | an interrupt vector. The interrupt service routine is assumed |
---|
67 | to abide by these conventions and have a prototype similar to |
---|
68 | the following: |
---|
69 | |
---|
70 | @ifset is-C |
---|
71 | @example |
---|
72 | rtems_isr user_isr( |
---|
73 | rtems_vector_number vector |
---|
74 | ); |
---|
75 | @end example |
---|
76 | @end ifset |
---|
77 | |
---|
78 | @ifset is-Ada |
---|
79 | @example |
---|
80 | procedure User_ISR ( |
---|
81 | vector : in RTEMS.Vector_Number |
---|
82 | ); |
---|
83 | @end example |
---|
84 | @end ifset |
---|
85 | |
---|
86 | The vector number argument is provided by RTEMS to |
---|
87 | allow the application to identify the interrupt source. This |
---|
88 | could be used to allow a single routine to service interrupts |
---|
89 | from multiple instances of the same device. For example, a |
---|
90 | single routine could service interrupts from multiple serial |
---|
91 | ports and use the vector number to identify which port requires |
---|
92 | servicing. |
---|
93 | |
---|
94 | To minimize the masking of lower or equal priority |
---|
95 | level interrupts, the ISR should perform the minimum actions |
---|
96 | required to service the interrupt. Other non-essential actions |
---|
97 | should be handled by application tasks. Once the user's ISR has |
---|
98 | completed, it returns control to the RTEMS interrupt manager |
---|
99 | which will perform task dispatching and restore the registers |
---|
100 | saved before the ISR was invoked. |
---|
101 | |
---|
102 | The RTEMS interrupt manager guarantees that proper |
---|
103 | task scheduling and dispatching are performed at the conclusion |
---|
104 | of an ISR. A system call made by the ISR may have readied a |
---|
105 | task of higher priority than the interrupted task. Therefore, |
---|
106 | when the ISR completes, the postponed dispatch processing must |
---|
107 | be performed. No dispatch processing is performed as part of |
---|
108 | directives which have been invoked by an ISR. |
---|
109 | |
---|
110 | Applications must adhere to the following rule if |
---|
111 | proper task scheduling and dispatching is to be performed: |
---|
112 | |
---|
113 | @itemize @b{ } |
---|
114 | |
---|
115 | @item @b{The interrupt manager must be used for all ISRs which |
---|
116 | may be interrupted by the highest priority ISR which invokes an |
---|
117 | RTEMS directive.} |
---|
118 | |
---|
119 | @end itemize |
---|
120 | |
---|
121 | |
---|
122 | Consider a processor which allows a numerically low |
---|
123 | interrupt level to interrupt a numerically greater interrupt |
---|
124 | level. In this example, if an RTEMS directive is used in a |
---|
125 | level 4 ISR, then all ISRs which execute at levels 0 through 4 |
---|
126 | must use the interrupt manager. |
---|
127 | |
---|
128 | Interrupts are nested whenever an interrupt occurs |
---|
129 | during the execution of another ISR. RTEMS supports efficient |
---|
130 | interrupt nesting by allowing the nested ISRs to terminate |
---|
131 | without performing any dispatch processing. Only when the |
---|
132 | outermost ISR terminates will the postponed dispatching occur. |
---|
133 | |
---|
134 | @ifinfo |
---|
135 | @node RTEMS Interrupt Levels, Disabling of Interrupts by RTEMS, Processing an Interrupt, Interrupt Manager Background |
---|
136 | @end ifinfo |
---|
137 | @subsection RTEMS Interrupt Levels |
---|
138 | |
---|
139 | Many processors support multiple interrupt levels or |
---|
140 | priorities. The exact number of interrupt levels is processor |
---|
141 | dependent. RTEMS internally supports 256 interrupt levels which |
---|
142 | are mapped to the processor's interrupt levels. For specific |
---|
143 | information on the mapping between RTEMS and the target |
---|
144 | processor's interrupt levels, refer to the Interrupt Processing |
---|
145 | chapter of the C Applications Supplement document for a specific |
---|
146 | target processor. |
---|
147 | |
---|
148 | @ifinfo |
---|
149 | @node Disabling of Interrupts by RTEMS, Interrupt Manager Operations, RTEMS Interrupt Levels, Interrupt Manager Background |
---|
150 | @end ifinfo |
---|
151 | @subsection Disabling of Interrupts by RTEMS |
---|
152 | |
---|
153 | During the execution of directive calls, critical |
---|
154 | sections of code may be executed. When these sections are |
---|
155 | encountered, RTEMS disables all maskable interrupts before the |
---|
156 | execution of the section and restores them to the previous level |
---|
157 | upon completion of the section. RTEMS has been optimized to |
---|
158 | insure that interrupts are disabled for a minimum length of |
---|
159 | time. The maximum length of time interrupts are disabled by |
---|
160 | RTEMS is processor dependent and is detailed in the Timing |
---|
161 | Specification chapter of the C Applications Supplement document |
---|
162 | for a specific target processor. |
---|
163 | |
---|
164 | Non-maskable interrupts (NMI) cannot be disabled, and |
---|
165 | ISRs which execute at this level MUST NEVER issue RTEMS system |
---|
166 | calls. If a directive is invoked, unpredictable results may |
---|
167 | occur due to the inability of RTEMS to protect its critical |
---|
168 | sections. However, ISRs that make no system calls may safely |
---|
169 | execute as non-maskable interrupts. |
---|
170 | |
---|
171 | @ifinfo |
---|
172 | @node Interrupt Manager Operations, Establishing an ISR, Disabling of Interrupts by RTEMS, Interrupt Manager |
---|
173 | @end ifinfo |
---|
174 | @section Operations |
---|
175 | @ifinfo |
---|
176 | @menu |
---|
177 | * Establishing an ISR:: |
---|
178 | * Directives Allowed from an ISR:: |
---|
179 | @end menu |
---|
180 | @end ifinfo |
---|
181 | |
---|
182 | @ifinfo |
---|
183 | @node Establishing an ISR, Directives Allowed from an ISR, Interrupt Manager Operations, Interrupt Manager Operations |
---|
184 | @end ifinfo |
---|
185 | @subsection Establishing an ISR |
---|
186 | |
---|
187 | The interrupt_catch directive establishes an ISR for |
---|
188 | the system. The address of the ISR and its associated CPU |
---|
189 | vector number are specified to this directive. This directive |
---|
190 | installs the RTEMS interrupt wrapper in the processor's |
---|
191 | Interrupt Vector Table and the address of the user's ISR in the |
---|
192 | RTEMS' Vector Table. This directive returns the previous |
---|
193 | contents of the specified vector in the RTEMS' Vector Table. |
---|
194 | |
---|
195 | @ifinfo |
---|
196 | @node Directives Allowed from an ISR, Interrupt Manager Directives, Establishing an ISR, Interrupt Manager Operations |
---|
197 | @end ifinfo |
---|
198 | @subsection Directives Allowed from an ISR |
---|
199 | |
---|
200 | Using the interrupt manager insures that RTEMS knows |
---|
201 | when a directive is being called from an ISR. The ISR may then |
---|
202 | use system calls to synchronize itself with an application task. |
---|
203 | The synchronization may involve messages, events or signals |
---|
204 | being passed by the ISR to the desired task. Directives invoked |
---|
205 | by an ISR must operate only on objects which reside on the local |
---|
206 | node. The following is a list of RTEMS system calls that may be |
---|
207 | made from an ISR: |
---|
208 | |
---|
209 | @itemize @bullet |
---|
210 | @item Task Management |
---|
211 | |
---|
212 | @itemize - |
---|
213 | @item task_get_note, task_set_note, task_suspend, task_resume |
---|
214 | @end itemize |
---|
215 | |
---|
216 | @item Clock Management |
---|
217 | |
---|
218 | @itemize - |
---|
219 | @item clock_get, clock_tick |
---|
220 | @end itemize |
---|
221 | |
---|
222 | @item Message, Event, and Signal Management |
---|
223 | |
---|
224 | @itemize - |
---|
225 | @item message_queue_send, message_queue_urgent |
---|
226 | @item event_send |
---|
227 | @item signal_send |
---|
228 | @end itemize |
---|
229 | |
---|
230 | @item Semaphore Management |
---|
231 | |
---|
232 | @itemize - |
---|
233 | @item semaphore_release |
---|
234 | @end itemize |
---|
235 | |
---|
236 | @item Dual-Ported Memory Management |
---|
237 | |
---|
238 | @itemize - |
---|
239 | @item port_external_to_internal, port_internal_to_external |
---|
240 | @end itemize |
---|
241 | |
---|
242 | @item IO Management |
---|
243 | |
---|
244 | @itemize - |
---|
245 | @item io_initialize, io_open, io_close, io_read, io_write, io_control |
---|
246 | @end itemize |
---|
247 | |
---|
248 | @item Fatal Error Management |
---|
249 | |
---|
250 | @itemize - |
---|
251 | @item fatal_error_occurred |
---|
252 | @end itemize |
---|
253 | |
---|
254 | @item Multiprocessing |
---|
255 | |
---|
256 | @itemize - |
---|
257 | @item multiprocessing_announce |
---|
258 | @end itemize |
---|
259 | @end itemize |
---|
260 | |
---|
261 | @ifinfo |
---|
262 | @node Interrupt Manager Directives, INTERRUPT_CATCH - Establish an ISR, Directives Allowed from an ISR, Interrupt Manager |
---|
263 | @end ifinfo |
---|
264 | @section Directives |
---|
265 | @ifinfo |
---|
266 | @menu |
---|
267 | * INTERRUPT_CATCH - Establish an ISR:: |
---|
268 | @end menu |
---|
269 | @end ifinfo |
---|
270 | |
---|
271 | This section details the interrupt manager's |
---|
272 | directives. A subsection is dedicated to each of this manager's |
---|
273 | directives and describes the calling sequence, related |
---|
274 | constants, usage, and status codes. |
---|
275 | |
---|
276 | @page |
---|
277 | @ifinfo |
---|
278 | @node INTERRUPT_CATCH - Establish an ISR, Clock Manager, Interrupt Manager Directives, Interrupt Manager Directives |
---|
279 | @end ifinfo |
---|
280 | @subsection INTERRUPT_CATCH - Establish an ISR |
---|
281 | |
---|
282 | @subheading CALLING SEQUENCE: |
---|
283 | |
---|
284 | @ifset is-C |
---|
285 | @example |
---|
286 | rtems_status_code rtems_interrupt_catch( |
---|
287 | rtems_isr_entry new_isr_handler, |
---|
288 | rtems_vector_number vector, |
---|
289 | rtems_isr_entry *old_isr_handler |
---|
290 | ); |
---|
291 | @end example |
---|
292 | @end ifset |
---|
293 | |
---|
294 | @ifset is-Ada |
---|
295 | @example |
---|
296 | procedure Interrupt_Catch ( |
---|
297 | New_ISR_handler : in RTEMS.Address; |
---|
298 | Vector : in RTEMS.Vector_Number; |
---|
299 | Old_ISR_Handler : out RTEMS.Address; |
---|
300 | Result : out RTEMS.Status_Codes |
---|
301 | ); |
---|
302 | @end example |
---|
303 | @end ifset |
---|
304 | |
---|
305 | @subheading DIRECTIVE STATUS CODES: |
---|
306 | @code{SUCCESSFUL} - ISR established successfully@* |
---|
307 | @code{INVALID_NUMBER} - illegal vector number@* |
---|
308 | @code{INVALID_ADDRESS} - illegal ISR entry point |
---|
309 | |
---|
310 | @subheading DESCRIPTION: |
---|
311 | |
---|
312 | This directive establishes an interrupt service |
---|
313 | routine (ISR) for the specified interrupt vector number. The |
---|
314 | new_isr_handler parameter specifies the entry point of the ISR. |
---|
315 | The entry point of the previous ISR for the specified vector is |
---|
316 | returned in old_isr_handler. |
---|
317 | |
---|
318 | @subheading NOTES: |
---|
319 | |
---|
320 | This directive will not cause the calling task to be |
---|
321 | preempted. |
---|
322 | |
---|