Re: [RFC] docs: add a reset controller chapter to the driver API docs

[Jonathan Corbet]

On Tue, 22 Oct 2019 18:45:47 +0200
Philipp Zabel  wrote:

> Add initial reset controller API documentation. This is mostly indented
> to describe the concepts to users of the consumer API, and to tie the
> kerneldoc comments we already have into the driver API documentation.
> 
> Signed-off-by: Philipp Zabel 

One quick comment...

>  Documentation/driver-api/index.rst |   1 +
>  Documentation/driver-api/reset.rst | 217 +
>  2 files changed, 218 insertions(+)
>  create mode 100644 Documentation/driver-api/reset.rst
> 

[...]

> +Shared and exclusive resets
> +---
> +
> +The reset controller API provides either reference counted deassertion and
> +assertion or direct, exclusive control.
> +The distinction between shared and exclusive reset controls is made at the 
> time
> +the reset control is requested, either via 
> :c:func:`devm_reset_control_get_shared`
> +or via :c:func:`devm_reset_control_get_exclusive`.

:c:func: isn't needed anymore, and is actively discouraged - the function
references will be linked anyway.  So just say function() rather than
:c:func:`function` everywhere, please.

Thanks,

jon

Re: [PATCH] docs/core-api: memory-allocation: mention size helpers

[Jonathan Corbet]

On Tue, 22 Oct 2019 20:05:38 +
Chris Packham  wrote:

> > Quick comment: we don't need :c:func: anymore; the markup happens anyway.
> > So rather than adding more of them, could I ask you to please take out the
> > ones that are there now?  
> 
> So just with backquotes i.e. :c:func:`kmalloc` becomes `kmalloc`?

No, just:

kmalloc()

will do the trick.  See:


https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#the-c-domain

Thanks,

jon

Re: [PATCH v7 3/5] mm/hugetlb_vmemmap: move comment block to Documentation/vm

[Jonathan Corbet]

Joao Martins  writes:

> In preparation for device-dax for using hugetlbfs compound page tail
> deduplication technique, move the comment block explanation into a
> common place in Documentation/vm.
>
> Cc: Muchun Song 
> Cc: Mike Kravetz 
> Suggested-by: Dan Williams 
> Signed-off-by: Joao Martins 
> Reviewed-by: Muchun Song 
> Reviewed-by: Dan Williams 
> ---
>  Documentation/vm/index.rst |   1 +
>  Documentation/vm/vmemmap_dedup.rst | 175 +
>  mm/hugetlb_vmemmap.c   | 168 +--
>  3 files changed, 177 insertions(+), 167 deletions(-)
>  create mode 100644 Documentation/vm/vmemmap_dedup.rst

Thanks for remembering to add this to the index.rst file!  That said, I
get the impression you didn't actually build the docs afterward and look
at the result; there are a number of things here that won't render the
way you might like.

> diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst
> index 44365c4574a3..2fb612bb72c9 100644
> --- a/Documentation/vm/index.rst
> +++ b/Documentation/vm/index.rst
> @@ -37,5 +37,6 @@ algorithms.  If you are looking for advice on simply 
> allocating memory, see the
> transhuge
> unevictable-lru
> vmalloced-kernel-stacks
> +   vmemmap_dedup
> z3fold
> zsmalloc
> diff --git a/Documentation/vm/vmemmap_dedup.rst 
> b/Documentation/vm/vmemmap_dedup.rst
> new file mode 100644
> index ..8143b2ce414d
> --- /dev/null
> +++ b/Documentation/vm/vmemmap_dedup.rst
> @@ -0,0 +1,175 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _vmemmap_dedup:

This label isn't needed, I'd take it out.

> +==
> +Free some vmemmap pages of HugeTLB
> +==
> +
> +The struct page structures (page structs) are used to describe a physical
> +page frame. By default, there is a one-to-one mapping from a page frame to
> +it's corresponding page struct.
> +
> +HugeTLB pages consist of multiple base page size pages and is supported by
> +many architectures. See hugetlbpage.rst in the Documentation directory for
> +more details. On the x86-64 architecture, HugeTLB pages of size 2MB and 1GB
> +are currently supported. Since the base page size on x86 is 4KB, a 2MB
> +HugeTLB page consists of 512 base pages and a 1GB HugeTLB page consists of
> +4096 base pages. For each base page, there is a corresponding page struct.
> +
> +Within the HugeTLB subsystem, only the first 4 page structs are used to
> +contain unique information about a HugeTLB page. __NR_USED_SUBPAGE provides
> +this upper limit. The only 'useful' information in the remaining page structs
> +is the compound_head field, and this field is the same for all tail pages.
> +
> +By removing redundant page structs for HugeTLB pages, memory can be returned
> +to the buddy allocator for other uses.
> +
> +Different architectures support different HugeTLB pages. For example, the
> +following table is the HugeTLB page size supported by x86 and arm64
> +architectures. Because arm64 supports 4k, 16k, and 64k base pages and
> +supports contiguous entries, so it supports many kinds of sizes of HugeTLB
> +page.
> +
> ++--+---+---+
> +| Architecture | Page Size |HugeTLB Page Size  |
> ++--+---+---+---+---+---+
> +|x86-64|4KB|2MB|1GB|   |   |
> ++--+---+---+---+---+---+
> +|  |4KB|   64KB|2MB|32MB   |1GB|
> +|  +---+---+---+---+---+
> +|arm64 |   16KB|2MB|   32MB| 1GB   |   |
> +|  +---+---+---+---+---+
> +|  |   64KB|2MB|  512MB|16GB   |   |
> ++--+---+---+---+---+---+
> +
> +When the system boot up, every HugeTLB page has more than one struct page
> +structs which size is (unit: pages):
> +
> +   struct_size = HugeTLB_Size / PAGE_SIZE * sizeof(struct page) / PAGE_SIZE

This, for example, needs to be in a literal block or you won't get what
you expect; that's true of all of the code samples and ascii-art
sections.  Easiest way to do that is to end the preceding text line with
:: instead of :

Thanks,

jon

Re: [PATCH v7 3/5] mm/hugetlb_vmemmap: move comment block to Documentation/vm

[Jonathan Corbet]

Joao Martins  writes:

>>> +HugeTLB pages consist of multiple base page size pages and is supported by
>>> +many architectures. See hugetlbpage.rst in the Documentation directory for
>
> While at it, I'll replace hugetlbpage.rst in the Documentation directory to 
> be:
>
> See :ref:`Documentation/vm/hugetlbpage.rst ` for more details.

You can make that just:

See Documentation/vm/hugetlbpage.rst for more details

...and the Right Thing will happen.

Otherwise looks good.

Thanks,

jon

Re: [PATCH] docs: move riscv under arch

[Jonathan Corbet]

Conor Dooley  writes:

> On Thu, Sep 28, 2023 at 01:29:42PM +0300, Costa Shulyupin wrote:
>> and fix all in-tree references.
>> 
>> Architecture-specific documentation is being moved into Documentation/arch/
>> as a way of cleaning up the top-level documentation directory and making
>> the docs hierarchy more closely match the source hierarchy.
>> 
>> Signed-off-by: Costa Shulyupin 
>
> This doesn't apply to riscv/for-next or next/master, with git
> complaining about the sha1 being lacking or useless. What does this
> actually apply to?

docs-next, I would guess (though I haven't had a chance to try it).  If
you would like to carry this through the riscv tree (which is probably
the most sensible option), I suspect Costa could be talked into
respinning it...?

Thanks,

jon

Re: [PATCH] docs: move riscv under arch

[Jonathan Corbet]

Conor Dooley  writes:

> On Sat, Sep 30, 2023 at 08:26:38AM -0600, Jonathan Corbet wrote:
>> Conor Dooley  writes:
>> 
>> > On Thu, Sep 28, 2023 at 01:29:42PM +0300, Costa Shulyupin wrote:
>> >> and fix all in-tree references.
>> >> 
>> >> Architecture-specific documentation is being moved into 
>> >> Documentation/arch/
>> >> as a way of cleaning up the top-level documentation directory and making
>> >> the docs hierarchy more closely match the source hierarchy.
>> >> 
>> >> Signed-off-by: Costa Shulyupin 
>> >
>> > This doesn't apply to riscv/for-next or next/master, with git
>> > complaining about the sha1 being lacking or useless. What does this
>> > actually apply to?
>> 
>> docs-next, I would guess (though I haven't had a chance to try it).
>
> I'm far from the world's best git-er, but doesn't the lacking or useless
> report from git while trying to apply the patches mean that this patch
> depended on commit that is not in next/master (which I assume includes
> docs-next).

It just means there's a divergence somewhere.  One tree has a patch that
the other lacks, and that creates a conflict making the whole thing
fail.  Business as usual...

jon

Re: [PATCH] docs: submitting-patches: Suggest a longer expected time for responses

[Jonathan Corbet]

Mark Brown  writes:

> While some subsystems do typically have very fast turnaround times on
> review this is far from standard over the kernel and is likely to set
> unrealistic expectations for submitters.  Tell submitters to expect 2-3
> weeks instead, this will cover more of the kernel.
>
> Signed-off-by: Mark Brown 
> ---
>  Documentation/process/submitting-patches.rst | 8 
>  1 file changed, 4 insertions(+), 4 deletions(-)

I was hoping to see some more comments on this; it is a fairly
significant change in the expectations we put on our reviewers.  Oh
well, I've applied it.  I wonder if we should add a note saying to look
at the maintainer profile for the subsystem in question for more
specific guidance?  Of course, it would be good to have more of those...

Thanks,

jon

Re: [PATCH] docs: submitting-patches: Introduce Test: tag

[Jonathan Corbet]

Konrad Dybcio  writes:

> Currently, we blindly trust the submitters that they both compiled their
> code at all, tested it on a relevant device, and have done so in a manner
> that made sense for a given changeset.
>
> If at least two of these three things were always true, the review
> workflow would be much more exciting.
>
> Introduce a new Test: tag to help submitters express the way the patch
> was tested, making it easier to understand for reviewers and maintainers
> whether it was tested, and if so, whether that test was sufficient.
>
> I originally found something like this on Google's Android kernel repos
> and loved the concept.
>
> Test: make htmldocs and manual examination
> Signed-off-by: Konrad Dybcio 
> ---
>  Documentation/process/submitting-patches.rst | 18 +-
>  1 file changed, 17 insertions(+), 1 deletion(-)

Do we really want to do this?  To me, it almost seems like it codifies
the idea that sending *untested* patches is OK as long as you leave out
the tag.

Others may disagree, but I don't think we need yet another tag for this.
Testing of patches before sending them should be the norm; if special
notes about testing are needed, they can go in or below the changelog,
as appropriate.

Thanks,

jon

Re: [PATCH v1] docs: move riscv under arch

[Jonathan Corbet]

Costa Shulyupin  writes:

> and fix all in-tree references.
>
> Architecture-specific documentation is being moved into Documentation/arch/
> as a way of cleaning up the top-level documentation directory and making
> the docs hierarchy more closely match the source hierarchy.
>
> Signed-off-by: Costa Shulyupin 
>

Applied, thanks.

This is the last of the arch moves!  Thanks again for helping push this
through to a conclusion.

jon

Re: [PATCH v2] docs: submitting-patches: encourage direct notifications to commenters

[Jonathan Corbet]

Thomas Weißschuh  writes:

> Commenters may not receive new versions of patches via the lists.
> Without a directed notification to them they might miss those new
> versions.
>
> This is frustrating for the patch developers as they don't receive their
> earned Reviewed-by.
> It is also frustrating for the commenters, as they might think their
> review got ignored or they have to dig up new versions from the archive
> manually.
>
> So encourage patch submitters to make sure that all commenters get
> notified also when no Reviewed-by was issued yet.
>
> Signed-off-by: Thomas Weißschuh 
> ---
> Changes in v2:
> - s/reviewer/commenter/ to avoid ambiguity (Christoph)
> - Link to v1: 
> https://lore.kernel.org/r/20230927-docs-cc-reviewer-v1-1-2af46ceb2...@weissschuh.net
> ---
>  Documentation/process/submitting-patches.rst | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/Documentation/process/submitting-patches.rst 
> b/Documentation/process/submitting-patches.rst
> index efac910e2659..3245b7b38b98 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -327,6 +327,8 @@ politely and address the problems they have pointed out.  
> When sending a next
>  version, add a ``patch changelog`` to the cover letter or to individual 
> patches
>  explaining difference against previous submission (see
>  :ref:`the_canonical_patch_format`).
> +Notify people that commented on your patch about new versions by adding them 
> to
> +the patches CC list.

Applied, thanks.

jon

Re: [PATCH] Documentation: security-bugs.rst: linux-distros relaxed their rules

[Jonathan Corbet]

Willy Tarreau  writes:

> The linux-distros list relaxed their rules to try to adapt better to
> how the Linux kernel works. Let's update the Coordination part to
> explain why and when to contact them or not to and how to avoid trouble
> in the future.
>
> Link: https://www.openwall.com/lists/oss-security/2023/09/08/4
> Cc: Greg Kroah-Hartman 
> Cc: Kees Cook 
> Cc: Solar Designer 
> Cc: Vegard Nossum 
> Acked-by: Jiri Kosina 
> Signed-off-by: Willy Tarreau 
> ---
>
> This is the final version for merging. Changes since RFC:
>   - s/BEFORE/UNTIL from Vegard
>   - improved wording from Alexander
>   - acked-by from Jiri

Greg, you've taken changes to this file in the past; do you want to grab
this one or should I pick it up?

Thanks,

jon

Re: [PATCH v3] docs: dt-bindings: add DTS Coding Style document

[Jonathan Corbet]

Krzysztof Kozlowski  writes:

> Document preferred coding style for Devicetree sources (DTS and DTSI),
> to bring consistency among all (sub)architectures and ease in reviews.

One little nit:

> diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst 
> b/Documentation/devicetree/bindings/dts-coding-style.rst
> new file mode 100644
> index ..e374bec0f555
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
> @@ -0,0 +1,194 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. _dtscodingstyle:

There is no need to put a label at the top of a document like that, I'd
just take it out.

Thanks,

jon

Re: [PATCH] Took care of some grammatical mistakes

[Jonathan Corbet]

attreyee-muk  writes:

> Respected Maintainers, 
>
> I have made some grammatical changes in the livepatch.rst file where I
> felt that the sentence would have sounded more correct and would have become 
> easy for
> beginners to understand by reading. 
> Requesting review of my proposed changes from the mainatiners. 
>
> Thank You
> Attreyee Mukherjee
>
> Signed-off-by: attreyee-muk 
> ---
>  Documentation/livepatch/livepatch.rst | 8 
>  1 file changed, 4 insertions(+), 4 deletions(-)

Your changes seem OK as far as they go.  But please read our
documentation on patch submission:

  https://docs.kernel.org/process/submitting-patches.html

..and specifically the parts about writing proper changelogs and the use
of a full name for your signoff.

Thanks,

jon

Re: [PATCH] docs: submitting-patches: improve the base commit explanation

[Jonathan Corbet]

Borislav Petkov  writes:

> From: "Borislav Petkov (AMD)" 
>
> After receiving a second patchset this week without knowing which tree
> it applies on and trying to apply it on the obvious ones and failing,
> make sure the base tree information which needs to be supplied in the
> 0th message of the patchset is spelled out more explicitly.
>
> Also, make the formulations stronger as this really is a requirement and
> not only a useful thing anymore.
>
> Signed-off-by: Borislav Petkov (AMD) 
> ---
>  Documentation/process/submitting-patches.rst | 15 +++
>  1 file changed, 11 insertions(+), 4 deletions(-)

Applied, thanks.

jon

Re: [PATCH 0/2] Minor grammatical fixup for livepatch docs

[Jonathan Corbet]

Bagas Sanjaya  writes:

> I was prompted to write this little grammar fix series when reading
> the fix from Attreyee [1], with review comments requesting changes
> to that fix. So here's my version of the fix, with reviews from [1]
> addressed (and distinct grammar fixes splitted).

How is this helpful?  Why are you trying to push aside somebody who is
working toward a first contribution to the kernel?  This is not the way
to help somebody learn to work with the kernel community.

Attreyee, I would like to encourage you to redo your patch set based on
the feedback you have received so that we can apply it.

Thanks,

jon

Re: [PATCH] docs: conf.py: Ignore __counted_by attribute

[Jonathan Corbet]

Kees Cook  writes:

> It seems that Sphinx is confused by the __counted_by attribute on struct
> members. Add it to the list of known attributes.
>
> Reported-by: kernel test robot 
> Closes: 
> https://lore.kernel.org/oe-kbuild-all/202312150614.kox8xukr-...@intel.com/
> Cc: Jonathan Corbet 
> Cc: "Gustavo A. R. Silva" 
> Cc: linux-doc@vger.kernel.org
> Cc: linux-harden...@vger.kernel.org
> Signed-off-by: Kees Cook 
> ---
>  Documentation/conf.py | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index d4fdf6a3875a..5898c74b96fb 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -106,6 +106,7 @@ if major >= 3:
>  "__weak",
>  "noinline",
>  "__fix_address",
> +"__counted_by",

Applied, thanks.

jon

Re: [PATCH] scripts: kernel-doc: Clarify missing struct member description

[Jonathan Corbet]

Kees Cook  writes:

> The output "or member" should be more specific, instead saying "struct
> member".
>
> Cc: Jonathan Corbet 
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Kees Cook 
> ---
>  scripts/kernel-doc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 39e730ee1fef..41f838042364 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1613,7 +1613,7 @@ sub push_parameter($) {
>   $parameterdescs{$param} = $undescribed;
>  
>   if (show_warnings($type, $declaration_name) && $param !~ /\./) {
> - emit_warning("${file}:$.", "Function parameter or 
> member '$param' not described in '$declaration_name'\n");
> + emit_warning("${file}:$.", "Function parameter or 
> struct member '$param' not described in '$declaration_name'\n");
>   }

Applied, thanks.

jon

Re: [PATCH] scripts: kernel-doc: Bug fixed for erroneous warning

[Jonathan Corbet]

Muhammad Muzammil  writes:

> From: Muzammil Ashraf 
>
> kernel-doc: fixed erroneous warning generated by '__counted_by'
>
> Signed-off-by: Muzammil Ashraf 
> ---
>  scripts/kernel-doc | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 1484127db104..ea9688df0e93 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1661,6 +1661,7 @@ sub check_sections($) {
>   }
>   elsif (($decl_type eq "struct") or
>  ($decl_type eq "union")) {
> +next if (index("@_", "__counted_by") != -1);
>   emit_warning("${file}:$.",
>   "Excess $decl_type member " .
>   "'$sects[$sx]' " .

Could you give an example of the warnings that this patch addresses?
I've not seen any caused by __counted_by since f600c77aeaff was applied
to docs-next.  What did it miss?

Thanks,

jon

Re: [PATCH] Documentation/livepatch: Update terminology in livepatch

[Jonathan Corbet]

attreyee-muk  writes:

> Update the sentence in livepatch.rst to: "Functions are there for a reason. 
> Take some input parameters, acquire or release locks, read, process, and 
> write some data in a defined way."
>
> Signed-off-by: Attreyee Mukherjee 
> ---
>  Documentation/livepatch/livepatch.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

So this is a classic example of saying what you have done, but not why.
What makes this a change that we want?

Also, please wrap your changelogs to a reasonable line length.

Thanks,

jon

Re: [PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Jonathan Corbet]

Steven Rostedt  writes:

> From: "Steven Rostedt (Google)" 
>
> When the buffer_percent file was added to the kernel, the documentation
> should have been updated to document what that file does.
>
> Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
> Signed-off-by: Steven Rostedt (Google) 
> ---
> Changes since v1: 
> https://lore.kernel.org/all/20231226123525.71a6d...@gandalf.local.home/
>
> - Fixed some grammar issues.
>
>  Documentation/trace/ftrace.rst | 15 +++
>  1 file changed, 15 insertions(+)

Are you planning on shipping this one upstream, or would you like me to
pick it up?

Thanks,

jon

Re: [PATCH] Docs: remove mentions of fdformat from util-linux

[Jonathan Corbet]

Thomas Weißschuh  writes:

> Since util-linux commit 13b26e3c36d1
> ("fdformat: remove command from default build")
> the fdformat tool is not built anymore by default.
> As a result it is not packaged anymore by distributions and therefore
> not usable by users.
>
> Instead mention the "mount" command as more likely to be present
> alternative.
>
> Also drop the reference to fdformat from the list of features of new
> versions of util-linux.
>
> Signed-off-by: Thomas Weißschuh 
> ---
>  Documentation/process/changes.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Amusingly, my F39 system still has fdformat...but this change makes
sense, applied, thanks.

jon

Re: [PATCH v1 1/2] docs, kprobes: Update email address of Masami Hiramatsu

[Jonathan Corbet]

Tiezhu Yang  writes:

> According to the latest authorship and Signed-off-by:
>
>   Masami Hiramatsu (Google) 
>
> Masami Hiramatsu is working at Google, so the current email @redhat.com
> is out of date, it is better to use the email @kernel.org.
>
> Signed-off-by: Tiezhu Yang 
> ---
>  Documentation/trace/kprobes.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst
> index f825970a1495..968ae080accd 100644
> --- a/Documentation/trace/kprobes.rst
> +++ b/Documentation/trace/kprobes.rst
> @@ -4,7 +4,7 @@ Kernel Probes (Kprobes)
>  
>  :Author: Jim Keniston 
>  :Author: Prasanna S Panchamukhi 
> -:Author: Masami Hiramatsu 
> +:Author: Masami Hiramatsu 

Masami, is this change OK with you?

Thanks,

jon

Re: [PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Jonathan Corbet]

Steven Rostedt  writes:

> On Wed, 03 Jan 2024 14:15:30 -0700
> Jonathan Corbet  wrote:
>
>> Steven Rostedt  writes:
>> 
>> > From: "Steven Rostedt (Google)" 
>> >
>> > When the buffer_percent file was added to the kernel, the documentation
>> > should have been updated to document what that file does.
>> >
>> > Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
>> > Signed-off-by: Steven Rostedt (Google) 
>> > ---
>> > Changes since v1: 
>> > https://lore.kernel.org/all/20231226123525.71a6d...@gandalf.local.home/
>> >
>> > - Fixed some grammar issues.
>> >
>> >  Documentation/trace/ftrace.rst | 15 +++
>> >  1 file changed, 15 insertions(+)  
>> 
>> Are you planning on shipping this one upstream, or would you like me to
>> pick it up?
>
> I was hoping you can take it, but please take v3.
>
>   https://lore.kernel.org/all/20231229122402.537eb...@gandalf.local.home/

Yep, will do.

Thanks,

jon

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li  writes:

> In section "18) Don't re-invent the kernel macros" in "Linux kernel
> coding style":
>
> Show how reusing macros from shared headers prevents naming collisions
> using "stringify", the one of the most widely reinvented macro, as an
> example.
>
> This patch aims to provide a stronger reason to reuse shared macros,
> by showing the risk of improvised macro variants.
>
> Signed-off-by: Yueh-Shun Li 
> ---
>  Documentation/process/coding-style.rst | 22 ++
>  1 file changed, 22 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst 
> b/Documentation/process/coding-style.rst
> index 2504cb00a961..1e79aba4b346 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of some 
> structure member, use
>  There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
>  that do strict type checking if you need them.
>  
> +Using existing macros provided by the shared headers also prevents naming
> +collisions. For example, if one developer define in ``foo.h``
> +
> +.. code-block:: c
> +
> + #define __stringify(x) __stringify_1(x)
> + #define __stringify_1(x) #x
> +
> +and another define in ``bar.h``
> +
> +.. code-block:: c
> +
> + #define stringify(x) __stringify(x)
> + #define __stringify(x) #x
> +
> +When both headers are ``#include``-d into the same file, the facilities 
> provided
> +by ``foo.h`` might be broken by ``bar.h``.
> +
> +If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` provided by
> +``include/linux/stringify.h``, they wouldn't have stepped onto each other's
> +toes.
> +

So everything we add to our documentation has a cost in terms of reader
attention.  We ask people to read through a lot of material now, and
should only increase that ask for good reason.

With that context, I have to wonder whether we really need to tell our
readers, who are supposed to be capable developers, that reuse can help
to avoid name collisions?

Thanks,

jon

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li  writes:

>> So everything we add to our documentation has a cost in terms of reader
>> attention.  We ask people to read through a lot of material now, and
>> should only increase that ask for good reason.
>> 
>> With that context, I have to wonder whether we really need to tell our
>> readers, who are supposed to be capable developers, that reuse can help
>> to avoid name collisions?
>> 
>
> The motivation comes from existing inconsistency of the "__stringify()" 
> macro
> definition between e.g. "samples/bpf/tracex5.bpf.c" and other files.
>
> I agree that increasing the length of the documentation without
> substantial benefits would not be helpful for the readers, and
> doubling the length of a section is too much for its purpose.
>
> Should I shorten it into one sentence, like
>
> ```
> On the other hand, locally-defined variants, such as ``#define 
> __stringify(x) #x``,
> could lead to naming collisions that break otherwise functioning 
> facilities.
> ```
>
> or just omit it in the next version of patches?

My own feeling (others may well disagree) is that this isn't worth
mentioning in the coding-style document.  What you *could* do is to fix
the redefinitions (if that hasn't happened yet) and make sure that the
macros in question are covered in our kernel documentation.

Thanks,

jon

Re: [PATCH] Documentation/livepatch: Update terminology in livepatch

[Jonathan Corbet]

Attreyee M  writes:

> Hello maintainers, 
>
> I wanted to ask if this patch of mine is accepted as of now. 

You never responded to the question that is still quoted in your
(unfortunately top-posted) email:

> So this is a classic example of saying what you have done, but not why.
> What makes this a change that we want?

So no, not accepted.  Even with a proper changelog, though, I'm not sure
I see the value in that particular change.

jon

Re: [PATCH v1 0/2] Update kprobes documentation

[Jonathan Corbet]

Tiezhu Yang  writes:

> This is based on 6.7-rc6.
>
> Tiezhu Yang (2):
>   docs, kprobes: Update email address of Masami Hiramatsu
>   docs, kprobes: Add loongarch as supported architecture
>
>  Documentation/trace/kprobes.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>

Series applied, thanks.

jon

Re: [PATCH] docs/zh_CN/power: Use kcalloc() instead of kzalloc()

[Jonathan Corbet]

Erick Archer  writes:

> As noted in the "Deprecated Interfaces, Language Features, Attributes,
> and Conventions" documentation [1], size calculations (especially
> multiplication) should not be performed in memory allocator (or similar)
> function arguments due to the risk of them overflowing. This could lead
> to values wrapping around and a smaller allocation being made than the
> caller was expecting. Using those allocations could lead to linear
> overflows of heap memory and other misbehaviors.
>
> So, in the example code use the purpose specific kcalloc() function
> instead of the argument size * count in the kzalloc() function.
>
> Link: 
> https://www.kernel.org/doc/html/next/process/deprecated.html#open-coded-arithmetic-in-allocator-arguments
>  [1]
> Link: https://github.com/KSPP/linux/issues/162
> Signed-off-by: Erick Archer 
> ---
>  Documentation/translations/zh_CN/power/opp.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/translations/zh_CN/power/opp.rst 
> b/Documentation/translations/zh_CN/power/opp.rst
> index 8d6e3f6f6202..7470fa2d4c43 100644
> --- a/Documentation/translations/zh_CN/power/opp.rst
> +++ b/Documentation/translations/zh_CN/power/opp.rst
> @@ -274,7 +274,7 @@ dev_pm_opp_get_opp_count
>{
>   /* 做一些事情 */
>   num_available = dev_pm_opp_get_opp_count(dev);
> - speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
> + speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);

Without addressing the validity of this change, as Hu says, we should
never change the translations without fixing the original as well -
otherwise they aren't really translations anymore.

Thanks,

jon

Re: [PATCH] coding-style: Add guidance to prefer dev_dbg

[Jonathan Corbet]

Abhishek Pandit-Subedi  writes:

> During review, it was suggested that drivers only emit messages when
> something is wrong or it is a debug message. Document this as a formal
> recommendation.
>
> https://lore.kernel.org/linux-usb/2024012525-alienate-frown-916b@gregkh/
>
> Signed-off-by: Abhishek Pandit-Subedi 
> ---
> I'm sending up the change to documentation while this is still fresh.
> Will send an update to checkpatch.pl afterwards.
>
>  Documentation/process/coding-style.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/process/coding-style.rst 
> b/Documentation/process/coding-style.rst
> index c48382c6b477..f8ec23fa89bc 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -899,7 +899,8 @@ which you should use to make sure messages are matched to 
> the right device
>  and driver, and are tagged with the right level:  dev_err(), dev_warn(),
>  dev_info(), and so forth.  For messages that aren't associated with a
>  particular device,  defines pr_notice(), pr_info(),
> -pr_warn(), pr_err(), etc.
> +pr_warn(), pr_err(), etc. When drivers are working properly they are quiet,
> +so prefer to use dev_dbg/pr_debug unless something is wrong.
>  

Applied, thanks.

jon

Re: [PATCH] docs: maintainer: add existing SoC and netdev profiles

[Jonathan Corbet]

Krzysztof Kozlowski  writes:

> Extend the list of maintainer profiles with SoC and netdev.
>
> Signed-off-by: Krzysztof Kozlowski 
> ---
>  Documentation/maintainer/maintainer-entry-profile.rst | 3 +++
>  1 file changed, 3 insertions(+)

Applied, thanks.

jon

Re: [PATCH] Documentation: coding-style: Fix indentation in code-blocks

[Jonathan Corbet]

Thorsten Blum  writes:

> - Remove spaces in C code-blocks to align error labels consistently
> - Replace tab characters with spaces in emacs-lisp code blocks
>
> Signed-off-by: Thorsten Blum 
> ---
>  Documentation/process/coding-style.rst| 6 +++---
>  Documentation/translations/it_IT/process/coding-style.rst | 6 +++---
>  Documentation/translations/sp_SP/process/coding-style.rst | 6 +++---
>  Documentation/translations/zh_CN/process/coding-style.rst | 4 ++--
>  Documentation/translations/zh_TW/process/coding-style.rst | 4 ++--
>  5 files changed, 13 insertions(+), 13 deletions(-)

I have applied this, but I would really rather not see a lot of
white-space patches like this; there are so many ways in which our
documentation could use improvement, and this is pretty far down the
list.

Thanks,

jon

Re: [PATCH] Documentation: coding-style: Update syntax highlighting for code-blocks

[Jonathan Corbet]

Thorsten Blum  writes:

> Use c and elisp instead of none in code-blocks
>
> Signed-off-by: Thorsten Blum 
> ---
>  Documentation/process/coding-style.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/process/coding-style.rst 
> b/Documentation/process/coding-style.rst
> index c48382c6b477..a75c7044d8b7 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -203,7 +203,7 @@ Do not unnecessarily use braces where a single statement 
> will do.
>  
>  and
>  
> -.. code-block:: none
> +.. code-block:: c
>  
>   if (condition)
>   do_this();
> @@ -660,7 +660,7 @@ make a good program).
>  So, you can either get rid of GNU emacs, or change it to use saner
>  values.  To do the latter, you can stick the following in your .emacs file:
>  
> -.. code-block:: none
> +.. code-block:: elisp

Applied, thanks.

jon

Re: [PATCH v2] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Jonathan Corbet]

Thorsten Blum  writes:

> sphinx.rst:
> - Remove unnecessary newline
> - Fix grammar s/on/in/
> - Fix grammar s/check/checks/
> - Capitalize heading "The C domain"
>
> changes.rst:
> - Remove colon after "pahole" to be consistent with other entries
>
> howto.rst:
> - Fix grammar s/you will/will you/
> - Hyphenate "real-world problems"
>
> Signed-off-by: Thorsten Blum 
> Reviewed-by: Randy Dunlap 
> Reviewed-by: Bagas Sanjaya 
> ---
> Changes in v2:
> - Preserve Reviewed-by: tags
> - s/on/in/ in sphinx.rst as suggested by Matthew Wilcox 
> ---
>  Documentation/doc-guide/sphinx.rst | 7 +++
>  Documentation/process/changes.rst  | 4 ++--
>  Documentation/process/howto.rst| 4 ++--
>  3 files changed, 7 insertions(+), 8 deletions(-)

Applied, thanks.

jon

Re: [PATCH] docs: staging: fix typo in docs

[Jonathan Corbet]

Vincenzo Mezzela  writes:

So your fix is fine, but I need to point out a couple of things with the
changelog.

> This patch resolves a spelling error in the documentation found
> with codespell.

If you look at Documentation/process/submitting-patches.rst, you'll see
that changelog text should be phrased in the imperative mode; no "this
patch".  I tend not to be too fussy about that, but some maintainers
will reject a patch out of hand for that, so it's a good thing to learn
to avoid.

> It is submitted as part of my application to the "Linux Kernel Bug
> Fixing Spring Unpaid 2024" mentorship program of the Linux Kernel
> Foundation.

This is interesting (I'd never heard of the Linux Kernel Foundation),
but it's not really relevant for the kernel development history.  If you
want to put this kind of information in a submission, put it after the
"---" line so that it doesn't end up being committed with the patch.

> Signed-off-by: Vincenzo Mezzela 

I have gone ahead and fixed up these things and applied your two
patches, thanks.

jon

Re: [PATCH] Documentation: Document the Linux Kernel CVE process

[Jonathan Corbet]

Greg Kroah-Hartman  writes:

> On Tue, Feb 13, 2024 at 07:48:12PM +0100, Greg Kroah-Hartman wrote:
>> The Linux kernel project now has the ability to assign CVEs to fixed
>> issues, so document the process and how individual developers can get a
>> CVE if one is not automatically assigned for their fixes.
>> 
>> Signed-off-by: Greg Kroah-Hartman 
>> Signed-off-by: Sasha Levin 
>> Signed-off-by: Lee Jones 
>> ---
>
> Jon, if you don't have any objections, I can just take this in my tree
> for the next -rc pull request I have for Linus with other driver-core
> type stuff.

Up to you - I probably have another 6.8 pull to do as well.  Happy
either way, if you want to push it:

Acked-by: Jonathan Corbet 

Thanks,

jon

Re: [PATCH] Documentation: embargoed-hardware-issues.rst: Fix Trilok's email

[Jonathan Corbet]

Trilok Soni  writes:

> On 2/2/2024 9:06 AM, Carlos Bilbao wrote:
>> On 2/2/24 10:48, Greg KH wrote:
>>> On Fri, Feb 02, 2024 at 09:41:19AM -0700, Jeffrey Hugo wrote:
 The servers for the @codeaurora domain have long been retired and any
 messages addressed to @codeaurora will bounce.

 Trilok has an entry in .mailmap, but the raw documentation files still
 list an old @codeaurora address.  Update the address in the
 documentation files for anyone reading them.

 Signed-off-by: Jeffrey Hugo 
 ---
   Documentation/process/embargoed-hardware-issues.rst | 2 +-
   .../translations/sp_SP/process/embargoed-hardware-issues.rst    | 2 +-
   .../translations/zh_CN/process/embargoed-hardware-issues.rst    | 2 +-
   .../translations/zh_TW/process/embargoed-hardware-issues.rst    | 2 +-
   4 files changed, 4 insertions(+), 4 deletions(-)
>>>
>>> I think we need an ack from Trilok for this :)
>> 
>> Assuming ack from Trilok, regarding the Spanish documentation,
>> 
>> Reviewed-by: Carlos Bilbao 
>
> Looks good to me. Thank you.
>
> Reviewed-by: Trilok Soni  

Applied, thanks.

jon

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Jonathan Corbet]

Greg Kroah-Hartman  writes:

> On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
>> rst basically allows any order of the heading underlines, and their
>> relative hierarchy is determined by how they show up in each document,
>> it's not specified by rst. However, it would be much easier for everyone
>> if all the kernel documents followed the same style.
>
> Agreed, someone should pick a style and sweep the whole directory and
> sync them up to the agreed formatting. :)

Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :)

jon

Re: [PATCH] Documentation: update mailing list addresses

[Jonathan Corbet]

Konstantin Ryabitsev  writes:

> The mailman2 server running on lists.linuxfoundation.org will be shut
> down in very imminent future. Update all instances of obsolete list
> addresses throughout the tree with their new destinations.
>
> Signed-off-by: Konstantin Ryabitsev 
> ---
> Jon, I am sending this primarily to linux-doc, since most of the changes
> are in Documentation/* and only a handful in MAINTAINERS. I think it
> makes most sense to bubble this up via the docs subsystem.
> ---
>  Documentation/ABI/testing/sysfs-bus-vdpa   | 10 
> +-
>  Documentation/networking/bridge.rst|  2 +-
>  Documentation/process/researcher-guidelines.rst|  2 +-
>  .../translations/sp_SP/process/researcher-guidelines.rst   |  2 +-
>  MAINTAINERS|  6 +++---
>  5 files changed, 11 insertions(+), 11 deletions(-)

Applied, thanks.

jon

Re: Simple analytics for docs.kernel.org and patchwork, please?

[Jonathan Corbet]

Jakub Kicinski  writes:

> On Mon, 26 Feb 2024 14:24:39 -0500 Konstantin Ryabitsev wrote:
>> In general, my previous experience enabling libravatar on git.kernel.org has
>> taught me that many very vocal people *really* don't like to have any kind of
>> statistics gathered about them. However, if it's just for docs.kernel.org,
>> then I don't think I have specific objections.
>> 
>> That said, I would need help turning this on -- if someone can pass me along 
>> a
>> Sphinx configuration option that I can enable during build time, then I'll be
>> happy to add it to our build jobs.
>
> Excellent :)
>
> Let me CC linux-doc in case someone can tell us how to hook things in.

It's probably not just a configuration option.  I suspect that this will
need to be done either by editing the templates or with a little
extension.  Either could require adding this support to the kernel repo,
which might raise some eyebrows.

jon

Re: [PATCH] docs: submit-checklist: structure by category

[Jonathan Corbet]

Lukas Bulwahn  writes:

> While going through the submit checklist, the list order seemed rather
> random, probably just by historical coincidences of always adding yet the
> next point someone thought of at the end of the list.
>
> Structure and order them by the category of such activity,
> reviewing, documenting, checking with tools, building and testing.

So this is clearly a step in the right direction, so I'm not opposed to
it.  But I do have a couple of thoughts:

- This document is old and unloved.  Its age shows in a lot of ways
  (wmb() rather than the sorts of barriers that are socially acceptable
  in 2024, for example).  It makes no mention of the CI systems that
  should get their say for a lot of subsystems; nor does it mention the
  subsystem-specific maintainer profiles that should also be
  consulted. And so on.  It needs a lot of work rather than a
  reshuffling.  (But, as I say, the reshuffling is an improvement, so
  I'll take it).

- It's a bit of an awkward fit with submitting-patches.rst.  Someday
  we'll have a set of coherent docs, maybe.

Anyway, I'm done grumbling now...:)  I'll look forward to v2 -
preferably soon; I have travel coming up and may need to cut things off
for 6.9 a bit earlier than usual.

Thanks,

jon

Re: [PATCH v2 3/3] docs: submit-checklist: change to autonumbered lists

[Jonathan Corbet]

Akira Yokosawa  writes:

>> -1) If you use a facility then #include the file that defines/declares
>> +#. If you use a facility then #include the file that defines/declares
>> that facility.  Don't depend on other header files pulling in ones
>> that you use.
>
> Wait.  This will render the list starting from:
>
> 1. If you use ...
>
> In patch 1/1, you didn't change the ")".
>
> It was Jani who suggested "#.", but "#)" would work just fine.

So I'm a little confused.  Is the objection that it renders the number
as "1." rather than "1)"?  That doesn't seem like the biggest of deals,
somehow, but am I missing something?

A bigger complaint I might raise is that auto-numbering restarts the
enumeration in each subsection, so we have a lot of steps #1, which is a
definite change from before.

That, of course, can be fixed by giving an explicit starting number in
each subsection, partially defeating the point of the change in the
first place.

I honestly have to wonder: does this document need the enumerated list
at all?  We don't refer to the numbers anywhere, so I don't think there
is much useful information there.  How about just using regular bulleted
lists instead?

That said, I don't have strong feelings one way or the other, and can
certainly apply it as-is if that's the consensus on what we should do.

Thanks,

jon

Re: [PATCH v2 0/3] docs: submit-checklist: structure by category

[Jonathan Corbet]

Lukas Bulwahn  writes:

> Dear Jonathan,
>
> this v2 series addresses all review feedback of the patch v1 here:
>
>   
> https://lore.kernel.org/linux-doc/20240226104653.54877-1-lukas.bulw...@gmail.com/
>
> Immediate actionable review feedback was:
>
> from Jani Nikula:
>   - turn categories into subheadings
>   - use common heading adornment
>   - change to bullet or autonumbered lists
>   - propose those changes as separate additional patches
>
> from Randy Dunlap:
>   - if subheadings, drop the colons at the end.
>   - acked change to test with linux-next
>   - Stephen Rothwell requested item 1 to stay item 1.
>   - pointed out swapping the config names in the commit message.
>
> v1 -> v2:
> The commit message of patch 1/3 is improved addressing Randy's
> feedback on the commit message.
> The diff itself of patch 1/3 is unchanged.
>
> Patch 2/3 and 3/3 addresses Jani's and Randy's feedback.
>
> The extended discussion and feedback was:
>
>   - Is the checkstack script worth mentioning or can it be replaced?
>   - missing some nowadays more important points.
>   - consider getting it coherent with submitting-patches.rst
>
> I have put the extended feedback onto my todo list; for the next
> iteration on this document---after cleaning up submitting-patches and
> making the howto and submitting-patches more coherent.
>
> I followed Jani's request and created three patches, this might help
> in the next/final review---if any further review happens now.
>
> However, I do not think the kernel repository needs to be swamped with
> three patches for this 'logically one change' to a single document. So,
> I also squashed the three patches back into one patch, sent out as
> PATCH v2-squashed:
>
>   
> https://lore.kernel.org/linux-doc/20240229030146.8418-1-lukas.bulw...@gmail.com/
>
> Please either pick this patch series or just the PATCH v2-squashed as
> you see fit.
>
> Lukas Bulwahn (3):
>   docs: submit-checklist: structure by category
>   docs: submit-checklist: use subheadings
>   docs: submit-checklist: change to autonumbered lists
>
>  Documentation/process/submit-checklist.rst | 163 +++--
>  1 file changed, 88 insertions(+), 75 deletions(-)

So I've applied the first two patches, since there doesn't seem to be
any disagreement over those.  Once we figure out how we want the
autonumbering to be done, that can go in as well.

Thanks,

jon

Re: [PATCH 0/3] Towards a re-organized submitting patches

[Jonathan Corbet]

Lukas Bulwahn  writes:

> Dear Jonathan,
>
> I wanted to clean up the development-process documentation. There is
> however no easy way to break the ice here:
>
> The elephant in the room is that there is some unclear relation between
> 5.Posting.rst, 6.Followthrough.rst and submitting-patches.rst.
> (Yes, I know each document has its own history...; but let us put the
> history aside for now.)

FWIW, the objective of those two documents is quite different; one is a
high-level overview of how the development process as a whole works, the
other is a detailed guide to submitting work for consideration.

> Submitting-patches.rst contains information largely put together from
> different initial starting points and is partly outdated due to common
> workflows with git format-patch and git send-email.

You should have seen it before I thrashed it a few years back :)

> For a simple experiment, I moved the larger parts on the tags
> (signed-off-by, co-developed-by, acked-by, reported-by, etc.) into a
> separate document and then ran the numbers on submitting-patches again:
>
>   4329 submitting-patches.rst
>
> Nowt, the size of submitting-patches is actually below Posting and
> Followthrough.

I don't think we should be driven by word counts.  I do think that
moving a bunch of information on tags to its own document could make
sense.

> So, the difficult task to reach a coherent process description is to see
> some relation between these documents and then go through the editorial
> changes. I have come up with this kind of vision:
>
> Phase 1: Clean up submitting patches
>
>   Topics/Statements that can be easily cleaned up first do not get in
>   the way (at least mentally) when trying to understand the next steps.
>   
>   E.g., as an experiment I moved the details on tags into a separate
>   document.

Fine.

> Phase 2: Make submitting-patches have one clear temporal flow.
>
>   The top-level structure should basically be along the temporal order of
>   things: Prepare a patch, Post a patch, Respond to review, Send reworked
>   patches, Be patient before resending

This makes sense as well.  I wonder if splitting the document along some
of those lines might also be a good idea, with submitting-patches.rst
becoming a relatively short overview deferring details to the others.
This is one of the most important docs we have, and it's far too much
for people to engage with all at once.

> Phase 3: Merge the pieces of content from Posting and Followthrough into
> submitting patches if it adds something to that document.
>
>   When both documents roughly cover the topics of similar depth, we look
>   fine-grained into how to construct the one document that has the best
>   from both documents.
>   
> Phase 4: Remove Posting and Followthrough and simply replace it in the
> process description with submitting patches.

In broad terms, this seems like a good direction to me.

Again, let's remember the different purposes of these documents.  The
development-process document is an overall description of the process,
so it doesn't need the details.  But when you say:

> Posting will not be missed.

I don't entirely agree.  But I don't doubt it could be a fraction of
what it is now.

> So, here are some first changes to Phase 1 and Phase 2.

At a first glance, these changes seem fine.  I think I'll hold them
until after the merge window so that others can think about what you're
up to, but I suspect there will be no reason not to apply this first set
then.

Thanks for working on this material; it's some of the most important we
have and it definitely needs some attention.

jon

Re: [PATCH 0/3] Towards a re-organized submitting patches

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> On 03.03.24 17:31, Jonathan Corbet wrote:
>> Lukas Bulwahn  writes:
>>> I wanted to clean up the development-process documentation. There is
>>> however no easy way to break the ice here:
>>>
>>> The elephant in the room is that there is some unclear relation between
>>> 5.Posting.rst, 6.Followthrough.rst and submitting-patches.rst.
>>> (Yes, I know each document has its own history...; but let us put the
>>> history aside for now.)
>> 
>> FWIW, the objective of those two documents is quite different; one is a
>> high-level overview of how the development process as a whole works, the
>> other is a detailed guide to submitting work for consideration.
>
> Sorry, I'm slightly confused here, so I have to ask: which is which?
>
> Due to the "*essential*" in the headline of submitting-patches.rst and
> its "For *detailed* information on how the kernel development process
> works, see Documentation/process/development-process.rst" in the intro
> make it sounds to me like submitting-patches.rst should be the one with
> the high-level overview. But...
>
>> Again, let's remember the different purposes of these documents.  The
>> development-process document is an overall description of the process,
>> so it doesn't need the details.
>
> ...this makes it sounds like you consider it the other way around. And
> for me that feels the wrong, as why describe the overall process in
> detail, but leave the most important part of the process to some other
> document?
>
> /me wonders what he is missing

The series of files starting with Documentation/process/1.Intro.rst was
meant to describe the whole of the development process to a wider
audience; I originally wrote it as a project for the Linux Foundation.
It covers far more than the business of putting up patches for
consideration - development cycles and all that.

submitting-patches.rst, instead, covers the details of getting code
considered for merging; it is intended to be read by the people actually
trying to do that work.

One document describes what the pieces of the car are and how they work
together to get you to the pub.  The other gives all of the steps for
working on the brakes without causing accidents.  They both fit as part
of a larger body of documentation, but they are definitely not the same
document.

Make sense?

jon

Re: [PATCH v2 0/2] docs: *-regressions.rst: Tweaks to the commands

[Jonathan Corbet]

Nícolas F. R. A. Prado  writes:

> A couple tweaks to the commands in the regression documentation to make
> them up-to-date and less confusing.
>
> Signed-off-by: Nícolas F. R. A. Prado 
> ---
> Changes in v2:
> - Reworded patch 1:
>   - s/collon/colon/
>   - Made title and message more straightforward
> - Link to v1: 
> https://lore.kernel.org/r/20240308-regzbot-fixes-v1-0-577a4fe16...@collabora.com
>
> ---
> Nícolas F. R. A. Prado (2):
>   docs: *-regressions.rst: Add colon to regzbot commands
>   docs: handling-regressions.rst: Update regzbot command fixed-by to fix
>
>  Documentation/admin-guide/reporting-regressions.rst |  2 +-
>  Documentation/process/handling-regressions.rst  | 12 ++--
>  2 files changed, 7 insertions(+), 7 deletions(-)

Applied, thanks.

jon

Re: [PATCH] trace doc: Minor grammatical correction

[Jonathan Corbet]

Sarat Mandava  writes:

> Use the correct relative pronoun.
>
> Signed-off-by: Sarat Mandava 
> ---
>  Documentation/trace/tracepoints.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/trace/tracepoints.rst 
> b/Documentation/trace/tracepoints.rst
> index 0cb8d9ca3d60..decabcc77b56 100644
> --- a/Documentation/trace/tracepoints.rst
> +++ b/Documentation/trace/tracepoints.rst
> @@ -27,7 +27,7 @@ the tracepoint site).
>  
>  You can put tracepoints at important locations in the code. They are
>  lightweight hooks that can pass an arbitrary number of parameters,
> -which prototypes are described in a tracepoint declaration placed in a
> +whose prototypes are described in a tracepoint declaration placed in a
>  header file.
>  

Applied, thanks.

jon

Re: [PATCH v5 1/2] Documentation: coding-style: ask function-like macros to evaluate parameters

[Jonathan Corbet]

So I'm not sure what your desired path for getting this upstream is.  I
can take it, but I'm generally quite leery of taking coding-style
changes without some serious acks on them - nobody elected me as the
arbiter of proper coding style.

A nit below

Barry Song <21cn...@gmail.com> writes:

> From: Barry Song 
>
> Recent commit 77292bb8ca69c80 ("crypto: scomp - remove memcpy if
> sg_nents is 1 and pages are lowmem") leads to warnings on xtensa
> and loongarch,
>In file included from crypto/scompress.c:12:
>include/crypto/scatterwalk.h: In function 'scatterwalk_pagedone':
>include/crypto/scatterwalk.h:76:30: warning: variable 'page' set but not 
> used [-Wunused-but-set-variable]
>   76 | struct page *page;
>  |  ^~~~
>crypto/scompress.c: In function 'scomp_acomp_comp_decomp':
>>> crypto/scompress.c:174:38: warning: unused variable 'dst_page' 
>>> [-Wunused-variable]
>  174 | struct page *dst_page = sg_page(req->dst);
>  |
>
> The reason is that flush_dcache_page() is implemented as a noop
> macro on these platforms as below,
>
>  #define flush_dcache_page(page) do { } while (0)
>
> The driver code, for itself, seems be quite innocent and placing
> maybe_unused seems pointless,
>
>  struct page *dst_page = sg_page(req->dst);
>
>  for (i = 0; i < nr_pages; i++)
>   flush_dcache_page(dst_page + i);
>
> And it should be independent of architectural implementation
> differences.
>
> Let's provide guidance on coding style for requesting parameter
> evaluation or proposing the migration to a static inline
> function.
>
> Signed-off-by: Barry Song 
> Suggested-by: Max Filippov 
> Reviewed-by: Mark Brown 
> Cc: Chris Zankel 
> Cc: Huacai Chen 
> Cc: Herbert Xu 
> Cc: Guenter Roeck 
> Cc: Stephen Rothwell 
> Cc: Andy Whitcroft 
> Cc: Dwaipayan Ray 
> Cc: Joe Perches 
> Cc: Jonathan Corbet 
> Cc: Lukas Bulwahn 
> Cc: Xining Xu 
> ---
>  Documentation/process/coding-style.rst | 16 
>  1 file changed, 16 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst 
> b/Documentation/process/coding-style.rst
> index 9c7cf7347394..791d333a57fd 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -827,6 +827,22 @@ Macros with multiple statements should be enclosed in a 
> do - while block:
>   do_this(b, c);  \
>   } while (0)
>  
> +Function-like macros with unused parameters should be replaced by static
> +inline functions to avoid the issue of unused variables:
> +
> +.. code-block:: c

I would just use the "::" notation here; the ..code-block:: just adds
noise IMO.

> + static inline void fun(struct foo *foo)
> + {
> + }
> +
> +For historical reasons, many files still use the cast to (void) to evaluate
> +parameters, but this method is not recommended:
> +
> +.. code-block:: c
> +
> + #define macrofun(foo) do { (void) (foo); } while (0)
> +

1) If you're putting in examples of something *not* to do, it's probably
better to also put in something like:

   /* don't do this */

people don't always read closely.

2) Can we say *why* it's not recommended?

Thanks,

jon

Re: [RFC PATCH v1 1/2] docs: reporting-issue: rework the detailed guide

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Rework the detailed step-by-step guide for various reasons:
>
> * Simplify the search with the help of lore.kernel.org/all/, which did
>   not exist when the text was written.
>
> * Make use of the recently added document
>   Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst,
>   which covers many steps this text partly covered way better.
>
> * The 'quickly report a stable regression to the stable team' approach
>   hardly worked out: most of the time the regression was not known yet.
>   Try a different approach using the regressions list.
>
> * Reports about stable/longterm regressions most of the time were
>   greeted with a brief reply along the lines of 'Is mainline affected as
>   well?'; this is needed to determine who is responsible, so we might as
>   well make the reporter check that before sending the report (which
>   verify-bugs-and-bisect-regressions.rst already tells them to do, too).
>
> * A lot of fine tuning after seeing what people were struggling with.

So I have read through this, and don't find anything objectionable.  I
will point out that each of those bullet items above might be better
handled in a separate patch; the result might be easier to review.

Thanks,

jon

Re: [RFC PATCH v1 2/2] docs: reporting-issue: rework the TLDR

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> Rework the TLDR (aka the short guide) for various reasons:
>
> * People had to read it entirely and then act upon what they learned,
>   which from feedback I got was apparently somewhat hard and confusing
>   given everything we expect from bug reporters; this partly was because
>   the first paragraph covered a special case (regression in
>   stable/longterm kernel) and not the main aspect most people cared
>   about when they came to the document.
>
>   Use a step-by-step approach to avoid this.
>
> * Make use of
>   Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
>
> * The 'quickly report a stable regression to the stable team' approach
>   hardly worked out: most of the time the regression was not known yet.
>   Try a different approach using the regressions list.
>
> * Reports about stable/longterm regressions most of the time were
>   greeted with a brief reply along the lines of 'Is mainline affected as
>   well?'; this is needed to determine who is responsible, so it might as
>   well make the reporter check that before sending the report (which
>   verify-bugs-and-bisect-regressions.rst already tells them to do, too).
>
> Not-signed-off-by: Thorsten Leemhuis 
> ---
>  .../admin-guide/reporting-issues.rst  | 104 +++---
>  1 file changed, 62 insertions(+), 42 deletions(-)

>From a quick read, no objections here.

jon

Re: [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word

[Jonathan Corbet]

"Linux regression tracking (Thorsten Leemhuis)"
 writes:

> On 28.03.24 20:29, Karel Balej wrote:
>> Quoting of the '"no regressions" rule' expression differs between
>> occurrences, sometimes being presented as '"no regressions rule"'. Unify
>> the quoting using the first form which seems semantically correct or is
>> at least used dominantly, albeit marginally.
>> 
>> One of the occurrences is obviously missing the 'rule' part -- add it.
>> 
>> Signed-off-by: Karel Balej 
>
> Thx for this:
>
> Reviewed-by: Thorsten Leemhuis 

I've applied this patch; part 2, it seems, is subject to further work so
I have not applied that one.

Thanks,

jon

Re: [PATCH v1 2/2] Documentation: process: Recommend to put Cc: tags after cutter '---' line

[Jonathan Corbet]

Andy Shevchenko  writes:

>> A lot of patches get sent with
>> more Cc's in the mail message than in the commit message.
>
> Note, this is the recommendation as it's stated. You can continue polluting
> the environment on your wish.

The environmental case here is ... not strong.

I, too, have my doubts about this recommendation; responding this way is
not going to change a lot of minds, IMO.

Thanks,

jon

Re: [PATCH] docs, kprobes: Add riscv as supported architecture

[Jonathan Corbet]

Ivan Orlov  writes:

> Support of kprobes and kretprobes for riscv was introduced 3 years ago
> by the following change:
>
> commit c22b0bcb1dd0 ("riscv: Add kprobes supported")
>
> Add riscv to the list of supported architectures.
>
> Signed-off-by: Ivan Orlov 
> ---
>  Documentation/trace/kprobes.rst | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst
> index e1636e579c9c..5e606730cec6 100644
> --- a/Documentation/trace/kprobes.rst
> +++ b/Documentation/trace/kprobes.rst
> @@ -322,6 +322,7 @@ architectures:
>  - s390
>  - parisc
>  - loongarch
> +- riscv
>  
Applied, thanks.

jon

Re: [PATCH v2 0/5] docs: stable-kernel-rules: fine-tuning and 'no stable backport' tag

[Jonathan Corbet]

Thorsten Leemhuis  writes:

> After a recent discussion regarding "do we need a 'nobackport' tag" I
> set out to create one change for stable-kernel-rules.rst. This is now
> the last patch in the series, which links to that discussion with
> all the details; the other stuff is fine-tuning that happened along the
> way.

I've applied the set, thanks.

jon

Re: [PATCH] docs: stable-kernel-rules: fix typo sent->send

[Jonathan Corbet]

"Bird, Tim"  writes:

> Change 'sent' to 'send'
>
> Signed-off-by: Tim Bird 
> ---
>  Documentation/process/stable-kernel-rules.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/process/stable-kernel-rules.rst 
> b/Documentation/process/stable-kernel-rules.rst
> index 1704f1c686d0..3178bef6fca3 100644
> --- a/Documentation/process/stable-kernel-rules.rst
> +++ b/Documentation/process/stable-kernel-rules.rst
> @@ -78,7 +78,7 @@ in the sign-off area. Once the patch is mainlined it will 
> be applied to the
>  stable tree without anything else needing to be done by the author or
>  subsystem maintainer.
>  
> -To sent additional instructions to the stable team, use a shell-style inline
> +To send additional instructions to the stable team, use a shell-style inline
>  comment:

Applied, thanks.

jon

Re: [PATCH] Documentation: tracing: Fix spelling mistakes

[Jonathan Corbet]

Saurav Shah  writes:

> Fix spelling mistakes in the documentation.
>
> Signed-off-by: Saurav Shah 
> ---
>  Documentation/trace/fprobetrace.rst | 4 ++--
>  Documentation/trace/ftrace.rst  | 2 +-
>  Documentation/trace/kprobetrace.rst | 2 +-
>  3 files changed, 4 insertions(+), 4 deletions(-)

Applied, thanks.

jon

Re: [PATCH v3] Documentation: cve Korean translation

[Jonathan Corbet]

ysk...@gmail.com writes:

> From: Yunseong Kim 
>
> This is a Documentation/process/cve korean version.

Thank you for working to improve our documentation.  A couple of
questions, though:

> Reviewed-by: Jinwoo Park 
> Signed-off-by: Yunseong Kim 

1) Why do I have three versions of it in my mailbox, sent over a period
   of 13 minutes?  What changed between the versions?

   Normally, you want to wait for reviews to come in on one version
   before posting the next, and you should put a comment after the "---"
   line saying what changed.

2) When did this review from Jinwoo Park happen?  I was not copied on
   that.

Thanks,

jon

Re: [PATCH v3] Documentation: cve Korean translation

[Jonathan Corbet]

Yunseong Kim  writes:

>> 1) Why do I have three versions of it in my mailbox, sent over a period
>>of 13 minutes?  What changed between the versions?
>
> Sorry, I forgot the name of the reviewer when I first sent the
> documentation content related patch version 2.

Which is fine, but...

>>Normally, you want to wait for reviews to come in on one version
>>before posting the next, and you should put a comment after the "---"
>>line saying what changed.
>> 
>> 2) When did this review from Jinwoo Park happen?  I was not copied on
>>that.

You did not answer this question.  Reviews should generally be done in
public, but that does not seem to have happened here?

Thanks,

jon

Re: [PATCH v3] Documentation: cve Korean translation

[Jonathan Corbet]

Yunseong Kim  writes:

> On 5/27/24 10:50 오후, Jonathan Corbet wrote:
>> Yunseong Kim  writes:
>> 
>>>> 1) Why do I have three versions of it in my mailbox, sent over a period
>>>>of 13 minutes?  What changed between the versions?
>>>
>>> Sorry, I forgot the name of the reviewer when I first sent the
>>> documentation content related patch version 2.
>> 
>> Which is fine, but...
>> 
>>>>Normally, you want to wait for reviews to come in on one version
>>>>before posting the next, and you should put a comment after the "---"
>>>>line saying what changed.
>>>>
>>>> 2) When did this review from Jinwoo Park happen?  I was not copied on
>>>>that.
>> 
>> You did not answer this question.  Reviews should generally be done in
>> public, but that does not seem to have happened here?
>
> Oops, sorry about that, Jonathan.
>
> Jinwoo Park sent me the review below, and I've updated some of ambiguous
> words in patch version 2.
>
> https://lore.kernel.org/linux-doc/57f0d90c-4cc6-4418-ab79-6ae026d8a...@gmail.com/T/#t

It does look like the patch was reviewed, but no Reviewed-by tag was
offered.  *Never* apply a Reviewed-by tag that has not been explicitly
given to you.

Jinwoo, would you like to offer that tag for this patch?

Thanks,

jon

Re: [PATCH v1] Documentation: process: Revert "Document suitability of Proton Mail for kernel development"

[Jonathan Corbet]

Conor Dooley  writes:

> From: Conor Dooley 
>
> Revert commit 1d2ed9234c85 ("Documentation: process: Document
> suitability of Proton Mail for kernel development") as Proton disabled
> WKD for kernel.org addresses as a result of some interaction with
> Konstantin on social.kernel.org
>
> Signed-off-by: Conor Dooley 
> ---

Applied, thanks.

jon

Re: [PATCH docs-next v3] docs: handling-regressions.rst: recommend using "Closes:" tags

[Jonathan Corbet]

Karel Balej  writes:

> Update the handling-regressions guide to recommend using "Closes:" tags
> rather than "Link:" when referencing fixed reports. The latter was used
> originally but now is only recommended when the given patch only fixes
> part of the issue, as described in submitting-patches. Briefly mention
> that and also note that regzbot currently doesn't make a distinction.
>
> Also fix a typo.
>
> Acked-by: Thorsten Leemhuis 
> Signed-off-by: Karel Balej 
> ---

Applied, thanks.

jon

Re: [PATCH v5] Documentation: cve Korean translation

[Jonathan Corbet]

ysk...@gmail.com writes:

> From: Yunseong Kim 
>
> This is a Documentation/process/cve korean version.
>
> The following changes have been updated based on SeongJae Park’s feedback
> from the last v4 patch.
>
> Signed-off-by: Yunseong Kim 
> ---
>  Documentation/translations/ko_KR/index.rst|   1 +
>  .../translations/ko_KR/process/cve.rst| 107 ++
>  2 files changed, 108 insertions(+)
>  create mode 100644 Documentation/translations/ko_KR/process/cve.rst

SeongJae, are you happy with this version?

Thanks,

jon


> diff --git a/Documentation/translations/ko_KR/index.rst 
> b/Documentation/translations/ko_KR/index.rst
> index 4add6b2fe1f2..46cbaf5696f2 100644
> --- a/Documentation/translations/ko_KR/index.rst
> +++ b/Documentation/translations/ko_KR/index.rst
> @@ -13,6 +13,7 @@
>  
> howto
>  
> +   process/cve
>  
>  리눅스 커널 메모리 배리어
>  -
> diff --git a/Documentation/translations/ko_KR/process/cve.rst 
> b/Documentation/translations/ko_KR/process/cve.rst
> new file mode 100644
> index ..30f2fc0420d8
> --- /dev/null
> +++ b/Documentation/translations/ko_KR/process/cve.rst
> @@ -0,0 +1,107 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +:원문: Documentation/process/cve.rst
> +:역자: 김윤성 
> +:감수: 박진우 , 김동현 
> +
> +==
> +CVE 항목들
> +==
> +
> +공통 취약점 및 노출(CVE®) 번호는 공개적으로 발표된 보안 취약점을 식별, 정의 및
> +목록화하기 위한 명확한 방법으로 개발되었습니다. 시간이 지남에 따라 커널
> +프로젝트와 관련하여서는 그 유용성이 감소했으며, CVE 번호는 부적절한 방식과
> +부적절한 이유로 할당되는 경우가 매우 많았습니다. 이로 인하여 커널 개발
> +커뮤니티에서는 이를 기피하는 경향이 있었습니다. 그러나 커널 커뮤니티 외부의
> +개인과 회사가 CVE 및 기타 형태의 보안 식별자를 할당하라는 지속적인 압박과
> +지속적인 남용이 결합되면서 커널 커뮤니티가 이러한 할당에 대한 통제권을 가져야
> +한다는 것이 분명해졌습니다.
> +
> +Linux 커널 개발팀은 잠재적인 Linux 커널 보안 문제에 대해 CVE를 할당할 수
> +있는 권한이 있습니다. 여기서 할당은
> +:doc:`일반 Linux 커널 보안 버그 보고절차`와는
> +별개입니다.
> +
> +Linux 커널에 할당된 모든 CVE 목록은
> +https://lore.kernel.org/linux-cve-announce/ 에 있는 Linux-CVE 메일링 리스트의
> +아카이브에서 확인할 수 있습니다. 할당된 CVE에 대한 알림을 받으려면 다음 메일링
> +리스트를 `구독`_ 하세요.
> +
> +절차
> +
> +
> +일반적인 안정 릴리스 절차의 일부로, 잠재적으로 보안 문제가 될 수 있는 커널
> +변경 사항은 CVE 번호 할당 담당을 하는 개발자가 식별하여 CVE 번호를 자동으로
> +할당합니다. 이러한 할당은 linux-cve-announce 메일링 리스트에 공지사항으로
> +수시로 게시됩니다.
> +
> +리눅스 커널은 시스템의 최하단 계층에서 동작합니다. 때문에 거의 모든 버그가
> +커널 보안을 취약하게 만들 수 있습니다. 하지만 버그를 수정할 때 악용 가능성을
> +명확하게 파악하기 힘든 경우가 많습니다. 이 때문에 CVE 할당 팀은 지나치게
> +조심스러워 보일 수도 있는 방식으로 버그 수정이 확인되는 모든 버그에 CVE 번호를
> +할당합니다. 이것이 리눅스 커널 팀이 발행한 많은 수의 CVE를 설명합니다.
> +
> +사용자가 CVE를 지정해야 한다고 생각하는 특정 수정 사항을 CVE 할당 팀이 놓친
> +경우에는 로 이메일을 보내 주시면 커널 CVE 할당 팀에서 함께
> +작업할 것입니다. 이 별칭은 이미 릴리스된 커널 트리에 있는 수정 사항에 대한
> +CVE 할당 전용이므로 잠재적인 보안 문제는 이 메일 주소로 보내서는 안 됩니다.
> +수정되지 않은 보안 문제를 발견했다고 생각되면
> +:doc:`일반 Linux 커널 보안 버그 보고 절차`를 따르세요.
> +
> +Linux 커널에서 수정되지 않은 보안 이슈에 대해서는 CVE가 자동으로 할당되지
> +않으며, 수정이 제공되고 stable 커널 트리에 적용된 후에만 자동으로 할당되며,
> +기존 수정의 git 커밋 ID로 추적할 수 있습니다. 커밋으로 문제가 해결되기 전에
> +CVE를 할당받고자 하는 사람은 커널 CVE 할당 팀에 문의하여
> +예약된 식별자 항목들에서 식별자를 할당받으시기 바랍니다.
> +
> +현재 Stable/LTS 커널 팀에서 지원하지 않는 커널 버전에서 발견된 문제에 대해서는
> +CVE가 할당되지 않습니다. 현재 지원되는 커널 브랜치 목록은
> +https://kernel.org/releases.html 에서 확인할 수 있습니다.
> +
> +CVE 항목들 할당 분쟁
> +
> +
> +리눅스 커널 변경 사항에 할당된 CVE에 이의를 제기하거나 수정할 권한은 영향을
> +받는 관련 하위 시스템의 관리자에게만 있습니다. 이 원칙은 취약점 보고의 정확성
> +및 책임감을 높이기 위해 존재합니다. 하위 시스템에 대한 깊은 전문 지식과 정확한
> +이해를 가진 사람만이 보고된 취약점의 유효성과 범위를 효과적으로 판단하고
> +적절한 CVE를 지정할 수 있습니다. 지정된 권한 외의 다른 사람이 CVE를 수정 또는
> +이의를 제기하려고 시도하면 혼란, 부정확한 보고, 그리고 궁극적으로는 시스템
> +손상으로 이어질 수 있습니다.
> +
> +유효하지 않은 CVE 항목들
> +
> +
> +개별 배포판에서만 지원되는 커널 버전의 보안 문제가 발견된 경우, 또는 개별
> +배포판에서 더 이상 kernel.org에서 지원하지 않는 커널 버전을 지원하고 있는
> +경우라면, 보안 문제가 발생하는 경우에 Linux 커널 CVE 팀에서 CVE를 할당할 수
> +없습니다. 변경된 사항을 적용한 개별 Linux 배포판에 직접 요청해야 합니다.
> +
> +적극적으로 지원되고 있는 커널 버전에 대해 리눅스 커널 CVE 팀 외의 다른 그룹이
> +CVE를 할당했다면, 이 CVE는 유효하지 않습니다. CNA 수정 절차를 통해 특정
> +배포판에서 적용한 항목을 무효화할 수 있도록 커널 CVE 할당 팀에
> +이메일을 통해 알려주시기 바랍니다.
> +
> +특정 CVE의 적용 범위
> +
> +
> +리눅스 커널은 다양한 방식으로 사용될 수 있으며, 외부 사용자가 커널에 접근하는
> +방법도 여러 가지이며, 전혀 접근하지 않을 수도 있습니다. 따라서 특정 CVE의 적용
> +범위는 리눅스 사용자가 결정해야 합니다. CVE 할당 팀은 이를 판단해줄 수
> +없습니다. 특정 CVE의 적용 범위를 확인하기 위해 우리 팀에 문의하지 않기를
> +바랍니다.
> +
> +또한 소스 트리는 매우 방대하고, 각 시스템은 소스 트리의 일부분만을 사용하기
> +때문에 많은 사용자들이 할당된 CVE 중 상당 부분이 자신의 시스템과 관련이 없다는
> +사실을 인지해야 합니다.
> +
> +즉, 우리는 사용자의 사용 사례를 알지 못하며 사용자가 커널의 어떤 부분을
> +사용하는지 알 수 없으므로 특정 CVE가 사용자의 시스템과 관련이 있는지 판단할 수
> +없습니다.
> +
> +여태까지 항상 그래왔듯이, 커뮤니티 구성원들의 통합된 테스트를 거친 전체 커널
> +변경 사항을 적용하는 것이 좋습니다. 개별적인 부분만 선택하여 적용하는 것을
> +권장하지 않습니다. 또한 많은 버그의 경우 전체적인 문제 해결은 단일 변경 사항이
> +아니라 여러 수정 사항의 누적을 통해 이루어집니다. 이상적으로는 모든 문제에
> +대한 모든 수정 사항에 CVE가 할당되지만, 때로는 누락될 수도 있습니다. 따라서
> +CVE가 할당되지 않은 일부 변경 사항도 시스템에 적용하는 것이 중요할 수 있습니다.
> -- 
> 2.34.1

Re: [PATCH 3/7] Docs: Move magic-number from process to staging

[Jonathan Corbet]

SeongJae Park  writes:

> 'Other material' section on 'process/index' is for unsorted documents.
> However we also have a dedicated place for the purpose, 'staging/'.
> Move 'magic-number' from the section to 'staging/' directory.
>
> Signed-off-by: SeongJae Park 
> ---
>  Documentation/process/index.rst   | 1 -
>  Documentation/staging/index.rst   | 1 +
>  Documentation/{process => staging}/magic-number.rst   | 0
>  Documentation/translations/it_IT/process/magic-number.rst | 2 +-
>  Documentation/translations/sp_SP/process/magic-number.rst | 2 +-
>  Documentation/translations/zh_CN/process/magic-number.rst | 2 +-
>  Documentation/translations/zh_TW/process/magic-number.rst | 2 +-
>  7 files changed, 5 insertions(+), 5 deletions(-)
>  rename Documentation/{process => staging}/magic-number.rst (100%)

I'll apply this for now, but I really think that this file, which has
little to say about Git-era kernels, should just be removed.

Thanks,

jon

Re: [PATCH 7/7] Docs/process/email-clients: Document HacKerMaiL

[Jonathan Corbet]

SeongJae Park  writes:

> HacKerMaiL (hkml) [1] is a simple tool for mailing lists-based
> development workflows such as that for most Linux kernel subsystems.  It
> is actively being maintained by DAMON maintainer, and recommended for
> DAMON community[2].  Add a simple introduction of the tool on the
> email-clients document, too.
>
> [1] https://github.com/sjp38/hackermail
> [2] https://lore.kernel.org/20240621170353.bfb83c2b...@smtp.kernel.org
>
> Signed-off-by: SeongJae Park 
> ---
>  Documentation/process/email-clients.rst | 9 +
>  1 file changed, 9 insertions(+)

We should really document lei as well if we're going to do this, but I
won't try to insist on that here...:)

jon

Re: [PATCH 0/7] minor document fixups

[Jonathan Corbet]

SeongJae Park  writes:

> This patch series is for minor document fixups.  First five patches
> clean up and remove 'Other material' section of process/index in favor
> of 'staging/' and better place for docs on the section.  A patch for
> adding DAMON maintainer-profile reference on maintainers' handbook
> follows.  And then the last patch adds 'hkml' as one of available email
> tools on email-clients document.
>
> SeongJae Park (7):
>   Docs/process/index: Remove unaligned-memory-access from 'Other
> material'
>   Docs/process/index: Remove riscv/patch-acceptance from 'Other
> material' section
>   Docs: Move magic-number from process to staging
>   Docs: Move clang-format from process/ to dev-tools/
>   Docs/process/index: Remove unsorted docs section
>   Docs/maintainer/maintainer-entry-profile: add DAMON maintainer profile
>   Docs/process/email-clients: Document HacKerMaiL
>
>  .clang-format |  2 +-
>  Documentation/{process => dev-tools}/clang-format.rst |  0
>  Documentation/dev-tools/index.rst |  1 +
>  Documentation/maintainer/maintainer-entry-profile.rst |  1 +
>  Documentation/process/4.Coding.rst|  2 +-
>  Documentation/process/coding-style.rst|  2 +-
>  Documentation/process/email-clients.rst   |  9 +
>  Documentation/process/index.rst   | 11 ---
>  Documentation/staging/index.rst   |  1 +
>  Documentation/{process => staging}/magic-number.rst   |  0
>  .../translations/it_IT/process/clang-format.rst   |  2 +-
>  .../translations/it_IT/process/magic-number.rst   |  2 +-
>  .../translations/sp_SP/process/coding-style.rst   |  2 +-
>  .../translations/sp_SP/process/magic-number.rst   |  2 +-
>  Documentation/translations/zh_CN/process/4.Coding.rst |  2 +-
>  .../translations/zh_CN/process/coding-style.rst   |  2 +-
>  .../translations/zh_CN/process/magic-number.rst   |  2 +-
>  Documentation/translations/zh_TW/process/4.Coding.rst |  2 +-
>  .../translations/zh_TW/process/coding-style.rst   |  2 +-
>  .../translations/zh_TW/process/magic-number.rst   |  2 +-
>  20 files changed, 25 insertions(+), 24 deletions(-)
>  rename Documentation/{process => dev-tools}/clang-format.rst (100%)
>  rename Documentation/{process => staging}/magic-number.rst (100%)

Series applied, thanks.

jon

Re: [PATCH v2 2/2] Documentation: best practices for using Link trailers

[Jonathan Corbet]

Konstantin Ryabitsev  writes:

> On Fri, Jun 21, 2024 at 02:07:44PM GMT, Kees Cook wrote:
>> On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
>> > +   This URL should be used when referring to relevant mailing list
>> > +   topics, related patch sets, or other notable discussion threads.
>> > +   A convenient way to associate ``Link:`` trailers with the commit
>> > +   message is to use markdown-like bracketed notation, for example::
>> > ...
>> > + Link: https://lore.kernel.org/some-msgid@here # [1]
>> > + Link: https://bugzilla.example.org/bug/12345  # [2]
>> 
>> Why are we adding the extra "# " characters? The vast majority of
>> existing Link tags don't do this:
>
> That's just convention. In general, the hash separates the trailer from the
> comment:
>
> Trailer-name: actual-trailer-body # comment
>

Did we ever come to a conclusion on this?  This one character seems to
be the main source of disagreement in this series, I'm wondering if I
should just apply it and let the painting continue thereafter...?

jon

Re: [PATCH v2 0/2] Documentation: update information for mailing lists

[Jonathan Corbet]

Konstantin Ryabitsev  writes:

> There have been some important changes to the mailing lists hosted at
> kernel.org, most importantly that vger.kernel.org was migrated from
> majordomo+zmailer to mlmmj and is now being served from the unified
> mailing list platform called "subspace" [1].
>
> This series updates many links pointing at obsolete locations, but also
> makes the following changes:
>
> - drops the recommendation to use /r/ subpaths in lore.kernel.org links
> (it has been unnecessary for a number of years)
> - adds some detail on how to reference specific Link trailers from
> inside the commit message
>
> Some of these changes are the result of discussions on the ksummit
> mailing list [2].
>
> Link: https://subspace.kernel.org # [1]
> Link: 
> https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat/
>  # [2]
> Signed-off-by: Konstantin Ryabitsev 
> ---
> Changes in v2:
> - Minor wording changes to text and commit messages based on feedback.
> - Link to v1: 
> https://lore.kernel.org/r/20240618-docs-patch-msgid-link-v1-0-30555f3f5...@linuxfoundation.org
>
So I have gone ahead and applied this.  There are some important changes
here that shouldn't miss the merge window, and we can argue about the #
marking with it in-tree.

I am rather amused, though, that b4 added a few extra tag lines:

> Link: https://example.com/somewhere.html  optional-other-stuff
> Signed-off-by: Random Developer 
>  [ Fixed formatting ]
> Signed-off-by: Steven Rostedt (Google) 

I do believe I'll amend the changelog before pushing this one :)

Thanks,

jon

Re: [PATCH v2] docs: maintainer: discourage taking conversations off-list

[Jonathan Corbet]

Jakub Kicinski  writes:

> Multiple vendors seem to prefer taking discussions off list, and
> ask contributors to work with them privately rather than just send
> patches to the list. I'd imagine this is because it's hard to fit in
> time for random developers popping up with features to review into
> packed schedule. From what I've seen "work in private" usually means
> someone on the company side will be assigned to handle the interaction,
> possibly months later. In worst case, the person scheduled to help
> the contributor takes over and writes the code themselves.
> This is not how the community is supposed to work.
>
> The discussion on v1 wasn't very conclusive. I am not capable of
> distilling many of the suggestions into meaningful changes.
> I believe the paragraph works in the context of the document.
>
> FWIW the paragraph has been consulted with 2 contributors to whom
> the described situation has happened.
>
> Reviewed-by: Greg Kroah-Hartman 
> Reviewed-by: Mark Brown 
> Reviewed-by: Shuah Khan 
> Signed-off-by: Jakub Kicinski 

After pondering on this for a while, I've decided to go ahead and apply
this.  The intent is good; we can always improve the execution if
somebody has a good idea.

I do have to say that all of the "must" language in this document is a
bit off-putting and may well convince potential maintainers that they
don't actually want to play this game.

Thanks,

jon

Re: [PATCH v2] Documentation: Document user_events ioctl code

[Jonathan Corbet]

Beau Belgrave  writes:

> The user events trace subsystem uses the 0x2A/'*' code for ioctls. These
> are published via the uapi/linux/user_events.h header file.
>
> Add a line indicating user events as the owner of the 0x2A/'*' code and
> reserve the first 32 sequence numbers.
>
> Signed-off-by: Beau Belgrave 
> ---
>  V2 Changes: Reserved first 32 sequence numbers for growth.
>
>  Documentation/userspace-api/ioctl/ioctl-number.rst | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst 
> b/Documentation/userspace-api/ioctl/ioctl-number.rst
> index a141e8e65c5d..d953549f0b2b 100644
> --- a/Documentation/userspace-api/ioctl/ioctl-number.rst
> +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
> @@ -97,6 +97,8 @@ Code  Seq#Include File  
>  Comments
>  '%'   00-0F  include/uapi/linux/stm.hSystem 
> Trace Module subsystem
>   
> 
>  '&'   00-07  drivers/firewire/nosy-user.h
> +'*'   00-1F  uapi/linux/user_events.hUser 
> Events Subsystem
> + 
> 

I've applied this, thanks.

jon

Re: [PATCH v2] MAINTAINERS: add Documentation/dev-tools/ to workflows@

[Jonathan Corbet]

Jakub Kicinski  writes:

> The goal of the workflows@ mailing list was to make it easier for
> maintainers who don't use lore+lei to subscribe to topics related
> to process changes. In other words it should cover changes to Documentation
> files which most maintainers should know about. Recent changes from Kees [1]
> to provide guidelines on naming KUnit files did not fall under workflows@
> since Documentation/dev-tools/ isn't covered. The patch volume for
> dev-tools isn't huge and most of the changes are interesting. Add it.
>
> Link: https://lore.kernel.org/20240720165441.it.320-k...@kernel.org/ # [1]
> Signed-off-by: Jakub Kicinski 
> Reviewed-by: Kees Cook 
> ---
> v2:
>  - s/workloads/workflows/
> v1: https://lore.kernel.org/all/20240722142913.1709594-1-k...@kernel.org/
> ---
>  MAINTAINERS | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ec6904cbfd1f..a85234de4fd0 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -6680,6 +6680,7 @@ DOCUMENTATION PROCESS
>  M:   Jonathan Corbet 
>  L:   workfl...@vger.kernel.org
>  S:   Maintained
> +F:   Documentation/dev-tools/
>  F:   Documentation/maintainer/

Applied, thanks.

jon

Re: [PATCH 1/2] Documentation: embargoed-hardware-issues.rst: minor cleanups and fixes

[Jonathan Corbet]

Greg Kroah-Hartman  writes:

> The embargoed-hardware-issues.rst file needed a bunch of minor grammar,
> punctuation, and syntax cleanups based on feedback we have gotten over
> the past few years.  The main change here is the term "silicon" being
> used over "hardware" to differentiate between companies that make a chip
> (i.e. a CPU) and those that take the chip and put it into their system.
>
> No process changes are made here at all, only clarification for the way
> the current process works.
>
> All of these changes have been approved by a review from a large number
> of different open source legal members, representing the companies
> involved in this process.
>
> Co-developed-by: Thomas Gleixner 
> Signed-off-by: Thomas Gleixner 
> Co-developed-by: Michael Dolan 
> Signed-off-by: Michael Dolan 
> Co-developed-by: Greg Kroah-Hartman 
> Signed-off-by: Greg Kroah-Hartman 
> ---
> Jon, I can take these changes through my tree if you don't object.

They seem fine to me, no problem.  Should anybody care:

Acked-by: Jonathan Corbet 

jon

Re: [PATCH] docs: improve comment consistency in .muttrc example configuration

[Jonathan Corbet]

Jiamu Sun  writes:

> Added a space to align comment formatting; this helps improve
> consistency and visual uniformity.
>
> Signed-off-by: Jiamu Sun 
> ---
>  Documentation/process/email-clients.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/process/email-clients.rst 
> b/Documentation/process/email-clients.rst
> index dd22c46d1d02..e6b9173a1845 100644
> --- a/Documentation/process/email-clients.rst
> +++ b/Documentation/process/email-clients.rst
> @@ -216,7 +216,7 @@ Mutt is highly customizable. Here is a minimum 
> configuration to start
>  using Mutt to send patches through Gmail::
>  
># .muttrc
> -  #   IMAP 
> +  #   IMAP  
>set imap_user = 'yourusern...@gmail.com'
>set imap_pass = 'yourpassword'

Applied, thanks.

jon

Re: [PATCH] Documentation: Fix spelling mistakes

[Jonathan Corbet]

Ivan Orlov  writes:

> On 8/10/24 19:32, Amit Vadhavana wrote:
>> Corrected spelling mistakes in the documentation to improve readability.
>> 
>
> Hi Amit,
>
> Since this patch contains changes for multiple files from different 
> subsystems, it should be divided into file-specific changes (so you have 
> one patch per updated file).

Often that is the best thing to do but, honestly, in this case I think I
should just take the set through the docs tree.  I don't see much point
in making things harder.

Thanks,

jon

Re: [PATCH] Documentation: Fix spelling mistakes

[Jonathan Corbet]

Now that I have looked at these, I have a couple of comments...

Amit Vadhavana  writes:

> Corrected spelling mistakes in the documentation to improve readability.

Normal form for a changelog is to use the imperative mode; some
maintainers are insistent about that.  So "Correct spelling ... "

> Signed-off-by: Amit Vadhavana 
> ---
>  Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst | 4 ++--
>  Documentation/arch/arm64/cpu-hotplug.rst | 2 +-
>  Documentation/arch/powerpc/ultravisor.rst| 2 +-
>  Documentation/arch/riscv/vector.rst  | 2 +-
>  Documentation/arch/sparc/oradax/oracle-dax.rst   | 2 +-
>  Documentation/arch/x86/mds.rst   | 2 +-
>  Documentation/arch/x86/x86_64/fsgs.rst   | 4 ++--
>  Documentation/process/backporting.rst| 6 +++---
>  8 files changed, 12 insertions(+), 12 deletions(-)

[...]

> diff --git a/Documentation/arch/riscv/vector.rst 
> b/Documentation/arch/riscv/vector.rst
> index 75dd88a62e1d..e4a28def318a 100644
> --- a/Documentation/arch/riscv/vector.rst
> +++ b/Documentation/arch/riscv/vector.rst
> @@ -15,7 +15,7 @@ status for the use of Vector in userspace. The intended 
> usage guideline for
>  these interfaces is to give init systems a way to modify the availability of 
> V
>  for processes running under its domain. Calling these interfaces is not
>  recommended in libraries routines because libraries should not override 
> policies
> -configured from the parant process. Also, users must noted that these 
> interfaces
> +configured from the parent process. Also, users must noted that these 
> interfaces

As long as you are fixing this line, s/noted/note/

>  are not portable to non-Linux, nor non-RISC-V environments, so it is 
> discourage
>  to use in a portable code. To get the availability of V in an ELF program,
>  please read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
> diff --git a/Documentation/arch/sparc/oradax/oracle-dax.rst 
> b/Documentation/arch/sparc/oradax/oracle-dax.rst
> index d1e14d572918..54ccb35ed51d 100644
> --- a/Documentation/arch/sparc/oradax/oracle-dax.rst
> +++ b/Documentation/arch/sparc/oradax/oracle-dax.rst
> @@ -197,7 +197,7 @@ Memory Constraints
>  ==
>  
>  The DAX hardware operates only on physical addresses. Therefore, it is
> -not aware of virtual memory mappings and the discontiguities that may
> +not aware of virtual memory mappings and the discontinuities that may

Whether "discontiguities" is recognized by a spelling checker or not, I
expect that is the word that was intended by the author of this
document.  I would not change it.

>  exist in the physical memory that a virtual buffer maps to. There is
>  no I/O TLB or any scatter/gather mechanism. All buffers, whether input
>  or output, must reside in a physically contiguous region of memory.
> diff --git a/Documentation/arch/x86/mds.rst b/Documentation/arch/x86/mds.rst
> index c58c72362911..5a2e6c0ef04a 100644
> --- a/Documentation/arch/x86/mds.rst
> +++ b/Documentation/arch/x86/mds.rst
> @@ -162,7 +162,7 @@ Mitigation points
> 3. It would take a large number of these precisely-timed NMIs to mount
>an actual attack.  There's presumably not enough bandwidth.
> 4. The NMI in question occurs after a VERW, i.e. when user state is
> -  restored and most interesting data is already scrubbed. Whats left
> +  restored and most interesting data is already scrubbed. What's left
>is only the data that NMI touches, and that may or may not be of
>any interest.
>  
> diff --git a/Documentation/arch/x86/x86_64/fsgs.rst 
> b/Documentation/arch/x86/x86_64/fsgs.rst
> index 50960e09e1f6..d07e445dac5c 100644
> --- a/Documentation/arch/x86/x86_64/fsgs.rst
> +++ b/Documentation/arch/x86/x86_64/fsgs.rst
> @@ -125,7 +125,7 @@ FSGSBASE instructions enablement
>  FSGSBASE instructions compiler support
>  ^^
>  
> -GCC version 4.6.4 and newer provide instrinsics for the FSGSBASE
> +GCC version 4.6.4 and newer provide intrinsics for the FSGSBASE
>  instructions. Clang 5 supports them as well.

Note that current kernels require rather newer versions of both
compilers than this, so this information does not need to be here at
all.  If you do not want to edit at that level, though, the change is an
improvement.

Thanks,

jon

Re: [PATCH] docs: process: fix typos in Documentation/process/backporting.rst

[Jonathan Corbet]

Aryabhatta Dey  writes:

> Change 'submiting' to 'submitting', 'famliar' to 'familiar' and
> 'appared' to 'appeared'.
>
> Signed-off-by: Aryabhatta Dey 
> ---
>  Documentation/process/backporting.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)

Applied, thanks.

jon

Re: [PATCH v2] docs: submitting-patches: Advertise b4

[Jonathan Corbet]

Mark Brown  writes:

> b4 is now widely used and is quite helpful for a lot of the things that
> submitting-patches covers, let's advertise it to submitters to try to make
> their lives easier and reduce the number of procedural issues maintainers
> see.
>
> Reviewed-by: Shuah Khan 
> Signed-off-by: Mark Brown 
> ---
> Changes in v2:
> - Remove some blank lines.
> - Link to v1: 
> https://lore.kernel.org/r/20240903-documentation-b4-advert-v1-1-c89d6f5db...@kernel.org
> ---

Applied, thanks.

jon

Re: [PATCH V2] Documentation: Fix spelling mistakes

[Jonathan Corbet]

Amit Vadhavana  writes:

> Correct spelling mistakes in the documentation to improve readability.
>
> Signed-off-by: Amit Vadhavana 
> ---
> V1: https://lore.kernel.org/all/20240810183238.34481-1-av2082...@gmail.com
> V1 -> V2:
> - Write the commit description in imperative mode.
> - Fix grammer mistakes in the sentence.
> ---
>  Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst | 4 ++--
>  Documentation/arch/arm64/cpu-hotplug.rst | 2 +-
>  Documentation/arch/powerpc/ultravisor.rst| 2 +-
>  Documentation/arch/riscv/vector.rst  | 2 +-
>  Documentation/arch/x86/mds.rst   | 2 +-
>  Documentation/arch/x86/x86_64/fsgs.rst   | 4 ++--
>  Documentation/process/backporting.rst| 6 +++---
>  7 files changed, 11 insertions(+), 11 deletions(-)
>

Applied, thanks.

jon

Re: [PATCH] docs/process: fix typos

[Jonathan Corbet]

Andrew Kreimer  writes:

> Fix typos in documentation.
>
> Signed-off-by: Andrew Kreimer 
> ---
>  Documentation/process/backporting.rst| 6 +++---
>  Documentation/process/coding-style.rst   | 2 +-
>  Documentation/process/maintainer-tip.rst | 2 +-
>  3 files changed, 5 insertions(+), 5 deletions(-)

Unfortunately, this one doesn't apply; backporting.rst was already fixed
by somebody else.  Can you respin your remaining changes against current
docs-next and resubmit?

Thanks,

jon

Re: [PATCH v2] docs/process: fix typos

[Jonathan Corbet]

Andrew Kreimer  writes:

> Fix typos in documentation.
>
> Signed-off-by: Andrew Kreimer 
> ---
> Synced with docs-next as requested.
>
>  Documentation/process/coding-style.rst   | 2 +-
>  Documentation/process/maintainer-tip.rst | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)

Applied, thanks.

jon

Re: [PATCH] Documentation: usb: convert usb-help to rst

[Jonathan Corbet]

On Sat,  6 Jul 2019 01:55:19 +0700
Phong Tran  wrote:

> Add new index.rst and change usb-help.txt format
> to rst.
> 
> Signed-off-by: Phong Tran 

Thank you for working to make the kernel's documentation better.  That
said, I really don't think there is value in keeping this document.  It
hasn't been updated in any useful way in decades, contains broken links,
and the links that still work are full of obsolete information.  Honestly,
a better patch would, IMO, just delete this file.

Thanks,

jon

Re: [PATCH] docs: automarkup.py: ignore exceptions when seeking for xrefs

[Jonathan Corbet]

On Sat,  6 Jul 2019 13:28:42 -0300
Mauro Carvalho Chehab  wrote:

> When using the automarkup extension with:
>   make pdfdocs
> 
> without passing an specific book, the code will raise an exception:
> 
> File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 86, 
> in auto_markup
>   node.parent.replace(node, markup_funcs(name, app, node))
> File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 59, 
> in markup_funcs
>   'function', target, pxref, lit_text)
> File 
> "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/domains/c.py", 
> line 308, in resolve_xref
>   contnode, target)
> File 
> "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/util/nodes.py",
>  line 450, in make_refnode
>   '#' + targetid)
> File 
> "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py",
>  line 159, in get_relative_uri
>   return self.get_target_uri(to, typ)
> File 
> "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py",
>  line 152, in get_target_uri
>   raise NoUri
>   sphinx.environment.NoUri
> 
> This happens because not all references will belong to a single
> PDF/LaTeX document.

Interesting.  I'd like to understand better why the HTML builder doesn't do
this...it seems like a bug in the latex builder somehow.

> Better to just ignore those than breaking Sphinx build.
> 
> Fixes: d74b0d31ddde ("Docs: An initial automarkup extension for sphinx")
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/sphinx/automarkup.py | 9 +++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/sphinx/automarkup.py 
> b/Documentation/sphinx/automarkup.py
> index b300cf129869..dba14374f269 100644
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -55,8 +55,13 @@ def markup_funcs(docname, app, node):
>reftype = 'function',
>reftarget = target, modname = None,
>classname = None)
> -xref = cdom.resolve_xref(app.env, docname, app.builder,
> - 'function', target, pxref, lit_text)
> +
> +# When building pdf documents, this may raise a NoUri exception
> +try:
> +xref = cdom.resolve_xref(app.env, docname, app.builder,
> + 'function', target, pxref, lit_text)
> +except:
> +xref = None

So this absolutely needs to be "except sphinx.environment.NoUri".  I have
seen catch-all "except" clauses paper over or otherwise hide too many
problems over the years; I really try to avoid ever using them.

I want to look at this problem and understand it a bit better; then I'll
probably end up applying this patch with the above tweak.

Thanks,

jon

Re: [Linux-kernel-mentees] [PATCH] Documentation: filesystems: Convert jfs.txt to reStructedText format.

[Jonathan Corbet]

On Sat, 6 Jul 2019 16:22:39 -0700
Shobhit Kukreti  wrote:

> This converts the plain text documentation of jfs.txt to reStructuredText 
> format.
> Added to documentation build process and verified with make htmldocs
> 
> Signed-off-by: Shobhit Kukreti 

Thanks for working to make the kernel documentation better.  That said, I
do have a request...


> ---
>  Documentation/filesystems/index.rst |  1 +
>  Documentation/filesystems/jfs.rst   | 74 
> +
>  Documentation/filesystems/jfs.txt   | 52 --
>  3 files changed, 75 insertions(+), 52 deletions(-)
>  create mode 100644 Documentation/filesystems/jfs.rst
>  delete mode 100644 Documentation/filesystems/jfs.txt
> 
> diff --git a/Documentation/filesystems/index.rst 
> b/Documentation/filesystems/index.rst
> index 1131c34..d700330 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found 
> here.
> :maxdepth: 2
>  
> binderfs.rst
> +   jfs
> diff --git a/Documentation/filesystems/jfs.rst 
> b/Documentation/filesystems/jfs.rst
> new file mode 100644
> index 000..bfb6110
> --- /dev/null
> +++ b/Documentation/filesystems/jfs.rst
> @@ -0,0 +1,74 @@
> +===
> +IBM's Journaled File System (JFS) for Linux
> +===
> +
> +JFS Homepage:  http://jfs.sourceforge.net/
> +
> +Following Mount Options are Supported
> +
> +(*) == default
> + .. tabularcolumns:: |p{1.3cm}|p{1.3cm}|p{8.0cm}|
> +
> +.. cssclass:: longtable
> +
> +.. flat-table::   
> +  :header-rows:  0
> +  :stub-columns: 0

Please don't use flat-table unless you really need to.  It makes the
documents harder to read in plain-text form, which is something we want to
avoid whenever possible.  A simple definition list seems more appropriate
for this information.

(I should really update the documentation to discourage use of flat-table).

Note that the merge window is open, so expect me to be even slower than
usual to respond to things for the next couple of weeks.

Thanks,

jon

Re: [PATCH 1/3] Documentation: virtual: Add toctree hooks

[Jonathan Corbet]

On Sat,  6 Jul 2019 14:38:13 -0700
Luke Nowakowski-Krijger  wrote:

> From: Luke Nowakowski-Krijger 
> 
> Added toctree hooks for indexing. Hooks added only for newly added files
> or already existing files. 
> 
> The hook for the top of the tree will be added in a later patch series
> when a few more substantial changes have been added. 
> 
> Signed-off-by: Luke Nowakowski-Krijger 
> ---
>  Documentation/virtual/index.rst | 18 ++
>  Documentation/virtual/kvm/index.rst | 12 
>  2 files changed, 30 insertions(+)
>  create mode 100644 Documentation/virtual/index.rst
>  create mode 100644 Documentation/virtual/kvm/index.rst
> 
> diff --git a/Documentation/virtual/index.rst b/Documentation/virtual/index.rst
> new file mode 100644
> index ..19c9fa2266f4
> --- /dev/null
> +++ b/Documentation/virtual/index.rst
> @@ -0,0 +1,18 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===
> +Linux Virtual Documentation
> +===
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   kvm/index
> +   paravirt_ops
> +
> +.. only:: html and subproject
> +
> +   Indices
> +   ===
> +
> +   * :ref:`genindex`
> diff --git a/Documentation/virtual/kvm/index.rst 
> b/Documentation/virtual/kvm/index.rst
> new file mode 100644
> index ..ada224a511fe
> --- /dev/null
> +++ b/Documentation/virtual/kvm/index.rst
> @@ -0,0 +1,12 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===
> +KVM
> +===
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   amd-memory-encryption
> +   cpuid
> +   vcpu-requests

At this point in the patch series, the above-mentioned RST files don't
exist.  So if somebody tries to build the docs here, the build will fail.
I suspect that it's pretty rare for people to use bisection with docs
builds, but it's still proper practice to ensure that things work at every
step in your series.  So the above entries should be added in the patches
that convert the files.

Also, vcpu-requests.txt is never touched in this patch series, which
suggests that you didn't build the docs even at the end of it.

Thanks,

jon

Re: [PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Jonathan Corbet]

On Sat,  6 Jul 2019 14:38:14 -0700
Luke Nowakowski-Krijger  wrote:

> From: Luke Nowakowski-Krijger 
> 
> Convert cpuid.txt to .rst format to be parsable by sphinx. 
> 
> Change format and spacing to make function definitions and return values
> much more clear. Also added a table that is parsable by sphinx and makes
> the information much more clean. 
> 
> Signed-off-by: Luke Nowakowski-Krijger 
> ---
>  Documentation/virtual/kvm/cpuid.rst | 99 +
>  Documentation/virtual/kvm/cpuid.txt | 83 
>  2 files changed, 99 insertions(+), 83 deletions(-)
>  create mode 100644 Documentation/virtual/kvm/cpuid.rst
>  delete mode 100644 Documentation/virtual/kvm/cpuid.txt
> 
> diff --git a/Documentation/virtual/kvm/cpuid.rst 
> b/Documentation/virtual/kvm/cpuid.rst
> new file mode 100644
> index ..1a03336a500e
> --- /dev/null
> +++ b/Documentation/virtual/kvm/cpuid.rst
> @@ -0,0 +1,99 @@
> +.. SPDX-License-Identifier: GPL-2.0

Do you know that this is the appropriate license for this file?  If so, you
should say how you know that.  I appreciate that you thought to add the
SPDX line, but we have to be sure that it actually matches the intent of
the creator of this file.

> +==
> +KVM CPUID bits
> +==
> +
> +:Author: Glauber Costa , Red Hat Inc, 2010

I rather suspect that email address doesn't work these days.

> +A guest running on a kvm host, can check some of its features using
> +cpuid. This is not always guaranteed to work, since userspace can
> +mask-out some, or even all KVM-related cpuid features before launching
> +a guest.
> +
> +KVM cpuid functions are:
> +
> +function: **KVM_CPUID_SIGNATURE (0x4000)**

I wouldn't add the **markup** here, it doesn't really help.

> +
> +returns::
> + 
> +   eax = 0x4001
> +   ebx = 0x4b4d564b
> +   ecx = 0x564b4d56
> +   edx = 0x4d
> +
> +Note that this value in ebx, ecx and edx corresponds to the string 
> "KVMKVMKVM".
> +The value in eax corresponds to the maximum cpuid function present in this 
> leaf,
> +and will be updated if more functions are added in the future.
> +Note also that old hosts set eax value to 0x0. This should
> +be interpreted as if the value was 0x4001.
> +This function queries the presence of KVM cpuid leafs.
> +
> +function: **define KVM_CPUID_FEATURES (0x4001)**
> +
> +returns::
> +
> +  ebx, ecx
> +  eax = an OR'ed group of (1 << flag)
> +
> +where ``flag`` is defined as below:
> +
> ++++-+
> +| flag   | value  | meaning  
>|
> ++++=+
> +| KVM_FEATURE_CLOCKSOURCE| 0  | kvmclock available at msrs   
>|
> +||| 0x11 and 0x12
>|

You might consider using the

=== = ==
simpler table format
=== = ==

here, it might be a bit easier to read and maintain.

Thanks,

jon

Re: [PATCH v2] kbuild: get rid of misleading $(AS) from documents

[Jonathan Corbet]

On Sun,  7 Jul 2019 01:25:08 +0900
Masahiro Yamada  wrote:

> The assembler files in the kernel are *.S instead of *.s, so they must
> be preprocessed. Since 'as' of GNU binutils is not able to preprocess,
> we always use $(CC) as an assembler driver.
> 
> $(AS) is almost unused in Kbuild. As of writing, there is just one place
> that directly invokes $(AS).
> 
>   $ git grep -e '$(AS)' -e '${AS}' -e '$AS' -e '$(AS:' -e '${AS:' -- 
> :^Documentation
>   drivers/net/wan/Makefile:  AS68K = $(AS)
> 
> The documentation about *_AFLAGS* sounds like the flags were passed
> to $(AS). This is somewhat misleading.
> 
> Signed-off-by: Masahiro Yamada 
> Reviewed-by: Nathan Chancellor 

Would you like me to send this up through the docs tree?

Thanks,

jon

Re: [PATCH] Documentation: coresight: covert txt to rst

[Jonathan Corbet]

On Sat,  6 Jul 2019 03:45:12 +0700
Phong Tran  wrote:

> change the format file and adpate the text style
> 
> Signed-off-by: Phong Tran 
> ---
>  .../trace/{coresight.txt => coresight.rst} | 296 
> -
>  Documentation/trace/index.rst  |   1 +
>  2 files changed, 167 insertions(+), 130 deletions(-)
>  rename Documentation/trace/{coresight.txt => coresight.rst} (59%)
> 
> diff --git a/Documentation/trace/coresight.txt 
> b/Documentation/trace/coresight.rst
> similarity index 59%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index efbc832146e7..bea24e70cfba 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,5 +1,6 @@
> - Coresight - HW Assisted Tracing on ARM
> - ==
> +==
> +Coresight - HW Assisted Tracing on ARM
> +==
>  
> Author:   Mathieu Poirier 
> Date: September 11th, 2014
> @@ -26,7 +27,7 @@ implementation, either storing the compressed stream in a 
> memory buffer or
>  creating an interface to the outside world where data can be transferred to a
>  host without fear of filling up the onboard coresight memory buffer.
>  
> -At typical coresight system would look like this:
> +At typical coresight system would look like this::
>  
>*
>    AMBA AXI  ===||
> @@ -95,6 +96,7 @@ Acronyms and Classification
>  
>  Acronyms:
>  
> + =
>  PTM: Program Trace Macrocell
>  ETM: Embedded Trace Macrocell
>  STM: System trace Macrocell
> @@ -104,6 +106,7 @@ TPIU:Trace Port Interface Unit
>  TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router
>  TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO
>  CTI: Cross Trigger Interface
> + =

A minor nit, but since you're making a table out of this, you don't need
the colons in the first column.

>  Classification:
>  
> @@ -118,7 +121,7 @@ Misc:
>  
>  
>  Device Tree Bindings
> ---
> +
>  
>  See Documentation/devicetree/bindings/arm/coresight.txt for details.
>  
> @@ -133,57 +136,63 @@ The coresight framework provides a central point to 
> represent, configure and
>  manage coresight devices on a platform.  Any coresight compliant device can
>  register with the framework for as long as they use the right APIs:
>  
> -struct coresight_device *coresight_register(struct coresight_desc *desc);
> -void coresight_unregister(struct coresight_device *csdev);
> +.. c:function:: struct coresight_device *coresight_register(struct 
> coresight_desc *desc);
> +.. c:function:: void coresight_unregister(struct coresight_device *csdev);
>  
> -The registering function is taking a "struct coresight_device *csdev" and
> +The registering function is taking a :code:`struct coresight_device *csdev` 
> and

As a general rule, we would rather see less markup in the text files than
you are applying here.  Just present the prototypes in a literal block
here.  (Even better would be a nice kerneldoc comment in the source that
could be pulled in, but that's more work).  I wouldn't use :code: anywhere,
really. 

As well as addressing Mathieu's comments, could you pass through and cut
the markup down to the bare minimum?

Thanks,

jon

Re: [PATCH v1 1/2] Documentation/filesystems: add binderfs

[Jonathan Corbet]

On Tue, 2 Jul 2019 10:57:29 -0700
Matthew Wilcox  wrote:

> I think you added it in the wrong place.
> 
> From 8167b80c950834da09a9204b6236f238197c197b Mon Sep 17 00:00:00 2001
> From: "Matthew Wilcox (Oracle)" 
> Date: Tue, 2 Jul 2019 13:54:38 -0400
> Subject: [PATCH] docs: Move binderfs to admin-guide
> 
> The documentation is more appropriate for the administrator than for
> the internal kernel API section it is currently in.
> 
> Signed-off-by: Matthew Wilcox (Oracle) 

Fine...applied...

jon

Re: [PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Jonathan Corbet]

On Mon, 8 Jul 2019 13:15:10 -0700
Luke Nowakowski-Krijger  wrote:

> > > +:Author: Glauber Costa , Red Hat Inc, 2010  
> > 
> > I rather suspect that email address doesn't work these days.
> >   
> 
> No I guess it wont :). We would still keep this correct? 

There's nothing good that will come from keeping a broken email address
there.  You could either:

 - Just take the address out, or

 - Track Glauber down and get a newer address; you could ask him about the
   licensing while you're at it :)

Thanks,

jon

Re: [PATCH v2] docs: driver-api: generic-counter: fix file path to ABI doc

[Jonathan Corbet]

On Tue, 9 Jul 2019 20:06:33 +0900
William Breathitt Gray  wrote:

> Fixes: 09e7d4ed8991 ("docs: Add Generic Counter interface documentation")
> Signed-off-by: William Breathitt Gray 
> 
> Jonathan, would you be able to pick this up in your tree?

I can apply it, yes.  But why are you supplying an SOB for it?

Thanks,

jon

Re: [PATCH v3] Added warnings in checkpatch.pl script to :

[Jonathan Corbet]

On Tue,  9 Jul 2019 17:54:17 +0530
NitinGote  wrote:

> From: Nitin Gote 

The patch needs a proper subject line.

> 1. Deprecate strcpy() in favor of strscpy().
> 2. Deprecate strlcpy() in favor of strscpy().
> 3. Deprecate strncpy() in favor of strscpy() or strscpy_pad().
> 
> Updated strncpy() section in Documentation/process/deprecated.rst
> to cover strscpy_pad() case.
> 
> Signed-off-by: Nitin Gote 
> ---
>  Change log:
>  v1->v2
>  - For string related apis, created different %deprecated_string_api
>and these will get emitted at CHECK Level using command line option
>-f/--file to avoid bad patched from novice script users.
> 
>  v2->v3
>  - Avoided use of $check in implementation.
>  - Incorporated trivial comments.
> 
>  Documentation/process/deprecated.rst |  6 +++---
>  scripts/checkpatch.pl| 24 
>  2 files changed, 27 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/process/deprecated.rst 
> b/Documentation/process/deprecated.rst
> index 49e0f64a3427..f564de3caf76 100644
> --- a/Documentation/process/deprecated.rst
> +++ b/Documentation/process/deprecated.rst
> @@ -93,9 +93,9 @@ will be NUL terminated. This can lead to various linear 
> read overflows
>  and other misbehavior due to the missing termination. It also NUL-pads the
>  destination buffer if the source contents are shorter than the destination
>  buffer size, which may be a needless performance penalty for callers using
> -only NUL-terminated strings. The safe replacement is :c:func:`strscpy`.
> -(Users of :c:func:`strscpy` still needing NUL-padding will need an
> -explicit :c:func:`memset` added.)
> +only NUL-terminated strings. In this case, the safe replacement is
> +:c:func:`strscpy`. If, however, the destination buffer still needs
> +NUL-padding, the safe replacement is :c:func:`strscpy_pad`.

Please don't use :c:func: in anything new; just write that as strscpy()
(or whatever) and The Right Thing will happen.

(Maybe we need a checkpatch rule for that :)

Thanks,

jon

[GIT PULL] Documentation for 5.3

[Jonathan Corbet]

The following changes since commit
d1fdb6d8f6a4109a4263176c84b899076a5f8008:

  Linux 5.2-rc4 (2019-06-08 20:24:46 -0700)

are available in the Git repository at:

  git://git.lwn.net/linux.git tags/docs-5.3

for you to fetch changes up to 454f96f2b738374da4b0a703b1e2e7aed82c4486:

  docs: automarkup.py: ignore exceptions when seeking for xrefs (2019-07-08 
14:35:47 -0600)


It's been a relatively busy cycle for docs:

 - A fair pile of RST conversions, many from Mauro.  These tend to
   reach beyond Documentation/ (mostly to adjust file paths in
   comments) and create more than the usual number of simple but annoying
   merge conflicts with other trees, unfortunately. He has a lot more of
   these waiting on the wings that, I think, will go to you directly later
   on.

 - A new document on how to use merges and rebases in kernel repos, and one
   on Spectre vulnerabilities.

 - Various improvements to the build system, including automatic markup of
   function() references because some people, for reasons I will never
   understand, were of the opinion that :c:func:``function()`` is
   unattractive and not fun to type.

 - We now recommend using sphinx 1.7, but still support back to 1.4.

 - Lots of smaller improvements, warning fixes, typo fixes, etc.


André Almeida (1):
  sphinx.rst: Add note about code snippets embedded in the text

Andy Shevchenko (2):
  docs/core-api: Add string helpers API to the list
  docs/core-api: Add integer power functions to the list

Aurelien Thierry (1):
  Documentation: fix typo CLOCK_MONONOTNIC_COARSE

Bhupesh Sharma (1):
  Documentation/stackprotector: powerpc supports stack protector

Bjorn Helgaas (1):
  scripts/sphinx-pre-install: fix "dependenties" typo

Federico Vaga (2):
  doc:it_IT: fix file references
  doc:it_IT: documentation alignment

Geert Uytterhoeven (4):
  Documentation: tee: Grammar s/the its/its/
  Documentation: net: dsa: Grammar s/the its/its/
  KVM: arm/arm64: Always capitalize ITS
  doc-rst: Add missing newline at end of file

George G. Davis (1):
  treewide: trivial: fix s/poped/popped/ typo

Helen Koike (1):
  Documentation/dm-init: fix multi device example

James Morse (4):
  Documentation: x86: Contiguous cbm isn't all X86
  Documentation: x86: Remove cdpl2 unspported statement and fix 
capitalisation
  Documentation: x86: Clarify MBA takes MB as referring to mba_sc
  Documentation: x86: fix some typos

Jiunn Chang (6):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks
  doc: RCU callback locks need only _bh, not necessarily _irq

Jonathan Corbet (18):
  docs: Do not seek comments in kernel/rcu/tree_plugin.h
  docs: Fix a misdirected kerneldoc directive
  docs: Do not seek kerneldoc comments in hw-consumer.h
  docs: No structured comments in target_core_device.c
  docs: no structured comments in fs/file_table.c
  docs: No structured comments in include/linux/interconnect.h
  kernel-doc: always name missing kerneldoc sections
  docs: look for sphinx-pre-install in the source tree
  docs: Completely fix the remote build tree case
  Merge branch 'vfs' into docs-next
  Merge tag 'v5.2-rc4' into mauro
  docs: Add a document on repository management
  Docs: An initial automarkup extension for sphinx
  docs: remove :c:func: annotations from xarray.rst
  kernel-doc: Don't try to mark up function names
  docs: Note that :c:func: should no longer be used
  Add the RCU docs to the core-api manual
  Merge branch 'automarkup' into docs-next

Konstantin Khlebnikov (1):
  block: document iostat changes for disk busy time accounting

Konstantin Ryabitsev (1):
  Documentation: PGP: update for newer HW devices

Lecopzer Chen (1):
  Documentation: {u,k}probes: add tracing_on before tracing

Luca Ceresoli (1):
  docs: clk: fix struct syntax

Masanari Iida (1):
  docs: tracing: Fix typos in histogram.rst

Matthew Wilcox (Oracle) (1):
  docs: Move binderfs to admin-guide

Mauro Carvalho Chehab (59):
  docs: cdomain.py: get rid of a warning since version 1.8
  scripts/sphinx-pre-install: make activate hint smarter
  scripts/sphinx-pre-install: get rid of RHEL7 explicity check
  scripts/sphinx-pre-install: always check if version is compatible with 
build
  scripts/documentation-file-ref-check: better handle translations
  scripts/documentation-file-ref-check: exclude false-positives
  scripts/documentation-file-ref-check: improve tools ref handling
  scripts/document

Re: [PATCH v4] Added warnings in checkpatch.pl script to :

[Jonathan Corbet]

On Tue,  9 Jul 2019 21:18:06 +0530
NitinGote  wrote:

> From: Nitin Gote 
> 
> 1. Deprecate strcpy() in favor of strscpy().
> 2. Deprecate strlcpy() in favor of strscpy().
> 3. Deprecate strncpy() in favor of strscpy() or strscpy_pad().
> 
> Updated strncpy() section in Documentation/process/deprecated.rst
> to cover strscpy_pad() case.
> 
> Signed-off-by: Nitin Gote 
> ---
>  Change log:
>  v1->v2
>  - For string related apis, created different %deprecated_string_api
>and these will get emitted at CHECK Level using command line option
>-f/--file to avoid bad patched from novice script users.
> 
>  v2->v3
>  - Avoided use of $check in implementation.
>  - Incorporated trivial comments.
> 
>  v3->v4
>  - Incorporated comment by removing "c:func:"

But you ignored the comment asking for a proper subject line on the
patch.  

Also,

> -only NUL-terminated strings. The safe replacement is :c:func:`strscpy`.
> -(Users of :c:func:`strscpy` still needing NUL-padding will need an
> -explicit :c:func:`memset` added.)
> +only NUL-terminated strings. In this case, the safe replacement is
> +`strscpy()`. If, however, the destination buffer still needs NUL-padding,
> +the safe replacement is `strscpy_pad()`.

Please make those just strscpy(), not `strscpy()`.  As I said, the right
thing will happen.

Thanks,

jon

Re: [PATCH 01/12] Documentation: move architectures together

[Jonathan Corbet]

On Fri, 12 Jul 2019 10:20:07 +0800
Alex Shi  wrote:

> There are many different archs in Documentation/ dir, it's better to
> move them together in 'Documentation/arch' which follows from kernel source.

So this seems certain to collide badly with Mauro's RST-conversion monster
patch set.

More to the point, though...if we are going to thrash up things this
badly, we want to be sure that we're doing it right so we don't end up
renaming everything again.  Grouping stuff into a new arch/ subdirectory
adds a bit of order, but it doesn't do much toward trying to organize our
documentation for its readers, and it doesn't help us to modernize the
docs and get rid of the old, useless stuff.  A quick check shows that many
of these files have seen no changes other than typo fixes since the
beginning of the Git era.

So, in my mind, this needs some thought.  Maybe we want a
Documentation/arch in the end, but I'm not convinced that we should just
create it and fill it with a snow shovel.  This might be a good thing to
discuss at the kernel summit in September.

Thanks,

jon

Re: [PATCH 5/5] docs: conf.py: add CJK package needed by translations

[Jonathan Corbet]

On Tue,  9 Jul 2019 15:33:23 -0300
Mauro Carvalho Chehab  wrote:

> In order to be able to output Asian symbols with XeLaTeX, we
> need the xeCJK package, and a default font for CJK symbols.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/conf.py | 4 
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 191bd380c523..e0e1f087d351 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -277,6 +277,10 @@ latex_elements = {
>  \\setromanfont{DejaVu Serif}
>  \\setmonofont{DejaVu Sans Mono}
>  
> + % This is needed for translations
> +\\usepackage{xeCJK}
> +\\setCJKmainfont{Noto Sans CJK SC}
> +
>   '''
>  }

Should there be a change to sphinx-pre-install as well so we don't send
people down the "which of 5,000 packages do I need now?" rathole?

jon

Re: [PATCH 0/5] PDF output fixes

[Jonathan Corbet]

On Tue,  9 Jul 2019 15:33:18 -0300
Mauro Carvalho Chehab  wrote:

> In order to be able to build all PDF books, besides the two patches I
> already sent:
> 
> docs: pdf: add all Documentation/*/index.rst to PDF output
> docs: automarkup.py: ignore exceptions when seeking for xrefs
> 
> A few others are needed:
> 
> - patch 1 removes nested tables for a few files I converted, as 
>   Sphinx LaTeX builder doesn't support it;
> - Patches 2 to 4 addresses some minor issues on some books,
>   usually requiring some blank lines, extra whitespaces or some
>   tag replacement;
> - Patch 5 is required in order to be able to build the translations
>   PDF book, as it adds Asian fonts support to XeLaTeX.

So, modulo my one comment on the last patch the series seems OK, though I
don't like having to work around limitations in PDF generation this way.
Can't you just make rst2pdf work instead? :)

I guess it makes sense for these to go with the big band-aid-removal patch
set.

Thanks,

jon

P.S. it seems that rst2pdf is actually being developed again:
https://akrabat.com/rst2pdf-back-from-the-dead/ .  I wonder how far
they'll get with it.

Re: [PATCH 1/2] doc:it_IT: align translation to mainline

[Jonathan Corbet]

On Thu, 18 Jul 2019 09:47:24 +0200
Federico Vaga  wrote:

> The patch translates the following patches in Italian:
> 
> d9d7c0c497b8 docs: Note that :c:func: should no longer be used
> 83e8b971f81c sphinx.rst: Add note about code snippets embedded in the text
> cca5e0b8a430 Documentation: PGP: update for newer HW devices
> 
> Signed-off-by: Federico Vaga 

Applied (and the second one as well), thanks.

jon

Re: [PATCH] docs/vm: transhuge: fix typo in madvise reference

[Jonathan Corbet]

On Tue, 16 Jul 2019 10:49:08 -0400
Jeremy Cline  wrote:

> Fix an off-by-one typo in the transparent huge pages admin
> documentation.
> 
> Signed-off-by: Jeremy Cline 

Applied, thanks.

jon

Re: [PATCH] Documentation: filesystem: fix "Removed Sysctls" table

[Jonathan Corbet]

On Tue, 23 Jul 2019 12:48:13 +0100
Sheriff Esseson  wrote:

> the "Removed Sysctls" section is a table - bring it alive with ReST.
> 
> Signed-off-by: Sheriff Esseson 

So this appears to be identical to the patch you sent three days ago; is
there a reason why you are sending it again now?

Thanks,

jon

Re: [PATCH] Documentation: move Documentation/virtual to Documentation/virt

[Jonathan Corbet]

On Wed, 24 Jul 2019 10:51:36 +0200
Paolo Bonzini  wrote:

> On 24/07/19 09:24, Christoph Hellwig wrote:
> > Renaming docs seems to be en vogue at the moment, so fix on of the
> > grossly misnamed directories.  We usually never use "virtual" as
> > a shortcut for virtualization in the kernel, but always virt,
> > as seen in the virt/ top-level directory.  Fix up the documentation
> > to match that.
> > 
> > Fixes: ed16648eb5b8 ("Move kvm, uml, and lguest subdirectories under a 
> > common "virtual" directory, I.E:")
> > Signed-off-by: Christoph Hellwig   
> 
> Queued, thanks.  I can't count how many times I said "I really should
> rename that directory".

...and it's up to Linus before I even got a chance to look at it - one has
to be fast around here...:)

There's nothing wrong with this move, but it does miss the point of much
of the reorganization that has been going on in the docs tree.  It's not
just a matter of getting more pleasing names; the real idea is to create a
better, more reader-focused organization on kernel documentation as a
whole.  Documentation/virt still has the sort of confusion of audiences
that we're trying to fix:

 - kvm/api.txt pretty clearly belongs in the userspace-api book, rather
   than tossed in with:

 - kvm/review-checklist.txt, which belongs in the subsystem guide, if only
   we'd gotten around to creating it yet, or

 - kvm/mmu.txt, which is information for kernel developers, or

 - uml/UserModeLinux-HOWTO.txt, which belongs in the admin guide.

I suspect that organization is going to be one of the main issues to talk
about in Lisbon.  Meanwhile, I hope that this rename won't preclude
organizational work in the future.

Thanks,

jon

Re: [PATCH] Documentation/admin-guide: Embargoed hardware security issues

[Jonathan Corbet]

On Thu, 25 Jul 2019 15:01:13 +0200
Greg Kroah-Hartman  wrote:

> From: Thomas Gleixner 
> 
> To address the requirements of embargoed hardware issues, like Meltdown,
> Spectre, L1TF, etc. it is necessary to define and document a process for
> handling embargoed hardware security issues.
> 
> Following the discussion at the maintainer summit 2018 in Edinburgh
> (https://lwn.net/Articles/769417/) the volunteered people have worked
> out a process and a Memorandum of Understanding.  The latter addresses
> the fact that the Linux kernel community cannot sign NDAs for various
> reasons.
> 

[...]

>  Documentation/admin-guide/embargoed-hardware-issues.rst |  281 
> 
>  Documentation/admin-guide/index.rst |1 
>  2 files changed, 282 insertions(+)

So I would argue that the admin guide (which is aimed at sysadmins) is the
wrong place for this document.  It's process information and is best placed
in the process manual (Documentation/process) IMO.  (Yes, I know
security-bugs.rst is in the admin guide; I remember there was a discussion
at the time and it ended up there, but I'm not really sure that's right
either).

> Note, this document has gone through numerous reviews by a number of
> kernel developers, developers at some of the Linux distros, as well as
> all of the lawyers from almost all open source-related companies.  It's
> been sitting on my local drive with no comments for a few months now,
> and it's about time to get this out and merged properly.
> 
> If anyone has any final comments, please let me know.

I do think it could benefit from a pass for basic language issues; I can do
that if such an effort would be welcome.

> If anyone from any company listed below wishes to add their name to the
> document, please send a follow-on patch and I will be glad to add it to
> the series.  I had a number of "I'll sign up" type comments from
> different people, but I want something with a "s-o-b" to keep people on
> the hook for this, so I did not add their name to the file without that.
> 
> thanks,
> 
> greg k-h
> 
> 
> 
> --- /dev/null
> +++ b/Documentation/admin-guide/embargoed-hardware-issues.rst
> @@ -0,0 +1,281 @@
> +.. _embargoedhardwareissues:

This label isn't used anywhere.

> +Embargoed hardware issues
> +=
> +
> +Scope
> +-
> +
> +Hardware issues which result in security problems are a different category
> +of security bugs than pure software bugs which  only affect the Linux
> +kernel.
> +
> +Hardware issues like Meltdown, Spectre, L1TF etc. must be treated
> +differently because they usually affect all Operating Systems (“OS“) and

Somebody may well complain about the "smart quotes" here; non-ascii stuff
has led to unhappiness in the past.

> +therefore need coordination across different OS vendors, distributions,
> +hardware vendors and other parties. For some of the issues, software
> +mitigations can depend on microcode or firmware updates, which need further
> +coordination.
> +
> +.. _Contact:
> +
> +Contact
> +---
> +
> +The Linux kernel hardware security team is separate from the regular Linux
> +kernel security team.
> +
> +The team is only handling the coordination of embargoed hardware security

s/is only handling/only handles/

> +issues. Reports of pure software security bugs in the Linux kernel are not
> +handled by this team and the reporter will be guided to contact the regular
> +Linux kernel security team (:ref:`Documentation/admin-guide/
> +`) instead.
> +
> +The team can be contacted by email at . This
> +is a private list of security officers who will help you to coordinate an
> +issue according to our documented process.
> +
> +The list is encrypted and email to the list can be sent by either PGP or
> +S/MIME encrypted and must be signed with the reporter's PGP key or S/MIME
> +certificate. The list's PGP key and S/MIME certificate are available from
> +https://www.kernel.org/

Somebody needs to fill in some dots there...:)

> +While hardware security issues are often handled by the affected hardware
> +vendor, we welcome contact from researchers or individuals who identified a

who *have* identified

> +potential hardware flaw.
> +
> +Hardware security officers
> +^^
> +
> +The current team of hardware security officers:
> +
> +  - Linus Torvalds (Linux Foundation Fellow)
> +  - Greg Kroah-Hartman (Linux Foundation Fellow)
> +  - Thomas Gleixner (Linux Foundation Fellow)
> +
> +Operation of mailing-lists
> +^^

I would de-hyphenate "mailing list" throughout.  But that's me.

> +The encrypted mailing-lists which are used in our process are hosted on
> +Linux Foundation's IT infrastructure. By providing this service Linux
> +Foundation's director of IT Infrastructure security technically has the
> +ability to access the embargoed information, but is obliged to
> +confidentiality by his employment contract. Linux Foundation's director of
> +IT Infrastructure

Re: [PATCH] docs: phy: Drop duplicate 'be made'

[Jonathan Corbet]

On Fri, 26 Jul 2019 11:55:34 +0200
Guido Günther  wrote:

> Fix duplicate words.
> 
> Signed-off-by: Guido Günther 

Applied, thanks.

jon