aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Documentation/DocBook/kernel-api.tmpl4
-rw-r--r--Documentation/DocBook/uio-howto.tmpl611
-rw-r--r--drivers/Kconfig1
-rw-r--r--drivers/Makefile1
-rw-r--r--drivers/uio/Kconfig29
-rw-r--r--drivers/uio/Makefile2
-rw-r--r--drivers/uio/uio.c701
-rw-r--r--drivers/uio/uio_cif.c156
-rw-r--r--include/linux/uio_driver.h91
9 files changed, 1596 insertions, 0 deletions
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
index fd2ef4d29b6d..a0af560ed740 100644
--- a/Documentation/DocBook/kernel-api.tmpl
+++ b/Documentation/DocBook/kernel-api.tmpl
@@ -408,6 +408,10 @@ X!Edrivers/pnp/system.c
408!Edrivers/pnp/manager.c 408!Edrivers/pnp/manager.c
409!Edrivers/pnp/support.c 409!Edrivers/pnp/support.c
410 </sect1> 410 </sect1>
411 <sect1><title>Userspace IO devices</title>
412!Edrivers/uio/uio.c
413!Iinclude/linux/uio_driver.h
414 </sect1>
411 </chapter> 415 </chapter>
412 416
413 <chapter id="blkdev"> 417 <chapter id="blkdev">
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