[PATCH] D147183: [RISCV][docs] Document which revision of the specification we implement

[Philip Reames via Phabricator via llvm-commits]

reames created this revision.
reames added reviewers: craig.topper, asb, kito-cheng, jrtc27.
Herald added subscribers: jobnoorman, luke, VincentWu, vkmr, frasercrmck, evandro, luismarques, apazos, sameer.abuasal, s.egerton, Jim, benna, psnobl, jocewei, PkmX, the_o, brucehoult, MartinMosbeck, rogfer01, edward-jones, zzheng, shiva0217, niosHD, sabuasal, bollu, simoncook, johnrusso, rbar, arichardson, mcrosier.
Herald added a project: All.
reames requested review of this revision.
Herald added subscribers: pcwang-thead, eopXD, MaskRay.
Herald added a project: LLVM.

This is intended to document the decision made in recent discussion, and ratified at the last risc-v sync up call two weeks ago.

The wording here turned out to be a bit tricky.  I ended up using the word "revision" as the specification internally defines several versioning schemes, and RVI assigns particular meaning to the words "specification version" that I really didn't want to get into.  If anyone has suggestions on how to improve this, please don't hesitate to chime in.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D147183

Files:
  llvm/docs/RISCVUsage.rst


Index: llvm/docs/RISCVUsage.rst
===================================================================
--- llvm/docs/RISCVUsage.rst
+++ llvm/docs/RISCVUsage.rst
@@ -12,6 +12,43 @@
 supported variations of the RISC-V specification.  It lives in the
 ``llvm/lib/Target/RISCV`` directory.
 
+Specification Documents
+=======================
+
+There have been a number of revisions to the RISC-V specifications.  LLVM
+implements the most recent non-draft specifications with pragmatic variances.
+The most recent specification can be found at:
+https://github.com/riscv/riscv-isa-manual/releases/.
+
+`The official RISC-V International specification page
+<https://riscv.org/technical/specifications/>`_. is also worth checking,
+but tends to significantly lag the non-draft specifications linked above.
+Make sure to check the `wiki for not yet integrated extensions
+<https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`_.
+
+The current known variances from the specification are:
+
+* Unconditionally allowing instructions from zifencei, zicsr, zicntr, and
+  zihpm without gating them on the extensions being enabled.  Previous
+  revisions of the specification included these instructions in the base
+  ISA, and we preserve this behavior to avoid breaking existing code.  If
+  a future revision of the specification reuses these opcodes for other
+  extensions, we may need to reevaluate this choice, and thus recommend
+  users migrate build systems so as not to rely on this.
+* Allowing CSRs to be named without gating on specific extensions.  This
+  applies to all CSR names, not just those in zicsr, zicntr, and zihpm.
+* Allowing extensions introduced in draft revisions of the specification
+  to be enabled before they reach a non-draft revision.  Most such
+  extensions will be experimental (see below), but non-experimental
+  extensions are also allowed provided that RISC-V International has
+  designated the individual extension as ratified.
+
+We are actively deciding not to support multiple specification revisions
+at this time. We acknowledge a likely future need, but actively defer the
+decisions making around handling this until we have a concrete example of
+real hardware having shipped and an incompatible change to the
+specification made afterwards.
+
 Base ISAs
 =========
 
@@ -218,11 +255,3 @@
 
 ``XVentanaCondOps``
   LLVM implements `version 1.0.0 of the VTx-family custom instructions specification <https://github.com/ventanamicro/ventana-custom-extensions/releases/download/v1.0.0/ventana-custom-extensions-v1.0.0.pdf>`_ by Ventana Micro Systems.  All instructions are prefixed with `vt.` as described in the specification, and the riscv-toolchain-convention document linked above.  These instructions are only available for riscv64 at this time.
-
-Specification Documents
-=======================
-For ratified specifications, please refer to the `official RISC-V International
-page <https://riscv.org/technical/specifications/>`_.  Make sure to check the
-`wiki for not yet integrated extensions
-<https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`_.
-


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D147183.509474.patch
Type: text/x-patch
Size: 3129 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20230329/2534470b/attachment.bin>