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] [PATCH 4/4 v2] PCI: document the change

To: "Jesse Barnes" <jbarnes@xxxxxxxxxxxxxxxx>, <linux-pci@xxxxxxxxxxxxxxx>
Subject: [Xen-devel] [PATCH 4/4 v2] PCI: document the change
From: "Zhao, Yu" <yu.zhao@xxxxxxxxx>
Date: Mon, 1 Sep 2008 19:21:06 +0800
Cc: Randy Dunlap <randy.dunlap@xxxxxxxxxx>, xen-devel@xxxxxxxxxxxxxxxxxxx, Grant Grundler <grundler@xxxxxxxxxxxxxxxx>, kvm@xxxxxxxxxxxxxxx, Matthew Wilcox <matthew@xxxxxx>, Greg KH <greg@xxxxxxxxx>, linux-kernel@xxxxxxxxxxxxxxx, virtualization@xxxxxxxxxxxxxxxxxxxxxxxxxx
Delivery-date: Mon, 01 Sep 2008 04:23:01 -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: AckMJNNs4wGff54MSr+UTWjd37C7Zw==
Thread-topic: [PATCH 4/4 v2] PCI: document the change
Complete the hotplug ABI document, and add SR-IOV HOWTO.

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

---
 Documentation/ABI/testing/sysfs-bus-pci |   67 ++++++++++++
 Documentation/DocBook/kernel-api.tmpl   |    3 +
 Documentation/PCI/pci-iov-howto.txt     |  177 +++++++++++++++++++++++++++++++
 3 files changed, 247 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/PCI/pci-iov-howto.txt

diff --git a/Documentation/ABI/testing/sysfs-bus-pci 
b/Documentation/ABI/testing/sysfs-bus-pci
index ceddcff..374e87b 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -9,3 +9,70 @@ 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/slots/.../power
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It indicates power status of a slot, and could be written
+               to enable or disable the slot.
+
+What:          /sys/bus/pci/slots/.../attention
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It indicates attention LED status of a slot, and could
+               be written to set the LED status.
+
+What:          /sys/bus/pci/slots/.../latch
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It indicates latch status of a slot.
+
+What:          /sys/bus/pci/slots/.../adapter
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It indicates presence of the adapter.
+
+What:          /sys/bus/pci/slots/.../max_bus_speed
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It indicates max bus speed of a slot.
+
+What:          /sys/bus/pci/slots/.../cur_bus_speed
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It indicates current bus speed of a slot.
+
+What:          /sys/bus/pci/slots/.../test
+Date:          Unknown
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It triggers adapter hardware test upon writing.
+
+What:          /sys/bus/pci/slots/.../param
+Date:          August 2008
+Contact:       linux-pci@xxxxxxxxxxxxxxx
+Description:
+               This file will appear when PCI hotplug is enabled and
+               the hotplug driver supports this operation.
+               It holds device specific parameters, and could be written
+               to configure the adapter in a slot.
diff --git a/Documentation/DocBook/kernel-api.tmpl 
b/Documentation/DocBook/kernel-api.tmpl
index b7b1482..36273af 100644
--- a/Documentation/DocBook/kernel-api.tmpl
+++ b/Documentation/DocBook/kernel-api.tmpl
@@ -239,6 +239,7 @@ X!Ekernel/module.c
      </sect1>
 
      <sect1><title>PCI Support Library</title>
+!Iinclude/linux/pci.h
 !Edrivers/pci/pci.c
 !Edrivers/pci/pci-driver.c
 !Edrivers/pci/remove.c
@@ -251,6 +252,8 @@ X!Edrivers/pci/hotplug.c
 -->
 !Edrivers/pci/probe.c
 !Edrivers/pci/rom.c
+!Edrivers/pci/ari.c
+!Edrivers/pci/iov.c
      </sect1>
      <sect1><title>PCI Hotplug Support Library</title>
 !Edrivers/pci/hotplug/pci_hotplug_core.c
diff --git a/Documentation/PCI/pci-iov-howto.txt 
b/Documentation/PCI/pci-iov-howto.txt
new file mode 100644
index 0000000..147e80f
--- /dev/null
+++ b/Documentation/PCI/pci-iov-howto.txt
@@ -0,0 +1,177 @@
+               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
+
+Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
+capability which makes one physical device appear as multiple virtual
+devices. The physical device is referred to as Physical Function while
+the virtual devices are referred to 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 (ARI) 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 by using device number in conjunction with function number to
+indicate a function in the device. This is almost transparent to the Linux
+kernel because the Linux kernel still can use 8-bit bus number field plus
+8-bit devfn number field to locate a function. ARI is managed via the 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
+
+If a device supports SR-IOV, then there should be some entires under
+/sys/bus/pci/slots/. The names of the entires are XXXX:BB:DD.F-iov-NNNN,
+where the first part (XXXX:BB:DD.F) is the domain, bus, device and function
+number of the device, and the third part (NNNN) is the index of a Virtual
+Function. There are three files under the entry: power, param and address.
+       - Writing 1 to the "power" will enable the Virtual Function,
+       and 0 will disable the Virtual Function; Reading it will get
+       status of the Virtual Function.
+       - Reading the "address" will get the bus, device and function
+       number of the Virtual Function.
+       - The "param" is the device specific parameters which may be
+       used by the Physical or Virtual Functions drivers.
+
+2.2 How can I use Virtual Functions
+
+Virtual Functions is 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 (*cb)(struct pci_dev *, int, int, char *))
+The pointer to the callback function could be NULL if Physical Function
+wants to ignore the events.
+
+To disable SR-IOV, Physical Function device driver needs to call:
+       void pci_iov_disable(struct pci_dev *dev)
+
+NOTE: these two functions sleeps 1 second waiting on hardware transaction
+completion according to SR-IOV specification.
+
+3.2 Usage example
+
+Following piece of code illustrates the usage of APIs above.
+
+static int callback(struct pci_dev *dev, int event, int arg, char *param)
+{
+       int err;
+
+       switch (event) {
+       case PCI_IOV_VF_ENABLE:
+               /*
+                * request to enable a Virtual Function, setup hardware
+                * resource to this Virtual Function if needed.
+                */
+               break;
+       case PCI_IOV_VF_DISABLE:
+               /*
+                * a Virtual Function has been disabled, reclaim hardware
+                * resource if needed.
+                */
+               break;
+       case PCI_IOV_VF_SETPARAM:
+               /*
+                * parameter of a Virtual Function has been changed, take
+                * corresponding actions if needed.
+                */
+               break;
+       case PCI_IOV_VF_GETPARAM:
+               /*
+                * return the parameters of a Virtual Function if any.
+                */
+               break;
+       default:
+               return -EINVAL;
+       }
+
+       return err;
+}
+
+static int __devinit dev_probe(struct pci_dev *dev,
+                               const struct pci_device_id *id)
+{
+       int err;
+
+       ...
+
+       err = pci_iov_enable(dev, callback);
+       if (err)
+               return err;
+
+       ...
+}
+
+static void __devexit dev_remove(struct pci_dev *dev)
+{
+       ...
+
+       pci_iov_disable(dev);
+
+       ...
+}
+
+#ifdef CONFIG_PM
+/*
+ * If the device supports the power management, then the SR-IOV
+ * may be disabled before the adapter goes to sleep, because
+ * Virtual Functions may not work when the adapter is in the\
+ * power-saving mode.
+ * The SR-IOV can be enabled again after the adapter wakes up.
+ */
+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.5.6.4


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

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