uio-howto.tmpl

linux 内核源代码

<?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>[e-mail]</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.4</revnumber>
	<date>2007-11-26</date>
	<authorinitials>hjk</authorinitials>
	<revremark>Removed section about uio_dummy.</revremark>
	</revision>
	<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>[e-mail]</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>
	<para>
	Please note that UIO is not an universal driver interface. Devices
	that are already handled well by other kernel subsystems (like
	networking or serial or USB) are no candidates for an UIO driver.
	Hardware that is ideally suited for an UIO driver fulfills all of
	the following:
	</para>
<itemizedlist>
<listitem>
	<para>The device has memory that can be mapped. The device can be
	controlled completely by writing to this memory.</para>
</listitem>
<listitem>
	<para>The device usually generates interrupts.</para>
</listitem>
<listitem>
	<para>The device does not fit into one of the standard kernel
	subsystems.</para>
</listitem>
</itemizedlist>
</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>[e-mail]</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>
</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.
	This interrupt simulation is done by calling
	<function>uio_event_notify()</function>
	from the timer's event handler.
	</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>