[PATCH 03/12] pci doc: convert PCI/PCIEBUS-HOWTO.txt to rst format
From: Changbin Du
Date: Fri Mar 29 2019 - 12:04:48 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>
---
.../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} | 112 +++++++++++-------
Documentation/PCI/index.rst | 1 +
2 files changed, 68 insertions(+), 45 deletions(-)
rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (75%)
diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/PCIEBUS-HOWTO.rst
similarity index 75%
rename from Documentation/PCI/PCIEBUS-HOWTO.txt
rename to Documentation/PCI/PCIEBUS-HOWTO.rst
index 15f0bb3b5045..bde6530689a6 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@xxxxxxxxx
- 11/03/2004
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================
+The PCI Express Port Bus Driver Guide HOWTO
+===========================================
+
+:Author: Tom L Nguyen tom.l.nguyen@xxxxxxxxx 11/03/2004
1. 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
+==========================================
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
@@ -31,6 +38,7 @@ 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?
+===========================================
In existing Linux kernels, the Linux Device Driver Model allows a
physical device to be handled by only a single driver. The PCI
@@ -51,21 +59,23 @@ 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
+==================================================================
5.1 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
@@ -73,6 +83,7 @@ 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
+-----------------------------------
PCI device drivers are implemented based on Linux Device Driver Model.
All service drivers are PCI device drivers. As discussed above, it is
@@ -90,8 +101,10 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
-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
@@ -100,68 +113,75 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
-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
+~~~~~~~~~~~~~~~~~
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
+==============================
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
+---------------------------------
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
@@ -180,6 +200,7 @@ 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
+--------------------------------
Service drivers for PCI Express Power Management (PME), Advanced
Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
@@ -189,6 +210,7 @@ that all service drivers will be well behaved and not overwrite
other service driver's configuration settings.
6.4 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 06fce3d3c7da..58ce08f14f33 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -8,3 +8,4 @@ Linux PCI Bus Subsystem
:maxdepth: 2
pci
+ PCIEBUS-HOWTO
--
2.20.1