UIO: Documentation
authorHans J. Koch <hjk@linutronix.de>
Mon, 11 Dec 2006 15:59:59 +0000 (16:59 +0100)
committerGreg Kroah-Hartman <gregkh@suse.de>
Wed, 18 Jul 2007 22:57:16 +0000 (15:57 -0700)
Documentation for the UIO interface

From: Hans J. Koch <hjk@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Documentation/DocBook/kernel-api.tmpl
Documentation/DocBook/uio-howto.tmpl [new file with mode: 0644]

index fd2ef4d..a0af560 100644 (file)
@@ -408,6 +408,10 @@ X!Edrivers/pnp/system.c
 !Edrivers/pnp/manager.c
 !Edrivers/pnp/support.c
      </sect1>
+     <sect1><title>Userspace IO devices</title>
+!Edrivers/uio/uio.c
+!Iinclude/linux/uio_driver.h
+     </sect1>
   </chapter>
 
   <chapter id="blkdev">
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
new file mode 100644 (file)
index 0000000..e3bb29a
--- /dev/null
@@ -0,0 +1,611 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []>
+
+<book id="index">
+<bookinfo>
+<title>The Userspace I/O HOWTO</title>
+
+<author>
+      <firstname>Hans-Jürgen</firstname>
+      <surname>Koch</surname>
+      <authorblurb><para>Linux developer, Linutronix</para></authorblurb>
+       <affiliation>
+       <orgname>
+               <ulink url="http://www.linutronix.de">Linutronix</ulink>
+       </orgname>
+
+       <address>
+          <email>hjk@linutronix.de</email>
+       </address>
+    </affiliation>
+</author>
+
+<pubdate>2006-12-11</pubdate>
+
+<abstract>
+       <para>This HOWTO describes concept and usage of Linux kernel's
+               Userspace I/O system.</para>
+</abstract>
+
+<revhistory>
+       <revision>
+       <revnumber>0.3</revnumber>
+       <date>2007-04-29</date>
+       <authorinitials>hjk</authorinitials>
+       <revremark>Added section about userspace drivers.</revremark>
+       </revision>
+       <revision>
+       <revnumber>0.2</revnumber>
+       <date>2007-02-13</date>
+       <authorinitials>hjk</authorinitials>
+       <revremark>Update after multiple mappings were added.</revremark>
+       </revision>
+       <revision>
+       <revnumber>0.1</revnumber>
+       <date>2006-12-11</date>
+       <authorinitials>hjk</authorinitials>
+       <revremark>First draft.</revremark>
+       </revision>
+</revhistory>
+</bookinfo>
+
+<chapter id="aboutthisdoc">
+<?dbhtml filename="about.html"?>
+<title>About this document</title>
+
+<sect1 id="copyright">
+<?dbhtml filename="copyright.html"?>
+<title>Copyright and License</title>
+<para>
+      Copyright (c) 2006 by Hans-Jürgen Koch.</para>
+<para>
+This documentation is Free Software licensed under the terms of the
+GPL version 2.
+</para>
+</sect1>
+
+<sect1 id="translations">
+<?dbhtml filename="translations.html"?>
+<title>Translations</title>
+
+<para>If you know of any translations for this document, or you are
+interested in translating it, please email me
+<email>hjk@linutronix.de</email>.
+</para>
+</sect1>
+
+<sect1 id="preface">
+<title>Preface</title>
+       <para>
+       For many types of devices, creating a Linux kernel driver is
+       overkill.  All that is really needed is some way to handle an
+       interrupt and provide access to the memory space of the
+       device.  The logic of controlling the device does not
+       necessarily have to be within the kernel, as the device does
+       not need to take advantage of any of other resources that the
+       kernel provides.  One such common class of devices that are
+       like this are for industrial I/O cards.
+       </para>
+       <para>
+       To address this situation, the userspace I/O system (UIO) was
+       designed.  For typical industrial I/O cards, only a very small
+       kernel module is needed. The main part of the driver will run in
+       user space. This simplifies development and reduces the risk of
+       serious bugs within a kernel module.
+       </para>
+</sect1>
+
+<sect1 id="thanks">
+<title>Acknowledgments</title>
+       <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of
+       Linutronix, who have not only written most of the UIO code, but also
+       helped greatly writing this HOWTO by giving me all kinds of background
+       information.</para>
+</sect1>
+
+<sect1 id="feedback">
+<title>Feedback</title>
+       <para>Find something wrong with this document? (Or perhaps something
+       right?) I would love to hear from you. Please email me at
+       <email>hjk@linutronix.de</email>.</para>
+</sect1>
+</chapter>
+
+<chapter id="about">
+<?dbhtml filename="about.html"?>
+<title>About UIO</title>
+
+<para>If you use UIO for your card's driver, here's what you get:</para>
+
+<itemizedlist>
+<listitem>
+       <para>only one small kernel module to write and maintain.</para>
+</listitem>
+<listitem>
+       <para>develop the main part of your driver in user space,
+       with all the tools and libraries you're used to.</para>
+</listitem>
+<listitem>
+       <para>bugs in your driver won't crash the kernel.</para>
+</listitem>
+<listitem>
+       <para>updates of your driver can take place without recompiling
+       the kernel.</para>
+</listitem>
+<listitem>
+       <para>if you need to keep some parts of your driver closed source,
+       you can do so without violating the GPL license on the kernel.</para>
+</listitem>
+</itemizedlist>
+
+<sect1 id="how_uio_works">
+<title>How UIO works</title>
+       <para>
+       Each UIO device is accessed through a device file and several
+       sysfs attribute files. The device file will be called
+       <filename>/dev/uio0</filename> for the first device, and
+       <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename>
+       and so on for subsequent devices.
+       </para>
+
+       <para><filename>/dev/uioX</filename> is used to access the
+       address space of the card. Just use
+       <function>mmap()</function> to access registers or RAM
+       locations of your card.
+       </para>
+
+       <para>
+       Interrupts are handled by reading from
+       <filename>/dev/uioX</filename>. A blocking
+       <function>read()</function> from
+       <filename>/dev/uioX</filename> will return as soon as an
+       interrupt occurs. You can also use
+       <function>select()</function> on
+       <filename>/dev/uioX</filename> to wait for an interrupt. The
+       integer value read from <filename>/dev/uioX</filename>
+       represents the total interrupt count. You can use this number
+       to figure out if you missed some interrupts.
+       </para>
+
+       <para>
+       To handle interrupts properly, your custom kernel module can
+       provide its own interrupt handler. It will automatically be
+       called by the built-in handler.
+       </para>
+
+       <para>
+       For cards that don't generate interrupts but need to be
+       polled, there is the possibility to set up a timer that
+       triggers the interrupt handler at configurable time intervals.
+       See <filename>drivers/uio/uio_dummy.c</filename> for an
+       example of this technique.
+       </para>
+
+       <para>
+       Each driver provides attributes that are used to read or write
+       variables. These attributes are accessible through sysfs
+       files.  A custom kernel driver module can add its own
+       attributes to the device owned by the uio driver, but not added
+       to the UIO device itself at this time.  This might change in the
+       future if it would be found to be useful.
+       </para>
+
+       <para>
+       The following standard attributes are provided by the UIO
+       framework:
+       </para>
+<itemizedlist>
+<listitem>
+       <para>
+       <filename>name</filename>: The name of your device. It is
+       recommended to use the name of your kernel module for this.
+       </para>
+</listitem>
+<listitem>
+       <para>
+       <filename>version</filename>: A version string defined by your
+       driver. This allows the user space part of your driver to deal
+       with different versions of the kernel module.
+       </para>
+</listitem>
+<listitem>
+       <para>
+       <filename>event</filename>: The total number of interrupts
+       handled by the driver since the last time the device node was
+       read.
+       </para>
+</listitem>
+</itemizedlist>
+<para>
+       These attributes appear under the
+       <filename>/sys/class/uio/uioX</filename> directory.  Please
+       note that this directory might be a symlink, and not a real
+       directory.  Any userspace code that accesses it must be able
+       to handle this.
+</para>
+<para>
+       Each UIO device can make one or more memory regions available for
+       memory mapping. This is necessary because some industrial I/O cards
+       require access to more than one PCI memory region in a driver.
+</para>
+<para>
+       Each mapping has its own directory in sysfs, the first mapping
+       appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>.
+       Subsequent mappings create directories <filename>map1/</filename>,
+       <filename>map2/</filename>, and so on. These directories will only
+       appear if the size of the mapping is not 0.
+</para>
+<para>
+       Each <filename>mapX/</filename> directory contains two read-only files
+       that show start address and size of the memory:
+</para>
+<itemizedlist>
+<listitem>
+       <para>
+       <filename>addr</filename>: The address of memory that can be mapped.
+       </para>
+</listitem>
+<listitem>
+       <para>
+       <filename>size</filename>: The size, in bytes, of the memory
+       pointed to by addr.
+       </para>
+</listitem>
+</itemizedlist>
+
+<para>
+       From userspace, the different mappings are distinguished by adjusting
+       the <varname>offset</varname> parameter of the
+       <function>mmap()</function> call. To map the memory of mapping N, you
+       have to use N times the page size as your offset:
+</para>
+<programlisting format="linespecific">
+offset = N * getpagesize();
+</programlisting>
+
+</sect1>
+</chapter>
+
+<chapter id="using-uio_dummy" xreflabel="Using uio_dummy">
+<?dbhtml filename="using-uio_dummy.html"?>
+<title>Using uio_dummy</title>
+       <para>
+       Well, there is no real use for uio_dummy. Its only purpose is
+       to test most parts of the UIO system (everything except
+       hardware interrupts), and to serve as an example for the
+       kernel module that you will have to write yourself.
+       </para>
+
+<sect1 id="what_uio_dummy_does">
+<title>What uio_dummy does</title>
+       <para>
+       The kernel module <filename>uio_dummy.ko</filename> creates a
+       device that uses a timer to generate periodic interrupts. The
+       interrupt handler does nothing but increment a counter. The
+       driver adds two custom attributes, <varname>count</varname>
+       and <varname>freq</varname>, that appear under
+       <filename>/sys/devices/platform/uio_dummy/</filename>.
+       </para>
+
+       <para>
+       The attribute <varname>count</varname> can be read and
+       written.  The associated file
+       <filename>/sys/devices/platform/uio_dummy/count</filename>
+       appears as a normal text file and contains the total number of
+       timer interrupts. If you look at it (e.g. using
+       <function>cat</function>), you'll notice it is slowly counting
+       up.
+       </para>
+
+       <para>
+       The attribute <varname>freq</varname> can be read and written.
+       The content of
+       <filename>/sys/devices/platform/uio_dummy/freq</filename>
+       represents the number of system timer ticks between two timer
+       interrupts. The default value of <varname>freq</varname> is
+       the value of the kernel variable <varname>HZ</varname>, which
+       gives you an interval of one second. Lower values will
+       increase the frequency. Try the following:
+       </para>
+<programlisting format="linespecific">
+cd /sys/devices/platform/uio_dummy/
+echo 100 > freq
+</programlisting>
+       <para>
+       Use <function>cat count</function> to see how the interrupt
+       frequency changes.
+       </para>
+</sect1>
+</chapter>
+
+<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
+<?dbhtml filename="custom_kernel_module.html"?>
+<title>Writing your own kernel module</title>
+       <para>
+       Please have a look at <filename>uio_dummy.c</filename> as an
+       example. The following paragraphs explain the different
+       sections of this file.
+       </para>
+
+<sect1 id="uio_info">
+<title>struct uio_info</title>
+       <para>
+       This structure tells the framework the details of your driver,
+       Some of the members are required, others are optional.
+       </para>
+
+<itemizedlist>
+<listitem><para>
+<varname>char *name</varname>: Required. The name of your driver as
+it will appear in sysfs. I recommend using the name of your module for this.
+</para></listitem>
+
+<listitem><para>
+<varname>char *version</varname>: Required. This string appears in
+<filename>/sys/class/uio/uioX/version</filename>.
+</para></listitem>
+
+<listitem><para>
+<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you
+have memory that can be mapped with <function>mmap()</function>. For each
+mapping you need to fill one of the <varname>uio_mem</varname> structures.
+See the description below for details.
+</para></listitem>
+
+<listitem><para>
+<varname>long irq</varname>: Required. If your hardware generates an
+interrupt, it's your modules task to determine the irq number during
+initialization. If you don't have a hardware generated interrupt but
+want to trigger the interrupt handler in some other way, set
+<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. The
+uio_dummy module does this as it triggers the event mechanism in a timer
+routine. If you had no interrupt at all, you could set
+<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
+rarely makes sense.
+</para></listitem>
+
+<listitem><para>
+<varname>unsigned long irq_flags</varname>: Required if you've set
+<varname>irq</varname> to a hardware interrupt number. The flags given
+here will be used in the call to <function>request_irq()</function>.
+</para></listitem>
+
+<listitem><para>
+<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct
+*vma)</varname>: Optional. If you need a special
+<function>mmap()</function> function, you can set it here. If this
+pointer is not NULL, your <function>mmap()</function> will be called
+instead of the built-in one.
+</para></listitem>
+
+<listitem><para>
+<varname>int (*open)(struct uio_info *info, struct inode *inode)
+</varname>: Optional. You might want to have your own
+<function>open()</function>, e.g. to enable interrupts only when your
+device is actually used.
+</para></listitem>
+
+<listitem><para>
+<varname>int (*release)(struct uio_info *info, struct inode *inode)
+</varname>: Optional. If you define your own
+<function>open()</function>, you will probably also want a custom
+<function>release()</function> function.
+</para></listitem>
+</itemizedlist>
+
+<para>
+Usually, your device will have one or more memory regions that can be mapped
+to user space. For each region, you have to set up a
+<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array.
+Here's a description of the fields of <varname>struct uio_mem</varname>:
+</para>
+
+<itemizedlist>
+<listitem><para>
+<varname>int memtype</varname>: Required if the mapping is used. Set this to
+<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
+card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
+memory (e.g. allocated with <function>kmalloc()</function>). There's also
+<varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
+</para></listitem>
+
+<listitem><para>
+<varname>unsigned long addr</varname>: Required if the mapping is used.
+Fill in the address of your memory block. This address is the one that
+appears in sysfs.
+</para></listitem>
+
+<listitem><para>
+<varname>unsigned long size</varname>: Fill in the size of the
+memory block that <varname>addr</varname> points to. If <varname>size</varname>
+is zero, the mapping is considered unused. Note that you
+<emphasis>must</emphasis> initialize <varname>size</varname> with zero for
+all unused mappings.
+</para></listitem>
+
+<listitem><para>
+<varname>void *internal_addr</varname>: If you have to access this memory
+region from within your kernel module, you will want to map it internally by
+using something like <function>ioremap()</function>. Addresses
+returned by this function cannot be mapped to user space, so you must not
+store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
+instead to remember such an address.
+</para></listitem>
+</itemizedlist>
+
+<para>
+Please do not touch the <varname>kobj</varname> element of
+<varname>struct uio_mem</varname>! It is used by the UIO framework
+to set up sysfs files for this mapping. Simply leave it alone.
+</para>
+</sect1>
+
+<sect1 id="adding_irq_handler">
+<title>Adding an interrupt handler</title>
+       <para>
+       What you need to do in your interrupt handler depends on your
+       hardware and on how you want to handle it. You should try to
+       keep the amount of code in your kernel interrupt handler low.
+       If your hardware requires no action that you
+       <emphasis>have</emphasis> to perform after each interrupt,
+       then your handler can be empty.</para> <para>If, on the other
+       hand, your hardware <emphasis>needs</emphasis> some action to
+       be performed after each interrupt, then you
+       <emphasis>must</emphasis> do it in your kernel module. Note
+       that you cannot rely on the userspace part of your driver. Your
+       userspace program can terminate at any time, possibly leaving
+       your hardware in a state where proper interrupt handling is
+       still required.
+       </para>
+
+       <para>
+       There might also be applications where you want to read data
+       from your hardware at each interrupt and buffer it in a piece
+       of kernel memory you've allocated for that purpose.  With this
+       technique you could avoid loss of data if your userspace
+       program misses an interrupt.
+       </para>
+
+       <para>
+       A note on shared interrupts: Your driver should support
+       interrupt sharing whenever this is possible. It is possible if
+       and only if your driver can detect whether your hardware has
+       triggered the interrupt or not. This is usually done by looking
+       at an interrupt status register. If your driver sees that the
+       IRQ bit is actually set, it will perform its actions, and the
+       handler returns IRQ_HANDLED. If the driver detects that it was
+       not your hardware that caused the interrupt, it will do nothing
+       and return IRQ_NONE, allowing the kernel to call the next
+       possible interrupt handler.
+       </para>
+
+       <para>
+       If you decide not to support shared interrupts, your card
+       won't work in computers with no free interrupts. As this
+       frequently happens on the PC platform, you can save yourself a
+       lot of trouble by supporting interrupt sharing.
+       </para>
+</sect1>
+
+</chapter>
+
+<chapter id="userspace_driver" xreflabel="Writing a driver in user space">
+<?dbhtml filename="userspace_driver.html"?>
+<title>Writing a driver in userspace</title>
+       <para>
+       Once you have a working kernel module for your hardware, you can
+       write the userspace part of your driver. You don't need any special
+       libraries, your driver can be written in any reasonable language,
+       you can use floating point numbers and so on. In short, you can
+       use all the tools and libraries you'd normally use for writing a
+       userspace application.
+       </para>
+
+<sect1 id="getting_uio_information">
+<title>Getting information about your UIO device</title>
+       <para>
+       Information about all UIO devices is available in sysfs. The
+       first thing you should do in your driver is check
+       <varname>name</varname> and <varname>version</varname> to
+       make sure your talking to the right device and that its kernel
+       driver has the version you expect.
+       </para>
+       <para>
+       You should also make sure that the memory mapping you need
+       exists and has the size you expect.
+       </para>
+       <para>
+       There is a tool called <varname>lsuio</varname> that lists
+       UIO devices and their attributes. It is available here:
+       </para>
+       <para>
+       <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
+               http://www.osadl.org/projects/downloads/UIO/user/</ulink>
+       </para>
+       <para>
+       With <varname>lsuio</varname> you can quickly check if your
+       kernel module is loaded and which attributes it exports.
+       Have a look at the manpage for details.
+       </para>
+       <para>
+       The source code of <varname>lsuio</varname> can serve as an
+       example for getting information about an UIO device.
+       The file <filename>uio_helper.c</filename> contains a lot of
+       functions you could use in your userspace driver code.
+       </para>
+</sect1>
+
+<sect1 id="mmap_device_memory">
+<title>mmap() device memory</title>
+       <para>
+       After you made sure you've got the right device with the
+       memory mappings you need, all you have to do is to call
+       <function>mmap()</function> to map the device's memory
+       to userspace.
+       </para>
+       <para>
+       The parameter <varname>offset</varname> of the
+       <function>mmap()</function> call has a special meaning
+       for UIO devices: It is used to select which mapping of
+       your device you want to map. To map the memory of
+       mapping N, you have to use N times the page size as
+       your offset:
+       </para>
+<programlisting format="linespecific">
+       offset = N * getpagesize();
+</programlisting>
+       <para>
+       N starts from zero, so if you've got only one memory
+       range to map, set <varname>offset = 0</varname>.
+       A drawback of this technique is that memory is always
+       mapped beginning with its start address.
+       </para>
+</sect1>
+
+<sect1 id="wait_for_interrupts">
+<title>Waiting for interrupts</title>
+       <para>
+       After you successfully mapped your devices memory, you
+       can access it like an ordinary array. Usually, you will
+       perform some initialization. After that, your hardware
+       starts working and will generate an interrupt as soon
+       as it's finished, has some data available, or needs your
+       attention because an error occured.
+       </para>
+       <para>
+       <filename>/dev/uioX</filename> is a read-only file. A
+       <function>read()</function> will always block until an
+       interrupt occurs. There is only one legal value for the
+       <varname>count</varname> parameter of
+       <function>read()</function>, and that is the size of a
+       signed 32 bit integer (4). Any other value for
+       <varname>count</varname> causes <function>read()</function>
+       to fail. The signed 32 bit integer read is the interrupt
+       count of your device. If the value is one more than the value
+       you read the last time, everything is OK. If the difference
+       is greater than one, you missed interrupts.
+       </para>
+       <para>
+       You can also use <function>select()</function> on
+       <filename>/dev/uioX</filename>.
+       </para>
+</sect1>
+
+</chapter>
+
+<appendix id="app1">
+<title>Further information</title>
+<itemizedlist>
+       <listitem><para>
+                       <ulink url="http://www.osadl.org">
+                               OSADL homepage.</ulink>
+               </para></listitem>
+       <listitem><para>
+               <ulink url="http://www.linutronix.de">
+                Linutronix homepage.</ulink>
+               </para></listitem>
+</itemizedlist>
+</appendix>
+
+</book>