* Re: [PATCH] arm64: Unify vertical spacing in HWCAPS
[not found] ` <YoieFI7hdJPJW5qy@debian.me>
@ 2022-05-21 9:22 ` Akira Yokosawa
2022-05-23 12:18 ` [PATCH v3] docs/arm64: elf_hwcaps: Unify HWCAP lists as description lists Martin Liška
0 siblings, 1 reply; 3+ messages in thread
From: Akira Yokosawa @ 2022-05-21 9:22 UTC (permalink / raw)
To: Bagas Sanjaya, Martin Liška
Cc: linux-doc, linux-kernel, corbet, Catalin Marinas, Will Deacon,
linux-arm-kernel
[+Cc: arm64 maintainers]
Hi Martin,
On 2022/05/21 17:08,
Bagas Sanjaya wrote:
> On Fri, May 20, 2022 at 04:01:33PM +0200, Martin Liška wrote:
>> Promote headings by removing intermediate blank lines.
>>
>> Signed-off-by: Martin Liska <mliska@suse.cz>
>> ---
>> Documentation/arm64/elf_hwcaps.rst | 23 -----------------------
>> 1 file changed, 23 deletions(-)
>>
>> diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst
>> index a8f30963e550..1e79044f51a2 100644
>> --- a/Documentation/arm64/elf_hwcaps.rst
>> +++ b/Documentation/arm64/elf_hwcaps.rst
>> @@ -171,96 +171,73 @@ HWCAP_PACG
>> Documentation/arm64/pointer-authentication.rst.
>>
>> HWCAP2_DCPODP
>> -
>> Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
>>
>> HWCAP2_SVE2
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
>>
>> HWCAP2_SVEAES
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
>>
>> HWCAP2_SVEPMULL
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
>>
>> HWCAP2_SVEBITPERM
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
>>
>> HWCAP2_SVESHA3
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
>>
>> HWCAP2_SVESM4
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
>>
>> HWCAP2_FLAGM2
>> -
>> Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
>>
>> HWCAP2_FRINT
>> -
>> Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
>>
>> HWCAP2_SVEI8MM
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001.
>>
>> HWCAP2_SVEF32MM
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001.
>>
>> HWCAP2_SVEF64MM
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001.
>>
>> HWCAP2_SVEBF16
>> -
>> Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001.
>>
>> HWCAP2_I8MM
>> -
>> Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001.
>>
>> HWCAP2_BF16
>> -
>> Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001.
>>
>> HWCAP2_DGH
>> -
>> Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001.
>>
>> HWCAP2_RNG
>> -
>> Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001.
>>
>> HWCAP2_BTI
>> -
>> Functionality implied by ID_AA64PFR0_EL1.BT == 0b0001.
>>
>> HWCAP2_MTE
>> -
>> Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described
>> by Documentation/arm64/memory-tagging-extension.rst.
>>
>> HWCAP2_ECV
>> -
>> Functionality implied by ID_AA64MMFR0_EL1.ECV == 0b0001.
>>
>> HWCAP2_AFP
>> -
>> Functionality implied by ID_AA64MFR1_EL1.AFP == 0b0001.
>>
>> HWCAP2_RPRES
>> -
>> Functionality implied by ID_AA64ISAR2_EL1.RPRES == 0b0001.
>>
>> HWCAP2_MTE3
>> -
>> Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0011, as described
>> by Documentation/arm64/memory-tagging-extension.rst.
>>
>> --
>> 2.36.1
>>
>
> Hi,
>
> Sorry for misunderstanding of this topic on my reply at [1].
>
> After applying this patch and doing htmldocs build, I see the HTML
> diff below.
Hey Bagas, please don't speak in HTML diffs.
Let's talk about ReST formatting.
So, the earlier part of the lists read:
----
HWCAP_FP
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
HWCAP_ASIMD
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
HWCAP_EVTSTRM
The generic timer is configured to generate events at a frequency of
approximately 10KHz.
[...]
-----
I see that what Martin wants is the consistency of the format of the lists.
I think the change is quite reasonable.
The list construct is called "Definition lists" in ReST. See:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists
This construct makes the defined terms be rendered in bolder
face. On the other hand, similar looking existing lists:
----
HWCAP2_DCPODP
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
HWCAP2_SVE2
Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
[...]
----
are not recognized as "Definition lists" and rendered differently.
Actually speaking, they are not in any list format.
So my suggestion of the title would be:
"docs/arm64: elf_hwcaps: Unify HWCAP lists as description lists"
[...]
> Also, when submitting next iterations of your patch series, don't forget
> to pass -v <number> to git-format-patch(1) so that the patch subject
> prefix contains the correct version numbers. I gave that advice because
> I don't see that this patch is sent as v2 of [2].
>
> CCing Akira to help reviewing.
>
> [1]: https://lore.kernel.org/linux-doc/4752814a-091c-9dd5-762c-6fd1a476c4bb@gmail.com/
> [2]: https://lore.kernel.org/linux-doc/b95b3128-f010-dcba-1f6a-1a85dd2d20a5@suse.cz/
>
Yeah, please post the next version as a v3.
Also, please note that this document belongs to the ARM64 PORT
(AARCH64 ARCHITECTURE) subsystem.
So please consult the entry in MAINTAINERS and prepare a
patch against its tree at:
T: git git://git.kernel.org/pub/scm/linux/kernel/git/arm64/linux.git
and CC to the maintainers and the list of the subsystem.
Thanks, Akira
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply [flat|nested] 3+ messages in thread