[PATCH v2 0/2] Documentation: misc-devices: Fix documentation issues (indentation, text format, toc) and outdated information

[PATCH v2 0/2] Documentation: misc-devices: Fix documentation issues (indentation, text format, toc) and outdated information

[Gustavo Pimentel]

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

This patch series fixes the documentation issues reported by doing
*make htmldocs*, such as:
 - indentation
 - text formatting
 - missing entry on the table of content related to dw-xdata-pcie misc
 driver index

Besides these warnings also fixes some outdated information related to
stop file interface in sysfs.

Changes:
 V2: Added cover-letter
     Added Reported-by, Link, and Fixes tags

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):
  Documentation: misc-devices: Fix indentation, formatting, and update
    outdated info
  Documentation: misc-devices: Add missing entry on the table of content
    related to dw-xdata-pcie

 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 v2 1/2] Documentation: misc-devices: Fix indentation, formatting, and update outdated info

[Gustavo Pimentel]

Fixes indentation issues reported by doing *make htmldocs* as well some
text formatting.

Besides these fixes, there was 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

Re: [PATCH v2 1/2] Documentation: misc-devices: Fix indentation, formatting, and update outdated info

[Greg Kroah-Hartman]

On Tue, Apr 06, 2021 at 11:17:48PM +0200, Gustavo Pimentel wrote:
> Fixes indentation issues reported by doing *make htmldocs* as well some
> text formatting.
> 
> Besides these fixes, there was some outdated information related to stop
> file interface in sysfs.

You are not doing this for all "misc-devices", you are doing this only
for one specific driver file.

Please look at the example I provided for how to name this and fix up.

> 
> 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(-)

What changed from v1?  Always put that below the --- line.

thanks,

greg k-h

RE: [PATCH v2 1/2] Documentation: misc-devices: Fix indentation, formatting, and update outdated info

[Gustavo Pimentel]

On Wed, Apr 7, 2021 at 7:17:12, Greg Kroah-Hartman 
<gregkh@linuxfoundation.org> wrote:

> On Tue, Apr 06, 2021 at 11:17:48PM +0200, Gustavo Pimentel wrote:
> > Fixes indentation issues reported by doing *make htmldocs* as well some
> > text formatting.
> > 
> > Besides these fixes, there was some outdated information related to stop
> > file interface in sysfs.
> 
> You are not doing this for all "misc-devices", you are doing this only
> for one specific driver file.
> 
> Please look at the example I provided for how to name this and fix up.

Sorry Greg, I didn't see an example provided. Perhaps you forgot it?

> 
> > 
> > Fixes: e1181b5bbc3c ("Documentation: misc-devices: Add Documentation for dw-xdata-pcie driver")
> > Link: https://urldefense.com/v3/__https://lore.kernel.org/linux-next/20210406214615.40cf3493@canb.auug.org.au/__;!!A4F2R9G_pg!MeIXpmOYi4yJTBq19JEADll7-g6cYBmmwG92EWipqsBiPzeubfMGVllrpMt8FpwvW5ZemHY$ 
> > 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(-)
> 
> What changed from v1?  Always put that below the --- line.

I've considered the V1 the 2 patches sent wrongly separately, based on 
your feedback I've generated a v2 to include the cover letter and the 
reported-by, link, and fixes tags.
Was this wrong?

I also placed the change list on the cover letter. Or do you prefer on 
each patch?

> 
> thanks,
> 
> greg k-h

Re: [PATCH v2 1/2] Documentation: misc-devices: Fix indentation, formatting, and update outdated info

[Greg Kroah-Hartman]

On Wed, Apr 07, 2021 at 03:57:31PM +0000, Gustavo Pimentel wrote:
> On Wed, Apr 7, 2021 at 7:17:12, Greg Kroah-Hartman 
> <gregkh@linuxfoundation.org> wrote:
> 
> > On Tue, Apr 06, 2021 at 11:17:48PM +0200, Gustavo Pimentel wrote:
> > > Fixes indentation issues reported by doing *make htmldocs* as well some
> > > text formatting.
> > > 
> > > Besides these fixes, there was some outdated information related to stop
> > > file interface in sysfs.
> > 
> > You are not doing this for all "misc-devices", you are doing this only
> > for one specific driver file.
> > 
> > Please look at the example I provided for how to name this and fix up.
> 
> Sorry Greg, I didn't see an example provided. Perhaps you forgot it?

Nope: https://lore.kernel.org/r/YGyl7OWHJm1NuaV2@kroah.com

> 
> > 
> > > 
> > > Fixes: e1181b5bbc3c ("Documentation: misc-devices: Add Documentation for dw-xdata-pcie driver")
> > > Link: https://urldefense.com/v3/__https://lore.kernel.org/linux-next/20210406214615.40cf3493@canb.auug.org.au/__;!!A4F2R9G_pg!MeIXpmOYi4yJTBq19JEADll7-g6cYBmmwG92EWipqsBiPzeubfMGVllrpMt8FpwvW5ZemHY$ 
> > > 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(-)
> > 
> > What changed from v1?  Always put that below the --- line.
> 
> I've considered the V1 the 2 patches sent wrongly separately, based on 
> your feedback I've generated a v2 to include the cover letter and the 
> reported-by, link, and fixes tags.
> Was this wrong?

No, but you need to say that here, otherwise how do we know this?

> I also placed the change list on the cover letter. Or do you prefer on 
> each patch?

Ah, if you put it in the cover letter, that's fine, but I almost never
read them :)

thanks,

greg k-h

RE: [PATCH v2 1/2] Documentation: misc-devices: Fix indentation, formatting, and update outdated info

[Gustavo Pimentel]

On Wed, Apr 7, 2021 at 18:35:16, Greg Kroah-Hartman 
<gregkh@linuxfoundation.org> wrote:

> On Wed, Apr 07, 2021 at 03:57:31PM +0000, Gustavo Pimentel wrote:
> > On Wed, Apr 7, 2021 at 7:17:12, Greg Kroah-Hartman 
> > <gregkh@linuxfoundation.org> wrote:
> > 
> > > On Tue, Apr 06, 2021 at 11:17:48PM +0200, Gustavo Pimentel wrote:
> > > > Fixes indentation issues reported by doing *make htmldocs* as well some
> > > > text formatting.
> > > > 
> > > > Besides these fixes, there was some outdated information related to stop
> > > > file interface in sysfs.
> > > 
> > > You are not doing this for all "misc-devices", you are doing this only
> > > for one specific driver file.
> > > 
> > > Please look at the example I provided for how to name this and fix up.
> > 
> > Sorry Greg, I didn't see an example provided. Perhaps you forgot it?
> 
> Nope: https://urldefense.com/v3/__https://lore.kernel.org/r/YGyl7OWHJm1NuaV2@kroah.com__;!!A4F2R9G_pg!P8mbZ8v-lsQ9vFXveIVRhy11GV8pgDdGWP7FW51NwcuaI2WpDfsuBeCFXIzdFzkTHKTv3oU$ 

That's right, for some reason I was stuck thinking that was some kind of 
link. My bad.

-Gustavo

[PATCH v2 2/2] Documentation: misc-devices: Add missing entry on the table of content related to dw-xdata-pcie

[Gustavo Pimentel]

Add missing entry on the table of content related to dw-xdata-pcie misc
driver reported in a warning by doing *make htmldocs*.

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