From patchwork Thu Jul 16 17:03:46 2009 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: "Michael S. Tsirkin" X-Patchwork-Id: 35928 Received: from vger.kernel.org (vger.kernel.org [209.132.176.167]) by demeter.kernel.org (8.14.2/8.14.2) with ESMTP id n6GH5XmS029461 for ; Thu, 16 Jul 2009 17:05:33 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932793AbZGPREu (ORCPT ); Thu, 16 Jul 2009 13:04:50 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S932781AbZGPREu (ORCPT ); Thu, 16 Jul 2009 13:04:50 -0400 Received: from mx2.redhat.com ([66.187.237.31]:38718 "EHLO mx2.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932757AbZGPREt (ORCPT ); Thu, 16 Jul 2009 13:04:49 -0400 Received: from int-mx2.corp.redhat.com (int-mx2.corp.redhat.com [172.16.27.26]) by mx2.redhat.com (8.13.8/8.13.8) with ESMTP id n6GH4arA013286; Thu, 16 Jul 2009 13:04:36 -0400 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx2.corp.redhat.com (8.13.1/8.13.1) with ESMTP id n6GH4ZfI029249; Thu, 16 Jul 2009 13:04:35 -0400 Received: from redhat.com (dhcp-0-94.tlv.redhat.com [10.35.0.94]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id n6GH4TH8006802; Thu, 16 Jul 2009 13:04:31 -0400 Date: Thu, 16 Jul 2009 20:03:46 +0300 From: "Michael S. Tsirkin" To: Greg KH Cc: "Hans J. Koch" , anthony@codemonkey.ws, avi@redhat.com, kvm@vger.kernel.org, chrisw@redhat.com, linux-kernel@vger.kernel.org Subject: Re: [PATCHv4] uio: add generic driver for PCI 2.3 devices Message-ID: <20090716170346.GA22095@redhat.com> References: <20090715201340.GA12279@redhat.com> <20090715220829.GB31962@suse.de> <20090716140709.GA16321@redhat.com> <20090716151254.GD3642@local> <20090716155208.GA2375@suse.de> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20090716155208.GA2375@suse.de> User-Agent: Mutt/1.5.19 (2009-01-05) X-Scanned-By: MIMEDefang 2.58 on 172.16.27.26 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org On Thu, Jul 16, 2009 at 08:52:08AM -0700, Greg KH wrote: > On Thu, Jul 16, 2009 at 05:12:55PM +0200, Hans J. Koch wrote: > > On Thu, Jul 16, 2009 at 05:07:10PM +0300, Michael S. Tsirkin wrote: > > > On Wed, Jul 15, 2009 at 03:08:29PM -0700, Greg KH wrote: > > > > How about moving that documentation into a place that people will notice > > > > it, like the rest of the UIO documentation? > > > > > > Greg, > > > > > > would it make more sense to add this to > > > Documentation/DocBook/uio-howto.xml, or to create > > > Documentation/uio_pci_generic.txt ? > > > > Hi Michael, > > I'd prefer to have it in uio-howto.xml so that people only have to look in > > one place. In does not have to be very detailled, just a short explanation > > what this driver is all about and a short example how to use it. > > I agree, that would be the best place for it. > > thanks, > > greg k-h OK. Could you take a look at the following please? --> doc: Document uio_pci_generic Signed-off-by: Michael S. Tsirkin --- -- To unsubscribe from this list: send the line "unsubscribe kvm" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 8f6e3b2..4d4ce0e 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -25,6 +25,10 @@ 2006-2008 Hans-Jürgen Koch. + + 2009 + Red Hat Inc, Michael S. Tsirkin (mst@redhat.com) + @@ -42,6 +46,13 @@ GPL version 2. + 0.9 + 2009-07-16 + mst + Added generic pci driver + + + 0.8 2008-12-24 hjk @@ -809,6 +820,158 @@ framework to set up sysfs files for this region. Simply leave it alone. + + +Generic PCI UIO driver + + The generic driver is a kernel module named uio_pci_generic. + It can work with any device compliant to PCI 2.3 (circa 2002) and + any compliant PCI Express device. Using this, you only need to + write the userspace driver, removing the need to write + a hardware-specific kernel module. + + + +Making the driver recognize the device + +Since the driver does not declare any device ids, it will not get loaded +automatically and will not automatically bind to any devices, you must load it +and allocate id to the driver yourself. For example: + + modprobe uio_pci_generic + echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id + + + +If there already is a hardware specific kernel driver for your device, the +generic driver still won't bind to it, in this case if you want to use the +generic driver (why would you?) you'll have to manually unbind the hardware +specific driver and bind the generic driver, like this: + + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind + + + +You can verify that the device has been bound to the driver +by looking for it in sysfs, for example like the following: + + ls -l /sys/bus/pci/devices/0000:00:19.0/driver + +Which if successful should print + + .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic + +Note that the generic driver will not bind to old PCI 2.2 devices. +If binding the device failed, run the following command: + + dmesg + +and look in the output for failure reasons + + + + +Things to know about uio_pci_generic + +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. uio_pci_generic detects this support, and won't bind to +devices which do not support the Interrupt Disable Bit in the command register. + + +On each interrupt, uio_pci_generic sets the Interrupt Disable bit. +This prevents the device from generating further interrupts +until the bit is cleared. The userspace driver should clear this +bit before blocking and waiting for more interrupts. + + + +Writing userspace driver using uio_pci_generic + +Userspace driver can use pci sysfs interface, or the +libpci libray that wraps it, to talk to the device and to +re-enable interrupts by writing to the command register. + + + +Example code using uio_pci_generic + +Here is some sample userspace driver code using uio_pci_generic: + +#include <stdlib.h> +#include <stdio.h> +#include <unistd.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <errno.h> + +int main() +{ + int uiofd; + int configfd; + int err; + int i; + unsigned icount; + unsigned char command_high; + + uiofd = open("/dev/uio0", O_RDONLY); + if (uiofd < 0) { + perror("uio open:"); + return errno; + } + configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); + if (uiofd < 0) { + perror("config open:"); + return errno; + } + + /* Read and cache command value */ + err = pread(configfd, &command_high, 1, 5); + if (err != 1) { + perror("command config read:"); + return errno; + } + command_high &= ~0x4; + + for(i = 0;; ++i) { + /* Print out a message, for debugging. */ + if (i == 0) + fprintf(stderr, "Started uio test driver.\n"); + else + fprintf(stderr, "Interrupts: %d\n", icount); + + /****************************************/ + /* Here we got an interrupt from the + device. Do something to it. */ + /****************************************/ + + /* Re-enable interrupts. */ + err = pwrite(configfd, &command_high, 1, 5); + if (err != 1) { + perror("config write:"); + break; + } + + /* Wait for next interrupt. */ + err = read(uiofd, &icount, 4); + if (err != 4) { + perror("uio read:"); + break; + } + + } + return errno; +} + + + + + + + Further information