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