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>`_.
-