Merge tag 'for-3.8' of git://git.kernel.org/pub/scm/linux/kernel/git/helgaas/pci

[can-eth-gw-linux.git] / Documentation / PCI / pci-iov-howto.txt

diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.txt
index fc73ef5d65b81366360d9d213bc2d675875ad4b7..cfaca7e6989346246e3205c52a353ea960b50ce5 100644 (file)
--- a/Documentation/PCI/pci-iov-howto.txt
+++ b/Documentation/PCI/pci-iov-howto.txt
@@ -2,6 +2,9 @@
                Copyright (C) 2009 Intel Corporation
                    Yu Zhao <yu.zhao@intel.com>
 
+               Update: November 2012
+                       -- sysfs-based SRIOV enable-/disable-ment
+               Donald Dutile <ddutile@redhat.com>
 
 1. Overview
 
@@ -24,10 +27,21 @@ real existing PCI device.
 
 2.1 How can I enable SR-IOV capability
 
-The device driver (PF driver) will control the enabling and disabling
-of the capability via API provided by SR-IOV core. If the hardware
-has SR-IOV capability, loading its PF driver would enable it and all
-VFs associated with the PF.
+Multiple methods are available for SR-IOV enablement.
+In the first method, the device driver (PF driver) will control the
+enabling and disabling of the capability via API provided by SR-IOV core.
+If the hardware has SR-IOV capability, loading its PF driver would
+enable it and all VFs associated with the PF.  Some PF drivers require
+a module parameter to be set to determine the number of VFs to enable.
+In the second method, a write to the sysfs file sriov_numvfs will
+enable and disable the VFs associated with a PCIe PF.  This method
+enables per-PF, VF enable/disable values versus the first method,
+which applies to all PFs of the same device.  Additionally, the
+PCI SRIOV core support ensures that enable/disable operations are
+valid to reduce duplication in multiple drivers for the same
+checks, e.g., check numvfs == 0 if enabling VFs, ensure
+numvfs <= totalvfs.
+The second method is the recommended method for new/future VF devices.
 
 2.2 How can I use the Virtual Functions
 
@@ -40,13 +54,22 @@ requires device driver that is same as a normal PCI device's.
 3.1 SR-IOV API
 
 To enable SR-IOV capability:
+(a) For the first method, in the driver:
        int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
        'nr_virtfn' is number of VFs to be enabled.
+(b) For the second method, from sysfs:
+       echo 'nr_virtfn' > \
+        /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
 
 To disable SR-IOV capability:
+(a) For the first method, in the driver:
        void pci_disable_sriov(struct pci_dev *dev);
+(b) For the second method, from sysfs:
+       echo  0 > \
+        /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
 
 To notify SR-IOV core of Virtual Function Migration:
+(a) In the driver:
        irqreturn_t pci_sriov_migration(struct pci_dev *dev);
 
 3.2 Usage example
@@ -88,6 +111,22 @@ static void dev_shutdown(struct pci_dev *dev)
        ...
 }
 
+static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
+{
+       if (numvfs > 0) {
+               ...
+               pci_enable_sriov(dev, numvfs);
+               ...
+               return numvfs;
+       }
+       if (numvfs == 0) {
+               ....
+               pci_disable_sriov(dev);
+               ...
+               return 0;
+       }
+}
+
 static struct pci_driver dev_driver = {
        .name =         "SR-IOV Physical Function driver",
        .id_table =     dev_id_table,
@@ -96,4 +135,5 @@ static struct pci_driver dev_driver = {
        .suspend =      dev_suspend,
        .resume =       dev_resume,
        .shutdown =     dev_shutdown,
+       .sriov_configure = dev_sriov_configure,
 };