2019-05-13 14:25:42

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 00/12] Include linux PCI docs into Sphinx TOC tree

Hi all,

The kernel now uses Sphinx to generate intelligent and beautiful documentation
from reStructuredText files. I converted most of the Linux PCI docs to rst
format in this serias.

For you to preview, please visit below url:
http://www.bytemem.com:8080/kernel-doc/PCI/index.html

Thank you!

v2: trivial style update.
v3: update titles. (Bjorn Helgaas)
v4: fix comments from Mauro Carvalho Chehab
v5: update MAINTAINERS (Joe Perches)

Changbin Du (12):
Documentation: add Linux PCI to Sphinx TOC tree
Documentation: PCI: convert pci.txt to reST
Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST
Documentation: PCI: convert pci-iov-howto.txt to reST
Documentation: PCI: convert MSI-HOWTO.txt to reST
Documentation: PCI: convert acpi-info.txt to reST
Documentation: PCI: convert pci-error-recovery.txt to reST
Documentation: PCI: convert pcieaer-howto.txt to reST
Documentation: PCI: convert endpoint/pci-endpoint.txt to reST
Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST
Documentation: PCI: convert endpoint/pci-test-function.txt to reST
Documentation: PCI: convert endpoint/pci-test-howto.txt to reST

.../PCI/{acpi-info.txt => acpi-info.rst} | 15 +-
Documentation/PCI/endpoint/index.rst | 13 +
...-endpoint-cfs.txt => pci-endpoint-cfs.rst} | 99 ++---
.../{pci-endpoint.txt => pci-endpoint.rst} | 96 +++--
...est-function.txt => pci-test-function.rst} | 34 +-
...{pci-test-howto.txt => pci-test-howto.rst} | 81 ++--
Documentation/PCI/index.rst | 18 +
.../PCI/{MSI-HOWTO.txt => msi-howto.rst} | 85 +++--
...or-recovery.txt => pci-error-recovery.rst} | 287 +++++++-------
.../{pci-iov-howto.txt => pci-iov-howto.rst} | 161 ++++----
Documentation/PCI/{pci.txt => pci.rst} | 356 ++++++++----------
.../{pcieaer-howto.txt => pcieaer-howto.rst} | 156 +++++---
.../{PCIEBUS-HOWTO.txt => picebus-howto.rst} | 140 ++++---
Documentation/index.rst | 1 +
MAINTAINERS | 4 +-
include/linux/mod_devicetable.h | 19 +
include/linux/pci.h | 37 ++
17 files changed, 913 insertions(+), 689 deletions(-)
rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (96%)
create mode 100644 Documentation/PCI/endpoint/index.rst
rename Documentation/PCI/endpoint/{pci-endpoint-cfs.txt => pci-endpoint-cfs.rst} (64%)
rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (82%)
rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (84%)
rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (78%)
create mode 100644 Documentation/PCI/index.rst
rename Documentation/PCI/{MSI-HOWTO.txt => msi-howto.rst} (88%)
rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (67%)
rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (63%)
rename Documentation/PCI/{pci.txt => pci.rst} (68%)
rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (72%)
rename Documentation/PCI/{PCIEBUS-HOWTO.txt => picebus-howto.rst} (70%)

--
2.20.1


2019-05-13 14:25:54

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 09/12] Documentation: PCI: convert endpoint/pci-endpoint.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
---
Documentation/PCI/endpoint/index.rst | 10 ++
.../{pci-endpoint.txt => pci-endpoint.rst} | 96 +++++++++++--------
Documentation/PCI/index.rst | 1 +
3 files changed, 69 insertions(+), 38 deletions(-)
create mode 100644 Documentation/PCI/endpoint/index.rst
rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (82%)

diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
new file mode 100644
index 000000000000..0db4f2fcd7f0
--- /dev/null
+++ b/Documentation/PCI/endpoint/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+PCI Endpoint Framework
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ pci-endpoint
diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt b/Documentation/PCI/endpoint/pci-endpoint.rst
similarity index 82%
rename from Documentation/PCI/endpoint/pci-endpoint.txt
rename to Documentation/PCI/endpoint/pci-endpoint.rst
index e86a96b66a6a..693f3a2ad7a4 100644
--- a/Documentation/PCI/endpoint/pci-endpoint.txt
+++ b/Documentation/PCI/endpoint/pci-endpoint.rst
@@ -1,11 +1,17 @@
- PCI ENDPOINT FRAMEWORK
- Kishon Vijay Abraham I <[email protected]>
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+PCI Endpoint Framework
+======================
+
+:Author: Kishon Vijay Abraham I <[email protected]>

This document is a guide to use the PCI Endpoint Framework in order to create
endpoint controller driver, endpoint function driver, and using configfs
interface to bind the function driver to the controller driver.

-1. Introduction
+Introduction
+============

Linux has a comprehensive PCI subsystem to support PCI controllers that
operates in Root Complex mode. The subsystem has capability to scan PCI bus,
@@ -19,26 +25,30 @@ add endpoint mode support in Linux. This will help to run Linux in an
EP system which can have a wide variety of use cases from testing or
validation, co-processor accelerator, etc.

-2. PCI Endpoint Core
+PCI Endpoint Core
+=================

The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
library, the Endpoint Function library, and the configfs layer to bind the
endpoint function with the endpoint controller.

-2.1 PCI Endpoint Controller(EPC) Library
+PCI Endpoint Controller(EPC) Library
+------------------------------------

The EPC library provides APIs to be used by the controller that can operate
in endpoint mode. It also provides APIs to be used by function driver/library
in order to implement a particular endpoint function.

-2.1.1 APIs for the PCI controller Driver
+APIs for the PCI controller Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section lists the APIs that the PCI Endpoint core provides to be used
by the PCI controller driver.

-*) devm_pci_epc_create()/pci_epc_create()
+* devm_pci_epc_create()/pci_epc_create()

The PCI controller driver should implement the following ops:
+
* write_header: ops to populate configuration space header
* set_bar: ops to configure the BAR
* clear_bar: ops to reset the BAR
@@ -51,110 +61,116 @@ by the PCI controller driver.
The PCI controller driver can then create a new EPC device by invoking
devm_pci_epc_create()/pci_epc_create().

-*) devm_pci_epc_destroy()/pci_epc_destroy()
+* devm_pci_epc_destroy()/pci_epc_destroy()

The PCI controller driver can destroy the EPC device created by either
devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
pci_epc_destroy().

-*) pci_epc_linkup()
+* pci_epc_linkup()

In order to notify all the function devices that the EPC device to which
they are linked has established a link with the host, the PCI controller
driver should invoke pci_epc_linkup().

-*) pci_epc_mem_init()
+* pci_epc_mem_init()

Initialize the pci_epc_mem structure used for allocating EPC addr space.

-*) pci_epc_mem_exit()
+* pci_epc_mem_exit()

Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().

-2.1.2 APIs for the PCI Endpoint Function Driver
+
+APIs for the PCI Endpoint Function Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section lists the APIs that the PCI Endpoint core provides to be used
by the PCI endpoint function driver.

-*) pci_epc_write_header()
+* pci_epc_write_header()

The PCI endpoint function driver should use pci_epc_write_header() to
write the standard configuration header to the endpoint controller.

-*) pci_epc_set_bar()
+* pci_epc_set_bar()

The PCI endpoint function driver should use pci_epc_set_bar() to configure
the Base Address Register in order for the host to assign PCI addr space.
Register space of the function driver is usually configured
using this API.

-*) pci_epc_clear_bar()
+* pci_epc_clear_bar()

The PCI endpoint function driver should use pci_epc_clear_bar() to reset
the BAR.

-*) pci_epc_raise_irq()
+* pci_epc_raise_irq()

The PCI endpoint function driver should use pci_epc_raise_irq() to raise
Legacy Interrupt, MSI or MSI-X Interrupt.

-*) pci_epc_mem_alloc_addr()
+* pci_epc_mem_alloc_addr()

The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
allocate memory address from EPC addr space which is required to access
RC's buffer

-*) pci_epc_mem_free_addr()
+* pci_epc_mem_free_addr()

The PCI endpoint function driver should use pci_epc_mem_free_addr() to
free the memory space allocated using pci_epc_mem_alloc_addr().

-2.1.3 Other APIs
+Other APIs
+~~~~~~~~~~

There are other APIs provided by the EPC library. These are used for binding
the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
using these APIs.

-*) pci_epc_get()
+* pci_epc_get()

Get a reference to the PCI endpoint controller based on the device name of
the controller.

-*) pci_epc_put()
+* pci_epc_put()

Release the reference to the PCI endpoint controller obtained using
pci_epc_get()

-*) pci_epc_add_epf()
+* pci_epc_add_epf()

Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
can have up to 8 functions according to the specification.

-*) pci_epc_remove_epf()
+* pci_epc_remove_epf()

Remove the PCI endpoint function from PCI endpoint controller.

-*) pci_epc_start()
+* pci_epc_start()

The PCI endpoint function driver should invoke pci_epc_start() once it
has configured the endpoint function and wants to start the PCI link.

-*) pci_epc_stop()
+* pci_epc_stop()

The PCI endpoint function driver should invoke pci_epc_stop() to stop
the PCI LINK.

-2.2 PCI Endpoint Function(EPF) Library
+
+PCI Endpoint Function(EPF) Library
+----------------------------------

The EPF library provides APIs to be used by the function driver and the EPC
library to provide endpoint mode functionality.

-2.2.1 APIs for the PCI Endpoint Function Driver
+APIs for the PCI Endpoint Function Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section lists the APIs that the PCI Endpoint core provides to be used
by the PCI endpoint function driver.

-*) pci_epf_register_driver()
+* pci_epf_register_driver()

The PCI Endpoint Function driver should implement the following ops:
* bind: ops to perform when a EPC device has been bound to EPF device
@@ -166,50 +182,54 @@ by the PCI endpoint function driver.
The PCI Function driver can then register the PCI EPF driver by using
pci_epf_register_driver().

-*) pci_epf_unregister_driver()
+* pci_epf_unregister_driver()

The PCI Function driver can unregister the PCI EPF driver by using
pci_epf_unregister_driver().

-*) pci_epf_alloc_space()
+* pci_epf_alloc_space()

The PCI Function driver can allocate space for a particular BAR using
pci_epf_alloc_space().

-*) pci_epf_free_space()
+* pci_epf_free_space()

The PCI Function driver can free the allocated space
(using pci_epf_alloc_space) by invoking pci_epf_free_space().

-2.2.2 APIs for the PCI Endpoint Controller Library
+APIs for the PCI Endpoint Controller Library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
This section lists the APIs that the PCI Endpoint core provides to be used
by the PCI endpoint controller library.

-*) pci_epf_linkup()
+* pci_epf_linkup()

The PCI endpoint controller library invokes pci_epf_linkup() when the
EPC device has established the connection to the host.

-2.2.2 Other APIs
+Other APIs
+~~~~~~~~~~
+
There are other APIs provided by the EPF library. These are used to notify
the function driver when the EPF device is bound to the EPC device.
pci-ep-cfs.c can be used as reference for using these APIs.

-*) pci_epf_create()
+* pci_epf_create()

Create a new PCI EPF device by passing the name of the PCI EPF device.
This name will be used to bind the the EPF device to a EPF driver.

-*) pci_epf_destroy()
+* pci_epf_destroy()

Destroy the created PCI EPF device.

-*) pci_epf_bind()
+* pci_epf_bind()

pci_epf_bind() should be invoked when the EPF device has been bound to
a EPC device.

-*) pci_epf_unbind()
+* pci_epf_unbind()

pci_epf_unbind() should be invoked when the binding between EPC device
and EPF device is lost.
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index f54b65b1ca5f..f4c6121868c3 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -15,3 +15,4 @@ Linux PCI Bus Subsystem
acpi-info
pci-error-recovery
pcieaer-howto
+ endpoint/index
--
2.20.1

2019-05-13 14:26:31

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 12/12] Documentation: PCI: convert endpoint/pci-test-howto.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/PCI/endpoint/index.rst | 1 +
...{pci-test-howto.txt => pci-test-howto.rst} | 81 +++++++++++++------
2 files changed, 56 insertions(+), 26 deletions(-)
rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (78%)

diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
index b680a3fc4fec..d114ea74b444 100644
--- a/Documentation/PCI/endpoint/index.rst
+++ b/Documentation/PCI/endpoint/index.rst
@@ -10,3 +10,4 @@ PCI Endpoint Framework
pci-endpoint
pci-endpoint-cfs
pci-test-function
+ pci-test-howto
diff --git a/Documentation/PCI/endpoint/pci-test-howto.txt b/Documentation/PCI/endpoint/pci-test-howto.rst
similarity index 78%
rename from Documentation/PCI/endpoint/pci-test-howto.txt
rename to Documentation/PCI/endpoint/pci-test-howto.rst
index 040479f437a5..909f770a07d6 100644
--- a/Documentation/PCI/endpoint/pci-test-howto.txt
+++ b/Documentation/PCI/endpoint/pci-test-howto.rst
@@ -1,38 +1,51 @@
- PCI TEST USERGUIDE
- Kishon Vijay Abraham I <[email protected]>
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+PCI Test User Guide
+===================
+
+:Author: Kishon Vijay Abraham I <[email protected]>

This document is a guide to help users use pci-epf-test function driver
and pci_endpoint_test host driver for testing PCI. The list of steps to
be followed in the host side and EP side is given below.

-1. Endpoint Device
+Endpoint Device
+===============

-1.1 Endpoint Controller Devices
+Endpoint Controller Devices
+---------------------------

-To find the list of endpoint controller devices in the system:
+To find the list of endpoint controller devices in the system::

# ls /sys/class/pci_epc/
51000000.pcie_ep

-If PCI_ENDPOINT_CONFIGFS is enabled
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
# ls /sys/kernel/config/pci_ep/controllers
51000000.pcie_ep

-1.2 Endpoint Function Drivers

-To find the list of endpoint function drivers in the system:
+Endpoint Function Drivers
+-------------------------
+
+To find the list of endpoint function drivers in the system::

# ls /sys/bus/pci-epf/drivers
pci_epf_test

-If PCI_ENDPOINT_CONFIGFS is enabled
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
# ls /sys/kernel/config/pci_ep/functions
pci_epf_test

-1.3 Creating pci-epf-test Device
+
+Creating pci-epf-test Device
+----------------------------

PCI endpoint function device can be created using the configfs. To create
-pci-epf-test device, the following commands can be used
+pci-epf-test device, the following commands can be used::

# mount -t configfs none /sys/kernel/config
# cd /sys/kernel/config/pci_ep/
@@ -42,7 +55,7 @@ The "mkdir func1" above creates the pci-epf-test function device that will
be probed by pci_epf_test driver.

The PCI endpoint framework populates the directory with the following
-configurable fields.
+configurable fields::

# ls functions/pci_epf_test/func1
baseclass_code interrupt_pin progif_code subsys_id
@@ -51,67 +64,83 @@ configurable fields.

The PCI endpoint function driver populates these entries with default values
when the device is bound to the driver. The pci-epf-test driver populates
-vendorid with 0xffff and interrupt_pin with 0x0001
+vendorid with 0xffff and interrupt_pin with 0x0001::

# cat functions/pci_epf_test/func1/vendorid
0xffff
# cat functions/pci_epf_test/func1/interrupt_pin
0x0001

-1.4 Configuring pci-epf-test Device
+
+Configuring pci-epf-test Device
+-------------------------------

The user can configure the pci-epf-test device using configfs entry. In order
to change the vendorid and the number of MSI interrupts used by the function
-device, the following commands can be used.
+device, the following commands can be used::

# echo 0x104c > functions/pci_epf_test/func1/vendorid
# echo 0xb500 > functions/pci_epf_test/func1/deviceid
# echo 16 > functions/pci_epf_test/func1/msi_interrupts
# echo 8 > functions/pci_epf_test/func1/msix_interrupts

-1.5 Binding pci-epf-test Device to EP Controller
+
+Binding pci-epf-test Device to EP Controller
+--------------------------------------------

In order for the endpoint function device to be useful, it has to be bound to
a PCI endpoint controller driver. Use the configfs to bind the function
-device to one of the controller driver present in the system.
+device to one of the controller driver present in the system::

# ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/

Once the above step is completed, the PCI endpoint is ready to establish a link
with the host.

-1.6 Start the Link
+
+Start the Link
+--------------

In order for the endpoint device to establish a link with the host, the _start_
-field should be populated with '1'.
+field should be populated with '1'::

# echo 1 > controllers/51000000.pcie_ep/start

-2. RootComplex Device

-2.1 lspci Output
+RootComplex Device
+==================
+
+lspci Output
+------------

-Note that the devices listed here correspond to the value populated in 1.4 above
+Note that the devices listed here correspond to the value populated in 1.4
+above::

00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
01:00.0 Unassigned class [ff00]: Texas Instruments Device b500

-2.2 Using Endpoint Test function Device
+
+Using Endpoint Test function Device
+-----------------------------------

pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
-tests. To compile this tool the following commands should be used:
+tests. To compile this tool the following commands should be used::

# cd <kernel-dir>
# make -C tools/pci

-or if you desire to compile and install in your system:
+or if you desire to compile and install in your system::

# cd <kernel-dir>
# make -C tools/pci install

The tool and script will be located in <rootfs>/usr/bin/

-2.2.1 pcitest.sh Output
+
+pcitest.sh Output
+~~~~~~~~~~~~~~~~~
+::
+
# pcitest.sh
BAR tests

--
2.20.1

2019-05-13 14:26:37

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 05/12] Documentation: PCI: convert MSI-HOWTO.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
---
v2:
o drop numbering.
o simplify author list
---
Documentation/PCI/index.rst | 1 +
.../PCI/{MSI-HOWTO.txt => msi-howto.rst} | 85 +++++++++++--------
2 files changed, 52 insertions(+), 34 deletions(-)
rename Documentation/PCI/{MSI-HOWTO.txt => msi-howto.rst} (88%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 0d9390298c4a..458354daac47 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -11,3 +11,4 @@ Linux PCI Bus Subsystem
pci
picebus-howto
pci-iov-howto
+ msi-howto
diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/msi-howto.rst
similarity index 88%
rename from Documentation/PCI/MSI-HOWTO.txt
rename to Documentation/PCI/msi-howto.rst
index 618e13d5e276..994cbb660ade 100644
--- a/Documentation/PCI/MSI-HOWTO.txt
+++ b/Documentation/PCI/msi-howto.rst
@@ -1,13 +1,16 @@
- The MSI Driver Guide HOWTO
- Tom L Nguyen [email protected]
- 10/03/2003
- Revised Feb 12, 2004 by Martine Silbermann
- email: [email protected]
- Revised Jun 25, 2004 by Tom L Nguyen
- Revised Jul 9, 2008 by Matthew Wilcox <[email protected]>
- Copyright 2003, 2008 Intel Corporation
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>

-1. About this guide
+==========================
+The MSI Driver Guide HOWTO
+==========================
+
+:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
+
+:Copyright: 2003, 2008 Intel Corporation
+
+About this guide
+================

This guide describes the basics of Message Signaled Interrupts (MSIs),
the advantages of using MSI over traditional interrupt mechanisms, how
@@ -15,7 +18,8 @@ to change your driver to use MSI or MSI-X and some basic diagnostics to
try if a device doesn't support MSIs.


-2. What are MSIs?
+What are MSIs?
+==============

A Message Signaled Interrupt is a write from the device to a special
address which causes an interrupt to be received by the CPU.
@@ -29,7 +33,8 @@ Devices may support both MSI and MSI-X, but only one can be enabled at
a time.


-3. Why use MSIs?
+Why use MSIs?
+=============

There are three reasons why using MSIs can give an advantage over
traditional pin-based interrupts.
@@ -61,14 +66,16 @@ Other possible designs include giving one interrupt to each packet queue
in a network card or each port in a storage controller.


-4. How to use MSIs
+How to use MSIs
+===============

PCI devices are initialised to use pin-based interrupts. The device
driver has to set up the device to use MSI or MSI-X. Not all machines
support MSIs correctly, and for those machines, the APIs described below
will simply fail and the device will continue to use pin-based interrupts.

-4.1 Include kernel support for MSIs
+Include kernel support for MSIs
+-------------------------------

To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
option enabled. This option is only available on some architectures,
@@ -76,14 +83,15 @@ and it may depend on some other options also being set. For example,
on x86, you must also enable X86_UP_APIC or SMP in order to see the
CONFIG_PCI_MSI option.

-4.2 Using MSI
+Using MSI
+---------

Most of the hard work is done for the driver in the PCI layer. The driver
simply has to request that the PCI layer set up the MSI capability for this
device.

To automatically use MSI or MSI-X interrupt vectors, use the following
-function:
+function::

int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
unsigned int max_vecs, unsigned int flags);
@@ -101,12 +109,12 @@ any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.

To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
-vectors, use the following function:
+vectors, use the following function::

int pci_irq_vector(struct pci_dev *dev, unsigned int nr);

Any allocated resources should be freed before removing the device using
-the following function:
+the following function::

void pci_free_irq_vectors(struct pci_dev *dev);

@@ -126,7 +134,7 @@ The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
as possible, likely up to the limit supported by the device. If nvec is
larger than the number supported by the device it will automatically be
capped to the supported limit, so there is no need to query the number of
-vectors supported beforehand:
+vectors supported beforehand::

nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
if (nvec < 0)
@@ -135,7 +143,7 @@ vectors supported beforehand:
If a driver is unable or unwilling to deal with a variable number of MSI
interrupts it can request a particular number of interrupts by passing that
number to pci_alloc_irq_vectors() function as both 'min_vecs' and
-'max_vecs' parameters:
+'max_vecs' parameters::

ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
if (ret < 0)
@@ -143,23 +151,24 @@ number to pci_alloc_irq_vectors() function as both 'min_vecs' and

The most notorious example of the request type described above is enabling
the single MSI mode for a device. It could be done by passing two 1s as
-'min_vecs' and 'max_vecs':
+'min_vecs' and 'max_vecs'::

ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
if (ret < 0)
goto out_err;

Some devices might not support using legacy line interrupts, in which case
-the driver can specify that only MSI or MSI-X is acceptable:
+the driver can specify that only MSI or MSI-X is acceptable::

nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);
if (nvec < 0)
goto out_err;

-4.3 Legacy APIs
+Legacy APIs
+-----------

The following old APIs to enable and disable MSI or MSI-X interrupts should
-not be used in new code:
+not be used in new code::

pci_enable_msi() /* deprecated */
pci_disable_msi() /* deprecated */
@@ -174,9 +183,11 @@ number of vectors. If you have a legitimate special use case for the count
of vectors we might have to revisit that decision and add a
pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.

-4.4 Considerations when using MSIs
+Considerations when using MSIs
+------------------------------

-4.4.1 Spinlocks
+Spinlocks
+~~~~~~~~~

Most device drivers have a per-device spinlock which is taken in the
interrupt handler. With pin-based interrupts or a single MSI, it is not
@@ -188,7 +199,8 @@ acquire the spinlock. Such deadlocks can be avoided by using
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
and acquire the lock (see Documentation/kernel-hacking/locking.rst).

-4.5 How to tell whether MSI/MSI-X is enabled on a device
+How to tell whether MSI/MSI-X is enabled on a device
+----------------------------------------------------

Using 'lspci -v' (as root) may show some devices with "MSI", "Message
Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
@@ -196,7 +208,8 @@ has an 'Enable' flag which is followed with either "+" (enabled)
or "-" (disabled).


-5. MSI quirks
+MSI quirks
+==========

Several PCI chipsets or devices are known not to support MSIs.
The PCI stack provides three ways to disable MSIs:
@@ -205,7 +218,8 @@ The PCI stack provides three ways to disable MSIs:
2. on all devices behind a specific bridge
3. on a single device

-5.1. Disabling MSIs globally
+Disabling MSIs globally
+-----------------------

Some host chipsets simply don't support MSIs properly. If we're
lucky, the manufacturer knows this and has indicated it in the ACPI
@@ -219,7 +233,8 @@ on the kernel command line to disable MSIs on all devices. It would be
in your best interests to report the problem to [email protected]
including a full 'lspci -v' so we can add the quirks to the kernel.

-5.2. Disabling MSIs below a bridge
+Disabling MSIs below a bridge
+-----------------------------

Some PCI bridges are not able to route MSIs between busses properly.
In this case, MSIs must be disabled on all devices behind the bridge.
@@ -230,7 +245,7 @@ as the nVidia nForce and Serverworks HT2000). As with host chipsets,
Linux mostly knows about them and automatically enables MSIs if it can.
If you have a bridge unknown to Linux, you can enable
MSIs in configuration space using whatever method you know works, then
-enable MSIs on that bridge by doing:
+enable MSIs on that bridge by doing::

echo 1 > /sys/bus/pci/devices/$bridge/msi_bus

@@ -244,7 +259,8 @@ below this bridge.
Again, please notify [email protected] of any bridges that need
special handling.

-5.3. Disabling MSIs on a single device
+Disabling MSIs on a single device
+---------------------------------

Some devices are known to have faulty MSI implementations. Usually this
is handled in the individual device driver, but occasionally it's necessary
@@ -252,7 +268,8 @@ to handle this with a quirk. Some drivers have an option to disable use
of MSI. While this is a convenient workaround for the driver author,
it is not good practice, and should not be emulated.

-5.4. Finding why MSIs are disabled on a device
+Finding why MSIs are disabled on a device
+-----------------------------------------

From the above three sections, you can see that there are many reasons
why MSIs may not be enabled for a given device. Your first step should
@@ -260,8 +277,8 @@ be to examine your dmesg carefully to determine whether MSIs are enabled
for your machine. You should also check your .config to be sure you
have enabled CONFIG_PCI_MSI.

-Then, 'lspci -t' gives the list of bridges above a device. Reading
-/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1)
+Then, 'lspci -t' gives the list of bridges above a device. Reading
+`/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1)
or disabled (0). If 0 is found in any of the msi_bus files belonging
to bridges between the PCI root and the device, MSIs are disabled.

--
2.20.1

2019-05-13 14:26:39

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 06/12] Documentation: PCI: convert acpi-info.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
---
.../PCI/{acpi-info.txt => acpi-info.rst} | 15 ++++++++++-----
Documentation/PCI/index.rst | 1 +
2 files changed, 11 insertions(+), 5 deletions(-)
rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (96%)

diff --git a/Documentation/PCI/acpi-info.txt b/Documentation/PCI/acpi-info.rst
similarity index 96%
rename from Documentation/PCI/acpi-info.txt
rename to Documentation/PCI/acpi-info.rst
index 3ffa3b03970e..060217081c79 100644
--- a/Documentation/PCI/acpi-info.txt
+++ b/Documentation/PCI/acpi-info.rst
@@ -1,4 +1,8 @@
- ACPI considerations for PCI host bridges
+.. SPDX-License-Identifier: GPL-2.0
+
+========================================
+ACPI considerations for PCI host bridges
+========================================

The general rule is that the ACPI namespace should describe everything the
OS might use unless there's another way for the OS to find it [1, 2].
@@ -131,12 +135,13 @@ address always corresponds to bus 0, even if the bus range below the bridge

[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
QWord/DWord/Word Address Space Descriptor (.1, .2, .3)
- General Flags: Bit [0] Ignored
+ General Flags: Bit [0] Ignored

Extended Address Space Descriptor (.4)
- General Flags: Bit [0] Consumer/Producer:
- 1–This device consumes this resource
- 0–This device produces and consumes this resource
+ General Flags: Bit [0] Consumer/Producer:
+
+ * 1 – This device consumes this resource
+ * 0 – This device produces and consumes this resource

[5] ACPI 6.2, sec 19.6.43:
ResourceUsage specifies whether the Memory range is consumed by
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 458354daac47..6f573f3df993 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -12,3 +12,4 @@ Linux PCI Bus Subsystem
picebus-howto
pci-iov-howto
msi-howto
+ acpi-info
--
2.20.1

2019-05-13 14:27:26

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 10/12] Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/PCI/endpoint/index.rst | 1 +
...-endpoint-cfs.txt => pci-endpoint-cfs.rst} | 99 +++++++++++--------
2 files changed, 57 insertions(+), 43 deletions(-)
rename Documentation/PCI/endpoint/{pci-endpoint-cfs.txt => pci-endpoint-cfs.rst} (64%)

diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
index 0db4f2fcd7f0..3951de9f923c 100644
--- a/Documentation/PCI/endpoint/index.rst
+++ b/Documentation/PCI/endpoint/index.rst
@@ -8,3 +8,4 @@ PCI Endpoint Framework
:maxdepth: 2

pci-endpoint
+ pci-endpoint-cfs
diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
similarity index 64%
rename from Documentation/PCI/endpoint/pci-endpoint-cfs.txt
rename to Documentation/PCI/endpoint/pci-endpoint-cfs.rst
index d740f29960a4..b6d39cdec56e 100644
--- a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
+++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
@@ -1,41 +1,51 @@
- CONFIGURING PCI ENDPOINT USING CONFIGFS
- Kishon Vijay Abraham I <[email protected]>
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+Configuring PCI Endpoint Using CONFIGFS
+=======================================
+
+:Author: Kishon Vijay Abraham I <[email protected]>

The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
PCI endpoint function and to bind the endpoint function
with the endpoint controller. (For introducing other mechanisms to
configure the PCI Endpoint Function refer to [1]).

-*) Mounting configfs
+Mounting configfs
+=================

The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
-directory. configfs can be mounted using the following command.
+directory. configfs can be mounted using the following command::

mount -t configfs none /sys/kernel/config

-*) Directory Structure
+Directory Structure
+===================

The pci_ep configfs has two directories at its root: controllers and
functions. Every EPC device present in the system will have an entry in
the *controllers* directory and and every EPF driver present in the system
will have an entry in the *functions* directory.
+::

-/sys/kernel/config/pci_ep/
- .. controllers/
- .. functions/
+ /sys/kernel/config/pci_ep/
+ .. controllers/
+ .. functions/

-*) Creating EPF Device
+Creating EPF Device
+===================

Every registered EPF driver will be listed in controllers directory. The
entries corresponding to EPF driver will be created by the EPF core.
+::

-/sys/kernel/config/pci_ep/functions/
- .. <EPF Driver1>/
- ... <EPF Device 11>/
- ... <EPF Device 21>/
- .. <EPF Driver2>/
- ... <EPF Device 12>/
- ... <EPF Device 22>/
+ /sys/kernel/config/pci_ep/functions/
+ .. <EPF Driver1>/
+ ... <EPF Device 11>/
+ ... <EPF Device 21>/
+ .. <EPF Driver2>/
+ ... <EPF Device 12>/
+ ... <EPF Device 22>/

In order to create a <EPF device> of the type probed by <EPF Driver>, the
user has to create a directory inside <EPF DriverN>.
@@ -44,34 +54,37 @@ Every <EPF device> directory consists of the following entries that can be
used to configure the standard configuration header of the endpoint function.
(These entries are created by the framework when any new <EPF Device> is
created)
-
- .. <EPF Driver1>/
- ... <EPF Device 11>/
- ... vendorid
- ... deviceid
- ... revid
- ... progif_code
- ... subclass_code
- ... baseclass_code
- ... cache_line_size
- ... subsys_vendor_id
- ... subsys_id
- ... interrupt_pin
-
-*) EPC Device
+::
+
+ .. <EPF Driver1>/
+ ... <EPF Device 11>/
+ ... vendorid
+ ... deviceid
+ ... revid
+ ... progif_code
+ ... subclass_code
+ ... baseclass_code
+ ... cache_line_size
+ ... subsys_vendor_id
+ ... subsys_id
+ ... interrupt_pin
+
+EPC Device
+==========

Every registered EPC device will be listed in controllers directory. The
entries corresponding to EPC device will be created by the EPC core.
-
-/sys/kernel/config/pci_ep/controllers/
- .. <EPC Device1>/
- ... <Symlink EPF Device11>/
- ... <Symlink EPF Device12>/
- ... start
- .. <EPC Device2>/
- ... <Symlink EPF Device21>/
- ... <Symlink EPF Device22>/
- ... start
+::
+
+ /sys/kernel/config/pci_ep/controllers/
+ .. <EPC Device1>/
+ ... <Symlink EPF Device11>/
+ ... <Symlink EPF Device12>/
+ ... start
+ .. <EPC Device2>/
+ ... <Symlink EPF Device21>/
+ ... <Symlink EPF Device22>/
+ ... start

The <EPC Device> directory will have a list of symbolic links to
<EPF Device>. These symbolic links should be created by the user to
@@ -81,7 +94,7 @@ The <EPC Device> directory will also have a *start* field. Once
"1" is written to this field, the endpoint device will be ready to
establish the link with the host. This is usually done after
all the EPF devices are created and linked with the EPC device.
-
+::

| controllers/
| <Directory: EPC name>/
@@ -102,4 +115,4 @@ all the EPF devices are created and linked with the EPC device.
| interrupt_pin
| function

-[1] -> Documentation/PCI/endpoint/pci-endpoint.txt
+[1] :doc:`pci-endpoint`
--
2.20.1

2019-05-13 16:00:15

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 01/12] Documentation: add Linux PCI to Sphinx TOC tree

Add a index.rst for PCI subsystem. More docs will be added later.

Signed-off-by: Changbin Du <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
---
Documentation/PCI/index.rst | 9 +++++++++
Documentation/index.rst | 1 +
2 files changed, 10 insertions(+)
create mode 100644 Documentation/PCI/index.rst

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
new file mode 100644
index 000000000000..c2f8728d11cf
--- /dev/null
+++ b/Documentation/PCI/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+Linux PCI Bus Subsystem
+=======================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9e01aace4f48..fb6477a692b8 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -101,6 +101,7 @@ needed).
filesystems/index
vm/index
bpf/index
+ PCI/index
misc-devices/index

Architecture-specific documentation
--
2.20.1

2019-05-13 16:27:32

by Mauro Carvalho Chehab

[permalink] [raw]
Subject: Re: [PATCH v5 09/12] Documentation: PCI: convert endpoint/pci-endpoint.txt to reST

Em Mon, 13 May 2019 22:19:57 +0800
Changbin Du <[email protected]> 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 <[email protected]>
> Acked-by: Bjorn Helgaas <[email protected]>
> ---
> Documentation/PCI/endpoint/index.rst | 10 ++
> .../{pci-endpoint.txt => pci-endpoint.rst} | 96 +++++++++++--------
> Documentation/PCI/index.rst | 1 +
> 3 files changed, 69 insertions(+), 38 deletions(-)
> create mode 100644 Documentation/PCI/endpoint/index.rst
> rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (82%)
>
> diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
> new file mode 100644
> index 000000000000..0db4f2fcd7f0
> --- /dev/null
> +++ b/Documentation/PCI/endpoint/index.rst
> @@ -0,0 +1,10 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================
> +PCI Endpoint Framework
> +======================
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + pci-endpoint
> diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt b/Documentation/PCI/endpoint/pci-endpoint.rst
> similarity index 82%
> rename from Documentation/PCI/endpoint/pci-endpoint.txt
> rename to Documentation/PCI/endpoint/pci-endpoint.rst
> index e86a96b66a6a..693f3a2ad7a4 100644
> --- a/Documentation/PCI/endpoint/pci-endpoint.txt
> +++ b/Documentation/PCI/endpoint/pci-endpoint.rst
> @@ -1,11 +1,17 @@
> - PCI ENDPOINT FRAMEWORK
> - Kishon Vijay Abraham I <[email protected]>
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================
> +PCI Endpoint Framework
> +======================

This will create a chapter called: "PCI Endpoint Framework" inside a
section named "PCI Endpoint Framework". This is redundant.

Just remove the title here keeping it only at the index file.

With such change:
Reviewed-by: Mauro Carvalho Chehab <[email protected]>

> +
> +:Author: Kishon Vijay Abraham I <[email protected]>
>
> This document is a guide to use the PCI Endpoint Framework in order to create
> endpoint controller driver, endpoint function driver, and using configfs
> interface to bind the function driver to the controller driver.
>
> -1. Introduction
> +Introduction
> +============
>
> Linux has a comprehensive PCI subsystem to support PCI controllers that
> operates in Root Complex mode. The subsystem has capability to scan PCI bus,
> @@ -19,26 +25,30 @@ add endpoint mode support in Linux. This will help to run Linux in an
> EP system which can have a wide variety of use cases from testing or
> validation, co-processor accelerator, etc.
>
> -2. PCI Endpoint Core
> +PCI Endpoint Core
> +=================
>
> The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
> library, the Endpoint Function library, and the configfs layer to bind the
> endpoint function with the endpoint controller.
>
> -2.1 PCI Endpoint Controller(EPC) Library
> +PCI Endpoint Controller(EPC) Library
> +------------------------------------
>
> The EPC library provides APIs to be used by the controller that can operate
> in endpoint mode. It also provides APIs to be used by function driver/library
> in order to implement a particular endpoint function.
>
> -2.1.1 APIs for the PCI controller Driver
> +APIs for the PCI controller Driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> This section lists the APIs that the PCI Endpoint core provides to be used
> by the PCI controller driver.
>
> -*) devm_pci_epc_create()/pci_epc_create()
> +* devm_pci_epc_create()/pci_epc_create()
>
> The PCI controller driver should implement the following ops:
> +
> * write_header: ops to populate configuration space header
> * set_bar: ops to configure the BAR
> * clear_bar: ops to reset the BAR
> @@ -51,110 +61,116 @@ by the PCI controller driver.
> The PCI controller driver can then create a new EPC device by invoking
> devm_pci_epc_create()/pci_epc_create().
>
> -*) devm_pci_epc_destroy()/pci_epc_destroy()
> +* devm_pci_epc_destroy()/pci_epc_destroy()
>
> The PCI controller driver can destroy the EPC device created by either
> devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
> pci_epc_destroy().
>
> -*) pci_epc_linkup()
> +* pci_epc_linkup()
>
> In order to notify all the function devices that the EPC device to which
> they are linked has established a link with the host, the PCI controller
> driver should invoke pci_epc_linkup().
>
> -*) pci_epc_mem_init()
> +* pci_epc_mem_init()
>
> Initialize the pci_epc_mem structure used for allocating EPC addr space.
>
> -*) pci_epc_mem_exit()
> +* pci_epc_mem_exit()
>
> Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
>
> -2.1.2 APIs for the PCI Endpoint Function Driver
> +
> +APIs for the PCI Endpoint Function Driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> This section lists the APIs that the PCI Endpoint core provides to be used
> by the PCI endpoint function driver.
>
> -*) pci_epc_write_header()
> +* pci_epc_write_header()
>
> The PCI endpoint function driver should use pci_epc_write_header() to
> write the standard configuration header to the endpoint controller.
>
> -*) pci_epc_set_bar()
> +* pci_epc_set_bar()
>
> The PCI endpoint function driver should use pci_epc_set_bar() to configure
> the Base Address Register in order for the host to assign PCI addr space.
> Register space of the function driver is usually configured
> using this API.
>
> -*) pci_epc_clear_bar()
> +* pci_epc_clear_bar()
>
> The PCI endpoint function driver should use pci_epc_clear_bar() to reset
> the BAR.
>
> -*) pci_epc_raise_irq()
> +* pci_epc_raise_irq()
>
> The PCI endpoint function driver should use pci_epc_raise_irq() to raise
> Legacy Interrupt, MSI or MSI-X Interrupt.
>
> -*) pci_epc_mem_alloc_addr()
> +* pci_epc_mem_alloc_addr()
>
> The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
> allocate memory address from EPC addr space which is required to access
> RC's buffer
>
> -*) pci_epc_mem_free_addr()
> +* pci_epc_mem_free_addr()
>
> The PCI endpoint function driver should use pci_epc_mem_free_addr() to
> free the memory space allocated using pci_epc_mem_alloc_addr().
>
> -2.1.3 Other APIs
> +Other APIs
> +~~~~~~~~~~
>
> There are other APIs provided by the EPC library. These are used for binding
> the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
> using these APIs.
>
> -*) pci_epc_get()
> +* pci_epc_get()
>
> Get a reference to the PCI endpoint controller based on the device name of
> the controller.
>
> -*) pci_epc_put()
> +* pci_epc_put()
>
> Release the reference to the PCI endpoint controller obtained using
> pci_epc_get()
>
> -*) pci_epc_add_epf()
> +* pci_epc_add_epf()
>
> Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
> can have up to 8 functions according to the specification.
>
> -*) pci_epc_remove_epf()
> +* pci_epc_remove_epf()
>
> Remove the PCI endpoint function from PCI endpoint controller.
>
> -*) pci_epc_start()
> +* pci_epc_start()
>
> The PCI endpoint function driver should invoke pci_epc_start() once it
> has configured the endpoint function and wants to start the PCI link.
>
> -*) pci_epc_stop()
> +* pci_epc_stop()
>
> The PCI endpoint function driver should invoke pci_epc_stop() to stop
> the PCI LINK.
>
> -2.2 PCI Endpoint Function(EPF) Library
> +
> +PCI Endpoint Function(EPF) Library
> +----------------------------------
>
> The EPF library provides APIs to be used by the function driver and the EPC
> library to provide endpoint mode functionality.
>
> -2.2.1 APIs for the PCI Endpoint Function Driver
> +APIs for the PCI Endpoint Function Driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> This section lists the APIs that the PCI Endpoint core provides to be used
> by the PCI endpoint function driver.
>
> -*) pci_epf_register_driver()
> +* pci_epf_register_driver()
>
> The PCI Endpoint Function driver should implement the following ops:
> * bind: ops to perform when a EPC device has been bound to EPF device
> @@ -166,50 +182,54 @@ by the PCI endpoint function driver.
> The PCI Function driver can then register the PCI EPF driver by using
> pci_epf_register_driver().
>
> -*) pci_epf_unregister_driver()
> +* pci_epf_unregister_driver()
>
> The PCI Function driver can unregister the PCI EPF driver by using
> pci_epf_unregister_driver().
>
> -*) pci_epf_alloc_space()
> +* pci_epf_alloc_space()
>
> The PCI Function driver can allocate space for a particular BAR using
> pci_epf_alloc_space().
>
> -*) pci_epf_free_space()
> +* pci_epf_free_space()
>
> The PCI Function driver can free the allocated space
> (using pci_epf_alloc_space) by invoking pci_epf_free_space().
>
> -2.2.2 APIs for the PCI Endpoint Controller Library
> +APIs for the PCI Endpoint Controller Library
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> This section lists the APIs that the PCI Endpoint core provides to be used
> by the PCI endpoint controller library.
>
> -*) pci_epf_linkup()
> +* pci_epf_linkup()
>
> The PCI endpoint controller library invokes pci_epf_linkup() when the
> EPC device has established the connection to the host.
>
> -2.2.2 Other APIs
> +Other APIs
> +~~~~~~~~~~
> +
> There are other APIs provided by the EPF library. These are used to notify
> the function driver when the EPF device is bound to the EPC device.
> pci-ep-cfs.c can be used as reference for using these APIs.
>
> -*) pci_epf_create()
> +* pci_epf_create()
>
> Create a new PCI EPF device by passing the name of the PCI EPF device.
> This name will be used to bind the the EPF device to a EPF driver.
>
> -*) pci_epf_destroy()
> +* pci_epf_destroy()
>
> Destroy the created PCI EPF device.
>
> -*) pci_epf_bind()
> +* pci_epf_bind()
>
> pci_epf_bind() should be invoked when the EPF device has been bound to
> a EPC device.
>
> -*) pci_epf_unbind()
> +* pci_epf_unbind()
>
> pci_epf_unbind() should be invoked when the binding between EPC device
> and EPF device is lost.
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index f54b65b1ca5f..f4c6121868c3 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -15,3 +15,4 @@ Linux PCI Bus Subsystem
> acpi-info
> pci-error-recovery
> pcieaer-howto
> + endpoint/index



Thanks,
Mauro

2019-05-13 17:16:22

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 07/12] Documentation: PCI: convert pci-error-recovery.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
---
Documentation/PCI/index.rst | 1 +
...or-recovery.txt => pci-error-recovery.rst} | 287 +++++++++---------
MAINTAINERS | 4 +-
3 files changed, 152 insertions(+), 140 deletions(-)
rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (67%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 6f573f3df993..92e62d0fc9e6 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -13,3 +13,4 @@ Linux PCI Bus Subsystem
pci-iov-howto
msi-howto
acpi-info
+ pci-error-recovery
diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.rst
similarity index 67%
rename from Documentation/PCI/pci-error-recovery.txt
rename to Documentation/PCI/pci-error-recovery.rst
index 0b6bb3ef449e..83db42092935 100644
--- a/Documentation/PCI/pci-error-recovery.txt
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -1,12 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0

- PCI Error Recovery
- ------------------
- February 2, 2006
+==================
+PCI Error Recovery
+==================

- Current document maintainer:
- Linas Vepstas <[email protected]>
- updated by Richard Lary <[email protected]>
- and Mike Mason <[email protected]> on 27-Jul-2009
+
+:Authors: - Linas Vepstas <[email protected]>
+ - Richard Lary <[email protected]>
+ - Mike Mason <[email protected]>


Many PCI bus controllers are able to detect a variety of hardware
@@ -63,7 +64,8 @@ mechanisms for dealing with SCSI bus errors and SCSI bus resets.


Detailed Design
----------------
+===============
+
Design and implementation details below, based on a chain of
public email discussions with Ben Herrenschmidt, circa 5 April 2005.

@@ -73,30 +75,33 @@ pci_driver. A driver that fails to provide the structure is "non-aware",
and the actual recovery steps taken are platform dependent. The
arch/powerpc implementation will simulate a PCI hotplug remove/add.

-This structure has the form:
-struct pci_error_handlers
-{
- int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
- int (*mmio_enabled)(struct pci_dev *dev);
- int (*slot_reset)(struct pci_dev *dev);
- void (*resume)(struct pci_dev *dev);
-};
-
-The possible channel states are:
-enum pci_channel_state {
- pci_channel_io_normal, /* I/O channel is in normal state */
- pci_channel_io_frozen, /* I/O to channel is blocked */
- pci_channel_io_perm_failure, /* PCI card is dead */
-};
-
-Possible return values are:
-enum pci_ers_result {
- PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
- PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
- PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
- PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
- PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
-};
+This structure has the form::
+
+ struct pci_error_handlers
+ {
+ int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
+ int (*mmio_enabled)(struct pci_dev *dev);
+ int (*slot_reset)(struct pci_dev *dev);
+ void (*resume)(struct pci_dev *dev);
+ };
+
+The possible channel states are::
+
+ enum pci_channel_state {
+ pci_channel_io_normal, /* I/O channel is in normal state */
+ pci_channel_io_frozen, /* I/O to channel is blocked */
+ pci_channel_io_perm_failure, /* PCI card is dead */
+ };
+
+Possible return values are::
+
+ enum pci_ers_result {
+ PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
+ PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
+ PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
+ PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
+ PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
+ };

A driver does not have to implement all of these callbacks; however,
if it implements any, it must implement error_detected(). If a callback
@@ -134,16 +139,17 @@ shouldn't do any new IOs. Called in task context. This is sort of a

All drivers participating in this system must implement this call.
The driver must return one of the following result codes:
- - PCI_ERS_RESULT_CAN_RECOVER:
- Driver returns this if it thinks it might be able to recover
- the HW by just banging IOs or if it wants to be given
- a chance to extract some diagnostic information (see
- mmio_enable, below).
- - PCI_ERS_RESULT_NEED_RESET:
- Driver returns this if it can't recover without a
- slot reset.
- - PCI_ERS_RESULT_DISCONNECT:
- Driver returns this if it doesn't want to recover at all.
+
+ - PCI_ERS_RESULT_CAN_RECOVER
+ Driver returns this if it thinks it might be able to recover
+ the HW by just banging IOs or if it wants to be given
+ a chance to extract some diagnostic information (see
+ mmio_enable, below).
+ - PCI_ERS_RESULT_NEED_RESET
+ Driver returns this if it can't recover without a
+ slot reset.
+ - PCI_ERS_RESULT_DISCONNECT
+ Driver returns this if it doesn't want to recover at all.

The next step taken will depend on the result codes returned by the
drivers.
@@ -159,25 +165,27 @@ then recovery proceeds to STEP 4 (Slot Reset).
If the platform is unable to recover the slot, the next step
is STEP 6 (Permanent Failure).

->>> The current powerpc implementation assumes that a device driver will
->>> *not* schedule or semaphore in this routine; the current powerpc
->>> implementation uses one kernel thread to notify all devices;
->>> thus, if one device sleeps/schedules, all devices are affected.
->>> Doing better requires complex multi-threaded logic in the error
->>> recovery implementation (e.g. waiting for all notification threads
->>> to "join" before proceeding with recovery.) This seems excessively
->>> complex and not worth implementing.
-
->>> The current powerpc implementation doesn't much care if the device
->>> attempts I/O at this point, or not. I/O's will fail, returning
->>> a value of 0xff on read, and writes will be dropped. If more than
->>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH
->>> assumes that the device driver has gone into an infinite loop
->>> and prints an error to syslog. A reboot is then required to
->>> get the device working again.
+.. note::
+
+ The current powerpc implementation assumes that a device driver will
+ *not* schedule or semaphore in this routine; the current powerpc
+ implementation uses one kernel thread to notify all devices;
+ thus, if one device sleeps/schedules, all devices are affected.
+ Doing better requires complex multi-threaded logic in the error
+ recovery implementation (e.g. waiting for all notification threads
+ to "join" before proceeding with recovery.) This seems excessively
+ complex and not worth implementing.
+
+ The current powerpc implementation doesn't much care if the device
+ attempts I/O at this point, or not. I/O's will fail, returning
+ a value of 0xff on read, and writes will be dropped. If more than
+ EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH
+ assumes that the device driver has gone into an infinite loop
+ and prints an error to syslog. A reboot is then required to
+ get the device working again.

STEP 2: MMIO Enabled
--------------------
+--------------------
The platform re-enables MMIO to the device (but typically not the
DMA), and then calls the mmio_enabled() callback on all affected
device drivers.
@@ -192,34 +200,36 @@ link reset was performed by the HW. If the platform can't just re-enable IOs
without a slot reset or a link reset, it will not call this callback, and
instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)

->>> The following is proposed; no platform implements this yet:
->>> Proposal: All I/O's should be done _synchronously_ from within
->>> this callback, errors triggered by them will be returned via
->>> the normal pci_check_whatever() API, no new error_detected()
->>> callback will be issued due to an error happening here. However,
->>> such an error might cause IOs to be re-blocked for the whole
->>> segment, and thus invalidate the recovery that other devices
->>> on the same segment might have done, forcing the whole segment
->>> into one of the next states, that is, link reset or slot reset.
+.. note::
+
+ The following is proposed; no platform implements this yet:
+ Proposal: All I/O's should be done _synchronously_ from within
+ this callback, errors triggered by them will be returned via
+ the normal pci_check_whatever() API, no new error_detected()
+ callback will be issued due to an error happening here. However,
+ such an error might cause IOs to be re-blocked for the whole
+ segment, and thus invalidate the recovery that other devices
+ on the same segment might have done, forcing the whole segment
+ into one of the next states, that is, link reset or slot reset.

The driver should return one of the following result codes:
- - PCI_ERS_RESULT_RECOVERED
- Driver returns this if it thinks the device is fully
- functional and thinks it is ready to start
- normal driver operations again. There is no
- guarantee that the driver will actually be
- allowed to proceed, as another driver on the
- same segment might have failed and thus triggered a
- slot reset on platforms that support it.
-
- - PCI_ERS_RESULT_NEED_RESET
- Driver returns this if it thinks the device is not
- recoverable in its current state and it needs a slot
- reset to proceed.
-
- - PCI_ERS_RESULT_DISCONNECT
- Same as above. Total failure, no recovery even after
- reset driver dead. (To be defined more precisely)
+ - PCI_ERS_RESULT_RECOVERED
+ Driver returns this if it thinks the device is fully
+ functional and thinks it is ready to start
+ normal driver operations again. There is no
+ guarantee that the driver will actually be
+ allowed to proceed, as another driver on the
+ same segment might have failed and thus triggered a
+ slot reset on platforms that support it.
+
+ - PCI_ERS_RESULT_NEED_RESET
+ Driver returns this if it thinks the device is not
+ recoverable in its current state and it needs a slot
+ reset to proceed.
+
+ - PCI_ERS_RESULT_DISCONNECT
+ Same as above. Total failure, no recovery even after
+ reset driver dead. (To be defined more precisely)

The next step taken depends on the results returned by the drivers.
If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
@@ -293,31 +303,33 @@ device will be considered "dead" in this case.
Drivers for multi-function cards will need to coordinate among
themselves as to which driver instance will perform any "one-shot"
or global device initialization. For example, the Symbios sym53cxx2
-driver performs device init only from PCI function 0:
+driver performs device init only from PCI function 0::

-+ if (PCI_FUNC(pdev->devfn) == 0)
-+ sym_reset_scsi_bus(np, 0);
+ + if (PCI_FUNC(pdev->devfn) == 0)
+ + sym_reset_scsi_bus(np, 0);

- Result codes:
- - PCI_ERS_RESULT_DISCONNECT
- Same as above.
+Result codes:
+ - PCI_ERS_RESULT_DISCONNECT
+ Same as above.

Drivers for PCI Express cards that require a fundamental reset must
set the needs_freset bit in the pci_dev structure in their probe function.
For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
-PCI card types:
+PCI card types::

-+ /* Set EEH reset type to fundamental if required by hba */
-+ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
-+ pdev->needs_freset = 1;
-+
+ + /* Set EEH reset type to fundamental if required by hba */
+ + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
+ + pdev->needs_freset = 1;
+ +

Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
Failure).

->>> The current powerpc implementation does not try a power-cycle
->>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
->>> However, it probably should.
+.. note::
+
+ The current powerpc implementation does not try a power-cycle
+ reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
+ However, it probably should.


STEP 5: Resume Operations
@@ -370,44 +382,43 @@ The current policy is to turn this into a platform policy.
That is, the recovery API only requires that:

- There is no guarantee that interrupt delivery can proceed from any
-device on the segment starting from the error detection and until the
-slot_reset callback is called, at which point interrupts are expected
-to be fully operational.
+ device on the segment starting from the error detection and until the
+ slot_reset callback is called, at which point interrupts are expected
+ to be fully operational.

- There is no guarantee that interrupt delivery is stopped, that is,
-a driver that gets an interrupt after detecting an error, or that detects
-an error within the interrupt handler such that it prevents proper
-ack'ing of the interrupt (and thus removal of the source) should just
-return IRQ_NOTHANDLED. It's up to the platform to deal with that
-condition, typically by masking the IRQ source during the duration of
-the error handling. It is expected that the platform "knows" which
-interrupts are routed to error-management capable slots and can deal
-with temporarily disabling that IRQ number during error processing (this
-isn't terribly complex). That means some IRQ latency for other devices
-sharing the interrupt, but there is simply no other way. High end
-platforms aren't supposed to share interrupts between many devices
-anyway :)
-
->>> Implementation details for the powerpc platform are discussed in
->>> the file Documentation/powerpc/eeh-pci-error-recovery.txt
-
->>> As of this writing, there is a growing list of device drivers with
->>> patches implementing error recovery. Not all of these patches are in
->>> mainline yet. These may be used as "examples":
->>>
->>> drivers/scsi/ipr
->>> drivers/scsi/sym53c8xx_2
->>> drivers/scsi/qla2xxx
->>> drivers/scsi/lpfc
->>> drivers/next/bnx2.c
->>> drivers/next/e100.c
->>> drivers/net/e1000
->>> drivers/net/e1000e
->>> drivers/net/ixgb
->>> drivers/net/ixgbe
->>> drivers/net/cxgb3
->>> drivers/net/s2io.c
->>> drivers/net/qlge
-
-The End
--------
+ a driver that gets an interrupt after detecting an error, or that detects
+ an error within the interrupt handler such that it prevents proper
+ ack'ing of the interrupt (and thus removal of the source) should just
+ return IRQ_NOTHANDLED. It's up to the platform to deal with that
+ condition, typically by masking the IRQ source during the duration of
+ the error handling. It is expected that the platform "knows" which
+ interrupts are routed to error-management capable slots and can deal
+ with temporarily disabling that IRQ number during error processing (this
+ isn't terribly complex). That means some IRQ latency for other devices
+ sharing the interrupt, but there is simply no other way. High end
+ platforms aren't supposed to share interrupts between many devices
+ anyway :)
+
+.. note::
+
+ Implementation details for the powerpc platform are discussed in
+ the file Documentation/powerpc/eeh-pci-error-recovery.txt
+
+ As of this writing, there is a growing list of device drivers with
+ patches implementing error recovery. Not all of these patches are in
+ mainline yet. These may be used as "examples":
+
+ - drivers/scsi/ipr
+ - drivers/scsi/sym53c8xx_2
+ - drivers/scsi/qla2xxx
+ - drivers/scsi/lpfc
+ - drivers/next/bnx2.c
+ - drivers/next/e100.c
+ - drivers/net/e1000
+ - drivers/net/e1000e
+ - drivers/net/ixgb
+ - drivers/net/ixgbe
+ - drivers/net/cxgb3
+ - drivers/net/s2io.c
+ - drivers/net/qlge
diff --git a/MAINTAINERS b/MAINTAINERS
index fb9f9d71f7a2..6e5ec5d3987e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12101,7 +12101,7 @@ M: Sam Bobroff <[email protected]>
M: Oliver O'Halloran <[email protected]>
L: [email protected]
S: Supported
-F: Documentation/PCI/pci-error-recovery.txt
+F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
@@ -12114,7 +12114,7 @@ PCI ERROR RECOVERY
M: Linas Vepstas <[email protected]>
L: [email protected]
S: Supported
-F: Documentation/PCI/pci-error-recovery.txt
+F: Documentation/PCI/pci-error-recovery.rst

PCI MSI DRIVER FOR ALTERA MSI IP
M: Ley Foon Tan <[email protected]>
--
2.20.1

2019-05-13 17:19:52

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 11/12] Documentation: PCI: convert endpoint/pci-test-function.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
---
Documentation/PCI/endpoint/index.rst | 1 +
...est-function.txt => pci-test-function.rst} | 34 ++++++++++++-------
2 files changed, 22 insertions(+), 13 deletions(-)
rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (84%)

diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
index 3951de9f923c..b680a3fc4fec 100644
--- a/Documentation/PCI/endpoint/index.rst
+++ b/Documentation/PCI/endpoint/index.rst
@@ -9,3 +9,4 @@ PCI Endpoint Framework

pci-endpoint
pci-endpoint-cfs
+ pci-test-function
diff --git a/Documentation/PCI/endpoint/pci-test-function.txt b/Documentation/PCI/endpoint/pci-test-function.rst
similarity index 84%
rename from Documentation/PCI/endpoint/pci-test-function.txt
rename to Documentation/PCI/endpoint/pci-test-function.rst
index 5916f1f592bb..63148df97232 100644
--- a/Documentation/PCI/endpoint/pci-test-function.txt
+++ b/Documentation/PCI/endpoint/pci-test-function.rst
@@ -1,5 +1,10 @@
- PCI TEST
- Kishon Vijay Abraham I <[email protected]>
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI Test Function
+=================
+
+:Author: Kishon Vijay Abraham I <[email protected]>

Traditionally PCI RC has always been validated by using standard
PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
@@ -23,30 +28,31 @@ The PCI endpoint test device has the following registers:
8) PCI_ENDPOINT_TEST_IRQ_TYPE
9) PCI_ENDPOINT_TEST_IRQ_NUMBER

-*) PCI_ENDPOINT_TEST_MAGIC
+* PCI_ENDPOINT_TEST_MAGIC

This register will be used to test BAR0. A known pattern will be written
and read back from MAGIC register to verify BAR0.

-*) PCI_ENDPOINT_TEST_COMMAND:
+* PCI_ENDPOINT_TEST_COMMAND

This register will be used by the host driver to indicate the function
that the endpoint device must perform.

-Bitfield Description:
+Bitfield Description::
+
Bit 0 : raise legacy IRQ
Bit 1 : raise MSI IRQ
Bit 2 : raise MSI-X IRQ
Bit 3 : read command (read data from RC buffer)
Bit 4 : write command (write data to RC buffer)
- Bit 5 : copy command (copy data from one RC buffer to another
- RC buffer)
+ Bit 5 : copy command (copy data from one RC buffer to another RC buffer)

-*) PCI_ENDPOINT_TEST_STATUS
+* PCI_ENDPOINT_TEST_STATUS

This register reflects the status of the PCI endpoint device.

-Bitfield Description:
+Bitfield Description::
+
Bit 0 : read success
Bit 1 : read fail
Bit 2 : write success
@@ -57,31 +63,33 @@ Bitfield Description:
Bit 7 : source address is invalid
Bit 8 : destination address is invalid

-*) PCI_ENDPOINT_TEST_SRC_ADDR
+* PCI_ENDPOINT_TEST_SRC_ADDR

This register contains the source address (RC buffer address) for the
COPY/READ command.

-*) PCI_ENDPOINT_TEST_DST_ADDR
+* PCI_ENDPOINT_TEST_DST_ADDR

This register contains the destination address (RC buffer address) for
the COPY/WRITE command.

-*) PCI_ENDPOINT_TEST_IRQ_TYPE
+* PCI_ENDPOINT_TEST_IRQ_TYPE

This register contains the interrupt type (Legacy/MSI) triggered
for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.

Possible types:
+
- Legacy : 0
- MSI : 1
- MSI-X : 2

-*) PCI_ENDPOINT_TEST_IRQ_NUMBER
+* PCI_ENDPOINT_TEST_IRQ_NUMBER

This register contains the triggered ID interrupt.

Admissible values:
+
- Legacy : 0
- MSI : [1 .. 32]
- MSI-X : [1 .. 2048]
--
2.20.1

2019-05-13 17:19:52

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 03/12] Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/PCI/index.rst | 1 +
.../{PCIEBUS-HOWTO.txt => picebus-howto.rst} | 140 ++++++++++--------
2 files changed, 82 insertions(+), 59 deletions(-)
rename Documentation/PCI/{PCIEBUS-HOWTO.txt => picebus-howto.rst} (70%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 7babf43709b0..79d6d75bbf28 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -9,3 +9,4 @@ Linux PCI Bus Subsystem
:numbered:

pci
+ picebus-howto
diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/picebus-howto.rst
similarity index 70%
rename from Documentation/PCI/PCIEBUS-HOWTO.txt
rename to Documentation/PCI/picebus-howto.rst
index 15f0bb3b5045..f882ff62c51f 100644
--- a/Documentation/PCI/PCIEBUS-HOWTO.txt
+++ b/Documentation/PCI/picebus-howto.rst
@@ -1,16 +1,23 @@
- The PCI Express Port Bus Driver Guide HOWTO
- Tom L Nguyen [email protected]
- 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 [email protected] 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
--
2.20.1

2019-05-13 17:19:52

by Changbin Du

[permalink] [raw]
Subject: [PATCH v5 08/12] Documentation: PCI: convert pcieaer-howto.txt to reST

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 <[email protected]>
Acked-by: Bjorn Helgaas <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
---
Documentation/PCI/index.rst | 1 +
.../{pcieaer-howto.txt => pcieaer-howto.rst} | 156 +++++++++++-------
2 files changed, 101 insertions(+), 56 deletions(-)
rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (72%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 92e62d0fc9e6..f54b65b1ca5f 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -14,3 +14,4 @@ Linux PCI Bus Subsystem
msi-howto
acpi-info
pci-error-recovery
+ pcieaer-howto
diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.rst
similarity index 72%
rename from Documentation/PCI/pcieaer-howto.txt
rename to Documentation/PCI/pcieaer-howto.rst
index 48ce7903e3c6..18bdefaafd1a 100644
--- a/Documentation/PCI/pcieaer-howto.txt
+++ b/Documentation/PCI/pcieaer-howto.rst
@@ -1,21 +1,29 @@
- The PCI Express Advanced Error Reporting Driver Guide HOWTO
- T. Long Nguyen <[email protected]>
- Yanmin Zhang <[email protected]>
- 07/29/2006
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>

+===========================================================
+The PCI Express Advanced Error Reporting Driver Guide HOWTO
+===========================================================

-1. Overview
+:Authors: - T. Long Nguyen <[email protected]>
+ - Yanmin Zhang <[email protected]>

-1.1 About this guide
+:Copyright: |copy| 2006 Intel Corporation
+
+Overview
+===========
+
+About this guide
+----------------

This guide describes the basics of the PCI Express Advanced Error
Reporting (AER) driver and provides information on how to use it, as
well as how to enable the drivers of endpoint devices to conform with
PCI Express AER driver.

-1.2 Copyright (C) Intel Corporation 2006.

-1.3 What is the PCI Express AER Driver?
+What is the PCI Express AER Driver?
+-----------------------------------

PCI Express error signaling can occur on the PCI Express link itself
or on behalf of transactions initiated on the link. PCI Express
@@ -30,17 +38,19 @@ The PCI Express AER driver provides the infrastructure to support PCI
Express Advanced Error Reporting capability. The PCI Express AER
driver provides three basic functions:

-- Gathers the comprehensive error information if errors occurred.
-- Reports error to the users.
-- Performs error recovery actions.
+ - Gathers the comprehensive error information if errors occurred.
+ - Reports error to the users.
+ - Performs error recovery actions.

AER driver only attaches root ports which support PCI-Express AER
capability.


-2. User Guide
+User Guide
+==========

-2.1 Include the PCI Express AER Root Driver into the Linux Kernel
+Include the PCI Express AER Root Driver into the Linux Kernel
+-------------------------------------------------------------

The PCI Express AER Root driver is a Root Port service driver attached
to the PCI Express Port Bus driver. If a user wants to use it, the driver
@@ -48,7 +58,8 @@ has to be compiled. Option CONFIG_PCIEAER supports this capability. It
depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
CONFIG_PCIEAER = y.

-2.2 Load PCI Express AER Root Driver
+Load PCI Express AER Root Driver
+--------------------------------

Some systems have AER support in firmware. Enabling Linux AER support at
the same time the firmware handles AER may result in unpredictable
@@ -56,30 +67,34 @@ behavior. Therefore, Linux does not handle AER events unless the firmware
grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0
Specification for details regarding _OSC usage.

-2.3 AER error output
+AER error output
+----------------

When a PCIe AER error is captured, an error message will be output to
console. If it's a correctable error, it is output as a warning.
Otherwise, it is printed as an error. So users could choose different
log level to filter out correctable error messages.

-Below shows an example:
-0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
-0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
-0000:50:00.0: [20] Unsupported Request (First)
-0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100
+Below shows an example::
+
+ 0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
+ 0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
+ 0000:50:00.0: [20] Unsupported Request (First)
+ 0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100

In the example, 'Requester ID' means the ID of the device who sends
the error message to root port. Pls. refer to pci express specs for
other fields.

-2.4 AER Statistics / Counters
+AER Statistics / Counters
+-------------------------

When PCIe AER errors are captured, the counters / statistics are also exposed
in the form of sysfs attributes which are documented at
Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats

-3. Developer Guide
+Developer Guide
+===============

To enable AER aware support requires a software driver to configure
the AER capability structure within its device and to provide callbacks.
@@ -120,7 +135,8 @@ hierarchy and links. These errors do not include any device specific
errors because device specific errors will still get sent directly to
the device driver.

-3.1 Configure the AER capability structure
+Configure the AER capability structure
+--------------------------------------

AER aware drivers of PCI Express component need change the device
control registers to enable AER. They also could change AER registers,
@@ -128,9 +144,11 @@ including mask and severity registers. Helper function
pci_enable_pcie_error_reporting could be used to enable AER. See
section 3.3.

-3.2. Provide callbacks
+Provide callbacks
+-----------------

-3.2.1 callback reset_link to reset pci express link
+callback reset_link to reset pci express link
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This callback is used to reset the pci express physical link when a
fatal error happens. The root port aer service driver provides a
@@ -140,13 +158,15 @@ upstream ports should provide their own reset_link functions.

In struct pcie_port_service_driver, a new pointer, reset_link, is
added.
+::

-pci_ers_result_t (*reset_link) (struct pci_dev *dev);
+ pci_ers_result_t (*reset_link) (struct pci_dev *dev);

Section 3.2.2.2 provides more detailed info on when to call
reset_link.

-3.2.2 PCI error-recovery callbacks
+PCI error-recovery callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The PCI Express AER Root driver uses error callbacks to coordinate
with downstream device drivers associated with a hierarchy in question
@@ -161,7 +181,8 @@ definitions of the callbacks.

Below sections specify when to call the error callback functions.

-3.2.2.1 Correctable errors
+Correctable errors
+~~~~~~~~~~~~~~~~~~

Correctable errors pose no impacts on the functionality of
the interface. The PCI Express protocol can recover without any
@@ -169,13 +190,16 @@ software intervention or any loss of data. These errors do not
require any recovery actions. The AER driver clears the device's
correctable error status register accordingly and logs these errors.

-3.2.2.2 Non-correctable (non-fatal and fatal) errors
+Non-correctable (non-fatal and fatal) errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If an error message indicates a non-fatal error, performing link reset
at upstream is not required. The AER driver calls error_detected(dev,
pci_channel_io_normal) to all drivers associated within a hierarchy in
-question. for example,
-EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort.
+question. for example::
+
+ EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort
+
If Upstream port A captures an AER error, the hierarchy consists of
Downstream port B and EndPoint.

@@ -199,53 +223,72 @@ function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
to mmio_enabled.

-3.3 helper functions
+helper functions
+----------------
+::
+
+ int pci_enable_pcie_error_reporting(struct pci_dev *dev);

-3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev);
pci_enable_pcie_error_reporting enables the device to send error
messages to root port when an error is detected. Note that devices
don't enable the error reporting by default, so device drivers need
call this function to enable it.

-3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev);
+::
+
+ int pci_disable_pcie_error_reporting(struct pci_dev *dev);
+
pci_disable_pcie_error_reporting disables the device to send error
messages to root port when an error is detected.

-3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);
+::
+
+ int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);`
+
pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
error status register.

-3.4 Frequent Asked Questions
+Frequent Asked Questions
+------------------------

-Q: What happens if a PCI Express device driver does not provide an
-error recovery handler (pci_driver->err_handler is equal to NULL)?
+Q:
+ What happens if a PCI Express device driver does not provide an
+ error recovery handler (pci_driver->err_handler is equal to NULL)?

-A: The devices attached with the driver won't be recovered. If the
-error is fatal, kernel will print out warning messages. Please refer
-to section 3 for more information.
+A:
+ The devices attached with the driver won't be recovered. If the
+ error is fatal, kernel will print out warning messages. Please refer
+ to section 3 for more information.

-Q: What happens if an upstream port service driver does not provide
-callback reset_link?
+Q:
+ What happens if an upstream port service driver does not provide
+ callback reset_link?

-A: Fatal error recovery will fail if the errors are reported by the
-upstream ports who are attached by the service driver.
+A:
+ Fatal error recovery will fail if the errors are reported by the
+ upstream ports who are attached by the service driver.

-Q: How does this infrastructure deal with driver that is not PCI
-Express aware?
+Q:
+ How does this infrastructure deal with driver that is not PCI
+ Express aware?

-A: This infrastructure calls the error callback functions of the
-driver when an error happens. But if the driver is not aware of
-PCI Express, the device might not report its own errors to root
-port.
+A:
+ This infrastructure calls the error callback functions of the
+ driver when an error happens. But if the driver is not aware of
+ PCI Express, the device might not report its own errors to root
+ port.

-Q: What modifications will that driver need to make it compatible
-with the PCI Express AER Root driver?
+Q:
+ What modifications will that driver need to make it compatible
+ with the PCI Express AER Root driver?

-A: It could call the helper functions to enable AER in devices and
-cleanup uncorrectable status register. Pls. refer to section 3.3.
+A:
+ It could call the helper functions to enable AER in devices and
+ cleanup uncorrectable status register. Pls. refer to section 3.3.


-4. Software error injection
+Software error injection
+========================

Debugging PCIe AER error recovery code is quite difficult because it
is hard to trigger real hardware errors. Software based error
@@ -261,6 +304,7 @@ After reboot with new kernel or insert the module, a device file named

Then, you need a user space tool named aer-inject, which can be gotten
from:
+
https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/

More information about aer-inject can be found in the document comes
--
2.20.1

2019-05-14 14:36:57

by Changbin Du

[permalink] [raw]
Subject: Re: [PATCH v5 09/12] Documentation: PCI: convert endpoint/pci-endpoint.txt to reST

On Mon, May 13, 2019 at 12:01:54PM -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 13 May 2019 22:19:57 +0800
> Changbin Du <[email protected]> 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 <[email protected]>
> > Acked-by: Bjorn Helgaas <[email protected]>
> > ---
> > Documentation/PCI/endpoint/index.rst | 10 ++
> > .../{pci-endpoint.txt => pci-endpoint.rst} | 96 +++++++++++--------
> > Documentation/PCI/index.rst | 1 +
> > 3 files changed, 69 insertions(+), 38 deletions(-)
> > create mode 100644 Documentation/PCI/endpoint/index.rst
> > rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (82%)
> >
> > diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
> > new file mode 100644
> > index 000000000000..0db4f2fcd7f0
> > --- /dev/null
> > +++ b/Documentation/PCI/endpoint/index.rst
> > @@ -0,0 +1,10 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +======================
> > +PCI Endpoint Framework
> > +======================
> > +
> > +.. toctree::
> > + :maxdepth: 2
> > +
> > + pci-endpoint
> > diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt b/Documentation/PCI/endpoint/pci-endpoint.rst
> > similarity index 82%
> > rename from Documentation/PCI/endpoint/pci-endpoint.txt
> > rename to Documentation/PCI/endpoint/pci-endpoint.rst
> > index e86a96b66a6a..693f3a2ad7a4 100644
> > --- a/Documentation/PCI/endpoint/pci-endpoint.txt
> > +++ b/Documentation/PCI/endpoint/pci-endpoint.rst
> > @@ -1,11 +1,17 @@
> > - PCI ENDPOINT FRAMEWORK
> > - Kishon Vijay Abraham I <[email protected]>
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +======================
> > +PCI Endpoint Framework
> > +======================
>
> This will create a chapter called: "PCI Endpoint Framework" inside a
> section named "PCI Endpoint Framework". This is redundant.
>
> Just remove the title here keeping it only at the index file.
>
> With such change:
> Reviewed-by: Mauro Carvalho Chehab <[email protected]>
>
Removed now. Thanks.

> > +
> > +:Author: Kishon Vijay Abraham I <[email protected]>
> >
> > This document is a guide to use the PCI Endpoint Framework in order to create
> > endpoint controller driver, endpoint function driver, and using configfs
> > interface to bind the function driver to the controller driver.
> >
> > -1. Introduction
> > +Introduction
> > +============
> >
> > Linux has a comprehensive PCI subsystem to support PCI controllers that
> > operates in Root Complex mode. The subsystem has capability to scan PCI bus,
> > @@ -19,26 +25,30 @@ add endpoint mode support in Linux. This will help to run Linux in an
> > EP system which can have a wide variety of use cases from testing or
> > validation, co-processor accelerator, etc.
> >
> > -2. PCI Endpoint Core
> > +PCI Endpoint Core
> > +=================
> >
> > The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
> > library, the Endpoint Function library, and the configfs layer to bind the
> > endpoint function with the endpoint controller.
> >
> > -2.1 PCI Endpoint Controller(EPC) Library
> > +PCI Endpoint Controller(EPC) Library
> > +------------------------------------
> >
> > The EPC library provides APIs to be used by the controller that can operate
> > in endpoint mode. It also provides APIs to be used by function driver/library
> > in order to implement a particular endpoint function.
> >
> > -2.1.1 APIs for the PCI controller Driver
> > +APIs for the PCI controller Driver
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > This section lists the APIs that the PCI Endpoint core provides to be used
> > by the PCI controller driver.
> >
> > -*) devm_pci_epc_create()/pci_epc_create()
> > +* devm_pci_epc_create()/pci_epc_create()
> >
> > The PCI controller driver should implement the following ops:
> > +
> > * write_header: ops to populate configuration space header
> > * set_bar: ops to configure the BAR
> > * clear_bar: ops to reset the BAR
> > @@ -51,110 +61,116 @@ by the PCI controller driver.
> > The PCI controller driver can then create a new EPC device by invoking
> > devm_pci_epc_create()/pci_epc_create().
> >
> > -*) devm_pci_epc_destroy()/pci_epc_destroy()
> > +* devm_pci_epc_destroy()/pci_epc_destroy()
> >
> > The PCI controller driver can destroy the EPC device created by either
> > devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
> > pci_epc_destroy().
> >
> > -*) pci_epc_linkup()
> > +* pci_epc_linkup()
> >
> > In order to notify all the function devices that the EPC device to which
> > they are linked has established a link with the host, the PCI controller
> > driver should invoke pci_epc_linkup().
> >
> > -*) pci_epc_mem_init()
> > +* pci_epc_mem_init()
> >
> > Initialize the pci_epc_mem structure used for allocating EPC addr space.
> >
> > -*) pci_epc_mem_exit()
> > +* pci_epc_mem_exit()
> >
> > Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
> >
> > -2.1.2 APIs for the PCI Endpoint Function Driver
> > +
> > +APIs for the PCI Endpoint Function Driver
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > This section lists the APIs that the PCI Endpoint core provides to be used
> > by the PCI endpoint function driver.
> >
> > -*) pci_epc_write_header()
> > +* pci_epc_write_header()
> >
> > The PCI endpoint function driver should use pci_epc_write_header() to
> > write the standard configuration header to the endpoint controller.
> >
> > -*) pci_epc_set_bar()
> > +* pci_epc_set_bar()
> >
> > The PCI endpoint function driver should use pci_epc_set_bar() to configure
> > the Base Address Register in order for the host to assign PCI addr space.
> > Register space of the function driver is usually configured
> > using this API.
> >
> > -*) pci_epc_clear_bar()
> > +* pci_epc_clear_bar()
> >
> > The PCI endpoint function driver should use pci_epc_clear_bar() to reset
> > the BAR.
> >
> > -*) pci_epc_raise_irq()
> > +* pci_epc_raise_irq()
> >
> > The PCI endpoint function driver should use pci_epc_raise_irq() to raise
> > Legacy Interrupt, MSI or MSI-X Interrupt.
> >
> > -*) pci_epc_mem_alloc_addr()
> > +* pci_epc_mem_alloc_addr()
> >
> > The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
> > allocate memory address from EPC addr space which is required to access
> > RC's buffer
> >
> > -*) pci_epc_mem_free_addr()
> > +* pci_epc_mem_free_addr()
> >
> > The PCI endpoint function driver should use pci_epc_mem_free_addr() to
> > free the memory space allocated using pci_epc_mem_alloc_addr().
> >
> > -2.1.3 Other APIs
> > +Other APIs
> > +~~~~~~~~~~
> >
> > There are other APIs provided by the EPC library. These are used for binding
> > the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
> > using these APIs.
> >
> > -*) pci_epc_get()
> > +* pci_epc_get()
> >
> > Get a reference to the PCI endpoint controller based on the device name of
> > the controller.
> >
> > -*) pci_epc_put()
> > +* pci_epc_put()
> >
> > Release the reference to the PCI endpoint controller obtained using
> > pci_epc_get()
> >
> > -*) pci_epc_add_epf()
> > +* pci_epc_add_epf()
> >
> > Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
> > can have up to 8 functions according to the specification.
> >
> > -*) pci_epc_remove_epf()
> > +* pci_epc_remove_epf()
> >
> > Remove the PCI endpoint function from PCI endpoint controller.
> >
> > -*) pci_epc_start()
> > +* pci_epc_start()
> >
> > The PCI endpoint function driver should invoke pci_epc_start() once it
> > has configured the endpoint function and wants to start the PCI link.
> >
> > -*) pci_epc_stop()
> > +* pci_epc_stop()
> >
> > The PCI endpoint function driver should invoke pci_epc_stop() to stop
> > the PCI LINK.
> >
> > -2.2 PCI Endpoint Function(EPF) Library
> > +
> > +PCI Endpoint Function(EPF) Library
> > +----------------------------------
> >
> > The EPF library provides APIs to be used by the function driver and the EPC
> > library to provide endpoint mode functionality.
> >
> > -2.2.1 APIs for the PCI Endpoint Function Driver
> > +APIs for the PCI Endpoint Function Driver
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > This section lists the APIs that the PCI Endpoint core provides to be used
> > by the PCI endpoint function driver.
> >
> > -*) pci_epf_register_driver()
> > +* pci_epf_register_driver()
> >
> > The PCI Endpoint Function driver should implement the following ops:
> > * bind: ops to perform when a EPC device has been bound to EPF device
> > @@ -166,50 +182,54 @@ by the PCI endpoint function driver.
> > The PCI Function driver can then register the PCI EPF driver by using
> > pci_epf_register_driver().
> >
> > -*) pci_epf_unregister_driver()
> > +* pci_epf_unregister_driver()
> >
> > The PCI Function driver can unregister the PCI EPF driver by using
> > pci_epf_unregister_driver().
> >
> > -*) pci_epf_alloc_space()
> > +* pci_epf_alloc_space()
> >
> > The PCI Function driver can allocate space for a particular BAR using
> > pci_epf_alloc_space().
> >
> > -*) pci_epf_free_space()
> > +* pci_epf_free_space()
> >
> > The PCI Function driver can free the allocated space
> > (using pci_epf_alloc_space) by invoking pci_epf_free_space().
> >
> > -2.2.2 APIs for the PCI Endpoint Controller Library
> > +APIs for the PCI Endpoint Controller Library
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > This section lists the APIs that the PCI Endpoint core provides to be used
> > by the PCI endpoint controller library.
> >
> > -*) pci_epf_linkup()
> > +* pci_epf_linkup()
> >
> > The PCI endpoint controller library invokes pci_epf_linkup() when the
> > EPC device has established the connection to the host.
> >
> > -2.2.2 Other APIs
> > +Other APIs
> > +~~~~~~~~~~
> > +
> > There are other APIs provided by the EPF library. These are used to notify
> > the function driver when the EPF device is bound to the EPC device.
> > pci-ep-cfs.c can be used as reference for using these APIs.
> >
> > -*) pci_epf_create()
> > +* pci_epf_create()
> >
> > Create a new PCI EPF device by passing the name of the PCI EPF device.
> > This name will be used to bind the the EPF device to a EPF driver.
> >
> > -*) pci_epf_destroy()
> > +* pci_epf_destroy()
> >
> > Destroy the created PCI EPF device.
> >
> > -*) pci_epf_bind()
> > +* pci_epf_bind()
> >
> > pci_epf_bind() should be invoked when the EPF device has been bound to
> > a EPC device.
> >
> > -*) pci_epf_unbind()
> > +* pci_epf_unbind()
> >
> > pci_epf_unbind() should be invoked when the binding between EPC device
> > and EPF device is lost.
> > diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> > index f54b65b1ca5f..f4c6121868c3 100644
> > --- a/Documentation/PCI/index.rst
> > +++ b/Documentation/PCI/index.rst
> > @@ -15,3 +15,4 @@ Linux PCI Bus Subsystem
> > acpi-info
> > pci-error-recovery
> > pcieaer-howto
> > + endpoint/index
>
>
>
> Thanks,
> Mauro

--
Cheers,
Changbin Du