Em Wed, 24 Apr 2019 00:28:57 +0800
Changbin Du <changbin.du@xxxxxxxxx> escreveu:
> 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>
> Acked-by: Bjorn Helgaas <bhelgaas@xxxxxxxxxx>
> ---
> Documentation/PCI/index.rst | 1 +
> .../{pci-iov-howto.txt => pci-iov-howto.rst} | 161 ++++++++++--------
> 2 files changed, 94 insertions(+), 68 deletions(-)
> rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (63%)
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>
>
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index 452723318405..e1c19962a7f8 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -10,3 +10,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 63%
> rename from Documentation/PCI/pci-iov-howto.txt
> rename to Documentation/PCI/pci-iov-howto.rst
> index d2a84151e99c..b9fd003206f1 100644
> --- 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@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
> +====================================
>
> -1. Overview
> +:Copyright: |copy| 2009 Intel Corporation
> +:Authors: - Yu Zhao <yu.zhao@xxxxxxxxx>
> + - Donald Dutile <ddutile@xxxxxxxxxx>
>
> -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,
> + };
Thanks,
Mauro
