Eric Lee / linux-smarc-t335x-v3.2

Download as
Browse Code »

Commit b8ac9fc0e8cda9f9776019c5b0464b0c6d2d4c90

Authored by Stephen Rothwell
Committed by Greg Kroah-Hartman
1 parent a2ab3d3000
Exists in master and in 4 other branches v3.2_AM335xPSP_04.06.00.11, v3.2_NEWT335xPSP_04.06.00.11, v3.2_SBC_SMARTMEN, v3.2_SMARCT335xPSP_04.06.00.11

uio: make uio_info's name and version const 

These are only ever assigned constant strings and never modified.

This was noticed because Wolfram Sang needed to cast the result of
of_get_property() in order to assign it to the name field of a struct
uio_info.

Signed-off-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Hans J. Koch <hjk@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

Showing 2 changed files with 4 additions and 4 deletions Inline Diff

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