llvm/docs/RISCVUsage.rst

   1 =============================
   2 User Guide for RISC-V Target
   3 =============================
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 The RISC-V target provides code generation for processors implementing
  12 supported variations of the RISC-V specification.  It lives in the
  13 ``llvm/lib/Target/RISCV`` directory.
  14
  15 Specification Documents
  16 =======================
  17
  18 There have been a number of revisions to the RISC-V specifications. LLVM aims
  19 to implement the most recent ratified version of the standard RISC-V base ISAs
  20 and ISA extensions with pragmatic variances. The most recent specification can
  21 be found at: https://github.com/riscv/riscv-isa-manual/releases/.
  22
  23 `The official RISC-V International specification page
  24 <https://riscv.org/technical/specifications/>`_. is also worth checking, but
  25 tends to significantly lag the specifications linked above. Make sure to check
  26 the `wiki for not yet integrated extensions
  27 <https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`_ and note
  28 that in addition, we sometimes carry support for extensions that have not yet
  29 been ratified (these will be marked as experimental - see below) and support
  30 various vendor-specific extensions (see below).
  31
  32 The current known variances from the specification are:
  33
  34 * Unconditionally allowing instructions from zifencei, zicsr, zicntr, and
  35   zihpm without gating them on the extensions being enabled.  Previous
  36   revisions of the specification included these instructions in the base
  37   ISA, and we preserve this behavior to avoid breaking existing code.  If
  38   a future revision of the specification reuses these opcodes for other
  39   extensions, we may need to reevaluate this choice, and thus recommend
  40   users migrate build systems so as not to rely on this.
  41 * Allowing CSRs to be named without gating on specific extensions.  This
  42   applies to all CSR names, not just those in zicsr, zicntr, and zihpm.
  43
  44 We are actively deciding not to support multiple specification revisions
  45 at this time. We acknowledge a likely future need, but actively defer the
  46 decisions making around handling this until we have a concrete example of
  47 real hardware having shipped and an incompatible change to the
  48 specification made afterwards.
  49
  50 Base ISAs
  51 =========
  52
  53 The specification defines five base instruction sets: RV32I, RV32E, RV64I,
  54 RV64E, and RV128I. Currently, LLVM fully supports RV32I, and RV64I.  RV32E and
  55 RV64E are supported by the assembly-based tools only.  RV128I is not supported.
  56
  57 To specify the target triple:
  58
  59   .. table:: RISC-V Architectures
  60
  61      ============ ==============================================================
  62      Architecture Description
  63      ============ ==============================================================
  64      ``riscv32``   RISC-V with XLEN=32 (i.e. RV32I or RV32E)
  65      ``riscv64``   RISC-V with XLEN=64 (i.e. RV64I or RV64E)
  66      ============ ==============================================================
  67
  68 To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
  69 architecture string (e.g. ``riscv32``) with the extension ``e``.
  70
  71 .. _riscv-extensions:
  72
  73 Extensions
  74 ==========
  75
  76 The following table provides a status summary for extensions which have been
  77 ratified and thus have finalized specifications.  When relevant, detailed notes
  78 on support follow.
  79
  80   .. table:: Ratified Extensions by Status
  81
  82      ===============  =========================================================
  83      Extension        Status
  84      ===============  =========================================================
  85      ``A``            Supported
  86      ``C``            Supported
  87      ``D``            Supported
  88      ``F``            Supported
  89      ``H``            Assembly Support
  90      ``M``            Supported
  91      ``Svinval``      Assembly Support
  92      ``Svnapot``      Assembly Support
  93      ``Svpbmt``       Supported
  94      ``V``            Supported
  95      ``Zawrs``        Assembly Support
  96      ``Zba``          Supported
  97      ``Zbb``          Supported
  98      ``Zbc``          Supported
  99      ``Zbkb``         Supported (`See note <#riscv-scalar-crypto-note1>`__)
 100      ``Zbkc``         Supported
 101      ``Zbkx``         Supported (`See note <#riscv-scalar-crypto-note1>`__)
 102      ``Zbs``          Supported
 103      ``Zdinx``        Assembly Support for RV32. Full support for RV64.
 104      ``Zfh``          Supported
 105      ``Zfhmin``       Supported
 106      ``Zfinx``        Supported
 107      ``Zhinx``        Supported
 108      ``Zhinxmin``     Supported
 109      ``Zicbom``       Assembly Support
 110      ``Zicbop``       Assembly Support
 111      ``Zicboz``       Assembly Support
 112      ``Zicntr``       (`See Note <#riscv-i2p1-note>`__)
 113      ``Zicsr``        (`See Note <#riscv-i2p1-note>`__)
 114      ``Zifencei``     (`See Note <#riscv-i2p1-note>`__)
 115      ``Zihintpause``  Assembly Support
 116      ``Zihpm``        (`See Note <#riscv-i2p1-note>`__)
 117      ``Zkn``          Supported
 118      ``Zknd``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 119      ``Zkne``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 120      ``Zknh``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 121      ``Zksed``        Supported (`See note <#riscv-scalar-crypto-note2>`__)
 122      ``Zksh``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 123      ``Zk``           Supported
 124      ``Zkr``          Supported
 125      ``Zks``          Supported
 126      ``Zkt``          Supported
 127      ``Zmmul``        Supported
 128      ``Zve32x``       (`Partially <#riscv-vlen-32-note>`__) Supported
 129      ``Zve32f``       (`Partially <#riscv-vlen-32-note>`__) Supported
 130      ``Zve64x``       Supported
 131      ``Zve64f``       Supported
 132      ``Zve64d``       Supported
 133      ``Zvl32b``       (`Partially <#riscv-vlen-32-note>`__) Supported
 134      ``Zvl64b``       Supported
 135      ``Zvl128b``      Supported
 136      ``Zvl256b``      Supported
 137      ``Zvl512b``      Supported
 138      ``Zvl1024b``     Supported
 139      ``Zvl2048b``     Supported
 140      ``Zvl4096b``     Supported
 141      ``Zvl8192b``     Supported
 142      ``Zvl16384b``    Supported
 143      ``Zvl32768b``    Supported
 144      ``Zvl65536b``    Supported
 145      ===============  =========================================================
 146
 147 Assembly Support
 148   LLVM supports the associated instructions in assembly.  All assembly related tools (e.g. assembler, disassembler, llvm-objdump, etc..) are supported.  Compiler and linker will accept extension names, and linked binaries will contain appropriate ELF flags and attributes to reflect use of named extension.
 149
 150 Supported
 151   Fully supported by the compiler.  This includes everything in Assembly Support, along with - if relevant - C language intrinsics for the instructions and pattern matching by the compiler to recognize idiomatic patterns which can be lowered to the associated instructions.
 152
 153 .. _riscv-scalar-crypto-note1:
 154
 155 ``Zbkb``, ``Zbkx``
 156   Pattern matching support for these instructions is incomplete.
 157
 158 .. _riscv-scalar-crypto-note2:
 159
 160 ``Zknd``, ``Zkne``, ``Zknh``, ``Zksed``, ``Zksh``
 161   No pattern matching exists.  As a result, these instructions can only be used from assembler or via intrinsic calls.
 162
 163 .. _riscv-vlen-32-note:
 164
 165 ``Zve32x``, ``Zve32f``, ``Zvl32b``
 166   LLVM currently assumes a minimum VLEN (vector register width) of 64 bits during compilation, and as a result ``Zve32x`` and ``Zve32f`` are supported only for VLEN>=64.  Assembly support doesn't have this restriction.
 167
 168 .. _riscv-i2p1-note:
 169
 170 ``zicntr``, ``zicsr``, ``zifencei``, ``zihpm``
 171   Between versions 2.0 and 2.1 of the base I specification, a backwards incompatible change was made to remove selected instructions and CSRs from the base ISA.  These instructions were grouped into a set of new extensions, but were no longer required by the base ISA.  This change is partially described in "Preface to Document Version 20190608-Base-Ratified" from the specification document (the ``zicntr`` and ``zihpm`` bits are not mentioned).  LLVM currently implements version 2.1 of the base specification. To maintain compatibility, instructions from these extensions are accepted without being in the ``-march`` string.  LLVM also allows the explicit specification of the extensions in an ``-march`` string.
 172
 173 Experimental Extensions
 174 =======================
 175
 176 LLVM supports (to various degrees) a number of experimental extensions.  All experimental extensions have ``experimental-`` as a prefix.  There is explicitly no compatibility promised between versions of the toolchain, and regular users are strongly advised *not* to make use of experimental extensions before they reach ratification.
 177
 178 The primary goal of experimental support is to assist in the process of ratification by providing an existence proof of an implementation, and simplifying efforts to validate the value of a proposed extension against large code bases.  Experimental extensions are expected to either transition to ratified status, or be eventually removed.  The decision on whether to accept an experimental extension is currently done on an entirely case by case basis; if you want to propose one, attending the bi-weekly RISC-V sync-up call is strongly advised.
 179
 180 ``experimental-smaia``
 181   LLVM implements the `Ratification candidate 3 <https://github.com/riscv/riscv-aia/releases/tag/1.0-RC3>`_.
 182
 183 ``experimental-ssaia``
 184   LLVM implements the `Ratification candidate 3 <https://github.com/riscv/riscv-aia/releases/tag/1.0-RC3>`_.
 185
 186 ``experimental-zca``
 187   LLVM implements the `1.0.1 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/v1.0.1>`__.
 188
 189 ``experimental-zcb``
 190   LLVM implements the `1.0.1 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/v1.0.1>`__.
 191
 192 ``experimental-zcd``
 193   LLVM implements the `1.0.1 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/v1.0.1>`__.
 194
 195 ``experimental-zcf``
 196   LLVM implements the `1.0.1 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/v1.0.1>`__.
 197
 198 ``experimental-zcmp``
 199   LLVM implements the `1.0.1 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/v1.0.1>`__.
 200
 201 ``experimental-zcmt``
 202   LLVM implements the `1.0.1 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/v1.0.1>`_.
 203
 204 ``experimental-zfa``
 205   LLVM implements the `0.2 draft specification <https://github.com/riscv/riscv-isa-manual/releases/download/draft-20230131-c0b298a/zfa-20230414.pdf>`__.
 206
 207 ``experimental-zicond``
 208   LLVM implements the `1.0-rc1 draft specification <https://github.com/riscv/riscv-zicond/releases/tag/v1.0-rc1>`__.
 209
 210 ``experimental-zihintntl``
 211   LLVM implements the `0.2 draft specification <https://github.com/riscv/riscv-isa-manual/releases/tag/draft-20220831-bf5a151>`__.
 212
 213 ``experimental-ztso``
 214   LLVM implements the `v0.1 proposed specification <https://github.com/riscv/riscv-isa-manual/releases/download/draft-20220723-10eea63/riscv-spec.pdf>`__ (see Chapter 25).  The mapping from the C/C++ memory model to Ztso has not yet been ratified in any standards document.  There are multiple possible mappings, and they are *not* mutually ABI compatible.  The mapping LLVM implements is ABI compatible with the default WMO mapping.  This mapping may change and there is *explicitly* no ABI stability offered while the extension remains in experimental status.  User beware.
 215
 216 ``experimental-zvfh``
 217   LLVM implements `this draft text <https://github.com/riscv/riscv-v-spec/pull/780>`__.
 218
 219 ``experimental-zvbb``, ``experimental-zvbc``, ``experimental-zvkg``, ``experimental-zvkn``, ``experimental-zvkng``, ``experimental-zvknha``, ``experimental-zvknhb``, ``experimental-zvkns``, ``experimental-zvks``, ``experimental-zvksed``, ``experimental-zvksg``, ``experimental-zvksh``, ``experimental-zvkt``
 220   LLVM implements the `0.5 draft specification <https://github.com/riscv/riscv-crypto/releases/download/v20230407/riscv-crypto-spec-vector.pdf>`__. Note that current vector crypto extension version can be found in: <https://github.com/riscv/riscv-crypto>.
 221
 222 To use an experimental extension from `clang`, you must add `-menable-experimental-extensions` to the command line, and specify the exact version of the experimental extension you are using.  To use an experimental extension with LLVM's internal developer tools (e.g. `llc`, `llvm-objdump`, `llvm-mc`), you must prefix the extension name with `experimental-`.  Note that you don't need to specify the version with internal tools, and shouldn't include the `experimental-` prefix with `clang`.
 223
 224 Vendor Extensions
 225 =================
 226
 227 Vendor extensions are extensions which are not standardized by RISC-V International, and are instead defined by a hardware vendor.  The term vendor extension roughly parallels the definition of a `non-standard` extension from Section 1.3 of the Volume I: RISC-V Unprivileged ISA specification.  In particular, we expect to eventually accept both `custom` extensions and `non-conforming` extensions.
 228
 229 Inclusion of a vendor extension will be considered on a case by case basis.  All proposals should be brought to the bi-weekly RISCV sync calls for discussion.  For a general idea of the factors likely to be considered, please see the `Clang documentation <https://clang.llvm.org/get_involved.html>`_.
 230
 231 It is our intention to follow the naming conventions described in `riscv-non-isa/riscv-toolchain-conventions <https://github.com/riscv-non-isa/riscv-toolchain-conventions#conventions-for-vendor-extensions>`_.  Exceptions to this naming will need to be strongly motivated.
 232
 233 The current vendor extensions supported are:
 234
 235 ``XTHeadBa``
 236   LLVM implements `the THeadBa (address-generation) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 237
 238 ``XTHeadBb``
 239   LLVM implements `the THeadBb (basic bit-manipulation) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 240
 241 ``XTHeadBs``
 242   LLVM implements `the THeadBs (single-bit operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 243
 244 ``XTHeadCondMov``
 245   LLVM implements `the THeadCondMov (conditional move) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 246
 247 ``XTHeadCmo``
 248   LLVM implements `the THeadCmo (cache management operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 249
 250 ``XTHeadFMemIdx``
 251   LLVM implements `the THeadFMemIdx (indexed memory operations for floating point) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 252
 253 ``XTheadMac``
 254   LLVM implements `the XTheadMac (multiply-accumulate instructions) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 255
 256 ``XTHeadMemIdx``
 257   LLVM implements `the THeadMemIdx (indexed memory operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 258
 259 ``XTHeadMemPair``
 260   LLVM implements `the THeadMemPair (two-GPR memory operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 261
 262 ``XTHeadSync``
 263   LLVM implements `the THeadSync (multi-core synchronization instructions) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`_  by T-HEAD of Alibaba.  Instructions are prefixed with `th.` as described in the specification.
 264
 265 ``XTHeadVdot``
 266   LLVM implements `version 1.0.0 of the THeadV-family custom instructions specification <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.0/xthead-2022-12-04-2.2.0.pdf>`_ by T-HEAD of Alibaba.  All instructions are prefixed with `th.` as described in the specification, and the riscv-toolchain-convention document linked above.
 267
 268 ``XVentanaCondOps``
 269   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.
 270
 271 ``XSfvcp``
 272   LLVM implements `version 1.0.0 of the SiFive Vector Coprocessor Interface (VCIX) Software Specification <https://sifive.cdn.prismic.io/sifive/c3829e36-8552-41f0-a841-79945784241b_vcix-spec-software.pdf>`_ by SiFive.  All instructions are prefixed with `sf.vc.` as described in the specification, and the riscv-toolchain-convention document linked above.