From d7b2003761a2280e8d01af173355060aad464c67 Mon Sep 17 00:00:00 2001 From: Philip Reames Date: Mon, 3 Apr 2023 13:53:22 -0700 Subject: [PATCH] [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 --- llvm/docs/RISCVUsage.rst | 43 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/llvm/docs/RISCVUsage.rst b/llvm/docs/RISCVUsage.rst index 44a074f..c5ca207 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 +`_. is also worth checking, but +tends to significantly lag the specifications linked above. Make sure to check +the `wiki for not yet integrated 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 `_ 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 `_. Make sure to check the -`wiki for not yet integrated extensions -`_. - -- 2.7.4