Re: [PATCH] docs: move powerpc under arch

[Jonathan Corbet]

Michael Ellerman  writes:

> On October 4, 2023 3:05:48 AM GMT+11:00, Jonathan Corbet  
> wrote:
>>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 
>>
>>So this patch appears to have not been picked up, and to have received
>>no comments.  I'll happily carry it in docs-next, but it would be nice
>>to have an ack from the powerpc folks...?
>
> I acked it a few months back, and said I assumed you were merging it:
>
> https://lore.kernel.org/linuxppc-dev/87bkfwem93.fsf@mail.lhotse/
>
> I don't mind who merges it, I figured you merging it would generate fewer 
> conflicts, but I'm happy to take it if you think that would be better.
>
> Anyway here's another:
>
> Acked-by: Michael Ellerman  (powerpc)

OK, sorry, somehow I missed that.  I'll apply it shortly.

Thanks,

jon

Re: [PATCH] docs: move powerpc 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 

So this patch appears to have not been picked up, and to have received
no comments.  I'll happily carry it in docs-next, but it would be nice
to have an ack from the powerpc folks...?

Thanks,

jon

Re: [PATCH] Documentation: spufs: correct a duplicate word typo

[Jonathan Corbet]

Randy Dunlap  writes:

> Fix a typo of "or" which should be "of".
>
> Signed-off-by: Randy Dunlap 
> Cc: Jeremy Kerr 
> Cc: Arnd Bergmann 
> Cc: linuxppc-dev@lists.ozlabs.org
> Cc: Jonathan Corbet 
> ---
>  Documentation/filesystems/spufs/spufs.rst |2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> --- a/Documentation/filesystems/spufs/spufs.rst
> +++ b/Documentation/filesystems/spufs/spufs.rst
> @@ -227,7 +227,7 @@ Files
>from the data buffer, updating the value of the specified 
> signal
>notification register.  The signal  notification  register  
> will
>either be replaced with the input data or will be updated to 
> the
> -  bitwise OR or the old value and the input data, depending on 
> the
> +  bitwise OR of the old value and the input data, depending on 
> the
>contents  of  the  signal1_type,  or  signal2_type 
> respectively,
>file.

Applied, thanks.

jon

Re: [PATCH 2/3] Documentation: use different label names for each arch's elf_hwcaps.rst

[Jonathan Corbet]

Bagas Sanjaya  writes:

> Sphinx reported duplicate label warning:
>
> WARNING: duplicate label elf_hwcaps_index, other instance in 
> Documentation/arm64/elf_hwcaps.rst
>
> The warning is caused by elf_hwcaps_index label name is already used for
> arm64 documentation, whileas powerpc use the same name.
>
> Disambiguate the label name for each architecture's documentation. While
> at it, also adjust original reference in translated documentation.
>
> Link: 
> https://lore.kernel.org/linuxppc-dev/20220727220050.549db...@canb.auug.org.au/
> Fixes: 3df1ff42e69e91 ("powerpc: add documentation for HWCAPs")
> Reported-by: Stephen Rothwell 
> Signed-off-by: Bagas Sanjaya 
> ---
>  Documentation/arm64/elf_hwcaps.rst| 2 +-
>  Documentation/powerpc/elf_hwcaps.rst  | 2 +-
>  Documentation/translations/zh_CN/arm64/elf_hwcaps.rst | 2 +-
>  Documentation/translations/zh_TW/arm64/elf_hwcaps.rst | 2 +-
>  4 files changed, 4 insertions(+), 4 deletions(-)

A better solution in cases like this is to just delete the label
entirely.  I'm not quite sure how we got started with this habit of
adding unneeded labels, but they just clutter up the text - and, as
we've seen, add warnings.

These labels aren't needed for anything, so I'd just take them out.

Thanks,

jon

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

[Jonathan Corbet]

"Aneesh Kumar K.V"  writes:


> Thanks for looking into this. I guess we also need to format the below table?
>
>   | 08   40
> --|
>   |
> 0 | 10   20  80
>   |
> 8 | 20   10  160
>   |
> 40| 80   160  10
>
>
> I don't know how to represent that in the documentation file. A table is
> probably not the right one?

The cheap way out is to put it in a literal block, of course.  Sphinx
makes tables pretty easy, though:

  https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

jon

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

[Jonathan Corbet]

Stephen Rothwell  writes:

> Hi all,
>
> [cc'ing Jon in case he can fix the sphix hang - or knows anything about it]

That's new to me.  Which version of sphinx?

jon

Re: [PATCH] docs: kernel-parameters: mark numa=off is supported by a bundle of architectures

[Jonathan Corbet]

Barry Song  writes:

> risc-v and arm64 support numa=off by common arch_numa_init()
> in drivers/base/arch_numa.c. x86, ppc, mips, sparc support it
> by arch-level early_param.
> numa=off is widely used in linux distributions. it is better
> to document it.
>
> Signed-off-by: Barry Song 
> ---
>  Documentation/admin-guide/kernel-parameters.txt | 3 +++
>  1 file changed, 3 insertions(+)

Applied, thanks.

jon

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

[Jonathan Corbet]

He Ying  writes:

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

Applied, thanks.

jon

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

[Jonathan Corbet]

Bhaskar Chowdhury  writes:

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

Applied, thanks.

jon

Re: [PATCH] docs: powerpc: Fix tables in syscall64-abi.rst

[Jonathan Corbet]

Andrew Donnellan  writes:

> Commit 209b44c804c ("docs: powerpc: syscall64-abi.rst: fix a malformed
> table") attempted to fix the formatting of tables in syscall64-abi.rst, but
> inadvertently changed some register names.
>
> Redo the tables with the correct register names, and while we're here,
> clean things up to separate the registers into different rows and add
> headings.
>
> Fixes: 209b44c804c ("docs: powerpc: syscall64-abi.rst: fix a malformed table")
> Signed-off-by: Andrew Donnellan 
> ---
>  Documentation/powerpc/syscall64-abi.rst | 51 -
>  1 file changed, 32 insertions(+), 19 deletions(-)

Applied, thanks.

jon

Re: [PATCH 0/6] Add documentation for Documentation/features at the built docs

[Jonathan Corbet]

On Mon, 30 Nov 2020 16:36:29 +0100
Mauro Carvalho Chehab  wrote:

> This series got already submitted last year:
> 
>
> https://lore.kernel.org/lkml/cover.1561222784.git.mchehab+sams...@kernel.org/
> 
> Yet, on that time, there were too many other patches related to ReST
> conversion floating around. So, at the end, I guess this one got missed.
> 
> So, I did a rebase on the top of upstream, and added a few new changes.

OK, I've gone ahead and applied these; it gains me a new trivial conflict
with x86, but so be it...

That said, I think that the RST table formatting could be *way* improved.
The current tables are all white space and hard to make sense of.  What if
we condensed the information?  Just looking at the first entry in
Documentation/admin-guide/features.html, perhaps it could look like:

FEATURE KCONFIG/DESCRIPTION STATUS

cBPF-JITHAVE_CBPF_JIT   TODO: alpha, arc, arm...
ok: mips, powerpc, ...
arch supports cBPF JIT
optimizations

The result would be far more compact and easy to read, IMO.  I may get
around to giving this a try if (hint :) nobody else gets there first.

Thanks,

jon

Re: [PATCH V2] Doc: admin-guide: Add entry for kvm_cma_resv_ratio kernel param

[Jonathan Corbet]

On Mon, 21 Sep 2020 14:32:20 +0530
sathn...@linux.vnet.ibm.com wrote:

> From: Satheesh Rajendran 
> 
> Add document entry for kvm_cma_resv_ratio kernel param which
> is used to alter the KVM contiguous memory allocation percentage
> for hash pagetable allocation used by hash mode PowerPC KVM guests.
> 
> Cc: linux-ker...@vger.kernel.org
> Cc: kvm-...@vger.kernel.org
> Cc: linuxppc-dev@lists.ozlabs.org
> Cc: Paul Mackerras 
> Cc: Michael Ellerman 
> Cc: Jonathan Corbet 
> Reviewed-by: Randy Dunlap 
> Signed-off-by: Satheesh Rajendran 
> ---
> 
> V2: 
> Addressed review comments from Randy.
> 
> V1: https://lkml.org/lkml/2020/9/16/72

Applied, thanks.

jon

Re: [PATCH 00/20] Documentation: eliminate duplicated words

[Jonathan Corbet]

On Tue,  7 Jul 2020 11:03:54 -0700
Randy Dunlap  wrote:

>  Documentation/admin-guide/mm/numaperf.rst |2 +-
>  Documentation/block/pr.rst|2 +-
>  Documentation/core-api/printk-basics.rst  |2 +-
>  Documentation/dev-tools/kgdb.rst  |2 +-
>  Documentation/fpga/dfl.rst|2 +-
>  Documentation/gpu/drm-uapi.rst|2 +-
>  Documentation/gpu/komeda-kms.rst  |2 +-
>  Documentation/hid/intel-ish-hid.rst   |2 +-
>  Documentation/i2c/upgrading-clients.rst   |2 +-
>  Documentation/kbuild/kconfig-language.rst |2 +-
>  Documentation/leds/ledtrig-transient.rst  |2 +-
>  Documentation/maintainer/maintainer-entry-profile.rst |2 +-
>  Documentation/mips/ingenic-tcu.rst|2 +-
>  Documentation/misc-devices/xilinx_sdfec.rst   |2 +-
>  Documentation/powerpc/vas-api.rst |2 +-
>  Documentation/s390/vfio-ap.rst|2 +-
>  Documentation/scsi/advansys.rst   |2 +-
>  Documentation/security/keys/trusted-encrypted.rst |2 +-
>  Documentation/virt/kvm/api.rst|2 +-
>  Documentation/vm/memory-model.rst |2 +-
>  20 files changed, 20 insertions(+), 20 deletions(-)

I've applied this set, minus #17 that was already picked up by Martin.

Thanks,

jon

Re: [PATCH v2 00/15] Documentation fixes

[Jonathan Corbet]

On Tue, 23 Jun 2020 09:08:56 +0200
Mauro Carvalho Chehab  wrote:

> As requested, this is a rebase of a previous series posted on Jan, 15.
> 
> Since then, several patches got merged via other trees or became
> obsolete. There were also 2 patches before that fits better at the
> ReST conversion patchset. So, I'll be sending it on another patch
> series together with the remaining ReST conversions.
> 
> I also added reviews/acks received.
> 
> So, the series reduced from 29 to 15 patches.
> 
> Let's hope b4 would be able to properly handle this one.

Nope.  I don't know what it is about your patch series, but b4 is never
able to put them together.

I've applied the series except for #1, which already went through the -mm
tree.

Thanks,

jon

Re: [PATCH 00/22] ReST conversion patches (final?)

[Jonathan Corbet]

On Mon, 15 Jun 2020 08:50:05 +0200
Mauro Carvalho Chehab  wrote:

> That's my final(*) series of conversion patches from .txt to ReST.
> 
> (*) Well, running the script I'm using to check, I noticed a couple of new 
> *.txt files.
> If I have some time, I'll try to address those last pending things for v5.9.

OK, I've applied the set except for parts:

 1: |copy| as mentioned before
 18: because of the license boilerplate
 19: doesn't apply at all (perhaps because of one of the above)
 22: because I don't like the latex markup.

Also, I took the liberty of just reverting the |copy| change in #10.

Getting there..!

Thanks,

jon

Re: [PATCH v3 00/29] Convert files to ReST - part 2

[Jonathan Corbet]

On Tue, 28 Apr 2020 13:01:28 -0600
Jonathan Corbet  wrote:

> So I'm happy to merge this set, but there is one thing that worries me a
> bit... 
> 
> >  fs/cachefiles/Kconfig |4 +-
> >  fs/coda/Kconfig   |2 +-
> >  fs/configfs/inode.c   |2 +-
> >  fs/configfs/item.c|2 +-
> >  fs/fscache/Kconfig|8 +-
> >  fs/fscache/cache.c|8 +-
> >  fs/fscache/cookie.c   |2 +-
> >  fs/fscache/object.c   |4 +-
> >  fs/fscache/operation.c|2 +-
> >  fs/locks.c|2 +-
> >  include/linux/configfs.h  |2 +-
> >  include/linux/fs_context.h|2 +-
> >  include/linux/fscache-cache.h |4 +-
> >  include/linux/fscache.h   |   42 +-
> >  include/linux/lsm_hooks.h |2 +-  
> 
> I'd feel a bit better if I could get an ack or two from filesystem folks
> before I venture that far out of my own yard...what say you all?

It's been another week and nobody has complained, so I'm taking that as
assent; the series has been applied.

Thanks,

jon

Re: [PATCH v3 00/29] Convert files to ReST - part 2

[Jonathan Corbet]

On Mon, 27 Apr 2020 23:16:52 +0200
Mauro Carvalho Chehab  wrote:

> This is the second part of a series I wrote sometime ago where I manually
> convert lots of files to be properly parsed by Sphinx as ReST files.
> 
> As it touches on lot of stuff, this series is based on today's linux-next, 
> at tag next-20190617.
> 
> The first version of this series had 57 patches. The first part with 28 
> patches
> were already merged. Right now, there are still ~76  patches pending applying
> (including this series), and that's because I opted to do ~1 patch per 
> converted
>  directory.
> 
> That sounds too much to be send on a single round. So, I'm opting to split
> it on 3 parts for the conversion, plus a final patch adding orphaned books
> to existing ones. 
> 
> Those patches should probably be good to be merged either by subsystem
> maintainers or via the docs tree.

So I'm happy to merge this set, but there is one thing that worries me a
bit... 

>  fs/cachefiles/Kconfig |4 +-
>  fs/coda/Kconfig   |2 +-
>  fs/configfs/inode.c   |2 +-
>  fs/configfs/item.c|2 +-
>  fs/fscache/Kconfig|8 +-
>  fs/fscache/cache.c|8 +-
>  fs/fscache/cookie.c   |2 +-
>  fs/fscache/object.c   |4 +-
>  fs/fscache/operation.c|2 +-
>  fs/locks.c|2 +-
>  include/linux/configfs.h  |2 +-
>  include/linux/fs_context.h|2 +-
>  include/linux/fscache-cache.h |4 +-
>  include/linux/fscache.h   |   42 +-
>  include/linux/lsm_hooks.h |2 +-

I'd feel a bit better if I could get an ack or two from filesystem folks
before I venture that far out of my own yard...what say you all?

Thanks,

jon

Re: [PATCH v2 00/33] Documentation fixes for Kernel 5.8

[Jonathan Corbet]

On Tue, 14 Apr 2020 18:48:26 +0200
Mauro Carvalho Chehab  wrote:

> Patches 1 to 5 contain changes to the documentation toolset:
> 
> - The first 3 patches help to reduce a lot the number of reported
>   kernel-doc issues, by making the tool more smart.
> 
> - Patches 4 and 5 are meant to partially address the PDF
>   build, with now requires Sphinx version 2.4 or upper.
> 
> The remaining patches fix broken references detected by
> this tool:
> 
> ./scripts/documentation-file-ref-check
> 
> and address other random errors due to tags being mis-interpreted
> or mis-used.
> 
> They are independent each other, but some may depend on
> the kernel-doc improvements.
> 
> PS.: Due to the large number of C/C, I opted to keep a smaller
> set of C/C at this first e-mail (only e-mails with "L:" tag from
> MAINTAINERS file).

OK, I've applied this set, minus #17 which was applied elsewhere.

Thanks,

jon

Re: [PATCH v2 0/2] Don't generate thousands of new warnings when building docs

[Jonathan Corbet]

On Fri, 20 Mar 2020 16:11:01 +0100
Mauro Carvalho Chehab  wrote:

> This small series address a regression caused by a new patch at
> docs-next (and at linux-next).

I don't know how I missed that mess, sorry.  I plead distracting times or
something like that.  Heck, I think I'll blame everything on the plague
for at least the next few weeks.

Anyway, I've applied this, thanks for cleaning it up.

jon

Re: [patch V2 08/15] Documentation: Add lock ordering and nesting documentation

[Jonathan Corbet]

On Wed, 18 Mar 2020 21:43:10 +0100
Thomas Gleixner  wrote:

> From: Thomas Gleixner 
> 
> The kernel provides a variety of locking primitives. The nesting of these
> lock types and the implications of them on RT enabled kernels is nowhere
> documented.
> 
> Add initial documentation.

...time to add a a couple of nits...:)

> Signed-off-by: Thomas Gleixner 
> ---
> V2: Addressed review comments from Randy
> ---
>  Documentation/locking/index.rst |1 
>  Documentation/locking/locktypes.rst |  298 
> 
>  2 files changed, 299 insertions(+)
>  create mode 100644 Documentation/locking/locktypes.rst
> 
> --- a/Documentation/locking/index.rst
> +++ b/Documentation/locking/index.rst
> @@ -7,6 +7,7 @@ locking
>  .. toctree::
>  :maxdepth: 1
>  
> +locktypes
>  lockdep-design
>  lockstat
>  locktorture
> --- /dev/null
> +++ b/Documentation/locking/locktypes.rst
> @@ -0,0 +1,298 @@
> +.. _kernel_hacking_locktypes:
> +

So ... I vaguely remember that some Thomas guy added a document saying we
should be putting SPDX tags on our files? :)

> +==
> +Lock types and their rules
> +==

[...]

> +PREEMPT_RT caveats
> +==
> +
> +spinlock_t and rwlock_t
> +---
> +
> +The substitution of spinlock_t and rwlock_t on PREEMPT_RT enabled kernels
> +with RT-mutex based implementations has a few implications.
> +
> +On a non PREEMPT_RT enabled kernel the following code construct is
> +perfectly fine::
> +
> +   local_irq_disable();
> +   spin_lock();
> +
> +and fully equivalent to::
> +
> +   spin_lock_irq();
> +
> +Same applies to rwlock_t and the _irqsave() suffix variant.
> +
> +On a PREEMPT_RT enabled kernel this breaks because the RT-mutex
> +substitution expects a fully preemptible context.
> +
> +The preferred solution is to use :c:func:`spin_lock_irq()` or
> +:c:func:`spin_lock_irqsave()` and their unlock counterparts.

We don't need (and shouldn't use) :c:func: anymore; just saying
spin_lock_irq() will cause the Right Things to happen.

Thanks,
jon

Re: [PATCH v9 10/25] mm/gup: introduce pin_user_pages*() and FOLL_PIN

[Jonathan Corbet]

On Tue, 10 Dec 2019 18:53:03 -0800
John Hubbard  wrote:

> Introduce pin_user_pages*() variations of get_user_pages*() calls,
> and also pin_longterm_pages*() variations.

Just a couple of nits on the documentation patch

> +++ b/Documentation/core-api/pin_user_pages.rst
> @@ -0,0 +1,232 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +
> +pin_user_pages() and related calls
> +
> +
> +.. contents:: :local:
> +
> +Overview
> +
> +
> +This document describes the following functions: ::
> +
> + pin_user_pages
> + pin_user_pages_fast
> + pin_user_pages_remote

You could just say "the following functions::" and get the result you're
after with a slightly less alien plain-text reading experience.

Of course, you could also just say "This document describes
pin_user_pages(), pin_user_pages_fast(), and pin_user_pages_remote()." But
that's a matter of personal taste, I guess.  Using the function() notation
will cause the docs system to automatically link to the kerneldoc info,
though.  

> +Basic description of FOLL_PIN
> +=
> +
> +FOLL_PIN and FOLL_LONGTERM are flags that can be passed to the 
> get_user_pages*()
> +("gup") family of functions. FOLL_PIN has significant interactions and
> +interdependencies with FOLL_LONGTERM, so both are covered here.
> +
> +FOLL_PIN is internal to gup, meaning that it should not appear at the gup 
> call
> +sites. This allows the associated wrapper functions  (pin_user_pages*() and
> +others) to set the correct combination of these flags, and to check for 
> problems
> +as well.
> +
> +FOLL_LONGTERM, on the other hand, *is* allowed to be set at the gup call 
> sites.
> +This is in order to avoid creating a large number of wrapper functions to 
> cover
> +all combinations of get*(), pin*(), FOLL_LONGTERM, and more. Also, the
> +pin_user_pages*() APIs are clearly distinct from the get_user_pages*() APIs, 
> so
> +that's a natural dividing line, and a good point to make separate wrapper 
> calls.
> +In other words, use pin_user_pages*() for DMA-pinned pages, and
> +get_user_pages*() for other cases. There are four cases described later on in
> +this document, to further clarify that concept.
> +
> +FOLL_PIN and FOLL_GET are mutually exclusive for a given gup call. However,
> +multiple threads and call sites are free to pin the same struct pages, via 
> both
> +FOLL_PIN and FOLL_GET. It's just the call site that needs to choose one or 
> the
> +other, not the struct page(s).
> +
> +The FOLL_PIN implementation is nearly the same as FOLL_GET, except that 
> FOLL_PIN
> +uses a different reference counting technique.
> +
> +FOLL_PIN is a prerequisite to FOLL_LONGTGERM. Another way of saying that is,

FOLL_LONGTERM typoed there.

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: [RESEND PATCH] Documentation/stackprotector: powerpc supports stack protector

[Jonathan Corbet]

On Mon, 10 Jun 2019 15:33:39 +0530
Bhupesh Sharma  wrote:

> powerpc architecture (both 64-bit and 32-bit) supports stack protector
> mechanism since some time now [see commit 06ec27aea9fc ("powerpc/64:
> add stack protector support")].
> 
> Update stackprotector arch support documentation to reflect the same.
> 
> Cc: Jonathan Corbet 
> Cc: Michael Ellerman 
> Cc: linux-...@vger.kernel.org
> Cc: linux-ker...@vger.kernel.org
> Cc: linuxppc-dev@lists.ozlabs.org
> Signed-off-by: Bhupesh Sharma 
> ---
> Resend, this time Cc'ing Jonathan and doc-list.

Applied, thanks.

jon

Re: [PATCH v4 19/28] docs: powerpc: convert docs to ReST and rename to *.rst

[Jonathan Corbet]

On Wed, 12 Jun 2019 14:52:55 -0300
Mauro Carvalho Chehab  wrote:

> Convert docs to ReST and add them to the arch-specific
> book.
> 
> The conversion here was trivial, as almost every file there
> was already using an elegant format close to ReST standard.
> 
> The changes were mostly to mark literal blocks and add a few
> missing section title identifiers.
> 
> One note with regards to "--": on Sphinx, this can't be used
> to identify a list, as it will format it badly. This can be
> used, however, to identify a long hyphen - and "---" is an
> even longer one.
> 
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> Acked-by: Andrew Donnellan  # cxl

This one fails to apply because ...

[...]

> diff --git a/Documentation/PCI/pci-error-recovery.rst 
> b/Documentation/PCI/pci-error-recovery.rst
> index 83db42092935..acc21ecca322 100644
> --- a/Documentation/PCI/pci-error-recovery.rst
> +++ b/Documentation/PCI/pci-error-recovery.rst
> @@ -403,7 +403,7 @@ That is, the recovery API only requires that:
>  .. note::
>  
> Implementation details for the powerpc platform are discussed in
> -   the file Documentation/powerpc/eeh-pci-error-recovery.txt
> +   the file Documentation/powerpc/eeh-pci-error-recovery.rst
>  
> As of this writing, there is a growing list of device drivers with
> patches implementing error recovery. Not all of these patches are in
> @@ -422,3 +422,24 @@ That is, the recovery API only requires that:
> - drivers/net/cxgb3
> - drivers/net/s2io.c
> - drivers/net/qlge
> +
> +>>> As of this writing, there is a growing list of device drivers with
> +>>> patches implementing error recovery. Not all of these patches are in
> +>>> mainline yet. These may be used as "examples":
> +>>>
> +>>> drivers/scsi/ipr
> +>>> drivers/scsi/sym53c8xx_2
> +>>> drivers/scsi/qla2xxx
> +>>> drivers/scsi/lpfc
> +>>> drivers/next/bnx2.c
> +>>> drivers/next/e100.c
> +>>> drivers/net/e1000
> +>>> drivers/net/e1000e
> +>>> drivers/net/ixgb
> +>>> drivers/net/ixgbe
> +>>> drivers/net/cxgb3
> +>>> drivers/net/s2io.c
> +>>> drivers/net/qlge  

...of this, which has the look of a set of conflict markers that managed
to get committed...?

jon

Re: [PATCH] Documentation/stackprotector: powerpc supports stack protector

[Jonathan Corbet]

On Thu, 30 May 2019 18:37:46 +0530
Bhupesh Sharma  wrote:

> > This should probably go via the documentation tree?
> >
> > Acked-by: Michael Ellerman   
> 
> Thanks for the review Michael.
> I am ok with this going through the documentation tree as well.

Works for me too, but I don't seem to find the actual patch anywhere I
look.  Can you send me a copy?

Thanks,

jon

Re: [PATCH] Documentation: Add ARM64 to kernel-parameters.rst

[Jonathan Corbet]

On Fri, 3 May 2019 13:39:40 +0100
Will Deacon  wrote:

> > It looks like nobody has picked this up...so I've applied it.  
> 
> It's queued and tagged in the arm64 tree, which should also be in next!

Just looked again, I still don't see it there.  Josh's mitigations= change
is there, but not this one.  In any case, I've unapplied it, so it's all
yours.

Thanks,

jon

Re: [PATCH] Documentation: Add ARM64 to kernel-parameters.rst

[Jonathan Corbet]

On Fri, 12 Apr 2019 22:56:21 -0500
Josh Poimboeuf  wrote:

> Add ARM64 to the legend of architectures.  It's already used in several
> places in kernel-parameters.txt.
> 
> Suggested-by: Randy Dunlap 
> Signed-off-by: Josh Poimboeuf 

It looks like nobody has picked this up...so I've applied it.

Thanks,

jon

Re: [PATCH v4 00/63] Include linux ACPI/PCI/X86 docs into Sphinx TOC tree

[Jonathan Corbet]

On Wed, 24 Apr 2019 00:28:29 +0800
Changbin Du  wrote:

> The kernel now uses Sphinx to generate intelligent and beautiful documentation
> from reStructuredText files. I converted all of the Linux ACPI/PCI/X86 docs to
> reST format in this serias.
> 
> In this version I combined ACPI and PCI docs, and added new x86 docs 
> conversion.

As mentioned by others, this is a lot of stuff; I would really rather see
each of those groups as separate patch sets.

If you can do a reasonably quick turnaround with Mauro's suggestions
addressed and tags applied, we should be able to get at least some of this
into 5.2.  Thanks, Mauro, for looking at all of this stuff!

Thanks,

jon

Re: Avoiding merge conflicts while adding new docs - Was: Re: [PATCH 00/57] Convert files to ReST

[Jonathan Corbet]

On Thu, 18 Apr 2019 09:42:23 -0300
Mauro Carvalho Chehab  wrote:

> After thinking a little bit and doing some tests, I think a good solution
> would be to add ":orphan:" markup to the new .rst files that were not
> added yet into the main body (e. g. something like the enclosed example).

Interesting...I didn't know about that.  Yes, I think it makes sense to
put that in...

jon

Re: [PATCH v2 00/21] Convert hwmon documentation to ReST

[Jonathan Corbet]

On Fri, 12 Apr 2019 20:09:16 -0700
Guenter Roeck  wrote:

> The big real-world question is: Is the series good enough for you to accept,
> or do you expect some level of user/kernel separation ?

I guess it can go in; it's forward progress, even if it doesn't make the
improvements I would like to see.

The real question, I guess, is who should take it.  I've been seeing a
fair amount of activity on hwmon, so I suspect that the potential for
conflicts is real.  Perhaps things would go smoother if it went through
your tree?

Thanks,

jon

Re: [PATCH v2 00/21] Convert hwmon documentation to ReST

[Jonathan Corbet]

On Thu, 11 Apr 2019 14:07:31 -0700
Guenter Roeck  wrote:

> > While nobody does such split, IMHO, the best would be to keep the
> > information outside Documentation/admin-guide. But hey! You're
> > the Doc maintainer. If you prefer to move, I'm perfectly fine
> > with that.
> >   
> 
> Same here, but please don't move the files which are kernel facing only.

Well, let's step back and think about this.  Who is the audience for
these documents?  That will tell us a lot about where they should really
be.  

What I would prefer to avoid is the status quo where *everything* is in
the top-level directory, and where documents are organized for the
convenience of their maintainers rather than of their readers.  But
sometimes I feel like I'm alone in that desire...:)

Thanks,

jon

Re: [PATCH v2 00/21] Convert hwmon documentation to ReST

[Jonathan Corbet]

On Wed, 10 Apr 2019 16:22:37 -0300
Mauro Carvalho Chehab  wrote:

> This series converts the contents of Documentation/hwmon to ReST
> format.
> 
> PS.: I opted to group the conversion files per groups of maintainer
> set, as, if I were to generate one patch per file, it would give around
> 160 patches.
> 
> I also added those patches to my development tree at:
>   https://git.linuxtv.org/mchehab/experimental.git/log/?h=hwmon
> 
> If you want to see the results, they're at:
>   https://www.infradead.org/~mchehab/hwmon/

This set seems generally good and could probably be applied as-is.  But I
have to ask...is there a reason to not take the last step and actually
bring this stuff into the Sphinx doc tree?

We seem to be mostly documenting sysfs files and such.  I am *guessing*
that perhaps the set should move to Documentation/admin-guide/hwmon?  Or
have I misunderstood the intended audience here?

Thanks,

jon

Re: [PATCH 0/1] Start conversion of PowerPC docs

[Jonathan Corbet]

On Fri, 08 Feb 2019 14:40:28 +1100
Michael Ellerman  wrote:

> > - I don't think this should be a top-level directory full of docs; the top
> >   level is already rather overpopulated.  At worst, we should create an
> >   arch/ directory for architecture-specific docs.  
> 
> We currently have arch specific directories for arm, arm64, ia64, m68k,
> nios2, openrisc, parisc, powerpc, s390, sh, sparc, x86, xtensa.
> 
> Do you mean they should all be moved to Documentation/arch ?

Over time I'm really trying to bring some organization to Documentation/,
and to have that reflected in an RST tree that looks like somebody actually
thought about it.  So yes, I would eventually like to see something like
Documentation/arch, just like we have arch/ in the top-level directory.

> >   I kind of think that
> >   this should be thought through a bit more, though, with an eye toward
> >   who the audience is.  Some of it is clearly developer documentation, and
> >   some of it is aimed at admins; ptrace.rst is user-space API stuff.
> >   Nobody ever welcomes me saying this, but we should really split things
> >   into the appropriate manuals according to audience.  
> 
> I don't think any of it's aimed at admins, but I haven't read every
> word. I see it as aimed at kernel devs or people writing directly to the
> kernel API, eg. gdb developers reading ptrace.rst.
> 
> If Documentation/ wants to be more user focused and nicely curated
> perhaps we need arch/foo/docs/ for these developer centric docs?

Stuff for GDB developers is best placed in the userspace-api docbook; we're
trying to concentrate that there.  Stuff for kernel developers is a bit
more diffuse still; arch/foo/docs may end up being the best place for it in
the end, yes.

> > - It would be good to know how much of this stuff is still relevant.
> >   bootwrapper.txt hasn't been modified since it was added in 2008.  
> 
> It hasn't been modified but AFAIK it's still pretty much accurate and
> definitely something we want to have documented.

That's fine for this (and all the others); I'm just hoping that somebody
has thought about it.  We're carrying a *lot* of dusty old stuff that, IMO,
can only serve to confuse those who read it.  If these files don't fall
into that category, that's great.

> We support some hardware that is ~25 years old, so we have some old
> documentation too, and I'd rather we didn't drop things just because
> they're old.

I agree, as long as they remain correct and relevant.

> > - I'm glad you're adding SPDX lines, but do you know that the license is
> >   correct in each case?  It's best to be careful with such things.  
> 
> None of the files have licenses so I think we just fall back to COPYING
> don't we? In which case GPL-2.0 is correct for all files.

That's often the best choice, though some people have resorted to some
rather more in-depth archeology to try to figure out what the original
author actually intended.  Again, I'm just asking so that we're sure it's
the best choice.

Thanks,

jon

Re: [PATCH 0/1] Start conversion of PowerPC docs

[Jonathan Corbet]

On Thu,  7 Feb 2019 17:03:15 +1100
"Tobin C. Harding"  wrote:

> As discussed at LCA here is the start to the docs conversion for PowerPC
> to RST.
> 
> This applies cleanly on top of the mainline (5.20-rc5) and Jon's tree
> (docs-next branch).
> 
> I'm guessing it should go in through the PowerPC tree because I doubt
> you want to review this Jon, it's one big single patch (all blame for
> that falls on mpe ;)

Well, I went and took a look anyway, being a glutton for punishment.  So
naturally I do have some comments...

- I don't think this should be a top-level directory full of docs; the top
  level is already rather overpopulated.  At worst, we should create an
  arch/ directory for architecture-specific docs.  I kind of think that
  this should be thought through a bit more, though, with an eye toward
  who the audience is.  Some of it is clearly developer documentation, and
  some of it is aimed at admins; ptrace.rst is user-space API stuff.
  Nobody ever welcomes me saying this, but we should really split things
  into the appropriate manuals according to audience.

- It would be good to know how much of this stuff is still relevant.
  bootwrapper.txt hasn't been modified since it was added in 2008.
  cpu_features.txt predates the git era, as does mpc52xx.txt; hvcs.txt is
  nearly as old. And so on.  Can we perhaps stop dragging some of those
  docs around?

- The use of flat-table in isa-versions.rst totally wrecks the readability
  of those tables in the plain-text version.  Said tables are pretty close
  to being RST in their original form; it would be far better to just fix
  anything needing fixing but to keep that form.

- I'm glad you're adding SPDX lines, but do you know that the license is
  correct in each case?  It's best to be careful with such things.

Thanks,

jon

Re: [PATCH] Documentation: fix spelling mistake, EACCESS -> EACCES

[Jonathan Corbet]

On Fri, 26 Oct 2018 18:25:49 +0100
Colin King  wrote:

> Trivial fix to a spelling mistake of the error access name EACCESS,
> rename to EACCES
> 
> Signed-off-by: Colin Ian King 
> ---
>  Documentation/filesystems/spufs.txt | 2 +-
>  Documentation/gpu/drm-uapi.rst  | 4 ++--
>  2 files changed, 3 insertions(+), 3 deletions(-)

Applied, thanks.  

This is the first patch to spufs.txt since 2006...I wonder if that stuff
is being used by anybody...

jon

Re: [PATCH] [RFC v2] Drop all 00-INDEX files from Documentation/

[Jonathan Corbet]

On Tue,  4 Sep 2018 00:15:23 +0200
Henrik Austad  wrote:

> I don't really have an opinion to whether or not we /should/ have 00-INDEX,
> but the above 00-INDEX should either be removed or be kept up to date. If
> we should keep the files, I can try to keep them updated, but I rather not
> if we just want to delete them anyway.
> 
> As a starting point, remove all index-files and references to 00-INDEX and
> see where the discussion is going.

Applied, thanks.

jon

Re: [PATCH] [RFC v2] Drop all 00-INDEX files from Documentation/

[Jonathan Corbet]

On Tue, 4 Sep 2018 09:59:08 -0400
Steven Rostedt  wrote:

> On Tue, 4 Sep 2018 13:30:30 +0200
> Pavel Machek  wrote:
> 
> > I'd say this is still quite valueable, and it might be worth fixing,
> > rather then removing completely.  
> 
> I agree. Perhaps we should have a 00-DESCRIPTION file in each
> directory, and each file could start with a:
> 
>  DESCRIPTION: 
> 
> and then these files could be generated by those that have these tags.

I really don't want to hack up yet another documentation syntax and
processing scheme.  We already have one that does all of this and more.
That energy would be far better spent bringing the docs into the RST
hierarchy, IMO.

Thanks,

jon  (who is increasingly inclined to apply this patch)

Re: [PATCH] Documentation: Add powerpc options for spec_store_bypass_disable

[Jonathan Corbet]

On Tue, 10 Jul 2018 12:08:36 +1000
Michael Ellerman  wrote:

> Document the support for spec_store_bypass_disable that was added for
> powerpc in commit a048a07d7f45 ("powerpc/64s: Add support for a store
> forwarding barrier at kernel entry/exit").
> 
> Signed-off-by: Michael Ellerman 

Applied, thanks.

jon

Re: [PATCH 0/9] Fix references for some missing documentation files

[Jonathan Corbet]

On Tue, 26 Jun 2018 06:49:02 -0300
Mauro Carvalho Chehab  wrote:

> Having nothing to do while waiting for my plane to arrive while
> returning back from Japan, I ended by writing a small series of 
> patches meant to reduce the number of bad Documentation/* 
> links that are detected by:
>   ./scripts/documentation-file-ref-check

I've applied everything except the two networking patches, since I expect
those to go through Dave's tree.

Thanks,

jon

Re: [PATCH 00/32] docs/vm: convert to ReST format

[Jonathan Corbet]

On Sun, 15 Apr 2018 20:36:56 +0300
Mike Rapoport  wrote:

> I didn't mean we should keep it as unorganized jumble of stuff and I agree
> that splitting the documentation by audience is better because developers
> are already know how to find it :)
> 
> I just thought that putting the doc into the place should not be done
> immediately after mechanical ReST conversion but rather after improving the
> contents.

OK, this is fine.  I'll go ahead and apply the set, but then I'll be
watching to see that the other improvements come :)

In applying the set, there was a significant set of conflicts with
vm/hmm.rst; hopefully I've sorted those out properly.

Thanks,

jon

Re: [PATCH 00/32] docs/vm: convert to ReST format

[Jonathan Corbet]

Sorry for the silence, I'm pedaling as fast as I can, honest...

On Sun, 1 Apr 2018 09:38:58 +0300
Mike Rapoport  wrote:

> My thinking was to start with mechanical RST conversion and then to start
> working on the contents and ordering of the documentation. Some of the
> existing files, e.g. ksm.txt, can be moved as is into the appropriate
> places, others, like transhuge.txt should be at least split into admin/user
> and developer guides.
> 
> Another problem with many of the existing mm docs is that they are rather
> developer notes and it wouldn't be really straight forward to assign them
> to a particular topic.

All this sounds good.

> I believe that keeping the mm docs together will give better visibility of
> what (little) mm documentation we have and will make the updates easier.
> The documents that fit well into a certain topic could be linked there. For
> instance:

...but this sounds like just the opposite...?  

I've had this conversation with folks in a number of subsystems.
Everybody wants to keep their documentation together in one place - it's
easier for the developers after all.  But for the readers I think it's
objectively worse.  It perpetuates the mess that Documentation/ is, and
forces readers to go digging through all kinds of inappropriate material
in the hope of finding something that tells them what they need to know.

So I would *really* like to split the documentation by audience, as has
been done for a number of other kernel subsystems (and eventually all, I
hope).

I can go ahead and apply the RST conversion, that seems like a step in
the right direction regardless.  But I sure hope we don't really have to
keep it as an unorganized jumble of stuff...

Thanks,

jon

Re: [PATCH 00/32] docs/vm: convert to ReST format

[Jonathan Corbet]

On Wed, 21 Mar 2018 21:22:16 +0200
Mike Rapoport  wrote:

> These patches convert files in Documentation/vm to ReST format, add an
> initial index and link it to the top level documentation.
> 
> There are no contents changes in the documentation, except few spelling
> fixes. The relatively large diffstat stems from the indentation and
> paragraph wrapping changes.
> 
> I've tried to keep the formatting as consistent as possible, but I could
> miss some places that needed markup and add some markup where it was not
> necessary.

So I've been pondering on these for a bit.  It looks like a reasonable and
straightforward RST conversion, no real complaints there.  But I do have a
couple of concerns...

One is that, as we move documentation into RST, I'm really trying to
organize it a bit so that it is better tuned to the various audiences we
have.  For example, ksm.txt is going to be of interest to sysadmin types,
who might want to tune it.  mmu_notifier.txt is of interest to ...
somebody, but probably nobody who is thinking in user space.  And so on.

So I would really like to see this material split up and put into the
appropriate places in the RST hierarchy - admin-guide for administrative
stuff, core-api for kernel development topics, etc.  That, of course,
could be done separately from the RST conversion, but I suspect I know
what will (or will not) happen if we agree to defer that for now :)

The other is the inevitable merge conflicts that changing that many doc
files will create.  Sending the patches through Andrew could minimize
that, I guess, or at least make it his problem.  Alternatively, we could
try to do it as an end-of-merge-window sort of thing.  I can try to manage
that, but an ack or two from the mm crowd would be nice to have.

Thanks,

jon

Re: [PATCH][DOC] ppc/idle: Add documentation for powersave=off

[Jonathan Corbet]

On Fri, 2 Dec 2016 00:08:26 +1100
Balbir Singh  wrote:

> Update kernel-parameters.txt to add Documentation
> for powersave=off.

Applied to docs-next, thanks.

jon

Re: [PATCH V3 3/5] mm: mlock: Introduce VM_LOCKONFAULT and add mlock flags to enable it

[Jonathan Corbet]

On Thu, 9 Jul 2015 14:46:35 -0400
Eric B Munson emun...@akamai.com wrote:

  One other question...if I call mlock2(MLOCK_ONFAULT) on a range that
  already has resident pages, I believe that those pages will not be locked
  until they are reclaimed and faulted back in again, right?  I suspect that
  could be surprising to users.  
 
 That is the case.  I am looking into what it would take to find only the
 present pages in a range and lock them, if that is the behavior that is
 preferred I can include it in the updated series.

For whatever my $0.02 is worth, I think that should be done.  Otherwise
the mlock2() interface is essentially nondeterministic; you'll never
really know if a specific page is locked or not.

Thanks,

jon
___
Linuxppc-dev mailing list
Linuxppc-dev@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/linuxppc-dev

Re: [PATCH] Doc: powerpc: Fix typos in Documentation/powerpc

[Jonathan Corbet]

On Mon,  6 Jul 2015 23:41:57 +0900
Masanari Iida standby2...@gmail.com wrote:

 This patch fix some spelling typo found in Documentation/powerpc.

Applied (with Ian's ack) to the docs tree, thanks.

jon
___
Linuxppc-dev mailing list
Linuxppc-dev@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/linuxppc-dev

Re: [PATCH V3 3/5] mm: mlock: Introduce VM_LOCKONFAULT and add mlock flags to enable it

[Jonathan Corbet]

On Tue,  7 Jul 2015 13:03:41 -0400
Eric B Munson emun...@akamai.com wrote:

 This patch introduces the ability to request that pages are not
 pre-faulted, but are placed on the unevictable LRU when they are finally
 faulted in.  This can be done area at a time via the
 mlock2(MLOCK_ONFAULT) or the mlockall(MCL_ONFAULT) system calls.  These
 calls can be undone via munlock2(MLOCK_ONFAULT) or
 munlockall2(MCL_ONFAULT).

Quick, possibly dumb question: I've been beating my head against these for
a little bit, and I can't figure out what's supposed to happen in this
case:

mlock2(addr, len, MLOCK_ONFAULT);
munlock2(addr, len, MLOCK_LOCKED);

It looks to me like it will clear VM_LOCKED without actually unlocking any
pages.  Is that the intended result?

Thanks,

jon
___
Linuxppc-dev mailing list
Linuxppc-dev@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/linuxppc-dev

Re: [PATCH V3 3/5] mm: mlock: Introduce VM_LOCKONFAULT and add mlock flags to enable it

[Jonathan Corbet]

On Wed, 8 Jul 2015 16:34:56 -0400
Eric B Munson emun...@akamai.com wrote:

  Quick, possibly dumb question: I've been beating my head against these for
  a little bit, and I can't figure out what's supposed to happen in this
  case:
  
  mlock2(addr, len, MLOCK_ONFAULT);
  munlock2(addr, len, MLOCK_LOCKED);
  
  It looks to me like it will clear VM_LOCKED without actually unlocking any
  pages.  Is that the intended result?  
 
 This is not quite right, what happens when you call munlock2(addr, len,
 MLOCK_LOCKED); is we call apply_vma_flags(addr, len, VM_LOCKED, false).

From your explanation, it looks like what I said *was* right...what I was
missing was the fact that VM_LOCKED isn't set in the first place.  So that
call would be a no-op, clearing a flag that's already cleared.

One other question...if I call mlock2(MLOCK_ONFAULT) on a range that
already has resident pages, I believe that those pages will not be locked
until they are reclaimed and faulted back in again, right?  I suspect that
could be surprising to users.

Thanks,

jon
___
Linuxppc-dev mailing list
Linuxppc-dev@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/linuxppc-dev

Re: [PATCH linux-next] Documentation: Build mic/mpssd only for x86_64

[Jonathan Corbet]

On Thu,  4 Dec 2014 13:27:29 -0800
Ashutosh Dixit ashutosh.di...@intel.com wrote:

 mic/mpssd along with MIC drivers are currently only usable on
 x86_64. So build mic/mpssd only for x86_64 to avoid build breaks on
 big-endian systems.

I can certainly apply this.  But it seems to me that this kind of code
doesn't belong in the documentation directory.  How about a patch to move
it to tools/ ?

jon
___
Linuxppc-dev mailing list
Linuxppc-dev@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/linuxppc-dev