Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Andrea Parri]

On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> On Thu, 10 May 2018 14:23:35 +0200
> Andrea Parri <andrea.pa...@amarulasolutions.com> wrote:
> 
> > only
> > remember that other people (including some developers running into the
> > "disadventure" of opening an RST doc. from their preferred text editor
> > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > guess...") _use_ such doc. and _do care_ about it, and that what might
> > be an improvement for some people might look as "vandalizing" to others.
> 
> If you have an example of a place where use of a web browser has been
> made mandatory, please point it out.  Avoiding that was at the top of the
> list of explicit requirements.

That's all I need.


>Surely an extra colon is not going to
> force you to run screaming to the protective embrace of Firefox...?

Let me put it in these terms: I believe that that extra colon (or the
"diagram" keywork) is not going to improve/help my use of the doc. ;D

  Andrea


> 
> Thanks,
> 
> jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Andrea Parri]

On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 10:41:20 +0200
> Peter Zijlstra  wrote:
> 
> > > This is easily done by using "::" instead of just ":".  
> > 
> > And I'll voice my objection once again. This makes a regular comment
> > worse. This rst stuff is utter shit for making normal text files less
> > readable in your favourite text editor.
> > 
> > If this gets merged, I'll simply remove that spurious ':' the next time
> > I'm near that comment.
> 
> Seriously, Peter?
> 
> It's a simple colon.  It goes along with the /** marker for kerneldoc
> comments and the @ markers found within them, both of which you seem to
> have found a way to live with.
> 
> The RST work was discussed for a year before we even started.  It has
> brought in the efforts of a large number of developers, all of whom see
> the value in actually caring about our documentation and making it
> accessible to a much larger group of readers.  And it has all happened
> while preserving the primacy of the plain-text documentation.
> 
> You're not the only consumer of the docs.  You may not appreciate the
> improvements that have come, but others certainly do.  I do hope that you
> can find it in youself to avoid vandalizing things for everybody else ...?

You wrote it:  the fact that some people (including its developers) see
a value in the RST work or the fact that such work made the kernel doc.
accessible to a larger group of readers are not in question here;  only
remember that other people (including some developers running into the
"disadventure" of opening an RST doc. from their preferred text editor
and being brought to conclude:  "WTH!  I need to open a web browser, I
guess...") _use_ such doc. and _do care_ about it, and that what might
be an improvement for some people might look as "vandalizing" to others.

We're talking about readability/accessibility here, but I think similar
considerations apply to other aspects of the doc. such as availability/
completeness (yes, I did hear developers arguing "I won't write such a
doc., because...") and consistency (w.r.t. the doc. itself and sources).

  Andrea


> 
> Thanks,
> 
> jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 08/11] docs: refcount-vs-atomic.rst: prefix url with https

[Andrea Parri]

Hi Mauro,

On Wed, May 09, 2018 at 10:18:51AM -0300, Mauro Carvalho Chehab wrote:
> There's a github URL there, but it is not prefixed by https.
> Add a prefix, to avoid false-positives with:
>   ./scripts/documentation-file-ref-check
> 
> As a side effect, Sphinx should also generate a cross-ref.
> 
> Signed-off-by: Mauro Carvalho Chehab 

There seems to be a "conflicting" patch ("applied" according to Jon):


http://lkml.kernel.org/r/1525468309-5310-1-git-send-email-andrea.pa...@amarulasolutions.com

Let me stress here that the github repo. is out-of-date (and we have
no plans to keep that in sync with mainline).

  Andrea


> ---
>  Documentation/core-api/refcount-vs-atomic.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
> b/Documentation/core-api/refcount-vs-atomic.rst
> index 83351c258cdb..185d659e350a 100644
> --- a/Documentation/core-api/refcount-vs-atomic.rst
> +++ b/Documentation/core-api/refcount-vs-atomic.rst
> @@ -17,7 +17,7 @@ in order to help maintainers validate their code against 
> the change in
>  these memory ordering guarantees.
>  
>  The terms used through this document try to follow the formal LKMM defined in
> -github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> +https://github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
>  
>  memory-barriers.txt and atomic_t.txt provide more background to the
>  memory ordering in general and for atomic operations specifically.
> -- 
> 2.17.0
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Andrea Parri]

On Tue, May 08, 2018 at 03:28:51PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 8 May 2018 15:05:07 -0300
> Mauro Carvalho Chehab  escreveu:
> 
> > Em Tue, 08 May 2018 17:40:56 +0300
> > Jani Nikula  escreveu:

[...]

> > > Side note, there's scripts/documentation-file-ref-check to grep the
> > > kernel tree for things that look like file references to Documentation/*
> > > and complain if they don't exist.
> > > 
> > > I get about 350+ hits with that, patches welcome! ;)  
> > 
> > This small script fixes a bunch of such errors:
> > 
> > scripts/documentation-file-ref-check 2>broken_refs
> > for i in $(cat broken_refs|cut -d: -f 2|grep -v 
> > devicetree|sort|uniq|grep \\.txt); do
> > rst=$(basename $i)
> > rst=${rst/.txt/.rst}
> > f=$(find . -name $rst)
> > f=${f#./}
> > if [ "$f" != "" ]; then
> > echo "Replacing $i to $f"
> > for j in $(git grep -l $i); do
> > sed "s@$i@$f@g" -i $j
> > done
> > fi
> > done
> 
> It follows an improvement to the above script that shows also what
> it didn't find as a ReST file, and the ones that have common names
> with multiple matches.
> 
> I guess we could integrate something like that at 
> scripts/documentation-file-ref-check, in order to allow auto-correcting
> renamed .txt files.

FWIW, this would be more than welcome with me; thank you,

  Andrea


> 
> Regards,
> Mauro
> 
> 
> #!/bin/bash
> 
> scripts/documentation-file-ref-check 2>broken_refs
> for i in $(cat broken_refs|cut -d: -f 2|grep -v devicetree|sort|uniq|grep 
> \\.txt); do
> rst=$(basename $i)
> rst=${rst/.txt/.rst}
> f=$(find . -name $rst)
> 
> if [ "$f" == "" ]; then
> echo "ERROR: Didn't find a .rst replacement for $i"
> elif [ "$(echo $f | grep ' ')" != "" ]; then
> echo "ERROR: Found multiple possible replacements for $i:"
> for j in $f; do
> echo "$j"
> done
> else
> echo "Replacing $i to $f"
> f=${f#./}
> for j in $(git grep -l $i); do
> sed "s@$i@$f@g" -i $j
> done
> fi
> done
> 
> 
> Thanks,
> Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Andrea Parri]

On Tue, May 08, 2018 at 10:04:08AM -0600, Jonathan Corbet wrote:
> On Mon,  7 May 2018 06:35:41 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > The cachetlb.txt is already in ReST format. So, move it to the
> > core-api guide, where it belongs.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> 
> I think we could do a better job of this by integrating it with the
> kerneldoc comments.  Meanwhile, though, this is a step in the right
> direction, so I've applied it, thanks.

This depends on what you mean by "the right direction": IMO, breaking
in-sources references and get_maintainer.pl does not qualify as such.

  Andrea


> 
> jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Andrea Parri]

On Tue, May 08, 2018 at 06:02:42PM +0200, Andrea Parri wrote:
> Hi Jani,
> 
> On Tue, May 08, 2018 at 05:40:56PM +0300, Jani Nikula wrote:
> > On Mon, 07 May 2018, Andrea Parri <andrea.pa...@amarulasolutions.com> wrote:
> > > On Mon, May 07, 2018 at 06:35:41AM -0300, Mauro Carvalho Chehab wrote:
> > >> The cachetlb.txt is already in ReST format. So, move it to the
> > >> core-api guide, where it belongs.
> > >> 
> > >> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
> > >> ---
> > >>  Documentation/00-INDEX| 2 --
> > >>  Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
> > >>  Documentation/core-api/index.rst  | 1 +
> > >>  Documentation/memory-barriers.txt | 2 +-
> > >>  Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
> > >>  5 files changed, 3 insertions(+), 4 deletions(-)
> > >>  rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)
> > >
> > > I see a few "inline" references to the .txt file in -rc4 (see below):
> > > I am not sure if you managed to update them too.
> > 
> > Side note, there's scripts/documentation-file-ref-check to grep the
> > kernel tree for things that look like file references to Documentation/*
> > and complain if they don't exist.
> > 
> > I get about 350+ hits with that, patches welcome! ;)
> 
> Thanks for pointing out the script/results.
> 
> It's also worth stressing, I think, the fact that some of those are from
> the MAINTAINERS file; I stumbled accross one of them yesterday:
> 
>   
> http://lkml.kernel.org/r/1525707655-3542-1-git-send-email-andrea.pa...@amarulasolutions.com
> 
> False positives apart (e.g., the four references in tools/memory-model/),
> those are regressions from my POV: please do not (consiously) merge more!

s/four/five

  Andrea


> 
>   Andrea
> 
> 
> > 
> > 
> > BR,
> > Jani.
> > 
> > 
> > >
> > > ./arch/microblaze/include/asm/cacheflush.h:/* Look at 
> > > Documentation/cachetlb.txt */
> > > ./arch/unicore32/include/asm/cacheflush.h: *  See 
> > > Documentation/cachetlb.txt for more information.
> > > ./arch/arm64/include/asm/cacheflush.h: *  See Documentation/cachetlb.txt 
> > > for more information. Please note that
> > > ./arch/arm/include/asm/cacheflush.h: *See Documentation/cachetlb.txt 
> > > for more information.
> > > ./arch/xtensa/include/asm/cacheflush.h: * (see also 
> > > Documentation/cachetlb.txt)
> > > ./arch/xtensa/include/asm/cacheflush.h:/* This is not required, see 
> > > Documentation/cachetlb.txt */
> > >
> > >   Andrea
> > >
> > >
> > >> 
> > >> diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
> > >> index 53699c79ee54..04074059bcdc 100644
> > >> --- a/Documentation/00-INDEX
> > >> +++ b/Documentation/00-INDEX
> > >> @@ -76,8 +76,6 @@ bus-devices/
> > >>  - directory with info on TI GPMC (General Purpose Memory 
> > >> Controller)
> > >>  bus-virt-phys-mapping.txt
> > >>  - how to access I/O mapped memory from within device drivers.
> > >> -cachetlb.txt
> > >> -- describes the cache/TLB flushing interfaces Linux uses.
> > >>  cdrom/
> > >>  - directory with information on the CD-ROM drivers that Linux 
> > >> has.
> > >>  cgroup-v1/
> > >> diff --git a/Documentation/cachetlb.txt 
> > >> b/Documentation/core-api/cachetlb.rst
> > >> similarity index 100%
> > >> rename from Documentation/cachetlb.txt
> > >> rename to Documentation/core-api/cachetlb.rst
> > >> diff --git a/Documentation/core-api/index.rst 
> > >> b/Documentation/core-api/index.rst
> > >> index c670a8031786..d4d71ee564ae 100644
> > >> --- a/Documentation/core-api/index.rst
> > >> +++ b/Documentation/core-api/index.rst
> > >> @@ -14,6 +14,7 @@ Core utilities
> > >> kernel-api
> > >> assoc_array
> > >> atomic_ops
> > >> +   cachetlb
> > >> refcount-vs-atomic
> > >> cpu_hotplug
> > >> idr
> > >> diff --git a/Documentation/memory-barriers.txt 
> > >> b/Documentation/memory-barriers.txt
> > >> index 6dafc8085acc..983249906fc6 100644
> > >> -

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Andrea Parri]

Hi Jani,

On Tue, May 08, 2018 at 05:40:56PM +0300, Jani Nikula wrote:
> On Mon, 07 May 2018, Andrea Parri <andrea.pa...@amarulasolutions.com> wrote:
> > On Mon, May 07, 2018 at 06:35:41AM -0300, Mauro Carvalho Chehab wrote:
> >> The cachetlb.txt is already in ReST format. So, move it to the
> >> core-api guide, where it belongs.
> >> 
> >> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
> >> ---
> >>  Documentation/00-INDEX| 2 --
> >>  Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
> >>  Documentation/core-api/index.rst  | 1 +
> >>  Documentation/memory-barriers.txt | 2 +-
> >>  Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
> >>  5 files changed, 3 insertions(+), 4 deletions(-)
> >>  rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)
> >
> > I see a few "inline" references to the .txt file in -rc4 (see below):
> > I am not sure if you managed to update them too.
> 
> Side note, there's scripts/documentation-file-ref-check to grep the
> kernel tree for things that look like file references to Documentation/*
> and complain if they don't exist.
> 
> I get about 350+ hits with that, patches welcome! ;)

Thanks for pointing out the script/results.

It's also worth stressing, I think, the fact that some of those are from
the MAINTAINERS file; I stumbled accross one of them yesterday:

  
http://lkml.kernel.org/r/1525707655-3542-1-git-send-email-andrea.pa...@amarulasolutions.com

False positives apart (e.g., the four references in tools/memory-model/),
those are regressions from my POV: please do not (consiously) merge more!

  Andrea


> 
> 
> BR,
> Jani.
> 
> 
> >
> > ./arch/microblaze/include/asm/cacheflush.h:/* Look at 
> > Documentation/cachetlb.txt */
> > ./arch/unicore32/include/asm/cacheflush.h: *See 
> > Documentation/cachetlb.txt for more information.
> > ./arch/arm64/include/asm/cacheflush.h: *See Documentation/cachetlb.txt 
> > for more information. Please note that
> > ./arch/arm/include/asm/cacheflush.h: *  See Documentation/cachetlb.txt 
> > for more information.
> > ./arch/xtensa/include/asm/cacheflush.h: * (see also 
> > Documentation/cachetlb.txt)
> > ./arch/xtensa/include/asm/cacheflush.h:/* This is not required, see 
> > Documentation/cachetlb.txt */
> >
> >   Andrea
> >
> >
> >> 
> >> diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
> >> index 53699c79ee54..04074059bcdc 100644
> >> --- a/Documentation/00-INDEX
> >> +++ b/Documentation/00-INDEX
> >> @@ -76,8 +76,6 @@ bus-devices/
> >>- directory with info on TI GPMC (General Purpose Memory Controller)
> >>  bus-virt-phys-mapping.txt
> >>- how to access I/O mapped memory from within device drivers.
> >> -cachetlb.txt
> >> -  - describes the cache/TLB flushing interfaces Linux uses.
> >>  cdrom/
> >>- directory with information on the CD-ROM drivers that Linux has.
> >>  cgroup-v1/
> >> diff --git a/Documentation/cachetlb.txt 
> >> b/Documentation/core-api/cachetlb.rst
> >> similarity index 100%
> >> rename from Documentation/cachetlb.txt
> >> rename to Documentation/core-api/cachetlb.rst
> >> diff --git a/Documentation/core-api/index.rst 
> >> b/Documentation/core-api/index.rst
> >> index c670a8031786..d4d71ee564ae 100644
> >> --- a/Documentation/core-api/index.rst
> >> +++ b/Documentation/core-api/index.rst
> >> @@ -14,6 +14,7 @@ Core utilities
> >> kernel-api
> >> assoc_array
> >> atomic_ops
> >> +   cachetlb
> >> refcount-vs-atomic
> >> cpu_hotplug
> >> idr
> >> diff --git a/Documentation/memory-barriers.txt 
> >> b/Documentation/memory-barriers.txt
> >> index 6dafc8085acc..983249906fc6 100644
> >> --- a/Documentation/memory-barriers.txt
> >> +++ b/Documentation/memory-barriers.txt
> >> @@ -2903,7 +2903,7 @@ is discarded from the CPU's cache and reloaded.  To 
> >> deal with this, the
> >>  appropriate part of the kernel must invalidate the overlapping bits of the
> >>  cache on each CPU.
> >>  
> >> -See Documentation/cachetlb.txt for more information on cache management.
> >> +See Documentation/core-api/cachetlb.rst for more information on cache 
> >> management.
> >>  
> >>  
> >>  CACHE COHERENCY VS MMIO
> >

[PATCH] certificate handling: Update references to the documentation

[Andrea Parri]

Commit 94e980cc45f2b2 ("Documentation/module-signing.txt: convert to
ReST markup") converted the .txt doc. to ReST markup, but it did not
update the references to the doc. (including in MAINTAINERS).

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
---
 MAINTAINERS   | 2 +-
 certs/Kconfig | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index df6e9bb2559af..803d4b4ff5f1d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3347,7 +3347,7 @@ M:David Howells <dhowe...@redhat.com>
 M: David Woodhouse <dw...@infradead.org>
 L: keyri...@vger.kernel.org
 S: Maintained
-F: Documentation/module-signing.txt
+F: Documentation/admin-guide/module-signing.rst
 F: certs/
 F: scripts/sign-file.c
 F: scripts/extract-cert.c
diff --git a/certs/Kconfig b/certs/Kconfig
index 5f7663df6e8e3..c94e93d8bccf0 100644
--- a/certs/Kconfig
+++ b/certs/Kconfig
@@ -13,7 +13,7 @@ config MODULE_SIG_KEY
 
  If this option is unchanged from its default "certs/signing_key.pem",
  then the kernel will automatically generate the private key and
- certificate as described in Documentation/module-signing.txt
+ certificate as described in 
Documentation/admin-guide/module-signing.rst
 
 config SYSTEM_TRUSTED_KEYRING
bool "Provide system-wide ring of trusted keys"
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 07/18] docs: core-api: add circular-buffers documentation

[Andrea Parri]

On Mon, May 07, 2018 at 06:35:43AM -0300, Mauro Carvalho Chehab wrote:
> The circular-buffers.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/00-INDEX  | 2 --
>  .../{circular-buffers.txt => core-api/circular-buffers.rst} | 0
>  Documentation/core-api/index.rst| 1 +
>  Documentation/memory-barriers.txt   | 2 +-
>  Documentation/translations/ko_KR/memory-barriers.txt| 2 +-
>  5 files changed, 3 insertions(+), 4 deletions(-)
>  rename Documentation/{circular-buffers.txt => core-api/circular-buffers.rst} 
> (100%)

Similarly:

./include/linux/circ_buf.h: * See Documentation/circular-buffers.txt for more 
information.
./drivers/lightnvm/pblk-rb.c: * (Documentation/circular-buffers.txt)
./drivers/media/dvb-core/dvb_ringbuffer.c:   * for memory barriers also see 
Documentation/circular-buffers.txt

  Andrea


> 
> diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
> index c6b81ef9827b..a9dd1384d8e3 100644
> --- a/Documentation/00-INDEX
> +++ b/Documentation/00-INDEX
> @@ -80,8 +80,6 @@ cdrom/
>   - directory with information on the CD-ROM drivers that Linux has.
>  cgroup-v1/
>   - cgroups v1 features, including cpusets and memory controller.
> -circular-buffers.txt
> - - how to make use of the existing circular buffer infrastructure
>  clk.txt
>   - info on the common clock framework
>  cma/
> diff --git a/Documentation/circular-buffers.txt 
> b/Documentation/core-api/circular-buffers.rst
> similarity index 100%
> rename from Documentation/circular-buffers.txt
> rename to Documentation/core-api/circular-buffers.rst
> diff --git a/Documentation/core-api/index.rst 
> b/Documentation/core-api/index.rst
> index d4d71ee564ae..3864de589126 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -26,6 +26,7 @@ Core utilities
> genalloc
> errseq
> printk-formats
> +   circular-buffers
>  
>  Interfaces for kernel debugging
>  ===
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index 983249906fc6..33b8bc9573f8 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -3083,7 +3083,7 @@ CIRCULAR BUFFERS
>  Memory barriers can be used to implement circular buffering without the need
>  of a lock to serialise the producer with the consumer.  See:
>  
> - Documentation/circular-buffers.txt
> + Documentation/core-api/circular-buffers.rst
>  
>  for details.
>  
> diff --git a/Documentation/translations/ko_KR/memory-barriers.txt 
> b/Documentation/translations/ko_KR/memory-barriers.txt
> index 081937577c1a..2ec5fe0c9cf4 100644
> --- a/Documentation/translations/ko_KR/memory-barriers.txt
> +++ b/Documentation/translations/ko_KR/memory-barriers.txt
> @@ -3023,7 +3023,7 @@ smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다.
>  동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다.  더 자세한 내용을
>  위해선 다음을 참고하세요:
>  
> - Documentation/circular-buffers.txt
> + Documentation/core-api/circular-buffers.rst
>  
>  
>  =
> -- 
> 2.17.0
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Andrea Parri]

On Mon, May 07, 2018 at 06:35:41AM -0300, Mauro Carvalho Chehab wrote:
> The cachetlb.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/00-INDEX| 2 --
>  Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
>  Documentation/core-api/index.rst  | 1 +
>  Documentation/memory-barriers.txt | 2 +-
>  Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
>  5 files changed, 3 insertions(+), 4 deletions(-)
>  rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)

I see a few "inline" references to the .txt file in -rc4 (see below):
I am not sure if you managed to update them too.

./arch/microblaze/include/asm/cacheflush.h:/* Look at 
Documentation/cachetlb.txt */
./arch/unicore32/include/asm/cacheflush.h: *See Documentation/cachetlb.txt 
for more information.
./arch/arm64/include/asm/cacheflush.h: *See Documentation/cachetlb.txt 
for more information. Please note that
./arch/arm/include/asm/cacheflush.h: *  See Documentation/cachetlb.txt for more 
information.
./arch/xtensa/include/asm/cacheflush.h: * (see also Documentation/cachetlb.txt)
./arch/xtensa/include/asm/cacheflush.h:/* This is not required, see 
Documentation/cachetlb.txt */

  Andrea


> 
> diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
> index 53699c79ee54..04074059bcdc 100644
> --- a/Documentation/00-INDEX
> +++ b/Documentation/00-INDEX
> @@ -76,8 +76,6 @@ bus-devices/
>   - directory with info on TI GPMC (General Purpose Memory Controller)
>  bus-virt-phys-mapping.txt
>   - how to access I/O mapped memory from within device drivers.
> -cachetlb.txt
> - - describes the cache/TLB flushing interfaces Linux uses.
>  cdrom/
>   - directory with information on the CD-ROM drivers that Linux has.
>  cgroup-v1/
> diff --git a/Documentation/cachetlb.txt b/Documentation/core-api/cachetlb.rst
> similarity index 100%
> rename from Documentation/cachetlb.txt
> rename to Documentation/core-api/cachetlb.rst
> diff --git a/Documentation/core-api/index.rst 
> b/Documentation/core-api/index.rst
> index c670a8031786..d4d71ee564ae 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -14,6 +14,7 @@ Core utilities
> kernel-api
> assoc_array
> atomic_ops
> +   cachetlb
> refcount-vs-atomic
> cpu_hotplug
> idr
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index 6dafc8085acc..983249906fc6 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -2903,7 +2903,7 @@ is discarded from the CPU's cache and reloaded.  To 
> deal with this, the
>  appropriate part of the kernel must invalidate the overlapping bits of the
>  cache on each CPU.
>  
> -See Documentation/cachetlb.txt for more information on cache management.
> +See Documentation/core-api/cachetlb.rst for more information on cache 
> management.
>  
>  
>  CACHE COHERENCY VS MMIO
> diff --git a/Documentation/translations/ko_KR/memory-barriers.txt 
> b/Documentation/translations/ko_KR/memory-barriers.txt
> index 0a0930ab4156..081937577c1a 100644
> --- a/Documentation/translations/ko_KR/memory-barriers.txt
> +++ b/Documentation/translations/ko_KR/memory-barriers.txt
> @@ -2846,7 +2846,7 @@ CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮
>  문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는
>  비트들을 무효화 시켜야 합니다.
>  
> -캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를
> +캐시 관리에 대한 더 많은 정보를 위해선 Documentation/core-api/cachetlb.rst 를
>  참고하세요.
>  
>  
> -- 
> 2.17.0
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v3 1/6] Documentation/features: Add script that refreshes the arch support status files in place

[Andrea Parri]

Provides the script:

Documentation/features/scripts/features-refresh.sh

which operates on the arch-support.txt files and refreshes them in place.

This way [1],

   "[...] we soft- decouple the refreshing of the entries from the
introduction of the features, while still making it all easy to
keep sync and to extend."

[1] http://lkml.kernel.org/r/20180328122211.GA25420@andrea

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 Documentation/features/scripts/features-refresh.sh | 98 ++
 1 file changed, 98 insertions(+)
 create mode 100755 Documentation/features/scripts/features-refresh.sh

diff --git a/Documentation/features/scripts/features-refresh.sh 
b/Documentation/features/scripts/features-refresh.sh
new file mode 100755
index 0..9e72d38a0720e
--- /dev/null
+++ b/Documentation/features/scripts/features-refresh.sh
@@ -0,0 +1,98 @@
+#
+# Small script that refreshes the kernel feature support status in place.
+#
+
+for F_FILE in Documentation/features/*/*/arch-support.txt; do
+   F=$(grep "^# Kconfig:" "$F_FILE" | cut -c26-)
+
+   #
+   # Each feature F is identified by a pair (O, K), where 'O' can
+   # be either the empty string (for 'nop') or "not" (the logical
+   # negation operator '!'); other operators are not supported.
+   #
+   O=""
+   K=$F
+   if [[ "$F" == !* ]]; then
+   O="not"
+   K=$(echo $F | sed -e 's/^!//g')
+   fi
+
+   #
+   # F := (O, K) is 'valid' iff there is a Kconfig file (for some
+   # arch) which contains K.
+   #
+   # Notice that this definition entails an 'asymmetry' between
+   # the case 'O = ""' and the case 'O = "not"'. E.g., F may be
+   # _invalid_ if:
+   #
+   # [case 'O = ""']
+   #   1) no arch provides support for F,
+   #   2) K does not exist (e.g., it was renamed/mis-typed);
+   #
+   # [case 'O = "not"']
+   #   3) all archs provide support for F,
+   #   4) as in (2).
+   #
+   # The rationale for adopting this definition (and, thus, for
+   # keeping the asymmetry) is:
+   #
+   #   We want to be able to 'detect' (2) (or (4)).
+   #
+   # (1) and (3) may further warn the developers about the fact
+   # that K can be removed.
+   #
+   F_VALID="false"
+   for ARCH_DIR in arch/*/; do
+   K_FILES=$(find $ARCH_DIR -name "Kconfig*")
+   K_GREP=$(grep "$K" $K_FILES)
+   if [ ! -z "$K_GREP" ]; then
+   F_VALID="true"
+   break
+   fi
+   done
+   if [ "$F_VALID" = "false" ]; then
+   printf "WARNING: '%s' is not a valid Kconfig\n" "$F"
+   fi
+
+   T_FILE="$F_FILE.tmp"
+   grep "^#" $F_FILE > $T_FILE
+   echo "---" >> $T_FILE
+   echo "| arch |status|" >> $T_FILE
+   echo "---" >> $T_FILE
+   for ARCH_DIR in arch/*/; do
+   ARCH=$(echo $ARCH_DIR | sed -e 's/arch//g' | sed -e 's/\///g')
+   K_FILES=$(find $ARCH_DIR -name "Kconfig*")
+   K_GREP=$(grep "$K" $K_FILES)
+   #
+   # Arch support status values for (O, K) are updated according
+   # to the following rules.
+   #
+   #   - ("", K) is 'supported by a given arch', if there is a
+   # Kconfig file for that arch which contains K;
+   #
+   #   - ("not", K) is 'supported by a given arch', if there is
+   # no Kconfig file for that arch which contains K;
+   #
+   #   - otherwise: preserve the previous status value (if any),
+   #default to 'not yet supported'.
+   #
+   # Notice that, according these rules, invalid features may be
+   # updated/modified.
+   #
+   if [ "$O" = "" ] && [ ! -z "$K_GREP" ]; then
+   printf "|%12s: |  ok  |\n" "$ARCH" >> $T_FILE
+   elif [ "$O" = "not" ] && [ -z "$K_GREP" ]; then
+   printf "|%12s: |  ok  |\n" "$ARCH" >> $T_FILE
+   else
+   S=$(grep -v "^#" "

[RFC PATCH v3 4/6] Documentation/features/locking: Use '!RWSEM_GENERIC_SPINLOCK' as Kconfig for 'rwsem-optimized'

[Andrea Parri]

Uses '!RWSEM_GENERIC_SPINLOCK' in place of 'Optimized asm/rwsem.h' as
Kconfig for 'rwsem-optimized': the new Kconfig expresses this feature
equivalently, while also enabling the script 'features-refresh.sh' to
operate on the corresponding arch support status file. Also refreshes
the status matrix by using the script 'features-refresh.sh'.

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 Documentation/features/locking/rwsem-optimized/arch-support.txt | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt 
b/Documentation/features/locking/rwsem-optimized/arch-support.txt
index 8afe24ffa3ab4..e54b1f1a8091d 100644
--- a/Documentation/features/locking/rwsem-optimized/arch-support.txt
+++ b/Documentation/features/locking/rwsem-optimized/arch-support.txt
@@ -1,6 +1,6 @@
 #
 # Feature name:  rwsem-optimized
-# Kconfig:   Optimized asm/rwsem.h
+# Kconfig:   !RWSEM_GENERIC_SPINLOCK
 # description:   arch provides optimized rwsem APIs
 #
 ---
@@ -8,8 +8,8 @@
 ---
 |   alpha: |  ok  |
 | arc: | TODO |
-| arm: | TODO |
-|   arm64: | TODO |
+| arm: |  ok  |
+|   arm64: |  ok  |
 | c6x: | TODO |
 |   h8300: | TODO |
 | hexagon: | TODO |
@@ -26,7 +26,7 @@
 |s390: |  ok  |
 |  sh: |  ok  |
 |   sparc: |  ok  |
-|  um: | TODO |
+|  um: |  ok  |
 |   unicore32: | TODO |
 | x86: |  ok  |
 |  xtensa: |  ok  |
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v3 2/6] Documentation/features: Refresh the arch support status files in place

[Andrea Parri]

Now that the script 'features-refresh.sh' is available, uses this script
to refresh all the arch-support.txt files in place.

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 Documentation/features/core/BPF-JIT/arch-support.txt   |  2 ++
 .../features/core/generic-idle-thread/arch-support.txt |  4 +++-
 Documentation/features/core/jump-labels/arch-support.txt   |  2 ++
 Documentation/features/core/tracehook/arch-support.txt |  2 ++
 Documentation/features/debug/KASAN/arch-support.txt|  4 +++-
 Documentation/features/debug/gcov-profile-all/arch-support.txt |  2 ++
 Documentation/features/debug/kgdb/arch-support.txt |  4 +++-
 .../features/debug/kprobes-on-ftrace/arch-support.txt  |  2 ++
 Documentation/features/debug/kprobes/arch-support.txt  |  4 +++-
 Documentation/features/debug/kretprobes/arch-support.txt   |  4 +++-
 Documentation/features/debug/optprobes/arch-support.txt|  4 +++-
 Documentation/features/debug/stackprotector/arch-support.txt   |  2 ++
 Documentation/features/debug/uprobes/arch-support.txt  |  6 --
 .../features/debug/user-ret-profiler/arch-support.txt  |  2 ++
 Documentation/features/io/dma-api-debug/arch-support.txt   |  2 ++
 Documentation/features/io/dma-contiguous/arch-support.txt  |  4 +++-
 Documentation/features/io/sg-chain/arch-support.txt|  2 ++
 Documentation/features/lib/strncasecmp/arch-support.txt|  2 ++
 Documentation/features/locking/cmpxchg-local/arch-support.txt  |  4 +++-
 Documentation/features/locking/lockdep/arch-support.txt|  4 +++-
 Documentation/features/locking/queued-rwlocks/arch-support.txt | 10 ++
 .../features/locking/queued-spinlocks/arch-support.txt |  8 +---
 .../features/locking/rwsem-optimized/arch-support.txt  |  2 ++
 Documentation/features/perf/kprobes-event/arch-support.txt |  6 --
 Documentation/features/perf/perf-regs/arch-support.txt |  4 +++-
 Documentation/features/perf/perf-stackdump/arch-support.txt|  4 +++-
 .../features/sched/membarrier-sync-core/arch-support.txt   |  2 ++
 Documentation/features/sched/numa-balancing/arch-support.txt   |  6 --
 Documentation/features/seccomp/seccomp-filter/arch-support.txt |  6 --
 .../features/time/arch-tick-broadcast/arch-support.txt |  4 +++-
 Documentation/features/time/clockevents/arch-support.txt   |  4 +++-
 Documentation/features/time/context-tracking/arch-support.txt  |  2 ++
 Documentation/features/time/irq-time-acct/arch-support.txt |  4 +++-
 .../features/time/modern-timekeeping/arch-support.txt  |  2 ++
 Documentation/features/time/virt-cpuacct/arch-support.txt  |  2 ++
 Documentation/features/vm/ELF-ASLR/arch-support.txt|  4 +++-
 Documentation/features/vm/PG_uncached/arch-support.txt |  2 ++
 Documentation/features/vm/THP/arch-support.txt |  2 ++
 Documentation/features/vm/TLB/arch-support.txt |  2 ++
 Documentation/features/vm/huge-vmap/arch-support.txt   |  2 ++
 Documentation/features/vm/ioremap_prot/arch-support.txt|  2 ++
 Documentation/features/vm/numa-memblock/arch-support.txt   |  4 +++-
 Documentation/features/vm/pte_special/arch-support.txt |  2 ++
 43 files changed, 117 insertions(+), 31 deletions(-)

diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt 
b/Documentation/features/core/BPF-JIT/arch-support.txt
index 0b96b4e1e7d4a..d277f971ccd6b 100644
--- a/Documentation/features/core/BPF-JIT/arch-support.txt
+++ b/Documentation/features/core/BPF-JIT/arch-support.txt
@@ -17,10 +17,12 @@
 |m68k: | TODO |
 |  microblaze: | TODO |
 |mips: |  ok  |
+|   nds32: | TODO |
 |   nios2: | TODO |
 |openrisc: | TODO |
 |  parisc: | TODO |
 | powerpc: |  ok  |
+|   riscv: | TODO |
 |s390: |  ok  |
 |  sh: | TODO |
 |   sparc: |  ok  |
diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt 
b/Documentation/features/core/generic-idle-thread/arch-support.txt
index 372a2b18a6172..0ef6acdb991c7 100644
--- a/Documentation/features/core/generic-idle-thread/arch-support.txt
+++ b/Documentation/features/core/generic-idle-thread/arch-support.txt
@@ -17,10 +17,12 @@
 |m68k: | TODO |
 |  microblaze: | TODO |
 |mips: |  ok  |
+|   nds32: | TODO |
 |   nios2: | TODO |
-|openrisc: | TODO |
+|openrisc: |  ok  |
 |  parisc: |  ok  |
 | powerpc: |  ok  |
+|   riscv: |  ok  |
 |s390: |  ok  |
 |  sh: |  ok  |
 |   sparc: |  ok  |
diff --git a/Documentation/features/core/jump-labels/arch-support.txt 

[RFC PATCH v3 3/6] Documentation/features/core: Add arch support status files for 'cBPF-JIT' and 'eBPF-JIT'

[Andrea Parri]

Commit 606b5908e split 'HAVE_BPF_JIT' into cBPF and eBPF variant.
Adds arch support status files for the new variants, and removes the
status file corresponding to 'HAVE_BPT_JIT'. The new status matrices
were auto-generated using the script 'features-refresh.sh'.

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 .../features/core/BPF-JIT/arch-support.txt | 33 --
 .../features/core/cBPF-JIT/arch-support.txt| 33 ++
 .../features/core/eBPF-JIT/arch-support.txt| 33 ++
 3 files changed, 66 insertions(+), 33 deletions(-)
 delete mode 100644 Documentation/features/core/BPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/cBPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/eBPF-JIT/arch-support.txt

diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt 
b/Documentation/features/core/BPF-JIT/arch-support.txt
deleted file mode 100644
index d277f971ccd6b..0
--- a/Documentation/features/core/BPF-JIT/arch-support.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#
-# Feature name:  BPF-JIT
-# Kconfig:   HAVE_BPF_JIT
-# description:   arch supports BPF JIT optimizations
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: | TODO |
-| arm: |  ok  |
-|   arm64: |  ok  |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: |  ok  |
-|   nds32: | TODO |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: |  ok  |
-|   riscv: | TODO |
-|s390: |  ok  |
-|  sh: | TODO |
-|   sparc: |  ok  |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: |  ok  |
-|  xtensa: | TODO |
----
diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt 
b/Documentation/features/core/cBPF-JIT/arch-support.txt
new file mode 100644
index 0..90459cdde3143
--- /dev/null
+++ b/Documentation/features/core/cBPF-JIT/arch-support.txt
@@ -0,0 +1,33 @@
+#
+# Feature name:  cBPF-JIT
+# Kconfig:   HAVE_CBPF_JIT
+# description:   arch supports cBPF JIT optimizations
+#
+---
+| arch |status|
+---
+|   alpha: | TODO |
+| arc: | TODO |
+| arm: | TODO |
+|   arm64: | TODO |
+| c6x: | TODO |
+|   h8300: | TODO |
+| hexagon: | TODO |
+|ia64: | TODO |
+|m68k: | TODO |
+|  microblaze: | TODO |
+|mips: |  ok  |
+|   nds32: | TODO |
+|   nios2: | TODO |
+|openrisc: | TODO |
+|  parisc: | TODO |
+| powerpc: |  ok  |
+|   riscv: | TODO |
+|s390: | TODO |
+|  sh: | TODO |
+|   sparc: |  ok  |
+|  um: | TODO |
+|   unicore32: | TODO |
+| x86: | TODO |
+|  xtensa: | TODO |
+---
diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt 
b/Documentation/features/core/eBPF-JIT/arch-support.txt
new file mode 100644
index 0..c90a0382fe667
--- /dev/null
+++ b/Documentation/features/core/eBPF-JIT/arch-support.txt
@@ -0,0 +1,33 @@
+#
+# Feature name:  eBPF-JIT
+# Kconfig:   HAVE_EBPF_JIT
+# description:   arch supports eBPF JIT optimizations
+#
+---
+| arch |status|
+---
+|   alpha: | TODO |
+| arc: | TODO |
+| arm: |  ok  |
+|   arm64: |  ok  |
+| c6x: | TODO |
+|   h8300: | TODO |
+| hexagon: | TODO |
+|ia64: | TODO |
+|m68k: | TODO |
+|  microblaze: | TODO |
+|mips: |  ok  |
+|   nds32: | TODO |
+|   nios2: | TODO |
+|openrisc: | TODO |
+|  parisc: | TODO |
+| powerpc: |  ok  |
+|   riscv: | TODO |
+|s390: |  ok  |
+|  sh: | TODO |
+|   sparc: |  ok  |
+|  um: | TODO |
+|   unicore32: | TODO |
+| x86: |  ok  |
+|  xtensa: | TODO |
+---
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v3 5/6] Documentation/features/lib: Remove arch support status file for 'strncasecmp'

[Andrea Parri]

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 .../features/lib/strncasecmp/arch-support.txt  | 33 --
 1 file changed, 33 deletions(-)
 delete mode 100644 Documentation/features/lib/strncasecmp/arch-support.txt

diff --git a/Documentation/features/lib/strncasecmp/arch-support.txt 
b/Documentation/features/lib/strncasecmp/arch-support.txt
deleted file mode 100644
index 6148f42c3d902..0
--- a/Documentation/features/lib/strncasecmp/arch-support.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#
-# Feature name:  strncasecmp
-# Kconfig:   __HAVE_ARCH_STRNCASECMP
-# description:   arch provides an optimized strncasecmp() function
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: | TODO |
-| arm: | TODO |
-|   arm64: | TODO |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: | TODO |
-|   nds32: | TODO |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: | TODO |
-|   riscv: | TODO |
-|s390: | TODO |
-|  sh: | TODO |
-|   sparc: | TODO |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: | TODO |
-|  xtensa: | TODO |
----
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v3 6/6] Documentation/features/vm: Remove arch support status file for 'pte_special'

[Andrea Parri]

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 .../features/vm/pte_special/arch-support.txt   | 33 --
 1 file changed, 33 deletions(-)
 delete mode 100644 Documentation/features/vm/pte_special/arch-support.txt

diff --git a/Documentation/features/vm/pte_special/arch-support.txt 
b/Documentation/features/vm/pte_special/arch-support.txt
deleted file mode 100644
index 6a608a6dcf71d..0
--- a/Documentation/features/vm/pte_special/arch-support.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#
-# Feature name:  pte_special
-# Kconfig:   __HAVE_ARCH_PTE_SPECIAL
-# description:   arch supports the pte_special()/pte_mkspecial() VM 
APIs
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: |  ok  |
-| arm: |  ok  |
-|   arm64: |  ok  |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: | TODO |
-|   nds32: | TODO |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: |  ok  |
-|   riscv: | TODO |
-|s390: |  ok  |
-|  sh: |  ok  |
-|   sparc: |  ok  |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: |  ok  |
-|  xtensa: | TODO |
----
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v3 0/6] Documentation/features: Provide and apply 'features-refresh.sh'

[Andrea Parri]

Hi,

This series provides the script 'features-refresh.sh', which operates on
the arch support status files, and it applies this script to refresh the
status files in place; previous discussions about this series are at [1].

The series is organized as follows.

  - Patch 1/6 adds the script to 'Documentation/features/scripts/'.

  - Patch 2/6 presents the results of running the script; this run
also printed the messages

   WARNING: 'HAVE_BPF_JIT' is not a valid Kconfig
   WARNING: '__HAVE_ARCH_STRNCASECMP' is not a valid Kconfig
   WARNING: 'Optimized asm/rwsem.h' is not a valid Kconfig
   WARNING: '__HAVE_ARCH_PTE_SPECIAL' is not a valid Kconfig

to standard output.

  - Patches 3-6/6 fix each of these warnings.

(Applies on -rc4.)

Cheers,
  Andrea

[1] 
http://lkml.kernel.org/r/1523205027-31786-1-git-send-email-andrea.pa...@amarulasolutions.com

http://lkml.kernel.org/r/1522774551-9503-1-git-send-email-andrea.pa...@amarulasolutions.com
http://lkml.kernel.org/r/20180328122211.GA25420@andrea

Changes in v3:
  - rebase on -rc4

Changes in v2:
  - support negation operators in Kconfig (suggested by Ingo Molnar)
  - reorder patches 2/6 and 3/6 (suggested by Ingo Molnar)
  - add patches 4-6/6 (suggested by Ingo Molnar)

Andrea Parri (6):
  Documentation/features: Add script that refreshes the arch support
status files in place
  Documentation/features: Refresh the arch support status files in place
  Documentation/features/core: Add arch support status files for
'cBPF-JIT' and 'eBPF-JIT'
  Documentation/features/locking: Use '!RWSEM_GENERIC_SPINLOCK' as
Kconfig for 'rwsem-optimized'
  Documentation/features/lib: Remove arch support status file for
'strncasecmp'
  Documentation/features/vm: Remove arch support status file for
'pte_special'

 .../features/core/BPF-JIT/arch-support.txt | 31 ---
 .../features/core/cBPF-JIT/arch-support.txt| 33 
 .../features/core/eBPF-JIT/arch-support.txt| 33 
 .../core/generic-idle-thread/arch-support.txt  |  4 +-
 .../features/core/jump-labels/arch-support.txt |  2 +
 .../features/core/tracehook/arch-support.txt   |  2 +
 .../features/debug/KASAN/arch-support.txt  |  4 +-
 .../debug/gcov-profile-all/arch-support.txt|  2 +
 Documentation/features/debug/kgdb/arch-support.txt |  4 +-
 .../debug/kprobes-on-ftrace/arch-support.txt   |  2 +
 .../features/debug/kprobes/arch-support.txt|  4 +-
 .../features/debug/kretprobes/arch-support.txt |  4 +-
 .../features/debug/optprobes/arch-support.txt  |  4 +-
 .../features/debug/stackprotector/arch-support.txt |  2 +
 .../features/debug/uprobes/arch-support.txt|  6 +-
 .../debug/user-ret-profiler/arch-support.txt   |  2 +
 .../features/io/dma-api-debug/arch-support.txt |  2 +
 .../features/io/dma-contiguous/arch-support.txt|  4 +-
 .../features/io/sg-chain/arch-support.txt  |  2 +
 .../features/lib/strncasecmp/arch-support.txt  | 31 ---
 .../locking/cmpxchg-local/arch-support.txt |  4 +-
 .../features/locking/lockdep/arch-support.txt  |  4 +-
 .../locking/queued-rwlocks/arch-support.txt| 10 ++-
 .../locking/queued-spinlocks/arch-support.txt  |  8 +-
 .../locking/rwsem-optimized/arch-support.txt   | 10 ++-
 .../features/perf/kprobes-event/arch-support.txt   |  6 +-
 .../features/perf/perf-regs/arch-support.txt   |  4 +-
 .../features/perf/perf-stackdump/arch-support.txt  |  4 +-
 .../sched/membarrier-sync-core/arch-support.txt|  2 +
 .../features/sched/numa-balancing/arch-support.txt |  6 +-
 Documentation/features/scripts/features-refresh.sh | 98 ++
 .../seccomp/seccomp-filter/arch-support.txt|  6 +-
 .../time/arch-tick-broadcast/arch-support.txt  |  4 +-
 .../features/time/clockevents/arch-support.txt |  4 +-
 .../time/context-tracking/arch-support.txt |  2 +
 .../features/time/irq-time-acct/arch-support.txt   |  4 +-
 .../time/modern-timekeeping/arch-support.txt   |  2 +
 .../features/time/virt-cpuacct/arch-support.txt|  2 +
 .../features/vm/ELF-ASLR/arch-support.txt  |  4 +-
 .../features/vm/PG_uncached/arch-support.txt   |  2 +
 Documentation/features/vm/THP/arch-support.txt |  2 +
 Documentation/features/vm/TLB/arch-support.txt |  2 +
 .../features/vm/huge-vmap/arch-support.txt |  2 +
 .../features/vm/ioremap_prot/arch-support.txt  |  2 +
 .../features/vm/numa-memblock/arch-support.txt |  4 +-
 .../features/vm/pte_special/arch-support.txt   | 31 ---
 46 files changed, 279 insertions(+), 128 deletions(-)
 delete mode 100644 Documentation/features/core/BPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/cBPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/eBPF-JIT/arch-support.txt
 delete mode 100644 Documentation/features/lib/strncasecmp/arch-support.txt
 create mode 100755 Documentation

Re: [PATCH] Documentation: refcount-vs-atomic: Update reference to LKMM doc.

[Andrea Parri]

On Fri, May 04, 2018 at 02:13:59PM -0700, Kees Cook wrote:
> On Fri, May 4, 2018 at 2:11 PM, Andrea Parri
> <andrea.pa...@amarulasolutions.com> wrote:
> > The LKMM project has moved to 'tools/memory-model/'.
> >
> > Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
> > ---
> >  Documentation/core-api/refcount-vs-atomic.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
> > b/Documentation/core-api/refcount-vs-atomic.rst
> > index 83351c258cdb9..322851bada167 100644
> > --- a/Documentation/core-api/refcount-vs-atomic.rst
> > +++ b/Documentation/core-api/refcount-vs-atomic.rst
> > @@ -17,7 +17,7 @@ in order to help maintainers validate their code against 
> > the change in
> >  these memory ordering guarantees.
> >
> >  The terms used through this document try to follow the formal LKMM defined 
> > in
> > -github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> > +tools/memory-model/Documentation/explanation.txt.
> >
> >  memory-barriers.txt and atomic_t.txt provide more background to the
> >  memory ordering in general and for atomic operations specifically.
> 
> Will this get linkified by rst ?

I believe not, but I'm not too familiar with rst...  FWIW, I'm seeing that
the above memory-barriers.txt, atomic_t.txt are not linkified.

  Andrea


> 
> -Kees
> 
> -- 
> Kees Cook
> Pixel Security
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation: refcount-vs-atomic: Update reference to LKMM doc.

[Andrea Parri]

The LKMM project has moved to 'tools/memory-model/'.

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
---
 Documentation/core-api/refcount-vs-atomic.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
b/Documentation/core-api/refcount-vs-atomic.rst
index 83351c258cdb9..322851bada167 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the 
change in
 these memory ordering guarantees.
 
 The terms used through this document try to follow the formal LKMM defined in
-github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
+tools/memory-model/Documentation/explanation.txt.
 
 memory-barriers.txt and atomic_t.txt provide more background to the
 memory ordering in general and for atomic operations specifically.
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v2 0/6] Documentation/features: Provide and apply 'features-refresh.sh'

[Andrea Parri]

Hi Ingo, Jon,

On Sun, Apr 08, 2018 at 06:30:21PM +0200, Andrea Parri wrote:
> Hi,
> 
> This series provides the script 'features-refresh.sh', which operates on
> the arch support status files, and it applies this script to refresh the
> status files in place; previous discussions about this series are at [1].
> 
> The series is organized as follows.
> 
>   - Patch 1/6 adds the script to 'Documentation/features/scripts/'.
> 
>   - Patch 2/6 presents the results of running the script; this run
> also printed the messages
> 
>WARNING: 'HAVE_BPF_JIT' is not a valid Kconfig
>WARNING: '__HAVE_ARCH_STRNCASECMP' is not a valid Kconfig
>WARNING: 'Optimized asm/rwsem.h' is not a valid Kconfig
>WARNING: '__HAVE_ARCH_PTE_SPECIAL' is not a valid Kconfig
> 
> to standard output.
> 
>   - Patches 3-6/6 fix each of these warnings.
> 
> (Applies on today's mainline.)
> 
> Cheers,
>   Andrea
> 
> [1] https://marc.info/?l=linux-kernel=152223974927255=2
> https://marc.info/?l=linux-kernel=152277458614862=2
> 
> Changes in v2:
>   - support negation operators in Kconfig (suggested by Ingo Molnar)
>   - reorder patches 2/6 and 3/6 (suggested by Ingo Molnar)
>   - add patches 4-6/6 (suggested by Ingo Molnar)
> 
> Andrea Parri (6):
>   Documentation/features: Add script that refreshes the arch support
> status files in place
>   Documentation/features: Refresh the arch support status files in place
>   Documentation/features/core: Add arch support status files for
> 'cBPF-JIT' and 'eBPF-JIT'
>   Documentation/features/locking: Use '!RWSEM_GENERIC_SPINLOCK' as
> Kconfig for 'rwsem-optimized'
>   Documentation/features/lib: Remove arch support status file for
> 'strncasecmp'
>   Documentation/features/vm: Remove arch support status file for
> 'pte_special'

I understand that you didn't get the chance to look into this yet ;D
please let me know if you'd like me to rebase and re-send the series.

Thanks,
  Andrea


> 
>  .../features/core/BPF-JIT/arch-support.txt | 31 ---
>  .../features/core/cBPF-JIT/arch-support.txt| 33 
>  .../features/core/eBPF-JIT/arch-support.txt| 33 
>  .../core/generic-idle-thread/arch-support.txt  |  4 +-
>  .../features/core/jump-labels/arch-support.txt |  2 +
>  .../features/core/tracehook/arch-support.txt   |  2 +
>  .../features/debug/KASAN/arch-support.txt  |  4 +-
>  .../debug/gcov-profile-all/arch-support.txt|  2 +
>  Documentation/features/debug/kgdb/arch-support.txt |  4 +-
>  .../debug/kprobes-on-ftrace/arch-support.txt   |  2 +
>  .../features/debug/kprobes/arch-support.txt|  4 +-
>  .../features/debug/kretprobes/arch-support.txt |  4 +-
>  .../features/debug/optprobes/arch-support.txt  |  4 +-
>  .../features/debug/stackprotector/arch-support.txt |  2 +
>  .../features/debug/uprobes/arch-support.txt|  6 +-
>  .../debug/user-ret-profiler/arch-support.txt   |  2 +
>  .../features/io/dma-api-debug/arch-support.txt |  2 +
>  .../features/io/dma-contiguous/arch-support.txt|  4 +-
>  .../features/io/sg-chain/arch-support.txt  |  2 +
>  .../features/lib/strncasecmp/arch-support.txt  | 31 ---
>  .../locking/cmpxchg-local/arch-support.txt |  4 +-
>  .../features/locking/lockdep/arch-support.txt  |  4 +-
>  .../locking/queued-rwlocks/arch-support.txt| 10 ++-
>  .../locking/queued-spinlocks/arch-support.txt  |  8 +-
>  .../locking/rwsem-optimized/arch-support.txt   | 10 ++-
>  .../features/perf/kprobes-event/arch-support.txt   |  6 +-
>  .../features/perf/perf-regs/arch-support.txt   |  4 +-
>  .../features/perf/perf-stackdump/arch-support.txt  |  4 +-
>  .../sched/membarrier-sync-core/arch-support.txt|  2 +
>  .../features/sched/numa-balancing/arch-support.txt |  6 +-
>  Documentation/features/scripts/features-refresh.sh | 98 
> ++
>  .../seccomp/seccomp-filter/arch-support.txt|  6 +-
>  .../time/arch-tick-broadcast/arch-support.txt  |  4 +-
>  .../features/time/clockevents/arch-support.txt |  4 +-
>  .../time/context-tracking/arch-support.txt |  2 +
>  .../features/time/irq-time-acct/arch-support.txt   |  4 +-
>  .../time/modern-timekeeping/arch-support.txt   |  2 +
>  .../features/time/virt-cpuacct/arch-support.txt|  2 +
>  .../features/vm/ELF-ASLR/arch-support.txt  |  4 +-
>  .../features/vm/PG_uncached/arch-support.txt   |  2 +
>  Documentation/features/vm/THP/arch-support.txt |  2 +
>  Documentation/features/vm/TLB/arch-support.txt |  2 +
>  .../features/vm/huge-vmap/arch-support.txt |  2 +
>  .../features/vm/ioremap_pro

[RFC PATCH v2 3/6] Documentation/features/core: Add arch support status files for 'cBPF-JIT' and 'eBPF-JIT'

[Andrea Parri]

Commit 606b5908e split 'HAVE_BPF_JIT' into cBPF and eBPF variant.
Adds arch support status files for the new variants, and removes the
status file corresponding to 'HAVE_BPT_JIT'. The new status matrices
were auto-generated using the script 'features-refresh.sh'.

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 .../features/core/BPF-JIT/arch-support.txt | 33 --
 .../features/core/cBPF-JIT/arch-support.txt| 33 ++
 .../features/core/eBPF-JIT/arch-support.txt| 33 ++
 3 files changed, 66 insertions(+), 33 deletions(-)
 delete mode 100644 Documentation/features/core/BPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/cBPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/eBPF-JIT/arch-support.txt

diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt 
b/Documentation/features/core/BPF-JIT/arch-support.txt
deleted file mode 100644
index d277f971ccd6b..0
--- a/Documentation/features/core/BPF-JIT/arch-support.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#
-# Feature name:  BPF-JIT
-# Kconfig:   HAVE_BPF_JIT
-# description:   arch supports BPF JIT optimizations
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: | TODO |
-| arm: |  ok  |
-|   arm64: |  ok  |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: |  ok  |
-|   nds32: | TODO |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: |  ok  |
-|   riscv: | TODO |
-|s390: |  ok  |
-|  sh: | TODO |
-|   sparc: |  ok  |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: |  ok  |
-|  xtensa: | TODO |
----
diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt 
b/Documentation/features/core/cBPF-JIT/arch-support.txt
new file mode 100644
index 0..90459cdde3143
--- /dev/null
+++ b/Documentation/features/core/cBPF-JIT/arch-support.txt
@@ -0,0 +1,33 @@
+#
+# Feature name:  cBPF-JIT
+# Kconfig:   HAVE_CBPF_JIT
+# description:   arch supports cBPF JIT optimizations
+#
+---
+| arch |status|
+---
+|   alpha: | TODO |
+| arc: | TODO |
+| arm: | TODO |
+|   arm64: | TODO |
+| c6x: | TODO |
+|   h8300: | TODO |
+| hexagon: | TODO |
+|ia64: | TODO |
+|m68k: | TODO |
+|  microblaze: | TODO |
+|mips: |  ok  |
+|   nds32: | TODO |
+|   nios2: | TODO |
+|openrisc: | TODO |
+|  parisc: | TODO |
+| powerpc: |  ok  |
+|   riscv: | TODO |
+|s390: | TODO |
+|  sh: | TODO |
+|   sparc: |  ok  |
+|  um: | TODO |
+|   unicore32: | TODO |
+| x86: | TODO |
+|  xtensa: | TODO |
+---
diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt 
b/Documentation/features/core/eBPF-JIT/arch-support.txt
new file mode 100644
index 0..c90a0382fe667
--- /dev/null
+++ b/Documentation/features/core/eBPF-JIT/arch-support.txt
@@ -0,0 +1,33 @@
+#
+# Feature name:  eBPF-JIT
+# Kconfig:   HAVE_EBPF_JIT
+# description:   arch supports eBPF JIT optimizations
+#
+---
+| arch |status|
+---
+|   alpha: | TODO |
+| arc: | TODO |
+| arm: |  ok  |
+|   arm64: |  ok  |
+| c6x: | TODO |
+|   h8300: | TODO |
+| hexagon: | TODO |
+|ia64: | TODO |
+|m68k: | TODO |
+|  microblaze: | TODO |
+|mips: |  ok  |
+|   nds32: | TODO |
+|   nios2: | TODO |
+|openrisc: | TODO |
+|  parisc: | TODO |
+| powerpc: |  ok  |
+|   riscv: | TODO |
+|s390: |  ok  |
+|  sh: | TODO |
+|   sparc: |  ok  |
+|  um: | TODO |
+|   unicore32: | TODO |
+| x86: |  ok  |
+|  xtensa: | TODO |
+---
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v2 2/6] Documentation/features: Refresh the arch support status files in place

[Andrea Parri]

Now that the script 'features-refresh.sh' is available, uses this script
to refresh all the arch-support.txt files in place.

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 Documentation/features/core/BPF-JIT/arch-support.txt   |  2 ++
 .../features/core/generic-idle-thread/arch-support.txt |  4 +++-
 Documentation/features/core/jump-labels/arch-support.txt   |  2 ++
 Documentation/features/core/tracehook/arch-support.txt |  2 ++
 Documentation/features/debug/KASAN/arch-support.txt|  4 +++-
 Documentation/features/debug/gcov-profile-all/arch-support.txt |  2 ++
 Documentation/features/debug/kgdb/arch-support.txt |  4 +++-
 .../features/debug/kprobes-on-ftrace/arch-support.txt  |  2 ++
 Documentation/features/debug/kprobes/arch-support.txt  |  4 +++-
 Documentation/features/debug/kretprobes/arch-support.txt   |  4 +++-
 Documentation/features/debug/optprobes/arch-support.txt|  4 +++-
 Documentation/features/debug/stackprotector/arch-support.txt   |  2 ++
 Documentation/features/debug/uprobes/arch-support.txt  |  6 --
 .../features/debug/user-ret-profiler/arch-support.txt  |  2 ++
 Documentation/features/io/dma-api-debug/arch-support.txt   |  2 ++
 Documentation/features/io/dma-contiguous/arch-support.txt  |  4 +++-
 Documentation/features/io/sg-chain/arch-support.txt|  2 ++
 Documentation/features/lib/strncasecmp/arch-support.txt|  2 ++
 Documentation/features/locking/cmpxchg-local/arch-support.txt  |  4 +++-
 Documentation/features/locking/lockdep/arch-support.txt|  4 +++-
 Documentation/features/locking/queued-rwlocks/arch-support.txt | 10 ++
 .../features/locking/queued-spinlocks/arch-support.txt |  8 +---
 .../features/locking/rwsem-optimized/arch-support.txt  |  2 ++
 Documentation/features/perf/kprobes-event/arch-support.txt |  6 --
 Documentation/features/perf/perf-regs/arch-support.txt |  4 +++-
 Documentation/features/perf/perf-stackdump/arch-support.txt|  4 +++-
 .../features/sched/membarrier-sync-core/arch-support.txt   |  2 ++
 Documentation/features/sched/numa-balancing/arch-support.txt   |  6 --
 Documentation/features/seccomp/seccomp-filter/arch-support.txt |  6 --
 .../features/time/arch-tick-broadcast/arch-support.txt |  4 +++-
 Documentation/features/time/clockevents/arch-support.txt   |  4 +++-
 Documentation/features/time/context-tracking/arch-support.txt  |  2 ++
 Documentation/features/time/irq-time-acct/arch-support.txt |  4 +++-
 .../features/time/modern-timekeeping/arch-support.txt  |  2 ++
 Documentation/features/time/virt-cpuacct/arch-support.txt  |  2 ++
 Documentation/features/vm/ELF-ASLR/arch-support.txt|  4 +++-
 Documentation/features/vm/PG_uncached/arch-support.txt |  2 ++
 Documentation/features/vm/THP/arch-support.txt |  2 ++
 Documentation/features/vm/TLB/arch-support.txt |  2 ++
 Documentation/features/vm/huge-vmap/arch-support.txt   |  2 ++
 Documentation/features/vm/ioremap_prot/arch-support.txt|  2 ++
 Documentation/features/vm/numa-memblock/arch-support.txt   |  4 +++-
 Documentation/features/vm/pte_special/arch-support.txt |  2 ++
 43 files changed, 117 insertions(+), 31 deletions(-)

diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt 
b/Documentation/features/core/BPF-JIT/arch-support.txt
index 0b96b4e1e7d4a..d277f971ccd6b 100644
--- a/Documentation/features/core/BPF-JIT/arch-support.txt
+++ b/Documentation/features/core/BPF-JIT/arch-support.txt
@@ -17,10 +17,12 @@
 |m68k: | TODO |
 |  microblaze: | TODO |
 |mips: |  ok  |
+|   nds32: | TODO |
 |   nios2: | TODO |
 |openrisc: | TODO |
 |  parisc: | TODO |
 | powerpc: |  ok  |
+|   riscv: | TODO |
 |s390: |  ok  |
 |  sh: | TODO |
 |   sparc: |  ok  |
diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt 
b/Documentation/features/core/generic-idle-thread/arch-support.txt
index 372a2b18a6172..0ef6acdb991c7 100644
--- a/Documentation/features/core/generic-idle-thread/arch-support.txt
+++ b/Documentation/features/core/generic-idle-thread/arch-support.txt
@@ -17,10 +17,12 @@
 |m68k: | TODO |
 |  microblaze: | TODO |
 |mips: |  ok  |
+|   nds32: | TODO |
 |   nios2: | TODO |
-|openrisc: | TODO |
+|openrisc: |  ok  |
 |  parisc: |  ok  |
 | powerpc: |  ok  |
+|   riscv: |  ok  |
 |s390: |  ok  |
 |  sh: |  ok  |
 |   sparc: |  ok  |
diff --git a/Documentation/features/core/jump-labels/arch-support.txt 

[RFC PATCH v2 4/6] Documentation/features/locking: Use '!RWSEM_GENERIC_SPINLOCK' as Kconfig for 'rwsem-optimized'

[Andrea Parri]

Uses '!RWSEM_GENERIC_SPINLOCK' in place of 'Optimized asm/rwsem.h' as
Kconfig for 'rwsem-optimized': the new Kconfig expresses this feature
equivalently, while also enabling the script 'features-refresh.sh' to
operate on the corresponding arch support status file. Also refreshes
the status matrix by using the script 'features-refresh.sh'.

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 Documentation/features/locking/rwsem-optimized/arch-support.txt | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt 
b/Documentation/features/locking/rwsem-optimized/arch-support.txt
index 8afe24ffa3ab4..e54b1f1a8091d 100644
--- a/Documentation/features/locking/rwsem-optimized/arch-support.txt
+++ b/Documentation/features/locking/rwsem-optimized/arch-support.txt
@@ -1,6 +1,6 @@
 #
 # Feature name:  rwsem-optimized
-# Kconfig:   Optimized asm/rwsem.h
+# Kconfig:   !RWSEM_GENERIC_SPINLOCK
 # description:   arch provides optimized rwsem APIs
 #
 ---
@@ -8,8 +8,8 @@
 ---
 |   alpha: |  ok  |
 | arc: | TODO |
-| arm: | TODO |
-|   arm64: | TODO |
+| arm: |  ok  |
+|   arm64: |  ok  |
 | c6x: | TODO |
 |   h8300: | TODO |
 | hexagon: | TODO |
@@ -26,7 +26,7 @@
 |s390: |  ok  |
 |  sh: |  ok  |
 |   sparc: |  ok  |
-|  um: | TODO |
+|  um: |  ok  |
 |   unicore32: | TODO |
 | x86: |  ok  |
 |  xtensa: |  ok  |
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v2 5/6] Documentation/features/lib: Remove arch support status file for 'strncasecmp'

[Andrea Parri]

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 .../features/lib/strncasecmp/arch-support.txt  | 33 --
 1 file changed, 33 deletions(-)
 delete mode 100644 Documentation/features/lib/strncasecmp/arch-support.txt

diff --git a/Documentation/features/lib/strncasecmp/arch-support.txt 
b/Documentation/features/lib/strncasecmp/arch-support.txt
deleted file mode 100644
index 6148f42c3d902..0
--- a/Documentation/features/lib/strncasecmp/arch-support.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#
-# Feature name:  strncasecmp
-# Kconfig:   __HAVE_ARCH_STRNCASECMP
-# description:   arch provides an optimized strncasecmp() function
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: | TODO |
-| arm: | TODO |
-|   arm64: | TODO |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: | TODO |
-|   nds32: | TODO |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: | TODO |
-|   riscv: | TODO |
-|s390: | TODO |
-|  sh: | TODO |
-|   sparc: | TODO |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: | TODO |
-|  xtensa: | TODO |
----
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v2 1/6] Documentation/features: Add script that refreshes the arch support status files in place

[Andrea Parri]

Provides the script:

Documentation/features/scripts/features-refresh.sh

which operates on the arch-support.txt files and refreshes them in place.

This way [1],

   "[...] we soft- decouple the refreshing of the entries from the
introduction of the features, while still making it all easy to
keep sync and to extend."

[1] https://marc.info/?l=linux-kernel=152240950509781=2

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 Documentation/features/scripts/features-refresh.sh | 98 ++
 1 file changed, 98 insertions(+)
 create mode 100755 Documentation/features/scripts/features-refresh.sh

diff --git a/Documentation/features/scripts/features-refresh.sh 
b/Documentation/features/scripts/features-refresh.sh
new file mode 100755
index 0..9e72d38a0720e
--- /dev/null
+++ b/Documentation/features/scripts/features-refresh.sh
@@ -0,0 +1,98 @@
+#
+# Small script that refreshes the kernel feature support status in place.
+#
+
+for F_FILE in Documentation/features/*/*/arch-support.txt; do
+   F=$(grep "^# Kconfig:" "$F_FILE" | cut -c26-)
+
+   #
+   # Each feature F is identified by a pair (O, K), where 'O' can
+   # be either the empty string (for 'nop') or "not" (the logical
+   # negation operator '!'); other operators are not supported.
+   #
+   O=""
+   K=$F
+   if [[ "$F" == !* ]]; then
+   O="not"
+   K=$(echo $F | sed -e 's/^!//g')
+   fi
+
+   #
+   # F := (O, K) is 'valid' iff there is a Kconfig file (for some
+   # arch) which contains K.
+   #
+   # Notice that this definition entails an 'asymmetry' between
+   # the case 'O = ""' and the case 'O = "not"'. E.g., F may be
+   # _invalid_ if:
+   #
+   # [case 'O = ""']
+   #   1) no arch provides support for F,
+   #   2) K does not exist (e.g., it was renamed/mis-typed);
+   #
+   # [case 'O = "not"']
+   #   3) all archs provide support for F,
+   #   4) as in (2).
+   #
+   # The rationale for adopting this definition (and, thus, for
+   # keeping the asymmetry) is:
+   #
+   #   We want to be able to 'detect' (2) (or (4)).
+   #
+   # (1) and (3) may further warn the developers about the fact
+   # that K can be removed.
+   #
+   F_VALID="false"
+   for ARCH_DIR in arch/*/; do
+   K_FILES=$(find $ARCH_DIR -name "Kconfig*")
+   K_GREP=$(grep "$K" $K_FILES)
+   if [ ! -z "$K_GREP" ]; then
+   F_VALID="true"
+   break
+   fi
+   done
+   if [ "$F_VALID" = "false" ]; then
+   printf "WARNING: '%s' is not a valid Kconfig\n" "$F"
+   fi
+
+   T_FILE="$F_FILE.tmp"
+   grep "^#" $F_FILE > $T_FILE
+   echo "---" >> $T_FILE
+   echo "| arch |status|" >> $T_FILE
+   echo "---" >> $T_FILE
+   for ARCH_DIR in arch/*/; do
+   ARCH=$(echo $ARCH_DIR | sed -e 's/arch//g' | sed -e 's/\///g')
+   K_FILES=$(find $ARCH_DIR -name "Kconfig*")
+   K_GREP=$(grep "$K" $K_FILES)
+   #
+   # Arch support status values for (O, K) are updated according
+   # to the following rules.
+   #
+   #   - ("", K) is 'supported by a given arch', if there is a
+   # Kconfig file for that arch which contains K;
+   #
+   #   - ("not", K) is 'supported by a given arch', if there is
+   # no Kconfig file for that arch which contains K;
+   #
+   #   - otherwise: preserve the previous status value (if any),
+   #default to 'not yet supported'.
+   #
+   # Notice that, according these rules, invalid features may be
+   # updated/modified.
+   #
+   if [ "$O" = "" ] && [ ! -z "$K_GREP" ]; then
+   printf "|%12s: |  ok  |\n" "$ARCH" >> $T_FILE
+   elif [ "$O" = "not" ] && [ -z "$K_GREP" ]; then
+   printf "|%12s: |  ok  |\n" "$ARCH" >> $T_FILE
+   else
+   S=$(grep -v "^#" "

[RFC PATCH v2 6/6] Documentation/features/vm: Remove arch support status file for 'pte_special'

[Andrea Parri]

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
Cc: Ingo Molnar <mi...@kernel.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
---
 .../features/vm/pte_special/arch-support.txt   | 33 --
 1 file changed, 33 deletions(-)
 delete mode 100644 Documentation/features/vm/pte_special/arch-support.txt

diff --git a/Documentation/features/vm/pte_special/arch-support.txt 
b/Documentation/features/vm/pte_special/arch-support.txt
deleted file mode 100644
index 6a608a6dcf71d..0
--- a/Documentation/features/vm/pte_special/arch-support.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#
-# Feature name:  pte_special
-# Kconfig:   __HAVE_ARCH_PTE_SPECIAL
-# description:   arch supports the pte_special()/pte_mkspecial() VM 
APIs
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: |  ok  |
-| arm: |  ok  |
-|   arm64: |  ok  |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: | TODO |
-|   nds32: | TODO |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: |  ok  |
-|   riscv: | TODO |
-|s390: |  ok  |
-|  sh: |  ok  |
-|   sparc: |  ok  |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: |  ok  |
-|  xtensa: | TODO |
----
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH v2 0/6] Documentation/features: Provide and apply 'features-refresh.sh'

[Andrea Parri]

Hi,

This series provides the script 'features-refresh.sh', which operates on
the arch support status files, and it applies this script to refresh the
status files in place; previous discussions about this series are at [1].

The series is organized as follows.

  - Patch 1/6 adds the script to 'Documentation/features/scripts/'.

  - Patch 2/6 presents the results of running the script; this run
also printed the messages

   WARNING: 'HAVE_BPF_JIT' is not a valid Kconfig
   WARNING: '__HAVE_ARCH_STRNCASECMP' is not a valid Kconfig
   WARNING: 'Optimized asm/rwsem.h' is not a valid Kconfig
   WARNING: '__HAVE_ARCH_PTE_SPECIAL' is not a valid Kconfig

to standard output.

  - Patches 3-6/6 fix each of these warnings.

(Applies on today's mainline.)

Cheers,
  Andrea

[1] https://marc.info/?l=linux-kernel=152223974927255=2
https://marc.info/?l=linux-kernel=152277458614862=2

Changes in v2:
  - support negation operators in Kconfig (suggested by Ingo Molnar)
  - reorder patches 2/6 and 3/6 (suggested by Ingo Molnar)
  - add patches 4-6/6 (suggested by Ingo Molnar)

Andrea Parri (6):
  Documentation/features: Add script that refreshes the arch support
status files in place
  Documentation/features: Refresh the arch support status files in place
  Documentation/features/core: Add arch support status files for
'cBPF-JIT' and 'eBPF-JIT'
  Documentation/features/locking: Use '!RWSEM_GENERIC_SPINLOCK' as
Kconfig for 'rwsem-optimized'
  Documentation/features/lib: Remove arch support status file for
'strncasecmp'
  Documentation/features/vm: Remove arch support status file for
'pte_special'

 .../features/core/BPF-JIT/arch-support.txt | 31 ---
 .../features/core/cBPF-JIT/arch-support.txt| 33 
 .../features/core/eBPF-JIT/arch-support.txt| 33 
 .../core/generic-idle-thread/arch-support.txt  |  4 +-
 .../features/core/jump-labels/arch-support.txt |  2 +
 .../features/core/tracehook/arch-support.txt   |  2 +
 .../features/debug/KASAN/arch-support.txt  |  4 +-
 .../debug/gcov-profile-all/arch-support.txt|  2 +
 Documentation/features/debug/kgdb/arch-support.txt |  4 +-
 .../debug/kprobes-on-ftrace/arch-support.txt   |  2 +
 .../features/debug/kprobes/arch-support.txt|  4 +-
 .../features/debug/kretprobes/arch-support.txt |  4 +-
 .../features/debug/optprobes/arch-support.txt  |  4 +-
 .../features/debug/stackprotector/arch-support.txt |  2 +
 .../features/debug/uprobes/arch-support.txt|  6 +-
 .../debug/user-ret-profiler/arch-support.txt   |  2 +
 .../features/io/dma-api-debug/arch-support.txt |  2 +
 .../features/io/dma-contiguous/arch-support.txt|  4 +-
 .../features/io/sg-chain/arch-support.txt  |  2 +
 .../features/lib/strncasecmp/arch-support.txt  | 31 ---
 .../locking/cmpxchg-local/arch-support.txt |  4 +-
 .../features/locking/lockdep/arch-support.txt  |  4 +-
 .../locking/queued-rwlocks/arch-support.txt| 10 ++-
 .../locking/queued-spinlocks/arch-support.txt  |  8 +-
 .../locking/rwsem-optimized/arch-support.txt   | 10 ++-
 .../features/perf/kprobes-event/arch-support.txt   |  6 +-
 .../features/perf/perf-regs/arch-support.txt   |  4 +-
 .../features/perf/perf-stackdump/arch-support.txt  |  4 +-
 .../sched/membarrier-sync-core/arch-support.txt|  2 +
 .../features/sched/numa-balancing/arch-support.txt |  6 +-
 Documentation/features/scripts/features-refresh.sh | 98 ++
 .../seccomp/seccomp-filter/arch-support.txt|  6 +-
 .../time/arch-tick-broadcast/arch-support.txt  |  4 +-
 .../features/time/clockevents/arch-support.txt |  4 +-
 .../time/context-tracking/arch-support.txt |  2 +
 .../features/time/irq-time-acct/arch-support.txt   |  4 +-
 .../time/modern-timekeeping/arch-support.txt   |  2 +
 .../features/time/virt-cpuacct/arch-support.txt|  2 +
 .../features/vm/ELF-ASLR/arch-support.txt  |  4 +-
 .../features/vm/PG_uncached/arch-support.txt   |  2 +
 Documentation/features/vm/THP/arch-support.txt |  2 +
 Documentation/features/vm/TLB/arch-support.txt |  2 +
 .../features/vm/huge-vmap/arch-support.txt |  2 +
 .../features/vm/ioremap_prot/arch-support.txt  |  2 +
 .../features/vm/numa-memblock/arch-support.txt |  4 +-
 .../features/vm/pte_special/arch-support.txt   | 31 ---
 46 files changed, 279 insertions(+), 128 deletions(-)
 delete mode 100644 Documentation/features/core/BPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/cBPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/eBPF-JIT/arch-support.txt
 delete mode 100644 Documentation/features/lib/strncasecmp/arch-support.txt
 create mode 100755 Documentation/features/scripts/features-refresh.sh
 delete mode 100644 Documentation/features/vm/pte_special/arch-support.txt

-- 
2.7.4

--
To unsubscribe from this list: send

Re: [RFC PATCH 0/3] Documentation/features: Provide and apply "features-refresh.sh"

[Andrea Parri]

On Wed, Apr 04, 2018 at 06:56:32AM +0200, Ingo Molnar wrote:
> 
> * Andrea Parri <andrea.pa...@amarulasolutions.com> wrote:
> 
> > In Ingo's words [1]:
> > 
> >   "[...]  what should be done instead is to write a script that refreshes
> >all the arch-support.txt files in-place. [...]
> > 
> >It's OK for the script to have various quirks for weirdly implemented
> >features and exceptions: i.e. basically whenever it gets a feature wrong,
> >we can just tweak the script with quirks to make it all work out of box.
> > 
> >[...]  But in the end there should only be a single new script:
> > 
> >  Documentation/features/scripts/features-refresh.sh
> > 
> >... which operates on the arch-support.txt files and refreshes them in
> >place, and which, after all the refreshes have been committed, should
> >produce an empty 'git diff' result."
> > 
> >   "[...]  New features can then be added by basically just creating a
> >header-only arch-support.txt file, such as:
> > 
> >  triton:~/tip/Documentation/features> cat foo/bar/arch-support.txt
> >  #
> >  # Feature name:  shiny new fubar kernel feature
> >  # Kconfig:   ARCH_USE_FUBAR
> >  # description:   arch supports the fubar feature
> >  #
> > 
> >And running Documentation/features/scripts/features-refresh.sh would
> >auto-generate the arch support matrix. [...]
> >  
> >This way we soft- decouple the refreshing of the entries from the
> >introduction of the features, while still making it all easy to keep
> >sync and to extend."
> > 
> > This RFC presents a first attempt to implement such a feature/script, and
> > applies it script on top of Arnd's:
> > 
> >   git://git.kernel.org/pub/scm/linux/kernel/git/arnd/asm-generic.git 
> > arch-removal
> > 
> > Patch 1/3 provides the "features-refresh.sh" script.  Patch 2/3 removes the
> > "BPF-JIT" feature file and it creates header-only files for "cBPF-JIT" and
> > "eBPF-JIT".  Patch 3/3 presents the results of running the script; this run
> > also printed to standard output the following warnings:
> > 
> >   WARNING: '__HAVE_ARCH_STRNCASECMP' is not a valid Kconfig
> >   WARNING: 'Optimized asm/rwsem.h' is not a valid Kconfig
> >   WARNING: '!ARCH_USES_GETTIMEOFFSET' is not a valid Kconfig
> >   WARNING: '__HAVE_ARCH_PTE_SPECIAL' is not a valid Kconfig
> > 
> > (I'm sending these patches with empty commit messagges, for early feedback:
> >  I'll fill in these messages in subsequent versions if this makes sense...)
> > 
> > Cheers,
> >   Andrea
> > 
> > Andrea Parri (3):
> >   Documentation/features: Add script that refreshes the arch support status 
> > files in place
> >   Documentation/features/core: Add arch support status files for 'cBPF-JIT' 
> > and 'eBPF-JIT'
> >   Documentation/features: Refresh and auto-generate the arch support status 
> > files in place
> 
> Ok, this series is really impressive at its RFC stage already!
> 
> Beyond fixing those warnings, I'd also suggest another change: please make 
> the 
> new BPF features patch the last one, so that the 'refresh' patch shows how 
> much 
> original bit-rot we gathered recently.
> 
> The 'new features' patch should then also include the result of also running 
> the 
> script, i.e. a single patch adding the base fields and the generated parts as 
> well. That will be the usual development flow anyway - people won't do 
> two-part 
> patches just to show which bits are by hand and which are auto-generated.

Yes, I'll do.

Let me ask some hints about the warnings, as I'm not sure how to 'fix' them;
we have:

  a) __HAVE_ARCH_STRNCASECMP
 __HAVE_ARCH_PTE_SPECIAL

  b) Optimized asm/rwsem.h

  c) !ARCH_USES_GETTIMEOFFSET  

For (c), I see two options:

  1. replace that with 'ARCH_USES_GETTIMEOFFSET' (and update the status
 matrix accordingly)

  2. add logics/code to the script to handle simple boolean expressions
 (mmh, this could get nasty really soon... let's say: limiting to a
 leading '!', to start with ;)

For (a), I realize that 'grep-ing' the macros in arch-specific _sources_
does serve the purpose of producing the hard-coded status matrices; but
is this a reasonable approach? (e.g., can produce 'false-positives'?)

What could it be a suitable solution for (b)? are there Kconfig options
which I could in place of that expression? some other suggestion?

Thanks,
  Andrea


> 
> Thanks,
> 
>   Ingo
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH 0/3] Documentation/features: Provide and apply "features-refresh.sh"

[Andrea Parri]

In Ingo's words [1]:

  "[...]  what should be done instead is to write a script that refreshes
   all the arch-support.txt files in-place. [...]

   It's OK for the script to have various quirks for weirdly implemented
   features and exceptions: i.e. basically whenever it gets a feature wrong,
   we can just tweak the script with quirks to make it all work out of box.

   [...]  But in the end there should only be a single new script:

 Documentation/features/scripts/features-refresh.sh

   ... which operates on the arch-support.txt files and refreshes them in
   place, and which, after all the refreshes have been committed, should
   produce an empty 'git diff' result."

  "[...]  New features can then be added by basically just creating a
   header-only arch-support.txt file, such as:

 triton:~/tip/Documentation/features> cat foo/bar/arch-support.txt
 #
 # Feature name:  shiny new fubar kernel feature
 # Kconfig:   ARCH_USE_FUBAR
 # description:   arch supports the fubar feature
 #

   And running Documentation/features/scripts/features-refresh.sh would
   auto-generate the arch support matrix. [...]
 
   This way we soft- decouple the refreshing of the entries from the
   introduction of the features, while still making it all easy to keep
   sync and to extend."

This RFC presents a first attempt to implement such a feature/script, and
applies it script on top of Arnd's:

  git://git.kernel.org/pub/scm/linux/kernel/git/arnd/asm-generic.git 
arch-removal

Patch 1/3 provides the "features-refresh.sh" script.  Patch 2/3 removes the
"BPF-JIT" feature file and it creates header-only files for "cBPF-JIT" and
"eBPF-JIT".  Patch 3/3 presents the results of running the script; this run
also printed to standard output the following warnings:

  WARNING: '__HAVE_ARCH_STRNCASECMP' is not a valid Kconfig
  WARNING: 'Optimized asm/rwsem.h' is not a valid Kconfig
  WARNING: '!ARCH_USES_GETTIMEOFFSET' is not a valid Kconfig
  WARNING: '__HAVE_ARCH_PTE_SPECIAL' is not a valid Kconfig

(I'm sending these patches with empty commit messagges, for early feedback:
 I'll fill in these messages in subsequent versions if this makes sense...)

Cheers,
  Andrea

Andrea Parri (3):
  Documentation/features: Add script that refreshes the arch support
status files in place
  Documentation/features/core: Add arch support status files for
'cBPF-JIT' and 'eBPF-JIT'
  Documentation/features: Refresh and auto-generate the arch support
status files in place

 .../features/core/BPF-JIT/arch-support.txt | 31 
 .../features/core/cBPF-JIT/arch-support.txt| 32 +
 .../features/core/eBPF-JIT/arch-support.txt| 32 +
 .../core/generic-idle-thread/arch-support.txt  |  3 +-
 .../features/core/jump-labels/arch-support.txt |  1 +
 .../features/core/tracehook/arch-support.txt   |  1 +
 .../features/debug/KASAN/arch-support.txt  |  3 +-
 .../debug/gcov-profile-all/arch-support.txt|  1 +
 Documentation/features/debug/kgdb/arch-support.txt |  3 +-
 .../debug/kprobes-on-ftrace/arch-support.txt   |  1 +
 .../features/debug/kprobes/arch-support.txt|  3 +-
 .../features/debug/kretprobes/arch-support.txt |  3 +-
 .../features/debug/optprobes/arch-support.txt  |  3 +-
 .../features/debug/stackprotector/arch-support.txt |  1 +
 .../features/debug/uprobes/arch-support.txt|  5 +-
 .../debug/user-ret-profiler/arch-support.txt   |  1 +
 .../features/io/dma-api-debug/arch-support.txt |  1 +
 .../features/io/dma-contiguous/arch-support.txt|  3 +-
 .../features/io/sg-chain/arch-support.txt  |  1 +
 .../features/lib/strncasecmp/arch-support.txt  |  1 +
 .../locking/cmpxchg-local/arch-support.txt |  3 +-
 .../features/locking/lockdep/arch-support.txt  |  3 +-
 .../locking/queued-rwlocks/arch-support.txt|  9 ++--
 .../locking/queued-spinlocks/arch-support.txt  |  7 +--
 .../locking/rwsem-optimized/arch-support.txt   |  1 +
 .../features/perf/kprobes-event/arch-support.txt   |  5 +-
 .../features/perf/perf-regs/arch-support.txt   |  3 +-
 .../features/perf/perf-stackdump/arch-support.txt  |  3 +-
 .../sched/membarrier-sync-core/arch-support.txt|  1 +
 .../features/sched/numa-balancing/arch-support.txt |  5 +-
 Documentation/features/scripts/features-refresh.sh | 55 ++
 .../seccomp/seccomp-filter/arch-support.txt|  5 +-
 .../time/arch-tick-broadcast/arch-support.txt  |  3 +-
 .../features/time/clockevents/arch-support.txt |  3 +-
 .../time/context-tracking/arch-support.txt |  1 +
 .../features/time/irq-time-acct/arch-support.txt   |  3 +-
 .../time/modern-timekeeping/arch-support.txt   |  1 +
 .../features/time/virt-cpuacct/arch-support.txt|  1 +
 .../features/vm/ELF-ASLR/arch-support.txt  |  3 +-
 .../featu

[PATCH 2/3] Documentation/features/core: Add arch support status files for 'cBPF-JIT' and 'eBPF-JIT'

[Andrea Parri]

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
---
 .../features/core/BPF-JIT/arch-support.txt | 31 --
 .../features/core/cBPF-JIT/arch-support.txt|  5 
 .../features/core/eBPF-JIT/arch-support.txt|  5 
 3 files changed, 10 insertions(+), 31 deletions(-)
 delete mode 100644 Documentation/features/core/BPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/cBPF-JIT/arch-support.txt
 create mode 100644 Documentation/features/core/eBPF-JIT/arch-support.txt

diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt 
b/Documentation/features/core/BPF-JIT/arch-support.txt
deleted file mode 100644
index 0b96b4e1e7d4a..0
--- a/Documentation/features/core/BPF-JIT/arch-support.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-#
-# Feature name:  BPF-JIT
-# Kconfig:   HAVE_BPF_JIT
-# description:   arch supports BPF JIT optimizations
-#
----
-| arch |status|
----
-|   alpha: | TODO |
-| arc: | TODO |
-| arm: |  ok  |
-|   arm64: |  ok  |
-| c6x: | TODO |
-|   h8300: | TODO |
-| hexagon: | TODO |
-|ia64: | TODO |
-|m68k: | TODO |
-|  microblaze: | TODO |
-|mips: |  ok  |
-|   nios2: | TODO |
-|openrisc: | TODO |
-|  parisc: | TODO |
-| powerpc: |  ok  |
-|s390: |  ok  |
-|  sh: | TODO |
-|   sparc: |  ok  |
-|  um: | TODO |
-|   unicore32: | TODO |
-| x86: |  ok  |
-|  xtensa: | TODO |
----
diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt 
b/Documentation/features/core/cBPF-JIT/arch-support.txt
new file mode 100644
index 0..2ae2a7106e67d
--- /dev/null
+++ b/Documentation/features/core/cBPF-JIT/arch-support.txt
@@ -0,0 +1,5 @@
+#
+# Feature name:  cBPF-JIT
+# Kconfig:   HAVE_CBPF_JIT
+# description:   arch supports cBPF JIT optimizations
+#
diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt 
b/Documentation/features/core/eBPF-JIT/arch-support.txt
new file mode 100644
index 0..c8b0b458b9cec
--- /dev/null
+++ b/Documentation/features/core/eBPF-JIT/arch-support.txt
@@ -0,0 +1,5 @@
+#
+# Feature name:  eBPF-JIT
+# Kconfig:   HAVE_EBPF_JIT
+# description:   arch supports eBPF JIT optimizations
+#
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 3/3] Documentation/features: Refresh and auto-generate the arch support status files in place

[Andrea Parri]

Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
---
 .../features/core/cBPF-JIT/arch-support.txt| 27 ++
 .../features/core/eBPF-JIT/arch-support.txt| 27 ++
 .../core/generic-idle-thread/arch-support.txt  |  3 ++-
 .../features/core/jump-labels/arch-support.txt |  1 +
 .../features/core/tracehook/arch-support.txt   |  1 +
 .../features/debug/KASAN/arch-support.txt  |  3 ++-
 .../debug/gcov-profile-all/arch-support.txt|  1 +
 Documentation/features/debug/kgdb/arch-support.txt |  3 ++-
 .../debug/kprobes-on-ftrace/arch-support.txt   |  1 +
 .../features/debug/kprobes/arch-support.txt|  3 ++-
 .../features/debug/kretprobes/arch-support.txt |  3 ++-
 .../features/debug/optprobes/arch-support.txt  |  3 ++-
 .../features/debug/stackprotector/arch-support.txt |  1 +
 .../features/debug/uprobes/arch-support.txt|  5 ++--
 .../debug/user-ret-profiler/arch-support.txt   |  1 +
 .../features/io/dma-api-debug/arch-support.txt |  1 +
 .../features/io/dma-contiguous/arch-support.txt|  3 ++-
 .../features/io/sg-chain/arch-support.txt  |  1 +
 .../features/lib/strncasecmp/arch-support.txt  |  1 +
 .../locking/cmpxchg-local/arch-support.txt |  3 ++-
 .../features/locking/lockdep/arch-support.txt  |  3 ++-
 .../locking/queued-rwlocks/arch-support.txt|  9 
 .../locking/queued-spinlocks/arch-support.txt  |  7 +++---
 .../locking/rwsem-optimized/arch-support.txt   |  1 +
 .../features/perf/kprobes-event/arch-support.txt   |  5 ++--
 .../features/perf/perf-regs/arch-support.txt   |  3 ++-
 .../features/perf/perf-stackdump/arch-support.txt  |  3 ++-
 .../sched/membarrier-sync-core/arch-support.txt|  1 +
 .../features/sched/numa-balancing/arch-support.txt |  5 ++--
 .../seccomp/seccomp-filter/arch-support.txt|  5 ++--
 .../time/arch-tick-broadcast/arch-support.txt  |  3 ++-
 .../features/time/clockevents/arch-support.txt |  3 ++-
 .../time/context-tracking/arch-support.txt |  1 +
 .../features/time/irq-time-acct/arch-support.txt   |  3 ++-
 .../time/modern-timekeeping/arch-support.txt   |  1 +
 .../features/time/virt-cpuacct/arch-support.txt|  1 +
 .../features/vm/ELF-ASLR/arch-support.txt  |  3 ++-
 .../features/vm/PG_uncached/arch-support.txt   |  1 +
 Documentation/features/vm/THP/arch-support.txt |  1 +
 Documentation/features/vm/TLB/arch-support.txt |  1 +
 .../features/vm/huge-vmap/arch-support.txt |  1 +
 .../features/vm/ioremap_prot/arch-support.txt  |  1 +
 .../features/vm/numa-memblock/arch-support.txt |  3 ++-
 .../features/vm/pte_special/arch-support.txt   |  1 +
 44 files changed, 127 insertions(+), 31 deletions(-)

diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt 
b/Documentation/features/core/cBPF-JIT/arch-support.txt
index 2ae2a7106e67d..6b829e27c268a 100644
--- a/Documentation/features/core/cBPF-JIT/arch-support.txt
+++ b/Documentation/features/core/cBPF-JIT/arch-support.txt
@@ -3,3 +3,30 @@
 # Kconfig:   HAVE_CBPF_JIT
 # description:   arch supports cBPF JIT optimizations
 #
+---
+| arch |status|
+---
+|   alpha: | TODO |
+| arc: | TODO |
+| arm: | TODO |
+|   arm64: | TODO |
+| c6x: | TODO |
+|   h8300: | TODO |
+| hexagon: | TODO |
+|ia64: | TODO |
+|m68k: | TODO |
+|  microblaze: | TODO |
+|mips: |  ok  |
+|   nios2: | TODO |
+|openrisc: | TODO |
+|  parisc: | TODO |
+| powerpc: |  ok  |
+|   riscv: | TODO |
+|s390: | TODO |
+|  sh: | TODO |
+|   sparc: |  ok  |
+|  um: | TODO |
+|   unicore32: | TODO |
+| x86: | TODO |
+|  xtensa: | TODO |
+---
diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt 
b/Documentation/features/core/eBPF-JIT/arch-support.txt
index c8b0b458b9cec..4a4ab34ee293a 100644
--- a/Documentation/features/core/eBPF-JIT/arch-support.txt
+++ b/Documentation/features/core/eBPF-JIT/arch-support.txt
@@ -3,3 +3,30 @@
 # Kconfig:   HAVE_EBPF_JIT
 # description:   arch supports eBPF JIT optimizations
 #
+---
+| arch |status|
+---
+|   alpha: | TODO |
+| arc: | TODO |
+| arm: |  ok  |
+|   arm64: |  ok  |
+| c6x: | TODO |
+|   h8300: | TODO |
+| hexagon: | TODO |
+|ia64: | TODO |
+|m68k: | TODO |
+|  microblaze: | TODO |
+|mips: |  ok  |
+|   nios2: | TODO |
+|openrisc: | TODO |
+|  parisc: | TODO |
+| powerpc: |  ok  |
+|   riscv: | TODO |
+|s390:

[PATCH 1/3] Documentation/features: Add script that refreshes the arch support status files in place

[Andrea Parri]

Suggested-by: Ingo Molnar <mi...@kernel.org>
Signed-off-by: Andrea Parri <andrea.pa...@amarulasolutions.com>
---
 Documentation/features/scripts/features-refresh.sh | 55 ++
 1 file changed, 55 insertions(+)
 create mode 100755 Documentation/features/scripts/features-refresh.sh

diff --git a/Documentation/features/scripts/features-refresh.sh 
b/Documentation/features/scripts/features-refresh.sh
new file mode 100755
index 0..ae3e9d5d3f262
--- /dev/null
+++ b/Documentation/features/scripts/features-refresh.sh
@@ -0,0 +1,55 @@
+#
+# Small script that refreshes the kernel feature support status in place.
+#
+
+for F_FILE in Documentation/features/*/*/arch-support.txt; do
+   K=$(grep "^# Kconfig:" "$F_FILE" | cut -c26-)
+   K_VALID="false" # K is 'valid' iff there exists a Kconfig file
+   # (for some arch) containing K.
+
+   for ARCH_DIR in arch/*/; do
+   K_FILES=$(find $ARCH_DIR -name "Kconfig*")
+
+   K_GREP=$(grep "$K" $K_FILES)
+   if [ ! -z "$K_GREP" ]; then
+   K_VALID="true"
+   break
+   fi
+   done
+
+   if [ "$K_VALID" = "false" ]; then
+   printf "WARNING: '%s' is not a valid Kconfig\n" "$K"
+   fi
+
+   T_FILE="$F_FILE.tmp"
+
+   grep "^#" $F_FILE > $T_FILE
+   echo "---" >> $T_FILE
+   echo "| arch |status|" >> $T_FILE
+   echo "---" >> $T_FILE
+
+   for ARCH_DIR in arch/*/; do
+   ARCH=$(echo $ARCH_DIR | sed -e 's/arch//g' | sed -e 's/\///g')
+   K_FILES=$(find $ARCH_DIR -name "Kconfig*")
+
+   K_GREP=$(grep "$K" $K_FILES)
+   if [ ! -z "$K_GREP" ]; then
+   # K is 'supported by a given arch', if there exists
+   # a Kconfig file for this arch containing K.
+   printf "|%12s: |  ok  |\n" "$ARCH" >> $T_FILE
+   else
+   # ... Otherwise: Keep the original status (if any);
+   # default to "not yet supported".
+   S=$(grep -v "^#" "$F_FILE" | grep " $ARCH:")
+   if [ ! -z "$S" ]; then
+   echo "$S" >> $T_FILE
+   else
+   printf "|%12s: | TODO |\n" "$ARCH" \
+   >> $T_FILE
+   fi
+   fi
+   done
+
+   echo "---" >> $T_FILE
+   mv $T_FILE $F_FILE
+done
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Question] Documentation/features: More automation/scripting help?

[Andrea Parri]

Hi all,

The directory (not yet three years old although, I freely admit, I've
only recently become aware of it) provides arch. support matrices for
more than 40 generic kernel features that need per-arch. support:

This is a superb project! ;-)  and not a simple one given that, to be
effective, this requires the prompt collaboration between (the intere-
sted) features maintainers/developers, every architecture maintainers,
and documentation maintainers.

There currently appear to be some mismatches between such doc and the
the actual state of the code (e.g., missing architecture, feature not
existing anymore, status flags out-of-date). Realized this, I started
to patch the doc, but this process became soon tedious (consider also
that I barely know what some of these features are about...).

Hence this post. I am wondering if it would make sense to script some
of these matrices.  So, rather than (or together with) using the cur-
rently hard-coded matrices, try to (automatically) generate them from
the sources/configs. Consider the sketch below (sorry for the raw sh).

diff --git a/Documentation/features/list-arch.sh 
b/Documentation/features/list-arch.sh
index c16b5b5956889..cdec0c1db9db2 100755
--- a/Documentation/features/list-arch.sh
+++ b/Documentation/features/list-arch.sh
@@ -18,7 +18,13 @@ for F in */*/arch-support.txt; do
   C=$(grep -h "^# Kconfig:" $F | cut -c25-)
   D=$(grep -h "^# description:" $F | cut -c25-)
   S=$(grep -hw $ARCH $F | cut -d\| -f3)
+  myS=$(grep -h $C ../../arch/$ARCH/Kconfig)
+  if [ -z "$myS" ]; then
+ myS=" -- "
+  else
+ myS=" ok "
+  fi
 
-  printf "%10s/%-22s:%s| %35s # %s\n" "$SUBSYS" "$N" "$S" "$C" "$D"
+  printf "%10s/%-22s:%s VS. %s| %35s # %s\n" "$SUBSYS" "$N" "$S" "$myS" "$C" 
"$D"
 done
 

With this diff.,

andrea@andrea:~$ ./Documentation/features/list-arch.sh riscv > /tmp/riscv.txt
grep: asm/rwsem.h: No such file or directory
andrea@andrea:~$ cat /tmp/riscv.txt
#
# Kernel feature support matrix of the 'riscv' architecture:
#
  core/ BPF-JIT  : VS.  -- |
HAVE_BPF_JIT #  arch supports BPF JIT optimizations
  core/ generic-idle-thread  : VS.  ok | 
GENERIC_SMP_IDLE_THREAD #  arch makes use of the generic SMP idle thread 
facility
  core/ jump-labels  : VS.  -- |
HAVE_ARCH_JUMP_LABEL #  arch supports live patched, high efficiency branches
  core/ tracehook: VS.  ok | 
HAVE_ARCH_TRACEHOOK #  arch supports tracehook (ptrace) register handling APIs
 debug/ gcov-profile-all : VS.  -- |   
ARCH_HAS_GCOV_PROFILE_ALL #  arch supports whole-kernel GCOV code coverage 
profiling
 debug/ KASAN: VS.  -- | 
HAVE_ARCH_KASAN #  arch supports the KASAN runtime memory checker
 debug/ kgdb : VS.  -- |  
HAVE_ARCH_KGDB #  arch supports the kGDB kernel debugger
 debug/ kprobes  : VS.  ok |
HAVE_KPROBES #  arch supports live patched kernel probe
 debug/ kprobes-on-ftrace: VS.  -- |  
HAVE_KPROBES_ON_FTRACE #  arch supports combined kprobes and ftrace live 
patching
 debug/ kretprobes   : VS.  -- | 
HAVE_KRETPROBES #  arch supports kernel function-return probes
 debug/ optprobes: VS.  -- |  
HAVE_OPTPROBES #  arch supports live patched optprobes
 debug/ stackprotector   : VS.  -- |  
HAVE_CC_STACKPROTECTOR #  arch supports compiler driven stack overflow 
protection
 debug/ uprobes  : VS.  -- |   
ARCH_SUPPORTS_UPROBES #  arch supports live patched user probes
 debug/ user-ret-profiler: VS.  -- |   
HAVE_USER_RETURN_NOTIFIER #  arch supports user-space return from system call 
profiler
io/ dma-api-debug: VS.  ok |  
HAVE_DMA_API_DEBUG #  arch supports DMA debug facilities
io/ dma-contiguous   : VS.  ok | 
HAVE_DMA_CONTIGUOUS #  arch supports the DMA CMA (continuous memory allocator)
io/ sg-chain : VS.  -- |   
ARCH_HAS_SG_CHAIN #  arch supports chained scatter-gather lists
   lib/ strncasecmp  : VS.  -- | 
__HAVE_ARCH_STRNCASECMP #  arch provides an optimized strncasecmp() function
   locking/ cmpxchg-local: VS.  -- |  
HAVE_CMPXCHG_LOCAL #  arch supports the this_cpu_cmpxchg() API
   locking/ lockdep  : VS.  -- | 
LOCKDEP_SUPPORT #  arch supports the runtime locking correctness debug facility
   locking/ queued-rwlocks   : VS.  -- | 
ARCH_USE_QUEUED_RWLOCKS #  arch supports queued rwlocks
   locking/ queued-spinlocks : VS.  -- |   
ARCH_USE_QUEUED_SPINLOCKS #  arch supports queued spinlocks
   locking/ rwsem-optimized  : VS.  -- |   

Re: [RFC tip/locking/lockdep v5 16/17] lockdep: Documention for recursive read lock detection reasoning

[Andrea Parri]

On Thu, Feb 22, 2018 at 03:09:03PM +0800, Boqun Feng wrote:
> As now we support recursive read lock deadlock detection, add related
> explanation in the Documentation/lockdep/lockdep-desgin.txt:
> 
> * Definition of recursive read locks, non-recursive locks, strong
>   dependency path and notions of -(**)->.
> 
> * Lockdep's assumption.
> 
> * Informal proof of recursive read lock deadlock detection.

Once again... much appreciated!!, thanks for sharing.


> 
> Signed-off-by: Boqun Feng 
> Cc: Randy Dunlap 
> ---
>  Documentation/locking/lockdep-design.txt | 170 
> +++
>  1 file changed, 170 insertions(+)
> 
> diff --git a/Documentation/locking/lockdep-design.txt 
> b/Documentation/locking/lockdep-design.txt
> index 382bc25589c2..fd8a8d97ce58 100644
> --- a/Documentation/locking/lockdep-design.txt
> +++ b/Documentation/locking/lockdep-design.txt
> @@ -284,3 +284,173 @@ Run the command and save the output, then compare 
> against the output from
>  a later run of this command to identify the leakers.  This same output
>  can also help you find situations where runtime lock initialization has
>  been omitted.
> +
> +Recursive Read Deadlock Detection:
> +--
> +Lockdep now is equipped with deadlock detection for recursive read locks.
> +
> +Recursive read locks, as their name indicates, are the locks able to be
> +acquired recursively. Unlike non-recursive read locks, recursive read locks
> +only get blocked by current write lock *holders* other than write lock
> +*waiters*, for example:
> +
> + TASK A: TASK B:
> +
> + read_lock(X);
> +
> + write_lock(X);
> +
> + read_lock(X);
> +
> +is not a deadlock for recursive read locks, as while the task B is waiting 
> for
> +the lock X, the second read_lock() doesn't need to wait because it's a 
> recursive
> +read lock.
> +
> +Note that a lock can be a write lock(exclusive lock), a non-recursive read 
> lock
> +(non-recursive shared lock) or a recursive read lock(recursive shared lock),
> +depending on the API used to acquire it(more specifically, the value of the
> +'read' parameter for lock_acquire(...)). In other words, a single lock 
> instance
> +has three types of acquisition depending on the acquisition functions:
> +exclusive, non-recursive read, and recursive read.
> +
> +That said, recursive read locks could introduce deadlocks too, considering 
> the
> +following:
> +
> + TASK A: TASK B:
> +
> + read_lock(X);
> + read_lock(Y);
> + write_lock(Y);
> + write_lock(X);
> +
> +, neither task could get the write locks because the corresponding read locks
> +are held by each other.
> +
> +Lockdep could detect recursive read lock related deadlocks. The 
> dependencies(edges)
> +in the lockdep graph are classified into four categories:
> +
> +1) -(NN)->: non-recursive to non-recursive dependency, non-recursive locks 
> include
> +non-recursive read locks, write locks and exclusive locks(e.g. 
> spinlock_t).
> + They are treated equally in deadlock detection. "X -(NN)-> Y" means
> +X -> Y and both X and Y are non-recursive locks.
> +
> +2) -(RN)->: recursive to non-recursive dependency, recursive locks means 
> recursive read
> + locks. "X -(RN)-> Y" means X -> Y and X is recursive read lock and
> +Y is non-recursive lock.
> +
> +3) -(NR)->: non-recursive to recursive dependency, "X -(NR)-> Y" means X -> 
> Y and X is
> +non-recursive lock and Y is recursive lock.
> +
> +4) -(RR)->: recursive to recursive dependency, "X -(RR)-> Y" means X -> Y 
> and both X
> +and Y are recursive locks.
> +
> +Note that given two locks, they may have multiple dependencies between them, 
> for example:
> +
> + TASK A:
> +
> + read_lock(X);
> + write_lock(Y);
> + ...
> +
> + TASK B:
> +
> + write_lock(X);
> + write_lock(Y);
> +
> +, we have both X -(RN)-> Y and X -(NN)-> Y in the dependency graph.
> +
> +And obviously a non-recursive lock can block the corresponding recursive 
> lock,
> +and vice versa. Besides a non-recursive lock may block the other 
> non-recursive
> +lock of the same instance(e.g. a write lock may block a corresponding
> +non-recursive read lock and vice versa).
> +
> +We use -(*N)-> for edges that is either -(RN)-> or -(NN)->, the similar for 
> -(N*)->,
> +-(*R)-> and -(R*)->
> +
> +A "path" is a series of conjunct dependency edges in the graph. And we 
> define a
> +"strong" path, which indicates the strong dependency throughout each 
> dependency
> +in the path, as the path that doesn't have two conjunct edges(dependencies) 
> as
> +-(*R)-> and -(R*)->. IOW, a "strong" path is a path from a lock walking to 
> another
> +through the lock dependencies, and if X -> Y -> Z in the path(where X, Y, Z 
> are

Re: [PATCH 1/2] Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"

[Andrea Parri]

On Fri, Feb 09, 2018 at 06:29:23AM -0800, Paul E. McKenney wrote:
> On Fri, Feb 09, 2018 at 01:50:51PM +0100, Andrea Parri wrote:
> > On Fri, Feb 09, 2018 at 04:31:00AM -0800, Paul E. McKenney wrote:
> > > On Sun, Feb 04, 2018 at 07:37:08PM +0100, Andrea Parri wrote:
> > > > Hi Akira,
> > > > 
> > > > On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> > > > > Hi Paul,
> > > > > CC: Andrea
> > > > > 
> > > > > This is intentionally off the list, as I was not cc'd in the thread.
> > > > > If you think it is worthwhile, could you help me join the thread by
> > > > > forwarding the following part as a reply to your message, plus CC: to 
> > > > > me.
> > > > 
> > > > [CCing lists and other people]
> > > > 
> > > > 
> > > > > 
> > > > > On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > > > > > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> > > > > >> Recent efforts led to the specification of a memory consistency 
> > > > > >> model
> > > > > >> for the Linux kernel [1], which "can (roughly speaking) be thought 
> > > > > >> of
> > > > > >> as an automated version of memory-barriers.txt" and which is (in 
> > > > > >> turn)
> > > > > >> "accompanied by extensive documentation on its use and its design".
> > > > > >> 
> > > > > >> Make sure that the (occasional) reader of memory-barriers.txt will 
> > > > > >> be
> > > > > >> aware of these developments.
> > > > > >> 
> > > > > >> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> > > > > >> 
> > > > > >> Signed-off-by: Andrea Parri <parri.andrea@x>
> > > > > > 
> > > > > > I am inclined to pull in something along these lines, but would like
> > > > > > some feedback on the wording, especially how "official" we want to
> > > > > > make the memory model to be.
> > > > > > 
> > > > > > Thoughts?
> > > > > 
> > > > > The change log of commit e7720af5f9ac ("locking/Documentation: Add 
> > > > > disclaimer") says:
> > > > > 
> > > > > It appears people are reading this document as a requirements 
> > > > > list for
> > > > > building hardware. This is not the intent of this document. Nor 
> > > > > is it
> > > > > particularly suited for this purpose.
> > > > > 
> > > > > The primary purpose of this document is our collective attempt to 
> > > > > define
> > > > > a set of primitives that (hopefully) allow us to write correct 
> > > > > code on
> > > > > the myriad of SMP platforms Linux supports.
> > > > > 
> > > > > Its a definite work in progress as our understanding of these 
> > > > > platforms,
> > > > > and memory ordering in general, progresses.
> > > > > 
> > > > > Nor does being mentioned in this document mean we think its a
> > > > > particularly good idea; the data dependency barrier required by 
> > > > > Alpha
> > > > > being a prime example. Yes we have it, no you're insane to 
> > > > > require it
> > > > > when building new hardware.
> > > > > 
> > > > > My take on the Linux Kernel memory-consistency model is a supplement 
> > > > > of
> > > > > memory-barriers.txt and the disclaimer also applies to the memory 
> > > > > model.
> > > > > 
> > > > > > 
> > > > > > If I don't hear otherwise in a couple of days, I will pull this as 
> > > > > > is.
> > > > > > 
> > > > > > Thanx, Paul
> > > > > > 
> > > > > >> ---
> > > > > >>  Documentation/memory-barriers.txt | 4 +++-
> > > > > >>  1 file changed, 3 insertions(+), 1 deletion(-)
> > > > > >> 
> > > > > >> diff --git

Re: [PATCH 1/2] Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"

[Andrea Parri]

On Fri, Feb 09, 2018 at 04:31:00AM -0800, Paul E. McKenney wrote:
> On Sun, Feb 04, 2018 at 07:37:08PM +0100, Andrea Parri wrote:
> > Hi Akira,
> > 
> > On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> > > Hi Paul,
> > > CC: Andrea
> > > 
> > > This is intentionally off the list, as I was not cc'd in the thread.
> > > If you think it is worthwhile, could you help me join the thread by
> > > forwarding the following part as a reply to your message, plus CC: to me.
> > 
> > [CCing lists and other people]
> > 
> > 
> > > 
> > > On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > > > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> > > >> Recent efforts led to the specification of a memory consistency model
> > > >> for the Linux kernel [1], which "can (roughly speaking) be thought of
> > > >> as an automated version of memory-barriers.txt" and which is (in turn)
> > > >> "accompanied by extensive documentation on its use and its design".
> > > >> 
> > > >> Make sure that the (occasional) reader of memory-barriers.txt will be
> > > >> aware of these developments.
> > > >> 
> > > >> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> > > >> 
> > > >> Signed-off-by: Andrea Parri <parri.andrea@x>
> > > > 
> > > > I am inclined to pull in something along these lines, but would like
> > > > some feedback on the wording, especially how "official" we want to
> > > > make the memory model to be.
> > > > 
> > > > Thoughts?
> > > 
> > > The change log of commit e7720af5f9ac ("locking/Documentation: Add 
> > > disclaimer") says:
> > > 
> > > It appears people are reading this document as a requirements list for
> > > building hardware. This is not the intent of this document. Nor is it
> > > particularly suited for this purpose.
> > > 
> > > The primary purpose of this document is our collective attempt to 
> > > define
> > > a set of primitives that (hopefully) allow us to write correct code on
> > > the myriad of SMP platforms Linux supports.
> > > 
> > > Its a definite work in progress as our understanding of these 
> > > platforms,
> > > and memory ordering in general, progresses.
> > > 
> > > Nor does being mentioned in this document mean we think its a
> > > particularly good idea; the data dependency barrier required by Alpha
> > > being a prime example. Yes we have it, no you're insane to require it
> > > when building new hardware.
> > > 
> > > My take on the Linux Kernel memory-consistency model is a supplement of
> > > memory-barriers.txt and the disclaimer also applies to the memory model.
> > > 
> > > > 
> > > > If I don't hear otherwise in a couple of days, I will pull this as is.
> > > > 
> > > > Thanx, Paul
> > > > 
> > > >> ---
> > > >>  Documentation/memory-barriers.txt | 4 +++-
> > > >>  1 file changed, 3 insertions(+), 1 deletion(-)
> > > >> 
> > > >> diff --git a/Documentation/memory-barriers.txt 
> > > >> b/Documentation/memory-barriers.txt
> > > >> index a863009849a3b..8cc3f098f4a7d 100644
> > > >> --- a/Documentation/memory-barriers.txt
> > > >> +++ b/Documentation/memory-barriers.txt
> > > >> @@ -17,7 +17,9 @@ meant as a guide to using the various memory 
> > > >> barriers provided by Linux, but
> > > >>  in case of any doubt (and there are many) please ask.
> > > >> 
> > > >>  To repeat, this document is not a specification of what Linux expects 
> > > >> from
> > > >> -hardware.
> > > >> +hardware.  For such a specification, in the form of a memory 
> > > >> consistency
> > > >> +model, and for documentation about its usage and its design, the 
> > > >> reader is
> > > >> +referred to "tools/memory-model/".
> > > >> 
> > > 
> > > Adding cross-reference in this way can _weaken_ the message of the 
> > > disclaimer.
> > 
> > Thank y

Re: [PATCH 1/2] Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"

[Andrea Parri]

Hi Akira,

On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> Hi Paul,
> CC: Andrea
> 
> This is intentionally off the list, as I was not cc'd in the thread.
> If you think it is worthwhile, could you help me join the thread by
> forwarding the following part as a reply to your message, plus CC: to me.

[CCing lists and other people]


> 
> On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> >> Recent efforts led to the specification of a memory consistency model
> >> for the Linux kernel [1], which "can (roughly speaking) be thought of
> >> as an automated version of memory-barriers.txt" and which is (in turn)
> >> "accompanied by extensive documentation on its use and its design".
> >> 
> >> Make sure that the (occasional) reader of memory-barriers.txt will be
> >> aware of these developments.
> >> 
> >> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> >> 
> >> Signed-off-by: Andrea Parri <parri.andrea@x>
> > 
> > I am inclined to pull in something along these lines, but would like
> > some feedback on the wording, especially how "official" we want to
> > make the memory model to be.
> > 
> > Thoughts?
> 
> The change log of commit e7720af5f9ac ("locking/Documentation: Add 
> disclaimer") says:
> 
> It appears people are reading this document as a requirements list for
> building hardware. This is not the intent of this document. Nor is it
> particularly suited for this purpose.
> 
> The primary purpose of this document is our collective attempt to define
> a set of primitives that (hopefully) allow us to write correct code on
> the myriad of SMP platforms Linux supports.
> 
> Its a definite work in progress as our understanding of these platforms,
> and memory ordering in general, progresses.
> 
> Nor does being mentioned in this document mean we think its a
> particularly good idea; the data dependency barrier required by Alpha
> being a prime example. Yes we have it, no you're insane to require it
> when building new hardware.
> 
> My take on the Linux Kernel memory-consistency model is a supplement of
> memory-barriers.txt and the disclaimer also applies to the memory model.
> 
> > 
> > If I don't hear otherwise in a couple of days, I will pull this as is.
> > 
> > Thanx, Paul
> > 
> >> ---
> >>  Documentation/memory-barriers.txt | 4 +++-
> >>  1 file changed, 3 insertions(+), 1 deletion(-)
> >> 
> >> diff --git a/Documentation/memory-barriers.txt 
> >> b/Documentation/memory-barriers.txt
> >> index a863009849a3b..8cc3f098f4a7d 100644
> >> --- a/Documentation/memory-barriers.txt
> >> +++ b/Documentation/memory-barriers.txt
> >> @@ -17,7 +17,9 @@ meant as a guide to using the various memory barriers 
> >> provided by Linux, but
> >>  in case of any doubt (and there are many) please ask.
> >> 
> >>  To repeat, this document is not a specification of what Linux expects from
> >> -hardware.
> >> +hardware.  For such a specification, in the form of a memory consistency
> >> +model, and for documentation about its usage and its design, the reader is
> >> +referred to "tools/memory-model/".
> >> 
> 
> Adding cross-reference in this way can _weaken_ the message of the disclaimer.

Thank you for your remarks; I do share the same concern.


> What about adding it in the previous sentence as the patch appended bellow?

I do like this idea: I believe that my phrasing (and that "what Linux
expects from hardware") may be easily subject to misinterpretation...
which your solution can avoid.

  Andrea


> 
> The tag use in the change log may need adjustments. I'm not familiar with the
> manner in modifying other persons' patches. Of course, the wording itself can
> be improved further.  Any feedback is welcome.
> 
>  Thanks, Akira
> 
> >>  The purpose of this document is twofold:
> >> 
> >> -- 
> >> 2.7.4
> >> 
> 
> 8<---
> From 714e8c4b09acd6e965de116532dce05070b9e636 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <aki...@gmail.com>
> Date: Mon, 5 Feb 2018 00:28:36 +0900
> Subject: [PATCH] Documentation/memory-barriers.txt: cross-reference 
> "tools/memory-model/"
> 
> Recent efforts led to the specification of a memory consistency model
> for the Linux kernel [

Re: [PATCH 2/2] MAINTAINERS: list file memory-barriers.txt within the LKMM entry

[Andrea Parri]

On Fri, Feb 02, 2018 at 03:51:02PM -0800, Paul E. McKenney wrote:
> On Fri, Feb 02, 2018 at 10:13:42AM +0100, Andrea Parri wrote:
> > Now that a formal specification of the LKMM has become available to
> > the developer, some concern about how to track changes to the model
> > on the level of the "high-level documentation" was raised.
> > 
> > A first "mitigation" to this issue, suggested by Will, is to assign
> > maintainership (and responsibility!!)  of such documentation (here,
> > memory-barriers.txt) to the maintainers of the LKMM themselves.
> > 
> > Suggested-by: Will Deacon <will.dea...@arm.com>
> > Signed-off-by: Andrea Parri <parri.and...@gmail.com>
> 
> Very good, thank you, queued!  Please see below for the usual commit-log
> rework.  BTW, in future submissions, could you please capitalize the
> first word after the colon (":") in the subject line?  It is all too
> easy for me to forget to change this, as Ingo can attest.  ;-)

Sorry, I'll do my best! ;-)


> 
> If we are going to continue to use the LKMM acronym, should we make the
> first line of the MAINTAINERS block look something like this?

I've no strong opinion about whether we should, but it makes sense to me.
(The acronym is currently defined (and heavily used) in explanation.txt.)

Thanks,
  Andrea


> 
>   LINUX KERNEL MEMORY CONSISTENCY MODEL (LKMM)
> 
> One alternative would be to start calling it LKMCM, though that does
> look a bit like a Roman numeral.  ;-)
> 
>   Thanx, Paul
> 
> 
> 
> commit 2f80571625dc2d1977acdef79267ba1645b07c53
> Author: Andrea Parri <parri.and...@gmail.com>
> Date:   Fri Feb 2 10:13:42 2018 +0100
> 
> MAINTAINERS: List file memory-barriers.txt within the LKMM entry
> 
> We now have a shiny new Linux-kernel memory model (LKMM) and the old
> tried-and-true Documentation/memory-barrier.txt.  It would be good to
> keep these automatically synchronized, but in the meantime we need at
> least let people know that they are related.  Will suggested adding the
> Documentation/memory-barrier.txt file to the LKMM maintainership list,
> thus making the LKMM maintainers responsible for both the old and the new.
> This commit follows Will's excellent suggestion.
> 
> Suggested-by: Will Deacon <will.dea...@arm.com>
> Signed-off-by: Andrea Parri <parri.and...@gmail.com>
> Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ba4dc08fbe95..e6ad9b44e8fb 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8101,6 +8101,7 @@ L:  linux-ker...@vger.kernel.org
>  S:   Supported
>  T:   git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git
>  F:   tools/memory-model/
> +F:   Documentation/memory-barriers.txt
>  
>  LINUX SECURITY MODULE (LSM) FRAMEWORK
>  M:   Chris Wright <chr...@sous-sol.org>
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/2] MAINTAINERS: list file memory-barriers.txt within the LKMM entry

[Andrea Parri]

Now that a formal specification of the LKMM has become available to
the developer, some concern about how to track changes to the model
on the level of the "high-level documentation" was raised.

A first "mitigation" to this issue, suggested by Will, is to assign
maintainership (and responsibility!!)  of such documentation (here,
memory-barriers.txt) to the maintainers of the LKMM themselves.

Suggested-by: Will Deacon <will.dea...@arm.com>
Signed-off-by: Andrea Parri <parri.and...@gmail.com>
---
 On top of: https://marc.info/?l=linux-kernel=151748668632046=2 

 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 08454be9237d7..9466907aa4db1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8106,6 +8106,7 @@ L:linux-ker...@vger.kernel.org
 S: Supported
 T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git
 F: tools/memory-model/
+F: Documentation/memory-barriers.txt
 
 LINUX SECURITY MODULE (LSM) FRAMEWORK
 M: Chris Wright <chr...@sous-sol.org>
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/2] Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"

[Andrea Parri]

Recent efforts led to the specification of a memory consistency model
for the Linux kernel [1], which "can (roughly speaking) be thought of
as an automated version of memory-barriers.txt" and which is (in turn)
"accompanied by extensive documentation on its use and its design".

Make sure that the (occasional) reader of memory-barriers.txt will be
aware of these developments.

[1] https://marc.info/?l=linux-kernel=151687290114799=2

Signed-off-by: Andrea Parri <parri.and...@gmail.com>
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index a863009849a3b..8cc3f098f4a7d 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -17,7 +17,9 @@ meant as a guide to using the various memory barriers 
provided by Linux, but
 in case of any doubt (and there are many) please ask.
 
 To repeat, this document is not a specification of what Linux expects from
-hardware.
+hardware.  For such a specification, in the form of a memory consistency
+model, and for documentation about its usage and its design, the reader is
+referred to "tools/memory-model/".
 
 The purpose of this document is twofold:
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html