Skip to contentSkip to conversation

Documentation: Convert sysfs-pci to ReST

PATCH In review Vitor Massaru Iha 5 participants 12 messages Mar 31, 2020 – Apr 1, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Documentation: Convert sysfs-pci to ReST

Vitor Massaru Iha (2):
Documentation: filesystems: Convert sysfs-pci to ReST
Documentation: filesystems: remove whitespaces

 .../{sysfs-pci.txt => sysfs-pci.rst}          | 44 ++++++++++---------
 1 file changed, 24 insertions(+), 20 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (81%)
Signature · 1 line
2.21.1
#1 lore raw

PATCH 1/2 Documentation: filesystems: Convert sysfs-pci to ReST

---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)
Documentation/filesystems/sysfs-pci.rst renamed from Documentation/filesystems/sysfs-pci.txt +22 -18
similarity index 82%
rename from Documentation/filesystems/sysfs-pci.txt
rename to Documentation/filesystems/sysfs-pci.rst
index 06f1d64c6f70..9b93e7444b15 100644
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================
 Accessing PCI device resources through sysfs
---------------------------------------------
+============================================
 
 sysfs, usually mounted at /sys, provides access to PCI resources on platforms
 that support it.  For example, a given bus might look like this:
@@ -30,23 +33,24 @@ This bus contains a single function device in slot 0.  The domain and bus
 numbers are reproduced for convenience.  Under the device directory are several
 files, each with their own function.
 
-       file		   function
-       ----		   --------
-       class		   PCI class (ascii, ro)
-       config		   PCI config space (binary, rw)
-       device		   PCI device (ascii, ro)
-       enable	           Whether the device is enabled (ascii, rw)
-       irq		   IRQ number (ascii, ro)
-       local_cpus	   nearby CPU mask (cpumask, ro)
-       remove		   remove device from kernel's list (ascii, wo)
-       resource		   PCI resource host addresses (ascii, ro)
-       resource0..N	   PCI resource N, if present (binary, mmap, rw[1])
-       resource0_wc..N_wc  PCI WC map resource N, if prefetchable (binary, mmap)
-       revision		   PCI revision (ascii, ro)
-       rom		   PCI ROM resource, if present (binary, ro)
-       subsystem_device	   PCI subsystem device (ascii, ro)
-       subsystem_vendor	   PCI subsystem vendor (ascii, ro)
-       vendor		   PCI vendor (ascii, ro)
+	file		    function
+	=================== ======================================================
+	class		    PCI class (ascii, ro)
+	config		    PCI config space (binary, rw)
+	device		    PCI device (ascii, ro)
+	enable		    Whether the device is enabled (ascii, rw)
+	irq		    IRQ number (ascii, ro)
+	local_cpus	    nearby CPU mask (cpumask, ro)
+	remove		    remove device from kernel's list (ascii, wo)
+	resource	    PCI resource host addresses (ascii, ro)
+	resource0..N	    PCI resource N, if present (binary, mmap, rw[1])
+	resource0_wc..N_wc  PCI WC map resource N, if prefetchable (binary, mmap)
+	revision	    PCI revision (ascii, ro)
+	rom		    PCI ROM resource, if present (binary, ro)
+	subsystem_device    PCI subsystem device (ascii, ro)
+	subsystem_vendor    PCI subsystem vendor (ascii, ro)
+	vendor		    PCI vendor (ascii, ro)
+	=================== ======================================================
 
   ro - read only file
   rw - file is readable and writable
Signature · 6 lines
2.21.1

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
maintainer
#2 lore raw

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

Quoted 5 lines · On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <[email protected]> wrote:
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)

Please supply a changelog with your patches.

The conversion you have done in this file is incomplete; I suspect that you have not actually built the docs and seen what the results look like. There are literal blocks that you have not marked as such, as a minimum. Please actually do a docs build (after adding this file to index.rst) and make sure that the output is what you intended.

One other thing of note...this file dates back to before the Git era, and while it has seen numerous tweaks since then, it's clearly outdated. Look at what's actually under /sys/devices/pci* compared to what's documented. I will take the conversion without it, but what I would really like to see would be an effort to document all of the attributes that appear there with current kernels.

Thanks,

jon

#3 lore raw

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

Quoted 35 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <[email protected]> wrote:
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++-----
----
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst}

(82%)

Please supply a changelog with your patches.

The conversion you have done in this file is incomplete; I suspect that
you have not actually built the docs and seen what the results look like.
There are literal blocks that you have not marked as such, as a minimum.
Please actually do a docs build (after adding this file to index.rst) and
make sure that the output is what you intended.

One other thing of note...this file dates back to before the Git era, and
while it has seen numerous tweaks since then, it's clearly outdated. Look
at what's actually under /sys/devices/pci* compared to what's documented.
I will take the conversion without it, but what I would really like to see
would be an effort to document all of the attributes that appear there
with current kernels.

Quoted 3 lines

Thanks,

jon

Thanks for the review, I will check your comments and correct themif that document is still needed.

BR,
Vitor

maintainer
#4 lore raw

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

Quoted 2 lines · On Tue, 31 Mar 2020 20:03:46 -0300 Vitor Massaru Iha <[email protected]> wrote:

Thanks for the review, I will check your comments and correct themif that document is still needed.

Oh we definitely still want the document; it's out of date but not overtly wrong.

Thanks,

jon

#5 lore raw

Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

In reply to Jonathan Corbet
Quoted 18 lines · Jonathan Corbet
Quoted 5 lines · On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <[email protected]> wrote:
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)

Please supply a changelog with your patches.

The conversion you have done in this file is incomplete; I suspect that you have not actually built the docs and seen what the results look like. There are literal blocks that you have not marked as such, as a minimum. Please actually do a docs build (after adding this file to index.rst) and make sure that the output is what you intended.

Quoted 6 lines

One other thing of note...this file dates back to before the Git era, and while it has seen numerous tweaks since then, it's clearly outdated. Look at what's actually under /sys/devices/pci* compared to what's documented. I will take the conversion without it, but what I would really like to see would be an effort to document all of the attributes that appear there with current kernels.

If you do go ahead and add/change content (as opposed to simply doing the .txt -> .rst conversion), please do the conversion and the content changes in separate patches. That way the content changes will be easier to review because they won't be mixed in with a lot of mechanical .rst changes.

Bjorn

#6 lore raw

Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

Quoted 37 lines · Bjorn Helgaas
Quoted 23 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <[email protected]> wrote:
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---
------
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-

pci.rst} (82%)

Please supply a changelog with your patches.

The conversion you have done in this file is incomplete; I suspect that
you have not actually built the docs and seen what the results look like.
There are literal blocks that you have not marked as such, as a minimum.
Please actually do a docs build (after adding this file to index.rst) and
make sure that the output is what you intended.

Quoted 11 lines

One other thing of note...this file dates back to before the Git era, and
while it has seen numerous tweaks since then, it's clearly outdated. Look
at what's actually under /sys/devices/pci* compared to what's documented.
I will take the conversion without it, but what I would really like to see
would be an effort to document all of the attributes that appear there
with current kernels.

Quoted 8 lines

If you do go ahead and add/change content (as opposed to simply doing the .txt -> .rst conversion), please do the conversion and the content
changes in separate patches. That way the content changes will be easier to review because they won't be mixed in with a lot of mechanical .rst changes.

Bjorn

Sure, thanks for the review.

BR,
Vitor

#7 lore raw

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

In reply to Vitor Massaru Iha

Documentation/filesystems/sysfs-pci.rst

Quoted 7 lines · Vitor Massaru Iha
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)
Documentation/filesystems/sysfs-pci.rst renamed from Documentation/filesystems/sysfs-pci.txt +0 -0

In addition to Jon's comments, for the next version, I would suggest cc'ing the [email protected] mailing list.

Also, maybe add:

F: Documentation/filesystems/sysfs-pci.rst

to the 'PCI SUBSYSTEM' section of MAINTAINERS.

#8 lore raw

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

Quoted 15 lines · Matthew Wilcox

Documentation/filesystems/sysfs-pci.rst

Quoted 10 lines · Vitor Massaru Iha
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++-----
----
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst}

(82%)

Documentation/filesystems/sysfs-pci.rst renamed from Documentation/filesystems/sysfs-pci.txt +0 -0

In addition to Jon's comments, for the next version, I would suggest cc'ing the [email protected] mailing list.

Quoted 5 lines

Also, maybe add:

F: Documentation/filesystems/sysfs-pci.rst

to the 'PCI SUBSYSTEM' section of MAINTAINERS.

Thanks Matthew.

#9 lore raw

PATCH 2/2 Documentation: filesystems: remove whitespaces

In reply to Vitor Massaru Iha
---
 Documentation/filesystems/sysfs-pci.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/filesystems/sysfs-pci.rst +2 -2
index 9b93e7444b15..e4df647ec9db 100644
@@ -71,11 +71,11 @@ don't support mmapping of certain resources, so be sure to check the return
 value from any attempted mmap.  The most notable of these are I/O port
 resources, which also provide read/write access.
 
-The 'enable' file provides a counter that indicates how many times the device 
+The 'enable' file provides a counter that indicates how many times the device
 has been enabled.  If the 'enable' file currently returns '4', and a '1' is
 echoed into it, it will then return '5'.  Echoing a '0' into it will decrease
 the count.  Even when it returns to 0, though, some of the initialisation
-may not be reversed.  
+may not be reversed.
 
 The 'rom' file is special in that it provides read-only access to the device's
 ROM file, if available.  It's disabled by default, however, so applications
Signature · 1 line
2.21.1
maintainer
#10 lore raw
In reply to Vitor Massaru Iha
Quoted 7 lines · On Tue, 31 Mar 2020 19:28:55 -0300 Vitor Massaru Iha <[email protected]> wrote:

Vitor Massaru Iha (2):
Documentation: filesystems: Convert sysfs-pci to ReST
Documentation: filesystems: remove whitespaces

 .../{sysfs-pci.txt => sysfs-pci.rst}          | 44 ++++++++++---------
 1 file changed, 24 insertions(+), 20 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (81%)

Thanks for working on the documentation! I do have a few comments...

The purpose for including a cover letter on a patch series is to explain what the series as a whole is trying to accomplish. Without that, it's not all the helpful.

In this case, there is no real need for a series; just clean up that trailing whitespace while doing the conversion. (It *is* normally good practice to separate such conversions from other changes, but that particular change is trivial enough that you should just do it while you're there).

When you convert a file to RST, you need to add it to the index.rst file as well so that it can be a part of the documentation build.

Thanks,

jon

#11 lore raw
Quoted 10 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 31 Mar 2020 19:28:55 -0300 Vitor Massaru Iha <[email protected]> wrote:

Vitor Massaru Iha (2):
Documentation: filesystems: Convert sysfs-pci to ReST
Documentation: filesystems: remove whitespaces

 .../{sysfs-pci.txt => sysfs-pci.rst}          | 44 ++++++++++---------
 1 file changed, 24 insertions(+), 20 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (81%)

[]

Quoted 2 lines

When you convert a file to RST, you need to add it to the index.rst file as well so that it can be a part of the documentation build.

And if it's in the MAINTAINERS file, update the file type too.