UIO: Documentation for UIO ioport info handling

This patch updates UIO documentation with the changes introduced by previous UIO patch. Signed-off-by: Hans J. Koch <hjk@linutronix.de> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

UIO: Documentation for UIO ioport info handling
This patch updates UIO documentation with the changes introduced by previous UIO patch. Signed-off-by: Hans J. Koch <hjk@linutronix.de> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Hans J. Koch · Greg Kroah-Hartman
1 parent e70c412ee4
Showing 1 changed file with 97 additions and 0 deletions Side-by-side Diff
Documentation/DocBook/uio-howto.tmpl
@@ -42,6 +42,12 @@
  
 <revhistory>
 	<revision>
+	<revnumber>0.6</revnumber>
+	<date>2008-12-05</date>
+	<authorinitials>hjk</authorinitials>
+	<revremark>Added description of portio sysfs attributes.</revremark>
+	</revision>
+	<revision>
 	<revnumber>0.5</revnumber>
 	<date>2008-05-22</date>
 	<authorinitials>hjk</authorinitials>
@@ -318,6 +324,54 @@
 offset = N * getpagesize();
 </programlisting>
  
+<para>
+	Sometimes there is hardware with memory-like regions that can not be
+	mapped with the technique described here, but there are still ways to
+	access them from userspace. The most common example are x86 ioports.
+	On x86 systems, userspace can access these ioports using
+	<function>ioperm()</function>, <function>iopl()</function>,
+	<function>inb()</function>, <function>outb()</function>, and similar
+	functions.
+</para>
+<para>
+	Since these ioport regions can not be mapped, they will not appear under
+	<filename>/sys/class/uio/uioX/maps/</filename> like the normal memory
+	described above. Without information about the port regions a hardware
+	has to offer, it becomes difficult for the userspace part of the
+	driver to find out which ports belong to which UIO device.
+</para>
+<para>
+	To address this situation, the new directory
+	<filename>/sys/class/uio/uioX/portio/</filename> was added. It only
+	exists if the driver wants to pass information about one or more port
+	regions to userspace. If that is the case, subdirectories named
+	<filename>port0</filename>, <filename>port1</filename>, and so on,
+	will appear underneath
+	<filename>/sys/class/uio/uioX/portio/</filename>.
+</para>
+<para>
+	Each <filename>portX/</filename> directory contains three read-only
+	files that show start, size, and type of the port region:
+</para>
+<itemizedlist>
+<listitem>
+	<para>
+	<filename>start</filename>: The first port of this region.
+	</para>
+</listitem>
+<listitem>
+	<para>
+	<filename>size</filename>: The number of ports in this region.
+	</para>
+</listitem>
+<listitem>
+	<para>
+	<filename>porttype</filename>: A string describing the type of port.
+	</para>
+</listitem>
+</itemizedlist>
+
+
 </sect1>
 </chapter>
  
@@ -356,6 +410,13 @@
 </para></listitem>
  
 <listitem><para>
+<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
+if you want to pass information about ioports to userspace. For each port
+region you need to fill one of the <varname>uio_port</varname> structures.
+See the description below for details.
+</para></listitem>
+
+<listitem><para>
 <varname>long irq</varname>: Required. If your hardware generates an
 interrupt, it's your modules task to determine the irq number during
 initialization. If you don't have a hardware generated interrupt but
@@ -448,6 +509,42 @@
 <varname>struct uio_mem</varname>! It is used by the UIO framework
 to set up sysfs files for this mapping. Simply leave it alone.
 </para>
+
+<para>
+Sometimes, your device can have one or more port regions which can not be
+mapped to userspace. But if there are other possibilities for userspace to
+access these ports, it makes sense to make information about the ports
+available in sysfs. For each region, you have to set up a
+<varname>struct uio_port</varname> in the <varname>port[]</varname> array.
+Here's a description of the fields of <varname>struct uio_port</varname>:
+</para>
+
+<itemizedlist>
+<listitem><para>
+<varname>char *porttype</varname>: Required. Set this to one of the predefined
+constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
+architectures.
+</para></listitem>
+
+<listitem><para>
+<varname>unsigned long start</varname>: Required if the port region is used.
+Fill in the number of the first port of this region.
+</para></listitem>
+
+<listitem><para>
+<varname>unsigned long size</varname>: Fill in the number of ports in this
+region. If <varname>size</varname> is zero, the region is considered unused.
+Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
+with zero for all unused regions.
+</para></listitem>
+</itemizedlist>
+
+<para>
+Please do not touch the <varname>portio</varname> element of
+<varname>struct uio_port</varname>! It is used internally by the UIO
+framework to set up sysfs files for this region. Simply leave it alone.
+</para>
+
 </sect1>
  
 <sect1 id="adding_irq_handler">
...	...	@@ -42,6 +42,12 @@
42	42
43	43	<revhistory>
44	44	<revision>
	45	+ <revnumber>0.6</revnumber>
	46	+ <date>2008-12-05</date>
	47	+ <authorinitials>hjk</authorinitials>
	48	+ <revremark>Added description of portio sysfs attributes.</revremark>
	49	+ </revision>
	50	+ <revision>
45	51	<revnumber>0.5</revnumber>
46	52	<date>2008-05-22</date>
47	53	<authorinitials>hjk</authorinitials>
...	...	@@ -318,6 +324,54 @@
318	324	offset = N * getpagesize();
319	325	</programlisting>
320	326
	327	+<para>
	328	+ Sometimes there is hardware with memory-like regions that can not be
	329	+ mapped with the technique described here, but there are still ways to
	330	+ access them from userspace. The most common example are x86 ioports.
	331	+ On x86 systems, userspace can access these ioports using
	332	+ <function>ioperm()</function>, <function>iopl()</function>,
	333	+ <function>inb()</function>, <function>outb()</function>, and similar
	334	+ functions.
	335	+</para>
	336	+<para>
	337	+ Since these ioport regions can not be mapped, they will not appear under
	338	+ <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory
	339	+ described above. Without information about the port regions a hardware
	340	+ has to offer, it becomes difficult for the userspace part of the
	341	+ driver to find out which ports belong to which UIO device.
	342	+</para>
	343	+<para>
	344	+ To address this situation, the new directory
	345	+ <filename>/sys/class/uio/uioX/portio/</filename> was added. It only
	346	+ exists if the driver wants to pass information about one or more port
	347	+ regions to userspace. If that is the case, subdirectories named
	348	+ <filename>port0</filename>, <filename>port1</filename>, and so on,
	349	+ will appear underneath
	350	+ <filename>/sys/class/uio/uioX/portio/</filename>.
	351	+</para>
	352	+<para>
	353	+ Each <filename>portX/</filename> directory contains three read-only
	354	+ files that show start, size, and type of the port region:
	355	+</para>
	356	+<itemizedlist>
	357	+<listitem>
	358	+ <para>
	359	+ <filename>start</filename>: The first port of this region.
	360	+ </para>
	361	+</listitem>
	362	+<listitem>
	363	+ <para>
	364	+ <filename>size</filename>: The number of ports in this region.
	365	+ </para>
	366	+</listitem>
	367	+<listitem>
	368	+ <para>
	369	+ <filename>porttype</filename>: A string describing the type of port.
	370	+ </para>
	371	+</listitem>
	372	+</itemizedlist>
	373	+
	374	+
321	375	</sect1>
322	376	</chapter>
323	377
...	...	@@ -356,6 +410,13 @@
356	410	</para></listitem>
357	411
358	412	<listitem><para>
	413	+<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
	414	+if you want to pass information about ioports to userspace. For each port
	415	+region you need to fill one of the <varname>uio_port</varname> structures.
	416	+See the description below for details.
	417	+</para></listitem>
	418	+
	419	+<listitem><para>
359	420	<varname>long irq</varname>: Required. If your hardware generates an
360	421	interrupt, it's your modules task to determine the irq number during
361	422	initialization. If you don't have a hardware generated interrupt but
...	...	@@ -448,6 +509,42 @@
448	509	<varname>struct uio_mem</varname>! It is used by the UIO framework
449	510	to set up sysfs files for this mapping. Simply leave it alone.
450	511	</para>
	512	+
	513	+<para>
	514	+Sometimes, your device can have one or more port regions which can not be
	515	+mapped to userspace. But if there are other possibilities for userspace to
	516	+access these ports, it makes sense to make information about the ports
	517	+available in sysfs. For each region, you have to set up a
	518	+<varname>struct uio_port</varname> in the <varname>port[]</varname> array.
	519	+Here's a description of the fields of <varname>struct uio_port</varname>:
	520	+</para>
	521	+
	522	+<itemizedlist>
	523	+<listitem><para>
	524	+<varname>char *porttype</varname>: Required. Set this to one of the predefined
	525	+constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
	526	+architectures.
	527	+</para></listitem>
	528	+
	529	+<listitem><para>
	530	+<varname>unsigned long start</varname>: Required if the port region is used.
	531	+Fill in the number of the first port of this region.
	532	+</para></listitem>
	533	+
	534	+<listitem><para>
	535	+<varname>unsigned long size</varname>: Fill in the number of ports in this
	536	+region. If <varname>size</varname> is zero, the region is considered unused.
	537	+Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
	538	+with zero for all unused regions.
	539	+</para></listitem>
	540	+</itemizedlist>
	541	+
	542	+<para>
	543	+Please do not touch the <varname>portio</varname> element of
	544	+<varname>struct uio_port</varname>! It is used internally by the UIO
	545	+framework to set up sysfs files for this region. Simply leave it alone.
	546	+</para>
	547	+
451	548	</sect1>
452	549
453	550	<sect1 id="adding_irq_handler">