diff mbox series

[v4,28/63] Documentation: PCI: convert pci-iov-howto.txt to reST

Message ID 20190423162932.21428-29-changbin.du@gmail.com (mailing list archive)
State New, archived
Delegated to: Bjorn Helgaas
Headers show
Series Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand

Commit Message

Changbin Du April 23, 2019, 4:28 p.m. UTC
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%)

Comments

Mauro Carvalho Chehab April 24, 2019, 3:25 p.m. UTC | #1
Em Wed, 24 Apr 2019 00:28:57 +0800
Changbin Du <changbin.du@gmail.com> 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@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%)

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

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



Thanks,
Mauro
diff mbox series

Patch

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