Commit | Line | Data |
---|---|---|
cadf8106 AD |
1 | ======================= |
2 | The Userspace I/O HOWTO | |
3 | ======================= | |
4 | ||
5 | :Author: Hans-Jürgen Koch Linux developer, Linutronix | |
6 | :Date: 2006-12-11 | |
7 | ||
8 | About this document | |
9 | =================== | |
10 | ||
11 | Translations | |
12 | ------------ | |
13 | ||
14 | If you know of any translations for this document, or you are interested | |
15 | in translating it, please email me hjk@hansjkoch.de. | |
16 | ||
17 | Preface | |
18 | ------- | |
19 | ||
20 | For many types of devices, creating a Linux kernel driver is overkill. | |
21 | All that is really needed is some way to handle an interrupt and provide | |
22 | access to the memory space of the device. The logic of controlling the | |
23 | device does not necessarily have to be within the kernel, as the device | |
24 | does not need to take advantage of any of other resources that the | |
25 | kernel provides. One such common class of devices that are like this are | |
26 | for industrial I/O cards. | |
27 | ||
28 | To address this situation, the userspace I/O system (UIO) was designed. | |
29 | For typical industrial I/O cards, only a very small kernel module is | |
30 | needed. The main part of the driver will run in user space. This | |
31 | simplifies development and reduces the risk of serious bugs within a | |
32 | kernel module. | |
33 | ||
34 | Please note that UIO is not an universal driver interface. Devices that | |
35 | are already handled well by other kernel subsystems (like networking or | |
36 | serial or USB) are no candidates for an UIO driver. Hardware that is | |
37 | ideally suited for an UIO driver fulfills all of the following: | |
38 | ||
39 | - The device has memory that can be mapped. The device can be | |
40 | controlled completely by writing to this memory. | |
41 | ||
42 | - The device usually generates interrupts. | |
43 | ||
44 | - The device does not fit into one of the standard kernel subsystems. | |
45 | ||
46 | Acknowledgments | |
47 | --------------- | |
48 | ||
49 | I'd like to thank Thomas Gleixner and Benedikt Spranger of Linutronix, | |
50 | who have not only written most of the UIO code, but also helped greatly | |
51 | writing this HOWTO by giving me all kinds of background information. | |
52 | ||
53 | Feedback | |
54 | -------- | |
55 | ||
56 | Find something wrong with this document? (Or perhaps something right?) I | |
57 | would love to hear from you. Please email me at hjk@hansjkoch.de. | |
58 | ||
59 | About UIO | |
60 | ========= | |
61 | ||
62 | If you use UIO for your card's driver, here's what you get: | |
63 | ||
64 | - only one small kernel module to write and maintain. | |
65 | ||
66 | - develop the main part of your driver in user space, with all the | |
67 | tools and libraries you're used to. | |
68 | ||
69 | - bugs in your driver won't crash the kernel. | |
70 | ||
71 | - updates of your driver can take place without recompiling the kernel. | |
72 | ||
73 | How UIO works | |
74 | ------------- | |
75 | ||
76 | Each UIO device is accessed through a device file and several sysfs | |
77 | attribute files. The device file will be called ``/dev/uio0`` for the | |
78 | first device, and ``/dev/uio1``, ``/dev/uio2`` and so on for subsequent | |
79 | devices. | |
80 | ||
81 | ``/dev/uioX`` is used to access the address space of the card. Just use | |
82 | :c:func:`mmap()` to access registers or RAM locations of your card. | |
83 | ||
84 | Interrupts are handled by reading from ``/dev/uioX``. A blocking | |
85 | :c:func:`read()` from ``/dev/uioX`` will return as soon as an | |
86 | interrupt occurs. You can also use :c:func:`select()` on | |
87 | ``/dev/uioX`` to wait for an interrupt. The integer value read from | |
88 | ``/dev/uioX`` represents the total interrupt count. You can use this | |
89 | number to figure out if you missed some interrupts. | |
90 | ||
91 | For some hardware that has more than one interrupt source internally, | |
92 | but not separate IRQ mask and status registers, there might be | |
93 | situations where userspace cannot determine what the interrupt source | |
94 | was if the kernel handler disables them by writing to the chip's IRQ | |
95 | register. In such a case, the kernel has to disable the IRQ completely | |
96 | to leave the chip's register untouched. Now the userspace part can | |
97 | determine the cause of the interrupt, but it cannot re-enable | |
98 | interrupts. Another cornercase is chips where re-enabling interrupts is | |
99 | a read-modify-write operation to a combined IRQ status/acknowledge | |
100 | register. This would be racy if a new interrupt occurred simultaneously. | |
101 | ||
102 | To address these problems, UIO also implements a write() function. It is | |
103 | normally not used and can be ignored for hardware that has only a single | |
104 | interrupt source or has separate IRQ mask and status registers. If you | |
105 | need it, however, a write to ``/dev/uioX`` will call the | |
106 | :c:func:`irqcontrol()` function implemented by the driver. You have | |
107 | to write a 32-bit value that is usually either 0 or 1 to disable or | |
108 | enable interrupts. If a driver does not implement | |
109 | :c:func:`irqcontrol()`, :c:func:`write()` will return with | |
110 | ``-ENOSYS``. | |
111 | ||
112 | To handle interrupts properly, your custom kernel module can provide its | |
113 | own interrupt handler. It will automatically be called by the built-in | |
114 | handler. | |
115 | ||
116 | For cards that don't generate interrupts but need to be polled, there is | |
117 | the possibility to set up a timer that triggers the interrupt handler at | |
118 | configurable time intervals. This interrupt simulation is done by | |
119 | calling :c:func:`uio_event_notify()` from the timer's event | |
120 | handler. | |
121 | ||
122 | Each driver provides attributes that are used to read or write | |
123 | variables. These attributes are accessible through sysfs files. A custom | |
124 | kernel driver module can add its own attributes to the device owned by | |
125 | the uio driver, but not added to the UIO device itself at this time. | |
126 | This might change in the future if it would be found to be useful. | |
127 | ||
128 | The following standard attributes are provided by the UIO framework: | |
129 | ||
130 | - ``name``: The name of your device. It is recommended to use the name | |
131 | of your kernel module for this. | |
132 | ||
133 | - ``version``: A version string defined by your driver. This allows the | |
134 | user space part of your driver to deal with different versions of the | |
135 | kernel module. | |
136 | ||
137 | - ``event``: The total number of interrupts handled by the driver since | |
138 | the last time the device node was read. | |
139 | ||
140 | These attributes appear under the ``/sys/class/uio/uioX`` directory. | |
141 | Please note that this directory might be a symlink, and not a real | |
142 | directory. Any userspace code that accesses it must be able to handle | |
143 | this. | |
144 | ||
145 | Each UIO device can make one or more memory regions available for memory | |
146 | mapping. This is necessary because some industrial I/O cards require | |
147 | access to more than one PCI memory region in a driver. | |
148 | ||
149 | Each mapping has its own directory in sysfs, the first mapping appears | |
150 | as ``/sys/class/uio/uioX/maps/map0/``. Subsequent mappings create | |
151 | directories ``map1/``, ``map2/``, and so on. These directories will only | |
152 | appear if the size of the mapping is not 0. | |
153 | ||
154 | Each ``mapX/`` directory contains four read-only files that show | |
155 | attributes of the memory: | |
156 | ||
157 | - ``name``: A string identifier for this mapping. This is optional, the | |
158 | string can be empty. Drivers can set this to make it easier for | |
159 | userspace to find the correct mapping. | |
160 | ||
161 | - ``addr``: The address of memory that can be mapped. | |
162 | ||
163 | - ``size``: The size, in bytes, of the memory pointed to by addr. | |
164 | ||
165 | - ``offset``: The offset, in bytes, that has to be added to the pointer | |
166 | returned by :c:func:`mmap()` to get to the actual device memory. | |
167 | This is important if the device's memory is not page aligned. | |
168 | Remember that pointers returned by :c:func:`mmap()` are always | |
169 | page aligned, so it is good style to always add this offset. | |
170 | ||
171 | From userspace, the different mappings are distinguished by adjusting | |
172 | the ``offset`` parameter of the :c:func:`mmap()` call. To map the | |
173 | memory of mapping N, you have to use N times the page size as your | |
174 | offset:: | |
175 | ||
176 | offset = N * getpagesize(); | |
177 | ||
178 | Sometimes there is hardware with memory-like regions that can not be | |
179 | mapped with the technique described here, but there are still ways to | |
180 | access them from userspace. The most common example are x86 ioports. On | |
181 | x86 systems, userspace can access these ioports using | |
182 | :c:func:`ioperm()`, :c:func:`iopl()`, :c:func:`inb()`, | |
183 | :c:func:`outb()`, and similar functions. | |
184 | ||
185 | Since these ioport regions can not be mapped, they will not appear under | |
186 | ``/sys/class/uio/uioX/maps/`` like the normal memory described above. | |
187 | Without information about the port regions a hardware has to offer, it | |
188 | becomes difficult for the userspace part of the driver to find out which | |
189 | ports belong to which UIO device. | |
190 | ||
191 | To address this situation, the new directory | |
192 | ``/sys/class/uio/uioX/portio/`` was added. It only exists if the driver | |
193 | wants to pass information about one or more port regions to userspace. | |
194 | If that is the case, subdirectories named ``port0``, ``port1``, and so | |
195 | on, will appear underneath ``/sys/class/uio/uioX/portio/``. | |
196 | ||
197 | Each ``portX/`` directory contains four read-only files that show name, | |
198 | start, size, and type of the port region: | |
199 | ||
200 | - ``name``: A string identifier for this port region. The string is | |
201 | optional and can be empty. Drivers can set it to make it easier for | |
202 | userspace to find a certain port region. | |
203 | ||
204 | - ``start``: The first port of this region. | |
205 | ||
206 | - ``size``: The number of ports in this region. | |
207 | ||
208 | - ``porttype``: A string describing the type of port. | |
209 | ||
210 | Writing your own kernel module | |
211 | ============================== | |
212 | ||
213 | Please have a look at ``uio_cif.c`` as an example. The following | |
214 | paragraphs explain the different sections of this file. | |
215 | ||
216 | struct uio_info | |
217 | --------------- | |
218 | ||
219 | This structure tells the framework the details of your driver, Some of | |
220 | the members are required, others are optional. | |
221 | ||
222 | - ``const char *name``: Required. The name of your driver as it will | |
223 | appear in sysfs. I recommend using the name of your module for this. | |
224 | ||
225 | - ``const char *version``: Required. This string appears in | |
226 | ``/sys/class/uio/uioX/version``. | |
227 | ||
228 | - ``struct uio_mem mem[ MAX_UIO_MAPS ]``: Required if you have memory | |
229 | that can be mapped with :c:func:`mmap()`. For each mapping you | |
230 | need to fill one of the ``uio_mem`` structures. See the description | |
231 | below for details. | |
232 | ||
233 | - ``struct uio_port port[ MAX_UIO_PORTS_REGIONS ]``: Required if you | |
234 | want to pass information about ioports to userspace. For each port | |
235 | region you need to fill one of the ``uio_port`` structures. See the | |
236 | description below for details. | |
237 | ||
238 | - ``long irq``: Required. If your hardware generates an interrupt, it's | |
239 | your modules task to determine the irq number during initialization. | |
240 | If you don't have a hardware generated interrupt but want to trigger | |
241 | the interrupt handler in some other way, set ``irq`` to | |
242 | ``UIO_IRQ_CUSTOM``. If you had no interrupt at all, you could set | |
243 | ``irq`` to ``UIO_IRQ_NONE``, though this rarely makes sense. | |
244 | ||
245 | - ``unsigned long irq_flags``: Required if you've set ``irq`` to a | |
246 | hardware interrupt number. The flags given here will be used in the | |
247 | call to :c:func:`request_irq()`. | |
248 | ||
249 | - ``int (*mmap)(struct uio_info *info, struct vm_area_struct *vma)``: | |
250 | Optional. If you need a special :c:func:`mmap()` | |
251 | function, you can set it here. If this pointer is not NULL, your | |
252 | :c:func:`mmap()` will be called instead of the built-in one. | |
253 | ||
254 | - ``int (*open)(struct uio_info *info, struct inode *inode)``: | |
255 | Optional. You might want to have your own :c:func:`open()`, | |
256 | e.g. to enable interrupts only when your device is actually used. | |
257 | ||
258 | - ``int (*release)(struct uio_info *info, struct inode *inode)``: | |
259 | Optional. If you define your own :c:func:`open()`, you will | |
260 | probably also want a custom :c:func:`release()` function. | |
261 | ||
262 | - ``int (*irqcontrol)(struct uio_info *info, s32 irq_on)``: | |
263 | Optional. If you need to be able to enable or disable interrupts | |
264 | from userspace by writing to ``/dev/uioX``, you can implement this | |
265 | function. The parameter ``irq_on`` will be 0 to disable interrupts | |
266 | and 1 to enable them. | |
267 | ||
268 | Usually, your device will have one or more memory regions that can be | |
269 | mapped to user space. For each region, you have to set up a | |
270 | ``struct uio_mem`` in the ``mem[]`` array. Here's a description of the | |
271 | fields of ``struct uio_mem``: | |
272 | ||
273 | - ``const char *name``: Optional. Set this to help identify the memory | |
274 | region, it will show up in the corresponding sysfs node. | |
275 | ||
276 | - ``int memtype``: Required if the mapping is used. Set this to | |
277 | ``UIO_MEM_PHYS`` if you you have physical memory on your card to be | |
278 | mapped. Use ``UIO_MEM_LOGICAL`` for logical memory (e.g. allocated | |
279 | with :c:func:`kmalloc()`). There's also ``UIO_MEM_VIRTUAL`` for | |
280 | virtual memory. | |
281 | ||
282 | - ``phys_addr_t addr``: Required if the mapping is used. Fill in the | |
283 | address of your memory block. This address is the one that appears in | |
284 | sysfs. | |
285 | ||
286 | - ``resource_size_t size``: Fill in the size of the memory block that | |
287 | ``addr`` points to. If ``size`` is zero, the mapping is considered | |
288 | unused. Note that you *must* initialize ``size`` with zero for all | |
289 | unused mappings. | |
290 | ||
291 | - ``void *internal_addr``: If you have to access this memory region | |
292 | from within your kernel module, you will want to map it internally by | |
293 | using something like :c:func:`ioremap()`. Addresses returned by | |
294 | this function cannot be mapped to user space, so you must not store | |
295 | it in ``addr``. Use ``internal_addr`` instead to remember such an | |
296 | address. | |
297 | ||
298 | Please do not touch the ``map`` element of ``struct uio_mem``! It is | |
299 | used by the UIO framework to set up sysfs files for this mapping. Simply | |
300 | leave it alone. | |
301 | ||
302 | Sometimes, your device can have one or more port regions which can not | |
303 | be mapped to userspace. But if there are other possibilities for | |
304 | userspace to access these ports, it makes sense to make information | |
305 | about the ports available in sysfs. For each region, you have to set up | |
306 | a ``struct uio_port`` in the ``port[]`` array. Here's a description of | |
307 | the fields of ``struct uio_port``: | |
308 | ||
309 | - ``char *porttype``: Required. Set this to one of the predefined | |
310 | constants. Use ``UIO_PORT_X86`` for the ioports found in x86 | |
311 | architectures. | |
312 | ||
313 | - ``unsigned long start``: Required if the port region is used. Fill in | |
314 | the number of the first port of this region. | |
315 | ||
316 | - ``unsigned long size``: Fill in the number of ports in this region. | |
317 | If ``size`` is zero, the region is considered unused. Note that you | |
318 | *must* initialize ``size`` with zero for all unused regions. | |
319 | ||
320 | Please do not touch the ``portio`` element of ``struct uio_port``! It is | |
321 | used internally by the UIO framework to set up sysfs files for this | |
322 | region. Simply leave it alone. | |
323 | ||
324 | Adding an interrupt handler | |
325 | --------------------------- | |
326 | ||
327 | What you need to do in your interrupt handler depends on your hardware | |
328 | and on how you want to handle it. You should try to keep the amount of | |
329 | code in your kernel interrupt handler low. If your hardware requires no | |
330 | action that you *have* to perform after each interrupt, then your | |
331 | handler can be empty. | |
332 | ||
333 | If, on the other hand, your hardware *needs* some action to be performed | |
334 | after each interrupt, then you *must* do it in your kernel module. Note | |
335 | that you cannot rely on the userspace part of your driver. Your | |
336 | userspace program can terminate at any time, possibly leaving your | |
337 | hardware in a state where proper interrupt handling is still required. | |
338 | ||
339 | There might also be applications where you want to read data from your | |
340 | hardware at each interrupt and buffer it in a piece of kernel memory | |
341 | you've allocated for that purpose. With this technique you could avoid | |
342 | loss of data if your userspace program misses an interrupt. | |
343 | ||
344 | A note on shared interrupts: Your driver should support interrupt | |
345 | sharing whenever this is possible. It is possible if and only if your | |
346 | driver can detect whether your hardware has triggered the interrupt or | |
347 | not. This is usually done by looking at an interrupt status register. If | |
348 | your driver sees that the IRQ bit is actually set, it will perform its | |
349 | actions, and the handler returns IRQ_HANDLED. If the driver detects | |
350 | that it was not your hardware that caused the interrupt, it will do | |
351 | nothing and return IRQ_NONE, allowing the kernel to call the next | |
352 | possible interrupt handler. | |
353 | ||
354 | If you decide not to support shared interrupts, your card won't work in | |
355 | computers with no free interrupts. As this frequently happens on the PC | |
356 | platform, you can save yourself a lot of trouble by supporting interrupt | |
357 | sharing. | |
358 | ||
359 | Using uio_pdrv for platform devices | |
360 | ----------------------------------- | |
361 | ||
362 | In many cases, UIO drivers for platform devices can be handled in a | |
363 | generic way. In the same place where you define your | |
364 | ``struct platform_device``, you simply also implement your interrupt | |
365 | handler and fill your ``struct uio_info``. A pointer to this | |
366 | ``struct uio_info`` is then used as ``platform_data`` for your platform | |
367 | device. | |
368 | ||
369 | You also need to set up an array of ``struct resource`` containing | |
370 | addresses and sizes of your memory mappings. This information is passed | |
371 | to the driver using the ``.resource`` and ``.num_resources`` elements of | |
372 | ``struct platform_device``. | |
373 | ||
374 | You now have to set the ``.name`` element of ``struct platform_device`` | |
375 | to ``"uio_pdrv"`` to use the generic UIO platform device driver. This | |
376 | driver will fill the ``mem[]`` array according to the resources given, | |
377 | and register the device. | |
378 | ||
379 | The advantage of this approach is that you only have to edit a file you | |
380 | need to edit anyway. You do not have to create an extra driver. | |
381 | ||
382 | Using uio_pdrv_genirq for platform devices | |
383 | ------------------------------------------ | |
384 | ||
385 | Especially in embedded devices, you frequently find chips where the irq | |
386 | pin is tied to its own dedicated interrupt line. In such cases, where | |
387 | you can be really sure the interrupt is not shared, we can take the | |
388 | concept of ``uio_pdrv`` one step further and use a generic interrupt | |
389 | handler. That's what ``uio_pdrv_genirq`` does. | |
390 | ||
391 | The setup for this driver is the same as described above for | |
392 | ``uio_pdrv``, except that you do not implement an interrupt handler. The | |
393 | ``.handler`` element of ``struct uio_info`` must remain ``NULL``. The | |
394 | ``.irq_flags`` element must not contain ``IRQF_SHARED``. | |
395 | ||
396 | You will set the ``.name`` element of ``struct platform_device`` to | |
397 | ``"uio_pdrv_genirq"`` to use this driver. | |
398 | ||
399 | The generic interrupt handler of ``uio_pdrv_genirq`` will simply disable | |
400 | the interrupt line using :c:func:`disable_irq_nosync()`. After | |
401 | doing its work, userspace can reenable the interrupt by writing | |
402 | 0x00000001 to the UIO device file. The driver already implements an | |
403 | :c:func:`irq_control()` to make this possible, you must not | |
404 | implement your own. | |
405 | ||
406 | Using ``uio_pdrv_genirq`` not only saves a few lines of interrupt | |
407 | handler code. You also do not need to know anything about the chip's | |
408 | internal registers to create the kernel part of the driver. All you need | |
409 | to know is the irq number of the pin the chip is connected to. | |
410 | ||
411 | Using uio_dmem_genirq for platform devices | |
412 | ------------------------------------------ | |
413 | ||
414 | In addition to statically allocated memory ranges, they may also be a | |
415 | desire to use dynamically allocated regions in a user space driver. In | |
416 | particular, being able to access memory made available through the | |
417 | dma-mapping API, may be particularly useful. The ``uio_dmem_genirq`` | |
418 | driver provides a way to accomplish this. | |
419 | ||
420 | This driver is used in a similar manner to the ``"uio_pdrv_genirq"`` | |
421 | driver with respect to interrupt configuration and handling. | |
422 | ||
423 | Set the ``.name`` element of ``struct platform_device`` to | |
424 | ``"uio_dmem_genirq"`` to use this driver. | |
425 | ||
426 | When using this driver, fill in the ``.platform_data`` element of | |
427 | ``struct platform_device``, which is of type | |
428 | ``struct uio_dmem_genirq_pdata`` and which contains the following | |
429 | elements: | |
430 | ||
431 | - ``struct uio_info uioinfo``: The same structure used as the | |
432 | ``uio_pdrv_genirq`` platform data | |
433 | ||
434 | - ``unsigned int *dynamic_region_sizes``: Pointer to list of sizes of | |
435 | dynamic memory regions to be mapped into user space. | |
436 | ||
437 | - ``unsigned int num_dynamic_regions``: Number of elements in | |
438 | ``dynamic_region_sizes`` array. | |
439 | ||
440 | The dynamic regions defined in the platform data will be appended to the | |
441 | `` mem[] `` array after the platform device resources, which implies | |
442 | that the total number of static and dynamic memory regions cannot exceed | |
443 | ``MAX_UIO_MAPS``. | |
444 | ||
445 | The dynamic memory regions will be allocated when the UIO device file, | |
446 | ``/dev/uioX`` is opened. Similar to static memory resources, the memory | |
447 | region information for dynamic regions is then visible via sysfs at | |
448 | ``/sys/class/uio/uioX/maps/mapY/*``. The dynamic memory regions will be | |
449 | freed when the UIO device file is closed. When no processes are holding | |
450 | the device file open, the address returned to userspace is ~0. | |
451 | ||
452 | Writing a driver in userspace | |
453 | ============================= | |
454 | ||
455 | Once you have a working kernel module for your hardware, you can write | |
456 | the userspace part of your driver. You don't need any special libraries, | |
457 | your driver can be written in any reasonable language, you can use | |
458 | floating point numbers and so on. In short, you can use all the tools | |
459 | and libraries you'd normally use for writing a userspace application. | |
460 | ||
461 | Getting information about your UIO device | |
462 | ----------------------------------------- | |
463 | ||
464 | Information about all UIO devices is available in sysfs. The first thing | |
465 | you should do in your driver is check ``name`` and ``version`` to make | |
466 | sure your talking to the right device and that its kernel driver has the | |
467 | version you expect. | |
468 | ||
469 | You should also make sure that the memory mapping you need exists and | |
470 | has the size you expect. | |
471 | ||
472 | There is a tool called ``lsuio`` that lists UIO devices and their | |
473 | attributes. It is available here: | |
474 | ||
475 | http://www.osadl.org/projects/downloads/UIO/user/ | |
476 | ||
477 | With ``lsuio`` you can quickly check if your kernel module is loaded and | |
478 | which attributes it exports. Have a look at the manpage for details. | |
479 | ||
480 | The source code of ``lsuio`` can serve as an example for getting | |
481 | information about an UIO device. The file ``uio_helper.c`` contains a | |
482 | lot of functions you could use in your userspace driver code. | |
483 | ||
484 | mmap() device memory | |
485 | -------------------- | |
486 | ||
487 | After you made sure you've got the right device with the memory mappings | |
488 | you need, all you have to do is to call :c:func:`mmap()` to map the | |
489 | device's memory to userspace. | |
490 | ||
491 | The parameter ``offset`` of the :c:func:`mmap()` call has a special | |
492 | meaning for UIO devices: It is used to select which mapping of your | |
493 | device you want to map. To map the memory of mapping N, you have to use | |
494 | N times the page size as your offset:: | |
495 | ||
496 | offset = N * getpagesize(); | |
497 | ||
498 | N starts from zero, so if you've got only one memory range to map, set | |
499 | ``offset = 0``. A drawback of this technique is that memory is always | |
500 | mapped beginning with its start address. | |
501 | ||
502 | Waiting for interrupts | |
503 | ---------------------- | |
504 | ||
505 | After you successfully mapped your devices memory, you can access it | |
506 | like an ordinary array. Usually, you will perform some initialization. | |
507 | After that, your hardware starts working and will generate an interrupt | |
508 | as soon as it's finished, has some data available, or needs your | |
509 | attention because an error occurred. | |
510 | ||
511 | ``/dev/uioX`` is a read-only file. A :c:func:`read()` will always | |
512 | block until an interrupt occurs. There is only one legal value for the | |
513 | ``count`` parameter of :c:func:`read()`, and that is the size of a | |
514 | signed 32 bit integer (4). Any other value for ``count`` causes | |
515 | :c:func:`read()` to fail. The signed 32 bit integer read is the | |
516 | interrupt count of your device. If the value is one more than the value | |
517 | you read the last time, everything is OK. If the difference is greater | |
518 | than one, you missed interrupts. | |
519 | ||
520 | You can also use :c:func:`select()` on ``/dev/uioX``. | |
521 | ||
522 | Generic PCI UIO driver | |
523 | ====================== | |
524 | ||
525 | The generic driver is a kernel module named uio_pci_generic. It can | |
526 | work with any device compliant to PCI 2.3 (circa 2002) and any compliant | |
527 | PCI Express device. Using this, you only need to write the userspace | |
528 | driver, removing the need to write a hardware-specific kernel module. | |
529 | ||
530 | Making the driver recognize the device | |
531 | -------------------------------------- | |
532 | ||
533 | Since the driver does not declare any device ids, it will not get loaded | |
534 | automatically and will not automatically bind to any devices, you must | |
535 | load it and allocate id to the driver yourself. For example:: | |
536 | ||
537 | modprobe uio_pci_generic | |
538 | echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id | |
539 | ||
540 | If there already is a hardware specific kernel driver for your device, | |
541 | the generic driver still won't bind to it, in this case if you want to | |
542 | use the generic driver (why would you?) you'll have to manually unbind | |
543 | the hardware specific driver and bind the generic driver, like this:: | |
544 | ||
545 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind | |
546 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind | |
547 | ||
548 | You can verify that the device has been bound to the driver by looking | |
549 | for it in sysfs, for example like the following:: | |
550 | ||
551 | ls -l /sys/bus/pci/devices/0000:00:19.0/driver | |
552 | ||
553 | Which if successful should print:: | |
554 | ||
555 | .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic | |
556 | ||
557 | Note that the generic driver will not bind to old PCI 2.2 devices. If | |
558 | binding the device failed, run the following command:: | |
559 | ||
560 | dmesg | |
561 | ||
562 | and look in the output for failure reasons. | |
563 | ||
564 | Things to know about uio_pci_generic | |
565 | ------------------------------------ | |
566 | ||
567 | Interrupts are handled using the Interrupt Disable bit in the PCI | |
568 | command register and Interrupt Status bit in the PCI status register. | |
569 | All devices compliant to PCI 2.3 (circa 2002) and all compliant PCI | |
570 | Express devices should support these bits. uio_pci_generic detects | |
571 | this support, and won't bind to devices which do not support the | |
572 | Interrupt Disable Bit in the command register. | |
573 | ||
574 | On each interrupt, uio_pci_generic sets the Interrupt Disable bit. | |
575 | This prevents the device from generating further interrupts until the | |
576 | bit is cleared. The userspace driver should clear this bit before | |
577 | blocking and waiting for more interrupts. | |
578 | ||
579 | Writing userspace driver using uio_pci_generic | |
580 | ------------------------------------------------ | |
581 | ||
582 | Userspace driver can use pci sysfs interface, or the libpci library that | |
583 | wraps it, to talk to the device and to re-enable interrupts by writing | |
584 | to the command register. | |
585 | ||
586 | Example code using uio_pci_generic | |
587 | ---------------------------------- | |
588 | ||
589 | Here is some sample userspace driver code using uio_pci_generic:: | |
590 | ||
591 | #include <stdlib.h> | |
592 | #include <stdio.h> | |
593 | #include <unistd.h> | |
594 | #include <sys/types.h> | |
595 | #include <sys/stat.h> | |
596 | #include <fcntl.h> | |
597 | #include <errno.h> | |
598 | ||
599 | int main() | |
600 | { | |
601 | int uiofd; | |
602 | int configfd; | |
603 | int err; | |
604 | int i; | |
605 | unsigned icount; | |
606 | unsigned char command_high; | |
607 | ||
608 | uiofd = open("/dev/uio0", O_RDONLY); | |
609 | if (uiofd < 0) { | |
610 | perror("uio open:"); | |
611 | return errno; | |
612 | } | |
613 | configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); | |
614 | if (configfd < 0) { | |
615 | perror("config open:"); | |
616 | return errno; | |
617 | } | |
618 | ||
619 | /* Read and cache command value */ | |
620 | err = pread(configfd, &command_high, 1, 5); | |
621 | if (err != 1) { | |
622 | perror("command config read:"); | |
623 | return errno; | |
624 | } | |
625 | command_high &= ~0x4; | |
626 | ||
627 | for(i = 0;; ++i) { | |
628 | /* Print out a message, for debugging. */ | |
629 | if (i == 0) | |
630 | fprintf(stderr, "Started uio test driver.\n"); | |
631 | else | |
632 | fprintf(stderr, "Interrupts: %d\n", icount); | |
633 | ||
634 | /****************************************/ | |
635 | /* Here we got an interrupt from the | |
636 | device. Do something to it. */ | |
637 | /****************************************/ | |
638 | ||
639 | /* Re-enable interrupts. */ | |
640 | err = pwrite(configfd, &command_high, 1, 5); | |
641 | if (err != 1) { | |
642 | perror("config write:"); | |
643 | break; | |
644 | } | |
645 | ||
646 | /* Wait for next interrupt. */ | |
647 | err = read(uiofd, &icount, 4); | |
648 | if (err != 4) { | |
649 | perror("uio read:"); | |
650 | break; | |
651 | } | |
652 | ||
653 | } | |
654 | return errno; | |
655 | } | |
656 | ||
657 | Generic Hyper-V UIO driver | |
658 | ========================== | |
659 | ||
660 | The generic driver is a kernel module named uio_hv_generic. It | |
661 | supports devices on the Hyper-V VMBus similar to uio_pci_generic on | |
662 | PCI bus. | |
663 | ||
664 | Making the driver recognize the device | |
665 | -------------------------------------- | |
666 | ||
667 | Since the driver does not declare any device GUID's, it will not get | |
668 | loaded automatically and will not automatically bind to any devices, you | |
669 | must load it and allocate id to the driver yourself. For example, to use | |
44625605 | 670 | the network device class GUID:: |
cadf8106 AD |
671 | |
672 | modprobe uio_hv_generic | |
673 | echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id | |
674 | ||
675 | If there already is a hardware specific kernel driver for the device, | |
676 | the generic driver still won't bind to it, in this case if you want to | |
44625605 SH |
677 | use the generic driver for a userspace library you'll have to manually unbind |
678 | the hardware specific driver and bind the generic driver, using the device specific GUID | |
679 | like this:: | |
cadf8106 | 680 | |
44625605 SH |
681 | echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind |
682 | echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind | |
cadf8106 AD |
683 | |
684 | You can verify that the device has been bound to the driver by looking | |
685 | for it in sysfs, for example like the following:: | |
686 | ||
44625605 | 687 | ls -l /sys/bus/vmbus/devices/ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver |
cadf8106 AD |
688 | |
689 | Which if successful should print:: | |
690 | ||
44625605 | 691 | .../ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic |
cadf8106 AD |
692 | |
693 | Things to know about uio_hv_generic | |
694 | ----------------------------------- | |
695 | ||
696 | On each interrupt, uio_hv_generic sets the Interrupt Disable bit. This | |
697 | prevents the device from generating further interrupts until the bit is | |
698 | cleared. The userspace driver should clear this bit before blocking and | |
699 | waiting for more interrupts. | |
700 | ||
ca3cda6f SH |
701 | When host rescinds a device, the interrupt file descriptor is marked down |
702 | and any reads of the interrupt file descriptor will return -EIO. Similar | |
703 | to a closed socket or disconnected serial device. | |
704 | ||
c5702d1b SH |
705 | The vmbus device regions are mapped into uio device resources: |
706 | 0) Channel ring buffers: guest to host and host to guest | |
707 | 1) Guest to host interrupt signalling pages | |
708 | 2) Guest to host monitor page | |
e7d21464 SH |
709 | 3) Network receive buffer region |
710 | 4) Network send buffer region | |
c5702d1b | 711 | |
37b96a49 SH |
712 | If a subchannel is created by a request to host, then the uio_hv_generic |
713 | device driver will create a sysfs binary file for the per-channel ring buffer. | |
02a43659 MCC |
714 | For example:: |
715 | ||
37b96a49 SH |
716 | /sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring |
717 | ||
cadf8106 AD |
718 | Further information |
719 | =================== | |
720 | ||
721 | - `OSADL homepage. <http://www.osadl.org>`_ | |
722 | ||
723 | - `Linutronix homepage. <http://www.linutronix.de>`_ |