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