Documentation/DocBook/uio-howto.tmpl

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