diff options
author | Thomas Gleixner <tglx@linutronix.de> | 2006-06-29 05:24:47 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@g5.osdl.org> | 2006-06-29 13:26:23 -0400 |
commit | 11c869eaf1a9c97ef273f824a697fac017d68286 (patch) | |
tree | 03be0b39ab239985008d7a80960a232661b870d5 | |
parent | 77a5afecdb15e65034ab8390b46b824c186c62a8 (diff) |
[PATCH] genirq: doc: add design documentation
Add docbook file - includes API documentation.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Ingo Molnar <mingo@elte.hu>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
-rw-r--r-- | Documentation/DocBook/Makefile | 3 | ||||
-rw-r--r-- | Documentation/DocBook/genericirq.tmpl | 474 |
2 files changed, 476 insertions, 1 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 5a2882d275ba..66e1cf733571 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile | |||
@@ -10,7 +10,8 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ | |||
10 | kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ | 10 | kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ |
11 | procfs-guide.xml writing_usb_driver.xml \ | 11 | procfs-guide.xml writing_usb_driver.xml \ |
12 | kernel-api.xml journal-api.xml lsm.xml usb.xml \ | 12 | kernel-api.xml journal-api.xml lsm.xml usb.xml \ |
13 | gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml | 13 | gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ |
14 | genericirq.xml | ||
14 | 15 | ||
15 | ### | 16 | ### |
16 | # The build process is as follows (targets): | 17 | # The build process is as follows (targets): |
diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl new file mode 100644 index 000000000000..0f4a4b6321e4 --- /dev/null +++ b/Documentation/DocBook/genericirq.tmpl | |||
@@ -0,0 +1,474 @@ | |||
1 | <?xml version="1.0" encoding="UTF-8"?> | ||
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | ||
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | ||
4 | |||
5 | <book id="Generic-IRQ-Guide"> | ||
6 | <bookinfo> | ||
7 | <title>Linux generic IRQ handling</title> | ||
8 | |||
9 | <authorgroup> | ||
10 | <author> | ||
11 | <firstname>Thomas</firstname> | ||
12 | <surname>Gleixner</surname> | ||
13 | <affiliation> | ||
14 | <address> | ||
15 | <email>tglx@linutronix.de</email> | ||
16 | </address> | ||
17 | </affiliation> | ||
18 | </author> | ||
19 | <author> | ||
20 | <firstname>Ingo</firstname> | ||
21 | <surname>Molnar</surname> | ||
22 | <affiliation> | ||
23 | <address> | ||
24 | <email>mingo@elte.hu</email> | ||
25 | </address> | ||
26 | </affiliation> | ||
27 | </author> | ||
28 | </authorgroup> | ||
29 | |||
30 | <copyright> | ||
31 | <year>2005-2006</year> | ||
32 | <holder>Thomas Gleixner</holder> | ||
33 | </copyright> | ||
34 | <copyright> | ||
35 | <year>2005-2006</year> | ||
36 | <holder>Ingo Molnar</holder> | ||
37 | </copyright> | ||
38 | |||
39 | <legalnotice> | ||
40 | <para> | ||
41 | This documentation is free software; you can redistribute | ||
42 | it and/or modify it under the terms of the GNU General Public | ||
43 | License version 2 as published by the Free Software Foundation. | ||
44 | </para> | ||
45 | |||
46 | <para> | ||
47 | This program is distributed in the hope that it will be | ||
48 | useful, but WITHOUT ANY WARRANTY; without even the implied | ||
49 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | ||
50 | See the GNU General Public License for more details. | ||
51 | </para> | ||
52 | |||
53 | <para> | ||
54 | You should have received a copy of the GNU General Public | ||
55 | License along with this program; if not, write to the Free | ||
56 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | ||
57 | MA 02111-1307 USA | ||
58 | </para> | ||
59 | |||
60 | <para> | ||
61 | For more details see the file COPYING in the source | ||
62 | distribution of Linux. | ||
63 | </para> | ||
64 | </legalnotice> | ||
65 | </bookinfo> | ||
66 | |||
67 | <toc></toc> | ||
68 | |||
69 | <chapter id="intro"> | ||
70 | <title>Introduction</title> | ||
71 | <para> | ||
72 | The generic interrupt handling layer is designed to provide a | ||
73 | complete abstraction of interrupt handling for device drivers. | ||
74 | It is able to handle all the different types of interrupt controller | ||
75 | hardware. Device drivers use generic API functions to request, enable, | ||
76 | disable and free interrupts. The drivers do not have to know anything | ||
77 | about interrupt hardware details, so they can be used on different | ||
78 | platforms without code changes. | ||
79 | </para> | ||
80 | <para> | ||
81 | This documentation is provided to developers who want to implement | ||
82 | an interrupt subsystem based for their architecture, with the help | ||
83 | of the generic IRQ handling layer. | ||
84 | </para> | ||
85 | </chapter> | ||
86 | |||
87 | <chapter id="rationale"> | ||
88 | <title>Rationale</title> | ||
89 | <para> | ||
90 | The original implementation of interrupt handling in Linux is using | ||
91 | the __do_IRQ() super-handler, which is able to deal with every | ||
92 | type of interrupt logic. | ||
93 | </para> | ||
94 | <para> | ||
95 | Originally, Russell King identified different types of handlers to | ||
96 | build a quite universal set for the ARM interrupt handler | ||
97 | implementation in Linux 2.5/2.6. He distinguished between: | ||
98 | <itemizedlist> | ||
99 | <listitem><para>Level type</para></listitem> | ||
100 | <listitem><para>Edge type</para></listitem> | ||
101 | <listitem><para>Simple type</para></listitem> | ||
102 | </itemizedlist> | ||
103 | In the SMP world of the __do_IRQ() super-handler another type | ||
104 | was identified: | ||
105 | <itemizedlist> | ||
106 | <listitem><para>Per CPU type</para></listitem> | ||
107 | </itemizedlist> | ||
108 | </para> | ||
109 | <para> | ||
110 | This split implementation of highlevel IRQ handlers allows us to | ||
111 | optimize the flow of the interrupt handling for each specific | ||
112 | interrupt type. This reduces complexity in that particular codepath | ||
113 | and allows the optimized handling of a given type. | ||
114 | </para> | ||
115 | <para> | ||
116 | The original general IRQ implementation used hw_interrupt_type | ||
117 | structures and their ->ack(), ->end() [etc.] callbacks to | ||
118 | differentiate the flow control in the super-handler. This leads to | ||
119 | a mix of flow logic and lowlevel hardware logic, and it also leads | ||
120 | to unnecessary code duplication: for example in i386, there is a | ||
121 | ioapic_level_irq and a ioapic_edge_irq irq-type which share many | ||
122 | of the lowlevel details but have different flow handling. | ||
123 | </para> | ||
124 | <para> | ||
125 | A more natural abstraction is the clean separation of the | ||
126 | 'irq flow' and the 'chip details'. | ||
127 | </para> | ||
128 | <para> | ||
129 | Analysing a couple of architecture's IRQ subsystem implementations | ||
130 | reveals that most of them can use a generic set of 'irq flow' | ||
131 | methods and only need to add the chip level specific code. | ||
132 | The separation is also valuable for (sub)architectures | ||
133 | which need specific quirks in the irq flow itself but not in the | ||
134 | chip-details - and thus provides a more transparent IRQ subsystem | ||
135 | design. | ||
136 | </para> | ||
137 | <para> | ||
138 | Each interrupt descriptor is assigned its own highlevel flow | ||
139 | handler, which is normally one of the generic | ||
140 | implementations. (This highlevel flow handler implementation also | ||
141 | makes it simple to provide demultiplexing handlers which can be | ||
142 | found in embedded platforms on various architectures.) | ||
143 | </para> | ||
144 | <para> | ||
145 | The separation makes the generic interrupt handling layer more | ||
146 | flexible and extensible. For example, an (sub)architecture can | ||
147 | use a generic irq-flow implementation for 'level type' interrupts | ||
148 | and add a (sub)architecture specific 'edge type' implementation. | ||
149 | </para> | ||
150 | <para> | ||
151 | To make the transition to the new model easier and prevent the | ||
152 | breakage of existing implementations, the __do_IRQ() super-handler | ||
153 | is still available. This leads to a kind of duality for the time | ||
154 | being. Over time the new model should be used in more and more | ||
155 | architectures, as it enables smaller and cleaner IRQ subsystems. | ||
156 | </para> | ||
157 | </chapter> | ||
158 | <chapter id="bugs"> | ||
159 | <title>Known Bugs And Assumptions</title> | ||
160 | <para> | ||
161 | None (knock on wood). | ||
162 | </para> | ||
163 | </chapter> | ||
164 | |||
165 | <chapter id="Abstraction"> | ||
166 | <title>Abstraction layers</title> | ||
167 | <para> | ||
168 | There are three main levels of abstraction in the interrupt code: | ||
169 | <orderedlist> | ||
170 | <listitem><para>Highlevel driver API</para></listitem> | ||
171 | <listitem><para>Highlevel IRQ flow handlers</para></listitem> | ||
172 | <listitem><para>Chiplevel hardware encapsulation</para></listitem> | ||
173 | </orderedlist> | ||
174 | </para> | ||
175 | <sect1> | ||
176 | <title>Interrupt control flow</title> | ||
177 | <para> | ||
178 | Each interrupt is described by an interrupt descriptor structure | ||
179 | irq_desc. The interrupt is referenced by an 'unsigned int' numeric | ||
180 | value which selects the corresponding interrupt decription structure | ||
181 | in the descriptor structures array. | ||
182 | The descriptor structure contains status information and pointers | ||
183 | to the interrupt flow method and the interrupt chip structure | ||
184 | which are assigned to this interrupt. | ||
185 | </para> | ||
186 | <para> | ||
187 | Whenever an interrupt triggers, the lowlevel arch code calls into | ||
188 | the generic interrupt code by calling desc->handle_irq(). | ||
189 | This highlevel IRQ handling function only uses desc->chip primitives | ||
190 | referenced by the assigned chip descriptor structure. | ||
191 | </para> | ||
192 | </sect1> | ||
193 | <sect1> | ||
194 | <title>Highlevel Driver API</title> | ||
195 | <para> | ||
196 | The highlevel Driver API consists of following functions: | ||
197 | <itemizedlist> | ||
198 | <listitem><para>request_irq()</para></listitem> | ||
199 | <listitem><para>free_irq()</para></listitem> | ||
200 | <listitem><para>disable_irq()</para></listitem> | ||
201 | <listitem><para>enable_irq()</para></listitem> | ||
202 | <listitem><para>disable_irq_nosync() (SMP only)</para></listitem> | ||
203 | <listitem><para>synchronize_irq() (SMP only)</para></listitem> | ||
204 | <listitem><para>set_irq_type()</para></listitem> | ||
205 | <listitem><para>set_irq_wake()</para></listitem> | ||
206 | <listitem><para>set_irq_data()</para></listitem> | ||
207 | <listitem><para>set_irq_chip()</para></listitem> | ||
208 | <listitem><para>set_irq_chip_data()</para></listitem> | ||
209 | </itemizedlist> | ||
210 | See the autogenerated function documentation for details. | ||
211 | </para> | ||
212 | </sect1> | ||
213 | <sect1> | ||
214 | <title>Highlevel IRQ flow handlers</title> | ||
215 | <para> | ||
216 | The generic layer provides a set of pre-defined irq-flow methods: | ||
217 | <itemizedlist> | ||
218 | <listitem><para>handle_level_irq</para></listitem> | ||
219 | <listitem><para>handle_edge_irq</para></listitem> | ||
220 | <listitem><para>handle_simple_irq</para></listitem> | ||
221 | <listitem><para>handle_percpu_irq</para></listitem> | ||
222 | </itemizedlist> | ||
223 | The interrupt flow handlers (either predefined or architecture | ||
224 | specific) are assigned to specific interrupts by the architecture | ||
225 | either during bootup or during device initialization. | ||
226 | </para> | ||
227 | <sect2> | ||
228 | <title>Default flow implementations</title> | ||
229 | <sect3> | ||
230 | <title>Helper functions</title> | ||
231 | <para> | ||
232 | The helper functions call the chip primitives and | ||
233 | are used by the default flow implementations. | ||
234 | The following helper functions are implemented (simplified excerpt): | ||
235 | <programlisting> | ||
236 | default_enable(irq) | ||
237 | { | ||
238 | desc->chip->unmask(irq); | ||
239 | } | ||
240 | |||
241 | default_disable(irq) | ||
242 | { | ||
243 | if (!delay_disable(irq)) | ||
244 | desc->chip->mask(irq); | ||
245 | } | ||
246 | |||
247 | default_ack(irq) | ||
248 | { | ||
249 | chip->ack(irq); | ||
250 | } | ||
251 | |||
252 | default_mask_ack(irq) | ||
253 | { | ||
254 | if (chip->mask_ack) { | ||
255 | chip->mask_ack(irq); | ||
256 | } else { | ||
257 | chip->mask(irq); | ||
258 | chip->ack(irq); | ||
259 | } | ||
260 | } | ||
261 | |||
262 | noop(irq) | ||
263 | { | ||
264 | } | ||
265 | |||
266 | </programlisting> | ||
267 | </para> | ||
268 | </sect3> | ||
269 | </sect2> | ||
270 | <sect2> | ||
271 | <title>Default flow handler implementations</title> | ||
272 | <sect3> | ||
273 | <title>Default Level IRQ flow handler</title> | ||
274 | <para> | ||
275 | handle_level_irq provides a generic implementation | ||
276 | for level-triggered interrupts. | ||
277 | </para> | ||
278 | <para> | ||
279 | The following control flow is implemented (simplified excerpt): | ||
280 | <programlisting> | ||
281 | desc->chip->start(); | ||
282 | handle_IRQ_event(desc->action); | ||
283 | desc->chip->end(); | ||
284 | </programlisting> | ||
285 | </para> | ||
286 | </sect3> | ||
287 | <sect3> | ||
288 | <title>Default Edge IRQ flow handler</title> | ||
289 | <para> | ||
290 | handle_edge_irq provides a generic implementation | ||
291 | for edge-triggered interrupts. | ||
292 | </para> | ||
293 | <para> | ||
294 | The following control flow is implemented (simplified excerpt): | ||
295 | <programlisting> | ||
296 | if (desc->status & running) { | ||
297 | desc->chip->hold(); | ||
298 | desc->status |= pending | masked; | ||
299 | return; | ||
300 | } | ||
301 | desc->chip->start(); | ||
302 | desc->status |= running; | ||
303 | do { | ||
304 | if (desc->status & masked) | ||
305 | desc->chip->enable(); | ||
306 | desc-status &= ~pending; | ||
307 | handle_IRQ_event(desc->action); | ||
308 | } while (status & pending); | ||
309 | desc-status &= ~running; | ||
310 | desc->chip->end(); | ||
311 | </programlisting> | ||
312 | </para> | ||
313 | </sect3> | ||
314 | <sect3> | ||
315 | <title>Default simple IRQ flow handler</title> | ||
316 | <para> | ||
317 | handle_simple_irq provides a generic implementation | ||
318 | for simple interrupts. | ||
319 | </para> | ||
320 | <para> | ||
321 | Note: The simple flow handler does not call any | ||
322 | handler/chip primitives. | ||
323 | </para> | ||
324 | <para> | ||
325 | The following control flow is implemented (simplified excerpt): | ||
326 | <programlisting> | ||
327 | handle_IRQ_event(desc->action); | ||
328 | </programlisting> | ||
329 | </para> | ||
330 | </sect3> | ||
331 | <sect3> | ||
332 | <title>Default per CPU flow handler</title> | ||
333 | <para> | ||
334 | handle_percpu_irq provides a generic implementation | ||
335 | for per CPU interrupts. | ||
336 | </para> | ||
337 | <para> | ||
338 | Per CPU interrupts are only available on SMP and | ||
339 | the handler provides a simplified version without | ||
340 | locking. | ||
341 | </para> | ||
342 | <para> | ||
343 | The following control flow is implemented (simplified excerpt): | ||
344 | <programlisting> | ||
345 | desc->chip->start(); | ||
346 | handle_IRQ_event(desc->action); | ||
347 | desc->chip->end(); | ||
348 | </programlisting> | ||
349 | </para> | ||
350 | </sect3> | ||
351 | </sect2> | ||
352 | <sect2> | ||
353 | <title>Quirks and optimizations</title> | ||
354 | <para> | ||
355 | The generic functions are intended for 'clean' architectures and chips, | ||
356 | which have no platform-specific IRQ handling quirks. If an architecture | ||
357 | needs to implement quirks on the 'flow' level then it can do so by | ||
358 | overriding the highlevel irq-flow handler. | ||
359 | </para> | ||
360 | </sect2> | ||
361 | <sect2> | ||
362 | <title>Delayed interrupt disable</title> | ||
363 | <para> | ||
364 | This per interrupt selectable feature, which was introduced by Russell | ||
365 | King in the ARM interrupt implementation, does not mask an interrupt | ||
366 | at the hardware level when disable_irq() is called. The interrupt is | ||
367 | kept enabled and is masked in the flow handler when an interrupt event | ||
368 | happens. This prevents losing edge interrupts on hardware which does | ||
369 | not store an edge interrupt event while the interrupt is disabled at | ||
370 | the hardware level. When an interrupt arrives while the IRQ_DISABLED | ||
371 | flag is set, then the interrupt is masked at the hardware level and | ||
372 | the IRQ_PENDING bit is set. When the interrupt is re-enabled by | ||
373 | enable_irq() the pending bit is checked and if it is set, the | ||
374 | interrupt is resent either via hardware or by a software resend | ||
375 | mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when | ||
376 | you want to use the delayed interrupt disable feature and your | ||
377 | hardware is not capable of retriggering an interrupt.) | ||
378 | The delayed interrupt disable can be runtime enabled, per interrupt, | ||
379 | by setting the IRQ_DELAYED_DISABLE flag in the irq_desc status field. | ||
380 | </para> | ||
381 | </sect2> | ||
382 | </sect1> | ||
383 | <sect1> | ||
384 | <title>Chiplevel hardware encapsulation</title> | ||
385 | <para> | ||
386 | The chip level hardware descriptor structure irq_chip | ||
387 | contains all the direct chip relevant functions, which | ||
388 | can be utilized by the irq flow implementations. | ||
389 | <itemizedlist> | ||
390 | <listitem><para>ack()</para></listitem> | ||
391 | <listitem><para>mask_ack() - Optional, recommended for performance</para></listitem> | ||
392 | <listitem><para>mask()</para></listitem> | ||
393 | <listitem><para>unmask()</para></listitem> | ||
394 | <listitem><para>retrigger() - Optional</para></listitem> | ||
395 | <listitem><para>set_type() - Optional</para></listitem> | ||
396 | <listitem><para>set_wake() - Optional</para></listitem> | ||
397 | </itemizedlist> | ||
398 | These primitives are strictly intended to mean what they say: ack means | ||
399 | ACK, masking means masking of an IRQ line, etc. It is up to the flow | ||
400 | handler(s) to use these basic units of lowlevel functionality. | ||
401 | </para> | ||
402 | </sect1> | ||
403 | </chapter> | ||
404 | |||
405 | <chapter id="doirq"> | ||
406 | <title>__do_IRQ entry point</title> | ||
407 | <para> | ||
408 | The original implementation __do_IRQ() is an alternative entry | ||
409 | point for all types of interrupts. | ||
410 | </para> | ||
411 | <para> | ||
412 | This handler turned out to be not suitable for all | ||
413 | interrupt hardware and was therefore reimplemented with split | ||
414 | functionality for egde/level/simple/percpu interrupts. This is not | ||
415 | only a functional optimization. It also shortens code paths for | ||
416 | interrupts. | ||
417 | </para> | ||
418 | <para> | ||
419 | To make use of the split implementation, replace the call to | ||
420 | __do_IRQ by a call to desc->chip->handle_irq() and associate | ||
421 | the appropriate handler function to desc->chip->handle_irq(). | ||
422 | In most cases the generic handler implementations should | ||
423 | be sufficient. | ||
424 | </para> | ||
425 | </chapter> | ||
426 | |||
427 | <chapter id="locking"> | ||
428 | <title>Locking on SMP</title> | ||
429 | <para> | ||
430 | The locking of chip registers is up to the architecture that | ||
431 | defines the chip primitives. There is a chip->lock field that can be used | ||
432 | for serialization, but the generic layer does not touch it. The per-irq | ||
433 | structure is protected via desc->lock, by the generic layer. | ||
434 | </para> | ||
435 | </chapter> | ||
436 | <chapter id="structs"> | ||
437 | <title>Structures</title> | ||
438 | <para> | ||
439 | This chapter contains the autogenerated documentation of the structures which are | ||
440 | used in the generic IRQ layer. | ||
441 | </para> | ||
442 | !Iinclude/linux/irq.h | ||
443 | </chapter> | ||
444 | |||
445 | <chapter id="pubfunctions"> | ||
446 | <title>Public Functions Provided</title> | ||
447 | <para> | ||
448 | This chapter contains the autogenerated documentation of the kernel API functions | ||
449 | which are exported. | ||
450 | </para> | ||
451 | !Ekernel/irq/manage.c | ||
452 | !Ekernel/irq/chip.c | ||
453 | </chapter> | ||
454 | |||
455 | <chapter id="intfunctions"> | ||
456 | <title>Internal Functions Provided</title> | ||
457 | <para> | ||
458 | This chapter contains the autogenerated documentation of the internal functions. | ||
459 | </para> | ||
460 | !Ikernel/irq/handle.c | ||
461 | !Ikernel/irq/chip.c | ||
462 | </chapter> | ||
463 | |||
464 | <chapter id="credits"> | ||
465 | <title>Credits</title> | ||
466 | <para> | ||
467 | The following people have contributed to this document: | ||
468 | <orderedlist> | ||
469 | <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> | ||
470 | <listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem> | ||
471 | </orderedlist> | ||
472 | </para> | ||
473 | </chapter> | ||
474 | </book> | ||