luck/tmp_suning_uos_patched
1
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

UIO: fix up the UIO documentation

Browse Source 
Remove references to the old uio_dummy demo module from UIO documentation.
Add a small paragraph to make it clearer that UIO is not a universal driver
interface.

Signed-off-by: Hans J Koch <hjk@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
This commit is contained in:
Hans J Koch 2007-11-26 22:03:29 +01:00 committed by Greg Kroah-Hartman
parent dec13c1544
commit ed423c24a8
1 changed files with 32 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
Documentation/DocBook/uio-howto.tmpl
View File

@ -29,6 +29,12 @@
</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>
@ -94,6 +100,26 @@ interested in translating it, please email me
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">
@ -174,8 +200,9 @@ interested in translating it, please email me
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.
This interrupt simulation is done by calling
<function>uio_event_notify()</function>
from the timer's event handler.
</para>
<para>
@ -263,63 +290,11 @@ offset = N * getpagesize();
</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
Please have a look at <filename>uio_cif.c</filename> as an
example. The following paragraphs explain the different
sections of this file.
</para>
@ -354,9 +329,8 @@ See the description below for details.
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_CUSTOM</varname>.
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>