Documentation: Convert sysfs-pci to ReST
Subsystems (2)
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
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
@@ -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
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
@@ -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
Jonathan Corbet
maintainerQuoted 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
Jonathan Corbet
maintainerRe: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST
In reply to Vitor Massaru IhaQuoted 5 lines · On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <[email protected]> wrote:
Signed-off-by Vitor Massaru Iha <[email protected]>--- .../{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
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:
Signed-off-by Vitor Massaru Iha <[email protected]>--- .../{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 toindex.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
Jonathan Corbet
maintainerRe: [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
Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST
In reply to Vitor Massaru IhaDocumentation/filesystems/sysfs-pci.rst
Quoted 7 lines · Vitor Massaru Iha
Signed-off-by Vitor Massaru Iha <[email protected]>--- .../{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.
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
Signed-off-by Vitor Massaru Iha <[email protected]>--- .../{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
-0In 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.rstto the 'PCI SUBSYSTEM' section of
MAINTAINERS.
Thanks Matthew.
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.rstfile 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.
Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST
In reply to Jonathan CorbetQuoted 18 lines · Jonathan Corbet
Quoted 5 lines · On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <[email protected]> wrote:
Signed-off-by Vitor Massaru Iha <[email protected]>--- .../{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
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:
Signed-off-by Vitor Massaru Iha <[email protected]>--- .../{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 toindex.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