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