aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorMichael S. Tsirkin <mst@redhat.com>2009-07-20 03:29:34 -0400
committerGreg Kroah-Hartman <gregkh@suse.de>2009-09-15 12:50:48 -0400
commitccb86a6907c9ba7b5be5f521362fc308e80bed34 (patch)
treee10f409f582a50243124d9b8bf38b2ec8be8d5ac /Documentation
parenta56af87648054089d89874b52e3fc23ed4f274ad (diff)
uio: add generic driver for PCI 2.3 devices
This adds a generic uio driver that can bind to any PCI device. First user will be virtualization where a qemu userspace process needs to give guest OS access to the device. Interrupts are handled using the Interrupt Disable bit in the PCI command register and Interrupt Status bit in the PCI status register. All devices compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should support these bits. Driver detects this support, and won't bind to devices which do not support the Interrupt Disable Bit in the command register. It's expected that more features of interest to virtualization will be added to this driver in the future. Possibilities are: mmap for device resources, MSI/MSI-X, eventfd (to interface with kvm), iommu. Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Acked-by: Chris Wright <chrisw@redhat.com> Signed-off-by: Hans J. Koch <hjk@linutronix.de> Acked-by: Jesse Barnes <jbarnes@virtuousgeek.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/uio-howto.tmpl163
1 files changed, 163 insertions, 0 deletions
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
index 8f6e3b2403c7..4d4ce0e61e42 100644
--- a/Documentation/DocBook/uio-howto.tmpl
+++ b/Documentation/DocBook/uio-howto.tmpl
@@ -25,6 +25,10 @@
25 <year>2006-2008</year> 25 <year>2006-2008</year>
26 <holder>Hans-Jürgen Koch.</holder> 26 <holder>Hans-Jürgen Koch.</holder>
27</copyright> 27</copyright>
28<copyright>
29 <year>2009</year>
30 <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder>
31</copyright>
28 32
29<legalnotice> 33<legalnotice>
30<para> 34<para>
@@ -42,6 +46,13 @@ GPL version 2.
42 46
43<revhistory> 47<revhistory>
44 <revision> 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>
45 <revnumber>0.8</revnumber> 56 <revnumber>0.8</revnumber>
46 <date>2008-12-24</date> 57 <date>2008-12-24</date>
47 <authorinitials>hjk</authorinitials> 58 <authorinitials>hjk</authorinitials>
@@ -809,6 +820,158 @@ framework to set up sysfs files for this region. Simply leave it alone.
809 820
810</chapter> 821</chapter>
811 822
823<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards">
824<?dbhtml filename="uio_pci_generic.html"?>
825<title>Generic PCI UIO driver</title>
826 <para>
827 The generic driver is a kernel module named uio_pci_generic.
828 It can work with any device compliant to PCI 2.3 (circa 2002) and
829 any compliant PCI Express device. Using this, you only need to
830 write the userspace driver, removing the need to write
831 a hardware-specific kernel module.
832 </para>
833
834<sect1 id="uio_pci_generic_binding">
835<title>Making the driver recognize the device</title>
836 <para>
837Since the driver does not declare any device ids, it will not get loaded
838automatically and will not automatically bind to any devices, you must load it
839and allocate id to the driver yourself. For example:
840 <programlisting>
841 modprobe uio_pci_generic
842 echo &quot;8086 10f5&quot; &gt; /sys/bus/pci/drivers/uio_pci_generic/new_id
843 </programlisting>
844 </para>
845 <para>
846If there already is a hardware specific kernel driver for your device, the
847generic driver still won't bind to it, in this case if you want to use the
848generic driver (why would you?) you'll have to manually unbind the hardware
849specific driver and bind the generic driver, like this:
850 <programlisting>
851 echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/e1000e/unbind
852 echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/uio_pci_generic/bind
853 </programlisting>
854 </para>
855 <para>
856You can verify that the device has been bound to the driver
857by looking for it in sysfs, for example like the following:
858 <programlisting>
859 ls -l /sys/bus/pci/devices/0000:00:19.0/driver
860 </programlisting>
861Which if successful should print
862 <programlisting>
863 .../0000:00:19.0/driver -&gt; ../../../bus/pci/drivers/uio_pci_generic
864 </programlisting>
865Note that the generic driver will not bind to old PCI 2.2 devices.
866If binding the device failed, run the following command:
867 <programlisting>
868 dmesg
869 </programlisting>
870and look in the output for failure reasons
871 </para>
872</sect1>
873
874<sect1 id="uio_pci_generic_internals">
875<title>Things to know about uio_pci_generic</title>
876 <para>
877Interrupts are handled using the Interrupt Disable bit in the PCI command
878register and Interrupt Status bit in the PCI status register. All devices
879compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should
880support these bits. uio_pci_generic detects this support, and won't bind to
881devices which do not support the Interrupt Disable Bit in the command register.
882 </para>
883 <para>
884On each interrupt, uio_pci_generic sets the Interrupt Disable bit.
885This prevents the device from generating further interrupts
886until the bit is cleared. The userspace driver should clear this
887bit before blocking and waiting for more interrupts.
888 </para>
889</sect1>
890<sect1 id="uio_pci_generic_userspace">
891<title>Writing userspace driver using uio_pci_generic</title>
892 <para>
893Userspace driver can use pci sysfs interface, or the
894libpci libray that wraps it, to talk to the device and to
895re-enable interrupts by writing to the command register.
896 </para>
897</sect1>
898<sect1 id="uio_pci_generic_example">
899<title>Example code using uio_pci_generic</title>
900 <para>
901Here is some sample userspace driver code using uio_pci_generic:
902<programlisting>
903#include &lt;stdlib.h&gt;
904#include &lt;stdio.h&gt;
905#include &lt;unistd.h&gt;
906#include &lt;sys/types.h&gt;
907#include &lt;sys/stat.h&gt;
908#include &lt;fcntl.h&gt;
909#include &lt;errno.h&gt;
910
911int main()
912{
913 int uiofd;
914 int configfd;
915 int err;
916 int i;
917 unsigned icount;
918 unsigned char command_high;
919
920 uiofd = open(&quot;/dev/uio0&quot;, O_RDONLY);
921 if (uiofd &lt; 0) {
922 perror(&quot;uio open:&quot;);
923 return errno;
924 }
925 configfd = open(&quot;/sys/class/uio/uio0/device/config&quot;, O_RDWR);
926 if (uiofd &lt; 0) {
927 perror(&quot;config open:&quot;);
928 return errno;
929 }
930
931 /* Read and cache command value */
932 err = pread(configfd, &amp;command_high, 1, 5);
933 if (err != 1) {
934 perror(&quot;command config read:&quot;);
935 return errno;
936 }
937 command_high &amp;= ~0x4;
938
939 for(i = 0;; ++i) {
940 /* Print out a message, for debugging. */
941 if (i == 0)
942 fprintf(stderr, &quot;Started uio test driver.\n&quot;);
943 else
944 fprintf(stderr, &quot;Interrupts: %d\n&quot;, icount);
945
946 /****************************************/
947 /* Here we got an interrupt from the
948 device. Do something to it. */
949 /****************************************/
950
951 /* Re-enable interrupts. */
952 err = pwrite(configfd, &amp;command_high, 1, 5);
953 if (err != 1) {
954 perror(&quot;config write:&quot;);
955 break;
956 }
957
958 /* Wait for next interrupt. */
959 err = read(uiofd, &amp;icount, 4);
960 if (err != 4) {
961 perror(&quot;uio read:&quot;);
962 break;
963 }
964
965 }
966 return errno;
967}
968
969</programlisting>
970 </para>
971</sect1>
972
973</chapter>
974
812<appendix id="app1"> 975<appendix id="app1">
813<title>Further information</title> 976<title>Further information</title>
814<itemizedlist> 977<itemizedlist>