From: Conor Dooley <[email protected]>
The RISC-V specs are permissive in what they allow as the ISA string,
but how we output this to userspace in /proc/cpuinfo is quasi uAPI.
Formalise this as part of the uAPI, by documenting the list of rules
we use at this point in time.
Signed-off-by: Conor Dooley <[email protected]>
---
I've not "tested" these docs. The NIPA-esque pwbot should go and
test it AFAICT. If it doesn't, I'll go add that.
---
Documentation/riscv/uabi.rst | 42 ++++++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)
diff --git a/Documentation/riscv/uabi.rst b/Documentation/riscv/uabi.rst
index 21a82cfb6c4d..bc3c8ced644b 100644
--- a/Documentation/riscv/uabi.rst
+++ b/Documentation/riscv/uabi.rst
@@ -3,4 +3,46 @@
RISC-V Linux User ABI
=====================
+Misaligned accesses
+-------------------
+
Misaligned accesses are supported in userspace, but they may perform poorly.
+
+ISA string ordering in /proc/cpuinfo
+------------------------------------
+
+The canonical order of ISA extension names in the ISA string is defined in
+chapter 27 of the unprivileged specification.
+The specification uses vague wording, such as should, when it comes to
+ordering, so for our purposes the following rules apply:
+
+#. Single-letter extensions come first, in "canonical order", so
+ "IMAFDQLCBKJTPVH".
+
+#. All multi-letter extensions will be separated from other multi-letter
+ extensions by an underscore.
+
+#. Additional standard extensions (starting with 'Z') will be sorted after
+ single-letter extensions and before any higher-privileged extensions.
+
+#. The first letter following the 'Z' conventionally indicates the most
+ closely related alphabetical extension category, IMAFDQLCBKJTPVH.
+ If multiple 'Z' extensions are named, they should be ordered first by
+ category, then alphabetically within a category.
+
+#. Standard supervisor-level extensions (starting with 'S') will be listed
+ after standard unprivileged extensions. If multiple
+ supervisor-level extensions are listed, they will be ordered
+ alphabetically.
+
+#. Standard machine-level extensions (starting with 'Zxm') will be listed
+ after any lower-privileged, standard extensions. If multiple
+ machine-level extensions are listed, they will be ordered
+ alphabetically.
+
+#. Non-standard extensions (starts with 'X') will be listed after all
+ standard extensions.
+
+An example string following the order is:
+ rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
+
--
2.38.1
On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote:
> From: Conor Dooley <[email protected]>
>
> The RISC-V specs are permissive in what they allow as the ISA string,
> but how we output this to userspace in /proc/cpuinfo is quasi uAPI.
>
> Formalise this as part of the uAPI, by documenting the list of rules
> we use at this point in time.
>
> Signed-off-by: Conor Dooley <[email protected]>
> ---
> I've not "tested" these docs. The NIPA-esque pwbot should go and
> test it AFAICT. If it doesn't, I'll go add that.
> ---
> Documentation/riscv/uabi.rst | 42 ++++++++++++++++++++++++++++++++++++
> 1 file changed, 42 insertions(+)
>
> diff --git a/Documentation/riscv/uabi.rst b/Documentation/riscv/uabi.rst
> index 21a82cfb6c4d..bc3c8ced644b 100644
> --- a/Documentation/riscv/uabi.rst
> +++ b/Documentation/riscv/uabi.rst
> @@ -3,4 +3,46 @@
> RISC-V Linux User ABI
> =====================
>
> +Misaligned accesses
> +-------------------
> +
> Misaligned accesses are supported in userspace, but they may perform poorly.
> +
> +ISA string ordering in /proc/cpuinfo
> +------------------------------------
> +
> +The canonical order of ISA extension names in the ISA string is defined in
> +chapter 27 of the unprivileged specification.
> +The specification uses vague wording, such as should, when it comes to
> +ordering, so for our purposes the following rules apply:
> +
> +#. Single-letter extensions come first, in "canonical order", so
> + "IMAFDQLCBKJTPVH".
> +
> +#. All multi-letter extensions will be separated from other multi-letter
> + extensions by an underscore.
> +
> +#. Additional standard extensions (starting with 'Z') will be sorted after
> + single-letter extensions and before any higher-privileged extensions.
> +
> +#. The first letter following the 'Z' conventionally indicates the most
> + closely related alphabetical extension category, IMAFDQLCBKJTPVH.
> + If multiple 'Z' extensions are named, they should be ordered first by
> + category, then alphabetically within a category.
> +
> +#. Standard supervisor-level extensions (starting with 'S') will be listed
> + after standard unprivileged extensions. If multiple
> + supervisor-level extensions are listed, they will be ordered
> + alphabetically.
> +
> +#. Standard machine-level extensions (starting with 'Zxm') will be listed
> + after any lower-privileged, standard extensions. If multiple
> + machine-level extensions are listed, they will be ordered
> + alphabetically.
> +
> +#. Non-standard extensions (starts with 'X') will be listed after all
Ehh, it's always the read *after* sending something that I notice the
inconsistency. This should be s/starts/starting/ for consistency.
> + standard extensions.
> +
> +An example string following the order is:
> + rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
> +
> --
> 2.38.1
>
On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote:
> +#. Single-letter extensions come first, in "canonical order", so
> + "IMAFDQLCBKJTPVH".
"..., that is ... ."
> +#. The first letter following the 'Z' conventionally indicates the most
> + closely related alphabetical extension category, IMAFDQLCBKJTPVH.
> + If multiple 'Z' extensions are named, they should be ordered first by
> + category, then alphabetically within a category.
> +
Did you mean "most closely related alphabetical extension category in
canonical order"?
> +An example string following the order is:
> + rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
> +
IMO literal code block should be better fit for the example above,
rather than definition list:
---- >8 ----
diff --git a/Documentation/riscv/uabi.rst b/Documentation/riscv/uabi.rst
index bc3c8ced644bcf..8005add855dc43 100644
--- a/Documentation/riscv/uabi.rst
+++ b/Documentation/riscv/uabi.rst
@@ -43,6 +43,7 @@ ordering, so for our purposes the following rules apply:
#. Non-standard extensions (starts with 'X') will be listed after all
standard extensions.
-An example string following the order is:
+An example string following the order is::
+
rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
Thanks.
--
An old man doll... just what I always wanted! - Clara
On Thu, Dec 01, 2022 at 10:05:32AM +0700, Bagas Sanjaya wrote:
> On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote:
> > +#. Single-letter extensions come first, in "canonical order", so
> > + "IMAFDQLCBKJTPVH".
>
> "..., that is ... ."
Hmm, that reads strangely to me. s/that/which/.
>
> > +#. The first letter following the 'Z' conventionally indicates the most
> > + closely related alphabetical extension category, IMAFDQLCBKJTPVH.
> > + If multiple 'Z' extensions are named, they should be ordered first by
> > + category, then alphabetically within a category.
> > +
>
> Did you mean "most closely related alphabetical extension category in
> canonical order"?
I am not 100% sure what you are suggesting a replacement of here. I
think I may reword this as:
For additional standard extensions, the first letter following the 'Z'
conventionally indicates the most closely related alphabetical
extension category. If multiple 'Z' extensions are named, they will
be ordered first by category, in canonical order as listed above, then
alphabetically within a category.
> > +An example string following the order is:
> > + rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
> > +
>
> IMO literal code block should be better fit for the example above,
> rather than definition list:
Uh, sure? I'm not sure what impact that has on the output, but I can
switch to a pre-formatted block.
Thanks,
Conor.
On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote:
> From: Conor Dooley <[email protected]>
>
> The RISC-V specs are permissive in what they allow as the ISA string,
> but how we output this to userspace in /proc/cpuinfo is quasi uAPI.
uABI
>
> Formalise this as part of the uAPI, by documenting the list of rules
uABI
> we use at this point in time.
>
> Signed-off-by: Conor Dooley <[email protected]>
> ---
> I've not "tested" these docs. The NIPA-esque pwbot should go and
> test it AFAICT. If it doesn't, I'll go add that.
> ---
> Documentation/riscv/uabi.rst | 42 ++++++++++++++++++++++++++++++++++++
> 1 file changed, 42 insertions(+)
>
> diff --git a/Documentation/riscv/uabi.rst b/Documentation/riscv/uabi.rst
> index 21a82cfb6c4d..bc3c8ced644b 100644
> --- a/Documentation/riscv/uabi.rst
> +++ b/Documentation/riscv/uabi.rst
> @@ -3,4 +3,46 @@
> RISC-V Linux User ABI
> =====================
>
> +Misaligned accesses
> +-------------------
> +
> Misaligned accesses are supported in userspace, but they may perform poorly.
> +
> +ISA string ordering in /proc/cpuinfo
> +------------------------------------
> +
> +The canonical order of ISA extension names in the ISA string is defined in
> +chapter 27 of the unprivileged specification.
> +The specification uses vague wording, such as should, when it comes to
> +ordering, so for our purposes the following rules apply:
> +
> +#. Single-letter extensions come first, in "canonical order", so
> + "IMAFDQLCBKJTPVH".
> +
> +#. All multi-letter extensions will be separated from other multi-letter
> + extensions by an underscore.
> +
> +#. Additional standard extensions (starting with 'Z') will be sorted after
> + single-letter extensions and before any higher-privileged extensions.
> +
> +#. The first letter following the 'Z' conventionally indicates the most
> + closely related alphabetical extension category, IMAFDQLCBKJTPVH.
> + If multiple 'Z' extensions are named, they should be ordered first by
> + category, then alphabetically within a category.
> +
> +#. Standard supervisor-level extensions (starting with 'S') will be listed
> + after standard unprivileged extensions. If multiple
nit: Seems like a short line, at what character are we required to wrap at
in this file?
> + supervisor-level extensions are listed, they will be ordered
> + alphabetically.
> +
> +#. Standard machine-level extensions (starting with 'Zxm') will be listed
> + after any lower-privileged, standard extensions. If multiple
> + machine-level extensions are listed, they will be ordered
> + alphabetically.
> +
> +#. Non-standard extensions (starts with 'X') will be listed after all
> + standard extensions.
> +
> +An example string following the order is:
> + rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
> +
> --
> 2.38.1
>
If this uABI hasn't "shipped" yet, giving us the freedom to discuss it
more, then I'd prefer we don't publish this (which looks like "shipping"
it) until we're 100% sure that this is the uABI we want.
(I feel like if we can still change the order in proc, as the previous
patch did, then we haven't yet shipped it.)
Thanks,
drew
On 12/1/22 15:17, Conor Dooley wrote:
> On Thu, Dec 01, 2022 at 10:05:32AM +0700, Bagas Sanjaya wrote:
>> On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote:
>>> +#. Single-letter extensions come first, in "canonical order", so
>>> + "IMAFDQLCBKJTPVH".
>>
>> "..., that is ... ."
>
> Hmm, that reads strangely to me. s/that/which/.
>
OK.
>>
>>> +#. The first letter following the 'Z' conventionally indicates the most
>>> + closely related alphabetical extension category, IMAFDQLCBKJTPVH.
>>> + If multiple 'Z' extensions are named, they should be ordered first by
>>> + category, then alphabetically within a category.
>>> +
>>
>> Did you mean "most closely related alphabetical extension category in
>> canonical order"?
>
> I am not 100% sure what you are suggesting a replacement of here. I
> think I may reword this as:
> For additional standard extensions, the first letter following the 'Z'
> conventionally indicates the most closely related alphabetical
> extension category. If multiple 'Z' extensions are named, they will
> be ordered first by category, in canonical order as listed above, then
> alphabetically within a category.
>
That LGTM.
>>> +An example string following the order is:
>>> + rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
>>> +
>>
>> IMO literal code block should be better fit for the example above,
>> rather than definition list:
>
> Uh, sure? I'm not sure what impact that has on the output, but I can
> switch to a pre-formatted block.
>
Something like ``foo``?
Thanks.
--
An old man doll... just what I always wanted! - Clara
On Fri, Dec 02, 2022 at 09:14:08AM +0700, Bagas Sanjaya wrote:
> On 12/1/22 15:17, Conor Dooley wrote:
> > On Thu, Dec 01, 2022 at 10:05:32AM +0700, Bagas Sanjaya wrote:
> >> On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote:
> >>> +#. Single-letter extensions come first, in "canonical order", so
> >>> + "IMAFDQLCBKJTPVH".
> >>
> >> "..., that is ... ."
> >
> > Hmm, that reads strangely to me. s/that/which/.
> >
>
> OK.
>
> >>
> >>> +#. The first letter following the 'Z' conventionally indicates the most
> >>> + closely related alphabetical extension category, IMAFDQLCBKJTPVH.
> >>> + If multiple 'Z' extensions are named, they should be ordered first by
> >>> + category, then alphabetically within a category.
> >>> +
> >>
> >> Did you mean "most closely related alphabetical extension category in
> >> canonical order"?
> >
> > I am not 100% sure what you are suggesting a replacement of here. I
> > think I may reword this as:
> > For additional standard extensions, the first letter following the 'Z'
> > conventionally indicates the most closely related alphabetical
> > extension category. If multiple 'Z' extensions are named, they will
> > be ordered first by category, in canonical order as listed above, then
> > alphabetically within a category.
> >
>
> That LGTM.
>
> >>> +An example string following the order is:
> >>> + rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
> >>> +
> >>
> >> IMO literal code block should be better fit for the example above,
> >> rather than definition list:
> >
> > Uh, sure? I'm not sure what impact that has on the output, but I can
> > switch to a pre-formatted block.
> >
>
> Something like ``foo``?
Not posting a v2 for another few days, but this is what I currently
have:
https://git.kernel.org/pub/scm/linux/kernel/git/conor/linux.git/tree/Documentation/riscv/uabi.rst?h=riscv-uabi_docs