[PATCH 00/12] Include linux PCI docs into Sphinx TOC tree

[PATCH 00/12] Include linux PCI docs into Sphinx TOC tree

[Changbin Du]

Hi Corbet,
I also did the conversion for PCI documentation. Please check, Thanks!

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://104.238.181.70:8080/kernel-doc/PCI/index.html

Thank you!

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

 .../PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst}      |  56 +++--
 .../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst}  | 112 +++++----
 .../PCI/{acpi-info.txt => acpi-info.rst}      |  11 +-
 Documentation/PCI/endpoint/index.rst          |  13 ++
 ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++++----
 .../{pci-endpoint.txt => pci-endpoint.rst}    |  74 +++---
 ...est-function.txt => pci-test-function.rst} |  32 +--
 ...{pci-test-howto.txt => pci-test-howto.rst} |  51 ++--
 Documentation/PCI/index.rst                   |  17 ++
 ...or-recovery.txt => pci-error-recovery.rst} | 180 ++++++++-------
 .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 144 +++++++-----
 Documentation/PCI/{pci.txt => pci.rst}        | 218 +++++++++---------
 .../{pcieaer-howto.txt => pcieaer-howto.rst}  |  67 ++++--
 Documentation/index.rst                       |   1 +
 MAINTAINERS                                   |   2 +-
 15 files changed, 641 insertions(+), 436 deletions(-)
 rename Documentation/PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst} (89%)
 rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (75%)
 rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (97%)
 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} (86%)
 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} (83%)
 create mode 100644 Documentation/PCI/index.rst
 rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (80%)
 rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (65%)
 rename Documentation/PCI/{pci.txt => pci.rst} (80%)
 rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (83%)

-- 
2.20.1

[PATCH 01/12] Documentation: add Linux PCI to Sphinx TOC tree

[Changbin Du]

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

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/index.rst | 8 ++++++++
 Documentation/index.rst     | 1 +
 2 files changed, 9 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..11096447f535
--- /dev/null
+++ b/Documentation/PCI/index.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+Linux PCI Bus Subsystem
+=======================
+
+.. toctree::
+   :maxdepth: 2
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e3aa28275894..35fc03526b3b 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -91,6 +91,7 @@ needed).
    vm/index
    bpf/index
    acpi/index
+   PCI/index
    misc-devices/index
 
 Architecture-specific documentation
-- 
2.20.1

[PATCH 02/12] pci doc: convert PCI/pci.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/index.rst            |   2 +
 Documentation/PCI/{pci.txt => pci.rst} | 218 +++++++++++++------------
 2 files changed, 116 insertions(+), 104 deletions(-)
 rename Documentation/PCI/{pci.txt => pci.rst} (80%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 11096447f535..06fce3d3c7da 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -6,3 +6,5 @@ Linux PCI Bus Subsystem
 
 .. toctree::
    :maxdepth: 2
+
+   pci
diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.rst
similarity index 80%
rename from Documentation/PCI/pci.txt
rename to Documentation/PCI/pci.rst
index badb26ac33dc..26542559bc4e 100644
--- a/Documentation/PCI/pci.txt
+++ b/Documentation/PCI/pci.rst
@@ -1,10 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-			How To Write Linux PCI Drivers
+==============================
+How To Write Linux PCI Drivers
+==============================
 
-		by Martin Mares <mj@ucw.cz> on 07-Feb-2000
-	updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006
+:Authors: - Martin Mares <mj@ucw.cz> on 07-Feb-2000,
+          - updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The world of PCI is vast and full of (mostly unpleasant) surprises.
 Since each CPU architecture implements different chip-sets and PCI devices
 have different requirements (erm, "features"), the result is the PCI support
@@ -27,7 +29,7 @@ Please send questions/comments/patches about Linux PCI API to the
 
 
 0. Structure of PCI drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================
 PCI drivers "discover" PCI devices in a system via pci_register_driver().
 Actually, it's the other way around. When the PCI generic code discovers
 a new device, the driver with a matching "description" will be notified.
@@ -42,24 +44,25 @@ pointers and thus dictates the high level structure of a driver.
 Once the driver knows about a PCI device and takes ownership, the
 driver generally needs to perform the following initialization:
 
-	Enable the device
-	Request MMIO/IOP resources
-	Set the DMA mask size (for both coherent and streaming DMA)
-	Allocate and initialize shared control data (pci_allocate_coherent())
-	Access device configuration space (if needed)
-	Register IRQ handler (request_irq())
-	Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
-	Enable DMA/processing engines
+  - Enable the device
+  - Request MMIO/IOP resources
+  - Set the DMA mask size (for both coherent and streaming DMA)
+  - Allocate and initialize shared control data (pci_allocate_coherent())
+  - Access device configuration space (if needed)
+  - Register IRQ handler (request_irq())
+  - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
+  - Enable DMA/processing engines
 
 When done using the device, and perhaps the module needs to be unloaded,
 the driver needs to take the follow steps:
-	Disable the device from generating IRQs
-	Release the IRQ (free_irq())
-	Stop all DMA activity
-	Release DMA buffers (both streaming and coherent)
-	Unregister from other subsystems (e.g. scsi or netdev)
-	Release MMIO/IOP resources
-	Disable the device
+
+  - Disable the device from generating IRQs
+  - Release the IRQ (free_irq())
+  - Stop all DMA activity
+  - Release DMA buffers (both streaming and coherent)
+  - Unregister from other subsystems (e.g. scsi or netdev)
+  - Release MMIO/IOP resources
+  - Disable the device
 
 Most of these topics are covered in the following sections.
 For the rest look at LDD3 or <linux/pci.h> .
@@ -72,11 +75,11 @@ lots of ifdefs in the drivers.
 
 
 1. pci_register_driver() call
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
 
 PCI device drivers call pci_register_driver() during their
 initialization with a pointer to a structure describing the driver
-(struct pci_driver):
+(struct pci_driver)::
 
 	field name	Description
 	----------	------------------------------------------------------
@@ -125,7 +128,7 @@ initialization with a pointer to a structure describing the driver
 The ID table is an array of struct pci_device_id entries ending with an
 all-zero entry.  Definitions with static const are generally preferred.
 
-Each entry consists of:
+Each entry consists of::
 
 	vendor,device	Vendor and device ID to match (or PCI_ANY_ID)
 
@@ -160,9 +163,10 @@ echo "vendor device subvendor subdevice class class_mask driver_data" > \
 All fields are passed in as hexadecimal values (no leading 0x).
 The vendor and device fields are mandatory, the others are optional. Users
 need pass only as many optional fields as necessary:
-	o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
-	o class and classmask fields default to 0
-	o driver_data defaults to 0UL.
+
+  - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
+  - class and classmask fields default to 0
+  - driver_data defaults to 0UL.
 
 Note that driver_data must match the value used by any of the pci_device_id
 entries defined in the driver. This makes the driver_data field mandatory
@@ -176,28 +180,29 @@ automatically calls the remove hook for all devices handled by the driver.
 
 
 1.1 "Attributes" for driver functions/data
+------------------------------------------
 
 Please mark the initialization and cleanup functions where appropriate
-(the corresponding macros are defined in <linux/init.h>):
+(the corresponding macros are defined in <linux/init.h>)::
 
 	__init		Initialization code. Thrown away after the driver
 			initializes.
 	__exit		Exit code. Ignored for non-modular drivers.
 
 Tips on when/where to use the above attributes:
-	o The module_init()/module_exit() functions (and all
+	- The module_init()/module_exit() functions (and all
 	  initialization functions called _only_ from these)
 	  should be marked __init/__exit.
 
-	o Do not mark the struct pci_driver.
+	- Do not mark the struct pci_driver.
 
-	o Do NOT mark a function if you are not sure which mark to use.
+	- Do NOT mark a function if you are not sure which mark to use.
 	  Better to not mark the function than mark the function wrong.
 
 
 
 2. How to find PCI devices manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===================================
 
 PCI drivers should have a really good reason for not using the
 pci_register_driver() interface to search for PCI devices.
@@ -207,17 +212,17 @@ E.g. combined serial/parallel port/floppy controller.
 
 A manual search may be performed using the following constructs:
 
-Searching by vendor and device ID:
+Searching by vendor and device ID::
 
 	struct pci_dev *dev = NULL;
 	while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
 		configure_device(dev);
 
-Searching by class ID (iterate in a similar way):
+Searching by class ID (iterate in a similar way)::
 
 	pci_get_class(CLASS_ID, dev)
 
-Searching by both vendor/device and subsystem vendor/device ID:
+Searching by both vendor/device and subsystem vendor/device ID::
 
 	pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
 
@@ -232,19 +237,19 @@ decrement the reference count on these devices by calling pci_dev_put().
 
 
 3. Device Initialization Steps
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==============================
 
 As noted in the introduction, most PCI drivers need the following steps
 for device initialization:
 
-	Enable the device
-	Request MMIO/IOP resources
-	Set the DMA mask size (for both coherent and streaming DMA)
-	Allocate and initialize shared control data (pci_allocate_coherent())
-	Access device configuration space (if needed)
-	Register IRQ handler (request_irq())
-	Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
-	Enable DMA/processing engines.
+  - Enable the device
+  - Request MMIO/IOP resources
+  - Set the DMA mask size (for both coherent and streaming DMA)
+  - Allocate and initialize shared control data (pci_allocate_coherent())
+  - Access device configuration space (if needed)
+  - Register IRQ handler (request_irq())
+  - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
+  - Enable DMA/processing engines.
 
 The driver can access PCI config space registers at any time.
 (Well, almost. When running BIST, config space can go away...but
@@ -253,16 +258,17 @@ will return garbage).
 
 
 3.1 Enable the PCI device
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 Before touching any device registers, the driver needs to enable
 the PCI device by calling pci_enable_device(). This will:
-	o wake up the device if it was in suspended state,
-	o allocate I/O and memory regions of the device (if BIOS did not),
-	o allocate an IRQ (if BIOS did not).
 
-NOTE: pci_enable_device() can fail! Check the return value.
+  - wake up the device if it was in suspended state,
+  - allocate I/O and memory regions of the device (if BIOS did not),
+  - allocate an IRQ (if BIOS did not).
 
-[ OS BUG: we don't check resource allocations before enabling those
+.. note:: pci_enable_device() can fail! Check the return value.
+
+.. warning:: OS BUG: we don't check resource allocations before enabling those
   resources. The sequence would make more sense if we called
   pci_request_resources() before calling pci_enable_device().
   Currently, the device drivers can't detect the bug when when two
@@ -271,7 +277,7 @@ NOTE: pci_enable_device() can fail! Check the return value.
 
   This has been discussed before but not changed as of 2.6.19:
 	http://lkml.org/lkml/2006/3/2/194
-]
+
 
 pci_set_master() will enable DMA by setting the bus master bit
 in the PCI_COMMAND register. It also fixes the latency timer value if
@@ -289,7 +295,7 @@ Mem-Wr-Inval.
 
 
 3.2 Request MMIO/IOP resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 Memory (MMIO), and I/O port addresses should NOT be read directly
 from the PCI device config space. Use the values in the pci_dev structure
 as the PCI "bus address" might have been remapped to a "host physical"
@@ -304,9 +310,9 @@ Conversely, drivers should call pci_release_region() AFTER
 calling pci_disable_device().
 The idea is to prevent two devices colliding on the same address range.
 
-[ See OS BUG comment above. Currently (2.6.19), The driver can only
+.. tip:: See OS BUG comment above. Currently (2.6.19), The driver can only
   determine MMIO and IO Port resource availability _after_ calling
-  pci_enable_device(). ]
+  pci_enable_device().
 
 Generic flavors of pci_request_region() are request_mem_region()
 (for MMIO ranges) and request_region() (for IO Port ranges).
@@ -317,11 +323,11 @@ Also see pci_request_selected_regions() below.
 
 
 3.3 Set the DMA mask size
-~~~~~~~~~~~~~~~~~~~~~~~~~
-[ If anything below doesn't make sense, please refer to
+-------------------------
+.. note:: If anything below doesn't make sense, please refer to
   Documentation/DMA-API.txt. This section is just a reminder that
   drivers need to indicate DMA capabilities of the device and is not
-  an authoritative source for DMA interfaces. ]
+  an authoritative source for DMA interfaces.
 
 While all drivers should explicitly indicate the DMA capability
 (e.g. 32 or 64 bit) of the PCI bus master, devices with more than
@@ -343,7 +349,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
 
 
 3.4 Setup shared control data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
 memory.  See Documentation/DMA-API.txt for a full description of
 the DMA APIs. This section is just a reminder that it needs to be done
@@ -351,14 +357,14 @@ before enabling DMA on the device.
 
 
 3.5 Initialize device registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 Some drivers will need specific "capability" fields programmed
 or other "vendor specific" register initialized or reset.
 E.g. clearing pending interrupts.
 
 
 3.6 Register IRQ handler
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 While calling request_irq() is the last step described here,
 this is often just another intermediate step to initialize a device.
 This step can often be deferred until the device is opened for use.
@@ -396,6 +402,7 @@ and msix_enabled flags in the pci_dev structure after calling
 pci_alloc_irq_vectors.
 
 There are (at least) two really good reasons for using MSI:
+
 1) MSI is an exclusive interrupt vector by definition.
    This means the interrupt handler doesn't have to verify
    its device caused the interrupt.
@@ -412,22 +419,22 @@ of MSI/MSI-X usage.
 
 
 4. PCI device shutdown
-~~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 When a PCI device driver is being unloaded, most of the following
 steps need to be performed:
 
-	Disable the device from generating IRQs
-	Release the IRQ (free_irq())
-	Stop all DMA activity
-	Release DMA buffers (both streaming and consistent)
-	Unregister from other subsystems (e.g. scsi or netdev)
-	Disable device from responding to MMIO/IO Port addresses
-	Release MMIO/IO Port resource(s)
+  - Disable the device from generating IRQs
+  - Release the IRQ (free_irq())
+  - Stop all DMA activity
+  - Release DMA buffers (both streaming and consistent)
+  - Unregister from other subsystems (e.g. scsi or netdev)
+  - Disable device from responding to MMIO/IO Port addresses
+  - Release MMIO/IO Port resource(s)
 
 
 4.1 Stop IRQs on the device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 How to do this is chip/device specific. If it's not done, it opens
 the possibility of a "screaming interrupt" if (and only if)
 the IRQ is shared with another device.
@@ -447,7 +454,7 @@ are not susceptible to the "screaming interrupt" problem.
 
 
 4.2 Release the IRQ
-~~~~~~~~~~~~~~~~~~~
+-------------------
 Once the device is quiesced (no more IRQs), one can call free_irq().
 This function will return control once any pending IRQs are handled,
 "unhook" the drivers IRQ handler from that IRQ, and finally release
@@ -455,7 +462,7 @@ the IRQ if no one else is using it.
 
 
 4.3 Stop all DMA activity
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 It's extremely important to stop all DMA operations BEFORE attempting
 to deallocate DMA control data. Failure to do so can result in memory
 corruption, hangs, and on some chip-sets a hard crash.
@@ -468,7 +475,7 @@ didn't get this step right in the past.
 
 
 4.4 Release DMA buffers
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 Once DMA is stopped, clean up streaming DMA first.
 I.e. unmap data buffers and return buffers to "upstream"
 owners if there is one.
@@ -479,7 +486,7 @@ See Documentation/DMA-API.txt for details on unmapping interfaces.
 
 
 4.5 Unregister from other subsystems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 Most low level PCI device drivers support some other subsystem
 like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
 driver isn't losing resources from that other subsystem.
@@ -488,30 +495,30 @@ the subsystem attempts to call into a driver that has been unloaded.
 
 
 4.6 Disable Device from responding to MMIO/IO Port addresses
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~-----------------------------------------------------------
 io_unmap() MMIO or IO Port resources and then call pci_disable_device().
 This is the symmetric opposite of pci_enable_device().
 Do not access device registers after calling pci_disable_device().
 
 
 4.7 Release MMIO/IO Port Resource(s)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 Call pci_release_region() to mark the MMIO or IO Port range as available.
 Failure to do so usually results in the inability to reload the driver.
 
 
 
 5. How to access PCI config space
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================
 
-You can use pci_(read|write)_config_(byte|word|dword) to access the config
-space of a device represented by struct pci_dev *. All these functions return 0
-when successful or an error code (PCIBIOS_...) which can be translated to a text
-string by pcibios_strerror. Most drivers expect that accesses to valid PCI
+You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
+space of a device represented by `struct pci_dev *`. All these functions return
+0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
+text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
 devices don't fail.
 
 If you don't have a struct pci_dev available, you can call
-pci_bus_(read|write)_config_(byte|word|dword) to access a given device
+`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
 and function on that bus.
 
 If you access fields in the standard portion of the config header, please
@@ -522,28 +529,29 @@ pci_find_capability() for the particular capability and it will find the
 corresponding register block for you.
 
 
-
 6. Other interesting functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==============================
 
-pci_get_domain_bus_and_slot()	Find pci_dev corresponding to given domain,
-				bus and slot and number. If the device is
-				found, its reference count is increased.
-pci_set_power_state()		Set PCI Power Management state (0=D0 ... 3=D3)
-pci_find_capability()		Find specified capability in device's capability
+::
+
+  pci_get_domain_bus_and_slot()	Find pci_dev corresponding to given domain,
+  				bus and slot and number. If the device is
+  				found, its reference count is increased.
+  pci_set_power_state()		Set PCI Power Management state (0=D0 ... 3=D3)
+  pci_find_capability()		Find specified capability in device's capability
 				list.
-pci_resource_start()		Returns bus start address for a given PCI region
-pci_resource_end()		Returns bus end address for a given PCI region
-pci_resource_len()		Returns the byte length of a PCI region
-pci_set_drvdata()		Set private driver data pointer for a pci_dev
-pci_get_drvdata()		Return private driver data pointer for a pci_dev
-pci_set_mwi()			Enable Memory-Write-Invalidate transactions.
-pci_clear_mwi()			Disable Memory-Write-Invalidate transactions.
+  pci_resource_start()		Returns bus start address for a given PCI region
+  pci_resource_end()		Returns bus end address for a given PCI region
+  pci_resource_len()		Returns the byte length of a PCI region
+  pci_set_drvdata()		Set private driver data pointer for a pci_dev
+  pci_get_drvdata()		Return private driver data pointer for a pci_dev
+  pci_set_mwi()			Enable Memory-Write-Invalidate transactions.
+  pci_clear_mwi()			Disable Memory-Write-Invalidate transactions.
 
 
 
 7. Miscellaneous hints
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 When displaying PCI device names to the user (for example when a driver wants
 to tell the user what card has it found), please use pci_name(pci_dev).
@@ -561,7 +569,7 @@ to be handled by platform and generic code, not individual drivers.
 
 
 8. Vendor and device identifications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+====================================
 
 Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
 are shared across multiple drivers.  You can add private definitions in
@@ -577,17 +585,19 @@ and https://github.com/pciutils/pciids.
 
 
 9. Obsolete functions
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 There are several functions which you might come across when trying to
 port an old driver to the new PCI interface.  They are no longer present
 in the kernel as they aren't compatible with hotplug or PCI domains or
 having sane locking.
 
-pci_find_device()	Superseded by pci_get_device()
-pci_find_subsys()	Superseded by pci_get_subsys()
-pci_find_slot()		Superseded by pci_get_domain_bus_and_slot()
-pci_get_slot()		Superseded by pci_get_domain_bus_and_slot()
+::
+
+  pci_find_device()	Superseded by pci_get_device()
+  pci_find_subsys()	Superseded by pci_get_subsys()
+  pci_find_slot()	Superseded by pci_get_domain_bus_and_slot()
+  pci_get_slot()	Superseded by pci_get_domain_bus_and_slot()
 
 
 The alternative is the traditional PCI device driver that walks PCI
@@ -596,7 +606,7 @@ device lists. This is still possible but discouraged.
 
 
 10. MMIO Space and "Write Posting"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==================================
 
 Converting a driver from using I/O Port space to using MMIO space
 often requires some additional changes. Specifically, "write posting"
@@ -609,14 +619,14 @@ the CPU before the transaction has reached its destination.
 
 Thus, timing sensitive code should add readl() where the CPU is
 expected to wait before doing other work.  The classic "bit banging"
-sequence works fine for I/O Port space:
+sequence works fine for I/O Port space::
 
        for (i = 8; --i; val >>= 1) {
                outb(val & 1, ioport_reg);      /* write bit */
                udelay(10);
        }
 
-The same sequence for MMIO space should be:
+The same sequence for MMIO space should be::
 
        for (i = 8; --i; val >>= 1) {
                writeb(val & 1, mmio_reg);      /* write bit */
-- 
2.20.1

[PATCH 03/12] pci doc: convert PCI/PCIEBUS-HOWTO.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 .../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst}  | 112 +++++++++++-------
 Documentation/PCI/index.rst                   |   1 +
 2 files changed, 68 insertions(+), 45 deletions(-)
 rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (75%)

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

[PATCH 04/12] pci doc: convert PCI/pci-iov-howto.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/index.rst                   |   1 +
 .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 144 ++++++++++--------
 2 files changed, 85 insertions(+), 60 deletions(-)
 rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (65%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 58ce08f14f33..751cd8f23c62 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -9,3 +9,4 @@ Linux PCI Bus Subsystem
 
    pci
    PCIEBUS-HOWTO
+   pci-iov-howto
diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.rst
similarity index 65%
rename from Documentation/PCI/pci-iov-howto.txt
rename to Documentation/PCI/pci-iov-howto.rst
index d2a84151e99c..068e2c93e828 100644
--- a/Documentation/PCI/pci-iov-howto.txt
+++ b/Documentation/PCI/pci-iov-howto.rst
@@ -1,14 +1,20 @@
-		PCI Express I/O Virtualization Howto
-		Copyright (C) 2009 Intel Corporation
-		    Yu Zhao <yu.zhao@intel.com>
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
 
-		Update: November 2012
-			-- sysfs-based SRIOV enable-/disable-ment
-		Donald Dutile <ddutile@redhat.com>
+====================================
+PCI Express I/O Virtualization Howto
+====================================
+
+:Copyright: |copy| 2009 Intel Corporation
+:Authors: - Yu Zhao <yu.zhao@intel.com>
+          - Update: November 2012, sysfs-based SRIOV enable-/disable-ment,
+            Donald Dutile <ddutile@redhat.com>
 
 1. Overview
+===========
 
 1.1 What is SR-IOV
+------------------
 
 Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
 capability which makes one physical device appear as multiple virtual
@@ -24,8 +30,10 @@ operates on the register set so it can be functional and appear as a
 real existing PCI device.
 
 2. User Guide
+=============
 
 2.1 How can I enable SR-IOV capability
+--------------------------------------
 
 Multiple methods are available for SR-IOV enablement.
 In the first method, the device driver (PF driver) will control the
@@ -44,104 +52,120 @@ numvfs <= totalvfs.
 The second method is the recommended method for new/future VF devices.
 
 2.2 How can I use the Virtual Functions
+---------------------------------------
 
 The VF is treated as hot-plugged PCI devices in the kernel, so they
 should be able to work in the same way as real PCI devices. The VF
 requires device driver that is same as a normal PCI device's.
 
 3. Developer Guide
+==================
 
 3.1 SR-IOV API
+--------------
 
 To enable SR-IOV capability:
-(a) For the first method, in the driver:
+(a) For the first method, in the driver::
+
 	int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
-	'nr_virtfn' is number of VFs to be enabled.
-(b) For the second method, from sysfs:
+
+'nr_virtfn' is number of VFs to be enabled.
+
+(b) For the second method, from sysfs::
+
 	echo 'nr_virtfn' > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
 
 To disable SR-IOV capability:
-(a) For the first method, in the driver:
+(a) For the first method, in the driver::
+
 	void pci_disable_sriov(struct pci_dev *dev);
-(b) For the second method, from sysfs:
+
+(b) For the second method, from sysfs::
+
 	echo  0 > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
 
 To enable auto probing VFs by a compatible driver on the host, run
 command below before enabling SR-IOV capabilities. This is the
 default behavior.
+::
+
 	echo 1 > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
 
 To disable auto probing VFs by a compatible driver on the host, run
 command below before enabling SR-IOV capabilities. Updating this
 entry will not affect VFs which are already probed.
+::
+
 	echo  0 > \
         /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
 
 3.2 Usage example
+-----------------
 
 Following piece of code illustrates the usage of the SR-IOV API.
+::
 
-static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
-{
-	pci_enable_sriov(dev, NR_VIRTFN);
+	static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
+	{
+		pci_enable_sriov(dev, NR_VIRTFN);
 
-	...
-
-	return 0;
-}
+		...
 
-static void dev_remove(struct pci_dev *dev)
-{
-	pci_disable_sriov(dev);
+		return 0;
+	}
 
-	...
-}
+	static void dev_remove(struct pci_dev *dev)
+	{
+		pci_disable_sriov(dev);
 
-static int dev_suspend(struct pci_dev *dev, pm_message_t state)
-{
-	...
+		...
+	}
 
-	return 0;
-}
+	static int dev_suspend(struct pci_dev *dev, pm_message_t state)
+	{
+		...
 
-static int dev_resume(struct pci_dev *dev)
-{
-	...
+		return 0;
+	}
 
-	return 0;
-}
+	static int dev_resume(struct pci_dev *dev)
+	{
+		...
 
-static void dev_shutdown(struct pci_dev *dev)
-{
-	...
-}
+		return 0;
+	}
 
-static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
-{
-	if (numvfs > 0) {
-		...
-		pci_enable_sriov(dev, numvfs);
+	static void dev_shutdown(struct pci_dev *dev)
+	{
 		...
-		return numvfs;
 	}
-	if (numvfs == 0) {
-		....
-		pci_disable_sriov(dev);
-		...
-		return 0;
+
+	static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
+	{
+		if (numvfs > 0) {
+			...
+			pci_enable_sriov(dev, numvfs);
+			...
+			return numvfs;
+		}
+		if (numvfs == 0) {
+			....
+			pci_disable_sriov(dev);
+			...
+			return 0;
+		}
 	}
-}
-
-static struct pci_driver dev_driver = {
-	.name =		"SR-IOV Physical Function driver",
-	.id_table =	dev_id_table,
-	.probe =	dev_probe,
-	.remove =	dev_remove,
-	.suspend =	dev_suspend,
-	.resume =	dev_resume,
-	.shutdown =	dev_shutdown,
-	.sriov_configure = dev_sriov_configure,
-};
+
+	static struct pci_driver dev_driver = {
+		.name =		"SR-IOV Physical Function driver",
+		.id_table =	dev_id_table,
+		.probe =	dev_probe,
+		.remove =	dev_remove,
+		.suspend =	dev_suspend,
+		.resume =	dev_resume,
+		.shutdown =	dev_shutdown,
+		.sriov_configure = dev_sriov_configure,
+	};
-- 
2.20.1

[PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 .../PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst}      | 56 ++++++++++++-------
 Documentation/PCI/index.rst                   |  1 +
 2 files changed, 38 insertions(+), 19 deletions(-)
 rename Documentation/PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst} (89%)

diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.rst
similarity index 89%
rename from Documentation/PCI/MSI-HOWTO.txt
rename to Documentation/PCI/MSI-HOWTO.rst
index 618e13d5e276..33f382632fdd 100644
--- a/Documentation/PCI/MSI-HOWTO.txt
+++ b/Documentation/PCI/MSI-HOWTO.rst
@@ -1,13 +1,18 @@
-		The MSI Driver Guide HOWTO
-	Tom L Nguyen tom.l.nguyen@intel.com
-			10/03/2003
-	Revised Feb 12, 2004 by Martine Silbermann
-		email: Martine.Silbermann@hp.com
-	Revised Jun 25, 2004 by Tom L Nguyen
-	Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
-		Copyright 2003, 2008 Intel Corporation
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==========================
+The MSI Driver Guide HOWTO
+==========================
+
+:Authors: - Tom L Nguyen <tom.l.nguyen@intel.com> 10/03/2003
+          - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@hp.com>
+	  - Revised Jun 25, 2004 by Tom L Nguyen
+	  - Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
+	    Copyright 2003, 2008 Intel Corporation
 
 1. About this guide
+===================
 
 This guide describes the basics of Message Signaled Interrupts (MSIs),
 the advantages of using MSI over traditional interrupt mechanisms, how
@@ -16,6 +21,7 @@ try if a device doesn't support MSIs.
 
 
 2. 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.
@@ -30,6 +36,7 @@ a time.
 
 
 3. Why use MSIs?
+================
 
 There are three reasons why using MSIs can give an advantage over
 traditional pin-based interrupts.
@@ -62,6 +69,7 @@ in a network card or each port in a storage controller.
 
 
 4. 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
@@ -69,6 +77,7 @@ 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
+-----------------------------------
 
 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,
@@ -77,13 +86,14 @@ on x86, you must also enable X86_UP_APIC or SMP in order to see the
 CONFIG_PCI_MSI option.
 
 4.2 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 +111,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 +136,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 +145,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,14 +153,14 @@ 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)
@@ -159,7 +169,7 @@ the driver can specify that only MSI or MSI-X is acceptable:
 4.3 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 */
@@ -175,8 +185,10 @@ 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
+----------------------------------
 
 4.4.1 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
@@ -189,6 +201,7 @@ 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
+--------------------------------------------------------
 
 Using 'lspci -v' (as root) may show some devices with "MSI", "Message
 Signalled Interrupts" or "MSI-X" capabilities.  Each of these capabilities
@@ -197,6 +210,7 @@ or "-" (disabled).
 
 
 5. MSI quirks
+=============
 
 Several PCI chipsets or devices are known not to support MSIs.
 The PCI stack provides three ways to disable MSIs:
@@ -206,6 +220,7 @@ The PCI stack provides three ways to disable MSIs:
 3. on a single device
 
 5.1. 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
@@ -220,6 +235,7 @@ in your best interests to report the problem to linux-pci@vger.kernel.org
 including a full 'lspci -v' so we can add the quirks to the kernel.
 
 5.2. 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 +246,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
 
@@ -245,6 +261,7 @@ Again, please notify linux-pci@vger.kernel.org of any bridges that need
 special handling.
 
 5.3. 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
@@ -253,6 +270,7 @@ 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
+----------------------------------------------
 
 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 +278,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.
 
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 751cd8f23c62..8ed57b9ecfe4 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -10,3 +10,4 @@ Linux PCI Bus Subsystem
    pci
    PCIEBUS-HOWTO
    pci-iov-howto
+   MSI-HOWTO
-- 
2.20.1

Re: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format

[Matthew Wilcox]

On Sat, Mar 30, 2019 at 12:04:06AM +0800, Changbin Du wrote:
> @@ -1,13 +1,18 @@
> -		The MSI Driver Guide HOWTO
> -	Tom L Nguyen tom.l.nguyen@intel.com
> -			10/03/2003
> -	Revised Feb 12, 2004 by Martine Silbermann
> -		email: Martine.Silbermann@hp.com
> -	Revised Jun 25, 2004 by Tom L Nguyen
> -	Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> -		Copyright 2003, 2008 Intel Corporation
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +==========================
> +The MSI Driver Guide HOWTO
> +==========================
> +
> +:Authors: - Tom L Nguyen <tom.l.nguyen@intel.com> 10/03/2003
> +          - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@hp.com>
> +	  - Revised Jun 25, 2004 by Tom L Nguyen
> +	  - Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> +	    Copyright 2003, 2008 Intel Corporation

The copyright line doesn't work quite the way it should in the rendered HTML.

It seems to me it should be:

:Copyright: 2003, 2008 Intel Corporation

Tom has used an ambiguous date format; given it appeared in the tree
in December 2003, I suspect he's used middle-endian format.  It doesn't
really seem relevant to have the dates here any more, so we could skip
including them.  Also, none of these email addresses work, so perhaps
just drop those too.

:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox

>  1. About this guide
> +===================

Should we drop the numbering of sections as part of this conversion?
I'd be inclined to.

>  4.2 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);

This should really be turned into kernel-doc and moved to pci.h, but
that seems like an awfully large amount of work to ask you to do when
you're already doing so much to improve the situation.

This is also a really bad document.  It has three audiences; people
configuring their kernel, people writing device drivers and people trying
to debug why their kernel doesn't work.  Again, that's not on you to
fix, but it's pretty frustrating to see so much good information so
badly organised.

Re: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format

[Changbin Du]

On Fri, Mar 29, 2019 at 09:00:09PM -0700, Matthew Wilcox wrote:
> On Sat, Mar 30, 2019 at 12:04:06AM +0800, Changbin Du wrote:
> > @@ -1,13 +1,18 @@
> > -		The MSI Driver Guide HOWTO
> > -	Tom L Nguyen tom.l.nguyen@intel.com
> > -			10/03/2003
> > -	Revised Feb 12, 2004 by Martine Silbermann
> > -		email: Martine.Silbermann@hp.com
> > -	Revised Jun 25, 2004 by Tom L Nguyen
> > -	Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> > -		Copyright 2003, 2008 Intel Corporation
> > +.. SPDX-License-Identifier: GPL-2.0
> > +.. include:: <isonum.txt>
> > +
> > +==========================
> > +The MSI Driver Guide HOWTO
> > +==========================
> > +
> > +:Authors: - Tom L Nguyen <tom.l.nguyen@intel.com> 10/03/2003
> > +          - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@hp.com>
> > +	  - Revised Jun 25, 2004 by Tom L Nguyen
> > +	  - Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> > +	    Copyright 2003, 2008 Intel Corporation
> 
> The copyright line doesn't work quite the way it should in the rendered HTML.
> 
> It seems to me it should be:
> 
> :Copyright: 2003, 2008 Intel Corporation
> 
> Tom has used an ambiguous date format; given it appeared in the tree
> in December 2003, I suspect he's used middle-endian format.  It doesn't
> really seem relevant to have the dates here any more, so we could skip
> including them.  Also, none of these email addresses work, so perhaps
> just drop those too.
> 
> :Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
>
yeah, looks better. Thanks.

> >  1. About this guide
> > +===================
> 
> Should we drop the numbering of sections as part of this conversion?
> I'd be inclined to.
>
yes, sphix can generate the numbering.

> >  4.2 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);
> 
> This should really be turned into kernel-doc and moved to pci.h, but
> that seems like an awfully large amount of work to ask you to do when
> you're already doing so much to improve the situation.
> 
> This is also a really bad document.  It has three audiences; people
> configuring their kernel, people writing device drivers and people trying
> to debug why their kernel doesn't work.  Again, that's not on you to
> fix, but it's pretty frustrating to see so much good information so
> badly organised.
I agree. But content improvment is out of this topic. So I will just
do the conversion in this serias.

-- 
Cheers,
Changbin Du

Re: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format

[Changbin Du]

Hi Corbet,
I also plant to convert x86 arch specific docs. And I will merge them into
one big serias for reviewing. Please wait for new revison. Thanks!

On Sat, Mar 30, 2019 at 12:04:06AM +0800, Changbin Du wrote
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  .../PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst}      | 56 ++++++++++++-------
>  Documentation/PCI/index.rst                   |  1 +
>  2 files changed, 38 insertions(+), 19 deletions(-)
>  rename Documentation/PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst} (89%)
> 
> diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.rst
> similarity index 89%
> rename from Documentation/PCI/MSI-HOWTO.txt
> rename to Documentation/PCI/MSI-HOWTO.rst
> index 618e13d5e276..33f382632fdd 100644
> --- a/Documentation/PCI/MSI-HOWTO.txt
> +++ b/Documentation/PCI/MSI-HOWTO.rst
> @@ -1,13 +1,18 @@
> -		The MSI Driver Guide HOWTO
> -	Tom L Nguyen tom.l.nguyen@intel.com
> -			10/03/2003
> -	Revised Feb 12, 2004 by Martine Silbermann
> -		email: Martine.Silbermann@hp.com
> -	Revised Jun 25, 2004 by Tom L Nguyen
> -	Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> -		Copyright 2003, 2008 Intel Corporation
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +==========================
> +The MSI Driver Guide HOWTO
> +==========================
> +
> +:Authors: - Tom L Nguyen <tom.l.nguyen@intel.com> 10/03/2003
> +          - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@hp.com>
> +	  - Revised Jun 25, 2004 by Tom L Nguyen
> +	  - Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> +	    Copyright 2003, 2008 Intel Corporation
>  
>  1. About this guide
> +===================
>  
>  This guide describes the basics of Message Signaled Interrupts (MSIs),
>  the advantages of using MSI over traditional interrupt mechanisms, how
> @@ -16,6 +21,7 @@ try if a device doesn't support MSIs.
>  
>  
>  2. 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.
> @@ -30,6 +36,7 @@ a time.
>  
>  
>  3. Why use MSIs?
> +================
>  
>  There are three reasons why using MSIs can give an advantage over
>  traditional pin-based interrupts.
> @@ -62,6 +69,7 @@ in a network card or each port in a storage controller.
>  
>  
>  4. 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
> @@ -69,6 +77,7 @@ 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
> +-----------------------------------
>  
>  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,
> @@ -77,13 +86,14 @@ on x86, you must also enable X86_UP_APIC or SMP in order to see the
>  CONFIG_PCI_MSI option.
>  
>  4.2 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 +111,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 +136,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 +145,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,14 +153,14 @@ 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)
> @@ -159,7 +169,7 @@ the driver can specify that only MSI or MSI-X is acceptable:
>  4.3 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 */
> @@ -175,8 +185,10 @@ 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
> +----------------------------------
>  
>  4.4.1 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
> @@ -189,6 +201,7 @@ 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
> +--------------------------------------------------------
>  
>  Using 'lspci -v' (as root) may show some devices with "MSI", "Message
>  Signalled Interrupts" or "MSI-X" capabilities.  Each of these capabilities
> @@ -197,6 +210,7 @@ or "-" (disabled).
>  
>  
>  5. MSI quirks
> +=============
>  
>  Several PCI chipsets or devices are known not to support MSIs.
>  The PCI stack provides three ways to disable MSIs:
> @@ -206,6 +220,7 @@ The PCI stack provides three ways to disable MSIs:
>  3. on a single device
>  
>  5.1. 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
> @@ -220,6 +235,7 @@ in your best interests to report the problem to linux-pci@vger.kernel.org
>  including a full 'lspci -v' so we can add the quirks to the kernel.
>  
>  5.2. 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 +246,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
>  
> @@ -245,6 +261,7 @@ Again, please notify linux-pci@vger.kernel.org of any bridges that need
>  special handling.
>  
>  5.3. 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
> @@ -253,6 +270,7 @@ 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
> +----------------------------------------------
>  
>  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 +278,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.
>  
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index 751cd8f23c62..8ed57b9ecfe4 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -10,3 +10,4 @@ Linux PCI Bus Subsystem
>     pci
>     PCIEBUS-HOWTO
>     pci-iov-howto
> +   MSI-HOWTO
> -- 
> 2.20.1
> 

-- 
Cheers,
Changbin Du

[PATCH 06/12] pci doc: convert PCI/acpi-info.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/{acpi-info.txt => acpi-info.rst} | 11 ++++++++---
 Documentation/PCI/index.rst                        |  1 +
 2 files changed, 9 insertions(+), 3 deletions(-)
 rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (97%)

diff --git a/Documentation/PCI/acpi-info.txt b/Documentation/PCI/acpi-info.rst
similarity index 97%
rename from Documentation/PCI/acpi-info.txt
rename to Documentation/PCI/acpi-info.rst
index 3ffa3b03970e..f7dabb7ca255 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].
@@ -135,8 +139,9 @@ address always corresponds to bus 0, even if the bus range below the bridge
 
     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
+
+        * 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 8ed57b9ecfe4..6e608afa55c1 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -11,3 +11,4 @@ Linux PCI Bus Subsystem
    PCIEBUS-HOWTO
    pci-iov-howto
    MSI-HOWTO
+   acpi-info
-- 
2.20.1

[PATCH 07/12] pci doc: convert PCI/pci-error-recovery.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/index.rst                   |   1 +
 ...or-recovery.txt => pci-error-recovery.rst} | 180 +++++++++---------
 MAINTAINERS                                   |   2 +-
 3 files changed, 96 insertions(+), 87 deletions(-)
 rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (80%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index 6e608afa55c1..e545460f5b3b 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -12,3 +12,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 80%
rename from Documentation/PCI/pci-error-recovery.txt
rename to Documentation/PCI/pci-error-recovery.rst
index 0b6bb3ef449e..ee74b0013c16 100644
--- a/Documentation/PCI/pci-error-recovery.txt
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -1,12 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-                       PCI Error Recovery
-                       ------------------
-                        February 2, 2006
+==================
+PCI Error Recovery
+==================
 
-                 Current document maintainer:
-             Linas Vepstas <linasvepstas@gmail.com>
-          updated by Richard Lary <rlary@us.ibm.com>
-       and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009
+February 2, 2006
+
+Current document maintainer:
+  - Linas Vepstas <linasvepstas@gmail.com>
+  - updated by Richard Lary <rlary@us.ibm.com>
+  - and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009
 
 
 Many PCI bus controllers are able to detect a variety of hardware
@@ -63,7 +66,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 +77,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 +141,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.
@@ -177,7 +185,7 @@ is STEP 6 (Permanent Failure).
 >>> 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.
@@ -203,23 +211,23 @@ instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
 >>> 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,24 +301,24 @@ 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).
@@ -370,23 +378,23 @@ 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 :)
+   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
diff --git a/MAINTAINERS b/MAINTAINERS
index 718890f348d4..994e849d56ef 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11966,7 +11966,7 @@ M:	Sam Bobroff <sbobroff@linux.ibm.com>
 M:	Oliver O'Halloran <oohall@gmail.com>
 L:	linuxppc-dev@lists.ozlabs.org
 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
-- 
2.20.1

[PATCH 08/12] pci doc: convert PCI/pcieaer-howto.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/index.rst                   |  1 +
 .../{pcieaer-howto.txt => pcieaer-howto.rst}  | 67 ++++++++++++++-----
 2 files changed, 50 insertions(+), 18 deletions(-)
 rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (83%)

diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index e545460f5b3b..44b7f9ca039e 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -13,3 +13,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 83%
rename from Documentation/PCI/pcieaer-howto.txt
rename to Documentation/PCI/pcieaer-howto.rst
index 48ce7903e3c6..b471ca9dde2f 100644
--- a/Documentation/PCI/pcieaer-howto.txt
+++ b/Documentation/PCI/pcieaer-howto.rst
@@ -1,12 +1,18 @@
-   The PCI Express Advanced Error Reporting Driver Guide HOWTO
-		T. Long Nguyen	<tom.l.nguyen@intel.com>
-		Yanmin Zhang	<yanmin.zhang@intel.com>
-				07/29/2006
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================================
+The PCI Express Advanced Error Reporting Driver Guide HOWTO
+===========================================================
+
+:Authors: - T. Long Nguyen <tom.l.nguyen@intel.com>
+	  - Yanmin Zhang <yanmin.zhang@intel.com> 7/29/2006
 
 
 1. Overview
+===========
 
 1.1 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
@@ -14,8 +20,10 @@ 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?
+---------------------------------------
 
 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
+=============
 
 2.1 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
@@ -49,6 +59,7 @@ depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
 CONFIG_PCIEAER = y.
 
 2.2 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
@@ -57,29 +68,33 @@ 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
+--------------------
 
 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
+-----------------------------
 
 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
+==================
 
 To enable AER aware support requires a software driver to configure
 the AER capability structure within its device and to provide callbacks.
@@ -121,6 +136,7 @@ errors because device specific errors will still get sent directly to
 the device driver.
 
 3.1 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,
@@ -129,8 +145,10 @@ pci_enable_pcie_error_reporting could be used to enable AER. See
 section 3.3.
 
 3.2. Provide callbacks
+----------------------
 
 3.2.1 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The PCI Express AER Root driver uses error callbacks to coordinate
 with downstream device drivers associated with a hierarchy in question
@@ -162,6 +182,7 @@ definitions of the callbacks.
 Below sections specify when to call the error callback functions.
 
 3.2.2.1 Correctable errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Correctable errors pose no impacts on the functionality of
 the interface. The PCI Express protocol can recover without any
@@ -170,12 +191,15 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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.
 
@@ -200,22 +224,27 @@ reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
 to mmio_enabled.
 
 3.3 helper functions
+--------------------
 
-3.3.1 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);
+3.3.2 `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);
+3.3.3 `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
+----------------------------
 
 Q: What happens if a PCI Express device driver does not provide an
 error recovery handler (pci_driver->err_handler is equal to NULL)?
@@ -246,6 +275,7 @@ cleanup uncorrectable status register. Pls. refer to section 3.3.
 
 
 4. 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 +291,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

[PATCH 09/12] pci doc: convert PCI/endpoint/pci-endpoint.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/endpoint/index.rst          | 10 +++
 .../{pci-endpoint.txt => pci-endpoint.rst}    | 74 +++++++++++--------
 Documentation/PCI/index.rst                   |  1 +
 3 files changed, 56 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/PCI/endpoint/index.rst
 rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (86%)

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 86%
rename from Documentation/PCI/endpoint/pci-endpoint.txt
rename to Documentation/PCI/endpoint/pci-endpoint.rst
index e86a96b66a6a..81ccbe1cd577 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 <kishon@ti.com>
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+PCI ENDPOINT FRAMEWORK
+======================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
 
 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
+===============
 
 Linux has a comprehensive PCI subsystem to support PCI controllers that
 operates in Root Complex mode. The subsystem has capability to scan PCI bus,
@@ -20,23 +26,26 @@ EP system which can have a wide variety of use cases from testing or
 validation, co-processor accelerator, etc.
 
 2. 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
+----------------------------------------
 
 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
@@ -51,23 +60,23 @@ 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().
 
@@ -76,85 +85,88 @@ by the PCI controller 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
+~~~~~~~~~~~~~~~~
 
 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
+--------------------------------------
 
 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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 +178,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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 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
+2.2.3 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 44b7f9ca039e..72a0668ccfc4 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -14,3 +14,4 @@ Linux PCI Bus Subsystem
    acpi-info
    pci-error-recovery
    pcieaer-howto
+   endpoint/index
-- 
2.20.1

[PATCH 10/12] pci doc: convert PCI/endpoint/pci-endpoint-cfs.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 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..a365e858f252 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 <kishon@ti.com>
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+CONFIGURING PCI ENDPOINT USING CONFIGFS
+=======================================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
 
 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

[PATCH 11/12] pci doc: convert PCI/endpoint/pci-test-function.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/endpoint/index.rst          |  1 +
 ...est-function.txt => pci-test-function.rst} | 32 +++++++++++--------
 2 files changed, 20 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..be18ec3d1da0 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 <kishon@ti.com>
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI TEST FUNCTION
+=================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
 
 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,17 +63,17 @@ 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.
@@ -77,7 +83,7 @@ Possible types:
  - MSI		: 1
  - MSI-X	: 2
 
-*) PCI_ENDPOINT_TEST_IRQ_NUMBER
+* PCI_ENDPOINT_TEST_IRQ_NUMBER
 
 This register contains the triggered ID interrupt.
 
-- 
2.20.1

[PATCH 12/12] pci doc: convert PCI/endpoint/pci-test-howto.txt to rst format

[Changbin Du]

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/PCI/endpoint/index.rst          |  1 +
 ...{pci-test-howto.txt => pci-test-howto.rst} | 51 +++++++++++++------
 2 files changed, 37 insertions(+), 15 deletions(-)
 rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (83%)

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 83%
rename from Documentation/PCI/endpoint/pci-test-howto.txt
rename to Documentation/PCI/endpoint/pci-test-howto.rst
index 040479f437a5..a81ae7daafa0 100644
--- a/Documentation/PCI/endpoint/pci-test-howto.txt
+++ b/Documentation/PCI/endpoint/pci-test-howto.rst
@@ -1,38 +1,49 @@
-			    PCI TEST USERGUIDE
-		    Kishon Vijay Abraham I <kishon@ti.com>
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+PCI TEST USERGUIDE
+==================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
 
 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
+==================
 
 1.1 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:
+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
+--------------------------------
 
 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 +53,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,7 +62,7 @@ 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
@@ -59,10 +70,11 @@ vendorid with 0xffff and interrupt_pin with 0x0001
 	  0x0001
 
 1.4 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
@@ -70,10 +82,11 @@ device, the following commands can be used.
 	# echo 8 > functions/pci_epf_test/func1/msix_interrupts
 
 1.5 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/
 
@@ -81,30 +94,35 @@ Once the above step is completed, the PCI endpoint is ready to establish a link
 with the host.
 
 1.6 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
+----------------
 
-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
+---------------------------------------
 
 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
@@ -112,6 +130,9 @@ or if you desire to compile and install in your system:
 The tool and script will be located in <rootfs>/usr/bin/
 
 2.2.1 pcitest.sh Output
+~~~~~~~~~~~~~~~~~~~~~~~
+::
+
 	# pcitest.sh
 	BAR tests
 
-- 
2.20.1

Re: [PATCH 00/12] Include linux PCI docs into Sphinx TOC tree

[Bjorn Helgaas]

On Sat, Mar 30, 2019 at 12:04:01AM +0800, Changbin Du wrote:
> Hi Corbet,

Conventional address would be "Hi Jonathan", just FYI.

> I also did the conversion for PCI documentation. Please check, Thanks!
> 
> 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://104.238.181.70:8080/kernel-doc/PCI/index.html
> 
> Thank you!
> 
> Changbin Du (12):
>   Documentation: add Linux PCI to Sphinx TOC tree
>   pci doc: convert PCI/pci.txt to rst format
>   pci doc: convert PCI/PCIEBUS-HOWTO.txt to rst format
>   pci doc: convert PCI/pci-iov-howto.txt to rst format
>   pci doc: convert PCI/MSI-HOWTO.txt to rst format
>   pci doc: convert PCI/acpi-info.txt to rst format
>   pci doc: convert PCI/pci-error-recovery.txt to rst format
>   pci doc: convert PCI/pcieaer-howto.txt to rst format
>   pci doc: convert PCI/endpoint/pci-endpoint.txt to rst format
>   pci doc: convert PCI/endpoint/pci-endpoint-cfs.txt to rst format
>   pci doc: convert PCI/endpoint/pci-test-function.txt to rst format
>   pci doc: convert PCI/endpoint/pci-test-howto.txt to rst format

Thanks for doing all this work!

Acked-by: Bjorn Helgaas <bhelgaas@google.com>

There's not a real convention yet for subject lines in Documentation/,
but I would propose:

  Documentation: PCI: Convert pci.txt to reST
  Documentation: PCI: Convert endpoint/pci-endpoint.txt to reST

because that at least goes with some recent Documentation/PCI changes
and it identifies "reST" as something other than a plain English word
(RST or ReST would also work for me).

>  .../PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst}      |  56 +++--
>  .../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst}  | 112 +++++----
>  .../PCI/{acpi-info.txt => acpi-info.rst}      |  11 +-
>  Documentation/PCI/endpoint/index.rst          |  13 ++
>  ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++++----
>  .../{pci-endpoint.txt => pci-endpoint.rst}    |  74 +++---
>  ...est-function.txt => pci-test-function.rst} |  32 +--
>  ...{pci-test-howto.txt => pci-test-howto.rst} |  51 ++--
>  Documentation/PCI/index.rst                   |  17 ++
>  ...or-recovery.txt => pci-error-recovery.rst} | 180 ++++++++-------
>  .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 144 +++++++-----
>  Documentation/PCI/{pci.txt => pci.rst}        | 218 +++++++++---------
>  .../{pcieaer-howto.txt => pcieaer-howto.rst}  |  67 ++++--
>  Documentation/index.rst                       |   1 +
>  MAINTAINERS                                   |   2 +-
>  15 files changed, 641 insertions(+), 436 deletions(-)
>  rename Documentation/PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst} (89%)
>  rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (75%)
>  rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (97%)
>  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} (86%)
>  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} (83%)
>  create mode 100644 Documentation/PCI/index.rst
>  rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (80%)
>  rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (65%)
>  rename Documentation/PCI/{pci.txt => pci.rst} (80%)
>  rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (83%)
> 
> -- 
> 2.20.1
> 

Re: [PATCH 00/12] Include linux PCI docs into Sphinx TOC tree

[Changbin Du]

On Mon, Apr 01, 2019 at 06:03:21PM -0500, Bjorn Helgaas wrote:
> On Sat, Mar 30, 2019 at 12:04:01AM +0800, Changbin Du wrote:
> > Hi Corbet,
> 
> Conventional address would be "Hi Jonathan", just FYI.
>
I know this convention. I said 'Hi Corbet' because I saw the name of email
address. Sorry if this is not the case. :)

> > I also did the conversion for PCI documentation. Please check, Thanks!
> > 
> > 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://104.238.181.70:8080/kernel-doc/PCI/index.html
> > 
> > Thank you!
> > 
> > Changbin Du (12):
> >   Documentation: add Linux PCI to Sphinx TOC tree
> >   pci doc: convert PCI/pci.txt to rst format
> >   pci doc: convert PCI/PCIEBUS-HOWTO.txt to rst format
> >   pci doc: convert PCI/pci-iov-howto.txt to rst format
> >   pci doc: convert PCI/MSI-HOWTO.txt to rst format
> >   pci doc: convert PCI/acpi-info.txt to rst format
> >   pci doc: convert PCI/pci-error-recovery.txt to rst format
> >   pci doc: convert PCI/pcieaer-howto.txt to rst format
> >   pci doc: convert PCI/endpoint/pci-endpoint.txt to rst format
> >   pci doc: convert PCI/endpoint/pci-endpoint-cfs.txt to rst format
> >   pci doc: convert PCI/endpoint/pci-test-function.txt to rst format
> >   pci doc: convert PCI/endpoint/pci-test-howto.txt to rst format
> 
> Thanks for doing all this work!
> 
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> 
> There's not a real convention yet for subject lines in Documentation/,
> but I would propose:
> 
>   Documentation: PCI: Convert pci.txt to reST
>   Documentation: PCI: Convert endpoint/pci-endpoint.txt to reST
> 
> because that at least goes with some recent Documentation/PCI changes
> and it identifies "reST" as something other than a plain English word
> (RST or ReST would also work for me).
> 
I agree. I am just a little lazy to update all of them this time :)
Thanks for your ACK!

> >  .../PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst}      |  56 +++--
> >  .../{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst}  | 112 +++++----
> >  .../PCI/{acpi-info.txt => acpi-info.rst}      |  11 +-
> >  Documentation/PCI/endpoint/index.rst          |  13 ++
> >  ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++++----
> >  .../{pci-endpoint.txt => pci-endpoint.rst}    |  74 +++---
> >  ...est-function.txt => pci-test-function.rst} |  32 +--
> >  ...{pci-test-howto.txt => pci-test-howto.rst} |  51 ++--
> >  Documentation/PCI/index.rst                   |  17 ++
> >  ...or-recovery.txt => pci-error-recovery.rst} | 180 ++++++++-------
> >  .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 144 +++++++-----
> >  Documentation/PCI/{pci.txt => pci.rst}        | 218 +++++++++---------
> >  .../{pcieaer-howto.txt => pcieaer-howto.rst}  |  67 ++++--
> >  Documentation/index.rst                       |   1 +
> >  MAINTAINERS                                   |   2 +-
> >  15 files changed, 641 insertions(+), 436 deletions(-)
> >  rename Documentation/PCI/{MSI-HOWTO.txt => MSI-HOWTO.rst} (89%)
> >  rename Documentation/PCI/{PCIEBUS-HOWTO.txt => PCIEBUS-HOWTO.rst} (75%)
> >  rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (97%)
> >  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} (86%)
> >  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} (83%)
> >  create mode 100644 Documentation/PCI/index.rst
> >  rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (80%)
> >  rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (65%)
> >  rename Documentation/PCI/{pci.txt => pci.rst} (80%)
> >  rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (83%)
> > 
> > -- 
> > 2.20.1
> > 

-- 
Cheers,
Changbin Du

Re: [PATCH 00/12] Include linux PCI docs into Sphinx TOC tree

[Bjorn Helgaas]

On Tue, Apr 02, 2019 at 11:08:54PM +0800, Changbin Du wrote:
> On Mon, Apr 01, 2019 at 06:03:21PM -0500, Bjorn Helgaas wrote:
> > On Sat, Mar 30, 2019 at 12:04:01AM +0800, Changbin Du wrote:
> > > Changbin Du (12):
> > >   Documentation: add Linux PCI to Sphinx TOC tree
> > >   pci doc: convert PCI/pci.txt to rst format
> > >   pci doc: convert PCI/PCIEBUS-HOWTO.txt to rst format
> > >   pci doc: convert PCI/pci-iov-howto.txt to rst format
> > >   pci doc: convert PCI/MSI-HOWTO.txt to rst format
> > >   pci doc: convert PCI/acpi-info.txt to rst format
> > >   pci doc: convert PCI/pci-error-recovery.txt to rst format
> > >   pci doc: convert PCI/pcieaer-howto.txt to rst format
> > >   pci doc: convert PCI/endpoint/pci-endpoint.txt to rst format
> > >   pci doc: convert PCI/endpoint/pci-endpoint-cfs.txt to rst format
> > >   pci doc: convert PCI/endpoint/pci-test-function.txt to rst format
> > >   pci doc: convert PCI/endpoint/pci-test-howto.txt to rst format
> > 
> > Thanks for doing all this work!
> > 
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > 
> > There's not a real convention yet for subject lines in Documentation/,
> > but I would propose:
> > 
> >   Documentation: PCI: Convert pci.txt to reST
> >   Documentation: PCI: Convert endpoint/pci-endpoint.txt to reST
> > 
> > because that at least goes with some recent Documentation/PCI changes
> > and it identifies "reST" as something other than a plain English word
> > (RST or ReST would also work for me).
> > 
> I agree. I am just a little lazy to update all of them this time :)
> Thanks for your ACK!

Well, I guess I'm too lazy to fix them all for you, so I personally
wouldn't apply these.  But maybe Jonathan will be more accommodating.

Bjorn

Re: [PATCH 00/12] Include linux PCI docs into Sphinx TOC tree

[Changbin Du]

On Tue, Apr 02, 2019 at 01:07:44PM -0500, Bjorn Helgaas wrote:
> On Tue, Apr 02, 2019 at 11:08:54PM +0800, Changbin Du wrote:
> > On Mon, Apr 01, 2019 at 06:03:21PM -0500, Bjorn Helgaas wrote:
> > > On Sat, Mar 30, 2019 at 12:04:01AM +0800, Changbin Du wrote:
> > > > Changbin Du (12):
> > > >   Documentation: add Linux PCI to Sphinx TOC tree
> > > >   pci doc: convert PCI/pci.txt to rst format
> > > >   pci doc: convert PCI/PCIEBUS-HOWTO.txt to rst format
> > > >   pci doc: convert PCI/pci-iov-howto.txt to rst format
> > > >   pci doc: convert PCI/MSI-HOWTO.txt to rst format
> > > >   pci doc: convert PCI/acpi-info.txt to rst format
> > > >   pci doc: convert PCI/pci-error-recovery.txt to rst format
> > > >   pci doc: convert PCI/pcieaer-howto.txt to rst format
> > > >   pci doc: convert PCI/endpoint/pci-endpoint.txt to rst format
> > > >   pci doc: convert PCI/endpoint/pci-endpoint-cfs.txt to rst format
> > > >   pci doc: convert PCI/endpoint/pci-test-function.txt to rst format
> > > >   pci doc: convert PCI/endpoint/pci-test-howto.txt to rst format
> > > 
> > > Thanks for doing all this work!
> > > 
> > > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > > 
> > > There's not a real convention yet for subject lines in Documentation/,
> > > but I would propose:
> > > 
> > >   Documentation: PCI: Convert pci.txt to reST
> > >   Documentation: PCI: Convert endpoint/pci-endpoint.txt to reST
> > > 
> > > because that at least goes with some recent Documentation/PCI changes
> > > and it identifies "reST" as something other than a plain English word
> > > (RST or ReST would also work for me).
> > > 
> > I agree. I am just a little lazy to update all of them this time :)
> > Thanks for your ACK!
> 
> Well, I guess I'm too lazy to fix them all for you, so I personally
> wouldn't apply these.  But maybe Jonathan will be more accommodating.
>
ok, I will fix this serias since they do matter.

> Bjorn

-- 
Cheers,
Changbin Du