About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / uio-howto.tmpl


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

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@hansjkoch.de</email>
20		</address>
21	    </affiliation>
22	</author>
23	
24	<copyright>
25		<year>2006-2008</year>
26		<holder>Hans-Jürgen Koch.</holder>
27	</copyright>
28	<copyright>
29		<year>2009</year>
30		<holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder>
31	</copyright>
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	
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>
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>
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>
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>
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>
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>
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>
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>
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">
115	<?dbhtml filename="aboutthis.html"?>
116	<title>About this document</title>
117	
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
124	<email>hjk@hansjkoch.de</email>.
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>
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>
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
181		<email>hjk@hansjkoch.de</email>.</para>
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>
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>
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>
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.
271		This interrupt simulation is done by calling
272		<function>uio_event_notify()</function>
273		from the timer's event handler.
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>
331		Each <filename>mapX/</filename> directory contains four read-only files
332		that show attributes of the memory:
333	</para>
334	<itemizedlist>
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>
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>
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>
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	
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>
401		Each <filename>portX/</filename> directory contains four read-only
402		files that show name, start, size, and type of the port region:
403	</para>
404	<itemizedlist>
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>
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	
430	</sect1>
431	</chapter>
432	
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>
437		Please have a look at <filename>uio_cif.c</filename> as an
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>
451	<varname>const char *name</varname>: Required. The name of your driver as
452	it will appear in sysfs. I recommend using the name of your module for this.
453	</para></listitem>
454	
455	<listitem><para>
456	<varname>const char *version</varname>: Required. This string appears in
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	
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	
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
479	<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
480	If you had no interrupt at all, you could set
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>
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>
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>
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	
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>
544	<varname>phys_addr_t addr</varname>: Required if the mapping is used.
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>
550	<varname>resource_size_t size</varname>: Fill in the size of the
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>
568	Please do not touch the <varname>map</varname> element of
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>
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	
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	
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	
729	<sect1 id="using-uio_dmem_genirq">
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>
756		<listitem><para><varname>struct uio_info uioinfo</varname>: The same
757		structure used as the  <varname>uio_pdrv_genirq</varname> platform
758		data</para></listitem>
759		<listitem><para><varname>unsigned int *dynamic_region_sizes</varname>:
760		Pointer to list of sizes of dynamic memory regions to be mapped into
761		user space.
762		</para></listitem>
763		<listitem><para><varname>unsigned int num_dynamic_regions</varname>:
764		Number of elements in <varname>dynamic_region_sizes</varname> array.
765		</para></listitem>
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.
776		Similar to static memory resources, the memory region information for
777		dynamic regions is then visible via sysfs at
778		<varname>/sys/class/uio/uioX/maps/mapY/*</varname>.
779		The dynamic memory regions will be freed when the UIO device file is
780		closed. When no processes are holding the device file open, the address
781		returned to userspace is ~0.
782		</para>
783	</sect1>
784	
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
868		attention because an error occurred.
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	
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 &quot;8086 10f5&quot; &gt; /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 &gt; /sys/bus/pci/drivers/e1000e/unbind
920	    echo -n 0000:00:19.0 &gt; /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 -&gt; ../../../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 &lt;stdlib.h&gt;
972	#include &lt;stdio.h&gt;
973	#include &lt;unistd.h&gt;
974	#include &lt;sys/types.h&gt;
975	#include &lt;sys/stat.h&gt;
976	#include &lt;fcntl.h&gt;
977	#include &lt;errno.h&gt;
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(&quot;/dev/uio0&quot;, O_RDONLY);
989		if (uiofd &lt; 0) {
990			perror(&quot;uio open:&quot;);
991			return errno;
992		}
993		configfd = open(&quot;/sys/class/uio/uio0/device/config&quot;, O_RDWR);
994		if (configfd &lt; 0) {
995			perror(&quot;config open:&quot;);
996			return errno;
997		}
998	
999		/* Read and cache command value */
1000		err = pread(configfd, &amp;command_high, 1, 5);
1001		if (err != 1) {
1002			perror(&quot;command config read:&quot;);
1003			return errno;
1004		}
1005		command_high &amp;= ~0x4;
1006	
1007		for(i = 0;; ++i) {
1008			/* Print out a message, for debugging. */
1009			if (i == 0)
1010				fprintf(stderr, &quot;Started uio test driver.\n&quot;);
1011			else
1012				fprintf(stderr, &quot;Interrupts: %d\n&quot;, 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, &amp;command_high, 1, 5);
1021			if (err != 1) {
1022				perror(&quot;config write:&quot;);
1023				break;
1024			}
1025	
1026			/* Wait for next interrupt. */
1027			err = read(uiofd, &amp;icount, 4);
1028			if (err != 4) {
1029				perror(&quot;uio read:&quot;);
1030				break;
1031			}
1032	
1033		}
1034		return errno;
1035	}
1036	
1037	</programlisting>
1038		</para>
1039	</sect1>
1040	
1041	</chapter>
1042	
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 &quot;f8615163-df3e-46c5-913f-f2d2f965ed0e&quot; &gt; /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 &gt; /sys/bus/vmbus/drivers/hv_netvsc/unbind
1071		  echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 &gt; /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 -&gt; ../../../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	
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>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog