Index: llvm/docs/RISCVUsage.rst =================================================================== --- llvm/docs/RISCVUsage.rst +++ llvm/docs/RISCVUsage.rst @@ -12,6 +12,41 @@ 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 @@ ``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 -`_. -