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