diff options
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/uio-howto.tmpl | 90 |
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"> | ||
308 | cd /sys/devices/platform/uio_dummy/ | ||
309 | echo 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. | |||
354 | interrupt, it's your modules task to determine the irq number during | 329 | interrupt, it's your modules task to determine the irq number during |
355 | initialization. If you don't have a hardware generated interrupt but | 330 | initialization. If you don't have a hardware generated interrupt but |
356 | want to trigger the interrupt handler in some other way, set | 331 | want 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>. |
358 | uio_dummy module does this as it triggers the event mechanism in a timer | 333 | If you had no interrupt at all, you could set |
359 | routine. 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 |
361 | rarely makes sense. | 335 | rarely makes sense. |
362 | </para></listitem> | 336 | </para></listitem> |