UIO: Add write function to allow irq masking
[linux-2.6.git] / Documentation / DocBook / uio-howto.tmpl
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []>
4
5 <book id="index">
6 <bookinfo>
7 <title>The Userspace I/O HOWTO</title>
8
9 <author>
10       <firstname>Hans-Jürgen</firstname>
11       <surname>Koch</surname>
12       <authorblurb><para>Linux developer, Linutronix</para></authorblurb>
13         <affiliation>
14         <orgname>
15                 <ulink url="http://www.linutronix.de">Linutronix</ulink>
16         </orgname>
17
18         <address>
19            <email>hjk@linutronix.de</email>
20         </address>
21     </affiliation>
22 </author>
23
24 <pubdate>2006-12-11</pubdate>
25
26 <abstract>
27         <para>This HOWTO describes concept and usage of Linux kernel's
28                 Userspace I/O system.</para>
29 </abstract>
30
31 <revhistory>
32         <revision>
33         <revnumber>0.5</revnumber>
34         <date>2008-05-22</date>
35         <authorinitials>hjk</authorinitials>
36         <revremark>Added description of write() function.</revremark>
37         </revision>
38         <revision>
39         <revnumber>0.4</revnumber>
40         <date>2007-11-26</date>
41         <authorinitials>hjk</authorinitials>
42         <revremark>Removed section about uio_dummy.</revremark>
43         </revision>
44         <revision>
45         <revnumber>0.3</revnumber>
46         <date>2007-04-29</date>
47         <authorinitials>hjk</authorinitials>
48         <revremark>Added section about userspace drivers.</revremark>
49         </revision>
50         <revision>
51         <revnumber>0.2</revnumber>
52         <date>2007-02-13</date>
53         <authorinitials>hjk</authorinitials>
54         <revremark>Update after multiple mappings were added.</revremark>
55         </revision>
56         <revision>
57         <revnumber>0.1</revnumber>
58         <date>2006-12-11</date>
59         <authorinitials>hjk</authorinitials>
60         <revremark>First draft.</revremark>
61         </revision>
62 </revhistory>
63 </bookinfo>
64
65 <chapter id="aboutthisdoc">
66 <?dbhtml filename="about.html"?>
67 <title>About this document</title>
68
69 <sect1 id="copyright">
70 <?dbhtml filename="copyright.html"?>
71 <title>Copyright and License</title>
72 <para>
73       Copyright (c) 2006-2008 by Hans-Jürgen Koch.</para>
74 <para>
75 This documentation is Free Software licensed under the terms of the
76 GPL version 2.
77 </para>
78 </sect1>
79
80 <sect1 id="translations">
81 <?dbhtml filename="translations.html"?>
82 <title>Translations</title>
83
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>.
87 </para>
88 </sect1>
89
90 <sect1 id="preface">
91 <title>Preface</title>
92         <para>
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.
101         </para>
102         <para>
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.
108         </para>
109         <para>
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
114         the following:
115         </para>
116 <itemizedlist>
117 <listitem>
118         <para>The device has memory that can be mapped. The device can be
119         controlled completely by writing to this memory.</para>
120 </listitem>
121 <listitem>
122         <para>The device usually generates interrupts.</para>
123 </listitem>
124 <listitem>
125         <para>The device does not fit into one of the standard kernel
126         subsystems.</para>
127 </listitem>
128 </itemizedlist>
129 </sect1>
130
131 <sect1 id="thanks">
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
136         information.</para>
137 </sect1>
138
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>
144 </sect1>
145 </chapter>
146
147 <chapter id="about">
148 <?dbhtml filename="about.html"?>
149 <title>About UIO</title>
150
151 <para>If you use UIO for your card's driver, here's what you get:</para>
152
153 <itemizedlist>
154 <listitem>
155         <para>only one small kernel module to write and maintain.</para>
156 </listitem>
157 <listitem>
158         <para>develop the main part of your driver in user space,
159         with all the tools and libraries you're used to.</para>
160 </listitem>
161 <listitem>
162         <para>bugs in your driver won't crash the kernel.</para>
163 </listitem>
164 <listitem>
165         <para>updates of your driver can take place without recompiling
166         the kernel.</para>
167 </listitem>
168 </itemizedlist>
169
170 <sect1 id="how_uio_works">
171 <title>How UIO works</title>
172         <para>
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.
178         </para>
179
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.
184         </para>
185
186         <para>
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.
197         </para>
198         <para>
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
209         simultaneously.
210         </para>
211         <para>
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>.
221         </para>
222
223         <para>
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.
227         </para>
228
229         <para>
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.
236         </para>
237
238         <para>
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.
245         </para>
246
247         <para>
248         The following standard attributes are provided by the UIO
249         framework:
250         </para>
251 <itemizedlist>
252 <listitem>
253         <para>
254         <filename>name</filename>: The name of your device. It is
255         recommended to use the name of your kernel module for this.
256         </para>
257 </listitem>
258 <listitem>
259         <para>
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.
263         </para>
264 </listitem>
265 <listitem>
266         <para>
267         <filename>event</filename>: The total number of interrupts
268         handled by the driver since the last time the device node was
269         read.
270         </para>
271 </listitem>
272 </itemizedlist>
273 <para>
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
278         to handle this.
279 </para>
280 <para>
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.
284 </para>
285 <para>
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.
291 </para>
292 <para>
293         Each <filename>mapX/</filename> directory contains two read-only files
294         that show start address and size of the memory:
295 </para>
296 <itemizedlist>
297 <listitem>
298         <para>
299         <filename>addr</filename>: The address of memory that can be mapped.
300         </para>
301 </listitem>
302 <listitem>
303         <para>
304         <filename>size</filename>: The size, in bytes, of the memory
305         pointed to by addr.
306         </para>
307 </listitem>
308 </itemizedlist>
309
310 <para>
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:
315 </para>
316 <programlisting format="linespecific">
317 offset = N * getpagesize();
318 </programlisting>
319
320 </sect1>
321 </chapter>
322
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>
326         <para>
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.
330         </para>
331
332 <sect1 id="uio_info">
333 <title>struct uio_info</title>
334         <para>
335         This structure tells the framework the details of your driver,
336         Some of the members are required, others are optional.
337         </para>
338
339 <itemizedlist>
340 <listitem><para>
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.
343 </para></listitem>
344
345 <listitem><para>
346 <varname>char *version</varname>: Required. This string appears in
347 <filename>/sys/class/uio/uioX/version</filename>.
348 </para></listitem>
349
350 <listitem><para>
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.
355 </para></listitem>
356
357 <listitem><para>
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
365 rarely makes sense.
366 </para></listitem>
367
368 <listitem><para>
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>.
372 </para></listitem>
373
374 <listitem><para>
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.
380 </para></listitem>
381
382 <listitem><para>
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.
387 </para></listitem>
388
389 <listitem><para>
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.
394 </para></listitem>
395
396 <listitem><para>
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.
402 </para></listitem>
403 </itemizedlist>
404
405 <para>
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>:
410 </para>
411
412 <itemizedlist>
413 <listitem><para>
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.
419 </para></listitem>
420
421 <listitem><para>
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
424 appears in sysfs.
425 </para></listitem>
426
427 <listitem><para>
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
432 all unused mappings.
433 </para></listitem>
434
435 <listitem><para>
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.
442 </para></listitem>
443 </itemizedlist>
444
445 <para>
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.
449 </para>
450 </sect1>
451
452 <sect1 id="adding_irq_handler">
453 <title>Adding an interrupt handler</title>
454         <para>
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
467         still required.
468         </para>
469
470         <para>
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.
476         </para>
477
478         <para>
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.
489         </para>
490
491         <para>
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.
496         </para>
497 </sect1>
498
499 </chapter>
500
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>
504         <para>
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.
511         </para>
512
513 <sect1 id="getting_uio_information">
514 <title>Getting information about your UIO device</title>
515         <para>
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.
521         </para>
522         <para>
523         You should also make sure that the memory mapping you need
524         exists and has the size you expect.
525         </para>
526         <para>
527         There is a tool called <varname>lsuio</varname> that lists
528         UIO devices and their attributes. It is available here:
529         </para>
530         <para>
531         <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
532                 http://www.osadl.org/projects/downloads/UIO/user/</ulink>
533         </para>
534         <para>
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.
538         </para>
539         <para>
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.
544         </para>
545 </sect1>
546
547 <sect1 id="mmap_device_memory">
548 <title>mmap() device memory</title>
549         <para>
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
553         to userspace.
554         </para>
555         <para>
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
561         your offset:
562         </para>
563 <programlisting format="linespecific">
564         offset = N * getpagesize();
565 </programlisting>
566         <para>
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.
571         </para>
572 </sect1>
573
574 <sect1 id="wait_for_interrupts">
575 <title>Waiting for interrupts</title>
576         <para>
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.
583         </para>
584         <para>
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.
596         </para>
597         <para>
598         You can also use <function>select()</function> on
599         <filename>/dev/uioX</filename>.
600         </para>
601 </sect1>
602
603 </chapter>
604
605 <appendix id="app1">
606 <title>Further information</title>
607 <itemizedlist>
608         <listitem><para>
609                         <ulink url="http://www.osadl.org">
610                                 OSADL homepage.</ulink>
611                 </para></listitem>
612         <listitem><para>
613                 <ulink url="http://www.linutronix.de">
614                  Linutronix homepage.</ulink>
615                 </para></listitem>
616 </itemizedlist>
617 </appendix>
618
619 </book>