[media] DocBook/demux.xml: Fix section references with dmx.h.xml
[linux-2.6.git] / Documentation / DocBook / uio-howto.tmpl
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []>
4
5 <book id="index">
6 <bookinfo>
7 <title>The Userspace I/O HOWTO</title>
8
9 <author>
10       <firstname>Hans-Jürgen</firstname>
11       <surname>Koch</surname>
12       <authorblurb><para>Linux developer, Linutronix</para></authorblurb>
13         <affiliation>
14         <orgname>
15                 <ulink url="http://www.linutronix.de">Linutronix</ulink>
16         </orgname>
17
18         <address>
19            <email>hjk@hansjkoch.de</email>
20         </address>
21     </affiliation>
22 </author>
23
24 <copyright>
25         <year>2006-2008</year>
26         <holder>Hans-Jürgen Koch.</holder>
27 </copyright>
28 <copyright>
29         <year>2009</year>
30         <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder>
31 </copyright>
32
33 <legalnotice>
34 <para>
35 This documentation is Free Software licensed under the terms of the
36 GPL version 2.
37 </para>
38 </legalnotice>
39
40 <pubdate>2006-12-11</pubdate>
41
42 <abstract>
43         <para>This HOWTO describes concept and usage of Linux kernel's
44                 Userspace I/O system.</para>
45 </abstract>
46
47 <revhistory>
48         <revision>
49         <revnumber>0.9</revnumber>
50         <date>2009-07-16</date>
51         <authorinitials>mst</authorinitials>
52         <revremark>Added generic pci driver
53                 </revremark>
54         </revision>
55         <revision>
56         <revnumber>0.8</revnumber>
57         <date>2008-12-24</date>
58         <authorinitials>hjk</authorinitials>
59         <revremark>Added name attributes in mem and portio sysfs directories.
60                 </revremark>
61         </revision>
62         <revision>
63         <revnumber>0.7</revnumber>
64         <date>2008-12-23</date>
65         <authorinitials>hjk</authorinitials>
66         <revremark>Added generic platform drivers and offset attribute.</revremark>
67         </revision>
68         <revision>
69         <revnumber>0.6</revnumber>
70         <date>2008-12-05</date>
71         <authorinitials>hjk</authorinitials>
72         <revremark>Added description of portio sysfs attributes.</revremark>
73         </revision>
74         <revision>
75         <revnumber>0.5</revnumber>
76         <date>2008-05-22</date>
77         <authorinitials>hjk</authorinitials>
78         <revremark>Added description of write() function.</revremark>
79         </revision>
80         <revision>
81         <revnumber>0.4</revnumber>
82         <date>2007-11-26</date>
83         <authorinitials>hjk</authorinitials>
84         <revremark>Removed section about uio_dummy.</revremark>
85         </revision>
86         <revision>
87         <revnumber>0.3</revnumber>
88         <date>2007-04-29</date>
89         <authorinitials>hjk</authorinitials>
90         <revremark>Added section about userspace drivers.</revremark>
91         </revision>
92         <revision>
93         <revnumber>0.2</revnumber>
94         <date>2007-02-13</date>
95         <authorinitials>hjk</authorinitials>
96         <revremark>Update after multiple mappings were added.</revremark>
97         </revision>
98         <revision>
99         <revnumber>0.1</revnumber>
100         <date>2006-12-11</date>
101         <authorinitials>hjk</authorinitials>
102         <revremark>First draft.</revremark>
103         </revision>
104 </revhistory>
105 </bookinfo>
106
107 <chapter id="aboutthisdoc">
108 <?dbhtml filename="aboutthis.html"?>
109 <title>About this document</title>
110
111 <sect1 id="translations">
112 <?dbhtml filename="translations.html"?>
113 <title>Translations</title>
114
115 <para>If you know of any translations for this document, or you are
116 interested in translating it, please email me
117 <email>hjk@hansjkoch.de</email>.
118 </para>
119 </sect1>
120
121 <sect1 id="preface">
122 <title>Preface</title>
123         <para>
124         For many types of devices, creating a Linux kernel driver is
125         overkill.  All that is really needed is some way to handle an
126         interrupt and provide access to the memory space of the
127         device.  The logic of controlling the device does not
128         necessarily have to be within the kernel, as the device does
129         not need to take advantage of any of other resources that the
130         kernel provides.  One such common class of devices that are
131         like this are for industrial I/O cards.
132         </para>
133         <para>
134         To address this situation, the userspace I/O system (UIO) was
135         designed.  For typical industrial I/O cards, only a very small
136         kernel module is needed. The main part of the driver will run in
137         user space. This simplifies development and reduces the risk of
138         serious bugs within a kernel module.
139         </para>
140         <para>
141         Please note that UIO is not an universal driver interface. Devices
142         that are already handled well by other kernel subsystems (like
143         networking or serial or USB) are no candidates for an UIO driver.
144         Hardware that is ideally suited for an UIO driver fulfills all of
145         the following:
146         </para>
147 <itemizedlist>
148 <listitem>
149         <para>The device has memory that can be mapped. The device can be
150         controlled completely by writing to this memory.</para>
151 </listitem>
152 <listitem>
153         <para>The device usually generates interrupts.</para>
154 </listitem>
155 <listitem>
156         <para>The device does not fit into one of the standard kernel
157         subsystems.</para>
158 </listitem>
159 </itemizedlist>
160 </sect1>
161
162 <sect1 id="thanks">
163 <title>Acknowledgments</title>
164         <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of
165         Linutronix, who have not only written most of the UIO code, but also
166         helped greatly writing this HOWTO by giving me all kinds of background
167         information.</para>
168 </sect1>
169
170 <sect1 id="feedback">
171 <title>Feedback</title>
172         <para>Find something wrong with this document? (Or perhaps something
173         right?) I would love to hear from you. Please email me at
174         <email>hjk@hansjkoch.de</email>.</para>
175 </sect1>
176 </chapter>
177
178 <chapter id="about">
179 <?dbhtml filename="about.html"?>
180 <title>About UIO</title>
181
182 <para>If you use UIO for your card's driver, here's what you get:</para>
183
184 <itemizedlist>
185 <listitem>
186         <para>only one small kernel module to write and maintain.</para>
187 </listitem>
188 <listitem>
189         <para>develop the main part of your driver in user space,
190         with all the tools and libraries you're used to.</para>
191 </listitem>
192 <listitem>
193         <para>bugs in your driver won't crash the kernel.</para>
194 </listitem>
195 <listitem>
196         <para>updates of your driver can take place without recompiling
197         the kernel.</para>
198 </listitem>
199 </itemizedlist>
200
201 <sect1 id="how_uio_works">
202 <title>How UIO works</title>
203         <para>
204         Each UIO device is accessed through a device file and several
205         sysfs attribute files. The device file will be called
206         <filename>/dev/uio0</filename> for the first device, and
207         <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename>
208         and so on for subsequent devices.
209         </para>
210
211         <para><filename>/dev/uioX</filename> is used to access the
212         address space of the card. Just use
213         <function>mmap()</function> to access registers or RAM
214         locations of your card.
215         </para>
216
217         <para>
218         Interrupts are handled by reading from
219         <filename>/dev/uioX</filename>. A blocking
220         <function>read()</function> from
221         <filename>/dev/uioX</filename> will return as soon as an
222         interrupt occurs. You can also use
223         <function>select()</function> on
224         <filename>/dev/uioX</filename> to wait for an interrupt. The
225         integer value read from <filename>/dev/uioX</filename>
226         represents the total interrupt count. You can use this number
227         to figure out if you missed some interrupts.
228         </para>
229         <para>
230         For some hardware that has more than one interrupt source internally,
231         but not separate IRQ mask and status registers, there might be
232         situations where userspace cannot determine what the interrupt source
233         was if the kernel handler disables them by writing to the chip's IRQ
234         register. In such a case, the kernel has to disable the IRQ completely
235         to leave the chip's register untouched. Now the userspace part can
236         determine the cause of the interrupt, but it cannot re-enable
237         interrupts. Another cornercase is chips where re-enabling interrupts
238         is a read-modify-write operation to a combined IRQ status/acknowledge
239         register. This would be racy if a new interrupt occurred
240         simultaneously.
241         </para>
242         <para>
243         To address these problems, UIO also implements a write() function. It
244         is normally not used and can be ignored for hardware that has only a
245         single interrupt source or has separate IRQ mask and status registers.
246         If you need it, however, a write to <filename>/dev/uioX</filename>
247         will call the <function>irqcontrol()</function> function implemented
248         by the driver. You have to write a 32-bit value that is usually either
249         0 or 1 to disable or enable interrupts. If a driver does not implement
250         <function>irqcontrol()</function>, <function>write()</function> will
251         return with <varname>-ENOSYS</varname>.
252         </para>
253
254         <para>
255         To handle interrupts properly, your custom kernel module can
256         provide its own interrupt handler. It will automatically be
257         called by the built-in handler.
258         </para>
259
260         <para>
261         For cards that don't generate interrupts but need to be
262         polled, there is the possibility to set up a timer that
263         triggers the interrupt handler at configurable time intervals.
264         This interrupt simulation is done by calling
265         <function>uio_event_notify()</function>
266         from the timer's event handler.
267         </para>
268
269         <para>
270         Each driver provides attributes that are used to read or write
271         variables. These attributes are accessible through sysfs
272         files.  A custom kernel driver module can add its own
273         attributes to the device owned by the uio driver, but not added
274         to the UIO device itself at this time.  This might change in the
275         future if it would be found to be useful.
276         </para>
277
278         <para>
279         The following standard attributes are provided by the UIO
280         framework:
281         </para>
282 <itemizedlist>
283 <listitem>
284         <para>
285         <filename>name</filename>: The name of your device. It is
286         recommended to use the name of your kernel module for this.
287         </para>
288 </listitem>
289 <listitem>
290         <para>
291         <filename>version</filename>: A version string defined by your
292         driver. This allows the user space part of your driver to deal
293         with different versions of the kernel module.
294         </para>
295 </listitem>
296 <listitem>
297         <para>
298         <filename>event</filename>: The total number of interrupts
299         handled by the driver since the last time the device node was
300         read.
301         </para>
302 </listitem>
303 </itemizedlist>
304 <para>
305         These attributes appear under the
306         <filename>/sys/class/uio/uioX</filename> directory.  Please
307         note that this directory might be a symlink, and not a real
308         directory.  Any userspace code that accesses it must be able
309         to handle this.
310 </para>
311 <para>
312         Each UIO device can make one or more memory regions available for
313         memory mapping. This is necessary because some industrial I/O cards
314         require access to more than one PCI memory region in a driver.
315 </para>
316 <para>
317         Each mapping has its own directory in sysfs, the first mapping
318         appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>.
319         Subsequent mappings create directories <filename>map1/</filename>,
320         <filename>map2/</filename>, and so on. These directories will only
321         appear if the size of the mapping is not 0.
322 </para>
323 <para>
324         Each <filename>mapX/</filename> directory contains four read-only files
325         that show attributes of the memory:
326 </para>
327 <itemizedlist>
328 <listitem>
329         <para>
330         <filename>name</filename>: A string identifier for this mapping. This
331         is optional, the string can be empty. Drivers can set this to make it
332         easier for userspace to find the correct mapping.
333         </para>
334 </listitem>
335 <listitem>
336         <para>
337         <filename>addr</filename>: The address of memory that can be mapped.
338         </para>
339 </listitem>
340 <listitem>
341         <para>
342         <filename>size</filename>: The size, in bytes, of the memory
343         pointed to by addr.
344         </para>
345 </listitem>
346 <listitem>
347         <para>
348         <filename>offset</filename>: The offset, in bytes, that has to be
349         added to the pointer returned by <function>mmap()</function> to get
350         to the actual device memory. This is important if the device's memory
351         is not page aligned. Remember that pointers returned by
352         <function>mmap()</function> are always page aligned, so it is good
353         style to always add this offset.
354         </para>
355 </listitem>
356 </itemizedlist>
357
358 <para>
359         From userspace, the different mappings are distinguished by adjusting
360         the <varname>offset</varname> parameter of the
361         <function>mmap()</function> call. To map the memory of mapping N, you
362         have to use N times the page size as your offset:
363 </para>
364 <programlisting format="linespecific">
365 offset = N * getpagesize();
366 </programlisting>
367
368 <para>
369         Sometimes there is hardware with memory-like regions that can not be
370         mapped with the technique described here, but there are still ways to
371         access them from userspace. The most common example are x86 ioports.
372         On x86 systems, userspace can access these ioports using
373         <function>ioperm()</function>, <function>iopl()</function>,
374         <function>inb()</function>, <function>outb()</function>, and similar
375         functions.
376 </para>
377 <para>
378         Since these ioport regions can not be mapped, they will not appear under
379         <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory
380         described above. Without information about the port regions a hardware
381         has to offer, it becomes difficult for the userspace part of the
382         driver to find out which ports belong to which UIO device.
383 </para>
384 <para>
385         To address this situation, the new directory
386         <filename>/sys/class/uio/uioX/portio/</filename> was added. It only
387         exists if the driver wants to pass information about one or more port
388         regions to userspace. If that is the case, subdirectories named
389         <filename>port0</filename>, <filename>port1</filename>, and so on,
390         will appear underneath
391         <filename>/sys/class/uio/uioX/portio/</filename>.
392 </para>
393 <para>
394         Each <filename>portX/</filename> directory contains four read-only
395         files that show name, start, size, and type of the port region:
396 </para>
397 <itemizedlist>
398 <listitem>
399         <para>
400         <filename>name</filename>: A string identifier for this port region.
401         The string is optional and can be empty. Drivers can set it to make it
402         easier for userspace to find a certain port region.
403         </para>
404 </listitem>
405 <listitem>
406         <para>
407         <filename>start</filename>: The first port of this region.
408         </para>
409 </listitem>
410 <listitem>
411         <para>
412         <filename>size</filename>: The number of ports in this region.
413         </para>
414 </listitem>
415 <listitem>
416         <para>
417         <filename>porttype</filename>: A string describing the type of port.
418         </para>
419 </listitem>
420 </itemizedlist>
421
422
423 </sect1>
424 </chapter>
425
426 <chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
427 <?dbhtml filename="custom_kernel_module.html"?>
428 <title>Writing your own kernel module</title>
429         <para>
430         Please have a look at <filename>uio_cif.c</filename> as an
431         example. The following paragraphs explain the different
432         sections of this file.
433         </para>
434
435 <sect1 id="uio_info">
436 <title>struct uio_info</title>
437         <para>
438         This structure tells the framework the details of your driver,
439         Some of the members are required, others are optional.
440         </para>
441
442 <itemizedlist>
443 <listitem><para>
444 <varname>const char *name</varname>: Required. The name of your driver as
445 it will appear in sysfs. I recommend using the name of your module for this.
446 </para></listitem>
447
448 <listitem><para>
449 <varname>const char *version</varname>: Required. This string appears in
450 <filename>/sys/class/uio/uioX/version</filename>.
451 </para></listitem>
452
453 <listitem><para>
454 <varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you
455 have memory that can be mapped with <function>mmap()</function>. For each
456 mapping you need to fill one of the <varname>uio_mem</varname> structures.
457 See the description below for details.
458 </para></listitem>
459
460 <listitem><para>
461 <varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
462 if you want to pass information about ioports to userspace. For each port
463 region you need to fill one of the <varname>uio_port</varname> structures.
464 See the description below for details.
465 </para></listitem>
466
467 <listitem><para>
468 <varname>long irq</varname>: Required. If your hardware generates an
469 interrupt, it's your modules task to determine the irq number during
470 initialization. If you don't have a hardware generated interrupt but
471 want to trigger the interrupt handler in some other way, set
472 <varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
473 If you had no interrupt at all, you could set
474 <varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
475 rarely makes sense.
476 </para></listitem>
477
478 <listitem><para>
479 <varname>unsigned long irq_flags</varname>: Required if you've set
480 <varname>irq</varname> to a hardware interrupt number. The flags given
481 here will be used in the call to <function>request_irq()</function>.
482 </para></listitem>
483
484 <listitem><para>
485 <varname>int (*mmap)(struct uio_info *info, struct vm_area_struct
486 *vma)</varname>: Optional. If you need a special
487 <function>mmap()</function> function, you can set it here. If this
488 pointer is not NULL, your <function>mmap()</function> will be called
489 instead of the built-in one.
490 </para></listitem>
491
492 <listitem><para>
493 <varname>int (*open)(struct uio_info *info, struct inode *inode)
494 </varname>: Optional. You might want to have your own
495 <function>open()</function>, e.g. to enable interrupts only when your
496 device is actually used.
497 </para></listitem>
498
499 <listitem><para>
500 <varname>int (*release)(struct uio_info *info, struct inode *inode)
501 </varname>: Optional. If you define your own
502 <function>open()</function>, you will probably also want a custom
503 <function>release()</function> function.
504 </para></listitem>
505
506 <listitem><para>
507 <varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)
508 </varname>: Optional. If you need to be able to enable or disable
509 interrupts from userspace by writing to <filename>/dev/uioX</filename>,
510 you can implement this function. The parameter <varname>irq_on</varname>
511 will be 0 to disable interrupts and 1 to enable them.
512 </para></listitem>
513 </itemizedlist>
514
515 <para>
516 Usually, your device will have one or more memory regions that can be mapped
517 to user space. For each region, you have to set up a
518 <varname>struct uio_mem</varname> in the <varname>mem[]</varname> array.
519 Here's a description of the fields of <varname>struct uio_mem</varname>:
520 </para>
521
522 <itemizedlist>
523 <listitem><para>
524 <varname>int memtype</varname>: Required if the mapping is used. Set this to
525 <varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
526 card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
527 memory (e.g. allocated with <function>kmalloc()</function>). There's also
528 <varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
529 </para></listitem>
530
531 <listitem><para>
532 <varname>unsigned long addr</varname>: Required if the mapping is used.
533 Fill in the address of your memory block. This address is the one that
534 appears in sysfs.
535 </para></listitem>
536
537 <listitem><para>
538 <varname>unsigned long size</varname>: Fill in the size of the
539 memory block that <varname>addr</varname> points to. If <varname>size</varname>
540 is zero, the mapping is considered unused. Note that you
541 <emphasis>must</emphasis> initialize <varname>size</varname> with zero for
542 all unused mappings.
543 </para></listitem>
544
545 <listitem><para>
546 <varname>void *internal_addr</varname>: If you have to access this memory
547 region from within your kernel module, you will want to map it internally by
548 using something like <function>ioremap()</function>. Addresses
549 returned by this function cannot be mapped to user space, so you must not
550 store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
551 instead to remember such an address.
552 </para></listitem>
553 </itemizedlist>
554
555 <para>
556 Please do not touch the <varname>kobj</varname> element of
557 <varname>struct uio_mem</varname>! It is used by the UIO framework
558 to set up sysfs files for this mapping. Simply leave it alone.
559 </para>
560
561 <para>
562 Sometimes, your device can have one or more port regions which can not be
563 mapped to userspace. But if there are other possibilities for userspace to
564 access these ports, it makes sense to make information about the ports
565 available in sysfs. For each region, you have to set up a
566 <varname>struct uio_port</varname> in the <varname>port[]</varname> array.
567 Here's a description of the fields of <varname>struct uio_port</varname>:
568 </para>
569
570 <itemizedlist>
571 <listitem><para>
572 <varname>char *porttype</varname>: Required. Set this to one of the predefined
573 constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
574 architectures.
575 </para></listitem>
576
577 <listitem><para>
578 <varname>unsigned long start</varname>: Required if the port region is used.
579 Fill in the number of the first port of this region.
580 </para></listitem>
581
582 <listitem><para>
583 <varname>unsigned long size</varname>: Fill in the number of ports in this
584 region. If <varname>size</varname> is zero, the region is considered unused.
585 Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
586 with zero for all unused regions.
587 </para></listitem>
588 </itemizedlist>
589
590 <para>
591 Please do not touch the <varname>portio</varname> element of
592 <varname>struct uio_port</varname>! It is used internally by the UIO
593 framework to set up sysfs files for this region. Simply leave it alone.
594 </para>
595
596 </sect1>
597
598 <sect1 id="adding_irq_handler">
599 <title>Adding an interrupt handler</title>
600         <para>
601         What you need to do in your interrupt handler depends on your
602         hardware and on how you want to handle it. You should try to
603         keep the amount of code in your kernel interrupt handler low.
604         If your hardware requires no action that you
605         <emphasis>have</emphasis> to perform after each interrupt,
606         then your handler can be empty.</para> <para>If, on the other
607         hand, your hardware <emphasis>needs</emphasis> some action to
608         be performed after each interrupt, then you
609         <emphasis>must</emphasis> do it in your kernel module. Note
610         that you cannot rely on the userspace part of your driver. Your
611         userspace program can terminate at any time, possibly leaving
612         your hardware in a state where proper interrupt handling is
613         still required.
614         </para>
615
616         <para>
617         There might also be applications where you want to read data
618         from your hardware at each interrupt and buffer it in a piece
619         of kernel memory you've allocated for that purpose.  With this
620         technique you could avoid loss of data if your userspace
621         program misses an interrupt.
622         </para>
623
624         <para>
625         A note on shared interrupts: Your driver should support
626         interrupt sharing whenever this is possible. It is possible if
627         and only if your driver can detect whether your hardware has
628         triggered the interrupt or not. This is usually done by looking
629         at an interrupt status register. If your driver sees that the
630         IRQ bit is actually set, it will perform its actions, and the
631         handler returns IRQ_HANDLED. If the driver detects that it was
632         not your hardware that caused the interrupt, it will do nothing
633         and return IRQ_NONE, allowing the kernel to call the next
634         possible interrupt handler.
635         </para>
636
637         <para>
638         If you decide not to support shared interrupts, your card
639         won't work in computers with no free interrupts. As this
640         frequently happens on the PC platform, you can save yourself a
641         lot of trouble by supporting interrupt sharing.
642         </para>
643 </sect1>
644
645 <sect1 id="using_uio_pdrv">
646 <title>Using uio_pdrv for platform devices</title>
647         <para>
648         In many cases, UIO drivers for platform devices can be handled in a
649         generic way. In the same place where you define your
650         <varname>struct platform_device</varname>, you simply also implement
651         your interrupt handler and fill your
652         <varname>struct uio_info</varname>. A pointer to this
653         <varname>struct uio_info</varname> is then used as
654         <varname>platform_data</varname> for your platform device.
655         </para>
656         <para>
657         You also need to set up an array of <varname>struct resource</varname>
658         containing addresses and sizes of your memory mappings. This
659         information is passed to the driver using the
660         <varname>.resource</varname> and <varname>.num_resources</varname>
661         elements of <varname>struct platform_device</varname>.
662         </para>
663         <para>
664         You now have to set the <varname>.name</varname> element of
665         <varname>struct platform_device</varname> to
666         <varname>"uio_pdrv"</varname> to use the generic UIO platform device
667         driver. This driver will fill the <varname>mem[]</varname> array
668         according to the resources given, and register the device.
669         </para>
670         <para>
671         The advantage of this approach is that you only have to edit a file
672         you need to edit anyway. You do not have to create an extra driver.
673         </para>
674 </sect1>
675
676 <sect1 id="using_uio_pdrv_genirq">
677 <title>Using uio_pdrv_genirq for platform devices</title>
678         <para>
679         Especially in embedded devices, you frequently find chips where the
680         irq pin is tied to its own dedicated interrupt line. In such cases,
681         where you can be really sure the interrupt is not shared, we can take
682         the concept of <varname>uio_pdrv</varname> one step further and use a
683         generic interrupt handler. That's what
684         <varname>uio_pdrv_genirq</varname> does.
685         </para>
686         <para>
687         The setup for this driver is the same as described above for
688         <varname>uio_pdrv</varname>, except that you do not implement an
689         interrupt handler. The <varname>.handler</varname> element of
690         <varname>struct uio_info</varname> must remain
691         <varname>NULL</varname>. The  <varname>.irq_flags</varname> element
692         must not contain <varname>IRQF_SHARED</varname>.
693         </para>
694         <para>
695         You will set the <varname>.name</varname> element of
696         <varname>struct platform_device</varname> to
697         <varname>"uio_pdrv_genirq"</varname> to use this driver.
698         </para>
699         <para>
700         The generic interrupt handler of <varname>uio_pdrv_genirq</varname>
701         will simply disable the interrupt line using
702         <function>disable_irq_nosync()</function>. After doing its work,
703         userspace can reenable the interrupt by writing 0x00000001 to the UIO
704         device file. The driver already implements an
705         <function>irq_control()</function> to make this possible, you must not
706         implement your own.
707         </para>
708         <para>
709         Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of
710         interrupt handler code. You also do not need to know anything about
711         the chip's internal registers to create the kernel part of the driver.
712         All you need to know is the irq number of the pin the chip is
713         connected to.
714         </para>
715 </sect1>
716
717 </chapter>
718
719 <chapter id="userspace_driver" xreflabel="Writing a driver in user space">
720 <?dbhtml filename="userspace_driver.html"?>
721 <title>Writing a driver in userspace</title>
722         <para>
723         Once you have a working kernel module for your hardware, you can
724         write the userspace part of your driver. You don't need any special
725         libraries, your driver can be written in any reasonable language,
726         you can use floating point numbers and so on. In short, you can
727         use all the tools and libraries you'd normally use for writing a
728         userspace application.
729         </para>
730
731 <sect1 id="getting_uio_information">
732 <title>Getting information about your UIO device</title>
733         <para>
734         Information about all UIO devices is available in sysfs. The
735         first thing you should do in your driver is check
736         <varname>name</varname> and <varname>version</varname> to
737         make sure your talking to the right device and that its kernel
738         driver has the version you expect.
739         </para>
740         <para>
741         You should also make sure that the memory mapping you need
742         exists and has the size you expect.
743         </para>
744         <para>
745         There is a tool called <varname>lsuio</varname> that lists
746         UIO devices and their attributes. It is available here:
747         </para>
748         <para>
749         <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
750                 http://www.osadl.org/projects/downloads/UIO/user/</ulink>
751         </para>
752         <para>
753         With <varname>lsuio</varname> you can quickly check if your
754         kernel module is loaded and which attributes it exports.
755         Have a look at the manpage for details.
756         </para>
757         <para>
758         The source code of <varname>lsuio</varname> can serve as an
759         example for getting information about an UIO device.
760         The file <filename>uio_helper.c</filename> contains a lot of
761         functions you could use in your userspace driver code.
762         </para>
763 </sect1>
764
765 <sect1 id="mmap_device_memory">
766 <title>mmap() device memory</title>
767         <para>
768         After you made sure you've got the right device with the
769         memory mappings you need, all you have to do is to call
770         <function>mmap()</function> to map the device's memory
771         to userspace.
772         </para>
773         <para>
774         The parameter <varname>offset</varname> of the
775         <function>mmap()</function> call has a special meaning
776         for UIO devices: It is used to select which mapping of
777         your device you want to map. To map the memory of
778         mapping N, you have to use N times the page size as
779         your offset:
780         </para>
781 <programlisting format="linespecific">
782         offset = N * getpagesize();
783 </programlisting>
784         <para>
785         N starts from zero, so if you've got only one memory
786         range to map, set <varname>offset = 0</varname>.
787         A drawback of this technique is that memory is always
788         mapped beginning with its start address.
789         </para>
790 </sect1>
791
792 <sect1 id="wait_for_interrupts">
793 <title>Waiting for interrupts</title>
794         <para>
795         After you successfully mapped your devices memory, you
796         can access it like an ordinary array. Usually, you will
797         perform some initialization. After that, your hardware
798         starts working and will generate an interrupt as soon
799         as it's finished, has some data available, or needs your
800         attention because an error occurred.
801         </para>
802         <para>
803         <filename>/dev/uioX</filename> is a read-only file. A
804         <function>read()</function> will always block until an
805         interrupt occurs. There is only one legal value for the
806         <varname>count</varname> parameter of
807         <function>read()</function>, and that is the size of a
808         signed 32 bit integer (4). Any other value for
809         <varname>count</varname> causes <function>read()</function>
810         to fail. The signed 32 bit integer read is the interrupt
811         count of your device. If the value is one more than the value
812         you read the last time, everything is OK. If the difference
813         is greater than one, you missed interrupts.
814         </para>
815         <para>
816         You can also use <function>select()</function> on
817         <filename>/dev/uioX</filename>.
818         </para>
819 </sect1>
820
821 </chapter>
822
823 <chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards">
824 <?dbhtml filename="uio_pci_generic.html"?>
825 <title>Generic PCI UIO driver</title>
826         <para>
827         The generic driver is a kernel module named uio_pci_generic.
828         It can work with any device compliant to PCI 2.3 (circa 2002) and
829         any compliant PCI Express device. Using this, you only need to
830         write the userspace driver, removing the need to write
831         a hardware-specific kernel module.
832         </para>
833
834 <sect1 id="uio_pci_generic_binding">
835 <title>Making the driver recognize the device</title>
836         <para>
837 Since the driver does not declare any device ids, it will not get loaded
838 automatically and will not automatically bind to any devices, you must load it
839 and allocate id to the driver yourself. For example:
840         <programlisting>
841  modprobe uio_pci_generic
842  echo &quot;8086 10f5&quot; &gt; /sys/bus/pci/drivers/uio_pci_generic/new_id
843         </programlisting>
844         </para>
845         <para>
846 If there already is a hardware specific kernel driver for your device, the
847 generic driver still won't bind to it, in this case if you want to use the
848 generic driver (why would you?) you'll have to manually unbind the hardware
849 specific driver and bind the generic driver, like this:
850         <programlisting>
851     echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/e1000e/unbind
852     echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/uio_pci_generic/bind
853         </programlisting>
854         </para>
855         <para>
856 You can verify that the device has been bound to the driver
857 by looking for it in sysfs, for example like the following:
858         <programlisting>
859     ls -l /sys/bus/pci/devices/0000:00:19.0/driver
860         </programlisting>
861 Which if successful should print
862         <programlisting>
863   .../0000:00:19.0/driver -&gt; ../../../bus/pci/drivers/uio_pci_generic
864         </programlisting>
865 Note that the generic driver will not bind to old PCI 2.2 devices.
866 If binding the device failed, run the following command:
867         <programlisting>
868   dmesg
869         </programlisting>
870 and look in the output for failure reasons
871         </para>
872 </sect1>
873
874 <sect1 id="uio_pci_generic_internals">
875 <title>Things to know about uio_pci_generic</title>
876         <para>
877 Interrupts are handled using the Interrupt Disable bit in the PCI command
878 register and Interrupt Status bit in the PCI status register.  All devices
879 compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should
880 support these bits.  uio_pci_generic detects this support, and won't bind to
881 devices which do not support the Interrupt Disable Bit in the command register.
882         </para>
883         <para>
884 On each interrupt, uio_pci_generic sets the Interrupt Disable bit.
885 This prevents the device from generating further interrupts
886 until the bit is cleared. The userspace driver should clear this
887 bit before blocking and waiting for more interrupts.
888         </para>
889 </sect1>
890 <sect1 id="uio_pci_generic_userspace">
891 <title>Writing userspace driver using uio_pci_generic</title>
892         <para>
893 Userspace driver can use pci sysfs interface, or the
894 libpci libray that wraps it, to talk to the device and to
895 re-enable interrupts by writing to the command register.
896         </para>
897 </sect1>
898 <sect1 id="uio_pci_generic_example">
899 <title>Example code using uio_pci_generic</title>
900         <para>
901 Here is some sample userspace driver code using uio_pci_generic:
902 <programlisting>
903 #include &lt;stdlib.h&gt;
904 #include &lt;stdio.h&gt;
905 #include &lt;unistd.h&gt;
906 #include &lt;sys/types.h&gt;
907 #include &lt;sys/stat.h&gt;
908 #include &lt;fcntl.h&gt;
909 #include &lt;errno.h&gt;
910
911 int main()
912 {
913         int uiofd;
914         int configfd;
915         int err;
916         int i;
917         unsigned icount;
918         unsigned char command_high;
919
920         uiofd = open(&quot;/dev/uio0&quot;, O_RDONLY);
921         if (uiofd &lt; 0) {
922                 perror(&quot;uio open:&quot;);
923                 return errno;
924         }
925         configfd = open(&quot;/sys/class/uio/uio0/device/config&quot;, O_RDWR);
926         if (uiofd &lt; 0) {
927                 perror(&quot;config open:&quot;);
928                 return errno;
929         }
930
931         /* Read and cache command value */
932         err = pread(configfd, &amp;command_high, 1, 5);
933         if (err != 1) {
934                 perror(&quot;command config read:&quot;);
935                 return errno;
936         }
937         command_high &amp;= ~0x4;
938
939         for(i = 0;; ++i) {
940                 /* Print out a message, for debugging. */
941                 if (i == 0)
942                         fprintf(stderr, &quot;Started uio test driver.\n&quot;);
943                 else
944                         fprintf(stderr, &quot;Interrupts: %d\n&quot;, icount);
945
946                 /****************************************/
947                 /* Here we got an interrupt from the
948                    device. Do something to it. */
949                 /****************************************/
950
951                 /* Re-enable interrupts. */
952                 err = pwrite(configfd, &amp;command_high, 1, 5);
953                 if (err != 1) {
954                         perror(&quot;config write:&quot;);
955                         break;
956                 }
957
958                 /* Wait for next interrupt. */
959                 err = read(uiofd, &amp;icount, 4);
960                 if (err != 4) {
961                         perror(&quot;uio read:&quot;);
962                         break;
963                 }
964
965         }
966         return errno;
967 }
968
969 </programlisting>
970         </para>
971 </sect1>
972
973 </chapter>
974
975 <appendix id="app1">
976 <title>Further information</title>
977 <itemizedlist>
978         <listitem><para>
979                         <ulink url="http://www.osadl.org">
980                                 OSADL homepage.</ulink>
981                 </para></listitem>
982         <listitem><para>
983                 <ulink url="http://www.linutronix.de">
984                  Linutronix homepage.</ulink>
985                 </para></listitem>
986 </itemizedlist>
987 </appendix>
988
989 </book>