blob: d799a2621e201aefb70ca8b201c40dccb63dae3a [file] [log] [blame]
Hans J. Koche3e0a282006-12-11 16:59:59 +01001<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []>
4
5<book id="index">
6<bookinfo>
7<title>The Userspace I/O HOWTO</title>
8
9<author>
10 <firstname>Hans-Jürgen</firstname>
11 <surname>Koch</surname>
12 <authorblurb><para>Linux developer, Linutronix</para></authorblurb>
13 <affiliation>
14 <orgname>
15 <ulink url="http://www.linutronix.de">Linutronix</ulink>
16 </orgname>
17
18 <address>
19 <email>hjk@linutronix.de</email>
20 </address>
21 </affiliation>
22</author>
23
Mike Frysinger17149d92008-06-24 14:24:57 -070024<copyright>
25 <year>2006-2008</year>
26 <holder>Hans-Jürgen Koch.</holder>
27</copyright>
28
29<legalnotice>
30<para>
31This documentation is Free Software licensed under the terms of the
32GPL version 2.
33</para>
34</legalnotice>
35
Hans J. Koche3e0a282006-12-11 16:59:59 +010036<pubdate>2006-12-11</pubdate>
37
38<abstract>
39 <para>This HOWTO describes concept and usage of Linux kernel's
40 Userspace I/O system.</para>
41</abstract>
42
43<revhistory>
44 <revision>
Hans J. Koch328a14e2008-05-23 13:50:14 +020045 <revnumber>0.5</revnumber>
46 <date>2008-05-22</date>
47 <authorinitials>hjk</authorinitials>
48 <revremark>Added description of write() function.</revremark>
49 </revision>
50 <revision>
Hans J Koched423c22007-11-26 22:03:29 +010051 <revnumber>0.4</revnumber>
52 <date>2007-11-26</date>
53 <authorinitials>hjk</authorinitials>
54 <revremark>Removed section about uio_dummy.</revremark>
55 </revision>
56 <revision>
Hans J. Koche3e0a282006-12-11 16:59:59 +010057 <revnumber>0.3</revnumber>
58 <date>2007-04-29</date>
59 <authorinitials>hjk</authorinitials>
60 <revremark>Added section about userspace drivers.</revremark>
61 </revision>
62 <revision>
63 <revnumber>0.2</revnumber>
64 <date>2007-02-13</date>
65 <authorinitials>hjk</authorinitials>
66 <revremark>Update after multiple mappings were added.</revremark>
67 </revision>
68 <revision>
69 <revnumber>0.1</revnumber>
70 <date>2006-12-11</date>
71 <authorinitials>hjk</authorinitials>
72 <revremark>First draft.</revremark>
73 </revision>
74</revhistory>
75</bookinfo>
76
77<chapter id="aboutthisdoc">
78<?dbhtml filename="about.html"?>
79<title>About this document</title>
80
Hans J. Koche3e0a282006-12-11 16:59:59 +010081<sect1 id="translations">
82<?dbhtml filename="translations.html"?>
83<title>Translations</title>
84
85<para>If you know of any translations for this document, or you are
86interested in translating it, please email me
87<email>hjk@linutronix.de</email>.
88</para>
89</sect1>
90
91<sect1 id="preface">
92<title>Preface</title>
93 <para>
94 For many types of devices, creating a Linux kernel driver is
95 overkill. All that is really needed is some way to handle an
96 interrupt and provide access to the memory space of the
97 device. The logic of controlling the device does not
98 necessarily have to be within the kernel, as the device does
99 not need to take advantage of any of other resources that the
100 kernel provides. One such common class of devices that are
101 like this are for industrial I/O cards.
102 </para>
103 <para>
104 To address this situation, the userspace I/O system (UIO) was
105 designed. For typical industrial I/O cards, only a very small
106 kernel module is needed. The main part of the driver will run in
107 user space. This simplifies development and reduces the risk of
108 serious bugs within a kernel module.
109 </para>
Hans J Koched423c22007-11-26 22:03:29 +0100110 <para>
111 Please note that UIO is not an universal driver interface. Devices
112 that are already handled well by other kernel subsystems (like
113 networking or serial or USB) are no candidates for an UIO driver.
114 Hardware that is ideally suited for an UIO driver fulfills all of
115 the following:
116 </para>
117<itemizedlist>
118<listitem>
119 <para>The device has memory that can be mapped. The device can be
120 controlled completely by writing to this memory.</para>
121</listitem>
122<listitem>
123 <para>The device usually generates interrupts.</para>
124</listitem>
125<listitem>
126 <para>The device does not fit into one of the standard kernel
127 subsystems.</para>
128</listitem>
129</itemizedlist>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100130</sect1>
131
132<sect1 id="thanks">
133<title>Acknowledgments</title>
134 <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of
135 Linutronix, who have not only written most of the UIO code, but also
136 helped greatly writing this HOWTO by giving me all kinds of background
137 information.</para>
138</sect1>
139
140<sect1 id="feedback">
141<title>Feedback</title>
142 <para>Find something wrong with this document? (Or perhaps something
143 right?) I would love to hear from you. Please email me at
144 <email>hjk@linutronix.de</email>.</para>
145</sect1>
146</chapter>
147
148<chapter id="about">
149<?dbhtml filename="about.html"?>
150<title>About UIO</title>
151
152<para>If you use UIO for your card's driver, here's what you get:</para>
153
154<itemizedlist>
155<listitem>
156 <para>only one small kernel module to write and maintain.</para>
157</listitem>
158<listitem>
159 <para>develop the main part of your driver in user space,
160 with all the tools and libraries you're used to.</para>
161</listitem>
162<listitem>
163 <para>bugs in your driver won't crash the kernel.</para>
164</listitem>
165<listitem>
166 <para>updates of your driver can take place without recompiling
167 the kernel.</para>
168</listitem>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100169</itemizedlist>
170
171<sect1 id="how_uio_works">
172<title>How UIO works</title>
173 <para>
174 Each UIO device is accessed through a device file and several
175 sysfs attribute files. The device file will be called
176 <filename>/dev/uio0</filename> for the first device, and
177 <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename>
178 and so on for subsequent devices.
179 </para>
180
181 <para><filename>/dev/uioX</filename> is used to access the
182 address space of the card. Just use
183 <function>mmap()</function> to access registers or RAM
184 locations of your card.
185 </para>
186
187 <para>
188 Interrupts are handled by reading from
189 <filename>/dev/uioX</filename>. A blocking
190 <function>read()</function> from
191 <filename>/dev/uioX</filename> will return as soon as an
192 interrupt occurs. You can also use
193 <function>select()</function> on
194 <filename>/dev/uioX</filename> to wait for an interrupt. The
195 integer value read from <filename>/dev/uioX</filename>
196 represents the total interrupt count. You can use this number
197 to figure out if you missed some interrupts.
198 </para>
Hans J. Koch328a14e2008-05-23 13:50:14 +0200199 <para>
200 For some hardware that has more than one interrupt source internally,
201 but not separate IRQ mask and status registers, there might be
202 situations where userspace cannot determine what the interrupt source
203 was if the kernel handler disables them by writing to the chip's IRQ
204 register. In such a case, the kernel has to disable the IRQ completely
205 to leave the chip's register untouched. Now the userspace part can
206 determine the cause of the interrupt, but it cannot re-enable
207 interrupts. Another cornercase is chips where re-enabling interrupts
208 is a read-modify-write operation to a combined IRQ status/acknowledge
209 register. This would be racy if a new interrupt occurred
210 simultaneously.
211 </para>
212 <para>
213 To address these problems, UIO also implements a write() function. It
214 is normally not used and can be ignored for hardware that has only a
215 single interrupt source or has separate IRQ mask and status registers.
216 If you need it, however, a write to <filename>/dev/uioX</filename>
217 will call the <function>irqcontrol()</function> function implemented
218 by the driver. You have to write a 32-bit value that is usually either
219 0 or 1 to disable or enable interrupts. If a driver does not implement
220 <function>irqcontrol()</function>, <function>write()</function> will
221 return with <varname>-ENOSYS</varname>.
222 </para>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100223
224 <para>
225 To handle interrupts properly, your custom kernel module can
226 provide its own interrupt handler. It will automatically be
227 called by the built-in handler.
228 </para>
229
230 <para>
231 For cards that don't generate interrupts but need to be
232 polled, there is the possibility to set up a timer that
233 triggers the interrupt handler at configurable time intervals.
Hans J Koched423c22007-11-26 22:03:29 +0100234 This interrupt simulation is done by calling
235 <function>uio_event_notify()</function>
236 from the timer's event handler.
Hans J. Koche3e0a282006-12-11 16:59:59 +0100237 </para>
238
239 <para>
240 Each driver provides attributes that are used to read or write
241 variables. These attributes are accessible through sysfs
242 files. A custom kernel driver module can add its own
243 attributes to the device owned by the uio driver, but not added
244 to the UIO device itself at this time. This might change in the
245 future if it would be found to be useful.
246 </para>
247
248 <para>
249 The following standard attributes are provided by the UIO
250 framework:
251 </para>
252<itemizedlist>
253<listitem>
254 <para>
255 <filename>name</filename>: The name of your device. It is
256 recommended to use the name of your kernel module for this.
257 </para>
258</listitem>
259<listitem>
260 <para>
261 <filename>version</filename>: A version string defined by your
262 driver. This allows the user space part of your driver to deal
263 with different versions of the kernel module.
264 </para>
265</listitem>
266<listitem>
267 <para>
268 <filename>event</filename>: The total number of interrupts
269 handled by the driver since the last time the device node was
270 read.
271 </para>
272</listitem>
273</itemizedlist>
274<para>
275 These attributes appear under the
276 <filename>/sys/class/uio/uioX</filename> directory. Please
277 note that this directory might be a symlink, and not a real
278 directory. Any userspace code that accesses it must be able
279 to handle this.
280</para>
281<para>
282 Each UIO device can make one or more memory regions available for
283 memory mapping. This is necessary because some industrial I/O cards
284 require access to more than one PCI memory region in a driver.
285</para>
286<para>
287 Each mapping has its own directory in sysfs, the first mapping
288 appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>.
289 Subsequent mappings create directories <filename>map1/</filename>,
290 <filename>map2/</filename>, and so on. These directories will only
291 appear if the size of the mapping is not 0.
292</para>
293<para>
294 Each <filename>mapX/</filename> directory contains two read-only files
295 that show start address and size of the memory:
296</para>
297<itemizedlist>
298<listitem>
299 <para>
300 <filename>addr</filename>: The address of memory that can be mapped.
301 </para>
302</listitem>
303<listitem>
304 <para>
305 <filename>size</filename>: The size, in bytes, of the memory
306 pointed to by addr.
307 </para>
308</listitem>
309</itemizedlist>
310
311<para>
312 From userspace, the different mappings are distinguished by adjusting
313 the <varname>offset</varname> parameter of the
314 <function>mmap()</function> call. To map the memory of mapping N, you
315 have to use N times the page size as your offset:
316</para>
317<programlisting format="linespecific">
318offset = N * getpagesize();
319</programlisting>
320
321</sect1>
322</chapter>
323
Hans J. Koche3e0a282006-12-11 16:59:59 +0100324<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
325<?dbhtml filename="custom_kernel_module.html"?>
326<title>Writing your own kernel module</title>
327 <para>
Hans J Koched423c22007-11-26 22:03:29 +0100328 Please have a look at <filename>uio_cif.c</filename> as an
Hans J. Koche3e0a282006-12-11 16:59:59 +0100329 example. The following paragraphs explain the different
330 sections of this file.
331 </para>
332
333<sect1 id="uio_info">
334<title>struct uio_info</title>
335 <para>
336 This structure tells the framework the details of your driver,
337 Some of the members are required, others are optional.
338 </para>
339
340<itemizedlist>
341<listitem><para>
342<varname>char *name</varname>: Required. The name of your driver as
343it will appear in sysfs. I recommend using the name of your module for this.
344</para></listitem>
345
346<listitem><para>
347<varname>char *version</varname>: Required. This string appears in
348<filename>/sys/class/uio/uioX/version</filename>.
349</para></listitem>
350
351<listitem><para>
352<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you
353have memory that can be mapped with <function>mmap()</function>. For each
354mapping you need to fill one of the <varname>uio_mem</varname> structures.
355See the description below for details.
356</para></listitem>
357
358<listitem><para>
359<varname>long irq</varname>: Required. If your hardware generates an
360interrupt, it's your modules task to determine the irq number during
361initialization. If you don't have a hardware generated interrupt but
362want to trigger the interrupt handler in some other way, set
Hans J Koched423c22007-11-26 22:03:29 +0100363<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
364If you had no interrupt at all, you could set
Hans J. Koche3e0a282006-12-11 16:59:59 +0100365<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
366rarely makes sense.
367</para></listitem>
368
369<listitem><para>
370<varname>unsigned long irq_flags</varname>: Required if you've set
371<varname>irq</varname> to a hardware interrupt number. The flags given
372here will be used in the call to <function>request_irq()</function>.
373</para></listitem>
374
375<listitem><para>
376<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct
377*vma)</varname>: Optional. If you need a special
378<function>mmap()</function> function, you can set it here. If this
379pointer is not NULL, your <function>mmap()</function> will be called
380instead of the built-in one.
381</para></listitem>
382
383<listitem><para>
384<varname>int (*open)(struct uio_info *info, struct inode *inode)
385</varname>: Optional. You might want to have your own
386<function>open()</function>, e.g. to enable interrupts only when your
387device is actually used.
388</para></listitem>
389
390<listitem><para>
391<varname>int (*release)(struct uio_info *info, struct inode *inode)
392</varname>: Optional. If you define your own
393<function>open()</function>, you will probably also want a custom
394<function>release()</function> function.
395</para></listitem>
Hans J. Koch328a14e2008-05-23 13:50:14 +0200396
397<listitem><para>
398<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)
399</varname>: Optional. If you need to be able to enable or disable
400interrupts from userspace by writing to <filename>/dev/uioX</filename>,
401you can implement this function. The parameter <varname>irq_on</varname>
402will be 0 to disable interrupts and 1 to enable them.
403</para></listitem>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100404</itemizedlist>
405
406<para>
407Usually, your device will have one or more memory regions that can be mapped
408to user space. For each region, you have to set up a
409<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array.
410Here's a description of the fields of <varname>struct uio_mem</varname>:
411</para>
412
413<itemizedlist>
414<listitem><para>
415<varname>int memtype</varname>: Required if the mapping is used. Set this to
416<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
417card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
418memory (e.g. allocated with <function>kmalloc()</function>). There's also
419<varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
420</para></listitem>
421
422<listitem><para>
423<varname>unsigned long addr</varname>: Required if the mapping is used.
424Fill in the address of your memory block. This address is the one that
425appears in sysfs.
426</para></listitem>
427
428<listitem><para>
429<varname>unsigned long size</varname>: Fill in the size of the
430memory block that <varname>addr</varname> points to. If <varname>size</varname>
431is zero, the mapping is considered unused. Note that you
432<emphasis>must</emphasis> initialize <varname>size</varname> with zero for
433all unused mappings.
434</para></listitem>
435
436<listitem><para>
437<varname>void *internal_addr</varname>: If you have to access this memory
438region from within your kernel module, you will want to map it internally by
439using something like <function>ioremap()</function>. Addresses
440returned by this function cannot be mapped to user space, so you must not
441store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
442instead to remember such an address.
443</para></listitem>
444</itemizedlist>
445
446<para>
447Please do not touch the <varname>kobj</varname> element of
448<varname>struct uio_mem</varname>! It is used by the UIO framework
449to set up sysfs files for this mapping. Simply leave it alone.
450</para>
451</sect1>
452
453<sect1 id="adding_irq_handler">
454<title>Adding an interrupt handler</title>
455 <para>
456 What you need to do in your interrupt handler depends on your
457 hardware and on how you want to handle it. You should try to
458 keep the amount of code in your kernel interrupt handler low.
459 If your hardware requires no action that you
460 <emphasis>have</emphasis> to perform after each interrupt,
461 then your handler can be empty.</para> <para>If, on the other
462 hand, your hardware <emphasis>needs</emphasis> some action to
463 be performed after each interrupt, then you
464 <emphasis>must</emphasis> do it in your kernel module. Note
465 that you cannot rely on the userspace part of your driver. Your
466 userspace program can terminate at any time, possibly leaving
467 your hardware in a state where proper interrupt handling is
468 still required.
469 </para>
470
471 <para>
472 There might also be applications where you want to read data
473 from your hardware at each interrupt and buffer it in a piece
474 of kernel memory you've allocated for that purpose. With this
475 technique you could avoid loss of data if your userspace
476 program misses an interrupt.
477 </para>
478
479 <para>
480 A note on shared interrupts: Your driver should support
481 interrupt sharing whenever this is possible. It is possible if
482 and only if your driver can detect whether your hardware has
483 triggered the interrupt or not. This is usually done by looking
484 at an interrupt status register. If your driver sees that the
485 IRQ bit is actually set, it will perform its actions, and the
486 handler returns IRQ_HANDLED. If the driver detects that it was
487 not your hardware that caused the interrupt, it will do nothing
488 and return IRQ_NONE, allowing the kernel to call the next
489 possible interrupt handler.
490 </para>
491
492 <para>
493 If you decide not to support shared interrupts, your card
494 won't work in computers with no free interrupts. As this
495 frequently happens on the PC platform, you can save yourself a
496 lot of trouble by supporting interrupt sharing.
497 </para>
498</sect1>
499
500</chapter>
501
502<chapter id="userspace_driver" xreflabel="Writing a driver in user space">
503<?dbhtml filename="userspace_driver.html"?>
504<title>Writing a driver in userspace</title>
505 <para>
506 Once you have a working kernel module for your hardware, you can
507 write the userspace part of your driver. You don't need any special
508 libraries, your driver can be written in any reasonable language,
509 you can use floating point numbers and so on. In short, you can
510 use all the tools and libraries you'd normally use for writing a
511 userspace application.
512 </para>
513
514<sect1 id="getting_uio_information">
515<title>Getting information about your UIO device</title>
516 <para>
517 Information about all UIO devices is available in sysfs. The
518 first thing you should do in your driver is check
519 <varname>name</varname> and <varname>version</varname> to
520 make sure your talking to the right device and that its kernel
521 driver has the version you expect.
522 </para>
523 <para>
524 You should also make sure that the memory mapping you need
525 exists and has the size you expect.
526 </para>
527 <para>
528 There is a tool called <varname>lsuio</varname> that lists
529 UIO devices and their attributes. It is available here:
530 </para>
531 <para>
532 <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
533 http://www.osadl.org/projects/downloads/UIO/user/</ulink>
534 </para>
535 <para>
536 With <varname>lsuio</varname> you can quickly check if your
537 kernel module is loaded and which attributes it exports.
538 Have a look at the manpage for details.
539 </para>
540 <para>
541 The source code of <varname>lsuio</varname> can serve as an
542 example for getting information about an UIO device.
543 The file <filename>uio_helper.c</filename> contains a lot of
544 functions you could use in your userspace driver code.
545 </para>
546</sect1>
547
548<sect1 id="mmap_device_memory">
549<title>mmap() device memory</title>
550 <para>
551 After you made sure you've got the right device with the
552 memory mappings you need, all you have to do is to call
553 <function>mmap()</function> to map the device's memory
554 to userspace.
555 </para>
556 <para>
557 The parameter <varname>offset</varname> of the
558 <function>mmap()</function> call has a special meaning
559 for UIO devices: It is used to select which mapping of
560 your device you want to map. To map the memory of
561 mapping N, you have to use N times the page size as
562 your offset:
563 </para>
564<programlisting format="linespecific">
565 offset = N * getpagesize();
566</programlisting>
567 <para>
568 N starts from zero, so if you've got only one memory
569 range to map, set <varname>offset = 0</varname>.
570 A drawback of this technique is that memory is always
571 mapped beginning with its start address.
572 </para>
573</sect1>
574
575<sect1 id="wait_for_interrupts">
576<title>Waiting for interrupts</title>
577 <para>
578 After you successfully mapped your devices memory, you
579 can access it like an ordinary array. Usually, you will
580 perform some initialization. After that, your hardware
581 starts working and will generate an interrupt as soon
582 as it's finished, has some data available, or needs your
583 attention because an error occured.
584 </para>
585 <para>
586 <filename>/dev/uioX</filename> is a read-only file. A
587 <function>read()</function> will always block until an
588 interrupt occurs. There is only one legal value for the
589 <varname>count</varname> parameter of
590 <function>read()</function>, and that is the size of a
591 signed 32 bit integer (4). Any other value for
592 <varname>count</varname> causes <function>read()</function>
593 to fail. The signed 32 bit integer read is the interrupt
594 count of your device. If the value is one more than the value
595 you read the last time, everything is OK. If the difference
596 is greater than one, you missed interrupts.
597 </para>
598 <para>
599 You can also use <function>select()</function> on
600 <filename>/dev/uioX</filename>.
601 </para>
602</sect1>
603
604</chapter>
605
606<appendix id="app1">
607<title>Further information</title>
608<itemizedlist>
609 <listitem><para>
610 <ulink url="http://www.osadl.org">
611 OSADL homepage.</ulink>
612 </para></listitem>
613 <listitem><para>
614 <ulink url="http://www.linutronix.de">
615 Linutronix homepage.</ulink>
616 </para></listitem>
617</itemizedlist>
618</appendix>
619
620</book>