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> | |
19 | <email>hjk@linutronix.de</email> | |
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> | |
28 | ||
29 | <legalnotice> | |
30 | <para> | |
31 | This documentation is Free Software licensed under the terms of the | |
32 | GPL version 2. | |
33 | </para> | |
34 | </legalnotice> | |
35 | ||
e3e0a28b HK |
36 | <pubdate>2006-12-11</pubdate> |
37 | ||
38 | <abstract> | |
39 | <para>This HOWTO describes concept and usage of Linux kernel's | |
40 | Userspace I/O system.</para> | |
41 | </abstract> | |
42 | ||
43 | <revhistory> | |
82057791 HK |
44 | <revision> |
45 | <revnumber>0.8</revnumber> | |
46 | <date>2008-12-24</date> | |
47 | <authorinitials>hjk</authorinitials> | |
48 | <revremark>Added name attributes in mem and portio sysfs directories. | |
49 | </revremark> | |
50 | </revision> | |
6a1b6996 HK |
51 | <revision> |
52 | <revnumber>0.7</revnumber> | |
53 | <date>2008-12-23</date> | |
54 | <authorinitials>hjk</authorinitials> | |
55 | <revremark>Added generic platform drivers and offset attribute.</revremark> | |
56 | </revision> | |
a2ab3d30 HK |
57 | <revision> |
58 | <revnumber>0.6</revnumber> | |
59 | <date>2008-12-05</date> | |
60 | <authorinitials>hjk</authorinitials> | |
61 | <revremark>Added description of portio sysfs attributes.</revremark> | |
62 | </revision> | |
328a14e7 HK |
63 | <revision> |
64 | <revnumber>0.5</revnumber> | |
65 | <date>2008-05-22</date> | |
66 | <authorinitials>hjk</authorinitials> | |
67 | <revremark>Added description of write() function.</revremark> | |
68 | </revision> | |
ed423c24 HK |
69 | <revision> |
70 | <revnumber>0.4</revnumber> | |
71 | <date>2007-11-26</date> | |
72 | <authorinitials>hjk</authorinitials> | |
73 | <revremark>Removed section about uio_dummy.</revremark> | |
74 | </revision> | |
e3e0a28b HK |
75 | <revision> |
76 | <revnumber>0.3</revnumber> | |
77 | <date>2007-04-29</date> | |
78 | <authorinitials>hjk</authorinitials> | |
79 | <revremark>Added section about userspace drivers.</revremark> | |
80 | </revision> | |
81 | <revision> | |
82 | <revnumber>0.2</revnumber> | |
83 | <date>2007-02-13</date> | |
84 | <authorinitials>hjk</authorinitials> | |
85 | <revremark>Update after multiple mappings were added.</revremark> | |
86 | </revision> | |
87 | <revision> | |
88 | <revnumber>0.1</revnumber> | |
89 | <date>2006-12-11</date> | |
90 | <authorinitials>hjk</authorinitials> | |
91 | <revremark>First draft.</revremark> | |
92 | </revision> | |
93 | </revhistory> | |
94 | </bookinfo> | |
95 | ||
96 | <chapter id="aboutthisdoc"> | |
4f7e5309 | 97 | <?dbhtml filename="aboutthis.html"?> |
e3e0a28b HK |
98 | <title>About this document</title> |
99 | ||
e3e0a28b HK |
100 | <sect1 id="translations"> |
101 | <?dbhtml filename="translations.html"?> | |
102 | <title>Translations</title> | |
103 | ||
104 | <para>If you know of any translations for this document, or you are | |
105 | interested in translating it, please email me | |
106 | <email>hjk@linutronix.de</email>. | |
107 | </para> | |
108 | </sect1> | |
109 | ||
110 | <sect1 id="preface"> | |
111 | <title>Preface</title> | |
112 | <para> | |
113 | For many types of devices, creating a Linux kernel driver is | |
114 | overkill. All that is really needed is some way to handle an | |
115 | interrupt and provide access to the memory space of the | |
116 | device. The logic of controlling the device does not | |
117 | necessarily have to be within the kernel, as the device does | |
118 | not need to take advantage of any of other resources that the | |
119 | kernel provides. One such common class of devices that are | |
120 | like this are for industrial I/O cards. | |
121 | </para> | |
122 | <para> | |
123 | To address this situation, the userspace I/O system (UIO) was | |
124 | designed. For typical industrial I/O cards, only a very small | |
125 | kernel module is needed. The main part of the driver will run in | |
126 | user space. This simplifies development and reduces the risk of | |
127 | serious bugs within a kernel module. | |
128 | </para> | |
ed423c24 HK |
129 | <para> |
130 | Please note that UIO is not an universal driver interface. Devices | |
131 | that are already handled well by other kernel subsystems (like | |
132 | networking or serial or USB) are no candidates for an UIO driver. | |
133 | Hardware that is ideally suited for an UIO driver fulfills all of | |
134 | the following: | |
135 | </para> | |
136 | <itemizedlist> | |
137 | <listitem> | |
138 | <para>The device has memory that can be mapped. The device can be | |
139 | controlled completely by writing to this memory.</para> | |
140 | </listitem> | |
141 | <listitem> | |
142 | <para>The device usually generates interrupts.</para> | |
143 | </listitem> | |
144 | <listitem> | |
145 | <para>The device does not fit into one of the standard kernel | |
146 | subsystems.</para> | |
147 | </listitem> | |
148 | </itemizedlist> | |
e3e0a28b HK |
149 | </sect1> |
150 | ||
151 | <sect1 id="thanks"> | |
152 | <title>Acknowledgments</title> | |
153 | <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of | |
154 | Linutronix, who have not only written most of the UIO code, but also | |
155 | helped greatly writing this HOWTO by giving me all kinds of background | |
156 | information.</para> | |
157 | </sect1> | |
158 | ||
159 | <sect1 id="feedback"> | |
160 | <title>Feedback</title> | |
161 | <para>Find something wrong with this document? (Or perhaps something | |
162 | right?) I would love to hear from you. Please email me at | |
163 | <email>hjk@linutronix.de</email>.</para> | |
164 | </sect1> | |
165 | </chapter> | |
166 | ||
167 | <chapter id="about"> | |
168 | <?dbhtml filename="about.html"?> | |
169 | <title>About UIO</title> | |
170 | ||
171 | <para>If you use UIO for your card's driver, here's what you get:</para> | |
172 | ||
173 | <itemizedlist> | |
174 | <listitem> | |
175 | <para>only one small kernel module to write and maintain.</para> | |
176 | </listitem> | |
177 | <listitem> | |
178 | <para>develop the main part of your driver in user space, | |
179 | with all the tools and libraries you're used to.</para> | |
180 | </listitem> | |
181 | <listitem> | |
182 | <para>bugs in your driver won't crash the kernel.</para> | |
183 | </listitem> | |
184 | <listitem> | |
185 | <para>updates of your driver can take place without recompiling | |
186 | the kernel.</para> | |
187 | </listitem> | |
e3e0a28b HK |
188 | </itemizedlist> |
189 | ||
190 | <sect1 id="how_uio_works"> | |
191 | <title>How UIO works</title> | |
192 | <para> | |
193 | Each UIO device is accessed through a device file and several | |
194 | sysfs attribute files. The device file will be called | |
195 | <filename>/dev/uio0</filename> for the first device, and | |
196 | <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> | |
197 | and so on for subsequent devices. | |
198 | </para> | |
199 | ||
200 | <para><filename>/dev/uioX</filename> is used to access the | |
201 | address space of the card. Just use | |
202 | <function>mmap()</function> to access registers or RAM | |
203 | locations of your card. | |
204 | </para> | |
205 | ||
206 | <para> | |
207 | Interrupts are handled by reading from | |
208 | <filename>/dev/uioX</filename>. A blocking | |
209 | <function>read()</function> from | |
210 | <filename>/dev/uioX</filename> will return as soon as an | |
211 | interrupt occurs. You can also use | |
212 | <function>select()</function> on | |
213 | <filename>/dev/uioX</filename> to wait for an interrupt. The | |
214 | integer value read from <filename>/dev/uioX</filename> | |
215 | represents the total interrupt count. You can use this number | |
216 | to figure out if you missed some interrupts. | |
217 | </para> | |
328a14e7 HK |
218 | <para> |
219 | For some hardware that has more than one interrupt source internally, | |
220 | but not separate IRQ mask and status registers, there might be | |
221 | situations where userspace cannot determine what the interrupt source | |
222 | was if the kernel handler disables them by writing to the chip's IRQ | |
223 | register. In such a case, the kernel has to disable the IRQ completely | |
224 | to leave the chip's register untouched. Now the userspace part can | |
225 | determine the cause of the interrupt, but it cannot re-enable | |
226 | interrupts. Another cornercase is chips where re-enabling interrupts | |
227 | is a read-modify-write operation to a combined IRQ status/acknowledge | |
228 | register. This would be racy if a new interrupt occurred | |
229 | simultaneously. | |
230 | </para> | |
231 | <para> | |
232 | To address these problems, UIO also implements a write() function. It | |
233 | is normally not used and can be ignored for hardware that has only a | |
234 | single interrupt source or has separate IRQ mask and status registers. | |
235 | If you need it, however, a write to <filename>/dev/uioX</filename> | |
236 | will call the <function>irqcontrol()</function> function implemented | |
237 | by the driver. You have to write a 32-bit value that is usually either | |
238 | 0 or 1 to disable or enable interrupts. If a driver does not implement | |
239 | <function>irqcontrol()</function>, <function>write()</function> will | |
240 | return with <varname>-ENOSYS</varname>. | |
241 | </para> | |
e3e0a28b HK |
242 | |
243 | <para> | |
244 | To handle interrupts properly, your custom kernel module can | |
245 | provide its own interrupt handler. It will automatically be | |
246 | called by the built-in handler. | |
247 | </para> | |
248 | ||
249 | <para> | |
250 | For cards that don't generate interrupts but need to be | |
251 | polled, there is the possibility to set up a timer that | |
252 | triggers the interrupt handler at configurable time intervals. | |
ed423c24 HK |
253 | This interrupt simulation is done by calling |
254 | <function>uio_event_notify()</function> | |
255 | from the timer's event handler. | |
e3e0a28b HK |
256 | </para> |
257 | ||
258 | <para> | |
259 | Each driver provides attributes that are used to read or write | |
260 | variables. These attributes are accessible through sysfs | |
261 | files. A custom kernel driver module can add its own | |
262 | attributes to the device owned by the uio driver, but not added | |
263 | to the UIO device itself at this time. This might change in the | |
264 | future if it would be found to be useful. | |
265 | </para> | |
266 | ||
267 | <para> | |
268 | The following standard attributes are provided by the UIO | |
269 | framework: | |
270 | </para> | |
271 | <itemizedlist> | |
272 | <listitem> | |
273 | <para> | |
274 | <filename>name</filename>: The name of your device. It is | |
275 | recommended to use the name of your kernel module for this. | |
276 | </para> | |
277 | </listitem> | |
278 | <listitem> | |
279 | <para> | |
280 | <filename>version</filename>: A version string defined by your | |
281 | driver. This allows the user space part of your driver to deal | |
282 | with different versions of the kernel module. | |
283 | </para> | |
284 | </listitem> | |
285 | <listitem> | |
286 | <para> | |
287 | <filename>event</filename>: The total number of interrupts | |
288 | handled by the driver since the last time the device node was | |
289 | read. | |
290 | </para> | |
291 | </listitem> | |
292 | </itemizedlist> | |
293 | <para> | |
294 | These attributes appear under the | |
295 | <filename>/sys/class/uio/uioX</filename> directory. Please | |
296 | note that this directory might be a symlink, and not a real | |
297 | directory. Any userspace code that accesses it must be able | |
298 | to handle this. | |
299 | </para> | |
300 | <para> | |
301 | Each UIO device can make one or more memory regions available for | |
302 | memory mapping. This is necessary because some industrial I/O cards | |
303 | require access to more than one PCI memory region in a driver. | |
304 | </para> | |
305 | <para> | |
306 | Each mapping has its own directory in sysfs, the first mapping | |
307 | appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. | |
308 | Subsequent mappings create directories <filename>map1/</filename>, | |
309 | <filename>map2/</filename>, and so on. These directories will only | |
310 | appear if the size of the mapping is not 0. | |
311 | </para> | |
312 | <para> | |
82057791 HK |
313 | Each <filename>mapX/</filename> directory contains four read-only files |
314 | that show attributes of the memory: | |
e3e0a28b HK |
315 | </para> |
316 | <itemizedlist> | |
82057791 HK |
317 | <listitem> |
318 | <para> | |
319 | <filename>name</filename>: A string identifier for this mapping. This | |
320 | is optional, the string can be empty. Drivers can set this to make it | |
321 | easier for userspace to find the correct mapping. | |
322 | </para> | |
323 | </listitem> | |
e3e0a28b HK |
324 | <listitem> |
325 | <para> | |
326 | <filename>addr</filename>: The address of memory that can be mapped. | |
327 | </para> | |
328 | </listitem> | |
329 | <listitem> | |
330 | <para> | |
331 | <filename>size</filename>: The size, in bytes, of the memory | |
332 | pointed to by addr. | |
333 | </para> | |
334 | </listitem> | |
6a1b6996 HK |
335 | <listitem> |
336 | <para> | |
337 | <filename>offset</filename>: The offset, in bytes, that has to be | |
338 | added to the pointer returned by <function>mmap()</function> to get | |
339 | to the actual device memory. This is important if the device's memory | |
340 | is not page aligned. Remember that pointers returned by | |
341 | <function>mmap()</function> are always page aligned, so it is good | |
342 | style to always add this offset. | |
343 | </para> | |
344 | </listitem> | |
e3e0a28b HK |
345 | </itemizedlist> |
346 | ||
347 | <para> | |
348 | From userspace, the different mappings are distinguished by adjusting | |
349 | the <varname>offset</varname> parameter of the | |
350 | <function>mmap()</function> call. To map the memory of mapping N, you | |
351 | have to use N times the page size as your offset: | |
352 | </para> | |
353 | <programlisting format="linespecific"> | |
354 | offset = N * getpagesize(); | |
355 | </programlisting> | |
356 | ||
a2ab3d30 HK |
357 | <para> |
358 | Sometimes there is hardware with memory-like regions that can not be | |
359 | mapped with the technique described here, but there are still ways to | |
360 | access them from userspace. The most common example are x86 ioports. | |
361 | On x86 systems, userspace can access these ioports using | |
362 | <function>ioperm()</function>, <function>iopl()</function>, | |
363 | <function>inb()</function>, <function>outb()</function>, and similar | |
364 | functions. | |
365 | </para> | |
366 | <para> | |
367 | Since these ioport regions can not be mapped, they will not appear under | |
368 | <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory | |
369 | described above. Without information about the port regions a hardware | |
370 | has to offer, it becomes difficult for the userspace part of the | |
371 | driver to find out which ports belong to which UIO device. | |
372 | </para> | |
373 | <para> | |
374 | To address this situation, the new directory | |
375 | <filename>/sys/class/uio/uioX/portio/</filename> was added. It only | |
376 | exists if the driver wants to pass information about one or more port | |
377 | regions to userspace. If that is the case, subdirectories named | |
378 | <filename>port0</filename>, <filename>port1</filename>, and so on, | |
379 | will appear underneath | |
380 | <filename>/sys/class/uio/uioX/portio/</filename>. | |
381 | </para> | |
382 | <para> | |
82057791 HK |
383 | Each <filename>portX/</filename> directory contains four read-only |
384 | files that show name, start, size, and type of the port region: | |
a2ab3d30 HK |
385 | </para> |
386 | <itemizedlist> | |
82057791 HK |
387 | <listitem> |
388 | <para> | |
389 | <filename>name</filename>: A string identifier for this port region. | |
390 | The string is optional and can be empty. Drivers can set it to make it | |
391 | easier for userspace to find a certain port region. | |
392 | </para> | |
393 | </listitem> | |
a2ab3d30 HK |
394 | <listitem> |
395 | <para> | |
396 | <filename>start</filename>: The first port of this region. | |
397 | </para> | |
398 | </listitem> | |
399 | <listitem> | |
400 | <para> | |
401 | <filename>size</filename>: The number of ports in this region. | |
402 | </para> | |
403 | </listitem> | |
404 | <listitem> | |
405 | <para> | |
406 | <filename>porttype</filename>: A string describing the type of port. | |
407 | </para> | |
408 | </listitem> | |
409 | </itemizedlist> | |
410 | ||
411 | ||
e3e0a28b HK |
412 | </sect1> |
413 | </chapter> | |
414 | ||
e3e0a28b HK |
415 | <chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> |
416 | <?dbhtml filename="custom_kernel_module.html"?> | |
417 | <title>Writing your own kernel module</title> | |
418 | <para> | |
ed423c24 | 419 | Please have a look at <filename>uio_cif.c</filename> as an |
e3e0a28b HK |
420 | example. The following paragraphs explain the different |
421 | sections of this file. | |
422 | </para> | |
423 | ||
424 | <sect1 id="uio_info"> | |
425 | <title>struct uio_info</title> | |
426 | <para> | |
427 | This structure tells the framework the details of your driver, | |
428 | Some of the members are required, others are optional. | |
429 | </para> | |
430 | ||
431 | <itemizedlist> | |
432 | <listitem><para> | |
b8ac9fc0 | 433 | <varname>const char *name</varname>: Required. The name of your driver as |
e3e0a28b HK |
434 | it will appear in sysfs. I recommend using the name of your module for this. |
435 | </para></listitem> | |
436 | ||
437 | <listitem><para> | |
b8ac9fc0 | 438 | <varname>const char *version</varname>: Required. This string appears in |
e3e0a28b HK |
439 | <filename>/sys/class/uio/uioX/version</filename>. |
440 | </para></listitem> | |
441 | ||
442 | <listitem><para> | |
443 | <varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you | |
444 | have memory that can be mapped with <function>mmap()</function>. For each | |
445 | mapping you need to fill one of the <varname>uio_mem</varname> structures. | |
446 | See the description below for details. | |
447 | </para></listitem> | |
448 | ||
a2ab3d30 HK |
449 | <listitem><para> |
450 | <varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required | |
451 | if you want to pass information about ioports to userspace. For each port | |
452 | region you need to fill one of the <varname>uio_port</varname> structures. | |
453 | See the description below for details. | |
454 | </para></listitem> | |
455 | ||
e3e0a28b HK |
456 | <listitem><para> |
457 | <varname>long irq</varname>: Required. If your hardware generates an | |
458 | interrupt, it's your modules task to determine the irq number during | |
459 | initialization. If you don't have a hardware generated interrupt but | |
460 | want to trigger the interrupt handler in some other way, set | |
ed423c24 HK |
461 | <varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. |
462 | If you had no interrupt at all, you could set | |
e3e0a28b HK |
463 | <varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this |
464 | rarely makes sense. | |
465 | </para></listitem> | |
466 | ||
467 | <listitem><para> | |
468 | <varname>unsigned long irq_flags</varname>: Required if you've set | |
469 | <varname>irq</varname> to a hardware interrupt number. The flags given | |
470 | here will be used in the call to <function>request_irq()</function>. | |
471 | </para></listitem> | |
472 | ||
473 | <listitem><para> | |
474 | <varname>int (*mmap)(struct uio_info *info, struct vm_area_struct | |
475 | *vma)</varname>: Optional. If you need a special | |
476 | <function>mmap()</function> function, you can set it here. If this | |
477 | pointer is not NULL, your <function>mmap()</function> will be called | |
478 | instead of the built-in one. | |
479 | </para></listitem> | |
480 | ||
481 | <listitem><para> | |
482 | <varname>int (*open)(struct uio_info *info, struct inode *inode) | |
483 | </varname>: Optional. You might want to have your own | |
484 | <function>open()</function>, e.g. to enable interrupts only when your | |
485 | device is actually used. | |
486 | </para></listitem> | |
487 | ||
488 | <listitem><para> | |
489 | <varname>int (*release)(struct uio_info *info, struct inode *inode) | |
490 | </varname>: Optional. If you define your own | |
491 | <function>open()</function>, you will probably also want a custom | |
492 | <function>release()</function> function. | |
493 | </para></listitem> | |
328a14e7 HK |
494 | |
495 | <listitem><para> | |
496 | <varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on) | |
497 | </varname>: Optional. If you need to be able to enable or disable | |
498 | interrupts from userspace by writing to <filename>/dev/uioX</filename>, | |
499 | you can implement this function. The parameter <varname>irq_on</varname> | |
500 | will be 0 to disable interrupts and 1 to enable them. | |
501 | </para></listitem> | |
e3e0a28b HK |
502 | </itemizedlist> |
503 | ||
504 | <para> | |
505 | Usually, your device will have one or more memory regions that can be mapped | |
506 | to user space. For each region, you have to set up a | |
507 | <varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. | |
508 | Here's a description of the fields of <varname>struct uio_mem</varname>: | |
509 | </para> | |
510 | ||
511 | <itemizedlist> | |
512 | <listitem><para> | |
513 | <varname>int memtype</varname>: Required if the mapping is used. Set this to | |
514 | <varname>UIO_MEM_PHYS</varname> if you you have physical memory on your | |
515 | card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical | |
516 | memory (e.g. allocated with <function>kmalloc()</function>). There's also | |
517 | <varname>UIO_MEM_VIRTUAL</varname> for virtual memory. | |
518 | </para></listitem> | |
519 | ||
520 | <listitem><para> | |
521 | <varname>unsigned long addr</varname>: Required if the mapping is used. | |
522 | Fill in the address of your memory block. This address is the one that | |
523 | appears in sysfs. | |
524 | </para></listitem> | |
525 | ||
526 | <listitem><para> | |
527 | <varname>unsigned long size</varname>: Fill in the size of the | |
528 | memory block that <varname>addr</varname> points to. If <varname>size</varname> | |
529 | is zero, the mapping is considered unused. Note that you | |
530 | <emphasis>must</emphasis> initialize <varname>size</varname> with zero for | |
531 | all unused mappings. | |
532 | </para></listitem> | |
533 | ||
534 | <listitem><para> | |
535 | <varname>void *internal_addr</varname>: If you have to access this memory | |
536 | region from within your kernel module, you will want to map it internally by | |
537 | using something like <function>ioremap()</function>. Addresses | |
538 | returned by this function cannot be mapped to user space, so you must not | |
539 | store it in <varname>addr</varname>. Use <varname>internal_addr</varname> | |
540 | instead to remember such an address. | |
541 | </para></listitem> | |
542 | </itemizedlist> | |
543 | ||
544 | <para> | |
545 | Please do not touch the <varname>kobj</varname> element of | |
546 | <varname>struct uio_mem</varname>! It is used by the UIO framework | |
547 | to set up sysfs files for this mapping. Simply leave it alone. | |
548 | </para> | |
a2ab3d30 HK |
549 | |
550 | <para> | |
551 | Sometimes, your device can have one or more port regions which can not be | |
552 | mapped to userspace. But if there are other possibilities for userspace to | |
553 | access these ports, it makes sense to make information about the ports | |
554 | available in sysfs. For each region, you have to set up a | |
555 | <varname>struct uio_port</varname> in the <varname>port[]</varname> array. | |
556 | Here's a description of the fields of <varname>struct uio_port</varname>: | |
557 | </para> | |
558 | ||
559 | <itemizedlist> | |
560 | <listitem><para> | |
561 | <varname>char *porttype</varname>: Required. Set this to one of the predefined | |
562 | constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 | |
563 | architectures. | |
564 | </para></listitem> | |
565 | ||
566 | <listitem><para> | |
567 | <varname>unsigned long start</varname>: Required if the port region is used. | |
568 | Fill in the number of the first port of this region. | |
569 | </para></listitem> | |
570 | ||
571 | <listitem><para> | |
572 | <varname>unsigned long size</varname>: Fill in the number of ports in this | |
573 | region. If <varname>size</varname> is zero, the region is considered unused. | |
574 | Note that you <emphasis>must</emphasis> initialize <varname>size</varname> | |
575 | with zero for all unused regions. | |
576 | </para></listitem> | |
577 | </itemizedlist> | |
578 | ||
579 | <para> | |
580 | Please do not touch the <varname>portio</varname> element of | |
581 | <varname>struct uio_port</varname>! It is used internally by the UIO | |
582 | framework to set up sysfs files for this region. Simply leave it alone. | |
583 | </para> | |
584 | ||
e3e0a28b HK |
585 | </sect1> |
586 | ||
587 | <sect1 id="adding_irq_handler"> | |
588 | <title>Adding an interrupt handler</title> | |
589 | <para> | |
590 | What you need to do in your interrupt handler depends on your | |
591 | hardware and on how you want to handle it. You should try to | |
592 | keep the amount of code in your kernel interrupt handler low. | |
593 | If your hardware requires no action that you | |
594 | <emphasis>have</emphasis> to perform after each interrupt, | |
595 | then your handler can be empty.</para> <para>If, on the other | |
596 | hand, your hardware <emphasis>needs</emphasis> some action to | |
597 | be performed after each interrupt, then you | |
598 | <emphasis>must</emphasis> do it in your kernel module. Note | |
599 | that you cannot rely on the userspace part of your driver. Your | |
600 | userspace program can terminate at any time, possibly leaving | |
601 | your hardware in a state where proper interrupt handling is | |
602 | still required. | |
603 | </para> | |
604 | ||
605 | <para> | |
606 | There might also be applications where you want to read data | |
607 | from your hardware at each interrupt and buffer it in a piece | |
608 | of kernel memory you've allocated for that purpose. With this | |
609 | technique you could avoid loss of data if your userspace | |
610 | program misses an interrupt. | |
611 | </para> | |
612 | ||
613 | <para> | |
614 | A note on shared interrupts: Your driver should support | |
615 | interrupt sharing whenever this is possible. It is possible if | |
616 | and only if your driver can detect whether your hardware has | |
617 | triggered the interrupt or not. This is usually done by looking | |
618 | at an interrupt status register. If your driver sees that the | |
619 | IRQ bit is actually set, it will perform its actions, and the | |
620 | handler returns IRQ_HANDLED. If the driver detects that it was | |
621 | not your hardware that caused the interrupt, it will do nothing | |
622 | and return IRQ_NONE, allowing the kernel to call the next | |
623 | possible interrupt handler. | |
624 | </para> | |
625 | ||
626 | <para> | |
627 | If you decide not to support shared interrupts, your card | |
628 | won't work in computers with no free interrupts. As this | |
629 | frequently happens on the PC platform, you can save yourself a | |
630 | lot of trouble by supporting interrupt sharing. | |
631 | </para> | |
632 | </sect1> | |
633 | ||
6a1b6996 HK |
634 | <sect1 id="using_uio_pdrv"> |
635 | <title>Using uio_pdrv for platform devices</title> | |
636 | <para> | |
637 | In many cases, UIO drivers for platform devices can be handled in a | |
638 | generic way. In the same place where you define your | |
639 | <varname>struct platform_device</varname>, you simply also implement | |
640 | your interrupt handler and fill your | |
641 | <varname>struct uio_info</varname>. A pointer to this | |
642 | <varname>struct uio_info</varname> is then used as | |
643 | <varname>platform_data</varname> for your platform device. | |
644 | </para> | |
645 | <para> | |
646 | You also need to set up an array of <varname>struct resource</varname> | |
647 | containing addresses and sizes of your memory mappings. This | |
648 | information is passed to the driver using the | |
649 | <varname>.resource</varname> and <varname>.num_resources</varname> | |
650 | elements of <varname>struct platform_device</varname>. | |
651 | </para> | |
652 | <para> | |
653 | You now have to set the <varname>.name</varname> element of | |
654 | <varname>struct platform_device</varname> to | |
655 | <varname>"uio_pdrv"</varname> to use the generic UIO platform device | |
656 | driver. This driver will fill the <varname>mem[]</varname> array | |
657 | according to the resources given, and register the device. | |
658 | </para> | |
659 | <para> | |
660 | The advantage of this approach is that you only have to edit a file | |
661 | you need to edit anyway. You do not have to create an extra driver. | |
662 | </para> | |
663 | </sect1> | |
664 | ||
665 | <sect1 id="using_uio_pdrv_genirq"> | |
666 | <title>Using uio_pdrv_genirq for platform devices</title> | |
667 | <para> | |
668 | Especially in embedded devices, you frequently find chips where the | |
669 | irq pin is tied to its own dedicated interrupt line. In such cases, | |
670 | where you can be really sure the interrupt is not shared, we can take | |
671 | the concept of <varname>uio_pdrv</varname> one step further and use a | |
672 | generic interrupt handler. That's what | |
673 | <varname>uio_pdrv_genirq</varname> does. | |
674 | </para> | |
675 | <para> | |
676 | The setup for this driver is the same as described above for | |
677 | <varname>uio_pdrv</varname>, except that you do not implement an | |
678 | interrupt handler. The <varname>.handler</varname> element of | |
679 | <varname>struct uio_info</varname> must remain | |
680 | <varname>NULL</varname>. The <varname>.irq_flags</varname> element | |
681 | must not contain <varname>IRQF_SHARED</varname>. | |
682 | </para> | |
683 | <para> | |
684 | You will set the <varname>.name</varname> element of | |
685 | <varname>struct platform_device</varname> to | |
686 | <varname>"uio_pdrv_genirq"</varname> to use this driver. | |
687 | </para> | |
688 | <para> | |
689 | The generic interrupt handler of <varname>uio_pdrv_genirq</varname> | |
690 | will simply disable the interrupt line using | |
691 | <function>disable_irq_nosync()</function>. After doing its work, | |
692 | userspace can reenable the interrupt by writing 0x00000001 to the UIO | |
693 | device file. The driver already implements an | |
694 | <function>irq_control()</function> to make this possible, you must not | |
695 | implement your own. | |
696 | </para> | |
697 | <para> | |
698 | Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of | |
699 | interrupt handler code. You also do not need to know anything about | |
700 | the chip's internal registers to create the kernel part of the driver. | |
701 | All you need to know is the irq number of the pin the chip is | |
702 | connected to. | |
703 | </para> | |
704 | </sect1> | |
705 | ||
e3e0a28b HK |
706 | </chapter> |
707 | ||
708 | <chapter id="userspace_driver" xreflabel="Writing a driver in user space"> | |
709 | <?dbhtml filename="userspace_driver.html"?> | |
710 | <title>Writing a driver in userspace</title> | |
711 | <para> | |
712 | Once you have a working kernel module for your hardware, you can | |
713 | write the userspace part of your driver. You don't need any special | |
714 | libraries, your driver can be written in any reasonable language, | |
715 | you can use floating point numbers and so on. In short, you can | |
716 | use all the tools and libraries you'd normally use for writing a | |
717 | userspace application. | |
718 | </para> | |
719 | ||
720 | <sect1 id="getting_uio_information"> | |
721 | <title>Getting information about your UIO device</title> | |
722 | <para> | |
723 | Information about all UIO devices is available in sysfs. The | |
724 | first thing you should do in your driver is check | |
725 | <varname>name</varname> and <varname>version</varname> to | |
726 | make sure your talking to the right device and that its kernel | |
727 | driver has the version you expect. | |
728 | </para> | |
729 | <para> | |
730 | You should also make sure that the memory mapping you need | |
731 | exists and has the size you expect. | |
732 | </para> | |
733 | <para> | |
734 | There is a tool called <varname>lsuio</varname> that lists | |
735 | UIO devices and their attributes. It is available here: | |
736 | </para> | |
737 | <para> | |
738 | <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> | |
739 | http://www.osadl.org/projects/downloads/UIO/user/</ulink> | |
740 | </para> | |
741 | <para> | |
742 | With <varname>lsuio</varname> you can quickly check if your | |
743 | kernel module is loaded and which attributes it exports. | |
744 | Have a look at the manpage for details. | |
745 | </para> | |
746 | <para> | |
747 | The source code of <varname>lsuio</varname> can serve as an | |
748 | example for getting information about an UIO device. | |
749 | The file <filename>uio_helper.c</filename> contains a lot of | |
750 | functions you could use in your userspace driver code. | |
751 | </para> | |
752 | </sect1> | |
753 | ||
754 | <sect1 id="mmap_device_memory"> | |
755 | <title>mmap() device memory</title> | |
756 | <para> | |
757 | After you made sure you've got the right device with the | |
758 | memory mappings you need, all you have to do is to call | |
759 | <function>mmap()</function> to map the device's memory | |
760 | to userspace. | |
761 | </para> | |
762 | <para> | |
763 | The parameter <varname>offset</varname> of the | |
764 | <function>mmap()</function> call has a special meaning | |
765 | for UIO devices: It is used to select which mapping of | |
766 | your device you want to map. To map the memory of | |
767 | mapping N, you have to use N times the page size as | |
768 | your offset: | |
769 | </para> | |
770 | <programlisting format="linespecific"> | |
771 | offset = N * getpagesize(); | |
772 | </programlisting> | |
773 | <para> | |
774 | N starts from zero, so if you've got only one memory | |
775 | range to map, set <varname>offset = 0</varname>. | |
776 | A drawback of this technique is that memory is always | |
777 | mapped beginning with its start address. | |
778 | </para> | |
779 | </sect1> | |
780 | ||
781 | <sect1 id="wait_for_interrupts"> | |
782 | <title>Waiting for interrupts</title> | |
783 | <para> | |
784 | After you successfully mapped your devices memory, you | |
785 | can access it like an ordinary array. Usually, you will | |
786 | perform some initialization. After that, your hardware | |
787 | starts working and will generate an interrupt as soon | |
788 | as it's finished, has some data available, or needs your | |
789 | attention because an error occured. | |
790 | </para> | |
791 | <para> | |
792 | <filename>/dev/uioX</filename> is a read-only file. A | |
793 | <function>read()</function> will always block until an | |
794 | interrupt occurs. There is only one legal value for the | |
795 | <varname>count</varname> parameter of | |
796 | <function>read()</function>, and that is the size of a | |
797 | signed 32 bit integer (4). Any other value for | |
798 | <varname>count</varname> causes <function>read()</function> | |
799 | to fail. The signed 32 bit integer read is the interrupt | |
800 | count of your device. If the value is one more than the value | |
801 | you read the last time, everything is OK. If the difference | |
802 | is greater than one, you missed interrupts. | |
803 | </para> | |
804 | <para> | |
805 | You can also use <function>select()</function> on | |
806 | <filename>/dev/uioX</filename>. | |
807 | </para> | |
808 | </sect1> | |
809 | ||
810 | </chapter> | |
811 | ||
812 | <appendix id="app1"> | |
813 | <title>Further information</title> | |
814 | <itemizedlist> | |
815 | <listitem><para> | |
816 | <ulink url="http://www.osadl.org"> | |
817 | OSADL homepage.</ulink> | |
818 | </para></listitem> | |
819 | <listitem><para> | |
820 | <ulink url="http://www.linutronix.de"> | |
821 | Linutronix homepage.</ulink> | |
822 | </para></listitem> | |
823 | </itemizedlist> | |
824 | </appendix> | |
825 | ||
826 | </book> |