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