About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / uio-howto.tmpl

Custom Search

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.