AuxXxilium/linux_dsm_epyc7002
1
0
Fork 0
mirror of https://github.com/AuxXxilium/linux_dsm_epyc7002.git synced 2025-03-11 23:27:42 +07:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST

Browse Source 
Convert 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>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
Changbin Du 2019-05-14 22:47:25 +08:00 committed by Bjorn Helgaas
parent 229b4e0728
commit 2e64224448
2 changed files with 82 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/PCI/index.rst
View File

@ -9,3 +9,4 @@ Linux PCI Bus Subsystem
:numbered: :numbered:
pci pci
picebus-howto

140
Documentation/PCI/PCIEBUS-HOWTO.txt → Documentation/PCI/picebus-howto.rst
View File

@ -1,16 +1,23 @@
The PCI Express Port Bus Driver Guide HOWTO .. SPDX-License-Identifier: GPL-2.0
Tom L Nguyen tom.l.nguyen@intel.com .. include:: <isonum.txt>
11/03/2004
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 This guide describes the basics of the PCI Express Port Bus driver
and provides information on how to enable the service drivers to and provides information on how to enable the service drivers to
register/unregister with the PCI Express Port Bus Driver. 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 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 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 be handled by a single complex driver or be individually distributed
and handled by corresponding service drivers. 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 In existing Linux kernels, the Linux Device Driver Model allows a
physical device to be handled by only a single driver. The PCI 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 to the corresponding service drivers as required. Some key
advantages of using the PCI Express Port Bus driver are listed below: advantages of using the PCI Express Port Bus driver are listed below:
- Allow multiple service drivers to run simultaneously on - Allow multiple service drivers to run simultaneously on
a PCI-PCI Bridge Port device. a PCI-PCI Bridge Port device.
- Allow service drivers implemented in an independent - Allow service drivers implemented in an independent
staged approach. staged approach.
- Allow one service driver to run on multiple PCI-PCI Bridge - Allow one service driver to run on multiple PCI-PCI Bridge
Port devices. Port devices.
- Manage and distribute resources of a PCI-PCI Bridge Port - Manage and distribute resources of a PCI-PCI Bridge Port
device to requested service drivers. 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 Including the PCI Express Port Bus driver depends on whether the PCI
Express support is included in the kernel config. The kernel will Express support is included in the kernel config. The kernel will
automatically include the PCI Express Port Bus driver as a kernel automatically include the PCI Express Port Bus driver as a kernel
driver when the PCI Express support is enabled in the 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. PCI device drivers are implemented based on Linux Device Driver Model.
All service drivers are PCI device drivers. As discussed above, it is 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 Failure to do so will result an identity mismatch, which prevents
the PCI Express Port Bus driver from loading a service driver. 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 This API replaces the Linux Driver Model's pci_register_driver API. A
service driver should always calls pcie_port_service_register at 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 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. 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 pcie_port_service_unregister replaces the Linux Driver Model's
pci_unregister_driver. It's always called by service driver when a pci_unregister_driver. It's always called by service driver when a
module exits. module exits.
5.2.3 Sample Code Sample Code
~~~~~~~~~~~
Below is sample service driver code to initialize the port service Below is sample service driver code to initialize the port service
driver data structure. driver data structure.
::
static struct pcie_port_service_id service_id[] = { { static struct pcie_port_service_id service_id[] = { {
.vendor = PCI_ANY_ID, .vendor = PCI_ANY_ID,
.device = PCI_ANY_ID, .device = PCI_ANY_ID,
.port_type = PCIE_RC_PORT, .port_type = PCIE_RC_PORT,
.service_type = PCIE_PORT_SERVICE_AER, .service_type = PCIE_PORT_SERVICE_AER,
}, { /* end: all zeroes */ } }, { /* end: all zeroes */ }
}; };
static struct pcie_port_service_driver root_aerdrv = { static struct pcie_port_service_driver root_aerdrv = {
.name = (char *)device_name, .name = (char *)device_name,
.id_table = &service_id[0], .id_table = &service_id[0],
.probe = aerdrv_load, .probe = aerdrv_load,
.remove = aerdrv_unload, .remove = aerdrv_unload,
.suspend = aerdrv_suspend, .suspend = aerdrv_suspend,
.resume = aerdrv_resume, .resume = aerdrv_resume,
}; };
Below is a sample code for registering/unregistering a service Below is a sample code for registering/unregistering a service
driver. driver.
::
static int __init aerdrv_service_init(void) static int __init aerdrv_service_init(void)
{ {
int retval = 0; int retval = 0;
retval = pcie_port_service_register(&root_aerdrv); retval = pcie_port_service_register(&root_aerdrv);
if (!retval) { if (!retval) {
/* /*
* FIX ME * FIX ME
*/ */
} }
return retval; return retval;
} }
static void __exit aerdrv_service_exit(void) static void __exit aerdrv_service_exit(void)
{ {
pcie_port_service_unregister(&root_aerdrv); pcie_port_service_unregister(&root_aerdrv);
} }
module_init(aerdrv_service_init); module_init(aerdrv_service_init);
module_exit(aerdrv_service_exit); module_exit(aerdrv_service_exit);
6. Possible Resource Conflicts Possible Resource Conflicts
===========================
Since all service drivers of a PCI-PCI Bridge Port device are Since all service drivers of a PCI-PCI Bridge Port device are
allowed to run simultaneously, below lists a few of possible resource allowed to run simultaneously, below lists a few of possible resource
conflicts with proposed solutions. 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 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 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 call request_irq/free_irq. In addition, the interrupt mode is stored
in the field interrupt_mode of struct pcie_device. 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 Service drivers for PCI Express Power Management (PME), Advanced
Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access 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 that all service drivers will be well behaved and not overwrite
other service driver's configuration settings. 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 Each service driver runs its PCI config operations on its own
capability structure except the PCI Express capability structure, in capability structure except the PCI Express capability structure, in