[v1,3/3] Documentation: riscv: add a section about ISA string ordering in /proc/cpuinfo
Message ID | 20221130234125.2722364-4-conor@kernel.org |
---|---|
State | New |
Headers |
Return-Path: <linux-kernel-owner@vger.kernel.org> Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp1216102wrr; Wed, 30 Nov 2022 16:01:27 -0800 (PST) X-Google-Smtp-Source: AA0mqf5ymWvmvR3dL4zr2k3Fwuh3okHpgf+zddXDuqjQMH1J6T8Ac8nF5Z+UiPaaoL0+inbYhJwf X-Received: by 2002:a05:6a00:1ad2:b0:56c:235:83a9 with SMTP id f18-20020a056a001ad200b0056c023583a9mr65439369pfv.6.1669852887167; Wed, 30 Nov 2022 16:01:27 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1669852887; cv=none; d=google.com; s=arc-20160816; b=Gmh32rMaEwOpf/RpYHe7o4MRlm+I7MxJxSCIpuq6caXxx3tMLn8VX26ppoj/dfEQ9M +EECAd5ch5V4HszI893PiH7QigFZJGlnVHzWvaBWIQ2xIoo7GR4eVavTmp3b3GV2V5Q7 ACbptPUHCula87iJwnpGpMsBrzM+1FKVdwBDnFE1NWq3ENL/xcFxbcbCsgXtFEut3K0L 6HAuiTgb4mZrKuHbQ5cy3IDcdP/LeaA4fwuiqKqMl5bUrAQLWaWCaGyAGqiCnHMga4tl hEB+QzDj88yYKIrNnWMfoNg4bN310EQoisQyNbLeR0J5ToW+4IF+IsXXkgeJTY0uk3ST 1u/g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=wBOKhhZ3+7TczGkTaEbfYCF88ju7MTsFi13ar22Txwk=; b=f3YvvaD+H/iywIK7MLyV23dFwjxGjM12P75d7/ZwGThq0KfiQrDdF5usgShNWUGNHh /vvdrS5QNzFcQRmAaxOWMZgN0o2vAETD0y6kvqDBynvxbnTqEzKVJgOKrjOEKdHVGuHM hrh2LwVChm3lQq7Nu3BaIrC0x4dcGQ1ZFDVdVqgVtC/SLByP/3rp2nvVa8miGR1tRHhw eGz7gQLisWJb75F/Xei5MBucT6SMsmPv36xrhIzg0FJQwo9buWwYAPGPiDdRoJN/kGx6 CeUN+gR+I5emI2rbMV6LqL+VOOT+8vkfzWGHA/jOdtqqdw5Nd+lChOt1sTPjr75i/fy9 S0rg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b="EnIw4/Ir"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id n11-20020a654ccb000000b00476a48051edsi2550739pgt.476.2022.11.30.16.01.13; Wed, 30 Nov 2022 16:01:27 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b="EnIw4/Ir"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229957AbiK3XmU (ORCPT <rfc822;heyuhang3455@gmail.com> + 99 others); Wed, 30 Nov 2022 18:42:20 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60950 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229900AbiK3XmH (ORCPT <rfc822;linux-kernel@vger.kernel.org>); Wed, 30 Nov 2022 18:42:07 -0500 Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5B01F4B9B9; Wed, 30 Nov 2022 15:42:06 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id E93F061E5F; Wed, 30 Nov 2022 23:42:05 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id B89BFC4347C; Wed, 30 Nov 2022 23:42:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1669851725; bh=Z7aEnVV+jWqoN52K1e+YmgnpAmHL+qz1PmK3NhAzRxQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EnIw4/IrxANCSz/9VMiRA2KIF6h3JhMAHa/K90/tVJu+PWuZwyGcVwk6Y/zm+B+jL SlBUCNPTLbcVhrHzZob+j5KwC/UXl07hBKXLBafS0wmQjHhK9Fw9J/vp4+JR7Y94uS TBP2keeu8Tg48fv4xCCzWzvNHS7gGuGlALoUG+FhDzeU/snOwUnk+ZLnOvmNTK/YGA lnuxunckxgcjRYxr0IB9pBW+hzIHmoPtb27IEAy2PWT44dlttLMlsVwte40Y/vhbPA sVQJHXRlDzCKMWkh3ALONUhRQT9ISq2l2EOKGhVynuXRuW2SWJGFVPd6riRsdahpDe SiRZLV22KB8Hw== From: Conor Dooley <conor@kernel.org> To: Palmer Dabbelt <palmer@dabbelt.com>, linux-riscv@lists.infradead.org Cc: Conor Dooley <conor.dooley@microchip.com>, ajones@ventanamicro.com, aou@eecs.berkeley.edu, conor@kernel.org, corbet@lwn.net, guoren@kernel.org, heiko@sntech.de, paul.walmsley@sifive.com, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH v1 3/3] Documentation: riscv: add a section about ISA string ordering in /proc/cpuinfo Date: Wed, 30 Nov 2022 23:41:26 +0000 Message-Id: <20221130234125.2722364-4-conor@kernel.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221130234125.2722364-1-conor@kernel.org> References: <20221130234125.2722364-1-conor@kernel.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-7.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_HI, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: <linux-kernel.vger.kernel.org> X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750967661089101318?= X-GMAIL-MSGID: =?utf-8?q?1750967661089101318?= |
Series |
Putting some basic order on isa extension lists
|
|
Commit Message
Conor Dooley
Nov. 30, 2022, 11:41 p.m. UTC
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(+)
Comments
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 +