lkml.org 
[lkml]   [2007]   [Jul]   [18]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH 2/3] UIO: Documentation
    Date
    From: Hans J. Koch <hjk@linutronix.de>

    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 | 4 +
    Documentation/DocBook/uio-howto.tmpl | 611 +++++++++++++++++++++++++++++++++
    2 files changed, 615 insertions(+), 0 deletions(-)
    create mode 100644 Documentation/DocBook/uio-howto.tmpl

    diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
    index fd2ef4d..a0af560 100644
    --- a/Documentation/DocBook/kernel-api.tmpl
    +++ b/Documentation/DocBook/kernel-api.tmpl
    @@ -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
    index 0000000..e3bb29a
    --- /dev/null
    +++ b/Documentation/DocBook/uio-howto.tmpl
    @@ -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>
    --
    1.5.2.2
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2007-07-19 01:37    [W:0.060 / U:30.716 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site