]>
Commit | Line | Data |
---|---|---|
e3e0a28b HK |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="index"> | |
6 | <bookinfo> | |
7 | <title>The Userspace I/O HOWTO</title> | |
8 | ||
9 | <author> | |
10 | <firstname>Hans-Jürgen</firstname> | |
11 | <surname>Koch</surname> | |
12 | <authorblurb><para>Linux developer, Linutronix</para></authorblurb> | |
13 | <affiliation> | |
14 | <orgname> | |
15 | <ulink url="http://www.linutronix.de">Linutronix</ulink> | |
16 | </orgname> | |
17 | ||
18 | <address> | |
f99e0e98 | 19 | <email>hjk@hansjkoch.de</email> |
e3e0a28b HK |
20 | </address> |
21 | </affiliation> | |
22 | </author> | |
23 | ||
17149d9f MF |
24 | <copyright> |
25 | <year>2006-2008</year> | |
26 | <holder>Hans-Jürgen Koch.</holder> | |
27 | </copyright> | |
ccb86a69 MT |
28 | <copyright> |
29 | <year>2009</year> | |
30 | <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> | |
31 | </copyright> | |
17149d9f MF |
32 | |
33 | <legalnotice> | |
34 | <para> | |
35 | This documentation is Free Software licensed under the terms of the | |
36 | GPL version 2. | |
37 | </para> | |
38 | </legalnotice> | |
39 | ||
e3e0a28b HK |
40 | <pubdate>2006-12-11</pubdate> |
41 | ||
42 | <abstract> | |
43 | <para>This HOWTO describes concept and usage of Linux kernel's | |
44 | Userspace I/O system.</para> | |
45 | </abstract> | |
46 | ||
47 | <revhistory> | |
a164a8a6 SH |
48 | <revision> |
49 | <revnumber>0.10</revnumber> | |
50 | <date>2016-10-17</date> | |
51 | <authorinitials>sch</authorinitials> | |
52 | <revremark>Added generic hyperv driver | |
53 | </revremark> | |
54 | </revision> | |
ccb86a69 MT |
55 | <revision> |
56 | <revnumber>0.9</revnumber> | |
57 | <date>2009-07-16</date> | |
58 | <authorinitials>mst</authorinitials> | |
59 | <revremark>Added generic pci driver | |
60 | </revremark> | |
61 | </revision> | |
82057791 HK |
62 | <revision> |
63 | <revnumber>0.8</revnumber> | |
64 | <date>2008-12-24</date> | |
65 | <authorinitials>hjk</authorinitials> | |
66 | <revremark>Added name attributes in mem and portio sysfs directories. | |
67 | </revremark> | |
68 | </revision> | |
6a1b6996 HK |
69 | <revision> |
70 | <revnumber>0.7</revnumber> | |
71 | <date>2008-12-23</date> | |
72 | <authorinitials>hjk</authorinitials> | |
73 | <revremark>Added generic platform drivers and offset attribute.</revremark> | |
74 | </revision> | |
a2ab3d30 HK |
75 | <revision> |
76 | <revnumber>0.6</revnumber> | |
77 | <date>2008-12-05</date> | |
78 | <authorinitials>hjk</authorinitials> | |
79 | <revremark>Added description of portio sysfs attributes.</revremark> | |
80 | </revision> | |
328a14e7 HK |
81 | <revision> |
82 | <revnumber>0.5</revnumber> | |
83 | <date>2008-05-22</date> | |
84 | <authorinitials>hjk</authorinitials> | |
85 | <revremark>Added description of write() function.</revremark> | |
86 | </revision> | |
ed423c24 HK |
87 | <revision> |
88 | <revnumber>0.4</revnumber> | |
89 | <date>2007-11-26</date> | |
90 | <authorinitials>hjk</authorinitials> | |
91 | <revremark>Removed section about uio_dummy.</revremark> | |
92 | </revision> | |
e3e0a28b HK |
93 | <revision> |
94 | <revnumber>0.3</revnumber> | |
95 | <date>2007-04-29</date> | |
96 | <authorinitials>hjk</authorinitials> | |
97 | <revremark>Added section about userspace drivers.</revremark> | |
98 | </revision> | |
99 | <revision> | |
100 | <revnumber>0.2</revnumber> | |
101 | <date>2007-02-13</date> | |
102 | <authorinitials>hjk</authorinitials> | |
103 | <revremark>Update after multiple mappings were added.</revremark> | |
104 | </revision> | |
105 | <revision> | |
106 | <revnumber>0.1</revnumber> | |
107 | <date>2006-12-11</date> | |
108 | <authorinitials>hjk</authorinitials> | |
109 | <revremark>First draft.</revremark> | |
110 | </revision> | |
111 | </revhistory> | |
112 | </bookinfo> | |
113 | ||
114 | <chapter id="aboutthisdoc"> | |
4f7e5309 | 115 | <?dbhtml filename="aboutthis.html"?> |
e3e0a28b HK |
116 | <title>About this document</title> |
117 | ||
e3e0a28b HK |
118 | <sect1 id="translations"> |
119 | <?dbhtml filename="translations.html"?> | |
120 | <title>Translations</title> | |
121 | ||
122 | <para>If you know of any translations for this document, or you are | |
123 | interested in translating it, please email me | |
f99e0e98 | 124 | <email>hjk@hansjkoch.de</email>. |
e3e0a28b HK |
125 | </para> |
126 | </sect1> | |
127 | ||
128 | <sect1 id="preface"> | |
129 | <title>Preface</title> | |
130 | <para> | |
131 | For many types of devices, creating a Linux kernel driver is | |
132 | overkill. All that is really needed is some way to handle an | |
133 | interrupt and provide access to the memory space of the | |
134 | device. The logic of controlling the device does not | |
135 | necessarily have to be within the kernel, as the device does | |
136 | not need to take advantage of any of other resources that the | |
137 | kernel provides. One such common class of devices that are | |
138 | like this are for industrial I/O cards. | |
139 | </para> | |
140 | <para> | |
141 | To address this situation, the userspace I/O system (UIO) was | |
142 | designed. For typical industrial I/O cards, only a very small | |
143 | kernel module is needed. The main part of the driver will run in | |
144 | user space. This simplifies development and reduces the risk of | |
145 | serious bugs within a kernel module. | |
146 | </para> | |
ed423c24 HK |
147 | <para> |
148 | Please note that UIO is not an universal driver interface. Devices | |
149 | that are already handled well by other kernel subsystems (like | |
150 | networking or serial or USB) are no candidates for an UIO driver. | |
151 | Hardware that is ideally suited for an UIO driver fulfills all of | |
152 | the following: | |
153 | </para> | |
154 | <itemizedlist> | |
155 | <listitem> | |
156 | <para>The device has memory that can be mapped. The device can be | |
157 | controlled completely by writing to this memory.</para> | |
158 | </listitem> | |
159 | <listitem> | |
160 | <para>The device usually generates interrupts.</para> | |
161 | </listitem> | |
162 | <listitem> | |
163 | <para>The device does not fit into one of the standard kernel | |
164 | subsystems.</para> | |
165 | </listitem> | |
166 | </itemizedlist> | |
e3e0a28b HK |
167 | </sect1> |
168 | ||
169 | <sect1 id="thanks"> | |
170 | <title>Acknowledgments</title> | |
171 | <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of | |
172 | Linutronix, who have not only written most of the UIO code, but also | |
173 | helped greatly writing this HOWTO by giving me all kinds of background | |
174 | information.</para> | |
175 | </sect1> | |
176 | ||
177 | <sect1 id="feedback"> | |
178 | <title>Feedback</title> | |
179 | <para>Find something wrong with this document? (Or perhaps something | |
180 | right?) I would love to hear from you. Please email me at | |
f99e0e98 | 181 | <email>hjk@hansjkoch.de</email>.</para> |
e3e0a28b HK |
182 | </sect1> |
183 | </chapter> | |
184 | ||
185 | <chapter id="about"> | |
186 | <?dbhtml filename="about.html"?> | |
187 | <title>About UIO</title> | |
188 | ||
189 | <para>If you use UIO for your card's driver, here's what you get:</para> | |
190 | ||
191 | <itemizedlist> | |
192 | <listitem> | |
193 | <para>only one small kernel module to write and maintain.</para> | |
194 | </listitem> | |
195 | <listitem> | |
196 | <para>develop the main part of your driver in user space, | |
197 | with all the tools and libraries you're used to.</para> | |
198 | </listitem> | |
199 | <listitem> | |
200 | <para>bugs in your driver won't crash the kernel.</para> | |
201 | </listitem> | |
202 | <listitem> | |
203 | <para>updates of your driver can take place without recompiling | |
204 | the kernel.</para> | |
205 | </listitem> | |
e3e0a28b HK |
206 | </itemizedlist> |
207 | ||
208 | <sect1 id="how_uio_works"> | |
209 | <title>How UIO works</title> | |
210 | <para> | |
211 | Each UIO device is accessed through a device file and several | |
212 | sysfs attribute files. The device file will be called | |
213 | <filename>/dev/uio0</filename> for the first device, and | |
214 | <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> | |
215 | and so on for subsequent devices. | |
216 | </para> | |
217 | ||
218 | <para><filename>/dev/uioX</filename> is used to access the | |
219 | address space of the card. Just use | |
220 | <function>mmap()</function> to access registers or RAM | |
221 | locations of your card. | |
222 | </para> | |
223 | ||
224 | <para> | |
225 | Interrupts are handled by reading from | |
226 | <filename>/dev/uioX</filename>. A blocking | |
227 | <function>read()</function> from | |
228 | <filename>/dev/uioX</filename> will return as soon as an | |
229 | interrupt occurs. You can also use | |
230 | <function>select()</function> on | |
231 | <filename>/dev/uioX</filename> to wait for an interrupt. The | |
232 | integer value read from <filename>/dev/uioX</filename> | |
233 | represents the total interrupt count. You can use this number | |
234 | to figure out if you missed some interrupts. | |
235 | </para> | |
328a14e7 HK |
236 | <para> |
237 | For some hardware that has more than one interrupt source internally, | |
238 | but not separate IRQ mask and status registers, there might be | |
239 | situations where userspace cannot determine what the interrupt source | |
240 | was if the kernel handler disables them by writing to the chip's IRQ | |
241 | register. In such a case, the kernel has to disable the IRQ completely | |
242 | to leave the chip's register untouched. Now the userspace part can | |
243 | determine the cause of the interrupt, but it cannot re-enable | |
244 | interrupts. Another cornercase is chips where re-enabling interrupts | |
245 | is a read-modify-write operation to a combined IRQ status/acknowledge | |
246 | register. This would be racy if a new interrupt occurred | |
247 | simultaneously. | |
248 | </para> | |
249 | <para> | |
250 | To address these problems, UIO also implements a write() function. It | |
251 | is normally not used and can be ignored for hardware that has only a | |
252 | single interrupt source or has separate IRQ mask and status registers. | |
253 | If you need it, however, a write to <filename>/dev/uioX</filename> | |
254 | will call the <function>irqcontrol()</function> function implemented | |
255 | by the driver. You have to write a 32-bit value that is usually either | |
256 | 0 or 1 to disable or enable interrupts. If a driver does not implement | |
257 | <function>irqcontrol()</function>, <function>write()</function> will | |
258 | return with <varname>-ENOSYS</varname>. | |
259 | </para> | |
e3e0a28b HK |
260 | |
261 | <para> | |
262 | To handle interrupts properly, your custom kernel module can | |
263 | provide its own interrupt handler. It will automatically be | |
264 | called by the built-in handler. | |
265 | </para> | |
266 | ||
267 | <para> | |
268 | For cards that don't generate interrupts but need to be | |
269 | polled, there is the possibility to set up a timer that | |
270 | triggers the interrupt handler at configurable time intervals. | |
ed423c24 HK |
271 | This interrupt simulation is done by calling |
272 | <function>uio_event_notify()</function> | |
273 | from the timer's event handler. | |
e3e0a28b HK |
274 | </para> |
275 | ||
276 | <para> | |
277 | Each driver provides attributes that are used to read or write | |
278 | variables. These attributes are accessible through sysfs | |
279 | files. A custom kernel driver module can add its own | |
280 | attributes to the device owned by the uio driver, but not added | |
281 | to the UIO device itself at this time. This might change in the | |
282 | future if it would be found to be useful. | |
283 | </para> | |
284 | ||
285 | <para> | |
286 | The following standard attributes are provided by the UIO | |
287 | framework: | |
288 | </para> | |
289 | <itemizedlist> | |
290 | <listitem> | |
291 | <para> | |
292 | <filename>name</filename>: The name of your device. It is | |
293 | recommended to use the name of your kernel module for this. | |
294 | </para> | |
295 | </listitem> | |
296 | <listitem> | |
297 | <para> | |
298 | <filename>version</filename>: A version string defined by your | |
299 | driver. This allows the user space part of your driver to deal | |
300 | with different versions of the kernel module. | |
301 | </para> | |
302 | </listitem> | |
303 | <listitem> | |
304 | <para> | |
305 | <filename>event</filename>: The total number of interrupts | |
306 | handled by the driver since the last time the device node was | |
307 | read. | |
308 | </para> | |
309 | </listitem> | |
310 | </itemizedlist> | |
311 | <para> | |
312 | These attributes appear under the | |
313 | <filename>/sys/class/uio/uioX</filename> directory. Please | |
314 | note that this directory might be a symlink, and not a real | |
315 | directory. Any userspace code that accesses it must be able | |
316 | to handle this. | |
317 | </para> | |
318 | <para> | |
319 | Each UIO device can make one or more memory regions available for | |
320 | memory mapping. This is necessary because some industrial I/O cards | |
321 | require access to more than one PCI memory region in a driver. | |
322 | </para> | |
323 | <para> | |
324 | Each mapping has its own directory in sysfs, the first mapping | |
325 | appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. | |
326 | Subsequent mappings create directories <filename>map1/</filename>, | |
327 | <filename>map2/</filename>, and so on. These directories will only | |
328 | appear if the size of the mapping is not 0. | |
329 | </para> | |
330 | <para> | |
82057791 HK |
331 | Each <filename>mapX/</filename> directory contains four read-only files |
332 | that show attributes of the memory: | |
e3e0a28b HK |
333 | </para> |
334 | <itemizedlist> | |
82057791 HK |
335 | <listitem> |
336 | <para> | |
337 | <filename>name</filename>: A string identifier for this mapping. This | |
338 | is optional, the string can be empty. Drivers can set this to make it | |
339 | easier for userspace to find the correct mapping. | |
340 | </para> | |
341 | </listitem> | |
e3e0a28b HK |
342 | <listitem> |
343 | <para> | |
344 | <filename>addr</filename>: The address of memory that can be mapped. | |
345 | </para> | |
346 | </listitem> | |
347 | <listitem> | |
348 | <para> | |
349 | <filename>size</filename>: The size, in bytes, of the memory | |
350 | pointed to by addr. | |
351 | </para> | |
352 | </listitem> | |
6a1b6996 HK |
353 | <listitem> |
354 | <para> | |
355 | <filename>offset</filename>: The offset, in bytes, that has to be | |
356 | added to the pointer returned by <function>mmap()</function> to get | |
357 | to the actual device memory. This is important if the device's memory | |
358 | is not page aligned. Remember that pointers returned by | |
359 | <function>mmap()</function> are always page aligned, so it is good | |
360 | style to always add this offset. | |
361 | </para> | |
362 | </listitem> | |
e3e0a28b HK |
363 | </itemizedlist> |
364 | ||
365 | <para> | |
366 | From userspace, the different mappings are distinguished by adjusting | |
367 | the <varname>offset</varname> parameter of the | |
368 | <function>mmap()</function> call. To map the memory of mapping N, you | |
369 | have to use N times the page size as your offset: | |
370 | </para> | |
371 | <programlisting format="linespecific"> | |
372 | offset = N * getpagesize(); | |
373 | </programlisting> | |
374 | ||
a2ab3d30 HK |
375 | <para> |
376 | Sometimes there is hardware with memory-like regions that can not be | |
377 | mapped with the technique described here, but there are still ways to | |
378 | access them from userspace. The most common example are x86 ioports. | |
379 | On x86 systems, userspace can access these ioports using | |
380 | <function>ioperm()</function>, <function>iopl()</function>, | |
381 | <function>inb()</function>, <function>outb()</function>, and similar | |
382 | functions. | |
383 | </para> | |
384 | <para> | |
385 | Since these ioport regions can not be mapped, they will not appear under | |
386 | <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory | |
387 | described above. Without information about the port regions a hardware | |
388 | has to offer, it becomes difficult for the userspace part of the | |
389 | driver to find out which ports belong to which UIO device. | |
390 | </para> | |
391 | <para> | |
392 | To address this situation, the new directory | |
393 | <filename>/sys/class/uio/uioX/portio/</filename> was added. It only | |
394 | exists if the driver wants to pass information about one or more port | |
395 | regions to userspace. If that is the case, subdirectories named | |
396 | <filename>port0</filename>, <filename>port1</filename>, and so on, | |
397 | will appear underneath | |
398 | <filename>/sys/class/uio/uioX/portio/</filename>. | |
399 | </para> | |
400 | <para> | |
82057791 HK |
401 | Each <filename>portX/</filename> directory contains four read-only |
402 | files that show name, start, size, and type of the port region: | |
a2ab3d30 HK |
403 | </para> |
404 | <itemizedlist> | |
82057791 HK |
405 | <listitem> |
406 | <para> | |
407 | <filename>name</filename>: A string identifier for this port region. | |
408 | The string is optional and can be empty. Drivers can set it to make it | |
409 | easier for userspace to find a certain port region. | |
410 | </para> | |
411 | </listitem> | |
a2ab3d30 HK |
412 | <listitem> |
413 | <para> | |
414 | <filename>start</filename>: The first port of this region. | |
415 | </para> | |
416 | </listitem> | |
417 | <listitem> | |
418 | <para> | |
419 | <filename>size</filename>: The number of ports in this region. | |
420 | </para> | |
421 | </listitem> | |
422 | <listitem> | |
423 | <para> | |
424 | <filename>porttype</filename>: A string describing the type of port. | |
425 | </para> | |
426 | </listitem> | |
427 | </itemizedlist> | |
428 | ||
429 | ||
e3e0a28b HK |
430 | </sect1> |
431 | </chapter> | |
432 | ||
e3e0a28b HK |
433 | <chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> |
434 | <?dbhtml filename="custom_kernel_module.html"?> | |
435 | <title>Writing your own kernel module</title> | |
436 | <para> | |
ed423c24 | 437 | Please have a look at <filename>uio_cif.c</filename> as an |
e3e0a28b HK |
438 | example. The following paragraphs explain the different |
439 | sections of this file. | |
440 | </para> | |
441 | ||
442 | <sect1 id="uio_info"> | |
443 | <title>struct uio_info</title> | |
444 | <para> | |
445 | This structure tells the framework the details of your driver, | |
446 | Some of the members are required, others are optional. | |
447 | </para> | |
448 | ||
449 | <itemizedlist> | |
450 | <listitem><para> | |
b8ac9fc0 | 451 | <varname>const char *name</varname>: Required. The name of your driver as |
e3e0a28b HK |
452 | it will appear in sysfs. I recommend using the name of your module for this. |
453 | </para></listitem> | |
454 | ||
455 | <listitem><para> | |
b8ac9fc0 | 456 | <varname>const char *version</varname>: Required. This string appears in |
e3e0a28b HK |
457 | <filename>/sys/class/uio/uioX/version</filename>. |
458 | </para></listitem> | |
459 | ||
460 | <listitem><para> | |
461 | <varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you | |
462 | have memory that can be mapped with <function>mmap()</function>. For each | |
463 | mapping you need to fill one of the <varname>uio_mem</varname> structures. | |
464 | See the description below for details. | |
465 | </para></listitem> | |
466 | ||
a2ab3d30 HK |
467 | <listitem><para> |
468 | <varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required | |
469 | if you want to pass information about ioports to userspace. For each port | |
470 | region you need to fill one of the <varname>uio_port</varname> structures. | |
471 | See the description below for details. | |
472 | </para></listitem> | |
473 | ||
e3e0a28b HK |
474 | <listitem><para> |
475 | <varname>long irq</varname>: Required. If your hardware generates an | |
476 | interrupt, it's your modules task to determine the irq number during | |
477 | initialization. If you don't have a hardware generated interrupt but | |
478 | want to trigger the interrupt handler in some other way, set | |
ed423c24 HK |
479 | <varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. |
480 | If you had no interrupt at all, you could set | |
e3e0a28b HK |
481 | <varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this |
482 | rarely makes sense. | |
483 | </para></listitem> | |
484 | ||
485 | <listitem><para> | |
486 | <varname>unsigned long irq_flags</varname>: Required if you've set | |
487 | <varname>irq</varname> to a hardware interrupt number. The flags given | |
488 | here will be used in the call to <function>request_irq()</function>. | |
489 | </para></listitem> | |
490 | ||
491 | <listitem><para> | |
492 | <varname>int (*mmap)(struct uio_info *info, struct vm_area_struct | |
493 | *vma)</varname>: Optional. If you need a special | |
494 | <function>mmap()</function> function, you can set it here. If this | |
495 | pointer is not NULL, your <function>mmap()</function> will be called | |
496 | instead of the built-in one. | |
497 | </para></listitem> | |
498 | ||
499 | <listitem><para> | |
500 | <varname>int (*open)(struct uio_info *info, struct inode *inode) | |
501 | </varname>: Optional. You might want to have your own | |
502 | <function>open()</function>, e.g. to enable interrupts only when your | |
503 | device is actually used. | |
504 | </para></listitem> | |
505 | ||
506 | <listitem><para> | |
507 | <varname>int (*release)(struct uio_info *info, struct inode *inode) | |
508 | </varname>: Optional. If you define your own | |
509 | <function>open()</function>, you will probably also want a custom | |
510 | <function>release()</function> function. | |
511 | </para></listitem> | |
328a14e7 HK |
512 | |
513 | <listitem><para> | |
514 | <varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on) | |
515 | </varname>: Optional. If you need to be able to enable or disable | |
516 | interrupts from userspace by writing to <filename>/dev/uioX</filename>, | |
517 | you can implement this function. The parameter <varname>irq_on</varname> | |
518 | will be 0 to disable interrupts and 1 to enable them. | |
519 | </para></listitem> | |
e3e0a28b HK |
520 | </itemizedlist> |
521 | ||
522 | <para> | |
523 | Usually, your device will have one or more memory regions that can be mapped | |
524 | to user space. For each region, you have to set up a | |
525 | <varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. | |
526 | Here's a description of the fields of <varname>struct uio_mem</varname>: | |
527 | </para> | |
528 | ||
529 | <itemizedlist> | |
b2433d86 GT |
530 | <listitem><para> |
531 | <varname>const char *name</varname>: Optional. Set this to help identify | |
532 | the memory region, it will show up in the corresponding sysfs node. | |
533 | </para></listitem> | |
534 | ||
e3e0a28b HK |
535 | <listitem><para> |
536 | <varname>int memtype</varname>: Required if the mapping is used. Set this to | |
537 | <varname>UIO_MEM_PHYS</varname> if you you have physical memory on your | |
538 | card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical | |
539 | memory (e.g. allocated with <function>kmalloc()</function>). There's also | |
540 | <varname>UIO_MEM_VIRTUAL</varname> for virtual memory. | |
541 | </para></listitem> | |
542 | ||
543 | <listitem><para> | |
27a90700 | 544 | <varname>phys_addr_t addr</varname>: Required if the mapping is used. |
e3e0a28b HK |
545 | Fill in the address of your memory block. This address is the one that |
546 | appears in sysfs. | |
547 | </para></listitem> | |
548 | ||
549 | <listitem><para> | |
e0f1147c | 550 | <varname>resource_size_t size</varname>: Fill in the size of the |
e3e0a28b HK |
551 | memory block that <varname>addr</varname> points to. If <varname>size</varname> |
552 | is zero, the mapping is considered unused. Note that you | |
553 | <emphasis>must</emphasis> initialize <varname>size</varname> with zero for | |
554 | all unused mappings. | |
555 | </para></listitem> | |
556 | ||
557 | <listitem><para> | |
558 | <varname>void *internal_addr</varname>: If you have to access this memory | |
559 | region from within your kernel module, you will want to map it internally by | |
560 | using something like <function>ioremap()</function>. Addresses | |
561 | returned by this function cannot be mapped to user space, so you must not | |
562 | store it in <varname>addr</varname>. Use <varname>internal_addr</varname> | |
563 | instead to remember such an address. | |
564 | </para></listitem> | |
565 | </itemizedlist> | |
566 | ||
567 | <para> | |
b2433d86 | 568 | Please do not touch the <varname>map</varname> element of |
e3e0a28b HK |
569 | <varname>struct uio_mem</varname>! It is used by the UIO framework |
570 | to set up sysfs files for this mapping. Simply leave it alone. | |
571 | </para> | |
a2ab3d30 HK |
572 | |
573 | <para> | |
574 | Sometimes, your device can have one or more port regions which can not be | |
575 | mapped to userspace. But if there are other possibilities for userspace to | |
576 | access these ports, it makes sense to make information about the ports | |
577 | available in sysfs. For each region, you have to set up a | |
578 | <varname>struct uio_port</varname> in the <varname>port[]</varname> array. | |
579 | Here's a description of the fields of <varname>struct uio_port</varname>: | |
580 | </para> | |
581 | ||
582 | <itemizedlist> | |
583 | <listitem><para> | |
584 | <varname>char *porttype</varname>: Required. Set this to one of the predefined | |
585 | constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 | |
586 | architectures. | |
587 | </para></listitem> | |
588 | ||
589 | <listitem><para> | |
590 | <varname>unsigned long start</varname>: Required if the port region is used. | |
591 | Fill in the number of the first port of this region. | |
592 | </para></listitem> | |
593 | ||
594 | <listitem><para> | |
595 | <varname>unsigned long size</varname>: Fill in the number of ports in this | |
596 | region. If <varname>size</varname> is zero, the region is considered unused. | |
597 | Note that you <emphasis>must</emphasis> initialize <varname>size</varname> | |
598 | with zero for all unused regions. | |
599 | </para></listitem> | |
600 | </itemizedlist> | |
601 | ||
602 | <para> | |
603 | Please do not touch the <varname>portio</varname> element of | |
604 | <varname>struct uio_port</varname>! It is used internally by the UIO | |
605 | framework to set up sysfs files for this region. Simply leave it alone. | |
606 | </para> | |
607 | ||
e3e0a28b HK |
608 | </sect1> |
609 | ||
610 | <sect1 id="adding_irq_handler"> | |
611 | <title>Adding an interrupt handler</title> | |
612 | <para> | |
613 | What you need to do in your interrupt handler depends on your | |
614 | hardware and on how you want to handle it. You should try to | |
615 | keep the amount of code in your kernel interrupt handler low. | |
616 | If your hardware requires no action that you | |
617 | <emphasis>have</emphasis> to perform after each interrupt, | |
618 | then your handler can be empty.</para> <para>If, on the other | |
619 | hand, your hardware <emphasis>needs</emphasis> some action to | |
620 | be performed after each interrupt, then you | |
621 | <emphasis>must</emphasis> do it in your kernel module. Note | |
622 | that you cannot rely on the userspace part of your driver. Your | |
623 | userspace program can terminate at any time, possibly leaving | |
624 | your hardware in a state where proper interrupt handling is | |
625 | still required. | |
626 | </para> | |
627 | ||
628 | <para> | |
629 | There might also be applications where you want to read data | |
630 | from your hardware at each interrupt and buffer it in a piece | |
631 | of kernel memory you've allocated for that purpose. With this | |
632 | technique you could avoid loss of data if your userspace | |
633 | program misses an interrupt. | |
634 | </para> | |
635 | ||
636 | <para> | |
637 | A note on shared interrupts: Your driver should support | |
638 | interrupt sharing whenever this is possible. It is possible if | |
639 | and only if your driver can detect whether your hardware has | |
640 | triggered the interrupt or not. This is usually done by looking | |
641 | at an interrupt status register. If your driver sees that the | |
642 | IRQ bit is actually set, it will perform its actions, and the | |
643 | handler returns IRQ_HANDLED. If the driver detects that it was | |
644 | not your hardware that caused the interrupt, it will do nothing | |
645 | and return IRQ_NONE, allowing the kernel to call the next | |
646 | possible interrupt handler. | |
647 | </para> | |
648 | ||
649 | <para> | |
650 | If you decide not to support shared interrupts, your card | |
651 | won't work in computers with no free interrupts. As this | |
652 | frequently happens on the PC platform, you can save yourself a | |
653 | lot of trouble by supporting interrupt sharing. | |
654 | </para> | |
655 | </sect1> | |
656 | ||
6a1b6996 HK |
657 | <sect1 id="using_uio_pdrv"> |
658 | <title>Using uio_pdrv for platform devices</title> | |
659 | <para> | |
660 | In many cases, UIO drivers for platform devices can be handled in a | |
661 | generic way. In the same place where you define your | |
662 | <varname>struct platform_device</varname>, you simply also implement | |
663 | your interrupt handler and fill your | |
664 | <varname>struct uio_info</varname>. A pointer to this | |
665 | <varname>struct uio_info</varname> is then used as | |
666 | <varname>platform_data</varname> for your platform device. | |
667 | </para> | |
668 | <para> | |
669 | You also need to set up an array of <varname>struct resource</varname> | |
670 | containing addresses and sizes of your memory mappings. This | |
671 | information is passed to the driver using the | |
672 | <varname>.resource</varname> and <varname>.num_resources</varname> | |
673 | elements of <varname>struct platform_device</varname>. | |
674 | </para> | |
675 | <para> | |
676 | You now have to set the <varname>.name</varname> element of | |
677 | <varname>struct platform_device</varname> to | |
678 | <varname>"uio_pdrv"</varname> to use the generic UIO platform device | |
679 | driver. This driver will fill the <varname>mem[]</varname> array | |
680 | according to the resources given, and register the device. | |
681 | </para> | |
682 | <para> | |
683 | The advantage of this approach is that you only have to edit a file | |
684 | you need to edit anyway. You do not have to create an extra driver. | |
685 | </para> | |
686 | </sect1> | |
687 | ||
688 | <sect1 id="using_uio_pdrv_genirq"> | |
689 | <title>Using uio_pdrv_genirq for platform devices</title> | |
690 | <para> | |
691 | Especially in embedded devices, you frequently find chips where the | |
692 | irq pin is tied to its own dedicated interrupt line. In such cases, | |
693 | where you can be really sure the interrupt is not shared, we can take | |
694 | the concept of <varname>uio_pdrv</varname> one step further and use a | |
695 | generic interrupt handler. That's what | |
696 | <varname>uio_pdrv_genirq</varname> does. | |
697 | </para> | |
698 | <para> | |
699 | The setup for this driver is the same as described above for | |
700 | <varname>uio_pdrv</varname>, except that you do not implement an | |
701 | interrupt handler. The <varname>.handler</varname> element of | |
702 | <varname>struct uio_info</varname> must remain | |
703 | <varname>NULL</varname>. The <varname>.irq_flags</varname> element | |
704 | must not contain <varname>IRQF_SHARED</varname>. | |
705 | </para> | |
706 | <para> | |
707 | You will set the <varname>.name</varname> element of | |
708 | <varname>struct platform_device</varname> to | |
709 | <varname>"uio_pdrv_genirq"</varname> to use this driver. | |
710 | </para> | |
711 | <para> | |
712 | The generic interrupt handler of <varname>uio_pdrv_genirq</varname> | |
713 | will simply disable the interrupt line using | |
714 | <function>disable_irq_nosync()</function>. After doing its work, | |
715 | userspace can reenable the interrupt by writing 0x00000001 to the UIO | |
716 | device file. The driver already implements an | |
717 | <function>irq_control()</function> to make this possible, you must not | |
718 | implement your own. | |
719 | </para> | |
720 | <para> | |
721 | Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of | |
722 | interrupt handler code. You also do not need to know anything about | |
723 | the chip's internal registers to create the kernel part of the driver. | |
724 | All you need to know is the irq number of the pin the chip is | |
725 | connected to. | |
726 | </para> | |
727 | </sect1> | |
728 | ||
9e4129bf | 729 | <sect1 id="using-uio_dmem_genirq"> |
b533a830 DHG |
730 | <title>Using uio_dmem_genirq for platform devices</title> |
731 | <para> | |
732 | In addition to statically allocated memory ranges, they may also be | |
733 | a desire to use dynamically allocated regions in a user space driver. | |
734 | In particular, being able to access memory made available through the | |
735 | dma-mapping API, may be particularly useful. The | |
736 | <varname>uio_dmem_genirq</varname> driver provides a way to accomplish | |
737 | this. | |
738 | </para> | |
739 | <para> | |
740 | This driver is used in a similar manner to the | |
741 | <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt | |
742 | configuration and handling. | |
743 | </para> | |
744 | <para> | |
745 | Set the <varname>.name</varname> element of | |
746 | <varname>struct platform_device</varname> to | |
747 | <varname>"uio_dmem_genirq"</varname> to use this driver. | |
748 | </para> | |
749 | <para> | |
750 | When using this driver, fill in the <varname>.platform_data</varname> | |
751 | element of <varname>struct platform_device</varname>, which is of type | |
752 | <varname>struct uio_dmem_genirq_pdata</varname> and which contains the | |
753 | following elements: | |
754 | </para> | |
755 | <itemizedlist> | |
9e4129bf | 756 | <listitem><para><varname>struct uio_info uioinfo</varname>: The same |
b533a830 | 757 | structure used as the <varname>uio_pdrv_genirq</varname> platform |
9e4129bf SD |
758 | data</para></listitem> |
759 | <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>: | |
b533a830 DHG |
760 | Pointer to list of sizes of dynamic memory regions to be mapped into |
761 | user space. | |
9e4129bf SD |
762 | </para></listitem> |
763 | <listitem><para><varname>unsigned int num_dynamic_regions</varname>: | |
b533a830 | 764 | Number of elements in <varname>dynamic_region_sizes</varname> array. |
9e4129bf | 765 | </para></listitem> |
b533a830 DHG |
766 | </itemizedlist> |
767 | <para> | |
768 | The dynamic regions defined in the platform data will be appended to | |
769 | the <varname> mem[] </varname> array after the platform device | |
770 | resources, which implies that the total number of static and dynamic | |
771 | memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. | |
772 | </para> | |
773 | <para> | |
774 | The dynamic memory regions will be allocated when the UIO device file, | |
775 | <varname>/dev/uioX</varname> is opened. | |
0ba4f6e4 | 776 | Similar to static memory resources, the memory region information for |
b533a830 DHG |
777 | dynamic regions is then visible via sysfs at |
778 | <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. | |
0ba4f6e4 | 779 | The dynamic memory regions will be freed when the UIO device file is |
b533a830 | 780 | closed. When no processes are holding the device file open, the address |
87c4d1a7 | 781 | returned to userspace is ~0. |
b533a830 DHG |
782 | </para> |
783 | </sect1> | |
784 | ||
e3e0a28b HK |
785 | </chapter> |
786 | ||
787 | <chapter id="userspace_driver" xreflabel="Writing a driver in user space"> | |
788 | <?dbhtml filename="userspace_driver.html"?> | |
789 | <title>Writing a driver in userspace</title> | |
790 | <para> | |
791 | Once you have a working kernel module for your hardware, you can | |
792 | write the userspace part of your driver. You don't need any special | |
793 | libraries, your driver can be written in any reasonable language, | |
794 | you can use floating point numbers and so on. In short, you can | |
795 | use all the tools and libraries you'd normally use for writing a | |
796 | userspace application. | |
797 | </para> | |
798 | ||
799 | <sect1 id="getting_uio_information"> | |
800 | <title>Getting information about your UIO device</title> | |
801 | <para> | |
802 | Information about all UIO devices is available in sysfs. The | |
803 | first thing you should do in your driver is check | |
804 | <varname>name</varname> and <varname>version</varname> to | |
805 | make sure your talking to the right device and that its kernel | |
806 | driver has the version you expect. | |
807 | </para> | |
808 | <para> | |
809 | You should also make sure that the memory mapping you need | |
810 | exists and has the size you expect. | |
811 | </para> | |
812 | <para> | |
813 | There is a tool called <varname>lsuio</varname> that lists | |
814 | UIO devices and their attributes. It is available here: | |
815 | </para> | |
816 | <para> | |
817 | <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> | |
818 | http://www.osadl.org/projects/downloads/UIO/user/</ulink> | |
819 | </para> | |
820 | <para> | |
821 | With <varname>lsuio</varname> you can quickly check if your | |
822 | kernel module is loaded and which attributes it exports. | |
823 | Have a look at the manpage for details. | |
824 | </para> | |
825 | <para> | |
826 | The source code of <varname>lsuio</varname> can serve as an | |
827 | example for getting information about an UIO device. | |
828 | The file <filename>uio_helper.c</filename> contains a lot of | |
829 | functions you could use in your userspace driver code. | |
830 | </para> | |
831 | </sect1> | |
832 | ||
833 | <sect1 id="mmap_device_memory"> | |
834 | <title>mmap() device memory</title> | |
835 | <para> | |
836 | After you made sure you've got the right device with the | |
837 | memory mappings you need, all you have to do is to call | |
838 | <function>mmap()</function> to map the device's memory | |
839 | to userspace. | |
840 | </para> | |
841 | <para> | |
842 | The parameter <varname>offset</varname> of the | |
843 | <function>mmap()</function> call has a special meaning | |
844 | for UIO devices: It is used to select which mapping of | |
845 | your device you want to map. To map the memory of | |
846 | mapping N, you have to use N times the page size as | |
847 | your offset: | |
848 | </para> | |
849 | <programlisting format="linespecific"> | |
850 | offset = N * getpagesize(); | |
851 | </programlisting> | |
852 | <para> | |
853 | N starts from zero, so if you've got only one memory | |
854 | range to map, set <varname>offset = 0</varname>. | |
855 | A drawback of this technique is that memory is always | |
856 | mapped beginning with its start address. | |
857 | </para> | |
858 | </sect1> | |
859 | ||
860 | <sect1 id="wait_for_interrupts"> | |
861 | <title>Waiting for interrupts</title> | |
862 | <para> | |
863 | After you successfully mapped your devices memory, you | |
864 | can access it like an ordinary array. Usually, you will | |
865 | perform some initialization. After that, your hardware | |
866 | starts working and will generate an interrupt as soon | |
867 | as it's finished, has some data available, or needs your | |
25985edc | 868 | attention because an error occurred. |
e3e0a28b HK |
869 | </para> |
870 | <para> | |
871 | <filename>/dev/uioX</filename> is a read-only file. A | |
872 | <function>read()</function> will always block until an | |
873 | interrupt occurs. There is only one legal value for the | |
874 | <varname>count</varname> parameter of | |
875 | <function>read()</function>, and that is the size of a | |
876 | signed 32 bit integer (4). Any other value for | |
877 | <varname>count</varname> causes <function>read()</function> | |
878 | to fail. The signed 32 bit integer read is the interrupt | |
879 | count of your device. If the value is one more than the value | |
880 | you read the last time, everything is OK. If the difference | |
881 | is greater than one, you missed interrupts. | |
882 | </para> | |
883 | <para> | |
884 | You can also use <function>select()</function> on | |
885 | <filename>/dev/uioX</filename>. | |
886 | </para> | |
887 | </sect1> | |
888 | ||
889 | </chapter> | |
890 | ||
ccb86a69 MT |
891 | <chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> |
892 | <?dbhtml filename="uio_pci_generic.html"?> | |
893 | <title>Generic PCI UIO driver</title> | |
894 | <para> | |
895 | The generic driver is a kernel module named uio_pci_generic. | |
896 | It can work with any device compliant to PCI 2.3 (circa 2002) and | |
897 | any compliant PCI Express device. Using this, you only need to | |
898 | write the userspace driver, removing the need to write | |
899 | a hardware-specific kernel module. | |
900 | </para> | |
901 | ||
902 | <sect1 id="uio_pci_generic_binding"> | |
903 | <title>Making the driver recognize the device</title> | |
904 | <para> | |
905 | Since the driver does not declare any device ids, it will not get loaded | |
906 | automatically and will not automatically bind to any devices, you must load it | |
907 | and allocate id to the driver yourself. For example: | |
908 | <programlisting> | |
909 | modprobe uio_pci_generic | |
910 | echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id | |
911 | </programlisting> | |
912 | </para> | |
913 | <para> | |
914 | If there already is a hardware specific kernel driver for your device, the | |
915 | generic driver still won't bind to it, in this case if you want to use the | |
916 | generic driver (why would you?) you'll have to manually unbind the hardware | |
917 | specific driver and bind the generic driver, like this: | |
918 | <programlisting> | |
919 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind | |
920 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind | |
921 | </programlisting> | |
922 | </para> | |
923 | <para> | |
924 | You can verify that the device has been bound to the driver | |
925 | by looking for it in sysfs, for example like the following: | |
926 | <programlisting> | |
927 | ls -l /sys/bus/pci/devices/0000:00:19.0/driver | |
928 | </programlisting> | |
929 | Which if successful should print | |
930 | <programlisting> | |
931 | .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic | |
932 | </programlisting> | |
933 | Note that the generic driver will not bind to old PCI 2.2 devices. | |
934 | If binding the device failed, run the following command: | |
935 | <programlisting> | |
936 | dmesg | |
937 | </programlisting> | |
938 | and look in the output for failure reasons | |
939 | </para> | |
940 | </sect1> | |
941 | ||
942 | <sect1 id="uio_pci_generic_internals"> | |
943 | <title>Things to know about uio_pci_generic</title> | |
944 | <para> | |
945 | Interrupts are handled using the Interrupt Disable bit in the PCI command | |
946 | register and Interrupt Status bit in the PCI status register. All devices | |
947 | compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should | |
948 | support these bits. uio_pci_generic detects this support, and won't bind to | |
949 | devices which do not support the Interrupt Disable Bit in the command register. | |
950 | </para> | |
951 | <para> | |
952 | On each interrupt, uio_pci_generic sets the Interrupt Disable bit. | |
953 | This prevents the device from generating further interrupts | |
954 | until the bit is cleared. The userspace driver should clear this | |
955 | bit before blocking and waiting for more interrupts. | |
956 | </para> | |
957 | </sect1> | |
958 | <sect1 id="uio_pci_generic_userspace"> | |
959 | <title>Writing userspace driver using uio_pci_generic</title> | |
960 | <para> | |
961 | Userspace driver can use pci sysfs interface, or the | |
962 | libpci libray that wraps it, to talk to the device and to | |
963 | re-enable interrupts by writing to the command register. | |
964 | </para> | |
965 | </sect1> | |
966 | <sect1 id="uio_pci_generic_example"> | |
967 | <title>Example code using uio_pci_generic</title> | |
968 | <para> | |
969 | Here is some sample userspace driver code using uio_pci_generic: | |
970 | <programlisting> | |
971 | #include <stdlib.h> | |
972 | #include <stdio.h> | |
973 | #include <unistd.h> | |
974 | #include <sys/types.h> | |
975 | #include <sys/stat.h> | |
976 | #include <fcntl.h> | |
977 | #include <errno.h> | |
978 | ||
979 | int main() | |
980 | { | |
981 | int uiofd; | |
982 | int configfd; | |
983 | int err; | |
984 | int i; | |
985 | unsigned icount; | |
986 | unsigned char command_high; | |
987 | ||
988 | uiofd = open("/dev/uio0", O_RDONLY); | |
989 | if (uiofd < 0) { | |
990 | perror("uio open:"); | |
991 | return errno; | |
992 | } | |
993 | configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); | |
93ce83b6 | 994 | if (configfd < 0) { |
ccb86a69 MT |
995 | perror("config open:"); |
996 | return errno; | |
997 | } | |
998 | ||
999 | /* Read and cache command value */ | |
1000 | err = pread(configfd, &command_high, 1, 5); | |
1001 | if (err != 1) { | |
1002 | perror("command config read:"); | |
1003 | return errno; | |
1004 | } | |
1005 | command_high &= ~0x4; | |
1006 | ||
1007 | for(i = 0;; ++i) { | |
1008 | /* Print out a message, for debugging. */ | |
1009 | if (i == 0) | |
1010 | fprintf(stderr, "Started uio test driver.\n"); | |
1011 | else | |
1012 | fprintf(stderr, "Interrupts: %d\n", icount); | |
1013 | ||
1014 | /****************************************/ | |
1015 | /* Here we got an interrupt from the | |
1016 | device. Do something to it. */ | |
1017 | /****************************************/ | |
1018 | ||
1019 | /* Re-enable interrupts. */ | |
1020 | err = pwrite(configfd, &command_high, 1, 5); | |
1021 | if (err != 1) { | |
1022 | perror("config write:"); | |
1023 | break; | |
1024 | } | |
1025 | ||
1026 | /* Wait for next interrupt. */ | |
1027 | err = read(uiofd, &icount, 4); | |
1028 | if (err != 4) { | |
1029 | perror("uio read:"); | |
1030 | break; | |
1031 | } | |
1032 | ||
1033 | } | |
1034 | return errno; | |
1035 | } | |
1036 | ||
1037 | </programlisting> | |
1038 | </para> | |
1039 | </sect1> | |
1040 | ||
1041 | </chapter> | |
1042 | ||
a164a8a6 SH |
1043 | <chapter id="uio_hv_generic" xreflabel="Using Generic driver for Hyper-V VMBUS"> |
1044 | <?dbhtml filename="uio_hv_generic.html"?> | |
1045 | <title>Generic Hyper-V UIO driver</title> | |
1046 | <para> | |
1047 | The generic driver is a kernel module named uio_hv_generic. | |
1048 | It supports devices on the Hyper-V VMBus similar to uio_pci_generic | |
1049 | on PCI bus. | |
1050 | </para> | |
1051 | ||
1052 | <sect1 id="uio_hv_generic_binding"> | |
1053 | <title>Making the driver recognize the device</title> | |
1054 | <para> | |
1055 | Since the driver does not declare any device GUID's, it will not get loaded | |
1056 | automatically and will not automatically bind to any devices, you must load it | |
1057 | and allocate id to the driver yourself. For example, to use the network device | |
1058 | GUID: | |
1059 | <programlisting> | |
1060 | modprobe uio_hv_generic | |
1061 | echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id | |
1062 | </programlisting> | |
1063 | </para> | |
1064 | <para> | |
1065 | If there already is a hardware specific kernel driver for the device, the | |
1066 | generic driver still won't bind to it, in this case if you want to use the | |
1067 | generic driver (why would you?) you'll have to manually unbind the hardware | |
1068 | specific driver and bind the generic driver, like this: | |
1069 | <programlisting> | |
1070 | echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind | |
1071 | echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind | |
1072 | </programlisting> | |
1073 | </para> | |
1074 | <para> | |
1075 | You can verify that the device has been bound to the driver | |
1076 | by looking for it in sysfs, for example like the following: | |
1077 | <programlisting> | |
1078 | ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver | |
1079 | </programlisting> | |
1080 | Which if successful should print | |
1081 | <programlisting> | |
1082 | .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic | |
1083 | </programlisting> | |
1084 | </para> | |
1085 | </sect1> | |
1086 | ||
1087 | <sect1 id="uio_hv_generic_internals"> | |
1088 | <title>Things to know about uio_hv_generic</title> | |
1089 | <para> | |
1090 | On each interrupt, uio_hv_generic sets the Interrupt Disable bit. | |
1091 | This prevents the device from generating further interrupts | |
1092 | until the bit is cleared. The userspace driver should clear this | |
1093 | bit before blocking and waiting for more interrupts. | |
1094 | </para> | |
1095 | </sect1> | |
1096 | </chapter> | |
1097 | ||
e3e0a28b HK |
1098 | <appendix id="app1"> |
1099 | <title>Further information</title> | |
1100 | <itemizedlist> | |
1101 | <listitem><para> | |
1102 | <ulink url="http://www.osadl.org"> | |
1103 | OSADL homepage.</ulink> | |
1104 | </para></listitem> | |
1105 | <listitem><para> | |
1106 | <ulink url="http://www.linutronix.de"> | |
1107 | Linutronix homepage.</ulink> | |
1108 | </para></listitem> | |
1109 | </itemizedlist> | |
1110 | </appendix> | |
1111 | ||
1112 | </book> |