[PATCH v3 0/2] dw-xdata-pcie: Fix documentation build warns

[PATCH v3 0/2] dw-xdata-pcie: Fix documentation build warns

[Gustavo Pimentel]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 1840 bytes --]

This patch series fixes the documentation build warnings, such as:
Documentation/misc-devices/dw-xdata-pcie.rst:20: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:24: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:25: WARNING: Block quote
ends without a blank line; unexpected unindent.
Documentation/misc-devices/dw-xdata-pcie.rst:30: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:34: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:35: WARNING: Block quote
ends without a blank line; unexpected unindent.
Documentation/misc-devices/dw-xdata-pcie.rst:40: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst: WARNING: document isn't
included in any toctree

Also fixes some outdated information related to stop file interface
in sysfs.

Changes:
 V2: Added cover-letter
     Added Reported-by, Link, and Fixes tags
 V3: Reformulated patch's text description and title

Cc: linux-doc@vger.kernel.org
Cc: linux-pci@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: Derek Kiernan <derek.kiernan@xilinx.com>
Cc: Dragan Cvetic <dragan.cvetic@xilinx.com>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Bjorn Helgaas <bhelgaas@google.com>
Cc: Krzysztof Wilczyński <kw@linux.com>
Cc: Stephen Rothwell <sfr@canb.auug.org.au>

Gustavo Pimentel (2):
  dw-xdata-pcie: Fix documentation build warns and update outdated info
  misc-device: Add dw-xdata-pcie to toctree(index)

 Documentation/misc-devices/dw-xdata-pcie.rst | 62 +++++++++++++++++++---------
 Documentation/misc-devices/index.rst         |  1 +
 2 files changed, 44 insertions(+), 19 deletions(-)

-- 
2.7.4

[PATCH v3 1/2] dw-xdata-pcie: Fix documentation build warns and update outdated info

[Gustavo Pimentel]

Fixes documentation build warnings related to indentation and text
formatting, such as:

Documentation/misc-devices/dw-xdata-pcie.rst:20: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:24: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:25: WARNING: Block quote
ends without a blank line; unexpected unindent.
Documentation/misc-devices/dw-xdata-pcie.rst:30: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:34: WARNING: Unexpected
indentation.
Documentation/misc-devices/dw-xdata-pcie.rst:35: WARNING: Block quote
ends without a blank line; unexpected unindent.
Documentation/misc-devices/dw-xdata-pcie.rst:40: WARNING: Unexpected
indentation.

Also fixes some outdated information related to stop file interface in sysfs.

Fixes: e1181b5bbc3c ("Documentation: misc-devices: Add Documentation for dw-xdata-pcie driver")
Link: https://lore.kernel.org/linux-next/20210406214615.40cf3493@canb.auug.org.au/
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Gustavo Pimentel <gustavo.pimentel@synopsys.com>
---
 Documentation/misc-devices/dw-xdata-pcie.rst | 62 +++++++++++++++++++---------
 1 file changed, 43 insertions(+), 19 deletions(-)

diff --git a/Documentation/misc-devices/dw-xdata-pcie.rst b/Documentation/misc-devices/dw-xdata-pcie.rst
index fd75c93..a956e1a 100644
--- a/Documentation/misc-devices/dw-xdata-pcie.rst
+++ b/Documentation/misc-devices/dw-xdata-pcie.rst
@@ -4,37 +4,61 @@
 Driver for Synopsys DesignWare PCIe traffic generator (also known as xData)
 ===========================================================================
 
+Supported chips:
+Synopsys DesignWare PCIe prototype solution
+
+Data sheet:
+Not freely available
+
+Author:
+Gustavo Pimentel <gustavo.pimentel@synopsys.com>
+
+Description
+-----------
+
 This driver should be used as a host-side (Root Complex) driver and Synopsys
 DesignWare prototype that includes this IP.
 
-The "dw-xdata-pcie" driver can be used to enable/disable PCIe traffic
+The dw-xdata-pcie driver can be used to enable/disable PCIe traffic
 generator in either direction (mutual exclusion) besides allowing the
 PCIe link performance analysis.
 
 The interaction with this driver is done through the module parameter and
 can be changed in runtime. The driver outputs the requested command state
-information to /var/log/kern.log or dmesg.
+information to ``/var/log/kern.log`` or dmesg.
+
+Example
+-------
+
+Write TLPs traffic generation - Root Complex to Endpoint direction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generate traffic::
+
+        # echo 1 > /sys/class/misc/dw-xdata-pcie.0/write
 
-Request write TLPs traffic generation - Root Complex to Endpoint direction
-- Command:
-	echo 1 > /sys/class/misc/dw-xdata-pcie/write
+Get link throughput in MB/s::
 
-Get write TLPs traffic link throughput in MB/s
-- Command:
-        cat /sys/class/misc/dw-xdata-pcie/write
-- Output example:
+        # cat /sys/class/misc/dw-xdata-pcie.0/write
 	204
 
-Request read TLPs traffic generation - Endpoint to Root Complex direction:
-- Command:
-	echo 1 > /sys/class/misc/dw-xdata-pcie/read
+Stop traffic in any direction::
 
-Get read TLPs traffic link throughput in MB/s
-- Command:
-        cat /sys/class/misc/dw-xdata-pcie/read
-- Output example:
+        # echo 0 > /sys/class/misc/dw-xdata-pcie.0/write
+
+Read TLPs traffic generation - Endpoint to Root Complex direction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generate traffic::
+
+        # echo 1 > /sys/class/misc/dw-xdata-pcie.0/read
+
+Get link throughput in MB/s::
+
+        # cat /sys/class/misc/dw-xdata-pcie.0/read
 	199
 
-Request to stop any current TLP transfer:
-- Command:
-	echo 1 > /sys/class/misc/dw-xdata-pcie/stop
+Stop traffic in any direction::
+
+        # echo 0 > /sys/class/misc/dw-xdata-pcie.0/read
+
-- 
2.7.4

[PATCH v3 2/2] misc-device: Add dw-xdata-pcie to toctree(index)

[Gustavo Pimentel]

With the recent addition of dw-xdata-pcie, the documentation build now
warns about a missing reference on the table of content related to it.

This fix solves the following error:

Documentation/misc-devices/dw-xdata-pcie.rst: WARNING: document isn't
included in any toctree

Fixes: e1181b5bbc3c ("Documentation: misc-devices: Add Documentation for dw-xdata-pcie driver")
Link: https://lore.kernel.org/linux-next/20210406214615.40cf3493@canb.auug.org.au/
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Gustavo Pimentel <gustavo.pimentel@synopsys.com>
---
 Documentation/misc-devices/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index 64420b331..30ac58f 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -19,6 +19,7 @@ fit into other categories.
    bh1770glc
    eeprom
    c2port
+   dw-xdata-pcie
    ibmvmc
    ics932s401
    isl29003
-- 
2.7.4

Re: [PATCH v3 1/2] dw-xdata-pcie: Fix documentation build warns and update outdated info

[Greg Kroah-Hartman]

On Wed, Apr 07, 2021 at 10:31:48PM +0200, Gustavo Pimentel wrote:
> Fixes documentation build warnings related to indentation and text
> formatting, such as:
> 
> Documentation/misc-devices/dw-xdata-pcie.rst:20: WARNING: Unexpected
> indentation.
> Documentation/misc-devices/dw-xdata-pcie.rst:24: WARNING: Unexpected
> indentation.
> Documentation/misc-devices/dw-xdata-pcie.rst:25: WARNING: Block quote
> ends without a blank line; unexpected unindent.
> Documentation/misc-devices/dw-xdata-pcie.rst:30: WARNING: Unexpected
> indentation.
> Documentation/misc-devices/dw-xdata-pcie.rst:34: WARNING: Unexpected
> indentation.
> Documentation/misc-devices/dw-xdata-pcie.rst:35: WARNING: Block quote
> ends without a blank line; unexpected unindent.
> Documentation/misc-devices/dw-xdata-pcie.rst:40: WARNING: Unexpected
> indentation.

In the future, there's no need to wrap error/warning lines like this in
a changelog text.  Not a big deal, but the above is messy to read,
right?

> 
> Also fixes some outdated information related to stop file interface in sysfs.

When you say "also", that means you need a separate patch usually.  And
for this patch, that is exactly what you need.  Please split this up
into one patch that fixes the reported problem, and another one that
adds the needed information.

thanks,

greg k-h