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%)
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
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
On Tue, 2020-03-31 at 16:57 -0600, Jonathan Corbet wrote:
> 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
Thanks for the review, I will check your comments and correct themif that document is still needed.
BR,
Vitor
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
On Tue, Mar 31, 2020 at 07:28:56PM -0300, Vitor Massaru Iha 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%)
>
> 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 [email protected] mailing list.
Also, maybe add:
F: Documentation/filesystems/sysfs-pci.rst
to the 'PCI SUBSYSTEM' section of MAINTAINERS.
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 <[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%)
> >
> > 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 [email protected] mailing list.
>
> Also, maybe add:
>
> F: Documentation/filesystems/sysfs-pci.rst
>
> to the 'PCI SUBSYSTEM' section of MAINTAINERS.
Thanks Matthew.
On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <[email protected]> wrote:
>
> 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.
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
On Tue, 2020-03-31 at 21:33 -0500, Bjorn Helgaas wrote:
> On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <[email protected]>
> wrote:
> > 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.
>
> 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