* Re: [PATCH 04/14] ABI: better identificate tables
From: Johan Hovold @ 2019-06-19 12:51 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Greg Kroah-Hartman, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <6bc45c0d5d464d25d4d16eceac48a2f407166944.1560477540.git.mchehab+samsung@kernel.org>
On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>
> When parsing via script, it is important to know if the script
> should consider a description as a literal block that should
> be displayed as-is, or if the description can be considered
> as a normal text.
>
> Change descriptions to ensure that the preceding line of a table
> ends with a colon. That makes easy to identify the need of a
> literal block.
In the cover letter you say that the first four patches of this series,
including this one, "fix some ABI descriptions that are violating the
syntax described at Documentation/ABI/README". This seems a bit harsh,
given that it's you that is now *introducing* a new syntax requirement
to assist your script.
Specifically, this new requirement isn't documented anywhere AFAICT, so
how will anyone adding new ABI descriptions learn about it?
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra | 2 +-
> .../ABI/testing/sysfs-class-backlight-driver-lm3533 | 6 +++---
> Documentation/ABI/testing/sysfs-class-led-driver-lm3533 | 8 ++++----
> Documentation/ABI/testing/sysfs-class-leds-gt683r | 4 ++--
> Documentation/ABI/testing/sysfs-driver-hid-roccat-kone | 2 +-
> 5 files changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
> index 16020b31ae64..5d41ebadf15e 100644
> --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
> +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
> @@ -5,7 +5,7 @@ Description: It is possible to switch the cpi setting of the mouse with the
> press of a button.
> When read, this file returns the raw number of the actual cpi
> setting reported by the mouse. This number has to be further
> - processed to receive the real dpi value.
> + processed to receive the real dpi value:
>
> VALUE DPI
> 1 400
Johan
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-19 13:04 UTC (permalink / raw)
To: Peter Zijlstra
Cc: Linux Doc Mailing List, Linux Kernel Mailing List,
Jonathan Corbet, Daniel Vetter
In-Reply-To: <20190619104239.GM3419@hirez.programming.kicks-ass.net>
Em Wed, 19 Jun 2019 12:42:39 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:
(reduced the C/C to just the relevant ML/people)
> On Wed, Jun 19, 2019 at 07:22:18AM -0300, Mauro Carvalho Chehab wrote:
> > Hi Daniel,
> >
> > Em Wed, 19 Jun 2019 11:05:57 +0200
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >
> > > On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab
> > > <mchehab+samsung@kernel.org> wrote:
> > > > diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> > > > index fa30dfcfc3c8..b0f948d8733b 100644
> > > > --- a/Documentation/gpu/drm-mm.rst
> > > > +++ b/Documentation/gpu/drm-mm.rst
> > > > @@ -320,7 +320,7 @@ struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
> > > > field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
> > > >
> > > > More detailed information about get_unmapped_area can be found in
> > > > -Documentation/nommu-mmap.rst
> > > > +Documentation/driver-api/nommu-mmap.rst
> > >
> > > Random drive-by comment: Could we convert these into hyperlinks within
> > > sphinx somehow, without making them less useful as raw file references
> > > (with vim I can just type 'gf' and it works, emacs probably the same).
> > > -Daniel
> >
> > Short answer: I don't know how vim/emacs would recognize Sphinx tags.
>
> No, the other way around, Sphinx can recognize local files and treat
> them special. That way we keep the text readable.
>
> Same with that :c:func:'foo' crap, that needs to die, and Sphinx needs
> to be taught about foo().
Just did a test today with Jon's extension with is meant to replace
:c:func:'foo' (with is currently on a separate 'automarkup' branch).
At least the version therestill needs some work, as it currently
mangles with titles and tables. like on those warnings/errors:
6.4 :c:func:`resync_start()`, :c:func:`resync_finish()`
-----------------------------------
/devel/v4l/docs/Documentation/driver-api/md/md-cluster.rst:323: WARNING: Title underline too short.
/devel/v4l/docs/Documentation/driver-api/serial/tty.rst:74: WARNING: Malformed table.
Text in column margin in table line 34.
======================= =======================================================
:c:func:`open()` Called when the line discipline is attached to
-
That's said, once it gets fixed to address those complex cases, a
regex like:
\bDocumentation/([\w\d\-\_\/]+)\.rst\b
could be used to convert to :doc: tag. It should be smart enough to convert
the relative paths, as we refer to the files from the git root directory
(with makes a lot sense to me), while Sphinx :doc: use relative patches
from the location where the parsed file is.
Something like the enclosed patch.
Thanks,
Mauro
[PATCH] automarkup.py: convert Documentation/* to hyperlinks
Auto-create hyperlinks when it finds a Documentation/.. occurrence.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..9d6926b61241 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -9,6 +9,7 @@
from __future__ import print_function
import re
import sphinx
+#import sys # Just for debug
#
# Regex nastiness. Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$')
#
RE_whitesp = re.compile(r'^(\s*)')
+#
+# Get a documentation reference
+#
+RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b')
+
+#
+# Doc link false-positives
+#
+RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst')
+
def MangleFile(app, docname, text):
ret = [ ]
previous = ''
literal = False
+
+ rel_dir = ''
+
+ for depth in range(0, docname.count('/')):
+ rel_dir += "../"
+
for line in text[0].split('\n'):
#
# See if we might be ending a literal block, as denoted by
@@ -63,7 +80,17 @@ def MangleFile(app, docname, text):
# Normal line - perform substitutions.
#
else:
- ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line))
+ new_line = RE_function.sub(r'\1:c:func:`\2`\3', line)
+
+ if not RE_false_doc_links.search(new_line):
+ new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line)
+
+ # # Just for debug - should be removed on production
+ # if new_line != line:
+ # print ("===>" + new_line, file=sys.stderr)
+
+ ret.append(new_line)
+
#
# Might we be starting a literal block? If so make note of
# the fact.
^ permalink raw reply related
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-19 13:19 UTC (permalink / raw)
To: Peter Zijlstra, Linux Doc Mailing List, Jonathan Corbet,
linux-kernel
In-Reply-To: <20190619114356.GP3419@hirez.programming.kicks-ass.net>
(c/c list cleaned)
Em Wed, 19 Jun 2019 13:43:56 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:
> On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
>
> > .../{ => driver-api}/atomic_bitops.rst | 2 -
>
> That's a .txt file, big fat NAK for making it an rst.
Rst is a text file. This one is parsed properly by Sphinx without
any changes.
>
> > .../{ => driver-api}/futex-requeue-pi.rst | 2 -
>
> > .../{ => driver-api}/gcc-plugins.rst | 2 -
>
> > Documentation/{ => driver-api}/kprobes.rst | 2 -
> > .../{ => driver-api}/percpu-rw-semaphore.rst | 2 -
>
> More NAK for rst conversion
Again, those don't need any conversion. Those files already parse
as-is by Sphinx, with no need for any change.
The only change here is that, on patch 1/22, the files that
aren't listed on an index file got a :orphan: added in order
to make this explicit. This patch removes it.
>
> > Documentation/{ => driver-api}/pi-futex.rst | 2 -
> > .../{ => driver-api}/preempt-locking.rst | 2 -
>
> > Documentation/{ => driver-api}/rbtree.rst | 2 -
>
> > .../{ => driver-api}/robust-futex-ABI.rst | 2 -
> > .../{ => driver-api}/robust-futexes.rst | 2 -
>
> > .../{ => driver-api}/speculation.rst | 8 +--
> > .../{ => driver-api}/static-keys.rst | 2 -
>
> > .../{ => driver-api}/this_cpu_ops.rst | 2 -
>
> > Documentation/locking/rt-mutex.rst | 2 +-
>
> NAK. None of the above have anything to do with driver-api.
Ok. Where do you think they should sit instead? core-api?
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: David Howells @ 2019-06-19 13:39 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: dhowells, Linux Doc Mailing List, Linux MM,
Linux Kernel Mailing List
In-Reply-To: <20190619072218.4437f891@coco.lan>
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > > -Documentation/nommu-mmap.rst
> > > +Documentation/driver-api/nommu-mmap.rst
Why is this moving to Documentation/driver-api? It's less to do with drivers
than with the userspace mapping interface. Documentation/vm/ would seem a
better home.
Or should we institute a Documentation/uapi/? Though that might be seen to
overlap with man2. Actually, should this be in man7?
David
^ permalink raw reply
* Re: [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-19 13:56 UTC (permalink / raw)
To: Johan Hovold, Greg Kroah-Hartman
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190619125135.GG25248@localhost>
Hi Johan,
Em Wed, 19 Jun 2019 14:51:35 +0200
Johan Hovold <johan@kernel.org> escreveu:
> On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >
> > When parsing via script, it is important to know if the script
> > should consider a description as a literal block that should
> > be displayed as-is, or if the description can be considered
> > as a normal text.
> >
> > Change descriptions to ensure that the preceding line of a table
> > ends with a colon. That makes easy to identify the need of a
> > literal block.
>
> In the cover letter you say that the first four patches of this series,
> including this one, "fix some ABI descriptions that are violating the
> syntax described at Documentation/ABI/README". This seems a bit harsh,
> given that it's you that is now *introducing* a new syntax requirement
> to assist your script.
Yeah, what's there at the cover letter doesn't apply to this specific
patch. The thing is that I wrote this series a lot of time ago (2016/17).
I revived those per a request at KS ML, as we still need to expose the
ABI content on some book that will be used by userspace people.
So, I just rebased it on the top of curent Kernel, add a cover letter
with the things I remembered and re-sent.
In the specific case of this patch, the ":" there actually makes sense
for someone that it is reading it as a text file, and it is an easy
hack to make it parse better.
> Specifically, this new requirement isn't documented anywhere AFAICT, so
> how will anyone adding new ABI descriptions learn about it?
Yeah, either that or provide an alternative to "Description" tag, to be
used with more complex ABI descriptions.
One of the things that occurred to me, back on 2017, is that we should
have a way to to specify that an specific ABI description would have
a rich format. Something like:
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi
Date: August 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
RST-Description:
It is possible to switch the cpi setting of the mouse with the
press of a button.
When read, this file returns the raw number of the actual cpi
setting reported by the mouse. This number has to be further
processed to receive the real dpi value:
===== =====
VALUE DPI
===== =====
1 400
2 800
4 1600
===== =====
With that, the script will know that the description contents will be using
the ReST markup, and parse it accordingly. Right now, what it does, instead,
is to place the description on a code-block, e. g. it will produce this
output for the description:
::
It is possible to switch the cpi setting of the mouse with the
press of a button.
When read, this file returns the raw number of the actual cpi
setting reported by the mouse. This number has to be further
processed to receive the real dpi value:
VALUE DPI
1 400
2 800
4 1600
Greg,
what do you think?
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1] dma-mapping: Fix filename references
From: Andy Shevchenko @ 2019-06-19 14:13 UTC (permalink / raw)
To: Bjorn Helgaas
Cc: Thomas Gleixner, Ingo Molnar, Borislav Petkov, x86,
H. Peter Anvin, Tony Luck, Fenghua Yu, Konrad Rzeszutek Wilk,
linux-doc, Christoph Hellwig
In-Reply-To: <CAErSpo4v5qxza6Uyo8ZJ1kWWY2eBMxn5JQNQk2kAeZ2PZ2a+Yw@mail.gmail.com>
On Wed, Mar 20, 2019 at 04:31:17PM -0500, Bjorn Helgaas wrote:
> On Wed, Mar 20, 2019 at 11:13 AM Andy Shevchenko
> <andriy.shevchenko@linux.intel.com> wrote:
> >
> > After the commit cf65a0f6f6ff
> >
> > ("dma-mapping: move all DMA mapping code to kernel/dma")
> >
> > some of the files are referring to outdated information, i.e. old file names
> > of DMA mapping sources.
> >
> > Fix it here.
Bjorn, thanks for review, my answers below.
> > * This function checks if the reserved crashkernel is allowed on the specific
> > * IA64 machine flavour. Machines without an IO TLB use swiotlb and require
> > * some memory below 4 GB (i.e. in 32 bit area), see the implementation of
> > - * lib/swiotlb.c. The hpzx1 architecture has an IO TLB but cannot use that
> > + * kernel/dma/swiotlb.c. The hpzx1 architecture has an IO TLB but cannot use that
> > * in kdump case. See the comment in sba_init() in sba_iommu.c.
>
> Is the point here that just that if you lack an IOTLB and want devices
> to be able to reach system memory above 4GB, you need a bounce buffer
> below 4GB? If so, maybe we could just say *that* instead of a
> nebulous reference to "the implementation of */swiotlb.c", which
> doesn't tell you what part of the implementation is relevant.
This patch is about broken links.
> > --- a/arch/x86/kernel/pci-swiotlb.c
> > +++ b/arch/x86/kernel/pci-swiotlb.c
> > @@ -1,5 +1,5 @@
> > // SPDX-License-Identifier: GPL-2.0
> > -/* Glue code to lib/swiotlb.c */
> > +/* Glue code to kernel/dma/swiotlb.c */
>
> I personally don't think there's much value in this line and I'd
> remove it entirely.
Will do.
> > /*
> > - * two parts from lib/swiotlb.c:
> > + * two parts from kernel/dma/swiotlb.c:
> > * -swiotlb size: user-specified with swiotlb= or default.
> > *
> > * -swiotlb overflow buffer: now hardcoded to 32k. We round it
>
> Is there any chance this could be updated to refer to some variable or
> function names that grep/ctags/cscope/etc could find? If we had that,
> I think the filename reference would be superfluous.
I'm not sure. Mauro probably the best person to ask what Sphinx can do here.
> > /*
> > * arch/x86/pci/sta2x11-fixup.c
> > - * glue code for lib/swiotlb.c and DMA translation between STA2x11
> > + * glue code for kernel/dma/swiotlb.c and DMA translation between STA2x11
>
> I think both of these lines (the "arch/x86/pci/sta2x11-fixup.c" one
> and the "glue code" one) are superfluous.
Will remove.
> There's also a superfluous empty line at the end of the GPL license
> text, but I guess that should be removed by replacing the whole thing
> with an SPDX line.
Correct.
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-19 14:15 UTC (permalink / raw)
To: David Howells; +Cc: Linux Doc Mailing List, Linux MM, Linux Kernel Mailing List
In-Reply-To: <11422.1560951550@warthog.procyon.org.uk>
Hi David,
Em Wed, 19 Jun 2019 14:39:10 +0100
David Howells <dhowells@redhat.com> escreveu:
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > > > -Documentation/nommu-mmap.rst
> > > > +Documentation/driver-api/nommu-mmap.rst
>
> Why is this moving to Documentation/driver-api?
Good point. I tried to do my best with those document renames, but
I'm pretty sure some of them ended by going to the wrong place - or
at least there are arguments in favor of moving it to different
places :-)
The driver-api ended to be where most of the stuff has been moved,
as this is the main kAPI dir (there is also a core-api dir for kAPI too).
I tend to place there stuff that has a mix of kAPI and uAPI at
driver-api, as usually such documents are written assuming that
the one that would be reading it is a Kernel developer.
> It's less to do with drivers
> than with the userspace mapping interface. Documentation/vm/ would seem a
> better home.
>
> Or should we institute a Documentation/uapi/? Though that might be seen to
> overlap with man2. Actually, should this be in man7?
Actually, there is an userspace-api dir too. While the logs show that
this was created back on 2017, I only noticed it very recently.
Re-checking the file, I see your point: there are lots of
userspace-relevant contents there. Yet, it also mentions kAPI internals,
like a reference for file and vm ops (at "Providing shareable character
device support" session):
file->f_op->get_unmapped_area()
file->f_op->mmap()
vm_ops->close()
It is up to MM people and Jon to decide where to place it.
In any case, the best (long term) seems to split it on separate files,
one with kAPI and another one with uAPI (just like may other subsystem
specific docs).
Thanks,
Mauro
^ permalink raw reply
* [PATCH v2] dma-mapping: Fix filename references
From: Andy Shevchenko @ 2019-06-19 14:19 UTC (permalink / raw)
To: Thomas Gleixner, Ingo Molnar, Borislav Petkov, x86,
H. Peter Anvin, Tony Luck, Fenghua Yu, Konrad Rzeszutek Wilk,
linux-doc, Christoph Hellwig, Bjorn Helgaas
Cc: Andy Shevchenko
After the commit cf65a0f6f6ff
("dma-mapping: move all DMA mapping code to kernel/dma")
some of the files are referring to outdated information, i.e. old file names
of DMA mapping sources.
Fix it here.
Note, the lines with "Glue code for..." have been removed completely.
Cc: Christoph Hellwig <hch@lst.de>
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
- address Bjorn's comments
Documentation/x86/x86_64/boot-options.rst | 2 +-
arch/ia64/kernel/setup.c | 2 +-
arch/x86/kernel/pci-swiotlb.c | 1 -
arch/x86/kernel/setup.c | 2 +-
arch/x86/pci/sta2x11-fixup.c | 4 +---
5 files changed, 4 insertions(+), 7 deletions(-)
diff --git a/Documentation/x86/x86_64/boot-options.rst b/Documentation/x86/x86_64/boot-options.rst
index 6a4285a3c7a4..2b98efb5ba7f 100644
--- a/Documentation/x86/x86_64/boot-options.rst
+++ b/Documentation/x86/x86_64/boot-options.rst
@@ -230,7 +230,7 @@ IOMMU (input/output memory management unit)
===========================================
Multiple x86-64 PCI-DMA mapping implementations exist, for example:
- 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all
+ 1. <kernel/dma/direct.c>: use no hardware/software IOMMU at all
(e.g. because you have < 3 GB memory).
Kernel boot message: "PCI-DMA: Disabling IOMMU"
diff --git a/arch/ia64/kernel/setup.c b/arch/ia64/kernel/setup.c
index c9cfa760cd57..ab8d25d3e358 100644
--- a/arch/ia64/kernel/setup.c
+++ b/arch/ia64/kernel/setup.c
@@ -256,7 +256,7 @@ __initcall(register_memory);
* This function checks if the reserved crashkernel is allowed on the specific
* IA64 machine flavour. Machines without an IO TLB use swiotlb and require
* some memory below 4 GB (i.e. in 32 bit area), see the implementation of
- * lib/swiotlb.c. The hpzx1 architecture has an IO TLB but cannot use that
+ * kernel/dma/swiotlb.c. The hpzx1 architecture has an IO TLB but cannot use that
* in kdump case. See the comment in sba_init() in sba_iommu.c.
*
* So, the only machvec that really supports loading the kdump kernel
diff --git a/arch/x86/kernel/pci-swiotlb.c b/arch/x86/kernel/pci-swiotlb.c
index 5f5302028a9a..c2cfa5e7c152 100644
--- a/arch/x86/kernel/pci-swiotlb.c
+++ b/arch/x86/kernel/pci-swiotlb.c
@@ -1,5 +1,4 @@
// SPDX-License-Identifier: GPL-2.0
-/* Glue code to lib/swiotlb.c */
#include <linux/pci.h>
#include <linux/cache.h>
diff --git a/arch/x86/kernel/setup.c b/arch/x86/kernel/setup.c
index 08a5f4a131f5..8655bf374893 100644
--- a/arch/x86/kernel/setup.c
+++ b/arch/x86/kernel/setup.c
@@ -477,7 +477,7 @@ static int __init reserve_crashkernel_low(void)
ret = parse_crashkernel_low(boot_command_line, total_low_mem, &low_size, &base);
if (ret) {
/*
- * two parts from lib/swiotlb.c:
+ * two parts from kernel/dma/swiotlb.c:
* -swiotlb size: user-specified with swiotlb= or default.
*
* -swiotlb overflow buffer: now hardcoded to 32k. We round it
diff --git a/arch/x86/pci/sta2x11-fixup.c b/arch/x86/pci/sta2x11-fixup.c
index 97bbc12dd6b2..6269a175385d 100644
--- a/arch/x86/pci/sta2x11-fixup.c
+++ b/arch/x86/pci/sta2x11-fixup.c
@@ -1,8 +1,6 @@
// SPDX-License-Identifier: GPL-2.0-only
/*
- * arch/x86/pci/sta2x11-fixup.c
- * glue code for lib/swiotlb.c and DMA translation between STA2x11
- * AMBA memory mapping and the X86 memory mapping
+ * DMA translation between STA2x11 AMBA memory mapping and the x86 memory mapping
*
* ST Microelectronics ConneXt (STA2X11/STA2X10)
*
--
2.20.1
^ permalink raw reply related
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Jonathan Corbet @ 2019-06-19 14:54 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: David Howells, Linux Doc Mailing List, Linux MM,
Linux Kernel Mailing List
In-Reply-To: <20190619111528.3e2665e3@coco.lan>
[Trimming the CC list from hell made sense, but it might have been better
to leave me on it...]
On Wed, 19 Jun 2019 11:15:28 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Em Wed, 19 Jun 2019 14:39:10 +0100
> David Howells <dhowells@redhat.com> escreveu:
>
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> >
> > > > > -Documentation/nommu-mmap.rst
> > > > > +Documentation/driver-api/nommu-mmap.rst
> >
> > Why is this moving to Documentation/driver-api?
>
> Good point. I tried to do my best with those document renames, but
> I'm pretty sure some of them ended by going to the wrong place - or
> at least there are arguments in favor of moving it to different
> places :-)
I think that a lot of this might also be an argument for slowing down just
a little bit. I really don't think that blasting through and reformatting
all of our text documents is the most urgent problem right now and, in
cases like this, it might create others.
Organization of the documentation tree is important; it has never really
gotten any attention so far, and we're trying to make it better. But
moving documents will, by its nature, annoy people. We can generally get
past that, but I'd really like to avoid moving things twice. In general,
I would rather see a single document converted, read critically and
updated, and carefully integrated with the rest than a hundred of them
swept into different piles...
See what I'm getting at?
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 04/14] ABI: better identificate tables
From: Greg Kroah-Hartman @ 2019-06-19 15:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190619105633.7f7315a5@coco.lan>
On Wed, Jun 19, 2019 at 10:56:33AM -0300, Mauro Carvalho Chehab wrote:
> Hi Johan,
>
> Em Wed, 19 Jun 2019 14:51:35 +0200
> Johan Hovold <johan@kernel.org> escreveu:
>
> > On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > >
> > > When parsing via script, it is important to know if the script
> > > should consider a description as a literal block that should
> > > be displayed as-is, or if the description can be considered
> > > as a normal text.
> > >
> > > Change descriptions to ensure that the preceding line of a table
> > > ends with a colon. That makes easy to identify the need of a
> > > literal block.
> >
> > In the cover letter you say that the first four patches of this series,
> > including this one, "fix some ABI descriptions that are violating the
> > syntax described at Documentation/ABI/README". This seems a bit harsh,
> > given that it's you that is now *introducing* a new syntax requirement
> > to assist your script.
>
> Yeah, what's there at the cover letter doesn't apply to this specific
> patch. The thing is that I wrote this series a lot of time ago (2016/17).
>
> I revived those per a request at KS ML, as we still need to expose the
> ABI content on some book that will be used by userspace people.
>
> So, I just rebased it on the top of curent Kernel, add a cover letter
> with the things I remembered and re-sent.
>
> In the specific case of this patch, the ":" there actually makes sense
> for someone that it is reading it as a text file, and it is an easy
> hack to make it parse better.
>
> > Specifically, this new requirement isn't documented anywhere AFAICT, so
> > how will anyone adding new ABI descriptions learn about it?
>
> Yeah, either that or provide an alternative to "Description" tag, to be
> used with more complex ABI descriptions.
>
> One of the things that occurred to me, back on 2017, is that we should
> have a way to to specify that an specific ABI description would have
> a rich format. Something like:
>
> What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi
> Date: August 2010
> Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
> RST-Description:
> It is possible to switch the cpi setting of the mouse with the
> press of a button.
> When read, this file returns the raw number of the actual cpi
> setting reported by the mouse. This number has to be further
> processed to receive the real dpi value:
>
> ===== =====
> VALUE DPI
> ===== =====
> 1 400
> 2 800
> 4 1600
> ===== =====
>
> With that, the script will know that the description contents will be using
> the ReST markup, and parse it accordingly. Right now, what it does, instead,
> is to place the description on a code-block, e. g. it will produce this
> output for the description:
>
> ::
>
> It is possible to switch the cpi setting of the mouse with the
> press of a button.
> When read, this file returns the raw number of the actual cpi
> setting reported by the mouse. This number has to be further
> processed to receive the real dpi value:
>
> VALUE DPI
> 1 400
> 2 800
> 4 1600
>
>
> Greg,
>
> what do you think?
I don't know when "Description" and "RST-Description" would be used.
Why not just parse "Description" like rst text and if things are "messy"
we fix them up as found, like you did with the ":" here? It doesn't
have to be complex, we can always fix them up after-the-fact if new
stuff gets added that doesn't quite parse properly.
Just like we do for most kernel-doc formatting :)
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-19 15:02 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Peter Zijlstra, Linux Doc Mailing List, Linux Kernel Mailing List
In-Reply-To: <20190619081353.75762028@lwn.net>
Hi Jon,
Em Wed, 19 Jun 2019 08:13:53 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Wed, 19 Jun 2019 12:42:39 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
>
> > No, the other way around, Sphinx can recognize local files and treat
> > them special. That way we keep the text readable.
> >
> > Same with that :c:func:'foo' crap, that needs to die, and Sphinx needs
> > to be taught about foo().
>
> I did a patch to make that latter part happen, but haven't been able to
> find the time to address the comments and get it out there. It definitely
> cleaned up the source files a lot and is worth doing. Will try to get
> back to it soon.
See my comment. Yeah, the :c:func:'foo' (the version you merged at the automarkup
branch) has currently a bug, when there's something like:
func()
======
or when func() is inside a table.
Solving the table case would be a lot better if the plugin could run the
existing table parser and only then handle the cross-reference replacements,
but I've no idea how flexible the Sphinx plugins can be.
>
> The local file links should be easy to do; we shouldn't need to add any
> markup for those.
Yeah, those are easy - except if someone adds a Documentation/* link
inside a table or inside a topic header.
Running a modified version of your tool shows just two new warnings:
Documentation/translations/ja_JP/howto.rst:176: WARNING: undefined label: :doc: (if the link has no caption the label must precede a section header)
Documentation/translations/zh_CN/process/submitting-drivers.rst:25: WARNING: unknown document: ../../../Documentation/translations/zh_CN/process/submitting-patches
The first one is because of this:
:Ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
(my parser didn't consider upper-case tags - a simple fix at a regex should
fix this)
The second one is because the URL is wrong. It is pointing to:
Documentation/Documentation/translations/zh_CN/process/submitting-patches
at Chinese translation.
So, at least the way our documentation is, the plugin seems to be working
as expected.
As a reference, I'm enclosing the diff against your patch:
commit 6231d7456e87bd3e11f892709945887bd55a8a20 (docs/automarkup)
Author: Jonathan Corbet <corbet@lwn.net>
Date: Thu Apr 25 07:55:07 2019 -0600
Docs: An initial automarkup extension for sphinx
Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process. As is always the
case, the real problem is detecting the situations where this markup should
*not* be done.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Thanks,
Mauro
-
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..60dad596c790 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -9,6 +9,7 @@
from __future__ import print_function
import re
import sphinx
+#import sys # Just for debug
#
# Regex nastiness. Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$')
#
RE_whitesp = re.compile(r'^(\s*)')
+#
+# Get a documentation reference
+#
+RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b')
+
+#
+# Doc link false-positives
+#
+RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst')
+
def MangleFile(app, docname, text):
ret = [ ]
previous = ''
literal = False
+
+ rel_dir = ''
+
+ for depth in range(0, docname.count('/')):
+ rel_dir += "../"
+
for line in text[0].split('\n'):
#
# See if we might be ending a literal block, as denoted by
@@ -63,7 +80,18 @@ def MangleFile(app, docname, text):
# Normal line - perform substitutions.
#
else:
- ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line))
+# new_line = RE_function.sub(r'\1:c:func:`\2`\3', line)
+ new_line = line
+
+ if not RE_false_doc_links.search(new_line):
+ new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line)
+
+ # # Just for debug - should be removed on production
+ # if new_line != line:
+ # print ("===>" + new_line, file=sys.stderr)
+
+ ret.append(new_line)
+
#
# Might we be starting a literal block? If so make note of
# the fact.
^ permalink raw reply related
* Re: [PATCH 2/6] docs: trace: add a missing blank line
From: Masami Hiramatsu @ 2019-06-19 15:08 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Masami Hiramatsu, Steven Rostedt (VMware),
Ingo Molnar, Andreas Ziegler, Lecopzer Chen
In-Reply-To: <91f90c10c12c6a2f6fb90fc0f9115fbd8dd73848.1560883872.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 15:51:18 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Sphinx expects a blank line after a literal block markup.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Looks good to me, thanks!
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
> ---
> Documentation/trace/kprobetrace.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index 3d162d432a3c..caa0a8ba081e 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -228,6 +228,7 @@ events, you need to enable it.
>
> Use the following command to start tracing in an interval.
> ::
> +
> # echo 1 > tracing_on
> Open something...
> # echo 0 > tracing_on
> --
> 2.21.0
>
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply
* Re: [PATCH 1/6] docs: trace: fix a broken label
From: Masami Hiramatsu @ 2019-06-19 15:09 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Masami Hiramatsu, Steven Rostedt (VMware),
Andreas Ziegler, Lecopzer Chen
In-Reply-To: <a83ea390bc28784518fce772b4c961ea1c976f14.1560883872.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 15:51:17 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Sphinx warnings about his:
>
> Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)
>
> The problem is quite simple: Sphinx wants a blank line after
> references.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This also looks good to me.
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
Thank you,
> ---
> Documentation/trace/kprobetrace.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index b729b40a5ba5..3d162d432a3c 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
> For $comm, the default type is "string"; any other type is invalid.
>
> .. _user_mem_access:
> +
> User Memory Access
> ------------------
> Kprobe events supports user-space memory access. For that purpose, you can use
> --
> 2.21.0
>
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply
* Re: [PATCH] docs: fb: Add TER16x32 to the available font names
From: Randy Dunlap @ 2019-06-19 15:25 UTC (permalink / raw)
To: Takashi Iwai, Jonathan Corbet
Cc: Bartlomiej Zolnierkiewicz, Greg Kroah-Hartman, linux-doc,
linux-fbdev, linux-kernel
In-Reply-To: <20190619053943.6320-1-tiwai@suse.de>
On 6/18/19 10:39 PM, Takashi Iwai wrote:
> The new font is available since recently.
>
> Signed-off-by: Takashi Iwai <tiwai@suse.de>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.
> ---
> Documentation/fb/fbcon.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
> index cfb9f7c38f18..1da65b9000de 100644
> --- a/Documentation/fb/fbcon.rst
> +++ b/Documentation/fb/fbcon.rst
> @@ -82,7 +82,7 @@ C. Boot options
>
> Select the initial font to use. The value 'name' can be any of the
> compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
> - PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
> + PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, TER16x32, VGA8x16, VGA8x8.
>
> Note, not all drivers can handle font with widths not divisible by 8,
> such as vga16fb.
>
--
~Randy
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Jani Nikula @ 2019-06-19 15:52 UTC (permalink / raw)
To: Jonathan Corbet, Mauro Carvalho Chehab
Cc: David Howells, Linux Doc Mailing List, Linux MM,
Linux Kernel Mailing List
In-Reply-To: <20190619085458.08872dbb@lwn.net>
On Wed, 19 Jun 2019, Jonathan Corbet <corbet@lwn.net> wrote:
> Organization of the documentation tree is important; it has never really
> gotten any attention so far, and we're trying to make it better. But
> moving documents will, by its nature, annoy people. We can generally get
> past that, but I'd really like to avoid moving things twice. In general,
> I would rather see a single document converted, read critically and
> updated, and carefully integrated with the rest than a hundred of them
> swept into different piles...
FWIW, as a first step, my preference would actually be cleaning up the
top level Documentation/ directory. Move every file to an existing or a
new subdirectory, even if just as .txt, or just delete. I understand
this would lead to an extra rst conversion and extension change later,
which you'd like to avoid, but IMO would be helpful.
We could even add an attic directory, which would be a suitable place
for things like zorro.txt. Attic is where I'd look for my old Amiga
hardware, so feels natural.
BR,
Jani.
--
Jani Nikula, Intel Open Source Graphics Center
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-19 15:54 UTC (permalink / raw)
To: Jonathan Corbet
Cc: David Howells, Linux Doc Mailing List, Linux MM,
Linux Kernel Mailing List, Asmaa Mnebhi, Vladimir Oltean
In-Reply-To: <20190619085458.08872dbb@lwn.net>
Em Wed, 19 Jun 2019 08:54:58 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> [Trimming the CC list from hell made sense, but it might have been better
> to leave me on it...]
>
> On Wed, 19 Jun 2019 11:15:28 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > Em Wed, 19 Jun 2019 14:39:10 +0100
> > David Howells <dhowells@redhat.com> escreveu:
> >
> > > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > >
> > > > > > -Documentation/nommu-mmap.rst
> > > > > > +Documentation/driver-api/nommu-mmap.rst
> > >
> > > Why is this moving to Documentation/driver-api?
> >
> > Good point. I tried to do my best with those document renames, but
> > I'm pretty sure some of them ended by going to the wrong place - or
> > at least there are arguments in favor of moving it to different
> > places :-)
>
> I think that a lot of this might also be an argument for slowing down just
> a little bit. I really don't think that blasting through and reformatting
> all of our text documents is the most urgent problem right now and, in
> cases like this, it might create others.
>
> Organization of the documentation tree is important; it has never really
> gotten any attention so far, and we're trying to make it better. But
> moving documents will, by its nature, annoy people. We can generally get
> past that, but I'd really like to avoid moving things twice. In general,
> I would rather see a single document converted, read critically and
> updated, and carefully integrated with the rest than a hundred of them
> swept into different piles...
>
> See what I'm getting at?
I see what you mean, and I agree with this principle. That's basically
why I split the patches into two groups.
The first group (with comes first) does just the conversion
and renames from txt to rst, adding a :orphan: to the stuff that was
just converted.
On this series, those are patches 1 to 11. I was already expecting
some heat on patch 1.
The next group of patches do the renaming part. Those are the ones that
actually took me a lot more time, as I needed to quickly read several docs
in order to understand what's happening, before proposing a change.
That's also the group of patches were I expect more active comments,
as there are several cases where this is not obvious.
Yet, from what I saw, there are some documents that sounds easy to
move, like Documentation/laptops, with (except if I missed something)
clearly belongs to admin-guide.
Applying the second patch series and patches 2 to 11 from this third
series is, IMHO, a good thing to do.
-
IMO, patches 1 and 12 are important, as, after those patches, the
/Documentation dir becomes a lot cleaner:
$ ls -F Documentation/
ABI/ fb/ locking/ s390/
accounting/ features/ logo.gif scheduler/
acpi/ filesystems/ logo.txt scsi/
admin-guide/ firmware_class/ m68k/ security/
arm/ firmware-guide/ maintainer/ sh/
arm64/ fpga/ Makefile sound/
auxdisplay/ gpio/ media/ sparc/
block/ gpu/ mic/ sphinx/
bpf/ hid/ mips/ sphinx-static/
cdrom/ hwmon/ misc-devices/ spi/
Changes@ i2c/ Module.symvers SubmittingPatches
CodingStyle ia64/ netlabel/ target/
conf.py ide/ networking/ timers/
core-api/ iio/ nios2/ trace/
cpu-freq/ index.rst openrisc/ translations/
crypto/ infiniband/ output/ usb/
devicetree/ input/ packing.txt userspace-api/
dev-tools/ ioctl/ parisc/ virtual/
DocBook/ IPMB.txt PCI/ vm/
doc-guide/ isdn/ pcmcia/ w1/
docutils.conf kbuild/ power/ watchdog/
dontdiff Kconfig powerpc/ wimax/
driver-api/ kernel-hacking/ process/ x86/
EDID/ leds/ RCU/ xtensa/
fault-injection/ livepatch/ riscv/
Being easy to identify when someone tries to add a new text file there
without thinking on where it would fit[1], and to reorganize the
directory tree in a way that it will fit our needs.
[1] Btw, there are some two files at linux-next, incrementally
increasing the Documentation/ mess:
IPMB.txt and packing.txt.
Added on those commits:
commit 51bd6f291583684f495ea498984dfc22049d7fd2
Author: Asmaa Mnebhi <Asmaa@mellanox.com>
Date: Mon Jun 10 14:57:02 2019 -0400
Add support for IPMB driver
commit 554aae35007e49f533d3d10e788295f7141725bc
Author: Vladimir Oltean <olteanv@gmail.com>
Date: Thu May 2 23:23:29 2019 +0300
lib: Add support for generic packing operations
We'll never finish organizing documents while people don't stop
adding new files to Documentation/ directory.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-19 16:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190619150207.GA19346@kroah.com>
Em Wed, 19 Jun 2019 17:02:07 +0200
Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> On Wed, Jun 19, 2019 at 10:56:33AM -0300, Mauro Carvalho Chehab wrote:
> > Hi Johan,
> >
> > Em Wed, 19 Jun 2019 14:51:35 +0200
> > Johan Hovold <johan@kernel.org> escreveu:
> >
> > > On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > > > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > >
> > > > When parsing via script, it is important to know if the script
> > > > should consider a description as a literal block that should
> > > > be displayed as-is, or if the description can be considered
> > > > as a normal text.
> > > >
> > > > Change descriptions to ensure that the preceding line of a table
> > > > ends with a colon. That makes easy to identify the need of a
> > > > literal block.
> > >
> > > In the cover letter you say that the first four patches of this series,
> > > including this one, "fix some ABI descriptions that are violating the
> > > syntax described at Documentation/ABI/README". This seems a bit harsh,
> > > given that it's you that is now *introducing* a new syntax requirement
> > > to assist your script.
> >
> > Yeah, what's there at the cover letter doesn't apply to this specific
> > patch. The thing is that I wrote this series a lot of time ago (2016/17).
> >
> > I revived those per a request at KS ML, as we still need to expose the
> > ABI content on some book that will be used by userspace people.
> >
> > So, I just rebased it on the top of curent Kernel, add a cover letter
> > with the things I remembered and re-sent.
> >
> > In the specific case of this patch, the ":" there actually makes sense
> > for someone that it is reading it as a text file, and it is an easy
> > hack to make it parse better.
> >
> > > Specifically, this new requirement isn't documented anywhere AFAICT, so
> > > how will anyone adding new ABI descriptions learn about it?
> >
> > Yeah, either that or provide an alternative to "Description" tag, to be
> > used with more complex ABI descriptions.
> >
> > One of the things that occurred to me, back on 2017, is that we should
> > have a way to to specify that an specific ABI description would have
> > a rich format. Something like:
> >
> > What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi
> > Date: August 2010
> > Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
> > RST-Description:
> > It is possible to switch the cpi setting of the mouse with the
> > press of a button.
> > When read, this file returns the raw number of the actual cpi
> > setting reported by the mouse. This number has to be further
> > processed to receive the real dpi value:
> >
> > ===== =====
> > VALUE DPI
> > ===== =====
> > 1 400
> > 2 800
> > 4 1600
> > ===== =====
> >
> > With that, the script will know that the description contents will be using
> > the ReST markup, and parse it accordingly. Right now, what it does, instead,
> > is to place the description on a code-block, e. g. it will produce this
> > output for the description:
> >
> > ::
> >
> > It is possible to switch the cpi setting of the mouse with the
> > press of a button.
> > When read, this file returns the raw number of the actual cpi
> > setting reported by the mouse. This number has to be further
> > processed to receive the real dpi value:
> >
> > VALUE DPI
> > 1 400
> > 2 800
> > 4 1600
> >
> >
> > Greg,
> >
> > what do you think?
>
> I don't know when "Description" and "RST-Description" would be used.
> Why not just parse "Description" like rst text and if things are "messy"
> we fix them up as found, like you did with the ":" here? It doesn't
> have to be complex, we can always fix them up after-the-fact if new
> stuff gets added that doesn't quite parse properly.
>
> Just like we do for most kernel-doc formatting :)
Works for me. Yet, I guess I tried that, back on 2017.
If I'm not mistaken, the initial patchset to solve the broken things
won't be small, and will be require a lot of attention in order to
identify what's broken and where.
Btw, one thing is to pass at ReST validation. Another thing is to
produce something that people can read.
Right now, the pertinent logic at the script I wrote (scripts/get_abi.pl)
is here:
if (!($desc =~ /^\s*$/)) {
if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
# put everything inside a code block
$desc =~ s/\n/\n /g;
print "::\n\n";
print " $desc\n\n";
} else {
# Escape any special chars from description
$desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
print "$desc\n\n";
}
}
If it discovers something weird enough, it just places everything
into a comment block. Otherwise, it assumes that it is a plain
text and that any special characters should be escaped.
If the above block is replaced by a simple:
print "$desc\n\n";
The description content will be handled as a ReST file.
I don't have any time right now to do this change and to handle the
warnings that will start to popup.
Btw, a single replace there is enough to show the amount of problems that
it will rise, as it will basically break Sphinx build with:
reading sources... [ 1%] admin-guide/abi-testing
reST markup error:
get_abi.pl rest --dir $srctree/Documentation/ABI/testing:45261: (SEVERE/4) Missing matching underline for section title overline.
==========================
PCIe Device AER statistics
These attributes show up under all the devices that are AER capable. These
Thanks,
Mauro
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 7bc619b6890c..e75f441afdcd 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -288,18 +288,18 @@ sub output_rest {
$desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
if (!($desc =~ /^\s*$/)) {
- if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
- # put everything inside a code block
- $desc =~ s/\n/\n /g;
+# if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
+# # put everything inside a code block
+# $desc =~ s/\n/\n /g;
- print "::\n\n";
- print " $desc\n\n";
- } else {
- # Escape any special chars from description
- $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
+# print "::\n\n";
+# print " $desc\n\n";
+# } else {
+# # Escape any special chars from description
+# $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
print "$desc\n\n";
- }
+# }
} else {
print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
}
^ permalink raw reply related
* Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book
From: Mauro Carvalho Chehab @ 2019-06-19 16:37 UTC (permalink / raw)
To: Jani Nikula
Cc: Greg Kroah-Hartman, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
In-Reply-To: <87h88nth3v.fsf@intel.com>
Em Tue, 18 Jun 2019 11:47:32 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> On Mon, 17 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > Yeah, I guess it should be possible to do that. How a python script
> > can identify if it was called by Sphinx, or if it was called directly?
>
> if __name__ == '__main__':
> # run on the command-line, not imported
Ok, when I have some spare time, I may try to convert one script
to python and see how it behaves.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1] dma-mapping: Fix filename references
From: Bjorn Helgaas @ 2019-06-19 17:57 UTC (permalink / raw)
To: Andy Shevchenko
Cc: Thomas Gleixner, Ingo Molnar, Borislav Petkov, x86,
H. Peter Anvin, Tony Luck, Fenghua Yu, Konrad Rzeszutek Wilk,
Linux Doc Mailing List, Christoph Hellwig
In-Reply-To: <20190619141307.GP9224@smile.fi.intel.com>
On Wed, Jun 19, 2019 at 9:13 AM Andy Shevchenko
<andriy.shevchenko@linux.intel.com> wrote:
>
> On Wed, Mar 20, 2019 at 04:31:17PM -0500, Bjorn Helgaas wrote:
> > On Wed, Mar 20, 2019 at 11:13 AM Andy Shevchenko
> > <andriy.shevchenko@linux.intel.com> wrote:
> > >
> > > After the commit cf65a0f6f6ff
> > >
> > > ("dma-mapping: move all DMA mapping code to kernel/dma")
> > >
> > > some of the files are referring to outdated information, i.e. old file names
> > > of DMA mapping sources.
> > >
> > > Fix it here.
>
> Bjorn, thanks for review, my answers below.
>
> > > * This function checks if the reserved crashkernel is allowed on the specific
> > > * IA64 machine flavour. Machines without an IO TLB use swiotlb and require
> > > * some memory below 4 GB (i.e. in 32 bit area), see the implementation of
> > > - * lib/swiotlb.c. The hpzx1 architecture has an IO TLB but cannot use that
> > > + * kernel/dma/swiotlb.c. The hpzx1 architecture has an IO TLB but cannot use that
> > > * in kdump case. See the comment in sba_init() in sba_iommu.c.
> >
> > Is the point here that just that if you lack an IOTLB and want devices
> > to be able to reach system memory above 4GB, you need a bounce buffer
> > below 4GB? If so, maybe we could just say *that* instead of a
> > nebulous reference to "the implementation of */swiotlb.c", which
> > doesn't tell you what part of the implementation is relevant.
>
> This patch is about broken links.
Oh, of course! Sorry, I don't know what I was thinking. I was
wasting my time (and yours) with comments about things you're not
changing, sorry about that.
Bjorn
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Peter Zijlstra @ 2019-06-19 21:27 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, linux-kernel
In-Reply-To: <20190619101922.04340605@coco.lan>
On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> (c/c list cleaned)
>
> Em Wed, 19 Jun 2019 13:43:56 +0200
> Peter Zijlstra <peterz@infradead.org> escreveu:
>
> > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> >
> > > .../{ => driver-api}/atomic_bitops.rst | 2 -
> >
> > That's a .txt file, big fat NAK for making it an rst.
>
> Rst is a text file. This one is parsed properly by Sphinx without
> any changes.
In my tree it is a .txt file, I've not seen patches changing it. And I
disagree, rst is just as much 'a text file' as .c is.
> > > .../{ => driver-api}/futex-requeue-pi.rst | 2 -
> >
> > > .../{ => driver-api}/gcc-plugins.rst | 2 -
> >
> > > Documentation/{ => driver-api}/kprobes.rst | 2 -
> > > .../{ => driver-api}/percpu-rw-semaphore.rst | 2 -
> >
> > More NAK for rst conversion
>
> Again, those don't need any conversion. Those files already parse
> as-is by Sphinx, with no need for any change.
And yet, they're a .txt file in my tree. And I've not seen a rename,
just this move.
> The only change here is that, on patch 1/22, the files that
> aren't listed on an index file got a :orphan: added in order
> to make this explicit. This patch removes it.
I've no idea what :orphan: is. Text file don't have markup.
> > > Documentation/{ => driver-api}/pi-futex.rst | 2 -
> > > .../{ => driver-api}/preempt-locking.rst | 2 -
> >
> > > Documentation/{ => driver-api}/rbtree.rst | 2 -
> >
> > > .../{ => driver-api}/robust-futex-ABI.rst | 2 -
> > > .../{ => driver-api}/robust-futexes.rst | 2 -
> >
> > > .../{ => driver-api}/speculation.rst | 8 +--
> > > .../{ => driver-api}/static-keys.rst | 2 -
> >
> > > .../{ => driver-api}/this_cpu_ops.rst | 2 -
> >
> > > Documentation/locking/rt-mutex.rst | 2 +-
> >
> > NAK. None of the above have anything to do with driver-api.
>
> Ok. Where do you think they should sit instead? core-api?
Pretty much all of then are core-api I tihnk, with exception of the one
that are ABI, which have nothing to do with API. And i've no idea where
GCC plugins go, but it's definitely nothing to do with drivers.
Many of the futex ones are about the sys_futex user API, which
apparently we have Documentation/userspace-api/ for.
Why are you doing this if you've no clue what they're on about?
Just randomly moving files about isn't helpful.
^ permalink raw reply
* Re: [PATCH v5 01/18] kunit: test: add KUnit test runner core
From: Stephen Boyd @ 2019-06-20 0:15 UTC (permalink / raw)
To: Brendan Higgins, frowand.list, gregkh, jpoimboe, keescook,
kieran.bingham, mcgrof, peterz, robh, shuah, tytso,
yamada.masahiro
Cc: devicetree, dri-devel, kunit-dev, linux-doc, linux-fsdevel,
linux-kbuild, linux-kernel, linux-kselftest, linux-nvdimm,
linux-um, Alexander.Levin, Tim.Bird, amir73il, dan.carpenter,
daniel, jdike, joel, julia.lawall, khilman, knut.omang, logang,
mpe, pmladek, rdunlap, richard, rientjes, rostedt, wfg,
Brendan Higgins
In-Reply-To: <20190617082613.109131-2-brendanhiggins@google.com>
Quoting Brendan Higgins (2019-06-17 01:25:56)
> diff --git a/kunit/test.c b/kunit/test.c
> new file mode 100644
> index 0000000000000..d05d254f1521f
> --- /dev/null
> +++ b/kunit/test.c
> @@ -0,0 +1,210 @@
> +// SPDX-License-Identifier: GPL-2.0
> +/*
> + * Base unit test (KUnit) API.
> + *
> + * Copyright (C) 2019, Google LLC.
> + * Author: Brendan Higgins <brendanhiggins@google.com>
> + */
> +
> +#include <linux/sched/debug.h>
> +#include <kunit/test.h>
> +
> +static bool kunit_get_success(struct kunit *test)
> +{
> + unsigned long flags;
> + bool success;
> +
> + spin_lock_irqsave(&test->lock, flags);
> + success = test->success;
> + spin_unlock_irqrestore(&test->lock, flags);
I still don't understand the locking scheme in this code. Is the
intention to make getter and setter APIs that are "safe" by adding in a
spinlock that is held around getting and setting various members in the
kunit structure?
In what situation is there more than one thread reading or writing the
kunit struct? Isn't it only a single process that is going to be
operating on this structure? And why do we need to disable irqs? Are we
expecting to be modifying the unit tests from irq contexts?
> +
> + return success;
> +}
> +
> +static void kunit_set_success(struct kunit *test, bool success)
> +{
> + unsigned long flags;
> +
> + spin_lock_irqsave(&test->lock, flags);
> + test->success = success;
> + spin_unlock_irqrestore(&test->lock, flags);
> +}
> +
> +static int kunit_vprintk_emit(int level, const char *fmt, va_list args)
> +{
> + return vprintk_emit(0, level, NULL, 0, fmt, args);
> +}
> +
> +static int kunit_printk_emit(int level, const char *fmt, ...)
> +{
> + va_list args;
> + int ret;
> +
> + va_start(args, fmt);
> + ret = kunit_vprintk_emit(level, fmt, args);
> + va_end(args);
> +
> + return ret;
> +}
> +
> +static void kunit_vprintk(const struct kunit *test,
> + const char *level,
> + struct va_format *vaf)
> +{
> + kunit_printk_emit(level[1] - '0', "\t# %s: %pV", test->name, vaf);
> +}
> +
> +static bool kunit_has_printed_tap_version;
Can you please move this into function local scope in the function
below?
> +
> +static void kunit_print_tap_version(void)
> +{
> + if (!kunit_has_printed_tap_version) {
> + kunit_printk_emit(LOGLEVEL_INFO, "TAP version 14\n");
> + kunit_has_printed_tap_version = true;
> + }
> +}
> +
[...]
> +
> +static bool kunit_module_has_succeeded(struct kunit_module *module)
> +{
> + const struct kunit_case *test_case;
> + bool success = true;
> +
> + for (test_case = module->test_cases; test_case->run_case; test_case++)
> + if (!test_case->success) {
> + success = false;
> + break;
Why not 'return false'?
> + }
> +
> + return success;
And 'return true'?
> +}
> +
> +static size_t kunit_module_counter = 1;
> +
> +static void kunit_print_subtest_end(struct kunit_module *module)
> +{
> + kunit_print_ok_not_ok(false,
> + kunit_module_has_succeeded(module),
> + kunit_module_counter++,
> + module->name);
> +}
> +
> +static void kunit_print_test_case_ok_not_ok(struct kunit_case *test_case,
> + size_t test_number)
> +{
> + kunit_print_ok_not_ok(true,
> + test_case->success,
> + test_number,
> + test_case->name);
> +}
> +
> +void kunit_init_test(struct kunit *test, const char *name)
> +{
> + spin_lock_init(&test->lock);
> + test->name = name;
> + test->success = true;
> +}
> +
> +/*
> + * Performs all logic to run a test case.
> + */
> +static void kunit_run_case(struct kunit_module *module,
> + struct kunit_case *test_case)
> +{
> + struct kunit test;
> + int ret = 0;
> +
> + kunit_init_test(&test, test_case->name);
> +
> + if (module->init) {
> + ret = module->init(&test);
> + if (ret) {
> + kunit_err(&test, "failed to initialize: %d\n", ret);
> + kunit_set_success(&test, false);
> + return;
> + }
> + }
> +
> + if (!ret)
> + test_case->run_case(&test);
Do we need this if condition? ret can only be set to non-zero above but
then we'll exit the function early so it seems unnecessary. Given that,
ret should probably be moved into the module->init path.
> +
> + if (module->exit)
> + module->exit(&test);
> +
> + test_case->success = kunit_get_success(&test);
> +}
> +
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: Frank Rowand @ 2019-06-20 1:17 UTC (permalink / raw)
To: Brendan Higgins, gregkh, jpoimboe, keescook, kieran.bingham,
mcgrof, peterz, robh, sboyd, shuah, tytso, yamada.masahiro
Cc: devicetree, dri-devel, kunit-dev, linux-doc, linux-fsdevel,
linux-kbuild, linux-kernel, linux-kselftest, linux-nvdimm,
linux-um, Alexander.Levin, Tim.Bird, amir73il, dan.carpenter,
daniel, jdike, joel, julia.lawall, khilman, knut.omang, logang,
mpe, pmladek, rdunlap, richard, rientjes, rostedt, wfg
In-Reply-To: <20190617082613.109131-1-brendanhiggins@google.com>
Hi Brendan,
I am only responding to this because you asked me to in the v4 thread.
Thank you for evaluating my comments in the v4 thread and asking me to
comment on v5
On 6/17/19 1:25 AM, Brendan Higgins wrote:
> ## TL;DR
>
> A not so quick follow-up to Stephen's suggestions on PATCH v4. Nothing
> that really changes any functionality or usage with the minor exception
> of a couple public functions that Stephen asked me to rename.
> Nevertheless, a good deal of clean up and fixes. See changes below.
>
> As for our current status, right now we got Reviewed-bys on all patches
> except:
>
> - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
> list
>
> However, it would probably be good to get reviews/acks from the
> subsystem maintainers on:
>
> - [PATCH v5 06/18] kbuild: enable building KUnit
> - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
> list
> - [PATCH v5 15/18] Documentation: kunit: add documentation for KUnit
> - [PATCH v5 17/18] kernel/sysctl-test: Add null pointer test for
> sysctl.c:proc_dointvec()
> - [PATCH v5 18/18] MAINTAINERS: add proc sysctl KUnit test to PROC
> SYSCTL section
>
> Other than that, I think we should be good to go.
>
> One last thing, I updated the background to include my thoughts on KUnit
> vs. in kernel testing with kselftest in the background sections as
> suggested by Frank in the discussion on PATCH v2.
>
> ## Background
>
> This patch set proposes KUnit, a lightweight unit testing and mocking
> framework for the Linux kernel.
>
> Unlike Autotest and kselftest, KUnit is a true unit testing framework;
> it does not require installing the kernel on a test machine or in a VM
> (however, KUnit still allows you to run tests on test machines or in VMs
> if you want[1]) and does not require tests to be written in userspace
> running on a host kernel. Additionally, KUnit is fast: From invocation
> to completion KUnit can run several dozen tests in under a second.
> Currently, the entire KUnit test suite for KUnit runs in under a second
> from the initial invocation (build time excluded).
>
> KUnit is heavily inspired by JUnit, Python's unittest.mock, and
> Googletest/Googlemock for C++. KUnit provides facilities for defining
> unit test cases, grouping related test cases into test suites, providing
> common infrastructure for running tests, mocking, spying, and much more.
>
I looked only at this section, as was specifically requested:
> ### But wait! Doesn't kselftest support in kernel testing?!
>
> In a previous version of this patchset Frank pointed out that kselftest
> already supports writing a test that resides in the kernel using the
> test module feature[2]. LWN did a really great summary on this
> discussion here[3].
>
> Kselftest has a feature that allows a test module to be loaded into a
> kernel using the kselftest framework; this does allow someone to write
> tests against kernel code not directly exposed to userland; however, it
> does not provide much of a framework around how to structure the tests.
> The kselftest test module feature just provides a header which has a
> standardized way of reporting test failures,
> and then provides
> infrastructure to load and run the tests using the kselftest test
> harness.
The in-kernel tests can also be invoked at boot time if they are
configured (Kconfig) as in-kernel instead of as modules. I did not
check how many of the tests have tri-state configuration to allow
this, but the few that I looked at did.
>
> The kselftest test module does not seem to be opinionated at all in
> regards to how tests are structured, how they check for failures, how
> tests are organized. Even in the method it provides for reporting
> failures is pretty simple; it doesn't have any more advanced failure
> reporting or logging features. Given what's there, I think it is fair to
> say that it is not actually a framework, but a feature that makes it
> possible for someone to do some checks in kernel space.
I would call that description a little dismissive. The set of in-kernel
tests that I looked like followed a common pattern and reported results
in a uniform manner.
>
> Furthermore, kselftest test module has very few users. I checked for all
> the tests that use it using the following grep command:
>
> grep -Hrn -e 'kselftest_module\.h'
>
> and only got three results: lib/test_strscpy.c, lib/test_printf.c, and
> lib/test_bitmap.c.
You missed many tests. I listed much more than that in the v4 thread, and
someone else also listed more in the v4 thread.
>
> So despite kselftest test module's existence, there really is no feature
> overlap between kselftest and KUnit, save one: that you can use either
> to write an in-kernel test, but this is a very small feature in
> comparison to everything that KUnit allows you to do. KUnit is a full
> x-unit style unit testing framework, whereas kselftest looks a lot more
> like an end-to-end/functional testing framework, with a feature that
> makes it possible to write in-kernel tests.
The description does not give enough credit to what is in kselftest.
It does not matter whether KUnit provides additional things, relative
to kselftest. The point I was making is that there appears to be
_some_ overlap between kselftest and KUnit, and if there is overlap
then it is worth considering whether the overlap can be unified instead
of duplicated.
I don't have a dog in this fight and the discussion in the v4 thread
went way off track. Thus I am not going to get sucked back into a
pointless debate in this thread.
Thanks for adding this section to address the issue.
-Frank
>
> ### What's so special about unit testing?
>
> A unit test is supposed to test a single unit of code in isolation,
> hence the name. There should be no dependencies outside the control of
> the test; this means no external dependencies, which makes tests orders
> of magnitudes faster. Likewise, since there are no external dependencies,
> there are no hoops to jump through to run the tests. Additionally, this
> makes unit tests deterministic: a failing unit test always indicates a
> problem. Finally, because unit tests necessarily have finer granularity,
> they are able to test all code paths easily solving the classic problem
> of difficulty in exercising error handling code.
>
> ### Is KUnit trying to replace other testing frameworks for the kernel?
>
> No. Most existing tests for the Linux kernel are end-to-end tests, which
> have their place. A well tested system has lots of unit tests, a
> reasonable number of integration tests, and some end-to-end tests. KUnit
> is just trying to address the unit test space which is currently not
> being addressed.
>
> ### More information on KUnit
>
> There is a bunch of documentation near the end of this patch set that
> describes how to use KUnit and best practices for writing unit tests.
> For convenience I am hosting the compiled docs here[4].
>
> Additionally for convenience, I have applied these patches to a
> branch[5]. The repo may be cloned with:
> git clone https://kunit.googlesource.com/linux
> This patchset is on the kunit/rfc/v5.2-rc4/v5 branch.
>
> ## Changes Since Last Version
>
> Aside from a couple public function renames, there isn't really anything
> in here that changes any functionality.
>
> - Went through and fixed a couple of anti-patterns suggested by Stephen
> Boyd. Things like:
> - Dropping an else clause at the end of a function.
> - Dropping the comma on the closing sentinel, `{}`, of a list.
> - Inlines a bunch of functions in the test case running logic in patch
> 01/18 to make it more readable as suggested by Stephen Boyd
> - Found and fixed bug in resource deallocation logic in patch 02/18. Bug
> was discovered as a result of making a change suggested by Stephen
> Boyd. This does not substantially change how any of the code works
> conceptually.
> - Renamed new_string_stream() to alloc_string_stream() as suggested by
> Stephen Boyd.
> - Made string-stream a KUnit managed object - based on a suggestion made
> by Stephen Boyd.
> - Renamed kunit_new_stream() to alloc_kunit_stream() as suggested by
> Stephen Boyd.
> - Removed the ability to set log level after allocating a kunit_stream,
> as suggested by Stephen Boyd.
>
> [1] https://google.github.io/kunit-docs/third_party/kernel/docs/usage.html#kunit-on-non-uml-architectures
> [2] https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html#test-module
> [3] https://lwn.net/Articles/790235/
> [4] https://google.github.io/kunit-docs/third_party/kernel/docs/
> [5] https://kunit.googlesource.com/linux/+/kunit/rfc/v5.2-rc4/v5
>
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-20 2:24 UTC (permalink / raw)
To: Peter Zijlstra; +Cc: Linux Doc Mailing List, Jonathan Corbet, linux-kernel
In-Reply-To: <20190619212753.GQ3419@hirez.programming.kicks-ass.net>
Em Wed, 19 Jun 2019 23:27:53 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:
> On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> > (c/c list cleaned)
> >
> > Em Wed, 19 Jun 2019 13:43:56 +0200
> > Peter Zijlstra <peterz@infradead.org> escreveu:
> >
> > > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> > >
> > > > .../{ => driver-api}/atomic_bitops.rst | 2 -
> > >
> > > That's a .txt file, big fat NAK for making it an rst.
> >
> > Rst is a text file. This one is parsed properly by Sphinx without
> > any changes.
>
> In my tree it is a .txt file, I've not seen patches changing it. And I
> disagree, rst is just as much 'a text file' as .c is.
ReStructured text is just text with a stricter style + some commands,
if the text author wants to enhance it.
Btw, I'm glad you mentioned c.
This is c:
int
func( int a, int
b ) {
return a + b;
}
This is also c:
func(int a,int b) { goto foo;
foo:
return(a+b) }
K&R style is also c, and this is also c:
#define f(a,b) (a+b)
Despite none of the above matches my taste - and some have issues - they
all build with gcc.
Yet, none of the above follows the Kernel coding style.
The way we use ReST (with absolute minimal changes), it becomes just
a text style.
Btw, I agree with you: there are some odd things at its style - and we
should work to try to reduce this to its minimal extent.
>
> > > > .../{ => driver-api}/futex-requeue-pi.rst | 2 -
> > >
> > > > .../{ => driver-api}/gcc-plugins.rst | 2 -
> > >
> > > > Documentation/{ => driver-api}/kprobes.rst | 2 -
> > > > .../{ => driver-api}/percpu-rw-semaphore.rst | 2 -
> > >
> > > More NAK for rst conversion
> >
> > Again, those don't need any conversion. Those files already parse
> > as-is by Sphinx, with no need for any change.
>
> And yet, they're a .txt file in my tree. And I've not seen a rename,
> just this move.
Rename is on patch 1/22.
No matter the extension, all the above files pass at the Sphinx style
validation without warnings or errors. Patch 1/22 doesn't make any
conversion.
Btw, the .rst extension is just a convenient way to help identifying what
was not validated. If I'm not mistaken, when the discussions about a
replacement for DocBook started at at linux-doc, someone proposed to
keep the .txt extension (changing it to accept .rst, .txt or both is
a single line change at conf.py).
>
> > The only change here is that, on patch 1/22, the files that
> > aren't listed on an index file got a :orphan: added in order
> > to make this explicit. This patch removes it.
>
> I've no idea what :orphan: is. Text file don't have markup.
>
> > > > Documentation/{ => driver-api}/pi-futex.rst | 2 -
> > > > .../{ => driver-api}/preempt-locking.rst | 2 -
> > >
> > > > Documentation/{ => driver-api}/rbtree.rst | 2 -
> > >
> > > > .../{ => driver-api}/robust-futex-ABI.rst | 2 -
> > > > .../{ => driver-api}/robust-futexes.rst | 2 -
> > >
> > > > .../{ => driver-api}/speculation.rst | 8 +--
> > > > .../{ => driver-api}/static-keys.rst | 2 -
> > >
> > > > .../{ => driver-api}/this_cpu_ops.rst | 2 -
> > >
> > > > Documentation/locking/rt-mutex.rst | 2 +-
> > >
> > > NAK. None of the above have anything to do with driver-api.
> >
> > Ok. Where do you think they should sit instead? core-api?
>
> Pretty much all of then are core-api I tihnk, with exception of the one
> that are ABI, which have nothing to do with API.
OK.
> And i've no idea where
> GCC plugins go, but it's definitely nothing to do with drivers.
I suspect that Documentation/security would be a better place
for GCC plugins (as it has been discussed at kernel-hardening ML),
but I'm waiting a feedback from Kees.
>
> Many of the futex ones are about the sys_futex user API, which
> apparently we have Documentation/userspace-api/ for.
Yeah, it makes sense to place sys_futex there.
Despite being an old dir, it is not too popular: there are
very few document there. I only discovered this one a few
days ago.
>
> Why are you doing this if you've no clue what they're on about?
I don't pretend to know precisely where each document will fit.
If you read carefully the content of each orphaned document, you'll see
that many of them have uAPI, kAPI and admin-guide info inside.
To be frank, I actually tried to get rid of this document shift
part, but a Jon's feedback when I submitted a much simpler RFC
patchset challenged me to try to place each document on some place. The
renaming part is by far a lot more complex than the conversion,
because depending on how you interpret the file contents -
and the description of each documentation chapter - it may fit on a
different subdir.
-
My main goal is to have an organized body with the documentation.
Try to read our docs as if it is a book, and you'll see what I'm talking
about: there are important missing parts, the document order isn't in
an order that would make easier for the headers, several documents are
placed on random places, etc.
Just like we have Makefiles, the index.rst files, plus the subdirectories
help to classify and organize the documentation on a coherent way.
-
The main problem I want to address with this particular patch is that
there are so many random documents from all sorts of subject at
Documentation/*.txt that it makes really hard to see the document
structure or to organize them.
Also, keeping txt files there at the root doc dir is a bad idea, as
people keep flooding Documentation/ root with new unclassified documents
on almost every Kernel version.
After 5.1, there are two new documents added inside Documentation/*.txt
(I guess both added at linux-next for 5.3).
I proposed a few months ago to create a Documentation/staging, and do:
mv Documentation/*.txt Documentation/*.rst Documentation/staging
Jani proposed today something similar to it (Documentation/attic)
The name is not important. Having a place were we can temporarily
place documents while we organize the directory structure and the
documentation indexes seem to be the best way to reorganize the
docs on a coherent way.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1 21/22] docs: admin-guide: add laptops documentation
From: Andy Shevchenko @ 2019-06-20 6:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Matan Ziv-Av,
Mattia Dongili, Arnd Bergmann, Greg Kroah-Hartman, Darren Hart,
Andy Shevchenko, Platform Driver
In-Reply-To: <48cf367612aeec99f9eef54bb57685eb3b6c4ebf.1560891322.git.mchehab+samsung@kernel.org>
On Wed, Jun 19, 2019 at 12:05 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The docs under Documentation/laptops contain users specific
> information.
>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
with a caveat about Documentation/admin-guide/sysctl/vm.rst.
How block bump is related to laptops? It sounds rather common
debugging feature, no?
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/ABI/testing/sysfs-block-device | 2 +-
> Documentation/ABI/testing/sysfs-platform-asus-laptop | 2 +-
> Documentation/admin-guide/index.rst | 1 +
> Documentation/admin-guide/kernel-parameters.txt | 2 +-
> Documentation/{ => admin-guide}/laptops/asus-laptop.rst | 0
> .../{ => admin-guide}/laptops/disk-shock-protection.rst | 0
> Documentation/{ => admin-guide}/laptops/index.rst | 1 -
> Documentation/{ => admin-guide}/laptops/laptop-mode.rst | 0
> Documentation/{ => admin-guide}/laptops/lg-laptop.rst | 1 -
> Documentation/{ => admin-guide}/laptops/sony-laptop.rst | 0
> Documentation/{ => admin-guide}/laptops/sonypi.rst | 0
> Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst | 0
> Documentation/{ => admin-guide}/laptops/toshiba_haps.rst | 0
> Documentation/admin-guide/sysctl/vm.rst | 4 ++--
> MAINTAINERS | 4 ++--
> drivers/char/Kconfig | 2 +-
> drivers/platform/x86/Kconfig | 4 ++--
> 17 files changed, 11 insertions(+), 12 deletions(-)
> rename Documentation/{ => admin-guide}/laptops/asus-laptop.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/disk-shock-protection.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/index.rst (95%)
> rename Documentation/{ => admin-guide}/laptops/laptop-mode.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/lg-laptop.rst (99%)
> rename Documentation/{ => admin-guide}/laptops/sony-laptop.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/sonypi.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/toshiba_haps.rst (100%)
>
> diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
> index 0d57bbb4fddc..17f2bc7dd261 100644
> --- a/Documentation/ABI/testing/sysfs-block-device
> +++ b/Documentation/ABI/testing/sysfs-block-device
> @@ -45,7 +45,7 @@ Description:
> - Values below -2 are rejected with -EINVAL
>
> For more information, see
> - Documentation/laptops/disk-shock-protection.rst
> + Documentation/admin-guide/laptops/disk-shock-protection.rst
>
>
> What: /sys/block/*/device/ncq_prio_enable
> diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
> index d67fa4bafa70..8b0e8205a6a2 100644
> --- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
> +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
> @@ -31,7 +31,7 @@ Description:
> To control the LED display, use the following :
> echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
> where T control the 3 letters display, and DDD the 3 digits display.
> - The DDD table can be found in Documentation/laptops/asus-laptop.rst
> + The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
>
> What: /sys/devices/platform/asus_laptop/bluetooth
> Date: January 2007
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 5940ce8d16af..e4f0cb2a02bd 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -79,6 +79,7 @@ configure specific aspects of kernel behavior to your liking.
> aoe/index
> perf-security
> acpi/index
> + laptops/index
>
> btmrvl
> clearing-warn-once
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 0b17312b9198..69a9e2e66dfb 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -4356,7 +4356,7 @@
> Format: <integer>
>
> sonypi.*= [HW] Sony Programmable I/O Control Device driver
> - See Documentation/laptops/sonypi.rst
> + See Documentation/admin-guide/laptops/sonypi.rst
>
> spectre_v2= [X86] Control mitigation of Spectre variant 2
> (indirect branch speculation) vulnerability.
> diff --git a/Documentation/laptops/asus-laptop.rst b/Documentation/admin-guide/laptops/asus-laptop.rst
> similarity index 100%
> rename from Documentation/laptops/asus-laptop.rst
> rename to Documentation/admin-guide/laptops/asus-laptop.rst
> diff --git a/Documentation/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst
> similarity index 100%
> rename from Documentation/laptops/disk-shock-protection.rst
> rename to Documentation/admin-guide/laptops/disk-shock-protection.rst
> diff --git a/Documentation/laptops/index.rst b/Documentation/admin-guide/laptops/index.rst
> similarity index 95%
> rename from Documentation/laptops/index.rst
> rename to Documentation/admin-guide/laptops/index.rst
> index 001a30910d09..6b554e39863b 100644
> --- a/Documentation/laptops/index.rst
> +++ b/Documentation/admin-guide/laptops/index.rst
> @@ -1,4 +1,3 @@
> -:orphan:
>
> ==============
> Laptop Drivers
> diff --git a/Documentation/laptops/laptop-mode.rst b/Documentation/admin-guide/laptops/laptop-mode.rst
> similarity index 100%
> rename from Documentation/laptops/laptop-mode.rst
> rename to Documentation/admin-guide/laptops/laptop-mode.rst
> diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/admin-guide/laptops/lg-laptop.rst
> similarity index 99%
> rename from Documentation/laptops/lg-laptop.rst
> rename to Documentation/admin-guide/laptops/lg-laptop.rst
> index f2c2ffe31101..ce9b14671cb9 100644
> --- a/Documentation/laptops/lg-laptop.rst
> +++ b/Documentation/admin-guide/laptops/lg-laptop.rst
> @@ -1,6 +1,5 @@
> .. SPDX-License-Identifier: GPL-2.0+
>
> -:orphan:
>
> LG Gram laptop extra features
> =============================
> diff --git a/Documentation/laptops/sony-laptop.rst b/Documentation/admin-guide/laptops/sony-laptop.rst
> similarity index 100%
> rename from Documentation/laptops/sony-laptop.rst
> rename to Documentation/admin-guide/laptops/sony-laptop.rst
> diff --git a/Documentation/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst
> similarity index 100%
> rename from Documentation/laptops/sonypi.rst
> rename to Documentation/admin-guide/laptops/sonypi.rst
> diff --git a/Documentation/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
> similarity index 100%
> rename from Documentation/laptops/thinkpad-acpi.rst
> rename to Documentation/admin-guide/laptops/thinkpad-acpi.rst
> diff --git a/Documentation/laptops/toshiba_haps.rst b/Documentation/admin-guide/laptops/toshiba_haps.rst
> similarity index 100%
> rename from Documentation/laptops/toshiba_haps.rst
> rename to Documentation/admin-guide/laptops/toshiba_haps.rst
> diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst
> index 4940ab610eb7..d918b11326f3 100644
> --- a/Documentation/admin-guide/sysctl/vm.rst
> +++ b/Documentation/admin-guide/sysctl/vm.rst
> @@ -108,7 +108,7 @@ block_dump
> ==========
>
> block_dump enables block I/O debugging when set to a nonzero value. More
> -information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
> +information on block I/O debugging is in Documentation/admin-guide/laptops/laptop-mode.rst.
>
>
> compact_memory
> @@ -298,7 +298,7 @@ laptop_mode
> ===========
>
> laptop_mode is a knob that controls "laptop mode". All the things that are
> -controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
> +controlled by this knob are discussed in Documentation/admin-guide/laptops/laptop-mode.rst.
>
>
> legacy_va_layout
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b7c81bd0f8e8..ab170522ec55 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8927,7 +8927,7 @@ M: Matan Ziv-Av <matan@svgalib.org>
> L: platform-driver-x86@vger.kernel.org
> S: Maintained
> F: Documentation/ABI/testing/sysfs-platform-lg-laptop
> -F: Documentation/laptops/lg-laptop.rst
> +F: Documentation/admin-guide/laptops/lg-laptop.rst
> F: drivers/platform/x86/lg-laptop.c
>
> LG2160 MEDIA DRIVER
> @@ -14756,7 +14756,7 @@ M: Mattia Dongili <malattia@linux.it>
> L: platform-driver-x86@vger.kernel.org
> W: http://www.linux.it/~malattia/wiki/index.php/Sony_drivers
> S: Maintained
> -F: Documentation/laptops/sony-laptop.rst
> +F: Documentation/admin-guide/laptops/sony-laptop.rst
> F: drivers/char/sonypi.c
> F: drivers/platform/x86/sony-laptop.c
> F: include/linux/sony-laptop.h
> diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
> index 3a0f94929814..3e866885a405 100644
> --- a/drivers/char/Kconfig
> +++ b/drivers/char/Kconfig
> @@ -382,7 +382,7 @@ config SONYPI
> Device which can be found in many (all ?) Sony Vaio laptops.
>
> If you have one of those laptops, read
> - <file:Documentation/laptops/sonypi.rst>, and say Y or M here.
> + <file:Documentation/admin-guide/laptops/sonypi.rst>, and say Y or M here.
>
> To compile this driver as a module, choose M here: the
> module will be called sonypi.
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index 9d866b6753fe..430f7f619553 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -451,7 +451,7 @@ config SONY_LAPTOP
> screen brightness control, Fn keys and allows powering on/off some
> devices.
>
> - Read <file:Documentation/laptops/sony-laptop.rst> for more information.
> + Read <file:Documentation/admin-guide/laptops/sony-laptop.rst> for more information.
>
> config SONYPI_COMPAT
> bool "Sonypi compatibility"
> @@ -503,7 +503,7 @@ config THINKPAD_ACPI
> support for Fn-Fx key combinations, Bluetooth control, video
> output switching, ThinkLight control, UltraBay eject and more.
> For more information about this driver see
> - <file:Documentation/laptops/thinkpad-acpi.rst> and
> + <file:Documentation/admin-guide/laptops/thinkpad-acpi.rst> and
> <http://ibm-acpi.sf.net/> .
>
> This driver was formerly known as ibm-acpi.
> --
> 2.21.0
>
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [Linux-kernel-mentees] [PATCH] Documentation: platform: convert x86-laptop-drivers.txt to reST
From: Andy Shevchenko @ 2019-06-20 6:19 UTC (permalink / raw)
To: Shuah Khan
Cc: Greg KH, Jonathan Corbet, Cezary Jackiewicz, Darren Hart,
Andy Shevchenko, Puranjay Mohan, Linux Documentation List,
linux-kernel-mentees, Linux Kernel Mailing List, Platform Driver
In-Reply-To: <8aeb222a-ee44-4125-45fd-ce9a741e7ecc@linuxfoundation.org>
On Tue, Jun 18, 2019 at 6:06 PM Shuah Khan <skhan@linuxfoundation.org> wrote:
> On 6/18/19 7:39 AM, Greg KH wrote:
> > On Tue, Jun 18, 2019 at 07:17:17AM -0600, Jonathan Corbet wrote:
> >> On Tue, 18 Jun 2019 07:41:58 +0200
> >> Greg KH <gregkh@linuxfoundation.org> wrote:
> >>> On Tue, Jun 18, 2019 at 11:02:27AM +0530, Puranjay Mohan wrote:
> > I bet it should be deleted, but we should ask the platform driver
> > maintainers first before we do that :)
> Adding Platform driver maintainers Darren Hart and Andy Shevchenko, and
> Compal laptop maintainer Cezary Jackiewicz to the discussion.
>
> + platform-driver-x86@vger.kernel.org
>
> Hi Darren, Andy, and Cezary,
>
> Would it be okay to remove the x86-laptop-drivers.txt or should it be
> converted to .rst and kept around?
Shuan, thanks for heads up.
The list of laptops supported by drivers in PDx86 subsystem is quite
big and growing. The mentioned file contains less than per cent out of
it and I don't think there is sense to make it up to date with
thousands lines. Agree on removal.
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox