diff mbox series

[v4,27/63] Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST

Message ID 20190423162932.21428-28-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>
---
 .../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst}  | 140 ++++++++++--------
 Documentation/PCI/index.rst                   |   1 +
 2 files changed, 82 insertions(+), 59 deletions(-)
 rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (70%)

Comments

Mauro Carvalho Chehab April 24, 2019, 3:23 p.m. UTC | #1
Em Wed, 24 Apr 2019 00:28:56 +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>
> ---
>  .../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst}  | 140 ++++++++++--------
>  Documentation/PCI/index.rst                   |   1 +
>  2 files changed, 82 insertions(+), 59 deletions(-)
>  rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (70%)

Names in lowercase after rename, please.

For the changes itself at the txt file:

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

> 
> diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/PCIEBUS-HOWTO.rst
> similarity index 70%
> rename from Documentation/PCI/PCIEBUS-HOWTO.txt
> rename to Documentation/PCI/PCIEBUS-HOWTO.rst
> index 15f0bb3b5045..f882ff62c51f 100644
> --- a/Documentation/PCI/PCIEBUS-HOWTO.txt
> +++ b/Documentation/PCI/PCIEBUS-HOWTO.rst
> @@ -1,16 +1,23 @@
> -		The PCI Express Port Bus Driver Guide HOWTO
> -	Tom L Nguyen tom.l.nguyen@intel.com
> -			11/03/2004
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
>  
> -1. About this guide
> +===========================================
> +The PCI Express Port Bus Driver Guide HOWTO
> +===========================================
> +
> +:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004
> +:Copyright: |copy| 2004 Intel Corporation
> +
> +About this guide
> +================
>  
>  This guide describes the basics of the PCI Express Port Bus driver
>  and provides information on how to enable the service drivers to
>  register/unregister with the PCI Express Port Bus Driver.
>  
> -2. Copyright 2004 Intel Corporation
>  
> -3. What is the PCI Express Port Bus Driver
> +What is the PCI Express Port Bus Driver
> +=======================================
>  
>  A PCI Express Port is a logical PCI-PCI Bridge structure. There
>  are two types of PCI Express Port: the Root Port and the Switch
> @@ -30,7 +37,8 @@ support (AER), and virtual channel support (VC). These services may
>  be handled by a single complex driver or be individually distributed
>  and handled by corresponding service drivers.
>  
> -4. Why use the PCI Express Port Bus Driver?
> +Why use the PCI Express Port Bus Driver?
> +========================================
>  
>  In existing Linux kernels, the Linux Device Driver Model allows a
>  physical device to be handled by only a single driver. The PCI
> @@ -51,28 +59,31 @@ PCI Express Ports and distributes all provided service requests
>  to the corresponding service drivers as required. Some key
>  advantages of using the PCI Express Port Bus driver are listed below:
>  
> -	- Allow multiple service drivers to run simultaneously on
> -	  a PCI-PCI Bridge Port device.
> +  - Allow multiple service drivers to run simultaneously on
> +    a PCI-PCI Bridge Port device.
>  
> -	- Allow service drivers implemented in an independent
> -	  staged approach.
> +  - Allow service drivers implemented in an independent
> +    staged approach.
>  
> -	- Allow one service driver to run on multiple PCI-PCI Bridge
> -	  Port devices.
> +  - Allow one service driver to run on multiple PCI-PCI Bridge
> +    Port devices.
>  
> -	- Manage and distribute resources of a PCI-PCI Bridge Port
> -	  device to requested service drivers.
> +  - Manage and distribute resources of a PCI-PCI Bridge Port
> +    device to requested service drivers.
>  
> -5. Configuring the PCI Express Port Bus Driver vs. Service Drivers
> +Configuring the PCI Express Port Bus Driver vs. Service Drivers
> +===============================================================
>  
> -5.1 Including the PCI Express Port Bus Driver Support into the Kernel
> +Including the PCI Express Port Bus Driver Support into the Kernel
> +-----------------------------------------------------------------
>  
>  Including the PCI Express Port Bus driver depends on whether the PCI
>  Express support is included in the kernel config. The kernel will
>  automatically include the PCI Express Port Bus driver as a kernel
>  driver when the PCI Express support is enabled in the kernel.
>  
> -5.2 Enabling Service Driver Support
> +Enabling Service Driver Support
> +-------------------------------
>  
>  PCI device drivers are implemented based on Linux Device Driver Model.
>  All service drivers are PCI device drivers. As discussed above, it is
> @@ -89,9 +100,11 @@ header file /include/linux/pcieport_if.h, before calling these APIs.
>  Failure to do so will result an identity mismatch, which prevents
>  the PCI Express Port Bus driver from loading a service driver.
>  
> -5.2.1 pcie_port_service_register
> +pcie_port_service_register
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +::
>  
> -int pcie_port_service_register(struct pcie_port_service_driver *new)
> +  int pcie_port_service_register(struct pcie_port_service_driver *new)
>  
>  This API replaces the Linux Driver Model's pci_register_driver API. A
>  service driver should always calls pcie_port_service_register at
> @@ -99,69 +112,76 @@ module init. Note that after service driver being loaded, calls
>  such as pci_enable_device(dev) and pci_set_master(dev) are no longer
>  necessary since these calls are executed by the PCI Port Bus driver.
>  
> -5.2.2 pcie_port_service_unregister
> +pcie_port_service_unregister
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +::
>  
> -void pcie_port_service_unregister(struct pcie_port_service_driver *new)
> +  void pcie_port_service_unregister(struct pcie_port_service_driver *new)
>  
>  pcie_port_service_unregister replaces the Linux Driver Model's
>  pci_unregister_driver. It's always called by service driver when a
>  module exits.
>  
> -5.2.3 Sample Code
> +Sample Code
> +~~~~~~~~~~~
>  
>  Below is sample service driver code to initialize the port service
>  driver data structure.
> +::
>  
> -static struct pcie_port_service_id service_id[] = { {
> -	.vendor = PCI_ANY_ID,
> -	.device = PCI_ANY_ID,
> -	.port_type = PCIE_RC_PORT,
> -	.service_type = PCIE_PORT_SERVICE_AER,
> -	}, { /* end: all zeroes */ }
> -};
> +  static struct pcie_port_service_id service_id[] = { {
> +    .vendor = PCI_ANY_ID,
> +    .device = PCI_ANY_ID,
> +    .port_type = PCIE_RC_PORT,
> +    .service_type = PCIE_PORT_SERVICE_AER,
> +    }, { /* end: all zeroes */ }
> +  };
>  
> -static struct pcie_port_service_driver root_aerdrv = {
> -	.name		= (char *)device_name,
> -	.id_table	= &service_id[0],
> +  static struct pcie_port_service_driver root_aerdrv = {
> +    .name		= (char *)device_name,
> +    .id_table	= &service_id[0],
>  
> -	.probe		= aerdrv_load,
> -	.remove		= aerdrv_unload,
> +    .probe		= aerdrv_load,
> +    .remove		= aerdrv_unload,
>  
> -	.suspend	= aerdrv_suspend,
> -	.resume		= aerdrv_resume,
> -};
> +    .suspend	= aerdrv_suspend,
> +    .resume		= aerdrv_resume,
> +  };
>  
>  Below is a sample code for registering/unregistering a service
>  driver.
> +::
>  
> -static int __init aerdrv_service_init(void)
> -{
> -	int retval = 0;
> +  static int __init aerdrv_service_init(void)
> +  {
> +    int retval = 0;
>  
> -	retval = pcie_port_service_register(&root_aerdrv);
> -	if (!retval) {
> -		/*
> -		 * FIX ME
> -		 */
> -	}
> -	return retval;
> -}
> +    retval = pcie_port_service_register(&root_aerdrv);
> +    if (!retval) {
> +      /*
> +      * FIX ME
> +      */
> +    }
> +    return retval;
> +  }
>  
> -static void __exit aerdrv_service_exit(void)
> -{
> -	pcie_port_service_unregister(&root_aerdrv);
> -}
> +  static void __exit aerdrv_service_exit(void)
> +  {
> +    pcie_port_service_unregister(&root_aerdrv);
> +  }
>  
> -module_init(aerdrv_service_init);
> -module_exit(aerdrv_service_exit);
> +  module_init(aerdrv_service_init);
> +  module_exit(aerdrv_service_exit);
>  
> -6. Possible Resource Conflicts
> +Possible Resource Conflicts
> +===========================
>  
>  Since all service drivers of a PCI-PCI Bridge Port device are
>  allowed to run simultaneously, below lists a few of possible resource
>  conflicts with proposed solutions.
>  
> -6.1 MSI and MSI-X Vector Resource
> +MSI and MSI-X Vector Resource
> +-----------------------------
>  
>  Once MSI or MSI-X interrupts are enabled on a device, it stays in this
>  mode until they are disabled again.  Since service drivers of the same
> @@ -179,7 +199,8 @@ driver. Service drivers should use (struct pcie_device*)dev->irq to
>  call request_irq/free_irq. In addition, the interrupt mode is stored
>  in the field interrupt_mode of struct pcie_device.
>  
> -6.3 PCI Memory/IO Mapped Regions
> +PCI Memory/IO Mapped Regions
> +----------------------------
>  
>  Service drivers for PCI Express Power Management (PME), Advanced
>  Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
> @@ -188,7 +209,8 @@ registers accessed are independent of each other. This patch assumes
>  that all service drivers will be well behaved and not overwrite
>  other service driver's configuration settings.
>  
> -6.4 PCI Config Registers
> +PCI Config Registers
> +--------------------
>  
>  Each service driver runs its PCI config operations on its own
>  capability structure except the PCI Express capability structure, in
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index 7babf43709b0..452723318405 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -9,3 +9,4 @@ Linux PCI Bus Subsystem
>     :numbered:
>  
>     pci
> +   PCIEBUS-HOWTO



Thanks,
Mauro
diff mbox series

Patch

diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/PCIEBUS-HOWTO.rst
similarity index 70%
rename from Documentation/PCI/PCIEBUS-HOWTO.txt
rename to Documentation/PCI/PCIEBUS-HOWTO.rst
index 15f0bb3b5045..f882ff62c51f 100644
--- a/Documentation/PCI/PCIEBUS-HOWTO.txt
+++ b/Documentation/PCI/PCIEBUS-HOWTO.rst
@@ -1,16 +1,23 @@ 
-		The PCI Express Port Bus Driver Guide HOWTO
-	Tom L Nguyen tom.l.nguyen@intel.com
-			11/03/2004
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
 
-1. About this guide
+===========================================
+The PCI Express Port Bus Driver Guide HOWTO
+===========================================
+
+:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004
+:Copyright: |copy| 2004 Intel Corporation
+
+About this guide
+================
 
 This guide describes the basics of the PCI Express Port Bus driver
 and provides information on how to enable the service drivers to
 register/unregister with the PCI Express Port Bus Driver.
 
-2. Copyright 2004 Intel Corporation
 
-3. What is the PCI Express Port Bus Driver
+What is the PCI Express Port Bus Driver
+=======================================
 
 A PCI Express Port is a logical PCI-PCI Bridge structure. There
 are two types of PCI Express Port: the Root Port and the Switch
@@ -30,7 +37,8 @@  support (AER), and virtual channel support (VC). These services may
 be handled by a single complex driver or be individually distributed
 and handled by corresponding service drivers.
 
-4. Why use the PCI Express Port Bus Driver?
+Why use the PCI Express Port Bus Driver?
+========================================
 
 In existing Linux kernels, the Linux Device Driver Model allows a
 physical device to be handled by only a single driver. The PCI
@@ -51,28 +59,31 @@  PCI Express Ports and distributes all provided service requests
 to the corresponding service drivers as required. Some key
 advantages of using the PCI Express Port Bus driver are listed below:
 
-	- Allow multiple service drivers to run simultaneously on
-	  a PCI-PCI Bridge Port device.
+  - Allow multiple service drivers to run simultaneously on
+    a PCI-PCI Bridge Port device.
 
-	- Allow service drivers implemented in an independent
-	  staged approach.
+  - Allow service drivers implemented in an independent
+    staged approach.
 
-	- Allow one service driver to run on multiple PCI-PCI Bridge
-	  Port devices.
+  - Allow one service driver to run on multiple PCI-PCI Bridge
+    Port devices.
 
-	- Manage and distribute resources of a PCI-PCI Bridge Port
-	  device to requested service drivers.
+  - Manage and distribute resources of a PCI-PCI Bridge Port
+    device to requested service drivers.
 
-5. Configuring the PCI Express Port Bus Driver vs. Service Drivers
+Configuring the PCI Express Port Bus Driver vs. Service Drivers
+===============================================================
 
-5.1 Including the PCI Express Port Bus Driver Support into the Kernel
+Including the PCI Express Port Bus Driver Support into the Kernel
+-----------------------------------------------------------------
 
 Including the PCI Express Port Bus driver depends on whether the PCI
 Express support is included in the kernel config. The kernel will
 automatically include the PCI Express Port Bus driver as a kernel
 driver when the PCI Express support is enabled in the kernel.
 
-5.2 Enabling Service Driver Support
+Enabling Service Driver Support
+-------------------------------
 
 PCI device drivers are implemented based on Linux Device Driver Model.
 All service drivers are PCI device drivers. As discussed above, it is
@@ -89,9 +100,11 @@  header file /include/linux/pcieport_if.h, before calling these APIs.
 Failure to do so will result an identity mismatch, which prevents
 the PCI Express Port Bus driver from loading a service driver.
 
-5.2.1 pcie_port_service_register
+pcie_port_service_register
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
 
-int pcie_port_service_register(struct pcie_port_service_driver *new)
+  int pcie_port_service_register(struct pcie_port_service_driver *new)
 
 This API replaces the Linux Driver Model's pci_register_driver API. A
 service driver should always calls pcie_port_service_register at
@@ -99,69 +112,76 @@  module init. Note that after service driver being loaded, calls
 such as pci_enable_device(dev) and pci_set_master(dev) are no longer
 necessary since these calls are executed by the PCI Port Bus driver.
 
-5.2.2 pcie_port_service_unregister
+pcie_port_service_unregister
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
 
-void pcie_port_service_unregister(struct pcie_port_service_driver *new)
+  void pcie_port_service_unregister(struct pcie_port_service_driver *new)
 
 pcie_port_service_unregister replaces the Linux Driver Model's
 pci_unregister_driver. It's always called by service driver when a
 module exits.
 
-5.2.3 Sample Code
+Sample Code
+~~~~~~~~~~~
 
 Below is sample service driver code to initialize the port service
 driver data structure.
+::
 
-static struct pcie_port_service_id service_id[] = { {
-	.vendor = PCI_ANY_ID,
-	.device = PCI_ANY_ID,
-	.port_type = PCIE_RC_PORT,
-	.service_type = PCIE_PORT_SERVICE_AER,
-	}, { /* end: all zeroes */ }
-};
+  static struct pcie_port_service_id service_id[] = { {
+    .vendor = PCI_ANY_ID,
+    .device = PCI_ANY_ID,
+    .port_type = PCIE_RC_PORT,
+    .service_type = PCIE_PORT_SERVICE_AER,
+    }, { /* end: all zeroes */ }
+  };
 
-static struct pcie_port_service_driver root_aerdrv = {
-	.name		= (char *)device_name,
-	.id_table	= &service_id[0],
+  static struct pcie_port_service_driver root_aerdrv = {
+    .name		= (char *)device_name,
+    .id_table	= &service_id[0],
 
-	.probe		= aerdrv_load,
-	.remove		= aerdrv_unload,
+    .probe		= aerdrv_load,
+    .remove		= aerdrv_unload,
 
-	.suspend	= aerdrv_suspend,
-	.resume		= aerdrv_resume,
-};
+    .suspend	= aerdrv_suspend,
+    .resume		= aerdrv_resume,
+  };
 
 Below is a sample code for registering/unregistering a service
 driver.
+::
 
-static int __init aerdrv_service_init(void)
-{
-	int retval = 0;
+  static int __init aerdrv_service_init(void)
+  {
+    int retval = 0;
 
-	retval = pcie_port_service_register(&root_aerdrv);
-	if (!retval) {
-		/*
-		 * FIX ME
-		 */
-	}
-	return retval;
-}
+    retval = pcie_port_service_register(&root_aerdrv);
+    if (!retval) {
+      /*
+      * FIX ME
+      */
+    }
+    return retval;
+  }
 
-static void __exit aerdrv_service_exit(void)
-{
-	pcie_port_service_unregister(&root_aerdrv);
-}
+  static void __exit aerdrv_service_exit(void)
+  {
+    pcie_port_service_unregister(&root_aerdrv);
+  }
 
-module_init(aerdrv_service_init);
-module_exit(aerdrv_service_exit);
+  module_init(aerdrv_service_init);
+  module_exit(aerdrv_service_exit);
 
-6. Possible Resource Conflicts
+Possible Resource Conflicts
+===========================
 
 Since all service drivers of a PCI-PCI Bridge Port device are
 allowed to run simultaneously, below lists a few of possible resource
 conflicts with proposed solutions.
 
-6.1 MSI and MSI-X Vector Resource
+MSI and MSI-X Vector Resource
+-----------------------------
 
 Once MSI or MSI-X interrupts are enabled on a device, it stays in this
 mode until they are disabled again.  Since service drivers of the same
@@ -179,7 +199,8 @@  driver. Service drivers should use (struct pcie_device*)dev->irq to
 call request_irq/free_irq. In addition, the interrupt mode is stored
 in the field interrupt_mode of struct pcie_device.
 
-6.3 PCI Memory/IO Mapped Regions
+PCI Memory/IO Mapped Regions
+----------------------------
 
 Service drivers for PCI Express Power Management (PME), Advanced
 Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
@@ -188,7 +209,8 @@  registers accessed are independent of each other. This patch assumes
 that all service drivers will be well behaved and not overwrite
 other service driver's configuration settings.
 
-6.4 PCI Config Registers
+PCI Config Registers
+--------------------
 
 Each service driver runs its PCI config operations on its own
 capability structure except the PCI Express capability structure, in
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 7babf43709b0..452723318405 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -9,3 +9,4 @@  Linux PCI Bus Subsystem
    :numbered:
 
    pci
+   PCIEBUS-HOWTO