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