Em Tue, 26 Dec 2023 23:55:26 -0800
Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
> Hi,
>
> Can anyone explain this? maybe even suggest a fix for it?
>
> This has been around for a few weeks AFAIK. I haven't see a patch for it,
> but I could have missed it.
>
> (since 17e02586ed185 in August/2023; oh, that just fixed the move
> of files to the Documentation/arch/ subdir, so maybe even longer)
>
>
> In file Documentation/ABI/testing/sysfs-bus-papr-pmem:
>
> response to H_SCM_HEALTH hcall. The details of the bit
> flags returned in response to this hcall is available
> at 'Documentation/arch/powerpc/papr_hcalls.rst'. Below are
> the flags reported in this sysfs file:
>
> kernel-doc reports:
>
> linux-next-20231222/Documentation/ABI/testing/sysfs-bus-papr-pmem:2: WARNING: unknown document: '/powerpc/papr_hcalls'
>
> and the output file Documentation/output/admin-guide/abi-testing.html says:
>
> response to H_SCM_HEALTH hcall. The details of the bit
> flags returned in response to this hcall is available
> at '<span class="xref std std-doc">/powerpc/papr_hcalls</span>' . Below are
> the flags reported in this sysfs file:</p>
With sphinx-build version 6.2.1 and latest linux-next, I'm getting:
<snip>
<p>Defined on file <a class="reference internal" href="#abi-file-testing-sysfs-bus-papr-pmem"><span class="std std-ref">sysfs-bus-papr-pmem</span></a></p>
<p>(RO) Report flags indicating various states of a
papr-pmem NVDIMM device. Each flag maps to a one or
more bits set in the dimm-health-bitmap retrieved in
response to H_SCM_HEALTH hcall. The details of the bit
flags returned in response to this hcall is available
at '<a class="reference internal" href="../arch/powerpc/papr_hcalls.html"><span class="doc">Hypercall Op-codes (hcalls)</span></a>' .
</snip>
It seems that references are properly evaluated there.
> so the leading "Documentation/arch" is being removed from the filename
> AFAICT.
Actually, this is not related to automarkup.py, but, instead to
get_abi automation. You can see how this is processed by running
get_abi.pl script, e. g.:
<snip>
$ ./scripts/get_abi.pl search nmemX/papr/flags
/sys/bus/nd/devices/nmemX/papr/flags
------------------------------------
Kernel version: v5.8
Date: Apr, 2020
Contact: linuxppc-dev <linuxppc-dev@xxxxxxxxxxxxxxxx>, nvdimm@xxxxxxxxxxxxxxx,
Defined on file(s): Documentation/ABI/testing/sysfs-bus-papr-pmem
Description:
(RO) Report flags indicating various states of a
papr-pmem NVDIMM device. Each flag maps to a one or
more bits set in the dimm-health-bitmap retrieved in
response to H_SCM_HEALTH hcall. The details of the bit
flags returned in response to this hcall is available
at 'Documentation/arch/powerpc/papr_hcalls.rst' . Below are
the flags reported in this sysfs file:
* "not_armed"
Indicates that NVDIMM contents will not
survive a power cycle.
* "flush_fail"
Indicates that NVDIMM contents
couldn't be flushed during last
shut-down event.
* "restore_fail"
Indicates that NVDIMM contents
couldn't be restored during NVDIMM
initialization.
* "encrypted"
NVDIMM contents are encrypted.
* "smart_notify"
There is health event for the NVDIMM.
* "scrubbed"
Indicating that contents of the
NVDIMM have been scrubbed.
* "locked"
Indicating that NVDIMM contents can't
be modified until next power cycle.
</snip>
The output there is not in ReST format. There is a "rest" parameter
to generate the version actually used by Sphinx.
When "./scripts/get_abi.pl rest" is used, it converts any reference
of Documentation/xxx.rst into[1]:
:doc:`/xxx`
Which is actually a relative link, pointing to the file at:
<doc_source_dir>/xxx.rst
The references there are relative to the doc root directory passed
to sphinx-build (Documentation/). So, the above shall create a
cross-reference to Documentation/xxx.rst using the document title as the
name of the reference, so this will become:
<a class="reference internal" href="../arch/powerpc/papr_hcalls.html"><span class="doc">Hypercall Op-codes (hcalls)</span></a>
[1] see https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#the-doc-role
See how a similar link is converted to ReST format:
<snip>
$ ./scripts/get_abi.pl rest |grep -A20 /mte_tcf_preferred
Warning: file Documentation/ABI/testing/sysfs-platform-silicom#20:
What '/sys/devices/platform/silicom-platform/power_cycle' doesn't have a description
| **\/sys\/devices\/system\/cpu\/cpuX\/mte_tcf_preferred** |
+----------------------------------------------------------+
Defined on file :ref:`sysfs-devices-system-cpu <abi_file_testing_sysfs_devices_system_cpu>`
Preferred MTE tag checking mode
When a user program specifies more than one MTE tag checking
mode, this sysfs node is used to specify which mode should
be preferred when scheduling a task on that CPU. Possible
values:
================ ==============================================
"sync" Prefer synchronous mode
"asymm" Prefer asymmetric mode
"async" Prefer asynchronous mode
================ ==============================================
See also: :doc:`/arch/arm64/memory-tagging-extension`
<snip>
> I tried changing the quoted filename from single quotes to double back quotes
> `` and I tried it without any quotes, all with the same results.
With a quote like "`", the above would be evaluated to:
See also: `:doc:`/arch/arm64/memory-tagging-extension``
which will probably cause problems when sphinx parses it.
That's said, I remember that some old Sphinx versions had issues
with the doc: tag. On some legacy versions, the <doc_source_dir>
is set in a wrong way, ignoring the path used at the sphinx-build
directory parameter.
Thanks,
Mauro
