blob: 8f6e3b2403c717f1d6df409440773b898f5af31c [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. Koch82057792009-01-07 00:15:39 +010045 <revnumber>0.8</revnumber>
46 <date>2008-12-24</date>
47 <authorinitials>hjk</authorinitials>
48 <revremark>Added name attributes in mem and portio sysfs directories.
49 </revremark>
50 </revision>
51 <revision>
Hans J. Koch6a1b6992009-01-07 00:12:37 +010052 <revnumber>0.7</revnumber>
53 <date>2008-12-23</date>
54 <authorinitials>hjk</authorinitials>
55 <revremark>Added generic platform drivers and offset attribute.</revremark>
56 </revision>
57 <revision>
Hans J. Kocha2ab3d32008-12-06 02:25:13 +010058 <revnumber>0.6</revnumber>
59 <date>2008-12-05</date>
60 <authorinitials>hjk</authorinitials>
61 <revremark>Added description of portio sysfs attributes.</revremark>
62 </revision>
63 <revision>
Hans J. Koch328a14e2008-05-23 13:50:14 +020064 <revnumber>0.5</revnumber>
65 <date>2008-05-22</date>
66 <authorinitials>hjk</authorinitials>
67 <revremark>Added description of write() function.</revremark>
68 </revision>
69 <revision>
Hans J Koched423c22007-11-26 22:03:29 +010070 <revnumber>0.4</revnumber>
71 <date>2007-11-26</date>
72 <authorinitials>hjk</authorinitials>
73 <revremark>Removed section about uio_dummy.</revremark>
74 </revision>
75 <revision>
Hans J. Koche3e0a282006-12-11 16:59:59 +010076 <revnumber>0.3</revnumber>
77 <date>2007-04-29</date>
78 <authorinitials>hjk</authorinitials>
79 <revremark>Added section about userspace drivers.</revremark>
80 </revision>
81 <revision>
82 <revnumber>0.2</revnumber>
83 <date>2007-02-13</date>
84 <authorinitials>hjk</authorinitials>
85 <revremark>Update after multiple mappings were added.</revremark>
86 </revision>
87 <revision>
88 <revnumber>0.1</revnumber>
89 <date>2006-12-11</date>
90 <authorinitials>hjk</authorinitials>
91 <revremark>First draft.</revremark>
92 </revision>
93</revhistory>
94</bookinfo>
95
96<chapter id="aboutthisdoc">
Mike Frysinger4f7e5302008-06-24 14:25:00 -070097<?dbhtml filename="aboutthis.html"?>
Hans J. Koche3e0a282006-12-11 16:59:59 +010098<title>About this document</title>
99
Hans J. Koche3e0a282006-12-11 16:59:59 +0100100<sect1 id="translations">
101<?dbhtml filename="translations.html"?>
102<title>Translations</title>
103
104<para>If you know of any translations for this document, or you are
105interested in translating it, please email me
106<email>hjk@linutronix.de</email>.
107</para>
108</sect1>
109
110<sect1 id="preface">
111<title>Preface</title>
112 <para>
113 For many types of devices, creating a Linux kernel driver is
114 overkill. All that is really needed is some way to handle an
115 interrupt and provide access to the memory space of the
116 device. The logic of controlling the device does not
117 necessarily have to be within the kernel, as the device does
118 not need to take advantage of any of other resources that the
119 kernel provides. One such common class of devices that are
120 like this are for industrial I/O cards.
121 </para>
122 <para>
123 To address this situation, the userspace I/O system (UIO) was
124 designed. For typical industrial I/O cards, only a very small
125 kernel module is needed. The main part of the driver will run in
126 user space. This simplifies development and reduces the risk of
127 serious bugs within a kernel module.
128 </para>
Hans J Koched423c22007-11-26 22:03:29 +0100129 <para>
130 Please note that UIO is not an universal driver interface. Devices
131 that are already handled well by other kernel subsystems (like
132 networking or serial or USB) are no candidates for an UIO driver.
133 Hardware that is ideally suited for an UIO driver fulfills all of
134 the following:
135 </para>
136<itemizedlist>
137<listitem>
138 <para>The device has memory that can be mapped. The device can be
139 controlled completely by writing to this memory.</para>
140</listitem>
141<listitem>
142 <para>The device usually generates interrupts.</para>
143</listitem>
144<listitem>
145 <para>The device does not fit into one of the standard kernel
146 subsystems.</para>
147</listitem>
148</itemizedlist>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100149</sect1>
150
151<sect1 id="thanks">
152<title>Acknowledgments</title>
153 <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of
154 Linutronix, who have not only written most of the UIO code, but also
155 helped greatly writing this HOWTO by giving me all kinds of background
156 information.</para>
157</sect1>
158
159<sect1 id="feedback">
160<title>Feedback</title>
161 <para>Find something wrong with this document? (Or perhaps something
162 right?) I would love to hear from you. Please email me at
163 <email>hjk@linutronix.de</email>.</para>
164</sect1>
165</chapter>
166
167<chapter id="about">
168<?dbhtml filename="about.html"?>
169<title>About UIO</title>
170
171<para>If you use UIO for your card's driver, here's what you get:</para>
172
173<itemizedlist>
174<listitem>
175 <para>only one small kernel module to write and maintain.</para>
176</listitem>
177<listitem>
178 <para>develop the main part of your driver in user space,
179 with all the tools and libraries you're used to.</para>
180</listitem>
181<listitem>
182 <para>bugs in your driver won't crash the kernel.</para>
183</listitem>
184<listitem>
185 <para>updates of your driver can take place without recompiling
186 the kernel.</para>
187</listitem>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100188</itemizedlist>
189
190<sect1 id="how_uio_works">
191<title>How UIO works</title>
192 <para>
193 Each UIO device is accessed through a device file and several
194 sysfs attribute files. The device file will be called
195 <filename>/dev/uio0</filename> for the first device, and
196 <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename>
197 and so on for subsequent devices.
198 </para>
199
200 <para><filename>/dev/uioX</filename> is used to access the
201 address space of the card. Just use
202 <function>mmap()</function> to access registers or RAM
203 locations of your card.
204 </para>
205
206 <para>
207 Interrupts are handled by reading from
208 <filename>/dev/uioX</filename>. A blocking
209 <function>read()</function> from
210 <filename>/dev/uioX</filename> will return as soon as an
211 interrupt occurs. You can also use
212 <function>select()</function> on
213 <filename>/dev/uioX</filename> to wait for an interrupt. The
214 integer value read from <filename>/dev/uioX</filename>
215 represents the total interrupt count. You can use this number
216 to figure out if you missed some interrupts.
217 </para>
Hans J. Koch328a14e2008-05-23 13:50:14 +0200218 <para>
219 For some hardware that has more than one interrupt source internally,
220 but not separate IRQ mask and status registers, there might be
221 situations where userspace cannot determine what the interrupt source
222 was if the kernel handler disables them by writing to the chip's IRQ
223 register. In such a case, the kernel has to disable the IRQ completely
224 to leave the chip's register untouched. Now the userspace part can
225 determine the cause of the interrupt, but it cannot re-enable
226 interrupts. Another cornercase is chips where re-enabling interrupts
227 is a read-modify-write operation to a combined IRQ status/acknowledge
228 register. This would be racy if a new interrupt occurred
229 simultaneously.
230 </para>
231 <para>
232 To address these problems, UIO also implements a write() function. It
233 is normally not used and can be ignored for hardware that has only a
234 single interrupt source or has separate IRQ mask and status registers.
235 If you need it, however, a write to <filename>/dev/uioX</filename>
236 will call the <function>irqcontrol()</function> function implemented
237 by the driver. You have to write a 32-bit value that is usually either
238 0 or 1 to disable or enable interrupts. If a driver does not implement
239 <function>irqcontrol()</function>, <function>write()</function> will
240 return with <varname>-ENOSYS</varname>.
241 </para>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100242
243 <para>
244 To handle interrupts properly, your custom kernel module can
245 provide its own interrupt handler. It will automatically be
246 called by the built-in handler.
247 </para>
248
249 <para>
250 For cards that don't generate interrupts but need to be
251 polled, there is the possibility to set up a timer that
252 triggers the interrupt handler at configurable time intervals.
Hans J Koched423c22007-11-26 22:03:29 +0100253 This interrupt simulation is done by calling
254 <function>uio_event_notify()</function>
255 from the timer's event handler.
Hans J. Koche3e0a282006-12-11 16:59:59 +0100256 </para>
257
258 <para>
259 Each driver provides attributes that are used to read or write
260 variables. These attributes are accessible through sysfs
261 files. A custom kernel driver module can add its own
262 attributes to the device owned by the uio driver, but not added
263 to the UIO device itself at this time. This might change in the
264 future if it would be found to be useful.
265 </para>
266
267 <para>
268 The following standard attributes are provided by the UIO
269 framework:
270 </para>
271<itemizedlist>
272<listitem>
273 <para>
274 <filename>name</filename>: The name of your device. It is
275 recommended to use the name of your kernel module for this.
276 </para>
277</listitem>
278<listitem>
279 <para>
280 <filename>version</filename>: A version string defined by your
281 driver. This allows the user space part of your driver to deal
282 with different versions of the kernel module.
283 </para>
284</listitem>
285<listitem>
286 <para>
287 <filename>event</filename>: The total number of interrupts
288 handled by the driver since the last time the device node was
289 read.
290 </para>
291</listitem>
292</itemizedlist>
293<para>
294 These attributes appear under the
295 <filename>/sys/class/uio/uioX</filename> directory. Please
296 note that this directory might be a symlink, and not a real
297 directory. Any userspace code that accesses it must be able
298 to handle this.
299</para>
300<para>
301 Each UIO device can make one or more memory regions available for
302 memory mapping. This is necessary because some industrial I/O cards
303 require access to more than one PCI memory region in a driver.
304</para>
305<para>
306 Each mapping has its own directory in sysfs, the first mapping
307 appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>.
308 Subsequent mappings create directories <filename>map1/</filename>,
309 <filename>map2/</filename>, and so on. These directories will only
310 appear if the size of the mapping is not 0.
311</para>
312<para>
Hans J. Koch82057792009-01-07 00:15:39 +0100313 Each <filename>mapX/</filename> directory contains four read-only files
314 that show attributes of the memory:
Hans J. Koche3e0a282006-12-11 16:59:59 +0100315</para>
316<itemizedlist>
317<listitem>
318 <para>
Hans J. Koch82057792009-01-07 00:15:39 +0100319 <filename>name</filename>: A string identifier for this mapping. This
320 is optional, the string can be empty. Drivers can set this to make it
321 easier for userspace to find the correct mapping.
322 </para>
323</listitem>
324<listitem>
325 <para>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100326 <filename>addr</filename>: The address of memory that can be mapped.
327 </para>
328</listitem>
329<listitem>
330 <para>
331 <filename>size</filename>: The size, in bytes, of the memory
332 pointed to by addr.
333 </para>
334</listitem>
Hans J. Koch6a1b6992009-01-07 00:12:37 +0100335<listitem>
336 <para>
337 <filename>offset</filename>: The offset, in bytes, that has to be
338 added to the pointer returned by <function>mmap()</function> to get
339 to the actual device memory. This is important if the device's memory
340 is not page aligned. Remember that pointers returned by
341 <function>mmap()</function> are always page aligned, so it is good
342 style to always add this offset.
343 </para>
344</listitem>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100345</itemizedlist>
346
347<para>
348 From userspace, the different mappings are distinguished by adjusting
349 the <varname>offset</varname> parameter of the
350 <function>mmap()</function> call. To map the memory of mapping N, you
351 have to use N times the page size as your offset:
352</para>
353<programlisting format="linespecific">
354offset = N * getpagesize();
355</programlisting>
356
Hans J. Kocha2ab3d32008-12-06 02:25:13 +0100357<para>
358 Sometimes there is hardware with memory-like regions that can not be
359 mapped with the technique described here, but there are still ways to
360 access them from userspace. The most common example are x86 ioports.
361 On x86 systems, userspace can access these ioports using
362 <function>ioperm()</function>, <function>iopl()</function>,
363 <function>inb()</function>, <function>outb()</function>, and similar
364 functions.
365</para>
366<para>
367 Since these ioport regions can not be mapped, they will not appear under
368 <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory
369 described above. Without information about the port regions a hardware
370 has to offer, it becomes difficult for the userspace part of the
371 driver to find out which ports belong to which UIO device.
372</para>
373<para>
374 To address this situation, the new directory
375 <filename>/sys/class/uio/uioX/portio/</filename> was added. It only
376 exists if the driver wants to pass information about one or more port
377 regions to userspace. If that is the case, subdirectories named
378 <filename>port0</filename>, <filename>port1</filename>, and so on,
379 will appear underneath
380 <filename>/sys/class/uio/uioX/portio/</filename>.
381</para>
382<para>
Hans J. Koch82057792009-01-07 00:15:39 +0100383 Each <filename>portX/</filename> directory contains four read-only
384 files that show name, start, size, and type of the port region:
Hans J. Kocha2ab3d32008-12-06 02:25:13 +0100385</para>
386<itemizedlist>
387<listitem>
388 <para>
Hans J. Koch82057792009-01-07 00:15:39 +0100389 <filename>name</filename>: A string identifier for this port region.
390 The string is optional and can be empty. Drivers can set it to make it
391 easier for userspace to find a certain port region.
392 </para>
393</listitem>
394<listitem>
395 <para>
Hans J. Kocha2ab3d32008-12-06 02:25:13 +0100396 <filename>start</filename>: The first port of this region.
397 </para>
398</listitem>
399<listitem>
400 <para>
401 <filename>size</filename>: The number of ports in this region.
402 </para>
403</listitem>
404<listitem>
405 <para>
406 <filename>porttype</filename>: A string describing the type of port.
407 </para>
408</listitem>
409</itemizedlist>
410
411
Hans J. Koche3e0a282006-12-11 16:59:59 +0100412</sect1>
413</chapter>
414
Hans J. Koche3e0a282006-12-11 16:59:59 +0100415<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
416<?dbhtml filename="custom_kernel_module.html"?>
417<title>Writing your own kernel module</title>
418 <para>
Hans J Koched423c22007-11-26 22:03:29 +0100419 Please have a look at <filename>uio_cif.c</filename> as an
Hans J. Koche3e0a282006-12-11 16:59:59 +0100420 example. The following paragraphs explain the different
421 sections of this file.
422 </para>
423
424<sect1 id="uio_info">
425<title>struct uio_info</title>
426 <para>
427 This structure tells the framework the details of your driver,
428 Some of the members are required, others are optional.
429 </para>
430
431<itemizedlist>
432<listitem><para>
Stephen Rothwellb8ac9fc2008-12-12 11:44:21 +0100433<varname>const char *name</varname>: Required. The name of your driver as
Hans J. Koche3e0a282006-12-11 16:59:59 +0100434it will appear in sysfs. I recommend using the name of your module for this.
435</para></listitem>
436
437<listitem><para>
Stephen Rothwellb8ac9fc2008-12-12 11:44:21 +0100438<varname>const char *version</varname>: Required. This string appears in
Hans J. Koche3e0a282006-12-11 16:59:59 +0100439<filename>/sys/class/uio/uioX/version</filename>.
440</para></listitem>
441
442<listitem><para>
443<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you
444have memory that can be mapped with <function>mmap()</function>. For each
445mapping you need to fill one of the <varname>uio_mem</varname> structures.
446See the description below for details.
447</para></listitem>
448
449<listitem><para>
Hans J. Kocha2ab3d32008-12-06 02:25:13 +0100450<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
451if you want to pass information about ioports to userspace. For each port
452region you need to fill one of the <varname>uio_port</varname> structures.
453See the description below for details.
454</para></listitem>
455
456<listitem><para>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100457<varname>long irq</varname>: Required. If your hardware generates an
458interrupt, it's your modules task to determine the irq number during
459initialization. If you don't have a hardware generated interrupt but
460want to trigger the interrupt handler in some other way, set
Hans J Koched423c22007-11-26 22:03:29 +0100461<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
462If you had no interrupt at all, you could set
Hans J. Koche3e0a282006-12-11 16:59:59 +0100463<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
464rarely makes sense.
465</para></listitem>
466
467<listitem><para>
468<varname>unsigned long irq_flags</varname>: Required if you've set
469<varname>irq</varname> to a hardware interrupt number. The flags given
470here will be used in the call to <function>request_irq()</function>.
471</para></listitem>
472
473<listitem><para>
474<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct
475*vma)</varname>: Optional. If you need a special
476<function>mmap()</function> function, you can set it here. If this
477pointer is not NULL, your <function>mmap()</function> will be called
478instead of the built-in one.
479</para></listitem>
480
481<listitem><para>
482<varname>int (*open)(struct uio_info *info, struct inode *inode)
483</varname>: Optional. You might want to have your own
484<function>open()</function>, e.g. to enable interrupts only when your
485device is actually used.
486</para></listitem>
487
488<listitem><para>
489<varname>int (*release)(struct uio_info *info, struct inode *inode)
490</varname>: Optional. If you define your own
491<function>open()</function>, you will probably also want a custom
492<function>release()</function> function.
493</para></listitem>
Hans J. Koch328a14e2008-05-23 13:50:14 +0200494
495<listitem><para>
496<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)
497</varname>: Optional. If you need to be able to enable or disable
498interrupts from userspace by writing to <filename>/dev/uioX</filename>,
499you can implement this function. The parameter <varname>irq_on</varname>
500will be 0 to disable interrupts and 1 to enable them.
501</para></listitem>
Hans J. Koche3e0a282006-12-11 16:59:59 +0100502</itemizedlist>
503
504<para>
505Usually, your device will have one or more memory regions that can be mapped
506to user space. For each region, you have to set up a
507<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array.
508Here's a description of the fields of <varname>struct uio_mem</varname>:
509</para>
510
511<itemizedlist>
512<listitem><para>
513<varname>int memtype</varname>: Required if the mapping is used. Set this to
514<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
515card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
516memory (e.g. allocated with <function>kmalloc()</function>). There's also
517<varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
518</para></listitem>
519
520<listitem><para>
521<varname>unsigned long addr</varname>: Required if the mapping is used.
522Fill in the address of your memory block. This address is the one that
523appears in sysfs.
524</para></listitem>
525
526<listitem><para>
527<varname>unsigned long size</varname>: Fill in the size of the
528memory block that <varname>addr</varname> points to. If <varname>size</varname>
529is zero, the mapping is considered unused. Note that you
530<emphasis>must</emphasis> initialize <varname>size</varname> with zero for
531all unused mappings.
532</para></listitem>
533
534<listitem><para>
535<varname>void *internal_addr</varname>: If you have to access this memory
536region from within your kernel module, you will want to map it internally by
537using something like <function>ioremap()</function>. Addresses
538returned by this function cannot be mapped to user space, so you must not
539store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
540instead to remember such an address.
541</para></listitem>
542</itemizedlist>
543
544<para>
545Please do not touch the <varname>kobj</varname> element of
546<varname>struct uio_mem</varname>! It is used by the UIO framework
547to set up sysfs files for this mapping. Simply leave it alone.
548</para>
Hans J. Kocha2ab3d32008-12-06 02:25:13 +0100549
550<para>
551Sometimes, your device can have one or more port regions which can not be
552mapped to userspace. But if there are other possibilities for userspace to
553access these ports, it makes sense to make information about the ports
554available in sysfs. For each region, you have to set up a
555<varname>struct uio_port</varname> in the <varname>port[]</varname> array.
556Here's a description of the fields of <varname>struct uio_port</varname>:
557</para>
558
559<itemizedlist>
560<listitem><para>
561<varname>char *porttype</varname>: Required. Set this to one of the predefined
562constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
563architectures.
564</para></listitem>
565
566<listitem><para>
567<varname>unsigned long start</varname>: Required if the port region is used.
568Fill in the number of the first port of this region.
569</para></listitem>
570
571<listitem><para>
572<varname>unsigned long size</varname>: Fill in the number of ports in this
573region. If <varname>size</varname> is zero, the region is considered unused.
574Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
575with zero for all unused regions.
576</para></listitem>
577</itemizedlist>
578
579<para>
580Please do not touch the <varname>portio</varname> element of
581<varname>struct uio_port</varname>! It is used internally by the UIO
582framework to set up sysfs files for this region. Simply leave it alone.
583</para>
584
Hans J. Koche3e0a282006-12-11 16:59:59 +0100585</sect1>
586
587<sect1 id="adding_irq_handler">
588<title>Adding an interrupt handler</title>
589 <para>
590 What you need to do in your interrupt handler depends on your
591 hardware and on how you want to handle it. You should try to
592 keep the amount of code in your kernel interrupt handler low.
593 If your hardware requires no action that you
594 <emphasis>have</emphasis> to perform after each interrupt,
595 then your handler can be empty.</para> <para>If, on the other
596 hand, your hardware <emphasis>needs</emphasis> some action to
597 be performed after each interrupt, then you
598 <emphasis>must</emphasis> do it in your kernel module. Note
599 that you cannot rely on the userspace part of your driver. Your
600 userspace program can terminate at any time, possibly leaving
601 your hardware in a state where proper interrupt handling is
602 still required.
603 </para>
604
605 <para>
606 There might also be applications where you want to read data
607 from your hardware at each interrupt and buffer it in a piece
608 of kernel memory you've allocated for that purpose. With this
609 technique you could avoid loss of data if your userspace
610 program misses an interrupt.
611 </para>
612
613 <para>
614 A note on shared interrupts: Your driver should support
615 interrupt sharing whenever this is possible. It is possible if
616 and only if your driver can detect whether your hardware has
617 triggered the interrupt or not. This is usually done by looking
618 at an interrupt status register. If your driver sees that the
619 IRQ bit is actually set, it will perform its actions, and the
620 handler returns IRQ_HANDLED. If the driver detects that it was
621 not your hardware that caused the interrupt, it will do nothing
622 and return IRQ_NONE, allowing the kernel to call the next
623 possible interrupt handler.
624 </para>
625
626 <para>
627 If you decide not to support shared interrupts, your card
628 won't work in computers with no free interrupts. As this
629 frequently happens on the PC platform, you can save yourself a
630 lot of trouble by supporting interrupt sharing.
631 </para>
632</sect1>
633
Hans J. Koch6a1b6992009-01-07 00:12:37 +0100634<sect1 id="using_uio_pdrv">
635<title>Using uio_pdrv for platform devices</title>
636 <para>
637 In many cases, UIO drivers for platform devices can be handled in a
638 generic way. In the same place where you define your
639 <varname>struct platform_device</varname>, you simply also implement
640 your interrupt handler and fill your
641 <varname>struct uio_info</varname>. A pointer to this
642 <varname>struct uio_info</varname> is then used as
643 <varname>platform_data</varname> for your platform device.
644 </para>
645 <para>
646 You also need to set up an array of <varname>struct resource</varname>
647 containing addresses and sizes of your memory mappings. This
648 information is passed to the driver using the
649 <varname>.resource</varname> and <varname>.num_resources</varname>
650 elements of <varname>struct platform_device</varname>.
651 </para>
652 <para>
653 You now have to set the <varname>.name</varname> element of
654 <varname>struct platform_device</varname> to
655 <varname>"uio_pdrv"</varname> to use the generic UIO platform device
656 driver. This driver will fill the <varname>mem[]</varname> array
657 according to the resources given, and register the device.
658 </para>
659 <para>
660 The advantage of this approach is that you only have to edit a file
661 you need to edit anyway. You do not have to create an extra driver.
662 </para>
663</sect1>
664
665<sect1 id="using_uio_pdrv_genirq">
666<title>Using uio_pdrv_genirq for platform devices</title>
667 <para>
668 Especially in embedded devices, you frequently find chips where the
669 irq pin is tied to its own dedicated interrupt line. In such cases,
670 where you can be really sure the interrupt is not shared, we can take
671 the concept of <varname>uio_pdrv</varname> one step further and use a
672 generic interrupt handler. That's what
673 <varname>uio_pdrv_genirq</varname> does.
674 </para>
675 <para>
676 The setup for this driver is the same as described above for
677 <varname>uio_pdrv</varname>, except that you do not implement an
678 interrupt handler. The <varname>.handler</varname> element of
679 <varname>struct uio_info</varname> must remain
680 <varname>NULL</varname>. The <varname>.irq_flags</varname> element
681 must not contain <varname>IRQF_SHARED</varname>.
682 </para>
683 <para>
684 You will set the <varname>.name</varname> element of
685 <varname>struct platform_device</varname> to
686 <varname>"uio_pdrv_genirq"</varname> to use this driver.
687 </para>
688 <para>
689 The generic interrupt handler of <varname>uio_pdrv_genirq</varname>
690 will simply disable the interrupt line using
691 <function>disable_irq_nosync()</function>. After doing its work,
692 userspace can reenable the interrupt by writing 0x00000001 to the UIO
693 device file. The driver already implements an
694 <function>irq_control()</function> to make this possible, you must not
695 implement your own.
696 </para>
697 <para>
698 Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of
699 interrupt handler code. You also do not need to know anything about
700 the chip's internal registers to create the kernel part of the driver.
701 All you need to know is the irq number of the pin the chip is
702 connected to.
703 </para>
704</sect1>
705
Hans J. Koche3e0a282006-12-11 16:59:59 +0100706</chapter>
707
708<chapter id="userspace_driver" xreflabel="Writing a driver in user space">
709<?dbhtml filename="userspace_driver.html"?>
710<title>Writing a driver in userspace</title>
711 <para>
712 Once you have a working kernel module for your hardware, you can
713 write the userspace part of your driver. You don't need any special
714 libraries, your driver can be written in any reasonable language,
715 you can use floating point numbers and so on. In short, you can
716 use all the tools and libraries you'd normally use for writing a
717 userspace application.
718 </para>
719
720<sect1 id="getting_uio_information">
721<title>Getting information about your UIO device</title>
722 <para>
723 Information about all UIO devices is available in sysfs. The
724 first thing you should do in your driver is check
725 <varname>name</varname> and <varname>version</varname> to
726 make sure your talking to the right device and that its kernel
727 driver has the version you expect.
728 </para>
729 <para>
730 You should also make sure that the memory mapping you need
731 exists and has the size you expect.
732 </para>
733 <para>
734 There is a tool called <varname>lsuio</varname> that lists
735 UIO devices and their attributes. It is available here:
736 </para>
737 <para>
738 <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
739 http://www.osadl.org/projects/downloads/UIO/user/</ulink>
740 </para>
741 <para>
742 With <varname>lsuio</varname> you can quickly check if your
743 kernel module is loaded and which attributes it exports.
744 Have a look at the manpage for details.
745 </para>
746 <para>
747 The source code of <varname>lsuio</varname> can serve as an
748 example for getting information about an UIO device.
749 The file <filename>uio_helper.c</filename> contains a lot of
750 functions you could use in your userspace driver code.
751 </para>
752</sect1>
753
754<sect1 id="mmap_device_memory">
755<title>mmap() device memory</title>
756 <para>
757 After you made sure you've got the right device with the
758 memory mappings you need, all you have to do is to call
759 <function>mmap()</function> to map the device's memory
760 to userspace.
761 </para>
762 <para>
763 The parameter <varname>offset</varname> of the
764 <function>mmap()</function> call has a special meaning
765 for UIO devices: It is used to select which mapping of
766 your device you want to map. To map the memory of
767 mapping N, you have to use N times the page size as
768 your offset:
769 </para>
770<programlisting format="linespecific">
771 offset = N * getpagesize();
772</programlisting>
773 <para>
774 N starts from zero, so if you've got only one memory
775 range to map, set <varname>offset = 0</varname>.
776 A drawback of this technique is that memory is always
777 mapped beginning with its start address.
778 </para>
779</sect1>
780
781<sect1 id="wait_for_interrupts">
782<title>Waiting for interrupts</title>
783 <para>
784 After you successfully mapped your devices memory, you
785 can access it like an ordinary array. Usually, you will
786 perform some initialization. After that, your hardware
787 starts working and will generate an interrupt as soon
788 as it's finished, has some data available, or needs your
789 attention because an error occured.
790 </para>
791 <para>
792 <filename>/dev/uioX</filename> is a read-only file. A
793 <function>read()</function> will always block until an
794 interrupt occurs. There is only one legal value for the
795 <varname>count</varname> parameter of
796 <function>read()</function>, and that is the size of a
797 signed 32 bit integer (4). Any other value for
798 <varname>count</varname> causes <function>read()</function>
799 to fail. The signed 32 bit integer read is the interrupt
800 count of your device. If the value is one more than the value
801 you read the last time, everything is OK. If the difference
802 is greater than one, you missed interrupts.
803 </para>
804 <para>
805 You can also use <function>select()</function> on
806 <filename>/dev/uioX</filename>.
807 </para>
808</sect1>
809
810</chapter>
811
812<appendix id="app1">
813<title>Further information</title>
814<itemizedlist>
815 <listitem><para>
816 <ulink url="http://www.osadl.org">
817 OSADL homepage.</ulink>
818 </para></listitem>
819 <listitem><para>
820 <ulink url="http://www.linutronix.de">
821 Linutronix homepage.</ulink>
822 </para></listitem>
823</itemizedlist>
824</appendix>
825
826</book>