WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-devel

[Xen-devel] SR-IOV: patches are available for Linux kernel [4/4]

To: <kvm@xxxxxxxxxxxxxxx>, <xen-devel@xxxxxxxxxxxxxxxxxxx>, <virtualization@xxxxxxxxxxxxxxxxxxxxxxxxxx>
Subject: [Xen-devel] SR-IOV: patches are available for Linux kernel [4/4]
From: "Zhao, Yu" <yu.zhao@xxxxxxxxx>
Date: Tue, 12 Aug 2008 16:46:39 +0800
Cc:
Delivery-date: Tue, 12 Aug 2008 01:47:05 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
Thread-index: Acj8VewGsx+WRAACS0Sz56Au4wAirAAAAgpwAABgcQAAAAfXUAAADJUw
Thread-topic: SR-IOV: patches are available for Linux kernel [4/4]
[PATCH 4/4] PCI: document SR-IOV

SR-IOV Documentation.

Signed-off-by: Yu Zhao <yu.zhao@xxxxxxxxx>
Signed-off-by:  Eddie Dong <eddie.dong@xxxxxxxxx>

---
 Documentation/ABI/testing/sysfs-bus-pci |   13 ++
 Documentation/PCI/00-INDEX              |    2 
 Documentation/PCI/pci-iov-howto.txt     |  170 +++++++++++++++++++++++++++++++
 3 files changed, 185 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-pci 
b/Documentation/ABI/testing/sysfs-bus-pci
index ceddcff..9ada27b 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -9,3 +9,16 @@ Description:
                that some devices may have malformatted data.  If the
                underlying VPD has a writable section then the
                corresponding section of this file will be writable.
+
+What:          /sys/bus/pci/devices/.../iov
+Date:          August 2008
+Contact:       Yu Zhao <yu.zhao@xxxxxxxxx>
+Description:
+               This file will appear when SR-IOV capability is enabled
+               by the device driver if supported. It holds number of
+               available Virtual Functions and Bus, Device, Function
+               number and status of these Virtual Functions that belong
+               to this device (Physical Function). This file can be
+               written using same format as what can be read out, to
+               change the number of available Virtual Functions and to
+               enable or disable a Virtual Functions.
diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index 49f4394..8f8ee17 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -10,3 +10,5 @@ pci.txt
        - info on the PCI subsystem for device driver authors
 pcieaer-howto.txt
        - the PCI Express Advanced Error Reporting Driver Guide HOWTO
+pci-iov-howto.txt
+       - PCI Express Single Root I/O Virtualization HOWTO
diff --git a/Documentation/PCI/pci-iov-howto.txt 
b/Documentation/PCI/pci-iov-howto.txt
new file mode 100644
index 0000000..2d7ae64
--- /dev/null
+++ b/Documentation/PCI/pci-iov-howto.txt
@@ -0,0 +1,170 @@
+               PCI Express Single Root I/O Virtualization HOWTO
+                       Copyright (C) 2008 Intel Corporation
+                           Yu Zhao <yu.zhao@xxxxxxxxx>
+
+
+1. Overview
+
+1.1 What is SR-IOV
+
+SR-IOV is PCI Express Extended Capability, which makes one physical device
+becomes multiple virtual devices. The physical device is referred as Physical
+Function while the virtual devices are refereed as Virtual Functions.
+Allocation of Virtual Functions can be dynamically controlled by Physical
+Function via registers encapsulated in the capability. By default, this
+feature is not enabled and the Physical Function behaves as traditional PCIe
+device. Once it's turned on, each Virtual Function's PCI configuration space
+can be accessed by its own Bus, Device and Function Number (Routing ID). And
+each Virtual Function also has PCI Memory Space, which is used to map its
+register set. Virtual Function device driver operates on the register set so
+it can be functional and appear as a real existing PCI device.
+
+1.2 What is ARI
+
+Alternative Routing-ID Interpretation allows a PCI Express Endpoint to use
+its device number field as part of function number. Traditionally, an
+Endpoint can only have 8 functions, and the device number of all Endpoints
+is zero. With ARI enabled, an Endpoint can have up to 256 functions. ARI is
+managed via a ARI Forwarding bit in the Device Capabilities 2 register of
+the PCI Express Capability on the Root Port or the Downstream Port and a new
+ARI Capability on the Endpoint.
+
+
+2. User Guide
+
+2.1 How can I manage SR-IOV
+
+SR-IOV can be managed by reading or writing /sys/bus/pci/devices/.../iov.
+Legal operations on this file include:
+       - Read: will get number of available VFs and a list of them.
+       - Write: bb:dd.f={1|0} will enable or disable a VF.
+       - Write: NumVFs=N will change number of available VFs.
+
+2.2 How can I use Virtual Functions
+
+Virtual Functions can be treated as hot-plugged PCI devices in the kernel,
+so they should be able to work in the same way as real PCI devices.
+NOTE: Virtual Function device driver must be loaded to make it work.
+
+
+3. Developer Guide
+
+3.1 SR-IOV APIs
+
+To enable SR-IOV, Physical Function device driver needs to call:
+       int pci_iov_enable(struct pci_dev *dev, int nvfs,
+                               int (*cb)(struct pci_dev *, int, int))
+NOTE: this function sleeps 2 seconds waiting on hardware transaction
+completion according to SR-IOV specification.
+
+To disable SR-IOV, Physical Function device driver needs to call:
+       void pci_iov_disable(struct pci_dev *dev)
+NOTE: this function sleeps 1 second waiting on hardware transaction
+completion according to SR-IOV specification.
+
+Following function can be used to query maximum number of Virtual Functions
+that a Physical Function can support:
+       int pci_iov_max_virtfn(struct pci_dev *dev)
+
+Following function can be used to retrieve parameter of a Virtual Function:
+       const char *pci_iov_virtfn_param(struct pci_dev *dev, int vfid)
+
+3.2 Usage example
+
+Following piece of codes illustrates the usage of APIs above.
+
+static int callback(struct pci_dev *dev, int event, int arg)
+{
+       int err;
+       const char *param;
+
+       switch (event) {
+       case PCI_IOV_VF_ENA:    /* request to enable a VF */
+               param = pci_iov_virtfn_param(dev, arg);
+               ...
+               break;
+       case PCI_IOV_VF_DIS:    /* a VF is disabled */
+               /*
+                * reclaim hardware resource if needed
+                */
+               break;
+       case PCI_IOV_VF_PAR:    /* VF parameter changed */
+               param = pci_iov_virtfn_param(dev, arg);
+               ...
+               break;
+       case PCI_IOV_VF_NUM:    /* request to change NumVFs */
+               /*
+                * adjust hardware resources if needed
+                * NOTE: arg is the new requested NumVFs
+                */
+               break;
+       case PCI_IOV_VF_ERR:    /* error occurred */
+               /*
+                * error handling
+                * NOTE: arg is the error code
+                */
+               break;
+       default:
+               return -EINVAL;
+       }
+
+       return err;
+}
+
+static int __devinit dev_probe(struct pci_dev *dev,
+                               const struct pci_device_id *id)
+{
+       int err, nvfs;
+
+       ...
+
+       nvfs = pci_iov_max_virtfn(dev);
+       if (nvfs <= 0)
+               return -ENODEV;
+
+       err = pci_iov_enable(dev, nvfs, callback);
+       if (err)
+               return err;
+
+       ...
+}
+
+static void __devexit dev_remove(struct pci_dev *dev)
+{
+       ...
+
+       pci_iov_disable(dev);
+
+       ...
+}
+
+#ifdef CONFIG_PM
+static int dev_suspend(struct pci_dev *dev, pm_message_t state)
+{
+       ...
+
+       pci_iov_disable(dev);
+
+       ...
+}
+
+static int dev_resume(struct pci_dev *dev)
+{
+       ...
+
+       pci_iov_enable(dev, nvfs, callback);
+
+       ...
+}
+#endif
+
+static struct pci_driver dev_driver = {
+       .name =         "SR-IOV PF driver",
+       .id_table =     dev_id_table,
+       .probe =        dev_probe,
+       .remove =       __devexit_p(dev_remove),
+#ifdef CONFIG_PM
+       .suspend =      dev_suspend,
+       .resume =       dev_resume,
+#endif
+};
-- 
1.4.2.1


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel

<Prev in Thread] Current Thread [Next in Thread>