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

[Alex Bradbury via Phabricator via llvm-commits]

asb added a comment.

I think this reflects what we (extensively) discussed and there was broad consensus for, so I'd be happy enough for it to land as-is rather than getting too bogged down over precise terminology. That said, I do think that going into the details of draft vs non-draft specifications and so on might be going into more detail than necessary, and could be confusing. It also seems like RISC-V is rather ignoring (and perhaps choosing to move away from?) the task of centralising all the extensions in a single ISA manual, so again it may make more sense to focus on ratified vs non-ratified as the thing that is easily understandable rather than trying to explain the way extension definitions are confusingly spread across different repositories.

I would suggest the following, which I think expresses what we need to. If you like it or some variant along these lines, fantastic. If not, I'd rather just land your version as-is (assuming there aren't other objections) so we can get the policy we agreed documented. Thanks for putting our conclusions into writing and convening the meeting to move this forwards.

  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.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D147183/new/

https://reviews.llvm.org/D147183