[PATCH 04/12] pci doc: convert PCI/pci-iov-howto.txt to rst format

From: Changbin Du
Date: Fri Mar 29 2019 - 12:04:52 EST

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

Signed-off-by: Changbin Du <changbin.du@xxxxxxxxx>
---
Documentation/PCI/index.rst | 1 +
.../{pci-iov-howto.txt => pci-iov-howto.rst} | 144 ++++++++++--------
2 files changed, 85 insertions(+), 60 deletions(-)
rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (65%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 58ce08f14f33..751cd8f23c62 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -9,3 +9,4 @@ Linux PCI Bus Subsystem

pci
PCIEBUS-HOWTO
+ pci-iov-howto
diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.rst
similarity index 65%
rename from Documentation/PCI/pci-iov-howto.txt
rename to Documentation/PCI/pci-iov-howto.rst
index d2a84151e99c..068e2c93e828 100644
--- a/Documentation/PCI/pci-iov-howto.txt
+++ b/Documentation/PCI/pci-iov-howto.rst
@@ -1,14 +1,20 @@
- PCI Express I/O Virtualization Howto
- Copyright (C) 2009 Intel Corporation
- Yu Zhao <yu.zhao@xxxxxxxxx>
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>

- Update: November 2012
- -- sysfs-based SRIOV enable-/disable-ment
- Donald Dutile <ddutile@xxxxxxxxxx>
+====================================
+PCI Express I/O Virtualization Howto
+====================================
+
+:Copyright: |copy| 2009 Intel Corporation
+:Authors: - Yu Zhao <yu.zhao@xxxxxxxxx>
+ - Update: November 2012, sysfs-based SRIOV enable-/disable-ment,
+ Donald Dutile <ddutile@xxxxxxxxxx>

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
@@ -24,8 +30,10 @@ operates on the register set so it can be functional and appear as a
real existing PCI device.

2. User Guide
+=============

2.1 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
@@ -44,104 +52,120 @@ numvfs <= totalvfs.
The second method is the recommended method for new/future VF devices.

2.2 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
+==================

3.1 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
+-----------------

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,
+ };
--
2.20.1