| Message ID | 20221130234125.2722364-4-conor@kernel.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Putting some basic order on isa extension lists | expand |
| Context | Check | Description |
|---|---|---|
| conchuod/patch_count | success | Link |
| conchuod/cover_letter | success | Series has a cover letter |
| conchuod/tree_selection | success | Guessed tree name to be for-next |
| conchuod/fixes_present | success | Fixes tag not required for -next series |
| conchuod/verify_signedoff | success | Signed-off-by tag matches author and committer |
| conchuod/kdoc | success | Errors and warnings before: 0 this patch: 0 |
| conchuod/module_param | success | Was 0 now: 0 |
| conchuod/build_rv32_defconfig | success | Build OK |
| conchuod/build_warn_rv64 | success | Errors and warnings before: 0 this patch: 0 |
| conchuod/dtb_warn_rv64 | success | Errors and warnings before: 0 this patch: 0 |
| conchuod/header_inline | success | No static functions without inline keyword in header files |
| conchuod/checkpatch | success | total: 0 errors, 0 warnings, 0 checks, 46 lines checked |
| conchuod/source_inline | success | Was 0 now: 0 |
| conchuod/build_rv64_nommu_k210_defconfig | success | Build OK |
| conchuod/verify_fixes | success | No Fixes tag |
| conchuod/build_rv64_nommu_virt_defconfig | success | Build OK |
On Wed, Nov 30, 2022 at 11:41:26PM +0000, Conor Dooley wrote: > From: Conor Dooley <conor.dooley@microchip.com> > > 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 <conor.dooley@microchip.com> > --- > 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.
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 <conor.dooley@microchip.com> > > 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 <conor.dooley@microchip.com> > --- > 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.
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
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 +