lkml.org 
[lkml]   [2019]   [Apr]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v4 28/63] Documentation: PCI: convert pci-iov-howto.txt to reST
    Date
    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@gmail.com>
    Acked-by: Bjorn Helgaas <bhelgaas@google.com>
    ---
    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%)

    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@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,
    + };
    --
    2.20.1
    \
     
     \ /
      Last update: 2019-04-23 18:35    [W:3.741 / U:0.412 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site