Re: [PATCH v2] docs: driver-model: Update the documentation for device class

[Jonathan Corbet]

Manivannan Sadhasivam  writes:

> The current documentation about the device class is out of date such
> that it refers to non-existent APIs and structures. This commit updates
> them to the current device class APIs and structures, removes wordings
> that no longer valid while trying to keep the original content intact.
>
> Signed-off-by: Manivannan Sadhasivam 
> ---
>
> Changes in v2:
>
> * Fixed CLASS_ATTR_RW as spotted by Greg
>
>  .../driver-api/driver-model/class.rst | 144 --
>  1 file changed, 66 insertions(+), 78 deletions(-)

Note that this file was removed in commit 1364c6787525 back in
February by Geert (added to CC).  If you want to update this document,
you'll first want to bring it back.

Thanks,

jon

Re: [PATCH v2 01/12] docs: path-lookup: update follow_managed() part

[Jonathan Corbet]

Fox Chen  writes:

> On Mon, Apr 19, 2021 at 11:25 AM Matthew Wilcox  wrote:
>>
>> On Mon, Apr 19, 2021 at 10:33:00AM +0800, Fox Chen wrote:
>> > On Mon, Apr 19, 2021 at 10:17 AM Matthew Wilcox  
>> > wrote:
>> > > You can drop ``..`` from around function named which are followed with
>> > > ().  d74b0d31ddde ("Docs: An initial automarkup extension for sphinx")
>> > > marks them up automatically.
>> > >
>> >
>> > Got it, thanks for letting me know. But I will still use them in this
>> > patch series to keep consistency with the remaining parts of the
>> > document.
>>
>> Well, you weren't.  For example:
>>
>> +As the last step of ``walk_component()``, ``step_into()`` will be called 
>> either
>> +directly from walk_component() or from handle_dots().  It calls
>> +``handle_mount()``, to check and handle mount points, in which a new
>>
>> Neither of the functions on the second line were using ``.
>
> Oh, That was a mistake,  They should've been wrapped with ``.
> Thanks for pointing it out. I will go through the whole patch set and
> fix this type of inconsistency in V3.

Please, if possible, go toward the bare function() form rather than
using literals...it's easier to read and the docs system will
automatically create cross references for you.

Thanks,

jon

Re: [RFC] scripts: kernel-doc: improve parsing for kernel-doc comments syntax

[Jonathan Corbet]

Aditya Srivastava  writes:

> Currently kernel-doc does not identify some cases of probable kernel
> doc comments, for e.g. pointer used as declaration type for identifier,
> space separated identifier, etc.
>
> Some example of these cases in files can be:
> i)" *  journal_t * jbd2_journal_init_dev() - creates and initialises a 
> journal structure"
> in fs/jbd2/journal.c
>
> ii) "*  dget, dget_dlock -  get a reference to a dentry" in
> include/linux/dcache.h
>
> iii) "  * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t"
> in include/linux/seqlock.h
>
> Also improve identification for non-kerneldoc comments. For e.g.,
>
> i) " *The following functions allow us to read data using a swap map"
> in kernel/power/swap.c does follow the kernel-doc like syntax, but the
> content inside does not adheres to the expected format.
>
> Improve parsing by adding support for these probable attempts to write
> kernel-doc comment.
>
> Suggested-by: Jonathan Corbet 
> Link: https://lore.kernel.org/lkml/87mtujktl2@meer.lwn.net
> Signed-off-by: Aditya Srivastava 
> ---
>  scripts/kernel-doc | 16 
>  1 file changed, 12 insertions(+), 4 deletions(-)

OK, I've applied this, but I have a couple of comments...

> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 888913528185..37665aa41e6b 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -2110,17 +2110,25 @@ sub process_name($$) {
>  } elsif (/$doc_decl/o) {
>   $identifier = $1;
>   my $is_kernel_comment = 0;
> - if (/^\s*\*\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
> + my $decl_start = qr{\s*\*};

I appreciate the attempt to make the regexes a bit more comprehensible,
but we can do better yet, methinks.  This $decl_start is very much like
$doc_com defined globally.

It would really help a lot if we could at least take the incredible mass
of regexes in this program and boil them down to a smaller, unique set
that is used throughout.  kernel-doc might still make brains explode,
but perhaps the blast radius would be a bit smaller.

> + my $fn_type = qr{\w+\s*\*\s*}; # i.e. pointer declaration type, foo * 
> bar() - desc

Some of the lines in this change go way beyond the 80-character
limit; please try not to do that.  I fixed up the offending comments
this time around.

Thanks,

jon

Re: [RFC 0/2] Add a new translation tool scripts/trslt.py

[Jonathan Corbet]

Wu XiangCheng  writes:

> Hi all,
>
> This set of patches aim to add a new translation tool - trslt.py, which
> can control the transltions version corresponding to source files.
>
> For a long time, kernel documentation translations lacks a way to control the
> version corresponding to the source files. If you translate a file and then
> someone updates the source file, there will be a problem. It's hard to know
> which version the existing translation corresponds to, and even harder to sync
> them. 
>
> The common way now is to check the date, but this is not exactly accurate,
> especially for documents that are often updated. And some translators write 
> corresponding commit ID in the commit log for reference, it is a good way, 
> but still a little troublesome.
>
> Thus, the purpose of ``trslt.py`` is to add a new annotating tag to the file
> to indicate corresponding version of the source file::
>
> .. translation_origin_commit: 
>
> The script will automatically copy file and generate tag when creating new
> translation, and give update suggestions based on those tags when updating
> translations.
>
> More details please read doc in [Patch 2/2].

So, like Federico, I'm unconvinced about putting this into the
translated text itself.  This is metadata, and I'd put it with the rest
of the metadata.  My own suggestion would be a tag like:

  Translates: 6161a4b18a66 ("docs: reporting-issues: make people CC the 
regressions list")

It would be an analogue to the Fixes tag in this regard; you could have
more than one of them if need be.

I'm not sure we really need a script in the kernel tree for this; it
seems like what you really want is some sort of git commit hook.  That
said, if you come up with something useful, we can certainly find a
place for it.

Thanks,

jon

Re: [PATCH v3] Documentation: dev-tools: Add Testing Overview

[Jonathan Corbet]

David Gow  writes:

> The kernel now has a number of testing and debugging tools, and we've
> seen a bit of confusion about what the differences between them are.
>
> Add a basic documentation outlining the testing tools, when to use each,
> and how they interact.
>
> This is a pretty quick overview rather than the idealised "kernel
> testing guide" that'd probably be optimal, but given the number of times
> questions like "When do you use KUnit and when do you use Kselftest?"
> are being asked, it seemed worth at least having something. Hopefully
> this can form the basis for more detailed documentation later.
>
> Signed-off-by: David Gow 
> Reviewed-by: Marco Elver 
> Reviewed-by: Daniel Latypov 
> ---
>
> Thanks again. Assuming no-one has any objections, I think this is good
> to go.

I've applied it after fixing the conflict with docs-next.

Thanks,

jon

Re: [PATCH v6] docs/zh_CN: add translations in zh_CN/dev-tools/gcov

[Jonathan Corbet]

Wu XiangCheng  writes:

> From: Bernard Zhao 
>
> Add new zh translations
> * zh_CN/dev-tools/gcov.rst
> * zh_CN/dev-tools/index.rst
> and link them to zh_CN/index.rst
>
> Signed-off-by: Bernard Zhao 
> Reviewed-by: Wu XiangCheng 
> Reviewed-by: Alex Shi 
> Reviewed-by: Fangrui Song 
> Signed-off-by: Wu XiangCheng 
> ---
> base: linux-next
> commit 269dd42f4776 ("docs/zh_CN: add riscv to zh_CN index")
>
> Changes since V5:
> * modified some words under Fangrui Song's advices
> * rewrite beginning paragragh since Bernard and Fangrui's advice
>
> Changes since V4:
> * modified some words under Alex Shi's advices
>
> Changes since V3:
> * update to newest linux-next
> * fix ``
> * fix tags
> * fix list indent
>
> Changes since V2:
> * fix some inaccurate translation
>
> Changes since V1:
> * add index.rst in dev-tools and link to to zh_CN/index.rst
> * fix some inaccurate translation
>
> Thanks!
>
>  .../translations/zh_CN/dev-tools/gcov.rst | 265 ++
>  .../translations/zh_CN/dev-tools/index.rst|  35 +++
>  Documentation/translations/zh_CN/index.rst|   1 +
>  3 files changed, 301 insertions(+)
>  create mode 100644 Documentation/translations/zh_CN/dev-tools/gcov.rst
>  create mode 100644 Documentation/translations/zh_CN/dev-tools/index.rst

Applied, thanks.

jon

Re: [PATCH] doc/virt/kvm: move KVM_X86_SET_MSR_FILTER in section 8

[Jonathan Corbet]

Emanuele Giuseppe Esposito  writes:

> KVM_X86_SET_MSR_FILTER is a capability, not an ioctl.
> Therefore move it from section 4.97 to the new 8.31 (other capabilities).
>
> To fill the gap, move KVM_X86_SET_MSR_FILTER (was 4.126) to
> 4.97, and shifted Xen-related ioctl (were 4.127 - 4.130) by
> one place (4.126 - 4.129).
>
> Also fixed minor typo in KVM_GET_MSR_INDEX_LIST ioctl description
> (section 4.3).
>
> Signed-off-by: Emanuele Giuseppe Esposito 
> ---
>  Documentation/virt/kvm/api.rst | 250 -
>  1 file changed, 125 insertions(+), 125 deletions(-)

Paolo, what's your thought on this one?  If it's OK should I pick it up?

Thanks,

jon

>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 1a2b5210cdbf..a230140d6a7f 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -201,7 +201,7 @@ Errors:
>  
>== 
>EFAULT the msr index list cannot be read from or written to
> -  E2BIG  the msr index list is to be to fit in the array specified by
> +  E2BIG  the msr index list is too big to fit in the array specified by
>   the user.
>== 
>  
> @@ -3686,31 +3686,105 @@ which is the maximum number of possibly pending 
> cpu-local interrupts.
>  
>  Queues an SMI on the thread's vcpu.
>  
> -4.97 KVM_CAP_PPC_MULTITCE
> --
> +4.97 KVM_X86_SET_MSR_FILTER
> +
>  
> -:Capability: KVM_CAP_PPC_MULTITCE
> -:Architectures: ppc
> -:Type: vm
> +:Capability: KVM_X86_SET_MSR_FILTER
> +:Architectures: x86
> +:Type: vm ioctl
> +:Parameters: struct kvm_msr_filter
> +:Returns: 0 on success, < 0 on error
>  
> -This capability means the kernel is capable of handling hypercalls
> -H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user
> -space. This significantly accelerates DMA operations for PPC KVM guests.
> -User space should expect that its handlers for these hypercalls
> -are not going to be called if user space previously registered LIOBN
> -in KVM (via KVM_CREATE_SPAPR_TCE or similar calls).
> +::
>  
> -In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest,
> -user space might have to advertise it for the guest. For example,
> -IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is
> -present in the "ibm,hypertas-functions" device-tree property.
> +  struct kvm_msr_filter_range {
> +  #define KVM_MSR_FILTER_READ  (1 << 0)
> +  #define KVM_MSR_FILTER_WRITE (1 << 1)
> + __u32 flags;
> + __u32 nmsrs; /* number of msrs in bitmap */
> + __u32 base;  /* MSR index the bitmap starts at */
> + __u8 *bitmap; /* a 1 bit allows the operations in flags, 0 denies */
> +  };
>  
> -The hypercalls mentioned above may or may not be processed successfully
> -in the kernel based fast path. If they can not be handled by the kernel,
> -they will get passed on to user space. So user space still has to have
> -an implementation for these despite the in kernel acceleration.
> +  #define KVM_MSR_FILTER_MAX_RANGES 16
> +  struct kvm_msr_filter {
> +  #define KVM_MSR_FILTER_DEFAULT_ALLOW (0 << 0)
> +  #define KVM_MSR_FILTER_DEFAULT_DENY  (1 << 0)
> + __u32 flags;
> + struct kvm_msr_filter_range ranges[KVM_MSR_FILTER_MAX_RANGES];
> +  };
>  
> -This capability is always enabled.
> +flags values for ``struct kvm_msr_filter_range``:
> +
> +``KVM_MSR_FILTER_READ``
> +
> +  Filter read accesses to MSRs using the given bitmap. A 0 in the bitmap
> +  indicates that a read should immediately fail, while a 1 indicates that
> +  a read for a particular MSR should be handled regardless of the default
> +  filter action.
> +
> +``KVM_MSR_FILTER_WRITE``
> +
> +  Filter write accesses to MSRs using the given bitmap. A 0 in the bitmap
> +  indicates that a write should immediately fail, while a 1 indicates that
> +  a write for a particular MSR should be handled regardless of the default
> +  filter action.
> +
> +``KVM_MSR_FILTER_READ | KVM_MSR_FILTER_WRITE``
> +
> +  Filter both read and write accesses to MSRs using the given bitmap. A 0
> +  in the bitmap indicates that both reads and writes should immediately fail,
> +  while a 1 indicates that reads and writes for a particular MSR are not
> +  filtered by this range.
> +
> +flags values for ``struct kvm_msr_filter``:
> +
> +``KVM_MSR_FILTER_DEFAULT_ALLOW``
> +
> +  If no filter range matches an MSR index that is getting accessed, KVM will
> +  fall back to allowing access to the MSR.
> +
> +``KVM_MSR_FILTER_DEFAULT_DENY``
> +
> +  If no filter range matches an MSR index that is getting accessed, KVM will
> +  fall back to rejecting access to the MSR. In this mode, all MSRs that 
> should
> +  be processed by KVM need to explicitly be marked as allowed in the bitmaps.
> +
> +This ioctl allows user space to define up to 16 

Re: [PATCH v2 00/12] docs: path-lookup: Update pathlookup docs

[Jonathan Corbet]

Fox Chen  writes:

> The Path lookup is a very complex subject in VFS. The path-lookup
> document provides a very detailed guidance to help people understand
> how path lookup works in the kernel. This document was originally
> written based on three lwn articles five years ago. As times goes by,
> some of the content is outdated. This patchset is intended to update
> the document to make it more relevant to current codebase.

Neil, have you had a chance to take a look at these?  I'm reluctant to
apply them without your ack...

Thanks,

jon

Re: [PATCH v2 0/2] Mention regression mailing list in reporting-bugs and MAINTAINERS

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Hi! A mailing list for regressions was finally created as
> regressi...@lists.linux.dev (we dropped the linux- prefix as the term is 
> already
> in the domain name). Hence, add it to MAINTAINERS, as that where people will
> look it up. I was a bit unsure how to actually do that, see the note in the
> first patch of the series for details.
>
> The second patch makes reporting-issues.rst mention the new list, so people CC
> it.
>
> @Jonathan: this hopefully is the last round of patches for 
> reporting-issues.rst
> for this cycle. Please let me known if you think the addition to the 
> MAINTAINERS
> file should better go through a different maintainer.

Naw...we all stick our fingers into MAINTAINERS at will...:)  I've
applied both, thanks.

jon

Re: [PATCH] doc:it_IT: align Italian documentation

[Jonathan Corbet]

Federico Vaga  writes:

> Translation for the following patches
>
> commit 7dfbea4c468c ("scripts: remove namespace.pl")
> commit 1a63f9cce7b7 ("docs: Remove make headers_check from checklist")
> commit 1e013ff7cb54 ("docs: Document cross-referencing using relative path")
> commit 0be1511f516e ("Documentation: doc-guide: fixes to sphinx.rst")
> commit 911358401284 ("kernel-doc: Fix example in Nested structs/unions")
> commit 875f82cb374b ("Documentation/submitting-patches: Extend commit message 
> layout description")
> commit 78f101a1b258 ("Documentation/submitting-patches: Add blurb about 
> backtraces in commit messages")
> commit f0ea149eee6b ("docs: submitting-patches: Emphasise the requirement to 
> Cc: stable when using Fixes: tag")
> commit 05a5f51ca566 ("Documentation: Replace lkml.org links with lore")
> commit 9bf19b78a203 ("Documentation/submitting-patches: Document the SoB 
> chain")
> commit b7592e5b82db ("docs: Remove the Microsoft rhetoric")
> commit 26606ce072d4 ("coding-style.rst: Avoid comma statements")
> commit dd58e649742a ("docs: Make syscalls' helpers naming consistent")
> commit 460cd17e9f7d ("net: switch to the kernel.org patchwork instance")
> commit 163ba35ff371 ("doc: use KCFLAGS instead of EXTRA_CFLAGS to pass flags 
> from command line")
> commit 0ef597c3ac49 ("docs: remove mention of ENABLE_MUST_CHECK")
> commit f8408264c77a ("drivers: Remove CONFIG_OPROFILE support")
> commit 0653c358d2dc ("scsi: Drop gdth driver")
> commit f8ae7bbec726 ("net: x25_asy: Delete the x25_asy driver")
> commit cf6d6fc27936 ("docs: process/howto.rst: make sections on bug reporting 
> match practice")
> commit da514157c4f0 ("docs: make reporting-bugs.rst obsolete")
> commit 4f8af077a02e ("docs: Fix reST markup when linking to sections")
> commit 3a4928cf5e3c ("Documentation: kernel-hacking: change 'current()' to 
> 'current'")
> commit c170f2eb9648 ("docs: Document cross-referencing between documentation 
> pages")
>
> Signed-off-by: Federico Vaga 

Applied, thanks.

jon

Re: [PATCH] Documentation/submitting-patches: Document RESEND tag on patches

[Jonathan Corbet]

Borislav Petkov  writes:

> Hi Jon,
>
> here's the next piece of documentation which should be generic enough.
>
> Thx.
>
> ---
> From: Borislav Petkov 
> Date: Tue, 13 Apr 2021 13:26:29 +0200
>
> Explain when a submitter should tag a patch or a patch series with the
> "RESEND" tag.
>
> This has been partially carved out from a tip subsystem handbook
> patchset by Thomas Gleixner:
>
>   https://lkml.kernel.org/r/20181107171010.421878...@linutronix.de
>
> and incorporates follow-on comments.
>
> Signed-off-by: Borislav Petkov 
> ---
>  Documentation/process/submitting-patches.rst | 10 ++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/process/submitting-patches.rst 
> b/Documentation/process/submitting-patches.rst
> index ab92d9ccd39a..9284735e0b34 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -346,6 +346,16 @@ that you have sent your patches to the right place.  
> Wait for a minimum of
>  one week before resubmitting or pinging reviewers - possibly longer during
>  busy times like merge windows.
>  
> +It's also ok to resend the patch or the patch series after a couple of
> +weeks with the word "RESEND" added to the subject line::
> +
> +   [PATCH Vx RESEND] sub/sys: Condensed patch summary
> +
> +Don't add "RESEND" when you are submitting a modified version of your
> +patch or patch series - "RESEND" only applies to resubmission of a
> +patch or patch series which have not been modified in any way from the
> +previous submission.
> +

Makes sense, applied.

For future installments, could you send them in their own thread as an
ordinary patch so I don't need to edit in the changelog after applying
them?

Thanks,

jon

Re: [PATCH] Documentation: dev-tools: Add Testing Overview

[Jonathan Corbet]

A nit but

> +The bulk of kernel tests are written using either the :doc:`kselftest
> +` or :doc:`KUnit ` frameworks. These both provide
> +infrastructure to help make running tests and groups of tests easier, as well
> +as providing helpers to aid in writing new tests.

If you just mention the relevant file, the docs build will make links
for you...so just "Documentation/dev-tools/kselftest.rst" rather than
the :doc: directive.  That helps to improve the readability of the
plain-text documentation as well.

> +`KUnit` tests therefore are best written against small, self-contained parts
> +of the kernel, which can be tested in isolation. This aligns well with the
> +concept of Unit testing.

If you want literal text, you need a double backtick: ``KUnit``.
Otherwise I'd just use normal quotes.

Thanks,

jon

Re: [PATCH] doc/zh_CN: Clean zh_CN translation maintainer

[Jonathan Corbet]

Wu XiangCheng  writes:

> Remove Harry Wei and  from
> MAINTAINERS Chinese Translation.
>
> According to git logs, Harry Wei (aka WeiWei Jia)
> * last submitted at 2012-05-07
> commit a9e73211fb0f ("Fix a mistake sentence in the file 
> 'Documentation/zh_CN/magic-number.txt'")
> * last Reviewed-by at 2016-02-16
> commit 45c73ea7a785 ("Documentation: Chinese translation of 
> arm64/silicon-errata.txt")
> * last Signed-off-by at 2019-03-13 (pick by Alex Shi)
> commit 95dcdb6e125f ("docs/zh_CN: rename magic-numbers as rst doc")
>
> According to mail list archives, Harry Wei
> * last replied at 2016-02-15
> 
> * last appeared at 2018-05-12
> 
>
> He/She did not maintain zh_CN translations for a long time.
>  is a maillist for Linux group of
> Xi'an University of Posts and Telecommunications, not special for zh_CN
> translation work.
>
> Anyway, many thanks him/her and Xiyou for their contributions to the early
> Chinese translation work!
>
> Signed-off-by: Wu XiangCheng 

I've applied this, thanks.

jon

Re: [PATCH] tools: Fix a typo in kernel-chktaint

[Jonathan Corbet]

Masanari Iida  writes:

> This patch fixes a spelling typo in kernel-chktaint
>
> Signed-off-by: Masanari Iida 
> ---
>  tools/debugging/kernel-chktaint | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/tools/debugging/kernel-chktaint b/tools/debugging/kernel-chktaint
> index 607b2b280945..719f18b1edf0 100755
> --- a/tools/debugging/kernel-chktaint
> +++ b/tools/debugging/kernel-chktaint
> @@ -25,7 +25,7 @@ if [ "$1"x != "x" ]; then
>   elif  [ $1 -ge 0 ] 2>/dev/null ; then
>   taint=$1
>   else
> - echo "Error: Parameter '$1' not a positive interger. Aborting." 
> >&2
> + echo "Error: Parameter '$1' not a positive integer. Aborting." 
> >&2
>   exit 1

Applied, thanks.

jon

Re: [RFC PATCH v1 2/2] docs: reporting-issues: make everyone CC the regressions list

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> +In case you performed a successful bisection, use the title of the change 
> that
> +introduced the regression as the second part of your subject. Make the report
> +also mention the commit id of the culprit. For tracking purposes, add a line
> +like the following that contains both pieces of information, but with the
> +commit id shortened to 12 characters::
> +
> +#regzb introduced: 94a632d91ad1 ("usc: xhbi-foo: check bar_params 
> earlier")
> +
> +In case of an unsuccessful bisection, make your report mention the latest 
> tested
> +version that's working fine (say 5.7) and the oldest where the issue occurs 
> (say
> +5.8-rc1). For tracking purposes add a line expressing it like this::
> +
> +#regzb introduced: v5.7..v5.8-rc1

I kind of share Greg's concern that people aren't going to want to do
this; it could even be seen as an impediment to reporting problems in
general.  If you *really* want random users to input this sort of
information, you may well end up creating some sort of web page to step
them through it.

Also, though, as I understand it the system that will interpret these
lines does not yet exist.  Experience tells me that, as this system
comes into existence, you will have a good chance of deciding that you
want the syntax to look different anyway.  So I would personally hold
off on telling people to include directives like this until you have
something that works with them.

But that's just me... if this is the way it's going to work then the
docs should of course reflect that.

Thanks,

jon

Re: [RFC PATCH 5/5] tracing: Add the osnoise tracer

[Jonathan Corbet]

Daniel Bristot de Oliveira  writes:

A quick nit:

>  Documentation/trace/osnoise_tracer.rst |  149 ++
>  include/linux/ftrace_irq.h |   16 +
>  include/trace/events/osnoise.h |  141 ++
>  kernel/trace/Kconfig   |   34 +
>  kernel/trace/Makefile  |1 +
>  kernel/trace/trace.h   |9 +-
>  kernel/trace/trace_entries.h   |   27 +
>  kernel/trace/trace_osnoise.c   | 1714 
>  kernel/trace/trace_output.c|   72 +-
>  9 files changed, 2159 insertions(+), 4 deletions(-)
>  create mode 100644 Documentation/trace/osnoise_tracer.rst
>  create mode 100644 include/trace/events/osnoise.h
>  create mode 100644 kernel/trace/trace_osnoise.c

When you create a new RST file, you need to add it to an index.rst (or
similar) file so that it gets incorporated into the docs build.

The document itself looks good on a quick read.  If you're making
another pass over it, you might consider reducing the ``markup noise`` a
bit; we try to keep that to a minimum in the kernel docs.  But otherwise
thanks for writing it!

jon

Re: [PATCH] docs: reporting-issues: Remove reference to oldnoconfig

[Jonathan Corbet]

Ismael Luceno  writes:

> Replace it with olddefconfig. oldnoconfig didn't do what the document
> suggests (it aliased to olddefconfig), and isn't available since 4.19.
>
> Ref: 04c459d20448 ("kconfig: remove oldnoconfig target")
> Ref: 312ee68752fa ("kconfig: announce removal of oldnoconfig if used")
> Signed-off-by: Ismael Luceno 
> ---
>  Documentation/admin-guide/reporting-issues.rst | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst 
> b/Documentation/admin-guide/reporting-issues.rst
> index 07879d01fe68..ffa0d4c6e450 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -1000,8 +1000,7 @@ In the whole process keep in mind: an issue only 
> qualifies as regression if the
>  older and the newer kernel got built with a similar configuration. The best 
> way
>  to archive this: copy the configuration file (``.config``) from the old 
> working
>  kernel freshly to each newer kernel version you try. Afterwards run ``make
> -oldnoconfig`` to adjust it for the needs of the new version without enabling
> -any new feature, as those are allowed to cause regressions.
> +olddefconfig`` to adjust it for the needs of the new version.

[CC += Thorsten]

Applied, thanks.

jon

Re: [PATCH] doc: admin-guide: remove explanation of "watchdog/%u"

[Jonathan Corbet]

Wang Qing  writes:

> "watchdog/%u" threads has be replaced by cpu_stop_work, 
> which will mislead the reader.
>
> Signed-off-by: Wang Qing 
> ---
>  .../admin-guide/kernel-per-CPU-kthreads.rst  | 20 
> 
>  1 file changed, 20 deletions(-)

Applied, thanks.

jon

Re: [PATCH 1/2] fs/namespace: corrent/improve kernel-doc notation

[Jonathan Corbet]

Randy Dunlap  writes:

> Fix kernel-doc warnings in fs/namespace.c:
>
> ./fs/namespace.c:1379: warning: Function parameter or member 'm' not 
> described in 'may_umount_tree'
> ./fs/namespace.c:1379: warning: Excess function parameter 'mnt' description 
> in 'may_umount_tree'
> ./fs/namespace.c:1950: warning: Function parameter or member 'path' not 
> described in 'clone_private_mount'
>
> Also convert path_is_mountpoint() comments to kernel-doc.
>
> Signed-off-by: Randy Dunlap 
> Cc: Al Viro 
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
> ---
> Jon, Al has OK-ed you to merge this patch (and the next one, please).
>
>  fs/namespace.c |   14 --
>  1 file changed, 8 insertions(+), 6 deletions(-)

An actual acked-by would have been nice, oh well.  Meanwhile, I've
applied them with fixes to the typos in both changelogs :)

Thanks,

jon

Re: [PATCH v2 0/7] Fix some issues at get_abi.pl script

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> This series replace this patch:
>   https://lore.kernel.org/linux-doc/20210324191722.08d35...@coco.lan/T/#t
>
> It turns that there were multiple bugs at the get_abi.pl code that
> create cross-references.
>
> Patches 1 to 6 fix those issues, and should apply cleanly on the top of
> the docs tree (although I tested against next-20210323).
>
> Patch 7 is optional, and independent from the other patches. It is meant
> to be applied against akpm's tree.  It makes the description (IMHO) 
> clearer, while producing cross references for the two mentioned symbols.

I've gone ahead and applied the set, with the exception of #7 which
doesn't apply here.

Thanks,

jon

Re: [PATCH 1/2] mailmap: update email address for Alex Shi

[Jonathan Corbet]

Alex Shi  writes:

> Add my kernel.org address for old email address.
>
> Signed-off-by: Alex Shi 

Both applied, thanks.

jon

Re: [PATCH] docs: powerpc: Fix misspellings and grammar errors

[Jonathan Corbet]

He Ying  writes:

> Reported-by: Hulk Robot 
> Signed-off-by: He Ying 
> ---
>  Documentation/powerpc/booting.rst| 2 +-
>  Documentation/powerpc/dawr-power9.rst| 2 +-
>  Documentation/powerpc/eeh-pci-error-recovery.rst | 2 +-
>  Documentation/powerpc/elfnote.rst| 2 +-
>  Documentation/powerpc/firmware-assisted-dump.rst | 2 +-
>  Documentation/powerpc/kaslr-booke32.rst  | 2 +-
>  Documentation/powerpc/mpc52xx.rst| 2 +-
>  Documentation/powerpc/papr_hcalls.rst| 4 ++--
>  Documentation/powerpc/transactional_memory.rst   | 4 ++--
>  9 files changed, 11 insertions(+), 11 deletions(-)

Applied, thanks.

jon

Re: [PATCH] Documentation: Add leading slash to some paths

[Jonathan Corbet]

Mark O'Donovan  writes:

> Change multiple sys/xyz to /sys/xyz
>
> Signed-off-by: Mark O'Donovan 
> ---
>  Documentation/admin-guide/mm/numaperf.rst |  2 +-
>  Documentation/fb/fbcon.rst|  4 ++--
>  Documentation/hid/intel-ish-hid.rst   |  2 +-
>  Documentation/leds/leds-lm3556.rst| 28 +++
>  4 files changed, 18 insertions(+), 18 deletions(-)

Makes sense ... applied, thanks.

jon

Re: [PATCH v1 1/4] docs: make reporting-issues.rst official and delete reporting-bugs.rst

[Jonathan Corbet]

Greg KH  writes:

> On Tue, Mar 30, 2021 at 04:13:04PM +0200, Thorsten Leemhuis wrote:
>> Removing Documentation/admin-guide/reporting-bugs.rst will break links
>> in some of the translations. I was unsure if simply changing them to
>> Documentation/admin-guide/reporting-issue.rst was wise, so I didn't
>> touch anything for now and CCed the maintainers for the Chinese and
>> Italian translation. I couldn't find one for the Japanse translation.
>
> Traditionally translations catch up much later on, you shouldn't have to
> worry about them the authors will clean them up and submit patches for
> them when they get the chance.

Agreed.  None of the broken references actually generate warnings
(though perhaps some should) so we can let the translators catch up on
their own time.

I've applied the set and stuck in this tweak:

> FWIW, this needs a
> 
>  s!stable/>_`!stable/>`_!
> 
> Sorry, this slipped through. :-/ Ciao, Thorsten

while I was at it.

Thanks,

jon

Re: [PATCH] scripts: kernel-doc: add warning for comment not following kernel-doc syntax

[Jonathan Corbet]

Aditya Srivastava  writes:

> On 29/3/21 7:26 pm, Jonathan Corbet wrote:
>> Aditya Srivastava  writes:
>> 
>>> Currently, kernel-doc start parsing the comment as a kernel-doc comment if
>>> it starts with '/**', but does not take into account if the content inside
>>> the comment too, adheres with the expected format.
>>> This results in unexpected and unclear warnings for the user.
>>>
>>> E.g., running scripts/kernel-doc -none mm/memcontrol.c emits:
>>> "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to 
>>> current(). Prototype was for get_mem_cgroup_from_current() instead"
>>>
>>> Here kernel-doc parses the corresponding comment as a kernel-doc comment
>>> and expects prototype for it in the next lines, and as a result causing
>>> this warning.
>>>
>>> Provide a clearer warning message to the users regarding the same, if the
>>> content inside the comment does not follow the kernel-doc expected format.
>>>
>>> Signed-off-by: Aditya Srivastava 
>>> ---
>>>  scripts/kernel-doc | 17 +
>>>  1 file changed, 13 insertions(+), 4 deletions(-)
>> 
>> This is definitely a capability we want, but I really don't think that
>> we can turn it on by default - for now.  Experience shows that if you
>> create a blizzard of warnings, nobody sees any of them.  How many
>> warnings does this add to a full docs build?
>> 
>
> Hi Jonathan, here's the diff I have created for the warnings before
> and after the changes:
> https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/kernel_doc_comment_syntax.txt
>
> Around ~1320 new warnings of this type are added to the kernel tree,
> and around ~1580 warnings are removed.

So I finally got around to looking at this again...  How did you
generate that file?

I tried applying the patch and doing a normal full htmldocs build and
got all of four warnings:

  ./include/linux/seqlock.h:829: warning: This comment starts with '/**', but 
isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
   * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t
  ./fs/jbd2/journal.c:1391: warning: This comment starts with '/**', but isn't 
a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
   *  journal_t * jbd2_journal_init_dev() - creates and initialises a journal 
structure
  ./fs/jbd2/journal.c:1422: warning: This comment starts with '/**', but isn't 
a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
   *  journal_t * jbd2_journal_init_inode () - creates a journal which maps to 
a inode.
  ./include/linux/dcache.h:309: warning: This comment starts with '/**', but 
isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
   *  dget, dget_dlock -  get a reference to a dentry

Two observations:

 - This is not an awful lot of warnings - not the blizzard I had
   feared.  At this level, I think we can just merge the patch and
   then, hopefully, fix those cases.

 - All of the warned-about places are *attempts* to write real kerneldoc
   comments, they just got the syntax wrong in one way or another.  It's
   probably not worth the effort to try to detect this case - the
   warning is enough to draw attention to the comment in question.

Thanks,

jon

Re: [PATCH] docs: Remove make headers_check from checklist in translations

[Jonathan Corbet]

Masahiro Yamada  writes:

> Hi Jon,
>
>
> On Tue, Mar 2, 2021 at 11:19 PM Masahiro Yamada  wrote:
>>
>> Commit 1a63f9cce7b7 ("docs: Remove make headers_check from checklist")
>> fixed only the English version.
>>
>> Let's fix the translated variants too.
>>
>> Signed-off-by: Masahiro Yamada 
>
> ping?

Hmm...somehow that went through the cracks..perhaps I thought it looked
like one of the patches you tend to apply yourself.

Anyway, applied now, apologies for the delay.

Thanks,

jon

Re: [1/5] reporting-issues: header and TLDR

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> FWIW, on another channel someone mentioned the process in the TLDR is
> quite complicated when it comes to regressions in stable and longterm
> kernels. I looked at the text and it seemed like a valid complaint, esp.
> as those regressions are something we really care about.
>
> To solve this properly I sadly had to shake up the text in this section
> completely and rewrite parts of it. Find the result below. I'm quite
> happy with it, as it afaics is more straight forward and easier to
> understand. And it matches the step-by-step guide better. And the best
> thing: it's a bit shorter than the old TLDR.

I think this is much improved - concise is good! :)  I really just have
one little comment...

> I'll wait a day or two and then will send it through the regular review
> together with a few small other fixes that piled up for the text, just
> wanted to add it here for completeness.
>
> ---
> The short guide (aka TL;DR)
> ===
>
> Are you facing a regression with vanilla kernels from the same stable or
> longterm series? One still supported? Then search the `LKML
> `_ and the `Linux stable mailing list
> _` archives for matching reports to
> join. If you don't find any, install `the latest release from that
> series `_. If it still shows the issue, report it
> to the stable mailing list and the stable maintainers.

If we really want this to be a short guide that gets people to the
answer quickly, we might as well put the addresses to report to right
here rather than making people search for them.

Thanks,

jon

Re: kerneldoc and rust (was [PATCH] kernel-doc: better handle '::' sequences)

[Jonathan Corbet]

Matthew Wilcox  writes:

If we're going to talk about incorporating Rust into the doc system, we
should probably include some Rust folks - thus, I'm adding Miguel.

> On Thu, Mar 25, 2021 at 04:30:32PM -0600, Jonathan Corbet wrote:
>> Matthew Wilcox  writes:
>> 
>> We did come to the mutual agreement that teaching kernel-doc to parse
>> Rust code as well was not an ideal solution.  Probably there will be
>> some sort of tool to translate between rustdoc and our sphinx setup.
>> Beyond that, we'll see how it goes.
>
> In the spirit of groping around for the best solution, I did some looking
> around at various options, including using rustdoc for .c files (that
> uses Markdown, which appears to be strictly worse than rST for our
> purposes).
>
> So here's my "modest proposal":
>
>  - Similar to our ".. kernel-doc::" invocation in .rst files, handle
>".. rustdoc::" (insert weeks of hacking here)
>  - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
>does, but interprets a different style of comment and actually does
>most of the repetitive boring bits for you.
>
> For example, xa_load:
>
> /**
>  * xa_load() - Load an entry from an XArray.
>  * @xa: XArray.
>  * @index: index into array.
>  *
>  * Context: Any context.  Takes and releases the RCU lock.
>  * Return: The entry at @index in @xa.
>  */
> void *xa_load(struct xarray *xa, unsigned long index)
>
> //rST
> // Load an entry from an XArray.
> //
> // :Context: Any context.  Takes and releases the RCU lock.
> // :Return: The entry in `xa` at `index`.
> void *xa_load(struct xarray *xa, unsigned long index)
>
> (more complex example below [2])
>
> Things I considered:
>
>  - Explicitly document that this is rST markup instead of Markdown or
>whatever.
>  - Don't repeat the name of the function.  The tool can figure it out.

That worries me a wee bit just because a common source of problems is
kerneldoc comments becoming separated from the functions they describe
over time.  We finally have tooling to notice that; this seems like a
step in the other direction.

>  - Don't force documenting each parameter.  Often they are obvious
>and there's really nothing interesting to say about the parameter.
>Witness the number of '@foo: The foo' (of type struct foo) that we
>have scattered throughout the tree.  It's not that the documenter is
>lazy, it's that there's genuinely nothing to say here.

...another failure mode is developers adding parameters and not
documenting them; this would mask that problem too.

>  - Use `interpreted text` to refer to parameters instead of *emphasis* or
>**strong emphasis**.  The tool can turn that into whatever markup
>is appropriate.
>  - Use field lists for Context and Return instead of sections.  The markup
>is simpler to use, and I think the rendered output is better.
>
> [1] by which i mean "in a completely different way from, but similar in
> concept"
>
> [2] More complex example:
>
> /**
>  * xa_store() - Store this entry in the XArray.
>  * @xa: XArray.
>  * @index: Index into array.
>  * @entry: New entry.
>  * @gfp: Memory allocation flags.
>  *
>  * After this function returns, loads from this index will return @entry.
>  * Storing into an existing multi-index entry updates the entry of every 
> index.
>  * The marks associated with @index are unaffected unless @entry is %NULL.
>  *
>  * Context: Any context.  Takes and releases the xa_lock.
>  * May sleep if the @gfp flags permit.
>  * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
>  * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
>  * failed.
>  */
> void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
>
> //rST
> // Store an entry in the XArray.
> //
> // After this function returns, loads from `index` will return `entry`.
> // Storing into an existing multi-index entry updates the entry of every 
> index.
> // The marks associated with `index` are unaffected unless `entry` is 
> ``NULL``.
> //
> // :Context: Any context.  Takes and releases the xa_lock.
> //May sleep if the `gfp` flags permit.
> // :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
> //cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
> //failed.
> void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)

Thanks,

jon

Re: [PATCH] scripts: kernel-doc: add warning for comment not following kernel-doc syntax

[Jonathan Corbet]

Aditya Srivastava  writes:

> Currently, kernel-doc start parsing the comment as a kernel-doc comment if
> it starts with '/**', but does not take into account if the content inside
> the comment too, adheres with the expected format.
> This results in unexpected and unclear warnings for the user.
>
> E.g., running scripts/kernel-doc -none mm/memcontrol.c emits:
> "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to 
> current(). Prototype was for get_mem_cgroup_from_current() instead"
>
> Here kernel-doc parses the corresponding comment as a kernel-doc comment
> and expects prototype for it in the next lines, and as a result causing
> this warning.
>
> Provide a clearer warning message to the users regarding the same, if the
> content inside the comment does not follow the kernel-doc expected format.
>
> Signed-off-by: Aditya Srivastava 
> ---
>  scripts/kernel-doc | 17 +
>  1 file changed, 13 insertions(+), 4 deletions(-)

This is definitely a capability we want, but I really don't think that
we can turn it on by default - for now.  Experience shows that if you
create a blizzard of warnings, nobody sees any of them.  How many
warnings does this add to a full docs build?

For now I think we need a flag to turn this warning on, which perhaps
can be set for a W=1 build.

Thanks,

jon

Re: linux-next: build warnings after merge of the jc_docs tree

[Jonathan Corbet]

Stephen Rothwell  writes:

> Hi all,
>
> After merging the jc_docs tree, today's linux-next build (htmldocs)
> produced these warnings:
>
> include/linux/pstore_zone.h:55: warning: Function parameter or member 'write' 
> not described in 'pstore_zone_info'
> include/linux/pstore_blk.h:43: warning: Function parameter or member 'write' 
> not described in 'pstore_device_info'
> include/media/v4l2-mediabus.h:127: warning: Function parameter or member 
> 'type' not described in 'v4l2_mbus_config'
>
> and many more similar. These appear to be false positives :-(
>
> Introduced by commit
>
>   8d295fbad687 ("kernel-doc: better handle '::' sequences")
>
> I have reverted that commit for today.

Argh, that was bad, sorry, I should have caught that.

Just added the following to fix it.

Thanks,

jon

>From 212209cff89fe497bc47abcd017aa95e4e8a5196 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 26 Mar 2021 13:16:35 -0600
Subject: [PATCH] docs: kernel-doc: properly recognize parameter lines with
 colons

The previous attempt to properly handle literal blocks broke parsing of
parameter lines containing colons; fix it by tweaking the regex to
specifically exclude the "::" pattern while accepting lines containing
colons in general.  Add a little documentation to the regex while in the
neighborhood.

Reported-by: Stephen Rothwell 
Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences")
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 8 +++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0ecd71477a16..d6d2b6e0b4eb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -391,8 +391,14 @@ my $doc_com = '\s*\*\s*';
 my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
+# Specifically:
+#   Match @word:
+#@...:
+# @{section-name}:
+# while trying to not match literal block starts like "example::"
+#
 my $doc_sect = $doc_com .
-
'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$';
+
'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
-- 
2.30.2

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jonathan Corbet]

Matthew Wilcox  writes:

> The rust code is alredy coming though ...
>
> rust/kernel/buffer.rs:/// A pre-allocated buffer that implements 
> [`core::fmt::Write`].
>
> so now we have three formats.  Markdown and RST are _very_ similar, but
> not identical [1].  Oh, and even better we now have three distinct tools --
> kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
> about integrating the various docs?

I have talked with them a bit, yes, but without any clear conclusions at
this point.  The Rust world has its own way of doing things with regard
to documentation, and I don't want to tell them they can't use it in the
kernel context.  So I think there's going to be a certain amount of
groping around for the best solution.

We did come to the mutual agreement that teaching kernel-doc to parse
Rust code as well was not an ideal solution.  Probably there will be
some sort of tool to translate between rustdoc and our sphinx setup.
Beyond that, we'll see how it goes.

jon

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jonathan Corbet]

Matthew Wilcox  writes:

> On Thu, Mar 25, 2021 at 12:51:25PM -0600, Jonathan Corbet wrote:
>> Mauro Carvalho Chehab  writes:
>> 
>> > Right now, if one of the following headers end with a '::', the
>> > kernel-doc script will do the wrong thing:
>> >
>> >description|context|returns?|notes?|examples?
>> >
>> > The real issue is with examples, as people could try to write
>> > something like:
>> >
>> >example::
>> >
>> >/* Some C code */
>> >
>> > and this won't be properly evaluated. So, improve the regex
>> > to not catch '\w+::' regex for the above identifiers.
>> >
>> > Signed-off-by: Mauro Carvalho Chehab 
>> > ---
>> >  scripts/kernel-doc | 2 +-
>> >  1 file changed, 1 insertion(+), 1 deletion(-)
>> 
>> Ahwouldn't it be nice if kerneldoc comments had just been RST from
>> the beginning?  I don't think we're fixing that at this point, though,
>> so this makes sense; applied.
>
> Well ...
>
> If somebody wants to write a new tool (*) that extracts documentation
> written in a different format, I think that could be done.  Because the
> hard part of writing documentation is getting the person who knows the
> code to get everything that's in their brain into words, not really
> the formatting.
>
> If somebody did want to write such a tool, I think we'd also want a
> tool that turns the existing kernel-doc into the new format, because
> maintaining two function-doc formats would be awful.

Yeah, the thing is that, as long as we're documenting code with
something other than RST, we *do* have two formats, and they interact
with each other in surprising and unwelcome ways.

I don't really see a fix, though.  Even if we come up with the Perfect
New Format™, I don't want to be the one trying to push through the
patches changing tens of thousands of kerneldoc comments over...

jon

Re: [PATCH v3 0/5] docs: reporting-issues: streamline process and solve a FIXME

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> BTW, I wondered it it would make sense to add a entry to the MAINTAINERS
> file for the text so I can keep and eye on things and help with fine
> tuning. Let me known if you think that idea is overblown, otherwise I'll
> likely add one with the patch that I'll send sooner or later to remove
> the WIP box near the top.

A MAINTAINERS entry makes sense for a document like that; I think it's a
fine idea to add yourself.

Thanks,

jon

Re: [PATCH v2 0/7] Fix some issues at get_abi.pl script

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> This series replace this patch:
>   https://lore.kernel.org/linux-doc/20210324191722.08d35...@coco.lan/T/#t
>
> It turns that there were multiple bugs at the get_abi.pl code that
> create cross-references.
>
> Patches 1 to 6 fix those issues, and should apply cleanly on the top of
> the docs tree (although I tested against next-20210323).
>
> Patch 7 is optional, and independent from the other patches. It is meant
> to be applied against akpm's tree.  It makes the description (IMHO) 
> clearer, while producing cross references for the two mentioned symbols.

So perhaps this is the best solution to the problem, but I must confess
to not being entirely happy with it.  get_abi.pl is becoming another
unreadable perlpile like kerneldoc, and this makes it worse.  Doing RST
parsing there seems particularly unwelcome.

Should the cross-reference generation, it now occurs to me, be done in
the automarkup module instead?  Then there's no need to interpret RST,
and we'd get cross-references throughout the kernel docs rather than in
just the ABI stuff.  Am I completely out to lunch here?

Thanks,

jon

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> Right now, if one of the following headers end with a '::', the
> kernel-doc script will do the wrong thing:
>
>   description|context|returns?|notes?|examples?
>
> The real issue is with examples, as people could try to write
> something like:
>
>   example::
>
>   /* Some C code */
>
> and this won't be properly evaluated. So, improve the regex
> to not catch '\w+::' regex for the above identifiers.
>
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  scripts/kernel-doc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Ahwouldn't it be nice if kerneldoc comments had just been RST from
the beginning?  I don't think we're fixing that at this point, though,
so this makes sense; applied.

Thanks,

jon

Re: [PATCH v3 0/5] docs: reporting-issues: streamline process and solve a FIXME

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> That's why I'd like to speed things up a little. But for that it would
> be good to have something from you: a kind of "I like the direction
> where this patch set is heading and I'm optimistic that we get it merged
> for 5.13-rc1" message from you. With something like that I could move
> ahead as outlined above already. Do you maybe have a minute for that?

Honestly, I don't see any reason to delay this work any further, so I've
just applied the set.

Sorry for the slowness, it has been a rather harsh week.

Thanks,

jon

Re: [PATCH] docs: sphinx: Trivial fix of a typo in the file rstFlatTable.py

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/buidler/builder/
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Documentation/sphinx/rstFlatTable.py | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/sphinx/rstFlatTable.py 
> b/Documentation/sphinx/rstFlatTable.py
> index a3eea0bbe6ba..1d2b9be6b6c5 100755
> --- a/Documentation/sphinx/rstFlatTable.py
> +++ b/Documentation/sphinx/rstFlatTable.py
> @@ -161,7 +161,7 @@ class ListTableBuilder(object):
>  for colwidth in colwidths:
>  colspec = nodes.colspec(colwidth=colwidth)
>  # FIXME: It seems, that the stub method only works well in the
> -# absence of rowspan (observed by the html buidler, the 
> docutils-xml
> +# absence of rowspan (observed by the html builder, the 
> docutils-xml
>  # build seems OK).  This is not extraordinary, because there 
> exists
>  # no table directive (except *this* flat-table) which allows to
>  # define coexistent of rowspan and stubs (there was no use-case
> --

This was fixed in your previous patch from March 2.  Bhaskar, please
slow down a bit and try not to create needless work for the recipients
of your patches, OK?

Thanks,

jon

Re: [PATCH] docs: filesystems: Fix a mundane typo

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/provisoned/provisioned/
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Documentation/filesystems/vfat.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/filesystems/vfat.rst 
> b/Documentation/filesystems/vfat.rst
> index e85d74e91295..760a4d83fdf9 100644
> --- a/Documentation/filesystems/vfat.rst
> +++ b/Documentation/filesystems/vfat.rst
> @@ -189,7 +189,7 @@ VFAT MOUNT OPTIONS
>  **discard**
>   If set, issues discard/TRIM commands to the block
>   device when blocks are freed. This is useful for SSD devices
> - and sparse/thinly-provisoned LUNs.
> + and sparse/thinly-provisioned LUNs.

Applied, thanks.

jon

Re: [PATCH] docs: powerpc: Fix a typo

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/struture/structure/
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Documentation/powerpc/firmware-assisted-dump.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/powerpc/firmware-assisted-dump.rst 
> b/Documentation/powerpc/firmware-assisted-dump.rst
> index 20ea8cdee0aa..6c0ae070ba67 100644
> --- a/Documentation/powerpc/firmware-assisted-dump.rst
> +++ b/Documentation/powerpc/firmware-assisted-dump.rst
> @@ -171,7 +171,7 @@ that were present in CMA region::
> (meta area)|
>|
>|
> -  Metadata: This area holds a metadata struture whose
> +  Metadata: This area holds a metadata structure whose
>address is registered with f/w and retrieved in the
>second kernel after crash, on platforms that support

Applied, thanks.

jon

Re: [PATCH -next v4] docs: document all error message types in checkpatch

[Jonathan Corbet]

Dwaipayan Ray  writes:

> All the error message types now have a verbose description.
>
> Also there are two new groups of message types:
>
> - Macros, Attributes and Symbols
> - Functions and Variables
>
> Rearrange the message types to fit these new groups as needed.
>
> Reviewed-by: Lukas Bulwahn 
> Signed-off-by: Dwaipayan Ray 
> ---
>
> Changes in v4:
> - Use lore.kernel.org links
> - modify explanation for DEFINE_ARCH_HAS
>
> Changes in v3:
> - Add more explanation for LOCKDEP
> - Minor grammar fixes
>
> Changes in v2:
> - Replace 4.10 kernel doc links by latest
>
>  Documentation/dev-tools/checkpatch.rst | 318 ++---
>  1 file changed, 280 insertions(+), 38 deletions(-)

Applied, thanks.

jon

Re: [PATCH] docs/kokr: make sections on bug reporting match practice

[Jonathan Corbet]

SeongJae Park  writes:

> From: SeongJae Park 
>
> Translate this commit to Korean:
>
> cf6d6fc27936 ("docs: process/howto.rst: make sections on bug reporting 
> match practice")
>
> Signed-off-by: SeongJae Park 
> ---
>  Documentation/translations/ko_KR/howto.rst | 18 +-
>  1 file changed, 9 insertions(+), 9 deletions(-)

Applied, thanks, sorry for the delay.

jon

Re: [PATCH] Documentation: gpio: chip should be plural

[Jonathan Corbet]

Bryan Brattlof  writes:

> Signed-off-by: Bryan Brattlof 
> ---
>  Documentation/driver-api/gpio/intro.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/gpio/intro.rst 
> b/Documentation/driver-api/gpio/intro.rst
> index 94dd7185e76e..2e924fb5b3d5 100644
> --- a/Documentation/driver-api/gpio/intro.rst
> +++ b/Documentation/driver-api/gpio/intro.rst
> @@ -27,7 +27,7 @@ What is a GPIO?
>  ===
>  
>  A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
> -digital signal. They are provided from many kinds of chip, and are familiar
> +digital signal. They are provided from many kinds of chips, and are familiar

Applied, thanks.

jon

Re: [PATCH] docs: rbtree.rst: Fix a typo

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/maintanence/maintenance/
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Documentation/core-api/rbtree.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, thanks.

jon

Re: [PATCH] docs: livepatch: Fix a typo

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> On 10:05 Thu 25 Mar 2021, Miroslav Benes wrote:

>>you sent the same fix a couple of weeks ago and Jon applied it.
>>
> Ah..difficult to rememberthanks for reminding ..it seems I need to keep
> track ...which I don't do at this moment ...so the patch get duplicated ..
>
> So.do you have any better policy to keep track???

1) Look at the emails that maintainers like me send you when patches
are applied.

2) Work against linux-next.

jon

Re: [PATCH] script: get_abi.pl: escape "<" and ">" characters

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> After merging the akpm-current tree, today's linux-next build (htmldocs)
> produced this warning:
>
>   Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline 
> interpreted text or phrase reference start-string without end-string.
>
> Introduced by commit 439d477342a3 ("mm: cma: support sysfs")
>
> As pointed by Jonathan, the problem is this text in
> sysfs-kernel-mm-cma:
>
>   Each CMA heap subdirectory (that is, each
>   /sys/kernel/mm/cma/ directory) contains the
>   following items:
>
> Is not parsed well, becase the major/minor signs need to be
> escaped, when converted into cross-references.

Sorry, I kind of dropped the ball on this, and everything else really; a
bit of a challenging time here.

This makes the warning go away, but I have to wonder if it's the right
fix - wouldn't it be better to avoid trying to create a cross-reference
entirely in cases where it clearly won't work?  Or am I missing
something here?

Thanks,

jon

Re: [PATCH] docs: submitting-patches Fix a typo

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> On 03:44 Mon 22 Mar 2021, Matthew Wilcox wrote:
>>On Mon, Mar 22, 2021 at 09:00:00AM +0530, Bhaskar Chowdhury wrote:
>>>
>>> s/mesages/messages/
>>
>>did you test the build afterwards?  you forgot to do something.
>>
> What are you talking about??? It is going over my head...why the build
> reqired?? A spello needs a rebuild Wondering

Willy is pointing out that you have introduced an error into the docs
build.  A few minutes of your time to learn the basics of RST are likely
to prove more helpful then typing lots of question marks...

Thanks,

jon

Re: [PATCH v6 7/8] Documentation: Add documentation for the Brute LSM

[Jonathan Corbet]

John Wood  writes:

> Add some info detailing what is the Brute LSM, its motivation, weak
> points of existing implementations, proposed solutions, enabling,
> disabling and self-tests.
>
> Signed-off-by: John Wood 
> ---
>  Documentation/admin-guide/LSM/Brute.rst | 278 
>  Documentation/admin-guide/LSM/index.rst |   1 +
>  security/brute/Kconfig  |   3 +-
>  3 files changed, 281 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/admin-guide/LSM/Brute.rst

Thanks for including documentation with the patch!

As you get closer to merging this, though, you'll want to take a minute
(OK, a few minutes) to build the docs and look at the result; there are
a number of places where you're not going to get what you expect.  Just
as an example:

[...]

> +Based on the above scenario it would be nice to have this detected and
> +mitigated, and this is the goal of this implementation. Specifically the
> +following attacks are expected to be detected:
> +
> +1.- Launching (fork()/exec()) a setuid/setgid process repeatedly until a
> +desirable memory layout is got (e.g. Stack Clash).
> +2.- Connecting to an exec()ing network daemon (e.g. xinetd) repeatedly until 
> a
> +desirable memory layout is got (e.g. what CTFs do for simple network
> +service).
> +3.- Launching processes without exec() (e.g. Android Zygote) and exposing 
> state
> +to attack a sibling.
> +4.- Connecting to a fork()ing network daemon (e.g. apache) repeatedly until 
> the
> +previously shared memory layout of all the other children is exposed 
> (e.g.
> +kind of related to HeartBleed).

Sphinx will try to recognize your enumerated list, but that may be a bit
more punctuation than it is prepared to deal with; I'd take the hyphens
out, if nothing else.

[...]

> +These statistics are hold by the brute_stats struct.
> +
> +struct brute_cred {
> + kuid_t uid;
> + kgid_t gid;
> + kuid_t suid;
> + kgid_t sgid;
> + kuid_t euid;
> + kgid_t egid;
> + kuid_t fsuid;
> + kgid_t fsgid;
> +};

That will certainly not render the way you want.  What you need here is
a literal block:

These statistics are hold by the brute_stats struct::

struct brute_cred {
kuid_t uid;
kgid_t gid;
kuid_t suid;
kgid_t sgid;
kuid_t euid;
kgid_t egid;
kuid_t fsuid;
kgid_t fsgid;
};

The "::" causes all of the indented text following to be formatted
literally. 

Thanks,

jon

Re: [RFC] scripts: kernel-doc: avoid warnings due to initial commented lines in file

[Jonathan Corbet]

Lukas Bulwahn  writes:

> Yeah, and as this line-counting is really just a poor man's
> heuristics, we might just be better to really turn this heuristics
> into a dedicated cleanup warning script, then we can check for more
> indicators, such as "does it contain the word Copyright" somewhere in
> the kernel-doc comment, which tells us even more that this is not a
> kernel-doc as we would expect it.

I really don't think we need that kind of heuristic.  The format of
kerneldoc comments is fairly rigid; it shouldn't be too hard to pick out
the /** comments that don't fit that format, right?  Am I missing
something there?

Thanks,

jon

Re: [RFC] scripts: kernel-doc: avoid warnings due to initial commented lines in file

[Jonathan Corbet]

Lukas Bulwahn  writes:

> I wonder if we could extend kernel-doc (not your preferred option as
> it seems) for a new dedicated warning message or maintain a separate
> kernel-doc sanity checking script to emit a dedicated warning based on
> some heuristics that suggests when a "header comment" is probably
> unintentionally declared as a "kernel-doc comment" when it really
> should not be.
>
> Jonathan, would you then prefer to have a separate kernel-doc sanity
> checking script that then allows us to maintain checking for patterns
> we already cleaned up?

Having a warning in kernel-doc for "This comment starts with /** but
isn't a kerneldoc comment" could be useful, I guess.  That is the real
problem, not the fact that it appears at the top of the file.  I'm all
for tools that help us to clean things up, but let's not add
line-counting hacks to try to paper it over.

Thanks,

jon

Re: linux-next: build warning after merge of the akpm-current tree

[Jonathan Corbet]

Stephen Rothwell  writes:

[Adding Mauro]

> On Tue, 16 Mar 2021 11:18:11 -0700 Minchan Kim  wrote:
>>
>> On Mon, Mar 15, 2021 at 04:35:22PM +1100, Stephen Rothwell wrote:
>> > Hi all,
>> > 
>> > After merging the akpm-current tree, today's linux-next build (htmldocs)
>> > produced this warning:
>> > 
>> > Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline 
>> > interpreted text or phrase reference start-string without end-string.
>> > 
>> > Introduced by commit
>> > 
>> >   439d477342a3 ("mm: cma: support sysfs")
>> >   
>> 
>> Hmm, I don't get it what happened here. Was it false-positive?
>
> I get the above from a "make htmldocs" run ... I don't know what causes
> it, sorry.  [cc'ing Jon]

OK, this took a while to figure out.  The problem is this text in
sysfs-kernel-mm-cma:

>   Each CMA heap subdirectory (that is, each
>   /sys/kernel/mm/cma/ directory) contains the
>   following items:

When scripts/get_abi.pl sees the /sys/kernel/mm/... string it wants to
turn it into a link to the matching ABI entry; at that point, the
 collides with the Sphinx directive and you get
that totally useless warning.

I think this is a bug in get_abi.pl.  Honestly I wonder if all these
cross-links are needed at all; if they truly are, then we shouldn't be
making bogus ones.  Mauro, how hard would it be to make this do the
right thing?

Thanks,

jon

Re: [PATCH] Documentation: sysrq: update description about sysrq crash

[Jonathan Corbet]

Gao Xiang  writes:

> After commit 8341f2f222d7 ("sysrq: Use panic() to force a crash"),
> a crash was not generated by dereferencing a NULL pointer anymore.
>
> Let's update documentation as well to make it less misleading.
>
> Cc: Matthias Kaehlcke 
> Cc: Greg Kroah-Hartman 
> Cc: Jonathan Corbet 
> Cc: Zefan Li 
> Signed-off-by: Gao Xiang 
> ---
>  Documentation/admin-guide/sysrq.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/admin-guide/sysrq.rst 
> b/Documentation/admin-guide/sysrq.rst
> index 67dfa4c29093..60ce5f5ebab6 100644
> --- a/Documentation/admin-guide/sysrq.rst
> +++ b/Documentation/admin-guide/sysrq.rst
> @@ -90,8 +90,8 @@ Command Function
>  ``b``Will immediately reboot the system without syncing or 
> unmounting
>  your disks.
>  
> -``c``Will perform a system crash by a NULL pointer dereference.
> -A crashdump will be taken if configured.
> +``c``Will perform a system crash and a crashdump will be taken
> +if configured.

Makes sense. Applied, thanks.

jon

Re: [PATCH v1, RFC] docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Tell users that reporting bugs with vendor kernels which are only
> slightly patched can be okay in some situations, but point out there's a
> risk in doing so.
>
> Adjust some related sections to make them compatible and a bit clearer.
> At the same time make them less daunting: we want users to report bugs,
> even if they can't test vanilla mainline kernel.
>
> Signed-off-by: Thorsten Leemhuis 
> CC: Randy Dunlap 
>
> ---
> With this I try to get rid of the last remaining parts that have a
> 'this needs discussion' box that's in the text. I hope I've found a
> middle ground that everybody can live with.

For the most part it seems OK to me.

I *really* worry, though, that this file is getting so big that few
people will work their way through it.  Anything that could be done to
make it more concise going forward would be more than welcome.

One other thing down below...

> v1, RFC
> * this version
> ---
>  .../admin-guide/reporting-issues.rst  | 273 ++
>  1 file changed, 149 insertions(+), 124 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst 
> b/Documentation/admin-guide/reporting-issues.rst
> index 18b1280f7abf..a475e014f9ca 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -94,10 +94,11 @@ early if an issue that looks like a Linux kernel problem 
> is actually caused by
>  something else. These steps thus help to ensure the time you invest in this
>  process won't feel wasted in the end:
>  
> - * Stop reading this document and report the problem to your vendor instead,
> -   unless you are running the latest mainline kernel already or are willing 
> to
> -   install it. This kernel must not be modified or enhanced in any way, and
> -   thus be considered 'vanilla'.
> + * Are you facing an issue with a Linux kernel a hardware or software vendor
> +   provided? Then in almost all cases you are better off to stop reading this
> +   document and reporting the issue to your vendor instead, unless you are
> +   willing to install the latest Linux version yourself. Be aware the latter
> +   will often be needed anyway to hunt down and fix issues.
>  
>   * See if the issue you are dealing with qualifies as regression, security
> issue, or a really severe problem: those are 'issues of high priority' 
> that
> @@ -134,12 +135,14 @@ process won't feel wasted in the end:
>  
>  After these preparations you'll now enter the main part:
>  
> - * Install the latest Linux mainline kernel: that's where all issues get
> -   fixed first, because it's the version line the kernel developers mainly
> -   care about. Testing and reporting with the latest Linux stable kernel can
> -   be an acceptable alternative in some situations, for example during the
> -   merge window; but during that period you might want to suspend your 
> efforts
> -   till its end anyway.
> + * Unless you are already running the latest 'mainline' Linux kernel, better
> +   go and install it for the reporting process. Testing and reporting with
> +   the latest 'stable' Linux can be an acceptable alternative in some
> +   situations; during the merge window that actually might be even the best
> +   approach, but in that development phase it can be an even better idea to
> +   suspend your efforts for a few days anyway. Whatever version you choose,
> +   ideally use a 'vanilla' built. Ignoring these advices will dramatically
> +   increase the risk you report will be rejected or ignored.

s/built/build/

Also, I would stop quoting terms like "mainline", "stable" and "vanilla"
throughout.  It makes the reading experience a bit stranger without
(IMO) adding anything.

Thanks,

jon

Re: [PATCH v2 2/2] docs: reporting-issues.rst: shortcut for reporting stable regressions

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Provide a much shorter and easier process for users that deal with
> regressions in stable and longterm kernels, as those should be reported
> quickly.
>
> Signed-off-by: Thorsten Leemhuis 
> CC: Randy Dunlap 

Seems generally good, but I had a couple of comments...

> v2
> * revist, lots of small improvements in various places
>
> v1
> * 
> https://lore.kernel.org/linux-doc/20210214145454.357392-1-li...@leemhuis.info/
> * initial version
> ---
>  .../admin-guide/reporting-issues.rst  | 140 --
>  1 file changed, 94 insertions(+), 46 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst 
> b/Documentation/admin-guide/reporting-issues.rst
> index 24ee78455d3e..937797e52837 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -106,6 +106,10 @@ process won't feel wasted in the end:
> issue, or a really severe problem: those are 'issues of high priority' 
> that
> need special handling in some steps that are about to follow.
>  
> + * If you are facing a regression within a stable or longterm version line
> +   (say something broke when updating from 5.10.4 to 5.10.5), head over to
> +   'Dealing with regressions within a stable and longterm kernel line'.

I would s/head over/scroll down/.  Otherwise readers may well wondering
where to go to find this section.

>   * Locate the driver or kernel subsystem that seems to be causing the issue.
> Find out how and where its developers expect reports. Note: most of the
> time this won't be bugzilla.kernel.org, as issues typically need to be 
> sent
> @@ -215,23 +219,42 @@ rebased on new stable or longterm releases. If that 
> case follow these steps:
> deemed unsuitable for backporting. If backporting was not considered at
> all, join the newest discussion, asking if it's in the cards.
>  
> - * Check if you're dealing with a regression that was never present in
> -   mainline by installing the first release of the version line you care
> -   about. If the issue doesn't show up with it, you basically need to report
> -   the issue with this version like you would report a problem with mainline
> -   (see above). This ideally includes a bisection followed by a search for
> -   existing reports on the net; with the help of the subject and the two
> -   relevant commit-ids. If that doesn't turn up anything, write the report; 
> CC
> -   or forward the report to the stable maintainers, the stable mailing list,
> -   and those who authored the change. Include the shortened commit-id if you
> -   found the change that causes it.
> -
>   * One of the former steps should lead to a solution. If that doesn't work
> out, ask the maintainers for the subsystem that seems to be causing the
> issue for advice; CC the mailing list for the particular subsystem as well
> as the stable mailing list.
>  
>  
> +Dealing with regressions within a stable and longterm kernel line
> +-
> +
> +This section is for you, if you face a regression within a stable or longterm
> +kernel version line, e.g. if something breaks when updating from 5.10.4 to
> +5.10.5 (a switch from 5.9.15 to 5.10.5 would not qualify). The developers 
> want
> +to fix such regressions as quickly as possible, hence there is a streamlined
> +process to report them:
> +
> + * Check the archives of the Linux stable mailing list for existing reports.
> +
> + * Check if the kernel developers still maintain the Linux kernel version
> +   line you care about: go to the front page of kernel.org and make sure it
> +   mentions the latest release of the particular version line without an
> +   '[EOL]' tag.
> +
> + * Install the latest release from the particular version line as a vanilla
> +   kernel. Ensure this kernel is not tainted and still shows the problem, as
> +   the issue might have already been fixed there.
> +
> + * Make sure it's not the kernel's surroundings that are causing the issue
> +   you face.

I can imagine that a lot of readers would have no idea what that means.
In fact, I'm not entirely sure what that means...

> + * Send a short problem report by mail to the people and mailing lists the
> +   :ref:`MAINTAINERS ` file specifies in the section 'STABLE
> +   BRANCH'. Roughly describe the issue and ideally explain how to reproduce
> +   it. Mention the first version that shows the problem and the last version
> +   that's working fine. Then wait for further instructions.
> +
> +
>  Reference section: Reporting issues to the kernel maintainers
>  =
>  
> @@ -433,6 +456,22 @@ fatal error where the kernel stop itself) with a 'Oops' 
> (a recoverable error),
>  as the kernel remains running after the latter.
>  
>  
> +Regression in stable or longterm kernel?
> +
> +
> +

Re: [PATCH] docs: don't include Documentation/Kconfig twice

[Jonathan Corbet]

Sergei Trofimovich  writes:

> Before the change there were two inclusions of Documentation/Kconfig:
> lib/Kconfig.debug:source "Documentation/Kconfig"
> Kconfig: source "Documentation/Kconfig"
>
> Kconfig also included 'source "lib/Kconfig.debug"'.
>
> Noticed as two 'make menuconfig' entries in both top level menu
> and in 'Kernel hacking' menu. The patch keeps entries only in
> 'Kernel hacking'.
>
> CC: Mauro Carvalho Chehab 
> CC: Jonathan Corbet 
> Signed-off-by: Sergei Trofimovich 
> ---
>  Kconfig | 2 --
>  1 file changed, 2 deletions(-)
>
> diff --git a/Kconfig b/Kconfig
> index 745bc773f567..97ed6389c921 100644
> --- a/Kconfig
> +++ b/Kconfig
> @@ -28,5 +28,3 @@ source "crypto/Kconfig"
>  source "lib/Kconfig"
>  
>  source "lib/Kconfig.debug"
> -
> -source "Documentation/Kconfig"
> -- 
> 2.30.1

I agree with not including it twice.  Under "kernel hacking" seems like
the wrong place to keep it, though.  There's a lot more than kernel
hacking in the kernel docs, I don't think we should bury it in quite
that way.  So I'd delete the other one.

Thanks,

jon

Re: [RFC PATCH] docs: Group arch-specific documentation under "CPU Architectures"

[Jonathan Corbet]

Jonathan Neuschäfer  writes:

> To declutter the top-level table of contents (the side bar), this
> patch reduces the architecture-specfic documentation to one top-level
> item, "CPU Architectures".
>
> Signed-off-by: Jonathan Neuschäfer 
> ---
>
> As a side effect, the TOC in index.html effectively gets one level of
> detail less. This could be fixed by specifying ':maxdepth: 3'.
> ---
>  Documentation/arch.rst  | 26 ++
>  Documentation/index.rst | 20 ++--
>  2 files changed, 28 insertions(+), 18 deletions(-)
>  create mode 100644 Documentation/arch.rst

I've badly wanted to clean up that page for a long time; this is a step
in that direction, so I'm happy to see it.  Applied, thanks.

And no, we need *less* detail on the front page, not more, so no need to
bring all that back.

Thanks,

jon

Re: [PATCH v3] Expose the bus kernel docs to the build docs.

[Jonathan Corbet]

Wren Turkal  writes:

> Before, the bus type related APIs that were defined in the
> include/linux/device/bus.h were not referenced anywhere in the docs, so
> I linked it to the bus types api documentation.

This should really be phrased in the imperative style as described in
Documentation/process/submitting-patches.rst.  I wouldn't ordinarily
reject a patch just for that, but...

> Signed-off-by: Wren Turkal 
> ---
>  Documentation/driver-api/driver-model/bus.rst | 8 
>  Documentation/driver-api/infrastructure.rst   | 3 +--
>  2 files changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/bus.rst 
> b/Documentation/driver-api/driver-model/bus.rst
> index 016b15a6e8ea..c53b01e95fd9 100644
> --- a/Documentation/driver-api/driver-model/bus.rst
> +++ b/Documentation/driver-api/driver-model/bus.rst
> @@ -1,3 +1,5 @@
> +.. _bus_types:
> +
>  =
>  Bus Types
>  =
> @@ -144,3 +146,9 @@ sysfs directory using::
>  
>   int bus_create_file(struct bus_type *, struct bus_attribute *);
>   void bus_remove_file(struct bus_type *, struct bus_attribute *);
> +
> +Functions and Structures
> +
> +
> +.. kernel-doc:: include/linux/device/bus.h
> +.. kernel-doc:: drivers/base/bus.c
> diff --git a/Documentation/driver-api/infrastructure.rst 
> b/Documentation/driver-api/infrastructure.rst
> index 683bd460e222..eb2a2c9e3c0c 100644
> --- a/Documentation/driver-api/infrastructure.rst
> +++ b/Documentation/driver-api/infrastructure.rst
> @@ -41,8 +41,7 @@ Device Drivers Base
>  .. kernel-doc:: drivers/base/platform.c
> :export:
>  
> -.. kernel-doc:: drivers/base/bus.c
> -   :export:
> +:ref:`bus_types`

Rather than inserting labels and making explicit cross-references, it
seems better to just let automarkup do the work for you.  So instead of
the above line, something like:

   See also Documentation/driver-api/driver-model/bus.rst

Thanks,

jon

Re: [PATCH] docs: dt: submitting-patches: Fix grammar in subsystem section

[Jonathan Corbet]

Geert Uytterhoeven  writes:

> Reword the subsystem bindings section to make sense, from a grammatical
> point of view.
>
> Signed-off-by: Geert Uytterhoeven 
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst 
> b/Documentation/devicetree/bindings/submitting-patches.rst
> index 68129ff09967d5d7..1d11c25249ff5465 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -75,8 +75,8 @@ II. For kernel maintainers
>   binding, and it hasn't received an Acked-by from the devicetree
>   maintainers after a few weeks, go ahead and take it.
>  
> - Subsystem bindings (anything affecting more than a single device)
> - then getting a devicetree maintainer to review it is required.
> + For subsystem bindings (anything affecting more than a single device),
> + getting a devicetree maintainer to review it is required.

Applied, thanks.

jon

Re: [RFC] scripts: kernel-doc: avoid warnings due to initial commented lines in file

[Jonathan Corbet]

Aditya  writes:

>> The opening comment mark /** is used for kernel-doc comments [1]
>> 
>> [1]
>> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments
>> 
>
> Hi Markus!
> That's true. But the content inside the comment does not follow
> kernel-doc format.
> For e.g., try running kernel-doc -none/man/rst on the above file in
> the example("sound/pci/ctxfi/ctresource.c").
> The starting 2-3 lines in files generally do not contain any
> struct/enum/function, etc. declaration.

The problem is that it's marked as a kerneldoc comment without actually
being one; it looks like somebody's internal corporate formatting.  The
fix is not to put a hack into kernel-doc - we have more than enough of
those in the file already!  The right thing to do is to remove the extra
"*" so that the comment doesn't look like a kerneldoc comment anymore.

Thanks,

jon

Re: [PATCH] Documentation/features: mark BATCHED_UNMAP_TLB_FLUSH doesn't apply to ARM64

[Jonathan Corbet]

Barry Song  writes:

> BATCHED_UNMAP_TLB_FLUSH is used on x86 to do batched tlb shootdown by
> sending one IPI to TLB flush all entries after unmapping pages rather
> than sending an IPI to flush each individual entry.
> On arm64, tlb shootdown is done by hardware. Flush instructions are
> innershareable. The local flushes are limited to the boot (1 per CPU)
> and when a task is getting a new ASID.
> So marking this feature as "TODO" is not proper. ".." isn't good as
> well. So this patch adds a "N/A" for this kind of features which are
> not needed on some architectures.
>
> Cc: Mel Gorman 
> Cc: Andy Lutomirski 
> Cc: Catalin Marinas 
> Cc: Will Deacon 
> Signed-off-by: Barry Song 
> ---
>  Documentation/features/arch-support.txt| 1 +
>  Documentation/features/vm/TLB/arch-support.txt | 2 +-
>  2 files changed, 2 insertions(+), 1 deletion(-)

This had a conflict with the c6x removal, but I fixed that up and
(finally) applied it, thanks.

jon

Re: [PATCH] docs/zh_CN: fix original link unknown document warning

[Jonathan Corbet]

Wu XiangCheng  writes:

> fix original link unknown document warning in zh_CN/admin-guide/README.rst
> and admin-guide/unicode.rst which introduced by commit:
>
>   550c8399d017 ("docs/zh_CN: Add zh_CN/admin-guide/README.rst")
>
> Reported-by: Stephen Rothwell 
> Signed-off-by: Wu XiangCheng 
> ---
> Sorry for the inconvenience. This is a fix patch. 
> Or I could re-submit the two original patches if you need.
>
>  Documentation/translations/zh_CN/admin-guide/README.rst  | 2 +-
>  Documentation/translations/zh_CN/admin-guide/unicode.rst | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst 
> b/Documentation/translations/zh_CN/admin-guide/README.rst
> index 939aee115e48..99b708a416d8 100644
> --- a/Documentation/translations/zh_CN/admin-guide/README.rst
> +++ b/Documentation/translations/zh_CN/admin-guide/README.rst
> @@ -1,6 +1,6 @@
>  .. include:: ../disclaimer-zh_CN.rst
>  
> -:Original: :ref:`Documentation/admin-guide/README.rst  5.x>`
> +:Original: :doc:`../../../admin-guide/README`

It seems even better to just let automarkup do its thing:

:Original: Documentation/admin-guide/README.rst

I'll just put in a quick fix along those lines.

Thanks,

jon

Re: [PATCH] docs: admin-guide: cgroup-v1: Fix typos in the file memory.rst

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/overcommited/overcommitted/
> s/Overcommiting/Overcommitting/
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Documentation/admin-guide/cgroup-v1/memory.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst 
> b/Documentation/admin-guide/cgroup-v1/memory.rst
> index 52688ae34461..0d574fd3f8e3 100644
> --- a/Documentation/admin-guide/cgroup-v1/memory.rst
> +++ b/Documentation/admin-guide/cgroup-v1/memory.rst
> @@ -360,8 +360,8 @@ U != 0, K = unlimited:
>
>  U != 0, K < U:
>  Kernel memory is a subset of the user memory. This setup is useful in
> -deployments where the total amount of memory per-cgroup is overcommited.
> -Overcommiting kernel memory limits is definitely not recommended, since 
> the
> +deployments where the total amount of memory per-cgroup is overcommitted.
> +Overcommitting kernel memory limits is definitely not recommended, since 
> the
>  box can still run out of non-reclaimable memory.

Applied, thanks.

jon

Re: [PATCH V2] docs: livepatch: Fix a typo and remove the unnecessary gaps in a sentence

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/varibles/variables/
>
> ...and remove leading spaces from a sentence.
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Changes from V1:
>   Pter pointed out some awkward  leading space in a sentence ,fixed it.
>
>  Documentation/livepatch/shadow-vars.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

I've applied this, poking in the suggested prepositional tweak in the
process.

Thanks,

jon

Re: [PATCH v2] docs: filesystem: Update smaps vm flag list to latest

[Jonathan Corbet]

Peter Xu  writes:

> We've missed a few documentation when adding new VM_* flags.  Add the missing
> pieces so they'll be in sync now.
>
> Signed-off-by: Peter Xu 
> ---
> v2:
> - rebase
> ---
>  Documentation/filesystems/proc.rst | 4 
>  1 file changed, 4 insertions(+)

Applied, thanks.

jon

Re: [PATCH] docs: conf.py: adjust the LaTeX document output

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> Changeset f546ff0c0c07 ("Move our minimum Sphinx version to 1.7")
> cleaned up some compatibility issues with previous Sphinx
> versions, but it also dropped the PDF margin sets.
>
> Without that, the media documentation won't build fine, as
> the margins are too wide to display texts with monospaced
> fonts.
>
> While here, align the  "latex_elements = {" values, and add
> a few other sphinxsetup configs in order to allow Sphinx to
> wrap long lines on literal blocks.
>
> Fixes: f546ff0c0c07 ("Move our minimum Sphinx version to 1.7")
> Signed-off-by: Mauro Carvalho Chehab 
>
>  Documentation/conf.py | 31 +++
>  1 file changed, 19 insertions(+), 12 deletions(-)

Applied, thanks.

jon

Re: [PATCH] Documentation/admin-guide: kernel-parameters: correct the architectures for numa_balancing

[Jonathan Corbet]

Barry Song  writes:

> X86 isn't the only architecture supporting NUMA_BALANCING. ARM64, PPC,
> S390 and RISCV also support it:

Applied, thanks.

jon

Re: [PATCH] docs: kvm: Fix a typo ("althought")

[Jonathan Corbet]

Jonathan Neuschäfer  writes:

> Signed-off-by: Jonathan Neuschäfer 
> ---
>  Documentation/virt/kvm/api.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index aed52b0fc16ec..3617a64e81fe2 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -55,7 +55,7 @@ not cause harm to the host, their actual behavior is not 
> guaranteed by
>  the API.  See "General description" for details on the ioctl usage
>  model that is supported by KVM.
>
> -It is important to note that althought VM ioctls may only be issued from
> +It is important to note that although VM ioctls may only be issued from
>  the process that created the VM, a VM's lifecycle is associated with its
>  file descriptor, not its creator (process).  In other words, the VM and

Applied, thanks.

jon

Re: [PATCH 0/8] input: Documentation: corrections to Doc/input/ files

[Jonathan Corbet]

Randy Dunlap  writes:

> Update several Documentation/input/ files for wording, punctutation,
> struct info, and file names.
>
> Cc: Dmitry Torokhov 
> Cc: linux-in...@vger.kernel.org
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
>
>  [PATCH 1/8] input: Documentation: corrections for input.rst
>  [PATCH 2/8] input: Documentation: corrections for event-codes.rst
>  [PATCH 3/8 RESEND] input: Documentation: update related file names in ff.rst
>  [PATCH 4/8] input: Documentation: corrections for gameport-programming.rst
>  [PATCH 5/8] input: Documentation: corrections for multi-touch-protocol.rst
>  [PATCH 6/8] input: Documentation: corrections for notifier.rst
>  [PATCH 7/8] input: Documentation: corrections for input-programming.rst
>  [PATCH 8/8] input: Documentation: corrections for uinput.rst
>
>  Documentation/input/event-codes.rst  |   10 ++--
>  Documentation/input/ff.rst   |6 +-
>  Documentation/input/gameport-programming.rst |   35 +++--
>  Documentation/input/input-programming.rst|   20 -
>  Documentation/input/input.rst|8 +--
>  Documentation/input/multi-touch-protocol.rst |8 +--
>  Documentation/input/notifier.rst |3 -
>  Documentation/input/uinput.rst   |2 
>  8 files changed, 52 insertions(+), 40 deletions(-)

Set applied, thanks.

jon

Re: [PATCH] scripts/kernel-doc: ignore identifier on anonymous enums

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> When anonymous enums are used, the identifier is empty.
>
> While, IMO, it should be avoided the usage of such enums,
> adding support for it is not hard.
>
> So, postpone the check for empty identifiers to happen
> only at the dump phase.
>
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  scripts/kernel-doc | 9 +++--
>  1 file changed, 7 insertions(+), 2 deletions(-)

Applied, thanks.

jon

Re: [PATCH] Documentation: dynamic-debug-howto: fix example

[Jonathan Corbet]

Martin Kepplinger  writes:

> dynamic debug is "expecting pairs of match-spec " so the example
> for all files of which the paths include "usb" there is "file" missing.
>
> Signed-off-by: Martin Kepplinger 
> ---
>  Documentation/admin-guide/dynamic-debug-howto.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst 
> b/Documentation/admin-guide/dynamic-debug-howto.rst
> index 6c04aea8f4cd..b119b8277b3e 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
> @@ -347,7 +347,7 @@ Examples
>   /dynamic_debug/control
>  
>// enable messages in files of which the paths include string "usb"
> -  nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control
> +  nullarbor:~ # echo -n 'file *usb* +p' > /dynamic_debug/control

Applied, thanks.

jon

Re: [PATCH 0/2] docs: driver-model: device: Add helper macro examples

[Jonathan Corbet]

Geert Uytterhoeven  writes:

>   Hi Jon, Greg, Rafael,
>
> The DEVICE_ATTR_* and ATTRIBUTE_GROUPS() helper macros have existed for
> more than a decade, but are still not mentioned in the driver-model
> device documentation.  Hence this patch series adds them, including
> examples, to the documentation.
>
> Thanks for your comments!
>
> Geert Uytterhoeven (2):
>   docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples
>   docs: driver-model: device: Add ATTRIBUTE_GROUPS() example
>
>  .../driver-api/driver-model/device.rst| 23 ++-
>  1 file changed, 17 insertions(+), 6 deletions(-)

Set applied, thanks.

jon

Re: [PATCH] PATCH Documentation translations:translate sound/hd-audio/controls to chinese

[Jonathan Corbet]

hjh  writes:

> Signed-off-by: hjh 
> ---
>  Documentation/translations/zh_CN/index.rst|   1 +
>  .../zh_CN/sound/hd-audio/controls.rst | 102 ++
>  .../zh_CN/sound/hd-audio/index.rst|  14 +++
>  .../translations/zh_CN/sound/index.rst|  22 
>  4 files changed, 139 insertions(+)
>  create mode 100644 
> Documentation/translations/zh_CN/sound/hd-audio/controls.rst
>  create mode 100644 Documentation/translations/zh_CN/sound/hd-audio/index.rst
>  create mode 100644 Documentation/translations/zh_CN/sound/index.rst

Applied, thanks.

jon

Re: [PATCH] media: add a subsystem profile documentation

[Jonathan Corbet]

Mauro Carvalho Chehab  writes:

> Document the basic policies of the media subsystem profile.
>
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/driver-api/media/index.rst  |   2 +
>  .../media/maintainer-entry-profile.rst| 206 ++
>  .../maintainer/maintainer-entry-profile.rst   |   1 +
>  3 files changed, 209 insertions(+)
>  create mode 100644 
> Documentation/driver-api/media/maintainer-entry-profile.rst

This all looks good to me; would you like me to take it or were you
going to send it upward yourself?

Thanks,

jon

Re: [RFC v2] scripts: kernel-doc: fix attribute capture in function parsing

[Jonathan Corbet]

Aditya Srivastava  writes:

> Currently, kernel-doc warns for function prototype parsing on the
> presence of attributes "__attribute_const__" and "__flatten" in the
> definition.
>
> There are 166 occurrences in ~70 files in the kernel tree for
> "__attribute_const__" and 5 occurrences in 4 files for "__flatten".
>
> Out of 166, there are 3 occurrences in three different files with
> "__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in
> ./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other
> occurrences have no preceding kernel-doc.
>
> Add support for  "__attribute_const__" and "__flatten" attributes.
>
> A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals
> that no additional warning or error has been added or removed by the fix.
>
> Suggested-by: Lukas Bulwahn 
> Signed-off-by: Aditya Srivastava 
> ---
> Changes in v2:
> - Remove "__attribute_const__" from the $return_type capture regex and add to 
> the substituting ones.
> - Add support for "__flatten" attribute
> - Modify commit message
>
>  scripts/kernel-doc | 2 ++
>  1 file changed, 2 insertions(+)

Applied, thanks.

jon

Re: [PATCH 1/1] docs: arm: /chosen node parameters

[Jonathan Corbet]

Heinrich Schuchardt  writes:

> Add missing items to table of parameters set in the /chosen node by the EFI
> stub.
>
> Signed-off-by: Heinrich Schuchardt 
> ---
>  Documentation/arm/uefi.rst | 7 +++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst
> index f732f957421f..9b0b5e458a1e 100644
> --- a/Documentation/arm/uefi.rst
> +++ b/Documentation/arm/uefi.rst
> @@ -64,4 +64,11 @@ linux,uefi-mmap-desc-size   32-bit   Size in bytes of each 
> entry in the UEFI
>   memory map.
>
>  linux,uefi-mmap-desc-ver32-bit   Version of the mmap descriptor format.
> +
> +linux,initrd-start  64-bit   Physical start address of an initrd
> +
> +linux,initrd-end64-bit   Physical end address of an initrd
> +
> +kaslr-seed  64-bit   Entropy used to randomize the kernel 
> image
> + base address location.
>  ==  ==   
> ===

Applied, thanks.

jon

Re: [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation

[Jonathan Corbet]

Randy Dunlap  writes:

> Use the documented kernel-doc format for function Return: descriptions.
> Begin constant values in kernel-doc comments with '%'.
>
> Remove kernel-doc "/**" from 2 functions that are not documented with
> kernel-doc notation.
>
> Fix typos, punctuation, & grammar.
>
> Also fix a few kernel-doc warnings:
>
> ../fs/eventpoll.c:1883: warning: Function parameter or member 'ep' not 
> described in 'ep_loop_check_proc'
> ../fs/eventpoll.c:1883: warning: Excess function parameter 'priv' description 
> in 'ep_loop_check_proc'
> ../fs/eventpoll.c:1932: warning: Function parameter or member 'ep' not 
> described in 'ep_loop_check'
> ../fs/eventpoll.c:1932: warning: Excess function parameter 'from' description 
> in 'ep_loop_check'
>
> Signed-off-by: Randy Dunlap 
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
> Cc: Andrew Morton 
> Cc: Alexander Viro 
> ---
> Jon: Al says that he is OK with one of you merging this fs/
>  (only comments) patch.
>
>  fs/eventpoll.c |   52 +++
>  1 file changed, 26 insertions(+), 26 deletions(-)

Both patches applied, thanks.

jon

Re: [PATCH] Documentation: ioctl: add entry for nsfs.h

[Jonathan Corbet]

Randy Dunlap  writes:

> All userspace ioctls major/magic number should be documented in
> Documentation/userspace-api/ioctl/ioctl-number.rst, so add
> the entry for .
>
> Signed-off-by: Randy Dunlap 
> Cc: Andrey Vagin 
> Cc: Serge Hallyn 
> Cc: Eric W. Biederman 
> Cc: linux-...@vger.kernel.org
> Cc: Jonathan Corbet 
> ---
> Feel free to modify the patch as needed.
>
> Probably don't need to backport:
> # Fixes: 6786741dbf99 ("nsfs: add ioctl to get an owning user namespace for 
> ns file descriptor")
>
>  Documentation/userspace-api/ioctl/ioctl-number.rst |1 +
>  1 file changed, 1 insertion(+)

Applied (rather belatedly, sorry).

Thanks,

jon

Re: [PATCH] Documentation: Replace more lkml.org links with lore

[Jonathan Corbet]

Kees Cook  writes:

> As started by commit 05a5f51ca566 ("Documentation: Replace lkml.org
> links with lore"), replace a few more scattered lkml.org links with
> lore to better use a single source that's more likely to stay available
> long-term.
>
> Signed-off-by: Kees Cook 
> ---
>  CREDITS| 2 +-
>  tools/scripts/Makefile.include | 3 ++-
>  2 files changed, 3 insertions(+), 2 deletions(-)

I've (rather belatedly) applied this, thanks.

jon

Re: [PATCH] docs: filesystem: Update smaps vm flag list to latest

[Jonathan Corbet]

Peter Xu  writes:

> We've missed a few documentation when adding new VM_* flags.  Add the missing
> pieces so they'll be in sync now.
>
> Signed-off-by: Peter Xu 
> ---
>  Documentation/filesystems/proc.rst | 5 +
>  1 file changed, 5 insertions(+)

So this patch doesn't apply; what version of the kernel did you generate
it against?  Could you redo against current kernels, please?

Thanks,

jon

Re: [PATCH] Documentation/submitting-patches: Extend commit message layout description

[Jonathan Corbet]

Borislav Petkov  writes:

> From: Borislav Petkov 
> Subject: [PATCH] Documentation/submitting-patches: Extend commit message 
> layout description
>
> Add more blurb about the level of detail that should be contained in a
> patch's commit message. Extend and make more explicit what text should
> be added under the --- line. Extend examples and split into more easily
> palatable paragraphs.
>
> This has been partially carved out from a tip subsystem handbook
> patchset by Thomas Gleixner:
>
>   https://lkml.kernel.org/r/20181107171010.421878...@linutronix.de
>
> and incorporates follow-on comments.
>
> Signed-off-by: Borislav Petkov 
> ---
>
> /me sends the next generic topic blurb.
>
>  Documentation/process/submitting-patches.rst | 89 
>  1 file changed, 56 insertions(+), 33 deletions(-)

Applied, with one tweak:

> +If there are four patches in a patch series the individual patches may
> +be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers
> +understand the order in which the patches should be applied and that
> +they have reviewed or applied all of the patches in the patch series.
>  
>  A couple of example Subjects::
>  
>  Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
>  Subject: [PATCH v2 01/27] x86: fix eflags tracking
> +Subject: [PATCH v2] sub/sys: Condensed patch summary
> +Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary

It's no longer "a couple" so I made this "Here are some good example
Subjects".

Thanks,

jon

Re: [PATCH v3 0/3] docs: arm: Improvements to Marvell SoC documentation

[Jonathan Corbet]

Lubomir Rintel  writes:

> Hi,
>
> please consider applying the patches chained to this message.
>
> The objective is to deal with the a large amount of dead links to
> material that often comes handy in marvel.rst; and improve some details
> along the way.
>
> Compared to v2, the patches "[PATCH v2 2/5] docs: arm: marvell: fix 38x
> functional spec link" and "[PATCH v2 5/5] docs: arm: marvell: rename
> marvel.rst to marvell.rst" have been removed, because analogous patches
> have already been applied. Also, more dead links have been removed,
> reducing the count of links removed in [PATCH v3 1/3] to one.
> Detailed changelogs in individual patches.

I've applied parts 1 and 3; since there is evidently an archive link for
the one killed in part 2, I left that out.

Thanks,

jon

Re: [PATCH] docs: reporting-issues.rst: explain how to decode stack traces

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Replace placeholder text about decoding stack traces with a section that
> properly describes what a typical user should do these days. To make
> it works for them, add a paragraph in an earlier section to ensure
> people build their kernels with everything that's needed to decode stack
> traces later.
>
> Signed-off-by: Thorsten Leemhuis 
> Reviewed-by: Qais Yousef 
> ---
> v1->v2
> * Fix typo pointed out by Randy
> * include review feedback from Qais and bis Reviewed-by:
>
> v1:
> https://lore.kernel.org/lkml/20210210054823.242262-1-li...@leemhuis.info/
> ---
>  .../admin-guide/reporting-issues.rst  | 81 ++-
>  1 file changed, 59 insertions(+), 22 deletions(-)

Applied, thanks.

jon

Re: [PATCH v8 0/3] checkpatch: add verbose mode

[Jonathan Corbet]

Joe Perches  writes:

> On Mon, 2021-03-01 at 14:22 -0700, Jonathan Corbet wrote:
>> Dwaipayan Ray  writes:
>> 
>> > Add a new verbose mode to checkpatch. The verbose test
>> > descriptions are read from the new checkpatch documentation
>> > file at `Documentation/dev-tools/checkpatch.rst`, which
>> > is also added by this series.
>> 
>> So I can certainly take the doc change, as requested.  Remind me,
>> though...should I apply the whole set, or will the checkpatch changes go
>> via another path?
>
> There's no dedicated upstream path for checkpatch.
> So please take the checkpatch changes too.

OK, I have just done that.

Thanks,

jon

Re: [PATCH] docs: watchdog: fix obsolete include file reference in pcwd

[Jonathan Corbet]

Flavio Suligoi  writes:

> The file linux/pcwd.h is not more present in the kernel
> sources. Its information is now moved into the file:
>
> include/uapi/linux/watchdog.h
>
> Signed-off-by: Flavio Suligoi 
> ---
>  Documentation/watchdog/pcwd-watchdog.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, thanks.

jon

Re: [PATCH] docs: driver-model: Remove obsolete device class documentation

[Jonathan Corbet]

Geert Uytterhoeven  writes:

> None of this is valid since v2.5.69.
>
> Signed-off-by: Geert Uytterhoeven 
> ---
> I started updating the document, until I realized that all of the
> typedefs, structures, functions, defines, and sysfs layout have been
> renamed, changed, or removed.  So I think it's better (for an expert in
> the field) to start from scratch.
> ---
>  .../driver-api/driver-model/class.rst | 149 --
>  .../driver-api/driver-model/index.rst |   1 -
>  2 files changed, 150 deletions(-)
>  delete mode 100644 Documentation/driver-api/driver-model/class.rst

Yay for deleting old useless stuff.  Applied, thanks.

jon

Re: [RFC v3] scripts: kernel-doc: fix typedef support for struct/union parsing

[Jonathan Corbet]

Aditya Srivastava  writes:

> Currently, there are ~1290 occurrences in 447 files in the kernel tree
> 'typedef struct/union' syntax for defining some struct/union. However,
> kernel-doc currently does not support that syntax. Of the ~1290
> occurrences, there are four occurrences in ./include/linux/zstd.h with
> typedef struct/union syntax and a preceding kernel-doc; all other
> occurrences have no preceding kernel-doc.
>
> Add support for parsing struct/union following this syntax.
>
> Signed-off-by: Aditya Srivastava 

Applied, thanks.

jon

Re: [PATCH v8 0/3] checkpatch: add verbose mode

[Jonathan Corbet]

Dwaipayan Ray  writes:

> Add a new verbose mode to checkpatch. The verbose test
> descriptions are read from the new checkpatch documentation
> file at `Documentation/dev-tools/checkpatch.rst`, which
> is also added by this series.

So I can certainly take the doc change, as requested.  Remind me,
though...should I apply the whole set, or will the checkpatch changes go
via another path?

Thanks,

jon

Re: [PATCH] doc: memcontrol: add description for oom_kill

[Jonathan Corbet]

Yang Shi  writes:

> When debugging an oom issue, I found the oom_kill counter of memcg is
> confusing.  At the first glance without checking document, I thought it
> just counts for memcg oom, but it turns out it counts both global and
> memcg oom.
>
> The cgroup v2 documents it, but the description is missed for cgroup v1.
>
> Signed-off-by: Yang Shi 
> ---
>  Documentation/admin-guide/cgroup-v1/memory.rst | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst 
> b/Documentation/admin-guide/cgroup-v1/memory.rst
> index 0936412e044e..44d5429636e2 100644
> --- a/Documentation/admin-guide/cgroup-v1/memory.rst
> +++ b/Documentation/admin-guide/cgroup-v1/memory.rst
> @@ -851,6 +851,9 @@ At reading, current status of OOM is shown.
> (if 1, oom-killer is disabled)
>   - under_oom0 or 1
> (if 1, the memory cgroup is under OOM, tasks may be stopped.)
> +- oom_kill integer counter
> +  The number of processes belonging to this cgroup killed by any
> +  kind of OOM killer.

Applied, thanks.

jon

Re: [PATCH] PATCH Documentation translations:translate sound/hd-audio/controls to chinese

[Jonathan Corbet]

hjh  writes:

> Signed-off-by: hjh 
> ---
>  Documentation/translations/zh_CN/index.rst|   1 +
>  .../zh_CN/sound/hd-audio/controls.rst | 102 ++
>  .../zh_CN/sound/hd-audio/index.rst|  17 +++
>  .../translations/zh_CN/sound/index.rst|  26 +
>  4 files changed, 146 insertions(+)
>  create mode 100644 
> Documentation/translations/zh_CN/sound/hd-audio/controls.rst
>  create mode 100644 Documentation/translations/zh_CN/sound/hd-audio/index.rst
>  create mode 100644 Documentation/translations/zh_CN/sound/index.rst

So you have sent me two versions of this in the last 24 hours with no
indication of what has changed or why I should prefer one over the
other.  Always include that information (under the "---" line) when you
send updated versions.

It looks like you got a Reviewed-by tag from Alex on the other version,
but that doesn't appear here; why?

[...]

> diff --git a/Documentation/translations/zh_CN/sound/hd-audio/index.rst 
> b/Documentation/translations/zh_CN/sound/hd-audio/index.rst
> new file mode 100644
> index ..c287aad51066
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/sound/hd-audio/index.rst
> @@ -0,0 +1,17 @@
> +.. include:: ../../disclaimer-zh_CN.rst
> +
> +:Original: :doc:`../../../../sound/hd-audio/index`
> +:Translator: Huang Jianghui 
> +
> +
> +高清音频
> +
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   notes
> +   models
> +   controls
> +   dp-mst
> +   realtek-pc-beep

So you list a bunch of files here, but most of them are not added in
your patch.  That will, of course, break the docs build.

> diff --git a/Documentation/translations/zh_CN/sound/index.rst 
> b/Documentation/translations/zh_CN/sound/index.rst
> new file mode 100644
> index ..42d86b361e42
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/sound/index.rst
> @@ -0,0 +1,26 @@

Similarly, including the index.rst file at this level is good, but...

> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: :doc:`../../../sound/index`
> +:Translator: Huang Jianghui 
> +
> +
> +
> +Linux 声音子系统文档
> +
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   kernel-api/index
> +   designs/index
> +   soc/index
> +   alsa-configuration
> +   hd-audio/index
> +   cards/index

What are all of these files?

Please fix these issues and make sure that the docs build runs correctly
before resubmitting.

Thanks,

jon

Re: [PATCH V2] docs: sphinx: Fix couple of spellings in the file rstFlatTable.py

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

> s/automaticly/automatically/
> s/buidler/builder/
>
> ..and a sentence construction fix.
>
> Signed-off-by: Bhaskar Chowdhury 
> ---
>  Changes from V1:
>  Incorporating Randy's observations ...i.e sentence construction
>
>  Documentation/sphinx/rstFlatTable.py | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Applied, thanks.

jon

[GIT PULL] Documentation fixes for 5.12

[Jonathan Corbet]

The following changes since commit 3c2e0a489da6a7c48ad67a246c7a287fcb4a4607:

  docs: kernel-hacking: be more civil (2021-02-11 10:00:40 -0700)

are available in the Git repository at:

  git://git.lwn.net/linux.git tags/docs-5.12-2

for you to fetch changes up to f37a15ea8db022373a2cb6d1a6004c65c2b7f17e:

  docs: proc.rst: fix indentation warning (2021-02-25 13:11:00 -0700)


A handful of late-arriving documentation fixes, nothing all that notable.


Aditya Srivastava (1):
  scripts: kernel-doc: fix array element capture in pointer-to-func parsing

Andrew Donnellan (1):
  docs: powerpc: Fix tables in syscall64-abi.rst

Antonio Terceiro (1):
  Documentation: cgroup-v2: fix path to example BPF program

Arnd Bergmann (2):
  Documentation: features: remove c6x references
  Documentation: features: refresh feature list

Masahiro Yamada (1):
  doc: use KCFLAGS instead of EXTRA_CFLAGS to pass flags from command line

Matthew Wilcox (1):
  Fix unaesthetic indentation

Michael Weiß (1):
  docs: ABI: testing: ima_policy: Fixed missing bracket

Randy Dunlap (2):
  Documentation: proc.rst: add more about the 6 fields in loadavg
  docs: proc.rst: fix indentation warning

 Documentation/ABI/testing/ima_policy   |  2 +-
 Documentation/admin-guide/cgroup-v2.rst|  2 +-
 Documentation/conf.py  |  3 +-
 .../features/core/cBPF-JIT/arch-support.txt|  1 -
 .../features/core/eBPF-JIT/arch-support.txt|  1 -
 .../core/generic-idle-thread/arch-support.txt  |  1 -
 .../features/core/jump-labels/arch-support.txt |  1 -
 .../features/core/tracehook/arch-support.txt   |  1 -
 .../features/debug/KASAN/arch-support.txt  |  1 -
 .../debug/debug-vm-pgtable/arch-support.txt|  1 -
 .../debug/gcov-profile-all/arch-support.txt|  3 +-
 Documentation/features/debug/kcov/arch-support.txt |  1 -
 Documentation/features/debug/kgdb/arch-support.txt |  1 -
 .../features/debug/kmemleak/arch-support.txt   |  3 +-
 .../debug/kprobes-on-ftrace/arch-support.txt   |  3 +-
 .../features/debug/kprobes/arch-support.txt|  3 +-
 .../features/debug/kretprobes/arch-support.txt |  3 +-
 .../features/debug/optprobes/arch-support.txt  |  1 -
 .../features/debug/stackprotector/arch-support.txt |  1 -
 .../features/debug/uprobes/arch-support.txt|  3 +-
 .../debug/user-ret-profiler/arch-support.txt   |  1 -
 .../features/io/dma-contiguous/arch-support.txt|  1 -
 .../locking/cmpxchg-local/arch-support.txt |  1 -
 .../features/locking/lockdep/arch-support.txt  |  1 -
 .../locking/queued-rwlocks/arch-support.txt|  1 -
 .../locking/queued-spinlocks/arch-support.txt  |  1 -
 .../features/perf/kprobes-event/arch-support.txt   |  3 +-
 .../features/perf/perf-regs/arch-support.txt   |  3 +-
 .../features/perf/perf-stackdump/arch-support.txt  |  3 +-
 .../sched/membarrier-sync-core/arch-support.txt|  1 -
 .../features/sched/numa-balancing/arch-support.txt |  3 +-
 .../seccomp/seccomp-filter/arch-support.txt|  1 -
 .../time/arch-tick-broadcast/arch-support.txt  |  1 -
 .../features/time/clockevents/arch-support.txt |  1 -
 .../time/context-tracking/arch-support.txt |  1 -
 .../features/time/irq-time-acct/arch-support.txt   |  1 -
 .../features/time/virt-cpuacct/arch-support.txt|  1 -
 .../features/vm/ELF-ASLR/arch-support.txt  |  1 -
 .../features/vm/PG_uncached/arch-support.txt   |  1 -
 Documentation/features/vm/THP/arch-support.txt |  1 -
 Documentation/features/vm/TLB/arch-support.txt |  1 -
 .../features/vm/huge-vmap/arch-support.txt |  1 -
 .../features/vm/ioremap_prot/arch-support.txt  |  1 -
 .../features/vm/pte_special/arch-support.txt   |  1 -
 Documentation/filesystems/proc.rst |  4 ++
 Documentation/powerpc/syscall64-abi.rst| 51 ++
 Documentation/process/4.Coding.rst |  2 +-
 Documentation/process/submit-checklist.rst |  2 +-
 .../translations/it_IT/process/4.Coding.rst|  2 +-
 .../it_IT/process/submit-checklist.rst |  2 +-
 .../translations/zh_CN/process/4.Coding.rst|  2 +-
 drivers/gpu/drm/tilcdc/Makefile|  2 +-
 scripts/kernel-doc |  2 +-
 53 files changed, 56 insertions(+), 81 deletions(-)

Re: linux-next: Fixes tag needs some work in the jc_docs tree

[Jonathan Corbet]

Stephen Rothwell  writes:

> Hi all,
>
> In commit
>
>   36eaf08fc283 ("docs: powerpc: Fix tables in syscall64-abi.rst")
>
> Fixes tag
>
>   Fixes: 209b44c804c ("docs: powerpc: syscall64-abi.rst: fix a malformed 
> table")
>
> has these problem(s):
>
>   - SHA1 should be at least 12 digits long
>
> I don't think this is worth rebasing for, but in the future it can be
> fixed by setting core.abbrev to 12 (or more) or (for git v2.11 or later)
> just making sure it is not set (or set to "auto").

I made that tag by hand while "fixing" the changlog on that commit,
which included the full ID.  Obviously, counting to 12 is a challenging
task for a slow guy like me...:)

Thanks,

jon

Re: [PATCH v7 0/2] checkpatch: add verbose mode

[Jonathan Corbet]

Dwaipayan Ray  writes:

> On Thu, Feb 25, 2021 at 11:03 PM Joe Perches  wrote:
>> I don't have any real objection to this patch set, but as this
>> might be added to the Documentation tree and in .rst format,
>> perhaps Jonathan Corbet and/or Mauro Carvalho Chehab might have
>> some opinion.
>>
>> Also I do not want to be a maintainer of this .rst file and
>> likely neither Jon nor Mauro would either.  Perhaps you?
>>
>
> I could take it up if everybody is okay with it!
>
>> Ideally, the patch order would be reversed so the .rst file
>> is added first, then checkpatch updated to use it.
>>
>
> Sure, if Jonathan or Mauro has no objections to it, I will be happy
> to resend it so that it can be picked up properly.

So I haven't been copied on this for a while.  Looking in the archives,
I see that you have a manual table of contents at the top of the
document; you could take that out and let Sphinx generate it (and keep
it current!) for you.

Either way, though, if you want to merge this via some other path, it's
OK by me:

Acked-by: Jonathan Corbet 

Thanks,

jon

Re: [PATCH -next] docs: proc.rst: fix indentation warning

[Jonathan Corbet]

Randy Dunlap  writes:

> Fix indentation snafu in proc.rst as reported by Stephen.
>
> next-20210219/Documentation/filesystems/proc.rst:697: WARNING: Unexpected 
> indentation.
>
> Fixes: 93ea4a0b8fce ("Documentation: proc.rst: add more about the 6 fields in 
> loadavg")
> Reported-by: Stephen Rothwell 
> Signed-off-by: Randy Dunlap 
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
> ---
> shame on me.
>
>  Documentation/filesystems/proc.rst |2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, thanks.

jon

Re: [PATCH] Documentation: cgroup-v2: fix path to example BPF program

[Jonathan Corbet]

Antonio Terceiro  writes:

> This file has been moved into the "progs" subdirectory in
> bd4aed0ee73ca873bef3cb3ec746dd796f03df28, together with all test BPF
> programs.
>
> Signed-off-by: Antonio Terceiro 
> Cc: Tejun Heo 
> Cc: Zefan Li 
> Cc: Johannes Weiner 
> Cc: Jonathan Corbet 
> Cc: Jiong Wang 
> ---
>  Documentation/admin-guide/cgroup-v2.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, thanks.  I did fix the changelog to include a Fixes: tag with
the commit listed in the proper format.

Thanks,

jon

Re: [PATCH 1/2] Documentation: features: remove c6x references

[Jonathan Corbet]

Arnd Bergmann  writes:

> From: Arnd Bergmann 
>
> The references to arch/c6x are obsolete now that the architecture
> is gone. Remove them.
>
> Signed-off-by: Arnd Bergmann 

Both applied, thanks.

jon

Re: [PATCH] docs: ABI: testing: ima_policy: Fixed missing bracket

[Jonathan Corbet]

Michael Weiß  writes:

> This fixes a minor typo introduced by commit 3442841d:
> "docs: ABI: testing: make the files compatible with ReST output"
>
> Signed-off-by: Michael Weiß 
> ---
>  Documentation/ABI/testing/ima_policy | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, but I rewrote the changelog to use a Fixes: tag and to cite the
offending commit in the proper format:

Fixes: 3442841d ("docs: ABI: testing: make the files compatible with 
ReST output")

Thanks,

jon

Re: [RFC] scripts: kernel-doc: fix typedef support for struct parsing

[Jonathan Corbet]

Aditya Srivastava  writes:

> There are files in kernel, which use 'typedef struct' syntax for defining
> struct. For eg, include/linux/zstd.h, drivers/scsi/megaraid/mega_common.h,
> etc.
> However, kernel-doc still does not support it, causing a parsing error.
>
> For eg, running scripts/kernel-doc -none on include/linux/zstd.h emits:
> "error: Cannot parse struct or union!"
>
> Add support for parsing it.
>
> Signed-off-by: Aditya Srivastava 
> ---
>  scripts/kernel-doc | 12 ++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 8b5bc7bf4bb8..46e904dc3f87 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1201,12 +1201,20 @@ sub dump_union($$) {
>  sub dump_struct($$) {
>  my $x = shift;
>  my $file = shift;
> +my $decl_type;
> +my $members;
>  
>  if ($x =~ 
> /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|cacheline_aligned_in_smp|cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/)
>  {
> - my $decl_type = $1;
> + $decl_type = $1;
>   $declaration_name = $2;
> - my $members = $3;
> + $members = $3;
> +} elsif ($x =~ 
> /typedef\s+(struct|union)\s*\{(.*)\}(?:\s*(?:__packed|__aligned|cacheline_aligned_in_smp|cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*\s*(\w*)\s*;/)
>  {

So this isn't your fault, but these regexes are really getting out of
hand.  I would *really* like to see some effort made into making this
code more understandable / maintainable as we tweak this stuff.  So:

 - Splitting out the common part, as suggested by Lukas, would be really
   useful.  That would also avoid the problem of only occurrence being
   edited the next tine we add a new qualifier.

 - Splitting out other subsections of the regex and giving them symbolic
   names would also help.

 - We really could use some comments before these branches saying what
   they are doing; it is *not* obvious from the code.

See what I'm getting at here?

Thanks,

jon

Re: [RFC] scripts: kernel-doc: fix array element capture in pointer-to-func parsing

[Jonathan Corbet]

Aditya Srivastava  writes:

> Currently, kernel-doc causes an unexpected error when array element (i.e.,
> "type (*foo[bar])(args)") is present as pointer parameter in
> pointer-to-function parsing.
>
> For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this
> error:
> "Use of uninitialized value $param in regexp compilation at ...", in
> combination with:
> "warning: Function parameter or member '' not described in 'gcov_info'"

In the future, please quote error messages from the kernel verbatim.
You can trim irrelevant stuff before or after, but please do not edit
them in this way.  That helps me to understand what you are fixing, and
is also useful for anybody else who might be searching for a solution to
the same problem.

> Here, the parameter parsing does not take into account the presence of
> array element (i.e. square brackets) in $param.
>
> Provide a simple fix by adding square brackets in the regex, responsible
> for capturing $param.
>
> A quick evaluation, by running 'kernel-doc -none' on entire kernel-tree,
> reveals that no additional warning or error has been added or removed by
> the fix.
>
> Suggested-by: Lukas Bulwahn 
> Signed-off-by: Aditya Srivastava 
> ---
> * Applies perfectly over next-20210217
>
>  scripts/kernel-doc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index e046e16e4411..8b5bc7bf4bb8 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1553,7 +1553,7 @@ sub create_parameterlist() {
>   } elsif ($arg =~ m/\(.+\)\s*\(/) {
>   # pointer-to-function
>   $arg =~ tr/#/,/;
> - $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
> + $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
>   $param = $1;
>   $type = $arg;
>   $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> -- 

...meanwhile, I have applied this one, thanks.

jon

Re: [PATCH] doc: use KCFLAGS instead of EXTRA_CFLAGS to pass flags from command line

[Jonathan Corbet]

Masahiro Yamada  writes:

> You should use KCFLAGS to pass additional compiler flags from the
> command line. Using EXTRA_CFLAGS is wrong.
>
> EXTRA_CFLAGS is supposed to specify flags applied only to the current
> Makefile (and now deprecated in favor of ccflags-y).
>
> It is still used in arch/mips/kvm/Makefile (and possibly in external
> modules too). Passing EXTRA_CFLAGS from the command line overwrites
> it and breaks the build.
>
> I also fixed drivers/gpu/drm/tilcdc/Makefile because commit 816175dd1fd7
> ("drivers/gpu/drm/tilcdc: Makefile, only -Werror when no -W* in
> EXTRA_CFLAGS") was based on the same misunderstanding.
>
> Signed-off-by: Masahiro Yamada 
> ---
>
>  Documentation/process/4.Coding.rst| 2 +-
>  Documentation/process/submit-checklist.rst| 2 +-
>  Documentation/translations/it_IT/process/4.Coding.rst | 2 +-
>  Documentation/translations/it_IT/process/submit-checklist.rst | 2 +-
>  Documentation/translations/zh_CN/process/4.Coding.rst | 2 +-
>  drivers/gpu/drm/tilcdc/Makefile   | 2 +-
>  6 files changed, 6 insertions(+), 6 deletions(-)

I've applied this, fixing the conflict with submit-checklist.rst in the
process.

Thanks,

jon

Re: [PATCH -next] Documentation: proc.rst: add more about the 6 fields in loadavg

[Jonathan Corbet]

Randy Dunlap  writes:

> Address Jon's feedback on the previous patch by adding info about
> field separators in the /proc/loadavg file.
>
> Signed-off-by: Randy Dunlap 
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
> ---
>  Documentation/filesystems/proc.rst |4 
>  1 file changed, 4 insertions(+)
>
> --- linux-next-20210219.orig/Documentation/filesystems/proc.rst
> +++ linux-next-20210219/Documentation/filesystems/proc.rst
> @@ -691,6 +691,10 @@ files are there, and which are missing.
>  number of processes currently runnable (running or on ready 
> queue);
>  total number of processes in system;
>  last pid created.
> +All fields are separated by one space except "number of
> +processes currently runnable" and "total number of processes
> +in system", which are separated by a slash ('/'). Example:
> +  0.61 0.61 0.55 3/828 22084
>   locksKernel locks

Applied, thanks.

jon