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" []>
7 <title>The Userspace I/O HOWTO</title>
10 <firstname>Hans-Jürgen</firstname>
11 <surname>Koch</surname>
12 <authorblurb><para>Linux developer, Linutronix</para></authorblurb>
15 <ulink url="http://www.linutronix.de">Linutronix</ulink>
19 <email>hjk@linutronix.de</email>
24 <pubdate>2006-12-11</pubdate>
27 <para>This HOWTO describes concept and usage of Linux kernel's
28 Userspace I/O system.</para>
33 <revnumber>0.5</revnumber>
34 <date>2008-05-22</date>
35 <authorinitials>hjk</authorinitials>
36 <revremark>Added description of write() function.</revremark>
39 <revnumber>0.4</revnumber>
40 <date>2007-11-26</date>
41 <authorinitials>hjk</authorinitials>
42 <revremark>Removed section about uio_dummy.</revremark>
45 <revnumber>0.3</revnumber>
46 <date>2007-04-29</date>
47 <authorinitials>hjk</authorinitials>
48 <revremark>Added section about userspace drivers.</revremark>
51 <revnumber>0.2</revnumber>
52 <date>2007-02-13</date>
53 <authorinitials>hjk</authorinitials>
54 <revremark>Update after multiple mappings were added.</revremark>
57 <revnumber>0.1</revnumber>
58 <date>2006-12-11</date>
59 <authorinitials>hjk</authorinitials>
60 <revremark>First draft.</revremark>
65 <chapter id="aboutthisdoc">
66 <?dbhtml filename="about.html"?>
67 <title>About this document</title>
69 <sect1 id="copyright">
70 <?dbhtml filename="copyright.html"?>
71 <title>Copyright and License</title>
73 Copyright (c) 2006-2008 by Hans-Jürgen Koch.</para>
75 This documentation is Free Software licensed under the terms of the
80 <sect1 id="translations">
81 <?dbhtml filename="translations.html"?>
82 <title>Translations</title>
84 <para>If you know of any translations for this document, or you are
85 interested in translating it, please email me
86 <email>hjk@linutronix.de</email>.
91 <title>Preface</title>
93 For many types of devices, creating a Linux kernel driver is
94 overkill. All that is really needed is some way to handle an
95 interrupt and provide access to the memory space of the
96 device. The logic of controlling the device does not
97 necessarily have to be within the kernel, as the device does
98 not need to take advantage of any of other resources that the
99 kernel provides. One such common class of devices that are
100 like this are for industrial I/O cards.
103 To address this situation, the userspace I/O system (UIO) was
104 designed. For typical industrial I/O cards, only a very small
105 kernel module is needed. The main part of the driver will run in
106 user space. This simplifies development and reduces the risk of
107 serious bugs within a kernel module.
110 Please note that UIO is not an universal driver interface. Devices
111 that are already handled well by other kernel subsystems (like
112 networking or serial or USB) are no candidates for an UIO driver.
113 Hardware that is ideally suited for an UIO driver fulfills all of
118 <para>The device has memory that can be mapped. The device can be
119 controlled completely by writing to this memory.</para>
122 <para>The device usually generates interrupts.</para>
125 <para>The device does not fit into one of the standard kernel
132 <title>Acknowledgments</title>
133 <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of
134 Linutronix, who have not only written most of the UIO code, but also
135 helped greatly writing this HOWTO by giving me all kinds of background
139 <sect1 id="feedback">
140 <title>Feedback</title>
141 <para>Find something wrong with this document? (Or perhaps something
142 right?) I would love to hear from you. Please email me at
143 <email>hjk@linutronix.de</email>.</para>
148 <?dbhtml filename="about.html"?>
149 <title>About UIO</title>
151 <para>If you use UIO for your card's driver, here's what you get:</para>
155 <para>only one small kernel module to write and maintain.</para>
158 <para>develop the main part of your driver in user space,
159 with all the tools and libraries you're used to.</para>
162 <para>bugs in your driver won't crash the kernel.</para>
165 <para>updates of your driver can take place without recompiling
170 <sect1 id="how_uio_works">
171 <title>How UIO works</title>
173 Each UIO device is accessed through a device file and several
174 sysfs attribute files. The device file will be called
175 <filename>/dev/uio0</filename> for the first device, and
176 <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename>
177 and so on for subsequent devices.
180 <para><filename>/dev/uioX</filename> is used to access the
181 address space of the card. Just use
182 <function>mmap()</function> to access registers or RAM
183 locations of your card.
187 Interrupts are handled by reading from
188 <filename>/dev/uioX</filename>. A blocking
189 <function>read()</function> from
190 <filename>/dev/uioX</filename> will return as soon as an
191 interrupt occurs. You can also use
192 <function>select()</function> on
193 <filename>/dev/uioX</filename> to wait for an interrupt. The
194 integer value read from <filename>/dev/uioX</filename>
195 represents the total interrupt count. You can use this number
196 to figure out if you missed some interrupts.
199 For some hardware that has more than one interrupt source internally,
200 but not separate IRQ mask and status registers, there might be
201 situations where userspace cannot determine what the interrupt source
202 was if the kernel handler disables them by writing to the chip's IRQ
203 register. In such a case, the kernel has to disable the IRQ completely
204 to leave the chip's register untouched. Now the userspace part can
205 determine the cause of the interrupt, but it cannot re-enable
206 interrupts. Another cornercase is chips where re-enabling interrupts
207 is a read-modify-write operation to a combined IRQ status/acknowledge
208 register. This would be racy if a new interrupt occurred
212 To address these problems, UIO also implements a write() function. It
213 is normally not used and can be ignored for hardware that has only a
214 single interrupt source or has separate IRQ mask and status registers.
215 If you need it, however, a write to <filename>/dev/uioX</filename>
216 will call the <function>irqcontrol()</function> function implemented
217 by the driver. You have to write a 32-bit value that is usually either
218 0 or 1 to disable or enable interrupts. If a driver does not implement
219 <function>irqcontrol()</function>, <function>write()</function> will
220 return with <varname>-ENOSYS</varname>.
224 To handle interrupts properly, your custom kernel module can
225 provide its own interrupt handler. It will automatically be
226 called by the built-in handler.
230 For cards that don't generate interrupts but need to be
231 polled, there is the possibility to set up a timer that
232 triggers the interrupt handler at configurable time intervals.
233 This interrupt simulation is done by calling
234 <function>uio_event_notify()</function>
235 from the timer's event handler.
239 Each driver provides attributes that are used to read or write
240 variables. These attributes are accessible through sysfs
241 files. A custom kernel driver module can add its own
242 attributes to the device owned by the uio driver, but not added
243 to the UIO device itself at this time. This might change in the
244 future if it would be found to be useful.
248 The following standard attributes are provided by the UIO
254 <filename>name</filename>: The name of your device. It is
255 recommended to use the name of your kernel module for this.
260 <filename>version</filename>: A version string defined by your
261 driver. This allows the user space part of your driver to deal
262 with different versions of the kernel module.
267 <filename>event</filename>: The total number of interrupts
268 handled by the driver since the last time the device node was
274 These attributes appear under the
275 <filename>/sys/class/uio/uioX</filename> directory. Please
276 note that this directory might be a symlink, and not a real
277 directory. Any userspace code that accesses it must be able
281 Each UIO device can make one or more memory regions available for
282 memory mapping. This is necessary because some industrial I/O cards
283 require access to more than one PCI memory region in a driver.
286 Each mapping has its own directory in sysfs, the first mapping
287 appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>.
288 Subsequent mappings create directories <filename>map1/</filename>,
289 <filename>map2/</filename>, and so on. These directories will only
290 appear if the size of the mapping is not 0.
293 Each <filename>mapX/</filename> directory contains two read-only files
294 that show start address and size of the memory:
299 <filename>addr</filename>: The address of memory that can be mapped.
304 <filename>size</filename>: The size, in bytes, of the memory
311 From userspace, the different mappings are distinguished by adjusting
312 the <varname>offset</varname> parameter of the
313 <function>mmap()</function> call. To map the memory of mapping N, you
314 have to use N times the page size as your offset:
316 <programlisting format="linespecific">
317 offset = N * getpagesize();
323 <chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
324 <?dbhtml filename="custom_kernel_module.html"?>
325 <title>Writing your own kernel module</title>
327 Please have a look at <filename>uio_cif.c</filename> as an
328 example. The following paragraphs explain the different
329 sections of this file.
332 <sect1 id="uio_info">
333 <title>struct uio_info</title>
335 This structure tells the framework the details of your driver,
336 Some of the members are required, others are optional.
341 <varname>char *name</varname>: Required. The name of your driver as
342 it will appear in sysfs. I recommend using the name of your module for this.
346 <varname>char *version</varname>: Required. This string appears in
347 <filename>/sys/class/uio/uioX/version</filename>.
351 <varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you
352 have memory that can be mapped with <function>mmap()</function>. For each
353 mapping you need to fill one of the <varname>uio_mem</varname> structures.
354 See the description below for details.
358 <varname>long irq</varname>: Required. If your hardware generates an
359 interrupt, it's your modules task to determine the irq number during
360 initialization. If you don't have a hardware generated interrupt but
361 want to trigger the interrupt handler in some other way, set
362 <varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
363 If you had no interrupt at all, you could set
364 <varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
369 <varname>unsigned long irq_flags</varname>: Required if you've set
370 <varname>irq</varname> to a hardware interrupt number. The flags given
371 here will be used in the call to <function>request_irq()</function>.
375 <varname>int (*mmap)(struct uio_info *info, struct vm_area_struct
376 *vma)</varname>: Optional. If you need a special
377 <function>mmap()</function> function, you can set it here. If this
378 pointer is not NULL, your <function>mmap()</function> will be called
379 instead of the built-in one.
383 <varname>int (*open)(struct uio_info *info, struct inode *inode)
384 </varname>: Optional. You might want to have your own
385 <function>open()</function>, e.g. to enable interrupts only when your
386 device is actually used.
390 <varname>int (*release)(struct uio_info *info, struct inode *inode)
391 </varname>: Optional. If you define your own
392 <function>open()</function>, you will probably also want a custom
393 <function>release()</function> function.
397 <varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)
398 </varname>: Optional. If you need to be able to enable or disable
399 interrupts from userspace by writing to <filename>/dev/uioX</filename>,
400 you can implement this function. The parameter <varname>irq_on</varname>
401 will be 0 to disable interrupts and 1 to enable them.
406 Usually, your device will have one or more memory regions that can be mapped
407 to user space. For each region, you have to set up a
408 <varname>struct uio_mem</varname> in the <varname>mem[]</varname> array.
409 Here's a description of the fields of <varname>struct uio_mem</varname>:
414 <varname>int memtype</varname>: Required if the mapping is used. Set this to
415 <varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
416 card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
417 memory (e.g. allocated with <function>kmalloc()</function>). There's also
418 <varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
422 <varname>unsigned long addr</varname>: Required if the mapping is used.
423 Fill in the address of your memory block. This address is the one that
428 <varname>unsigned long size</varname>: Fill in the size of the
429 memory block that <varname>addr</varname> points to. If <varname>size</varname>
430 is zero, the mapping is considered unused. Note that you
431 <emphasis>must</emphasis> initialize <varname>size</varname> with zero for
436 <varname>void *internal_addr</varname>: If you have to access this memory
437 region from within your kernel module, you will want to map it internally by
438 using something like <function>ioremap()</function>. Addresses
439 returned by this function cannot be mapped to user space, so you must not
440 store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
441 instead to remember such an address.
446 Please do not touch the <varname>kobj</varname> element of
447 <varname>struct uio_mem</varname>! It is used by the UIO framework
448 to set up sysfs files for this mapping. Simply leave it alone.
452 <sect1 id="adding_irq_handler">
453 <title>Adding an interrupt handler</title>
455 What you need to do in your interrupt handler depends on your
456 hardware and on how you want to handle it. You should try to
457 keep the amount of code in your kernel interrupt handler low.
458 If your hardware requires no action that you
459 <emphasis>have</emphasis> to perform after each interrupt,
460 then your handler can be empty.</para> <para>If, on the other
461 hand, your hardware <emphasis>needs</emphasis> some action to
462 be performed after each interrupt, then you
463 <emphasis>must</emphasis> do it in your kernel module. Note
464 that you cannot rely on the userspace part of your driver. Your
465 userspace program can terminate at any time, possibly leaving
466 your hardware in a state where proper interrupt handling is
471 There might also be applications where you want to read data
472 from your hardware at each interrupt and buffer it in a piece
473 of kernel memory you've allocated for that purpose. With this
474 technique you could avoid loss of data if your userspace
475 program misses an interrupt.
479 A note on shared interrupts: Your driver should support
480 interrupt sharing whenever this is possible. It is possible if
481 and only if your driver can detect whether your hardware has
482 triggered the interrupt or not. This is usually done by looking
483 at an interrupt status register. If your driver sees that the
484 IRQ bit is actually set, it will perform its actions, and the
485 handler returns IRQ_HANDLED. If the driver detects that it was
486 not your hardware that caused the interrupt, it will do nothing
487 and return IRQ_NONE, allowing the kernel to call the next
488 possible interrupt handler.
492 If you decide not to support shared interrupts, your card
493 won't work in computers with no free interrupts. As this
494 frequently happens on the PC platform, you can save yourself a
495 lot of trouble by supporting interrupt sharing.
501 <chapter id="userspace_driver" xreflabel="Writing a driver in user space">
502 <?dbhtml filename="userspace_driver.html"?>
503 <title>Writing a driver in userspace</title>
505 Once you have a working kernel module for your hardware, you can
506 write the userspace part of your driver. You don't need any special
507 libraries, your driver can be written in any reasonable language,
508 you can use floating point numbers and so on. In short, you can
509 use all the tools and libraries you'd normally use for writing a
510 userspace application.
513 <sect1 id="getting_uio_information">
514 <title>Getting information about your UIO device</title>
516 Information about all UIO devices is available in sysfs. The
517 first thing you should do in your driver is check
518 <varname>name</varname> and <varname>version</varname> to
519 make sure your talking to the right device and that its kernel
520 driver has the version you expect.
523 You should also make sure that the memory mapping you need
524 exists and has the size you expect.
527 There is a tool called <varname>lsuio</varname> that lists
528 UIO devices and their attributes. It is available here:
531 <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
532 http://www.osadl.org/projects/downloads/UIO/user/</ulink>
535 With <varname>lsuio</varname> you can quickly check if your
536 kernel module is loaded and which attributes it exports.
537 Have a look at the manpage for details.
540 The source code of <varname>lsuio</varname> can serve as an
541 example for getting information about an UIO device.
542 The file <filename>uio_helper.c</filename> contains a lot of
543 functions you could use in your userspace driver code.
547 <sect1 id="mmap_device_memory">
548 <title>mmap() device memory</title>
550 After you made sure you've got the right device with the
551 memory mappings you need, all you have to do is to call
552 <function>mmap()</function> to map the device's memory
556 The parameter <varname>offset</varname> of the
557 <function>mmap()</function> call has a special meaning
558 for UIO devices: It is used to select which mapping of
559 your device you want to map. To map the memory of
560 mapping N, you have to use N times the page size as
563 <programlisting format="linespecific">
564 offset = N * getpagesize();
567 N starts from zero, so if you've got only one memory
568 range to map, set <varname>offset = 0</varname>.
569 A drawback of this technique is that memory is always
570 mapped beginning with its start address.
574 <sect1 id="wait_for_interrupts">
575 <title>Waiting for interrupts</title>
577 After you successfully mapped your devices memory, you
578 can access it like an ordinary array. Usually, you will
579 perform some initialization. After that, your hardware
580 starts working and will generate an interrupt as soon
581 as it's finished, has some data available, or needs your
582 attention because an error occured.
585 <filename>/dev/uioX</filename> is a read-only file. A
586 <function>read()</function> will always block until an
587 interrupt occurs. There is only one legal value for the
588 <varname>count</varname> parameter of
589 <function>read()</function>, and that is the size of a
590 signed 32 bit integer (4). Any other value for
591 <varname>count</varname> causes <function>read()</function>
592 to fail. The signed 32 bit integer read is the interrupt
593 count of your device. If the value is one more than the value
594 you read the last time, everything is OK. If the difference
595 is greater than one, you missed interrupts.
598 You can also use <function>select()</function> on
599 <filename>/dev/uioX</filename>.
606 <title>Further information</title>
609 <ulink url="http://www.osadl.org">
610 OSADL homepage.</ulink>
613 <ulink url="http://www.linutronix.de">
614 Linutronix homepage.</ulink>