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
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?
Hi Minchan,
On Tue, 16 Mar 2021 11:18:11 -0700 Minchan Kim <[email protected]> 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
Stephen Rothwell <[email protected]> writes:
[Adding Mauro]
> On Tue, 16 Mar 2021 11:18:11 -0700 Minchan Kim <[email protected]> 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
Em Tue, 16 Mar 2021 17:09:20 -0600
Jonathan Corbet <[email protected]> escreveu:
> Stephen Rothwell <[email protected]> writes:
>
> [Adding Mauro]
>
> > On Tue, 16 Mar 2021 11:18:11 -0700 Minchan Kim <[email protected]> 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 <[email protected]>
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 <[email protected]>
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;
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 <[email protected]>
Reported-by: Jonathan Corbet <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
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
Mauro Carvalho Chehab <[email protected]> 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
Em Wed, 24 Mar 2021 11:12:37 -0600
Jonathan Corbet <[email protected]> escreveu:
> Mauro Carvalho Chehab <[email protected]> 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