linux/Documentation/DocBook/uio-howto.tmpl
<<
>>
Prefs
   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>
  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@hansjkoch.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@hansjkoch.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>const char *name</varname>: Optional. Set this to help identify
 525the memory region, it will show up in the corresponding sysfs node.
 526</para></listitem>
 527
 528<listitem><para>
 529<varname>int memtype</varname>: Required if the mapping is used. Set this to
 530<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
 531card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
 532memory (e.g. allocated with <function>kmalloc()</function>). There's also
 533<varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
 534</para></listitem>
 535
 536<listitem><para>
 537<varname>phys_addr_t addr</varname>: Required if the mapping is used.
 538Fill in the address of your memory block. This address is the one that
 539appears in sysfs.
 540</para></listitem>
 541
 542<listitem><para>
 543<varname>unsigned long size</varname>: Fill in the size of the
 544memory block that <varname>addr</varname> points to. If <varname>size</varname>
 545is zero, the mapping is considered unused. Note that you
 546<emphasis>must</emphasis> initialize <varname>size</varname> with zero for
 547all unused mappings.
 548</para></listitem>
 549
 550<listitem><para>
 551<varname>void *internal_addr</varname>: If you have to access this memory
 552region from within your kernel module, you will want to map it internally by
 553using something like <function>ioremap()</function>. Addresses
 554returned by this function cannot be mapped to user space, so you must not
 555store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
 556instead to remember such an address.
 557</para></listitem>
 558</itemizedlist>
 559
 560<para>
 561Please do not touch the <varname>map</varname> element of
 562<varname>struct uio_mem</varname>! It is used by the UIO framework
 563to set up sysfs files for this mapping. Simply leave it alone.
 564</para>
 565
 566<para>
 567Sometimes, your device can have one or more port regions which can not be
 568mapped to userspace. But if there are other possibilities for userspace to
 569access these ports, it makes sense to make information about the ports
 570available in sysfs. For each region, you have to set up a
 571<varname>struct uio_port</varname> in the <varname>port[]</varname> array.
 572Here's a description of the fields of <varname>struct uio_port</varname>:
 573</para>
 574
 575<itemizedlist>
 576<listitem><para>
 577<varname>char *porttype</varname>: Required. Set this to one of the predefined
 578constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
 579architectures.
 580</para></listitem>
 581
 582<listitem><para>
 583<varname>unsigned long start</varname>: Required if the port region is used.
 584Fill in the number of the first port of this region.
 585</para></listitem>
 586
 587<listitem><para>
 588<varname>unsigned long size</varname>: Fill in the number of ports in this
 589region. If <varname>size</varname> is zero, the region is considered unused.
 590Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
 591with zero for all unused regions.
 592</para></listitem>
 593</itemizedlist>
 594
 595<para>
 596Please do not touch the <varname>portio</varname> element of
 597<varname>struct uio_port</varname>! It is used internally by the UIO
 598framework to set up sysfs files for this region. Simply leave it alone.
 599</para>
 600
 601</sect1>
 602
 603<sect1 id="adding_irq_handler">
 604<title>Adding an interrupt handler</title>
 605        <para>
 606        What you need to do in your interrupt handler depends on your
 607        hardware and on how you want to handle it. You should try to
 608        keep the amount of code in your kernel interrupt handler low.
 609        If your hardware requires no action that you
 610        <emphasis>have</emphasis> to perform after each interrupt,
 611        then your handler can be empty.</para> <para>If, on the other
 612        hand, your hardware <emphasis>needs</emphasis> some action to
 613        be performed after each interrupt, then you
 614        <emphasis>must</emphasis> do it in your kernel module. Note
 615        that you cannot rely on the userspace part of your driver. Your
 616        userspace program can terminate at any time, possibly leaving
 617        your hardware in a state where proper interrupt handling is
 618        still required.
 619        </para>
 620
 621        <para>
 622        There might also be applications where you want to read data
 623        from your hardware at each interrupt and buffer it in a piece
 624        of kernel memory you've allocated for that purpose.  With this
 625        technique you could avoid loss of data if your userspace
 626        program misses an interrupt.
 627        </para>
 628
 629        <para>
 630        A note on shared interrupts: Your driver should support
 631        interrupt sharing whenever this is possible. It is possible if
 632        and only if your driver can detect whether your hardware has
 633        triggered the interrupt or not. This is usually done by looking
 634        at an interrupt status register. If your driver sees that the
 635        IRQ bit is actually set, it will perform its actions, and the
 636        handler returns IRQ_HANDLED. If the driver detects that it was
 637        not your hardware that caused the interrupt, it will do nothing
 638        and return IRQ_NONE, allowing the kernel to call the next
 639        possible interrupt handler.
 640        </para>
 641
 642        <para>
 643        If you decide not to support shared interrupts, your card
 644        won't work in computers with no free interrupts. As this
 645        frequently happens on the PC platform, you can save yourself a
 646        lot of trouble by supporting interrupt sharing.
 647        </para>
 648</sect1>
 649
 650<sect1 id="using_uio_pdrv">
 651<title>Using uio_pdrv for platform devices</title>
 652        <para>
 653        In many cases, UIO drivers for platform devices can be handled in a
 654        generic way. In the same place where you define your
 655        <varname>struct platform_device</varname>, you simply also implement
 656        your interrupt handler and fill your
 657        <varname>struct uio_info</varname>. A pointer to this
 658        <varname>struct uio_info</varname> is then used as
 659        <varname>platform_data</varname> for your platform device.
 660        </para>
 661        <para>
 662        You also need to set up an array of <varname>struct resource</varname>
 663        containing addresses and sizes of your memory mappings. This
 664        information is passed to the driver using the
 665        <varname>.resource</varname> and <varname>.num_resources</varname>
 666        elements of <varname>struct platform_device</varname>.
 667        </para>
 668        <para>
 669        You now have to set the <varname>.name</varname> element of
 670        <varname>struct platform_device</varname> to
 671        <varname>"uio_pdrv"</varname> to use the generic UIO platform device
 672        driver. This driver will fill the <varname>mem[]</varname> array
 673        according to the resources given, and register the device.
 674        </para>
 675        <para>
 676        The advantage of this approach is that you only have to edit a file
 677        you need to edit anyway. You do not have to create an extra driver.
 678        </para>
 679</sect1>
 680
 681<sect1 id="using_uio_pdrv_genirq">
 682<title>Using uio_pdrv_genirq for platform devices</title>
 683        <para>
 684        Especially in embedded devices, you frequently find chips where the
 685        irq pin is tied to its own dedicated interrupt line. In such cases,
 686        where you can be really sure the interrupt is not shared, we can take
 687        the concept of <varname>uio_pdrv</varname> one step further and use a
 688        generic interrupt handler. That's what
 689        <varname>uio_pdrv_genirq</varname> does.
 690        </para>
 691        <para>
 692        The setup for this driver is the same as described above for
 693        <varname>uio_pdrv</varname>, except that you do not implement an
 694        interrupt handler. The <varname>.handler</varname> element of
 695        <varname>struct uio_info</varname> must remain
 696        <varname>NULL</varname>. The  <varname>.irq_flags</varname> element
 697        must not contain <varname>IRQF_SHARED</varname>.
 698        </para>
 699        <para>
 700        You will set the <varname>.name</varname> element of
 701        <varname>struct platform_device</varname> to
 702        <varname>"uio_pdrv_genirq"</varname> to use this driver.
 703        </para>
 704        <para>
 705        The generic interrupt handler of <varname>uio_pdrv_genirq</varname>
 706        will simply disable the interrupt line using
 707        <function>disable_irq_nosync()</function>. After doing its work,
 708        userspace can reenable the interrupt by writing 0x00000001 to the UIO
 709        device file. The driver already implements an
 710        <function>irq_control()</function> to make this possible, you must not
 711        implement your own.
 712        </para>
 713        <para>
 714        Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of
 715        interrupt handler code. You also do not need to know anything about
 716        the chip's internal registers to create the kernel part of the driver.
 717        All you need to know is the irq number of the pin the chip is
 718        connected to.
 719        </para>
 720</sect1>
 721
 722</chapter>
 723
 724<chapter id="userspace_driver" xreflabel="Writing a driver in user space">
 725<?dbhtml filename="userspace_driver.html"?>
 726<title>Writing a driver in userspace</title>
 727        <para>
 728        Once you have a working kernel module for your hardware, you can
 729        write the userspace part of your driver. You don't need any special
 730        libraries, your driver can be written in any reasonable language,
 731        you can use floating point numbers and so on. In short, you can
 732        use all the tools and libraries you'd normally use for writing a
 733        userspace application.
 734        </para>
 735
 736<sect1 id="getting_uio_information">
 737<title>Getting information about your UIO device</title>
 738        <para>
 739        Information about all UIO devices is available in sysfs. The
 740        first thing you should do in your driver is check
 741        <varname>name</varname> and <varname>version</varname> to
 742        make sure your talking to the right device and that its kernel
 743        driver has the version you expect.
 744        </para>
 745        <para>
 746        You should also make sure that the memory mapping you need
 747        exists and has the size you expect.
 748        </para>
 749        <para>
 750        There is a tool called <varname>lsuio</varname> that lists
 751        UIO devices and their attributes. It is available here:
 752        </para>
 753        <para>
 754        <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
 755                http://www.osadl.org/projects/downloads/UIO/user/</ulink>
 756        </para>
 757        <para>
 758        With <varname>lsuio</varname> you can quickly check if your
 759        kernel module is loaded and which attributes it exports.
 760        Have a look at the manpage for details.
 761        </para>
 762        <para>
 763        The source code of <varname>lsuio</varname> can serve as an
 764        example for getting information about an UIO device.
 765        The file <filename>uio_helper.c</filename> contains a lot of
 766        functions you could use in your userspace driver code.
 767        </para>
 768</sect1>
 769
 770<sect1 id="mmap_device_memory">
 771<title>mmap() device memory</title>
 772        <para>
 773        After you made sure you've got the right device with the
 774        memory mappings you need, all you have to do is to call
 775        <function>mmap()</function> to map the device's memory
 776        to userspace.
 777        </para>
 778        <para>
 779        The parameter <varname>offset</varname> of the
 780        <function>mmap()</function> call has a special meaning
 781        for UIO devices: It is used to select which mapping of
 782        your device you want to map. To map the memory of
 783        mapping N, you have to use N times the page size as
 784        your offset:
 785        </para>
 786<programlisting format="linespecific">
 787        offset = N * getpagesize();
 788</programlisting>
 789        <para>
 790        N starts from zero, so if you've got only one memory
 791        range to map, set <varname>offset = 0</varname>.
 792        A drawback of this technique is that memory is always
 793        mapped beginning with its start address.
 794        </para>
 795</sect1>
 796
 797<sect1 id="wait_for_interrupts">
 798<title>Waiting for interrupts</title>
 799        <para>
 800        After you successfully mapped your devices memory, you
 801        can access it like an ordinary array. Usually, you will
 802        perform some initialization. After that, your hardware
 803        starts working and will generate an interrupt as soon
 804        as it's finished, has some data available, or needs your
 805        attention because an error occurred.
 806        </para>
 807        <para>
 808        <filename>/dev/uioX</filename> is a read-only file. A
 809        <function>read()</function> will always block until an
 810        interrupt occurs. There is only one legal value for the
 811        <varname>count</varname> parameter of
 812        <function>read()</function>, and that is the size of a
 813        signed 32 bit integer (4). Any other value for
 814        <varname>count</varname> causes <function>read()</function>
 815        to fail. The signed 32 bit integer read is the interrupt
 816        count of your device. If the value is one more than the value
 817        you read the last time, everything is OK. If the difference
 818        is greater than one, you missed interrupts.
 819        </para>
 820        <para>
 821        You can also use <function>select()</function> on
 822        <filename>/dev/uioX</filename>.
 823        </para>
 824</sect1>
 825
 826</chapter>
 827
 828<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards">
 829<?dbhtml filename="uio_pci_generic.html"?>
 830<title>Generic PCI UIO driver</title>
 831        <para>
 832        The generic driver is a kernel module named uio_pci_generic.
 833        It can work with any device compliant to PCI 2.3 (circa 2002) and
 834        any compliant PCI Express device. Using this, you only need to
 835        write the userspace driver, removing the need to write
 836        a hardware-specific kernel module.
 837        </para>
 838
 839<sect1 id="uio_pci_generic_binding">
 840<title>Making the driver recognize the device</title>
 841        <para>
 842Since the driver does not declare any device ids, it will not get loaded
 843automatically and will not automatically bind to any devices, you must load it
 844and allocate id to the driver yourself. For example:
 845        <programlisting>
 846 modprobe uio_pci_generic
 847 echo &quot;8086 10f5&quot; &gt; /sys/bus/pci/drivers/uio_pci_generic/new_id
 848        </programlisting>
 849        </para>
 850        <para>
 851If there already is a hardware specific kernel driver for your device, the
 852generic driver still won't bind to it, in this case if you want to use the
 853generic driver (why would you?) you'll have to manually unbind the hardware
 854specific driver and bind the generic driver, like this:
 855        <programlisting>
 856    echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/e1000e/unbind
 857    echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/uio_pci_generic/bind
 858        </programlisting>
 859        </para>
 860        <para>
 861You can verify that the device has been bound to the driver
 862by looking for it in sysfs, for example like the following:
 863        <programlisting>
 864    ls -l /sys/bus/pci/devices/0000:00:19.0/driver
 865        </programlisting>
 866Which if successful should print
 867        <programlisting>
 868  .../0000:00:19.0/driver -&gt; ../../../bus/pci/drivers/uio_pci_generic
 869        </programlisting>
 870Note that the generic driver will not bind to old PCI 2.2 devices.
 871If binding the device failed, run the following command:
 872        <programlisting>
 873  dmesg
 874        </programlisting>
 875and look in the output for failure reasons
 876        </para>
 877</sect1>
 878
 879<sect1 id="uio_pci_generic_internals">
 880<title>Things to know about uio_pci_generic</title>
 881        <para>
 882Interrupts are handled using the Interrupt Disable bit in the PCI command
 883register and Interrupt Status bit in the PCI status register.  All devices
 884compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should
 885support these bits.  uio_pci_generic detects this support, and won't bind to
 886devices which do not support the Interrupt Disable Bit in the command register.
 887        </para>
 888        <para>
 889On each interrupt, uio_pci_generic sets the Interrupt Disable bit.
 890This prevents the device from generating further interrupts
 891until the bit is cleared. The userspace driver should clear this
 892bit before blocking and waiting for more interrupts.
 893        </para>
 894</sect1>
 895<sect1 id="uio_pci_generic_userspace">
 896<title>Writing userspace driver using uio_pci_generic</title>
 897        <para>
 898Userspace driver can use pci sysfs interface, or the
 899libpci libray that wraps it, to talk to the device and to
 900re-enable interrupts by writing to the command register.
 901        </para>
 902</sect1>
 903<sect1 id="uio_pci_generic_example">
 904<title>Example code using uio_pci_generic</title>
 905        <para>
 906Here is some sample userspace driver code using uio_pci_generic:
 907<programlisting>
 908#include &lt;stdlib.h&gt;
 909#include &lt;stdio.h&gt;
 910#include &lt;unistd.h&gt;
 911#include &lt;sys/types.h&gt;
 912#include &lt;sys/stat.h&gt;
 913#include &lt;fcntl.h&gt;
 914#include &lt;errno.h&gt;
 915
 916int main()
 917{
 918        int uiofd;
 919        int configfd;
 920        int err;
 921        int i;
 922        unsigned icount;
 923        unsigned char command_high;
 924
 925        uiofd = open(&quot;/dev/uio0&quot;, O_RDONLY);
 926        if (uiofd &lt; 0) {
 927                perror(&quot;uio open:&quot;);
 928                return errno;
 929        }
 930        configfd = open(&quot;/sys/class/uio/uio0/device/config&quot;, O_RDWR);
 931        if (uiofd &lt; 0) {
 932                perror(&quot;config open:&quot;);
 933                return errno;
 934        }
 935
 936        /* Read and cache command value */
 937        err = pread(configfd, &amp;command_high, 1, 5);
 938        if (err != 1) {
 939                perror(&quot;command config read:&quot;);
 940                return errno;
 941        }
 942        command_high &amp;= ~0x4;
 943
 944        for(i = 0;; ++i) {
 945                /* Print out a message, for debugging. */
 946                if (i == 0)
 947                        fprintf(stderr, &quot;Started uio test driver.\n&quot;);
 948                else
 949                        fprintf(stderr, &quot;Interrupts: %d\n&quot;, icount);
 950
 951                /****************************************/
 952                /* Here we got an interrupt from the
 953                   device. Do something to it. */
 954                /****************************************/
 955
 956                /* Re-enable interrupts. */
 957                err = pwrite(configfd, &amp;command_high, 1, 5);
 958                if (err != 1) {
 959                        perror(&quot;config write:&quot;);
 960                        break;
 961                }
 962
 963                /* Wait for next interrupt. */
 964                err = read(uiofd, &amp;icount, 4);
 965                if (err != 4) {
 966                        perror(&quot;uio read:&quot;);
 967                        break;
 968                }
 969
 970        }
 971        return errno;
 972}
 973
 974</programlisting>
 975        </para>
 976</sect1>
 977
 978</chapter>
 979
 980<appendix id="app1">
 981<title>Further information</title>
 982<itemizedlist>
 983        <listitem><para>
 984                        <ulink url="http://www.osadl.org">
 985                                OSADL homepage.</ulink>
 986                </para></listitem>
 987        <listitem><para>
 988                <ulink url="http://www.linutronix.de">
 989                 Linutronix homepage.</ulink>
 990                </para></listitem>
 991</itemizedlist>
 992</appendix>
 993
 994</book>
 995
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.