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