* [PATCH 0/2] Documentation: Convert sysfs-pci to ReST @ 2020-03-31 22:28 Vitor Massaru Iha 2020-03-31 22:28 ` [PATCH 1/2] Documentation: filesystems: " Vitor Massaru Iha ` (2 more replies) 0 siblings, 3 replies; 12+ messages in thread From: Vitor Massaru Iha @ 2020-03-31 22:28 UTC (permalink / raw) To: linux-doc Cc: corbet, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees 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%) -- 2.21.1 ^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-03-31 22:28 [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Vitor Massaru Iha @ 2020-03-31 22:28 ` Vitor Massaru Iha 2020-03-31 22:57 ` Jonathan Corbet 2020-04-01 0:04 ` Matthew Wilcox 2020-03-31 22:28 ` [PATCH 2/2] Documentation: filesystems: remove whitespaces Vitor Massaru Iha 2020-03-31 22:49 ` [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Jonathan Corbet 2 siblings, 2 replies; 12+ messages in thread From: Vitor Massaru Iha @ 2020-03-31 22:28 UTC (permalink / raw) To: linux-doc Cc: corbet, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> --- .../{sysfs-pci.txt => sysfs-pci.rst} | 40 ++++++++++--------- 1 file changed, 22 insertions(+), 18 deletions(-) rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%) diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.rst similarity index 82% rename from Documentation/filesystems/sysfs-pci.txt rename to Documentation/filesystems/sysfs-pci.rst index 06f1d64c6f70..9b93e7444b15 100644 --- a/Documentation/filesystems/sysfs-pci.txt +++ b/Documentation/filesystems/sysfs-pci.rst @@ -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 -- 2.21.1 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-03-31 22:28 ` [PATCH 1/2] Documentation: filesystems: " Vitor Massaru Iha @ 2020-03-31 22:57 ` Jonathan Corbet 2020-03-31 23:03 ` Vitor Massaru Iha 2020-04-01 2:33 ` [Linux-kernel-mentees] " Bjorn Helgaas 2020-04-01 0:04 ` Matthew Wilcox 1 sibling, 2 replies; 12+ messages in thread From: Jonathan Corbet @ 2020-03-31 22:57 UTC (permalink / raw) To: Vitor Massaru Iha Cc: linux-doc, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees On Tue, 31 Mar 2020 19:28:56 -0300 Vitor Massaru Iha <vitor@massaru.org> wrote: > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> > --- > .../{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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-03-31 22:57 ` Jonathan Corbet @ 2020-03-31 23:03 ` Vitor Massaru Iha 2020-03-31 23:08 ` Jonathan Corbet 2020-04-01 2:33 ` [Linux-kernel-mentees] " Bjorn Helgaas 1 sibling, 1 reply; 12+ messages in thread From: Vitor Massaru Iha @ 2020-03-31 23:03 UTC (permalink / raw) To: Jonathan Corbet Cc: linux-doc, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees On Tue, 2020-03-31 at 16:57 -0600, Jonathan Corbet wrote: > On Tue, 31 Mar 2020 19:28:56 -0300 > Vitor Massaru Iha <vitor@massaru.org> wrote: > > > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> > > --- > > .../{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 Thanks for the review, I will check your comments and correct themif that document is still needed. BR, Vitor ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-03-31 23:03 ` Vitor Massaru Iha @ 2020-03-31 23:08 ` Jonathan Corbet 0 siblings, 0 replies; 12+ messages in thread From: Jonathan Corbet @ 2020-03-31 23:08 UTC (permalink / raw) To: Vitor Massaru Iha Cc: linux-doc, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees On Tue, 31 Mar 2020 20:03:46 -0300 Vitor Massaru Iha <vitor@massaru.org> 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-03-31 22:57 ` Jonathan Corbet 2020-03-31 23:03 ` Vitor Massaru Iha @ 2020-04-01 2:33 ` Bjorn Helgaas 2020-04-01 17:22 ` Vitor Massaru Iha 1 sibling, 1 reply; 12+ messages in thread From: Bjorn Helgaas @ 2020-04-01 2:33 UTC (permalink / raw) To: Jonathan Corbet Cc: Vitor Massaru Iha, linux-kernel-mentees, Brendan Higgins, LKML, open list:DOCUMENTATION, Mathew Wilcox On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <corbet@lwn.net> wrote: > > On Tue, 31 Mar 2020 19:28:56 -0300 > Vitor Massaru Iha <vitor@massaru.org> wrote: > > > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> > > --- > > .../{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. 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-04-01 2:33 ` [Linux-kernel-mentees] " Bjorn Helgaas @ 2020-04-01 17:22 ` Vitor Massaru Iha 0 siblings, 0 replies; 12+ messages in thread From: Vitor Massaru Iha @ 2020-04-01 17:22 UTC (permalink / raw) To: bjorn, Jonathan Corbet Cc: linux-kernel-mentees, Brendan Higgins, LKML, open list:DOCUMENTATION, Mathew Wilcox On Tue, 2020-03-31 at 21:33 -0500, Bjorn Helgaas wrote: > On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <corbet@lwn.net> > wrote: > > On Tue, 31 Mar 2020 19:28:56 -0300 > > Vitor Massaru Iha <vitor@massaru.org> wrote: > > > > > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> > > > --- > > > .../{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. > > 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-03-31 22:28 ` [PATCH 1/2] Documentation: filesystems: " Vitor Massaru Iha 2020-03-31 22:57 ` Jonathan Corbet @ 2020-04-01 0:04 ` Matthew Wilcox 2020-04-01 0:08 ` Vitor Massaru Iha 1 sibling, 1 reply; 12+ messages in thread From: Matthew Wilcox @ 2020-04-01 0:04 UTC (permalink / raw) To: Vitor Massaru Iha Cc: linux-doc, corbet, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees, linux-pci On Tue, Mar 31, 2020 at 07:28:56PM -0300, Vitor Massaru Iha wrote: > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> > --- > .../{sysfs-pci.txt => sysfs-pci.rst} | 40 ++++++++++--------- > 1 file changed, 22 insertions(+), 18 deletions(-) > rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%) > > diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.rst In addition to Jon's comments, for the next version, I would suggest cc'ing the linux-pci@vger.kernel.org mailing list. Also, maybe add: F: Documentation/filesystems/sysfs-pci.rst to the 'PCI SUBSYSTEM' section of MAINTAINERS. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST 2020-04-01 0:04 ` Matthew Wilcox @ 2020-04-01 0:08 ` Vitor Massaru Iha 0 siblings, 0 replies; 12+ messages in thread From: Vitor Massaru Iha @ 2020-04-01 0:08 UTC (permalink / raw) To: Matthew Wilcox Cc: linux-doc, corbet, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees, linux-pci On Tue, 2020-03-31 at 17:04 -0700, Matthew Wilcox wrote: > On Tue, Mar 31, 2020 at 07:28:56PM -0300, Vitor Massaru Iha wrote: > > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> > > --- > > .../{sysfs-pci.txt => sysfs-pci.rst} | 40 ++++++++++----- > > ---- > > 1 file changed, 22 insertions(+), 18 deletions(-) > > rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} > > (82%) > > > > diff --git a/Documentation/filesystems/sysfs-pci.txt > > b/Documentation/filesystems/sysfs-pci.rst > > In addition to Jon's comments, for the next version, I would suggest > cc'ing the linux-pci@vger.kernel.org mailing list. > > Also, maybe add: > > F: Documentation/filesystems/sysfs-pci.rst > > to the 'PCI SUBSYSTEM' section of MAINTAINERS. Thanks Matthew. ^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 2/2] Documentation: filesystems: remove whitespaces 2020-03-31 22:28 [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Vitor Massaru Iha 2020-03-31 22:28 ` [PATCH 1/2] Documentation: filesystems: " Vitor Massaru Iha @ 2020-03-31 22:28 ` Vitor Massaru Iha 2020-03-31 22:49 ` [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Jonathan Corbet 2 siblings, 0 replies; 12+ messages in thread From: Vitor Massaru Iha @ 2020-03-31 22:28 UTC (permalink / raw) To: linux-doc Cc: corbet, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees Signed-off-by: Vitor Massaru Iha <vitor@massaru.org> --- Documentation/filesystems/sysfs-pci.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst index 9b93e7444b15..e4df647ec9db 100644 --- a/Documentation/filesystems/sysfs-pci.rst +++ b/Documentation/filesystems/sysfs-pci.rst @@ -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 -- 2.21.1 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 0/2] Documentation: Convert sysfs-pci to ReST 2020-03-31 22:28 [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Vitor Massaru Iha 2020-03-31 22:28 ` [PATCH 1/2] Documentation: filesystems: " Vitor Massaru Iha 2020-03-31 22:28 ` [PATCH 2/2] Documentation: filesystems: remove whitespaces Vitor Massaru Iha @ 2020-03-31 22:49 ` Jonathan Corbet 2020-04-01 2:00 ` Joe Perches 2 siblings, 1 reply; 12+ messages in thread From: Jonathan Corbet @ 2020-03-31 22:49 UTC (permalink / raw) To: Vitor Massaru Iha Cc: linux-doc, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees On Tue, 31 Mar 2020 19:28:55 -0300 Vitor Massaru Iha <vitor@massaru.org> 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 0/2] Documentation: Convert sysfs-pci to ReST 2020-03-31 22:49 ` [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Jonathan Corbet @ 2020-04-01 2:00 ` Joe Perches 0 siblings, 0 replies; 12+ messages in thread From: Joe Perches @ 2020-04-01 2:00 UTC (permalink / raw) To: Jonathan Corbet, Vitor Massaru Iha Cc: linux-doc, linux-kernel, brendanhiggins, skhan, linux-kernel-mentees On Tue, 2020-03-31 at 16:49 -0600, Jonathan Corbet wrote: > On Tue, 31 Mar 2020 19:28:55 -0300 > Vitor Massaru Iha <vitor@massaru.org> 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%) [] > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2020-04-01 17:22 UTC | newest] Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-03-31 22:28 [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Vitor Massaru Iha 2020-03-31 22:28 ` [PATCH 1/2] Documentation: filesystems: " Vitor Massaru Iha 2020-03-31 22:57 ` Jonathan Corbet 2020-03-31 23:03 ` Vitor Massaru Iha 2020-03-31 23:08 ` Jonathan Corbet 2020-04-01 2:33 ` [Linux-kernel-mentees] " Bjorn Helgaas 2020-04-01 17:22 ` Vitor Massaru Iha 2020-04-01 0:04 ` Matthew Wilcox 2020-04-01 0:08 ` Vitor Massaru Iha 2020-03-31 22:28 ` [PATCH 2/2] Documentation: filesystems: remove whitespaces Vitor Massaru Iha 2020-03-31 22:49 ` [PATCH 0/2] Documentation: Convert sysfs-pci to ReST Jonathan Corbet 2020-04-01 2:00 ` Joe Perches
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).