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

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

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 350 bytes --]

Hi all,

After merging the akpm-current tree, today's linux-next build (htmldocs)
produced this warning:

Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline interpreted text or phrase reference start-string without end-string.

Introduced by commit

  439d477342a3 ("mm: cma: support sysfs")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Minchan Kim]

On Mon, Mar 15, 2021 at 04:35:22PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> After merging the akpm-current tree, today's linux-next build (htmldocs)
> produced this warning:
> 
> Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> 
> Introduced by commit
> 
>   439d477342a3 ("mm: cma: support sysfs")
> 

Hmm, I don't get it what happened here. Was it false-positive?

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

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 732 bytes --]

Hi Minchan,

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

I get the above from a "make htmldocs" run ... I don't know what causes
it, sorry.  [cc'ing Jon]

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Jonathan Corbet]

Stephen Rothwell <sfr@canb.auug.org.au> writes:

[Adding Mauro]

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

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

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

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

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

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Tue, 16 Mar 2021 17:09:20 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Stephen Rothwell <sfr@canb.auug.org.au> writes:
> 
> [Adding Mauro]
> 
> > On Tue, 16 Mar 2021 11:18:11 -0700 Minchan Kim <minchan@kernel.org> wrote:
> >>
> >> On Mon, Mar 15, 2021 at 04:35:22PM +1100, Stephen Rothwell wrote:
> >> > Hi all,
> >> > 
> >> > After merging the akpm-current tree, today's linux-next build (htmldocs)
> >> > produced this warning:
> >> > 
> >> > Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> >> > 
> >> > Introduced by commit
> >> > 
> >> >   	 ("mm: cma: support sysfs")
> >> >   
> >> 
> >> Hmm, I don't get it what happened here. Was it false-positive?
> >
> > I get the above from a "make htmldocs" run ... I don't know what causes
> > it, sorry.  [cc'ing Jon]
> 
> OK, this took a while to figure out.  The problem is this text in
> sysfs-kernel-mm-cma:
> 
> > 		Each CMA heap subdirectory (that is, each
> > 		/sys/kernel/mm/cma/<cma-heap-name> directory) contains the
> > 		following items:
> 
> When scripts/get_abi.pl sees the /sys/kernel/mm/... string it wants to
> turn it into a link to the matching ABI entry; at that point, the
> <text in angle brackets> collides with the Sphinx directive and you get
> that totally useless warning.
> 
> I think this is a bug in get_abi.pl. Honestly I wonder if all these
> cross-links are needed at all; if they truly are, then we shouldn't be
> making bogus ones.  Mauro, how hard would it be to make this do the
> right thing?

Actually, we need the "<>" syntax a the output document.

Basically, the script assumes that everything inside the ABI description
is ReST. So, it preserves the text untouched, except when creating
cross-references, which is the case here. The script expects an entry
for every cross-referenced symbol. In other words, something like:

	/sys/kernel/mm/cma/ 

should be converted into:

	:ref:`/sys/kernel/mm/cma/ <abi_sys_kernel_mm_cma>`

The actual output is more complex than that, as there are some special
chars that need to be escaped at the naming part.

You can check the full output of this single file with:

	$ mkdir Documentation/ABI/aa && cp Documentation/ABI/testing/sysfs-kernel-mm-cma
	$ ./scripts/get_abi.pl --dir=Documentation/ABI/aa rest

	Symbols under /sys/kernel
	-------------------------
	
	.. _abi_sys_kernel_mm_cma:
	
	+-------------------------+
	| **/sys/kernel/mm/cma/** |
	+-------------------------+
	
	Defined on file :ref:`sysfs-kernel-mm-cma <abi_file_aa_sysfs_kernel_mm_cma>`
	
	:ref:`\/sys\/kernel\/mm\/cma\/ <abi_sys_kernel_mm_cma>` contains a subdirectory for each CMA
	heap name (also sometimes called CMA areas).
	
	Each CMA heap subdirectory (that is, each
	:ref:`\/sys\/kernel\/mm\/cma\/ <abi_sys_kernel_mm_cma>`<cma-heap-name> directory) contains the
	following items:
	
	        alloc_pages_success
	        alloc_pages_fail
	
	
	.. _abi_sys_kernel_mm_cma_cma_heap_name_alloc_pages_fail:
	
	+-------------------------------------------------------------+
	| **/sys/kernel/mm/cma/<cma\-heap\-name>/alloc\_pages\_fail** |
	+-------------------------------------------------------------+
	
	Defined on file :ref:`sysfs-kernel-mm-cma <abi_file_aa_sysfs_kernel_mm_cma>`
	
	the number of pages CMA API failed to allocate
	
	
	.. _abi_sys_kernel_mm_cma_cma_heap_name_alloc_pages_success:
	
	+----------------------------------------------------------------+
	| **/sys/kernel/mm/cma/<cma\-heap\-name>/alloc\_pages\_success** |
	+----------------------------------------------------------------+
	
	Defined on file :ref:`sysfs-kernel-mm-cma <abi_file_aa_sysfs_kernel_mm_cma>`
	
	the number of pages CMA API succeeded to allocate
	
	
	.. _abi_file_aa_sysfs_kernel_mm_cma:
	
	File aa/sysfs\-kernel\-mm\-cma
	------------------------------
	
	Has the following ABI:
	
	- :ref:`\/sys\/kernel\/mm\/cma\/ <abi_sys_kernel_mm_cma>`
	
	- :ref:`\/sys\/kernel\/mm\/cma\/\<cma\-heap\-name\>\/alloc_pages_success <abi_sys_kernel_mm_cma_cma_heap_name_alloc_pages_success>`
	
	- :ref:`\/sys\/kernel\/mm\/cma\/\<cma\-heap\-name\>\/alloc_pages_fail <abi_sys_kernel_mm_cma_cma_heap_name_alloc_pages_fail>`
	
There are two separated issues here:

1) the cross-reference for "/sys/kernel/mm/cma/<cma-heap-name>"
   doesn't exist. The fix would be to do something like:

	What:           /sys/kernel/mm/cma/
	Date:           Feb 2021
	Contact:        Minchan Kim <minchan@kernel.org>
	Description:
	                /sys/kernel/mm/cma/ contains a subdirectory for each CMA
        	        heap name (also sometimes called CMA areas).

                	Each CMA heap subdirectory contains the following items:

                        	/sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_success
	                        /sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_fail

  This way, the /sys/kernel/mm/cma/<cma-heap-name>/* will produce the
  right cross-references;

2) The get_abi.pl doesn't escape "<" and ">" chars.

  The enclosed patch should do the trick. Please notice that I didn't
  check if this won't cause side effects - I'm in vacations until next
  week... too lazy to do a full test those days ;-) 

Thanks,
Mauro

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

Those characters should be escaped on cross-references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 92d9aa6cc4f5..79d195b48652 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -305,7 +305,7 @@ sub output_rest {
 		}
 
 		my $w = $what;
-		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+		$w =~ s/([\(\)\_\-\*\=\^\~\\\<\>])/\\$1/g;
 
 		if ($type ne "File") {
 			my $cur_part = $what;

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

[Mauro Carvalho Chehab]

After merging the akpm-current tree, today's linux-next build (htmldocs)
produced this warning:

	Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline interpreted text or phrase reference start-string without end-string.

Introduced by commit 439d477342a3 ("mm: cma: support sysfs")

As pointed by Jonathan, the problem is this text in
sysfs-kernel-mm-cma:

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

Is not parsed well, becase the major/minor signs need to be
escaped, when converted into cross-references.

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Reported-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 92d9aa6cc4f5..79d195b48652 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -305,7 +305,7 @@ sub output_rest {
 		}
 
 		my $w = $what;
-		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+		$w =~ s/([\(\)\_\-\*\=\^\~\\\<\>])/\\$1/g;
 
 		if ($type ne "File") {
 			my $cur_part = $what;
-- 
2.30.2

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

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

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

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

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

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Wed, 24 Mar 2021 11:12:37 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > After merging the akpm-current tree, today's linux-next build (htmldocs)
> > produced this warning:
> >
> > 	Documentation/ABI/testing/sysfs-kernel-mm-cma:2: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> >
> > Introduced by commit 439d477342a3 ("mm: cma: support sysfs")
> >
> > As pointed by Jonathan, the problem is this text in
> > sysfs-kernel-mm-cma:
> >
> > 	Each CMA heap subdirectory (that is, each
> > 	/sys/kernel/mm/cma/<cma-heap-name> directory) contains the
> > 	following items:
> >
> > Is not parsed well, becase the major/minor signs need to be
> > escaped, when converted into cross-references.  
> 
> Sorry, I kind of dropped the ball on this, and everything else really; a
> bit of a challenging time here.
> 
> This makes the warning go away, but I have to wonder if it's the right
> fix 

There's indeed an issue on another part of the script. I'm testing 
a second version using a better and more generic regex set.

> - wouldn't it be better to avoid trying to create a cross-reference
> entirely in cases where it clearly won't work?  Or am I missing
> something here?

The cross-reference logic on this script is somewhat smart: it
will only create cross-references if the symbol exists. If not,
it keeps the symbol as-is.

The problem was actually on another part of the logic: there is
a symbol "/sys/kernel/mm/cma". The script is currently thinking
that the "<" character at:
	/sys/kernel/mm/cma/<cma-heap-name> 

is a bondary. So, it ended converting the first part 
("/sys/kernel/mm/cma/") into a cross reference.

This patch fixed it by dropping the reference for the non-existent 
symbol "/sys/kernel/mm/cma/" (the reference should be, instead,
to /sys/kernel/mm/cma/<cma-heap-name>/foo), but there's still
a hidden bug, which causes that a reference for
/sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_success to be
broken.

I have already a new patch. I'm checking right now if everything
is ok after the regex change. I should be sending a version 2
probably in a few.

Thanks,
Mauro