Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.
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@hansjkoch.de</email> 20 </address> 21 </affiliation> 22 </author> 23 24 <copyright> 25 <year>2006-2008</year> 26 <holder>Hans-Jürgen Koch.</holder> 27 </copyright> 28 <copyright> 29 <year>2009</year> 30 <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> 31 </copyright> 32 33 <legalnotice> 34 <para> 35 This documentation is Free Software licensed under the terms of the 36 GPL version 2. 37 </para> 38 </legalnotice> 39 40 <pubdate>2006-12-11</pubdate> 41 42 <abstract> 43 <para>This HOWTO describes concept and usage of Linux kernel's 44 Userspace I/O system.</para> 45 </abstract> 46 47 <revhistory> 48 <revision> 49 <revnumber>0.10</revnumber> 50 <date>2016-10-17</date> 51 <authorinitials>sch</authorinitials> 52 <revremark>Added generic hyperv driver 53 </revremark> 54 </revision> 55 <revision> 56 <revnumber>0.9</revnumber> 57 <date>2009-07-16</date> 58 <authorinitials>mst</authorinitials> 59 <revremark>Added generic pci driver 60 </revremark> 61 </revision> 62 <revision> 63 <revnumber>0.8</revnumber> 64 <date>2008-12-24</date> 65 <authorinitials>hjk</authorinitials> 66 <revremark>Added name attributes in mem and portio sysfs directories. 67 </revremark> 68 </revision> 69 <revision> 70 <revnumber>0.7</revnumber> 71 <date>2008-12-23</date> 72 <authorinitials>hjk</authorinitials> 73 <revremark>Added generic platform drivers and offset attribute.</revremark> 74 </revision> 75 <revision> 76 <revnumber>0.6</revnumber> 77 <date>2008-12-05</date> 78 <authorinitials>hjk</authorinitials> 79 <revremark>Added description of portio sysfs attributes.</revremark> 80 </revision> 81 <revision> 82 <revnumber>0.5</revnumber> 83 <date>2008-05-22</date> 84 <authorinitials>hjk</authorinitials> 85 <revremark>Added description of write() function.</revremark> 86 </revision> 87 <revision> 88 <revnumber>0.4</revnumber> 89 <date>2007-11-26</date> 90 <authorinitials>hjk</authorinitials> 91 <revremark>Removed section about uio_dummy.</revremark> 92 </revision> 93 <revision> 94 <revnumber>0.3</revnumber> 95 <date>2007-04-29</date> 96 <authorinitials>hjk</authorinitials> 97 <revremark>Added section about userspace drivers.</revremark> 98 </revision> 99 <revision> 100 <revnumber>0.2</revnumber> 101 <date>2007-02-13</date> 102 <authorinitials>hjk</authorinitials> 103 <revremark>Update after multiple mappings were added.</revremark> 104 </revision> 105 <revision> 106 <revnumber>0.1</revnumber> 107 <date>2006-12-11</date> 108 <authorinitials>hjk</authorinitials> 109 <revremark>First draft.</revremark> 110 </revision> 111 </revhistory> 112 </bookinfo> 113 114 <chapter id="aboutthisdoc"> 115 <?dbhtml filename="aboutthis.html"?> 116 <title>About this document</title> 117 118 <sect1 id="translations"> 119 <?dbhtml filename="translations.html"?> 120 <title>Translations</title> 121 122 <para>If you know of any translations for this document, or you are 123 interested in translating it, please email me 124 <email>hjk@hansjkoch.de</email>. 125 </para> 126 </sect1> 127 128 <sect1 id="preface"> 129 <title>Preface</title> 130 <para> 131 For many types of devices, creating a Linux kernel driver is 132 overkill. All that is really needed is some way to handle an 133 interrupt and provide access to the memory space of the 134 device. The logic of controlling the device does not 135 necessarily have to be within the kernel, as the device does 136 not need to take advantage of any of other resources that the 137 kernel provides. One such common class of devices that are 138 like this are for industrial I/O cards. 139 </para> 140 <para> 141 To address this situation, the userspace I/O system (UIO) was 142 designed. For typical industrial I/O cards, only a very small 143 kernel module is needed. The main part of the driver will run in 144 user space. This simplifies development and reduces the risk of 145 serious bugs within a kernel module. 146 </para> 147 <para> 148 Please note that UIO is not an universal driver interface. Devices 149 that are already handled well by other kernel subsystems (like 150 networking or serial or USB) are no candidates for an UIO driver. 151 Hardware that is ideally suited for an UIO driver fulfills all of 152 the following: 153 </para> 154 <itemizedlist> 155 <listitem> 156 <para>The device has memory that can be mapped. The device can be 157 controlled completely by writing to this memory.</para> 158 </listitem> 159 <listitem> 160 <para>The device usually generates interrupts.</para> 161 </listitem> 162 <listitem> 163 <para>The device does not fit into one of the standard kernel 164 subsystems.</para> 165 </listitem> 166 </itemizedlist> 167 </sect1> 168 169 <sect1 id="thanks"> 170 <title>Acknowledgments</title> 171 <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of 172 Linutronix, who have not only written most of the UIO code, but also 173 helped greatly writing this HOWTO by giving me all kinds of background 174 information.</para> 175 </sect1> 176 177 <sect1 id="feedback"> 178 <title>Feedback</title> 179 <para>Find something wrong with this document? (Or perhaps something 180 right?) I would love to hear from you. Please email me at 181 <email>hjk@hansjkoch.de</email>.</para> 182 </sect1> 183 </chapter> 184 185 <chapter id="about"> 186 <?dbhtml filename="about.html"?> 187 <title>About UIO</title> 188 189 <para>If you use UIO for your card's driver, here's what you get:</para> 190 191 <itemizedlist> 192 <listitem> 193 <para>only one small kernel module to write and maintain.</para> 194 </listitem> 195 <listitem> 196 <para>develop the main part of your driver in user space, 197 with all the tools and libraries you're used to.</para> 198 </listitem> 199 <listitem> 200 <para>bugs in your driver won't crash the kernel.</para> 201 </listitem> 202 <listitem> 203 <para>updates of your driver can take place without recompiling 204 the kernel.</para> 205 </listitem> 206 </itemizedlist> 207 208 <sect1 id="how_uio_works"> 209 <title>How UIO works</title> 210 <para> 211 Each UIO device is accessed through a device file and several 212 sysfs attribute files. The device file will be called 213 <filename>/dev/uio0</filename> for the first device, and 214 <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> 215 and so on for subsequent devices. 216 </para> 217 218 <para><filename>/dev/uioX</filename> is used to access the 219 address space of the card. Just use 220 <function>mmap()</function> to access registers or RAM 221 locations of your card. 222 </para> 223 224 <para> 225 Interrupts are handled by reading from 226 <filename>/dev/uioX</filename>. A blocking 227 <function>read()</function> from 228 <filename>/dev/uioX</filename> will return as soon as an 229 interrupt occurs. You can also use 230 <function>select()</function> on 231 <filename>/dev/uioX</filename> to wait for an interrupt. The 232 integer value read from <filename>/dev/uioX</filename> 233 represents the total interrupt count. You can use this number 234 to figure out if you missed some interrupts. 235 </para> 236 <para> 237 For some hardware that has more than one interrupt source internally, 238 but not separate IRQ mask and status registers, there might be 239 situations where userspace cannot determine what the interrupt source 240 was if the kernel handler disables them by writing to the chip's IRQ 241 register. In such a case, the kernel has to disable the IRQ completely 242 to leave the chip's register untouched. Now the userspace part can 243 determine the cause of the interrupt, but it cannot re-enable 244 interrupts. Another cornercase is chips where re-enabling interrupts 245 is a read-modify-write operation to a combined IRQ status/acknowledge 246 register. This would be racy if a new interrupt occurred 247 simultaneously. 248 </para> 249 <para> 250 To address these problems, UIO also implements a write() function. It 251 is normally not used and can be ignored for hardware that has only a 252 single interrupt source or has separate IRQ mask and status registers. 253 If you need it, however, a write to <filename>/dev/uioX</filename> 254 will call the <function>irqcontrol()</function> function implemented 255 by the driver. You have to write a 32-bit value that is usually either 256 0 or 1 to disable or enable interrupts. If a driver does not implement 257 <function>irqcontrol()</function>, <function>write()</function> will 258 return with <varname>-ENOSYS</varname>. 259 </para> 260 261 <para> 262 To handle interrupts properly, your custom kernel module can 263 provide its own interrupt handler. It will automatically be 264 called by the built-in handler. 265 </para> 266 267 <para> 268 For cards that don't generate interrupts but need to be 269 polled, there is the possibility to set up a timer that 270 triggers the interrupt handler at configurable time intervals. 271 This interrupt simulation is done by calling 272 <function>uio_event_notify()</function> 273 from the timer's event handler. 274 </para> 275 276 <para> 277 Each driver provides attributes that are used to read or write 278 variables. These attributes are accessible through sysfs 279 files. A custom kernel driver module can add its own 280 attributes to the device owned by the uio driver, but not added 281 to the UIO device itself at this time. This might change in the 282 future if it would be found to be useful. 283 </para> 284 285 <para> 286 The following standard attributes are provided by the UIO 287 framework: 288 </para> 289 <itemizedlist> 290 <listitem> 291 <para> 292 <filename>name</filename>: The name of your device. It is 293 recommended to use the name of your kernel module for this. 294 </para> 295 </listitem> 296 <listitem> 297 <para> 298 <filename>version</filename>: A version string defined by your 299 driver. This allows the user space part of your driver to deal 300 with different versions of the kernel module. 301 </para> 302 </listitem> 303 <listitem> 304 <para> 305 <filename>event</filename>: The total number of interrupts 306 handled by the driver since the last time the device node was 307 read. 308 </para> 309 </listitem> 310 </itemizedlist> 311 <para> 312 These attributes appear under the 313 <filename>/sys/class/uio/uioX</filename> directory. Please 314 note that this directory might be a symlink, and not a real 315 directory. Any userspace code that accesses it must be able 316 to handle this. 317 </para> 318 <para> 319 Each UIO device can make one or more memory regions available for 320 memory mapping. This is necessary because some industrial I/O cards 321 require access to more than one PCI memory region in a driver. 322 </para> 323 <para> 324 Each mapping has its own directory in sysfs, the first mapping 325 appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. 326 Subsequent mappings create directories <filename>map1/</filename>, 327 <filename>map2/</filename>, and so on. These directories will only 328 appear if the size of the mapping is not 0. 329 </para> 330 <para> 331 Each <filename>mapX/</filename> directory contains four read-only files 332 that show attributes of the memory: 333 </para> 334 <itemizedlist> 335 <listitem> 336 <para> 337 <filename>name</filename>: A string identifier for this mapping. This 338 is optional, the string can be empty. Drivers can set this to make it 339 easier for userspace to find the correct mapping. 340 </para> 341 </listitem> 342 <listitem> 343 <para> 344 <filename>addr</filename>: The address of memory that can be mapped. 345 </para> 346 </listitem> 347 <listitem> 348 <para> 349 <filename>size</filename>: The size, in bytes, of the memory 350 pointed to by addr. 351 </para> 352 </listitem> 353 <listitem> 354 <para> 355 <filename>offset</filename>: The offset, in bytes, that has to be 356 added to the pointer returned by <function>mmap()</function> to get 357 to the actual device memory. This is important if the device's memory 358 is not page aligned. Remember that pointers returned by 359 <function>mmap()</function> are always page aligned, so it is good 360 style to always add this offset. 361 </para> 362 </listitem> 363 </itemizedlist> 364 365 <para> 366 From userspace, the different mappings are distinguished by adjusting 367 the <varname>offset</varname> parameter of the 368 <function>mmap()</function> call. To map the memory of mapping N, you 369 have to use N times the page size as your offset: 370 </para> 371 <programlisting format="linespecific"> 372 offset = N * getpagesize(); 373 </programlisting> 374 375 <para> 376 Sometimes there is hardware with memory-like regions that can not be 377 mapped with the technique described here, but there are still ways to 378 access them from userspace. The most common example are x86 ioports. 379 On x86 systems, userspace can access these ioports using 380 <function>ioperm()</function>, <function>iopl()</function>, 381 <function>inb()</function>, <function>outb()</function>, and similar 382 functions. 383 </para> 384 <para> 385 Since these ioport regions can not be mapped, they will not appear under 386 <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory 387 described above. Without information about the port regions a hardware 388 has to offer, it becomes difficult for the userspace part of the 389 driver to find out which ports belong to which UIO device. 390 </para> 391 <para> 392 To address this situation, the new directory 393 <filename>/sys/class/uio/uioX/portio/</filename> was added. It only 394 exists if the driver wants to pass information about one or more port 395 regions to userspace. If that is the case, subdirectories named 396 <filename>port0</filename>, <filename>port1</filename>, and so on, 397 will appear underneath 398 <filename>/sys/class/uio/uioX/portio/</filename>. 399 </para> 400 <para> 401 Each <filename>portX/</filename> directory contains four read-only 402 files that show name, start, size, and type of the port region: 403 </para> 404 <itemizedlist> 405 <listitem> 406 <para> 407 <filename>name</filename>: A string identifier for this port region. 408 The string is optional and can be empty. Drivers can set it to make it 409 easier for userspace to find a certain port region. 410 </para> 411 </listitem> 412 <listitem> 413 <para> 414 <filename>start</filename>: The first port of this region. 415 </para> 416 </listitem> 417 <listitem> 418 <para> 419 <filename>size</filename>: The number of ports in this region. 420 </para> 421 </listitem> 422 <listitem> 423 <para> 424 <filename>porttype</filename>: A string describing the type of port. 425 </para> 426 </listitem> 427 </itemizedlist> 428 429 430 </sect1> 431 </chapter> 432 433 <chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> 434 <?dbhtml filename="custom_kernel_module.html"?> 435 <title>Writing your own kernel module</title> 436 <para> 437 Please have a look at <filename>uio_cif.c</filename> as an 438 example. The following paragraphs explain the different 439 sections of this file. 440 </para> 441 442 <sect1 id="uio_info"> 443 <title>struct uio_info</title> 444 <para> 445 This structure tells the framework the details of your driver, 446 Some of the members are required, others are optional. 447 </para> 448 449 <itemizedlist> 450 <listitem><para> 451 <varname>const char *name</varname>: Required. The name of your driver as 452 it will appear in sysfs. I recommend using the name of your module for this. 453 </para></listitem> 454 455 <listitem><para> 456 <varname>const char *version</varname>: Required. This string appears in 457 <filename>/sys/class/uio/uioX/version</filename>. 458 </para></listitem> 459 460 <listitem><para> 461 <varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you 462 have memory that can be mapped with <function>mmap()</function>. For each 463 mapping you need to fill one of the <varname>uio_mem</varname> structures. 464 See the description below for details. 465 </para></listitem> 466 467 <listitem><para> 468 <varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required 469 if you want to pass information about ioports to userspace. For each port 470 region you need to fill one of the <varname>uio_port</varname> structures. 471 See the description below for details. 472 </para></listitem> 473 474 <listitem><para> 475 <varname>long irq</varname>: Required. If your hardware generates an 476 interrupt, it's your modules task to determine the irq number during 477 initialization. If you don't have a hardware generated interrupt but 478 want to trigger the interrupt handler in some other way, set 479 <varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. 480 If you had no interrupt at all, you could set 481 <varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this 482 rarely makes sense. 483 </para></listitem> 484 485 <listitem><para> 486 <varname>unsigned long irq_flags</varname>: Required if you've set 487 <varname>irq</varname> to a hardware interrupt number. The flags given 488 here will be used in the call to <function>request_irq()</function>. 489 </para></listitem> 490 491 <listitem><para> 492 <varname>int (*mmap)(struct uio_info *info, struct vm_area_struct 493 *vma)</varname>: Optional. If you need a special 494 <function>mmap()</function> function, you can set it here. If this 495 pointer is not NULL, your <function>mmap()</function> will be called 496 instead of the built-in one. 497 </para></listitem> 498 499 <listitem><para> 500 <varname>int (*open)(struct uio_info *info, struct inode *inode) 501 </varname>: Optional. You might want to have your own 502 <function>open()</function>, e.g. to enable interrupts only when your 503 device is actually used. 504 </para></listitem> 505 506 <listitem><para> 507 <varname>int (*release)(struct uio_info *info, struct inode *inode) 508 </varname>: Optional. If you define your own 509 <function>open()</function>, you will probably also want a custom 510 <function>release()</function> function. 511 </para></listitem> 512 513 <listitem><para> 514 <varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on) 515 </varname>: Optional. If you need to be able to enable or disable 516 interrupts from userspace by writing to <filename>/dev/uioX</filename>, 517 you can implement this function. The parameter <varname>irq_on</varname> 518 will be 0 to disable interrupts and 1 to enable them. 519 </para></listitem> 520 </itemizedlist> 521 522 <para> 523 Usually, your device will have one or more memory regions that can be mapped 524 to user space. For each region, you have to set up a 525 <varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. 526 Here's a description of the fields of <varname>struct uio_mem</varname>: 527 </para> 528 529 <itemizedlist> 530 <listitem><para> 531 <varname>const char *name</varname>: Optional. Set this to help identify 532 the memory region, it will show up in the corresponding sysfs node. 533 </para></listitem> 534 535 <listitem><para> 536 <varname>int memtype</varname>: Required if the mapping is used. Set this to 537 <varname>UIO_MEM_PHYS</varname> if you you have physical memory on your 538 card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical 539 memory (e.g. allocated with <function>kmalloc()</function>). There's also 540 <varname>UIO_MEM_VIRTUAL</varname> for virtual memory. 541 </para></listitem> 542 543 <listitem><para> 544 <varname>phys_addr_t addr</varname>: Required if the mapping is used. 545 Fill in the address of your memory block. This address is the one that 546 appears in sysfs. 547 </para></listitem> 548 549 <listitem><para> 550 <varname>resource_size_t size</varname>: Fill in the size of the 551 memory block that <varname>addr</varname> points to. If <varname>size</varname> 552 is zero, the mapping is considered unused. Note that you 553 <emphasis>must</emphasis> initialize <varname>size</varname> with zero for 554 all unused mappings. 555 </para></listitem> 556 557 <listitem><para> 558 <varname>void *internal_addr</varname>: If you have to access this memory 559 region from within your kernel module, you will want to map it internally by 560 using something like <function>ioremap()</function>. Addresses 561 returned by this function cannot be mapped to user space, so you must not 562 store it in <varname>addr</varname>. Use <varname>internal_addr</varname> 563 instead to remember such an address. 564 </para></listitem> 565 </itemizedlist> 566 567 <para> 568 Please do not touch the <varname>map</varname> element of 569 <varname>struct uio_mem</varname>! It is used by the UIO framework 570 to set up sysfs files for this mapping. Simply leave it alone. 571 </para> 572 573 <para> 574 Sometimes, your device can have one or more port regions which can not be 575 mapped to userspace. But if there are other possibilities for userspace to 576 access these ports, it makes sense to make information about the ports 577 available in sysfs. For each region, you have to set up a 578 <varname>struct uio_port</varname> in the <varname>port[]</varname> array. 579 Here's a description of the fields of <varname>struct uio_port</varname>: 580 </para> 581 582 <itemizedlist> 583 <listitem><para> 584 <varname>char *porttype</varname>: Required. Set this to one of the predefined 585 constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 586 architectures. 587 </para></listitem> 588 589 <listitem><para> 590 <varname>unsigned long start</varname>: Required if the port region is used. 591 Fill in the number of the first port of this region. 592 </para></listitem> 593 594 <listitem><para> 595 <varname>unsigned long size</varname>: Fill in the number of ports in this 596 region. If <varname>size</varname> is zero, the region is considered unused. 597 Note that you <emphasis>must</emphasis> initialize <varname>size</varname> 598 with zero for all unused regions. 599 </para></listitem> 600 </itemizedlist> 601 602 <para> 603 Please do not touch the <varname>portio</varname> element of 604 <varname>struct uio_port</varname>! It is used internally by the UIO 605 framework to set up sysfs files for this region. Simply leave it alone. 606 </para> 607 608 </sect1> 609 610 <sect1 id="adding_irq_handler"> 611 <title>Adding an interrupt handler</title> 612 <para> 613 What you need to do in your interrupt handler depends on your 614 hardware and on how you want to handle it. You should try to 615 keep the amount of code in your kernel interrupt handler low. 616 If your hardware requires no action that you 617 <emphasis>have</emphasis> to perform after each interrupt, 618 then your handler can be empty.</para> <para>If, on the other 619 hand, your hardware <emphasis>needs</emphasis> some action to 620 be performed after each interrupt, then you 621 <emphasis>must</emphasis> do it in your kernel module. Note 622 that you cannot rely on the userspace part of your driver. Your 623 userspace program can terminate at any time, possibly leaving 624 your hardware in a state where proper interrupt handling is 625 still required. 626 </para> 627 628 <para> 629 There might also be applications where you want to read data 630 from your hardware at each interrupt and buffer it in a piece 631 of kernel memory you've allocated for that purpose. With this 632 technique you could avoid loss of data if your userspace 633 program misses an interrupt. 634 </para> 635 636 <para> 637 A note on shared interrupts: Your driver should support 638 interrupt sharing whenever this is possible. It is possible if 639 and only if your driver can detect whether your hardware has 640 triggered the interrupt or not. This is usually done by looking 641 at an interrupt status register. If your driver sees that the 642 IRQ bit is actually set, it will perform its actions, and the 643 handler returns IRQ_HANDLED. If the driver detects that it was 644 not your hardware that caused the interrupt, it will do nothing 645 and return IRQ_NONE, allowing the kernel to call the next 646 possible interrupt handler. 647 </para> 648 649 <para> 650 If you decide not to support shared interrupts, your card 651 won't work in computers with no free interrupts. As this 652 frequently happens on the PC platform, you can save yourself a 653 lot of trouble by supporting interrupt sharing. 654 </para> 655 </sect1> 656 657 <sect1 id="using_uio_pdrv"> 658 <title>Using uio_pdrv for platform devices</title> 659 <para> 660 In many cases, UIO drivers for platform devices can be handled in a 661 generic way. In the same place where you define your 662 <varname>struct platform_device</varname>, you simply also implement 663 your interrupt handler and fill your 664 <varname>struct uio_info</varname>. A pointer to this 665 <varname>struct uio_info</varname> is then used as 666 <varname>platform_data</varname> for your platform device. 667 </para> 668 <para> 669 You also need to set up an array of <varname>struct resource</varname> 670 containing addresses and sizes of your memory mappings. This 671 information is passed to the driver using the 672 <varname>.resource</varname> and <varname>.num_resources</varname> 673 elements of <varname>struct platform_device</varname>. 674 </para> 675 <para> 676 You now have to set the <varname>.name</varname> element of 677 <varname>struct platform_device</varname> to 678 <varname>"uio_pdrv"</varname> to use the generic UIO platform device 679 driver. This driver will fill the <varname>mem[]</varname> array 680 according to the resources given, and register the device. 681 </para> 682 <para> 683 The advantage of this approach is that you only have to edit a file 684 you need to edit anyway. You do not have to create an extra driver. 685 </para> 686 </sect1> 687 688 <sect1 id="using_uio_pdrv_genirq"> 689 <title>Using uio_pdrv_genirq for platform devices</title> 690 <para> 691 Especially in embedded devices, you frequently find chips where the 692 irq pin is tied to its own dedicated interrupt line. In such cases, 693 where you can be really sure the interrupt is not shared, we can take 694 the concept of <varname>uio_pdrv</varname> one step further and use a 695 generic interrupt handler. That's what 696 <varname>uio_pdrv_genirq</varname> does. 697 </para> 698 <para> 699 The setup for this driver is the same as described above for 700 <varname>uio_pdrv</varname>, except that you do not implement an 701 interrupt handler. The <varname>.handler</varname> element of 702 <varname>struct uio_info</varname> must remain 703 <varname>NULL</varname>. The <varname>.irq_flags</varname> element 704 must not contain <varname>IRQF_SHARED</varname>. 705 </para> 706 <para> 707 You will set the <varname>.name</varname> element of 708 <varname>struct platform_device</varname> to 709 <varname>"uio_pdrv_genirq"</varname> to use this driver. 710 </para> 711 <para> 712 The generic interrupt handler of <varname>uio_pdrv_genirq</varname> 713 will simply disable the interrupt line using 714 <function>disable_irq_nosync()</function>. After doing its work, 715 userspace can reenable the interrupt by writing 0x00000001 to the UIO 716 device file. The driver already implements an 717 <function>irq_control()</function> to make this possible, you must not 718 implement your own. 719 </para> 720 <para> 721 Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of 722 interrupt handler code. You also do not need to know anything about 723 the chip's internal registers to create the kernel part of the driver. 724 All you need to know is the irq number of the pin the chip is 725 connected to. 726 </para> 727 </sect1> 728 729 <sect1 id="using-uio_dmem_genirq"> 730 <title>Using uio_dmem_genirq for platform devices</title> 731 <para> 732 In addition to statically allocated memory ranges, they may also be 733 a desire to use dynamically allocated regions in a user space driver. 734 In particular, being able to access memory made available through the 735 dma-mapping API, may be particularly useful. The 736 <varname>uio_dmem_genirq</varname> driver provides a way to accomplish 737 this. 738 </para> 739 <para> 740 This driver is used in a similar manner to the 741 <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt 742 configuration and handling. 743 </para> 744 <para> 745 Set the <varname>.name</varname> element of 746 <varname>struct platform_device</varname> to 747 <varname>"uio_dmem_genirq"</varname> to use this driver. 748 </para> 749 <para> 750 When using this driver, fill in the <varname>.platform_data</varname> 751 element of <varname>struct platform_device</varname>, which is of type 752 <varname>struct uio_dmem_genirq_pdata</varname> and which contains the 753 following elements: 754 </para> 755 <itemizedlist> 756 <listitem><para><varname>struct uio_info uioinfo</varname>: The same 757 structure used as the <varname>uio_pdrv_genirq</varname> platform 758 data</para></listitem> 759 <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>: 760 Pointer to list of sizes of dynamic memory regions to be mapped into 761 user space. 762 </para></listitem> 763 <listitem><para><varname>unsigned int num_dynamic_regions</varname>: 764 Number of elements in <varname>dynamic_region_sizes</varname> array. 765 </para></listitem> 766 </itemizedlist> 767 <para> 768 The dynamic regions defined in the platform data will be appended to 769 the <varname> mem[] </varname> array after the platform device 770 resources, which implies that the total number of static and dynamic 771 memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. 772 </para> 773 <para> 774 The dynamic memory regions will be allocated when the UIO device file, 775 <varname>/dev/uioX</varname> is opened. 776 Similar to static memory resources, the memory region information for 777 dynamic regions is then visible via sysfs at 778 <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. 779 The dynamic memory regions will be freed when the UIO device file is 780 closed. When no processes are holding the device file open, the address 781 returned to userspace is ~0. 782 </para> 783 </sect1> 784 785 </chapter> 786 787 <chapter id="userspace_driver" xreflabel="Writing a driver in user space"> 788 <?dbhtml filename="userspace_driver.html"?> 789 <title>Writing a driver in userspace</title> 790 <para> 791 Once you have a working kernel module for your hardware, you can 792 write the userspace part of your driver. You don't need any special 793 libraries, your driver can be written in any reasonable language, 794 you can use floating point numbers and so on. In short, you can 795 use all the tools and libraries you'd normally use for writing a 796 userspace application. 797 </para> 798 799 <sect1 id="getting_uio_information"> 800 <title>Getting information about your UIO device</title> 801 <para> 802 Information about all UIO devices is available in sysfs. The 803 first thing you should do in your driver is check 804 <varname>name</varname> and <varname>version</varname> to 805 make sure your talking to the right device and that its kernel 806 driver has the version you expect. 807 </para> 808 <para> 809 You should also make sure that the memory mapping you need 810 exists and has the size you expect. 811 </para> 812 <para> 813 There is a tool called <varname>lsuio</varname> that lists 814 UIO devices and their attributes. It is available here: 815 </para> 816 <para> 817 <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> 818 http://www.osadl.org/projects/downloads/UIO/user/</ulink> 819 </para> 820 <para> 821 With <varname>lsuio</varname> you can quickly check if your 822 kernel module is loaded and which attributes it exports. 823 Have a look at the manpage for details. 824 </para> 825 <para> 826 The source code of <varname>lsuio</varname> can serve as an 827 example for getting information about an UIO device. 828 The file <filename>uio_helper.c</filename> contains a lot of 829 functions you could use in your userspace driver code. 830 </para> 831 </sect1> 832 833 <sect1 id="mmap_device_memory"> 834 <title>mmap() device memory</title> 835 <para> 836 After you made sure you've got the right device with the 837 memory mappings you need, all you have to do is to call 838 <function>mmap()</function> to map the device's memory 839 to userspace. 840 </para> 841 <para> 842 The parameter <varname>offset</varname> of the 843 <function>mmap()</function> call has a special meaning 844 for UIO devices: It is used to select which mapping of 845 your device you want to map. To map the memory of 846 mapping N, you have to use N times the page size as 847 your offset: 848 </para> 849 <programlisting format="linespecific"> 850 offset = N * getpagesize(); 851 </programlisting> 852 <para> 853 N starts from zero, so if you've got only one memory 854 range to map, set <varname>offset = 0</varname>. 855 A drawback of this technique is that memory is always 856 mapped beginning with its start address. 857 </para> 858 </sect1> 859 860 <sect1 id="wait_for_interrupts"> 861 <title>Waiting for interrupts</title> 862 <para> 863 After you successfully mapped your devices memory, you 864 can access it like an ordinary array. Usually, you will 865 perform some initialization. After that, your hardware 866 starts working and will generate an interrupt as soon 867 as it's finished, has some data available, or needs your 868 attention because an error occurred. 869 </para> 870 <para> 871 <filename>/dev/uioX</filename> is a read-only file. A 872 <function>read()</function> will always block until an 873 interrupt occurs. There is only one legal value for the 874 <varname>count</varname> parameter of 875 <function>read()</function>, and that is the size of a 876 signed 32 bit integer (4). Any other value for 877 <varname>count</varname> causes <function>read()</function> 878 to fail. The signed 32 bit integer read is the interrupt 879 count of your device. If the value is one more than the value 880 you read the last time, everything is OK. If the difference 881 is greater than one, you missed interrupts. 882 </para> 883 <para> 884 You can also use <function>select()</function> on 885 <filename>/dev/uioX</filename>. 886 </para> 887 </sect1> 888 889 </chapter> 890 891 <chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> 892 <?dbhtml filename="uio_pci_generic.html"?> 893 <title>Generic PCI UIO driver</title> 894 <para> 895 The generic driver is a kernel module named uio_pci_generic. 896 It can work with any device compliant to PCI 2.3 (circa 2002) and 897 any compliant PCI Express device. Using this, you only need to 898 write the userspace driver, removing the need to write 899 a hardware-specific kernel module. 900 </para> 901 902 <sect1 id="uio_pci_generic_binding"> 903 <title>Making the driver recognize the device</title> 904 <para> 905 Since the driver does not declare any device ids, it will not get loaded 906 automatically and will not automatically bind to any devices, you must load it 907 and allocate id to the driver yourself. For example: 908 <programlisting> 909 modprobe uio_pci_generic 910 echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id 911 </programlisting> 912 </para> 913 <para> 914 If there already is a hardware specific kernel driver for your device, the 915 generic driver still won't bind to it, in this case if you want to use the 916 generic driver (why would you?) you'll have to manually unbind the hardware 917 specific driver and bind the generic driver, like this: 918 <programlisting> 919 echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind 920 echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind 921 </programlisting> 922 </para> 923 <para> 924 You can verify that the device has been bound to the driver 925 by looking for it in sysfs, for example like the following: 926 <programlisting> 927 ls -l /sys/bus/pci/devices/0000:00:19.0/driver 928 </programlisting> 929 Which if successful should print 930 <programlisting> 931 .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic 932 </programlisting> 933 Note that the generic driver will not bind to old PCI 2.2 devices. 934 If binding the device failed, run the following command: 935 <programlisting> 936 dmesg 937 </programlisting> 938 and look in the output for failure reasons 939 </para> 940 </sect1> 941 942 <sect1 id="uio_pci_generic_internals"> 943 <title>Things to know about uio_pci_generic</title> 944 <para> 945 Interrupts are handled using the Interrupt Disable bit in the PCI command 946 register and Interrupt Status bit in the PCI status register. All devices 947 compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should 948 support these bits. uio_pci_generic detects this support, and won't bind to 949 devices which do not support the Interrupt Disable Bit in the command register. 950 </para> 951 <para> 952 On each interrupt, uio_pci_generic sets the Interrupt Disable bit. 953 This prevents the device from generating further interrupts 954 until the bit is cleared. The userspace driver should clear this 955 bit before blocking and waiting for more interrupts. 956 </para> 957 </sect1> 958 <sect1 id="uio_pci_generic_userspace"> 959 <title>Writing userspace driver using uio_pci_generic</title> 960 <para> 961 Userspace driver can use pci sysfs interface, or the 962 libpci libray that wraps it, to talk to the device and to 963 re-enable interrupts by writing to the command register. 964 </para> 965 </sect1> 966 <sect1 id="uio_pci_generic_example"> 967 <title>Example code using uio_pci_generic</title> 968 <para> 969 Here is some sample userspace driver code using uio_pci_generic: 970 <programlisting> 971 #include <stdlib.h> 972 #include <stdio.h> 973 #include <unistd.h> 974 #include <sys/types.h> 975 #include <sys/stat.h> 976 #include <fcntl.h> 977 #include <errno.h> 978 979 int main() 980 { 981 int uiofd; 982 int configfd; 983 int err; 984 int i; 985 unsigned icount; 986 unsigned char command_high; 987 988 uiofd = open("/dev/uio0", O_RDONLY); 989 if (uiofd < 0) { 990 perror("uio open:"); 991 return errno; 992 } 993 configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); 994 if (configfd < 0) { 995 perror("config open:"); 996 return errno; 997 } 998 999 /* Read and cache command value */ 1000 err = pread(configfd, &command_high, 1, 5); 1001 if (err != 1) { 1002 perror("command config read:"); 1003 return errno; 1004 } 1005 command_high &= ~0x4; 1006 1007 for(i = 0;; ++i) { 1008 /* Print out a message, for debugging. */ 1009 if (i == 0) 1010 fprintf(stderr, "Started uio test driver.\n"); 1011 else 1012 fprintf(stderr, "Interrupts: %d\n", icount); 1013 1014 /****************************************/ 1015 /* Here we got an interrupt from the 1016 device. Do something to it. */ 1017 /****************************************/ 1018 1019 /* Re-enable interrupts. */ 1020 err = pwrite(configfd, &command_high, 1, 5); 1021 if (err != 1) { 1022 perror("config write:"); 1023 break; 1024 } 1025 1026 /* Wait for next interrupt. */ 1027 err = read(uiofd, &icount, 4); 1028 if (err != 4) { 1029 perror("uio read:"); 1030 break; 1031 } 1032 1033 } 1034 return errno; 1035 } 1036 1037 </programlisting> 1038 </para> 1039 </sect1> 1040 1041 </chapter> 1042 1043 <chapter id="uio_hv_generic" xreflabel="Using Generic driver for Hyper-V VMBUS"> 1044 <?dbhtml filename="uio_hv_generic.html"?> 1045 <title>Generic Hyper-V UIO driver</title> 1046 <para> 1047 The generic driver is a kernel module named uio_hv_generic. 1048 It supports devices on the Hyper-V VMBus similar to uio_pci_generic 1049 on PCI bus. 1050 </para> 1051 1052 <sect1 id="uio_hv_generic_binding"> 1053 <title>Making the driver recognize the device</title> 1054 <para> 1055 Since the driver does not declare any device GUID's, it will not get loaded 1056 automatically and will not automatically bind to any devices, you must load it 1057 and allocate id to the driver yourself. For example, to use the network device 1058 GUID: 1059 <programlisting> 1060 modprobe uio_hv_generic 1061 echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id 1062 </programlisting> 1063 </para> 1064 <para> 1065 If there already is a hardware specific kernel driver for the device, the 1066 generic driver still won't bind to it, in this case if you want to use the 1067 generic driver (why would you?) you'll have to manually unbind the hardware 1068 specific driver and bind the generic driver, like this: 1069 <programlisting> 1070 echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind 1071 echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind 1072 </programlisting> 1073 </para> 1074 <para> 1075 You can verify that the device has been bound to the driver 1076 by looking for it in sysfs, for example like the following: 1077 <programlisting> 1078 ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver 1079 </programlisting> 1080 Which if successful should print 1081 <programlisting> 1082 .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic 1083 </programlisting> 1084 </para> 1085 </sect1> 1086 1087 <sect1 id="uio_hv_generic_internals"> 1088 <title>Things to know about uio_hv_generic</title> 1089 <para> 1090 On each interrupt, uio_hv_generic sets the Interrupt Disable bit. 1091 This prevents the device from generating further interrupts 1092 until the bit is cleared. The userspace driver should clear this 1093 bit before blocking and waiting for more interrupts. 1094 </para> 1095 </sect1> 1096 </chapter> 1097 1098 <appendix id="app1"> 1099 <title>Further information</title> 1100 <itemizedlist> 1101 <listitem><para> 1102 <ulink url="http://www.osadl.org"> 1103 OSADL homepage.</ulink> 1104 </para></listitem> 1105 <listitem><para> 1106 <ulink url="http://www.linutronix.de"> 1107 Linutronix homepage.</ulink> 1108 </para></listitem> 1109 </itemizedlist> 1110 </appendix> 1111 1112 </book>