[llvm] d7b2003 - [RISCV][docs] Document which revision of the specification we implement

[Philip Reames via llvm-commits]

Author: Philip Reames
Date: 2023-04-03T13:54:32-07:00
New Revision: d7b2003761a2280e8d01af173355060aad464c67

URL: https://github.com/llvm/llvm-project/commit/d7b2003761a2280e8d01af173355060aad464c67
DIFF: https://github.com/llvm/llvm-project/commit/d7b2003761a2280e8d01af173355060aad464c67.diff

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

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.

Differential Revision: https://reviews.llvm.org/D147183

Added: 
    

Modified: 
    llvm/docs/RISCVUsage.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/RISCVUsage.rst b/llvm/docs/RISCVUsage.rst
index 44a074f405652..c5ca2076ad9d0 100644
--- a/llvm/docs/RISCVUsage.rst
+++ b/llvm/docs/RISCVUsage.rst
@@ -12,6 +12,41 @@ The RISC-V target provides code generation for processors implementing
 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 aims
+to implement the most recent ratified version of the standard RISC-V base ISAs
+and ISA extensions 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 specifications linked above. Make sure to check
+the `wiki for not yet integrated extensions
+<https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`_ and note
+that in addition, we sometimes carry support for extensions that have not yet
+been ratified (these will be marked as experimental - see below) and support
+various vendor-specific extensions (see below).
+
+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.
+
+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 +253,3 @@ The current vendor extensions supported are:
 
 ``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>`_.
-