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