Documentation: PCI: convert pci-iov-howto.txt to reST

Convert plain text documentation to reStructuredText format and add it to
Sphinx TOC tree.  No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 79d6d75..0d93902 100644 (file)
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -10,3 +10,4 @@ Linux PCI Bus Subsystem
 
    pci
    picebus-howto
+   pci-iov-howto

diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.rst
similarity index 63%
rename from Documentation/PCI/pci-iov-howto.txt
rename to Documentation/PCI/pci-iov-howto.rst
index d2a8415..b9fd003 100644 (file)
--- a/Documentation/PCI/pci-iov-howto.txt
+++ b/Documentation/PCI/pci-iov-howto.rst
@@ -1,14 +1,19 @@
-               PCI Express I/O Virtualization Howto
-               Copyright (C) 2009 Intel Corporation
-                   Yu Zhao <yu.zhao@intel.com>
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
 
-               Update: November 2012
-                       -- sysfs-based SRIOV enable-/disable-ment
-               Donald Dutile <ddutile@redhat.com>
+====================================
+PCI Express I/O Virtualization Howto
+====================================
 
-1. Overview
+:Copyright: |copy| 2009 Intel Corporation
+:Authors: - Yu Zhao <yu.zhao@intel.com>
+          - Donald Dutile <ddutile@redhat.com>
 
-1.1 What is SR-IOV
+Overview
+========
+
+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
@@ -23,9 +28,11 @@ Memory Space, which is used to map its register set. VF device driver
 operates on the register set so it can be functional and appear as a
 real existing PCI device.
 
-2. User Guide
+User Guide
+==========
 
-2.1 How can I enable SR-IOV capability
+How can I enable SR-IOV capability
+----------------------------------
 
 Multiple methods are available for SR-IOV enablement.
 In the first method, the device driver (PF driver) will control the
@@ -43,105 +50,123 @@ 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
+How can I use the Virtual Functions
+-----------------------------------
 
 The VF 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. The VF
 requires device driver that is same as a normal PCI device's.
 
-3. Developer Guide
+Developer Guide
+===============
 
-3.1 SR-IOV API
+SR-IOV API
+----------
 
 To enable SR-IOV capability:
-(a) For the first method, in the driver:
+
+(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:
+
+'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:
+
+(a) For the first method, in the driver::
+
        void pci_disable_sriov(struct pci_dev *dev);
-(b) For the second method, from sysfs:
+
+(b) For the second method, from sysfs::
+
        echo  0 > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
 
 To enable auto probing VFs by a compatible driver on the host, run
 command below before enabling SR-IOV capabilities. This is the
 default behavior.
+::
+
        echo 1 > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
 
 To disable auto probing VFs by a compatible driver on the host, run
 command below before enabling SR-IOV capabilities. Updating this
 entry will not affect VFs which are already probed.
+::
+
        echo  0 > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
 
-3.2 Usage example
+Usage example
+-------------
 
 Following piece of code illustrates the usage of the SR-IOV API.
+::
 
-static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
-{
-       pci_enable_sriov(dev, NR_VIRTFN);
+       static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
+       {
+               pci_enable_sriov(dev, NR_VIRTFN);
 
-       ...
-
-       return 0;
-}
+               ...
 
-static void dev_remove(struct pci_dev *dev)
-{
-       pci_disable_sriov(dev);
+               return 0;
+       }
 
-       ...
-}
+       static void dev_remove(struct pci_dev *dev)
+       {
+               pci_disable_sriov(dev);
 
-static int dev_suspend(struct pci_dev *dev, pm_message_t state)
-{
-       ...
+               ...
+       }
 
-       return 0;
-}
+       static int dev_suspend(struct pci_dev *dev, pm_message_t state)
+       {
+               ...
 
-static int dev_resume(struct pci_dev *dev)
-{
-       ...
+               return 0;
+       }
 
-       return 0;
-}
+       static int dev_resume(struct pci_dev *dev)
+       {
+               ...
 
-static void dev_shutdown(struct pci_dev *dev)
-{
-       ...
-}
+               return 0;
+       }
 
-static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
-{
-       if (numvfs > 0) {
-               ...
-               pci_enable_sriov(dev, numvfs);
+       static void dev_shutdown(struct pci_dev *dev)
+       {
                ...
-               return numvfs;
        }
-       if (numvfs == 0) {
-               ....
-               pci_disable_sriov(dev);
-               ...
-               return 0;
+
+       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,
-       .probe =        dev_probe,
-       .remove =       dev_remove,
-       .suspend =      dev_suspend,
-       .resume =       dev_resume,
-       .shutdown =     dev_shutdown,
-       .sriov_configure = dev_sriov_configure,
-};
+
+       static struct pci_driver dev_driver = {
+               .name =         "SR-IOV Physical Function driver",
+               .id_table =     dev_id_table,
+               .probe =        dev_probe,
+               .remove =       dev_remove,
+               .suspend =      dev_suspend,
+               .resume =       dev_resume,
+               .shutdown =     dev_shutdown,
+               .sriov_configure = dev_sriov_configure,
+       };