aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/uio-howto.tmpl90
1 files changed, 32 insertions, 58 deletions
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
index c119484258b8..fdd7f4f887b7 100644
--- a/Documentation/DocBook/uio-howto.tmpl
+++ b/Documentation/DocBook/uio-howto.tmpl
@@ -30,6 +30,12 @@
30 30
31<revhistory> 31<revhistory>
32 <revision> 32 <revision>
33 <revnumber>0.4</revnumber>
34 <date>2007-11-26</date>
35 <authorinitials>hjk</authorinitials>
36 <revremark>Removed section about uio_dummy.</revremark>
37 </revision>
38 <revision>
33 <revnumber>0.3</revnumber> 39 <revnumber>0.3</revnumber>
34 <date>2007-04-29</date> 40 <date>2007-04-29</date>
35 <authorinitials>hjk</authorinitials> 41 <authorinitials>hjk</authorinitials>
@@ -94,6 +100,26 @@ interested in translating it, please email me
94 user space. This simplifies development and reduces the risk of 100 user space. This simplifies development and reduces the risk of
95 serious bugs within a kernel module. 101 serious bugs within a kernel module.
96 </para> 102 </para>
103 <para>
104 Please note that UIO is not an universal driver interface. Devices
105 that are already handled well by other kernel subsystems (like
106 networking or serial or USB) are no candidates for an UIO driver.
107 Hardware that is ideally suited for an UIO driver fulfills all of
108 the following:
109 </para>
110<itemizedlist>
111<listitem>
112 <para>The device has memory that can be mapped. The device can be
113 controlled completely by writing to this memory.</para>
114</listitem>
115<listitem>
116 <para>The device usually generates interrupts.</para>
117</listitem>
118<listitem>
119 <para>The device does not fit into one of the standard kernel
120 subsystems.</para>
121</listitem>
122</itemizedlist>
97</sect1> 123</sect1>
98 124
99<sect1 id="thanks"> 125<sect1 id="thanks">
@@ -174,8 +200,9 @@ interested in translating it, please email me
174 For cards that don't generate interrupts but need to be 200 For cards that don't generate interrupts but need to be
175 polled, there is the possibility to set up a timer that 201 polled, there is the possibility to set up a timer that
176 triggers the interrupt handler at configurable time intervals. 202 triggers the interrupt handler at configurable time intervals.
177 See <filename>drivers/uio/uio_dummy.c</filename> for an 203 This interrupt simulation is done by calling
178 example of this technique. 204 <function>uio_event_notify()</function>
205 from the timer's event handler.
179 </para> 206 </para>
180 207
181 <para> 208 <para>
@@ -263,63 +290,11 @@ offset = N * getpagesize();
263</sect1> 290</sect1>
264</chapter> 291</chapter>
265 292
266<chapter id="using-uio_dummy" xreflabel="Using uio_dummy">
267<?dbhtml filename="using-uio_dummy.html"?>
268<title>Using uio_dummy</title>
269 <para>
270 Well, there is no real use for uio_dummy. Its only purpose is
271 to test most parts of the UIO system (everything except
272 hardware interrupts), and to serve as an example for the
273 kernel module that you will have to write yourself.
274 </para>
275
276<sect1 id="what_uio_dummy_does">
277<title>What uio_dummy does</title>
278 <para>
279 The kernel module <filename>uio_dummy.ko</filename> creates a
280 device that uses a timer to generate periodic interrupts. The
281 interrupt handler does nothing but increment a counter. The
282 driver adds two custom attributes, <varname>count</varname>
283 and <varname>freq</varname>, that appear under
284 <filename>/sys/devices/platform/uio_dummy/</filename>.
285 </para>
286
287 <para>
288 The attribute <varname>count</varname> can be read and
289 written. The associated file
290 <filename>/sys/devices/platform/uio_dummy/count</filename>
291 appears as a normal text file and contains the total number of
292 timer interrupts. If you look at it (e.g. using
293 <function>cat</function>), you'll notice it is slowly counting
294 up.
295 </para>
296
297 <para>
298 The attribute <varname>freq</varname> can be read and written.
299 The content of
300 <filename>/sys/devices/platform/uio_dummy/freq</filename>
301 represents the number of system timer ticks between two timer
302 interrupts. The default value of <varname>freq</varname> is
303 the value of the kernel variable <varname>HZ</varname>, which
304 gives you an interval of one second. Lower values will
305 increase the frequency. Try the following:
306 </para>
307<programlisting format="linespecific">
308cd /sys/devices/platform/uio_dummy/
309echo 100 > freq
310</programlisting>
311 <para>
312 Use <function>cat count</function> to see how the interrupt
313 frequency changes.
314 </para>
315</sect1>
316</chapter>
317
318<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> 293<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
319<?dbhtml filename="custom_kernel_module.html"?> 294<?dbhtml filename="custom_kernel_module.html"?>
320<title>Writing your own kernel module</title> 295<title>Writing your own kernel module</title>
321 <para> 296 <para>
322 Please have a look at <filename>uio_dummy.c</filename> as an 297 Please have a look at <filename>uio_cif.c</filename> as an
323 example. The following paragraphs explain the different 298 example. The following paragraphs explain the different
324 sections of this file. 299 sections of this file.
325 </para> 300 </para>
@@ -354,9 +329,8 @@ See the description below for details.
354interrupt, it's your modules task to determine the irq number during 329interrupt, it's your modules task to determine the irq number during
355initialization. If you don't have a hardware generated interrupt but 330initialization. If you don't have a hardware generated interrupt but
356want to trigger the interrupt handler in some other way, set 331want to trigger the interrupt handler in some other way, set
357<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. The 332<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
358uio_dummy module does this as it triggers the event mechanism in a timer 333If you had no interrupt at all, you could set
359routine. If you had no interrupt at all, you could set
360<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this 334<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
361rarely makes sense. 335rarely makes sense.
362</para></listitem> 336</para></listitem>