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 * The ordering of ``z*``, ``s*``, and ``x*`` prefixed extension names is not
  44   enforced in user-specified ISA naming strings (e.g. ``-march``).
  45
  46 We are actively deciding not to support multiple specification revisions
  47 at this time. We acknowledge a likely future need, but actively defer the
  48 decisions making around handling this until we have a concrete example of
  49 real hardware having shipped and an incompatible change to the
  50 specification made afterwards.
  51
  52 Base ISAs
  53 =========
  54
  55 The specification defines five base instruction sets: RV32I, RV32E, RV64I,
  56 RV64E, and RV128I. Currently, LLVM fully supports RV32I, and RV64I.  RV32E and
  57 RV64E are supported by the assembly-based tools only.  RV128I is not supported.
  58
  59 To specify the target triple:
  60
  61   .. table:: RISC-V Architectures
  62
  63      ============ ==============================================================
  64      Architecture Description
  65      ============ ==============================================================
  66      ``riscv32``   RISC-V with XLEN=32 (i.e. RV32I or RV32E)
  67      ``riscv64``   RISC-V with XLEN=64 (i.e. RV64I or RV64E)
  68      ============ ==============================================================
  69
  70 To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
  71 architecture string (e.g. ``riscv32``) with the extension ``e``.
  72
  73 .. _riscv-extensions:
  74
  75 Extensions
  76 ==========
  77
  78 The following table provides a status summary for extensions which have been
  79 ratified and thus have finalized specifications.  When relevant, detailed notes
  80 on support follow.
  81
  82   .. table:: Ratified Extensions by Status
  83
  84      ===============  =========================================================
  85      Extension        Status
  86      ===============  =========================================================
  87      ``A``            Supported
  88      ``C``            Supported
  89      ``D``            Supported
  90      ``F``            Supported
  91      ``E``            Supported (`See note <#riscv-rve-note>`__)
  92      ``H``            Assembly Support
  93      ``M``            Supported
  94      ``Smaia``        Supported
  95      ``Smepmp``       Supported
  96      ``Ssaia``        Supported
  97      ``Svinval``      Assembly Support
  98      ``Svnapot``      Assembly Support
  99      ``Svpbmt``       Supported
 100      ``V``            Supported
 101      ``Za128rs``      Supported (`See note <#riscv-profiles-extensions-note>`__)
 102      ``Za64rs``       Supported (`See note <#riscv-profiles-extensions-note>`__)
 103      ``Zawrs``        Assembly Support
 104      ``Zba``          Supported
 105      ``Zbb``          Supported
 106      ``Zbc``          Supported
 107      ``Zbkb``         Supported (`See note <#riscv-scalar-crypto-note1>`__)
 108      ``Zbkc``         Supported
 109      ``Zbkx``         Supported (`See note <#riscv-scalar-crypto-note1>`__)
 110      ``Zbs``          Supported
 111      ``Zca``          Supported
 112      ``Zcb``          Supported
 113      ``Zcd``          Supported
 114      ``Zcf``          Supported
 115      ``Zcmp``         Supported
 116      ``Zcmt``         Assembly Support
 117      ``Zdinx``        Supported
 118      ``Zfa``          Supported
 119      ``Zfh``          Supported
 120      ``Zfhmin``       Supported
 121      ``Zfinx``        Supported
 122      ``Zhinx``        Supported
 123      ``Zhinxmin``     Supported
 124      ``Zic64b``       Supported (`See note <#riscv-profiles-extensions-note>`__)
 125      ``Zicbom``       Assembly Support
 126      ``Zicbop``       Supported
 127      ``Zicboz``       Assembly Support
 128      ``Ziccamoa``     Supported (`See note <#riscv-profiles-extensions-note>`__)
 129      ``Ziccif``       Supported (`See note <#riscv-profiles-extensions-note>`__)
 130      ``Zicclsm``      Supported (`See note <#riscv-profiles-extensions-note>`__)
 131      ``Ziccrse``      Supported (`See note <#riscv-profiles-extensions-note>`__)
 132      ``Zicntr``       (`See Note <#riscv-i2p1-note>`__)
 133      ``Zicsr``        (`See Note <#riscv-i2p1-note>`__)
 134      ``Zifencei``     (`See Note <#riscv-i2p1-note>`__)
 135      ``Zihintntl``    Supported
 136      ``Zihintpause``  Assembly Support
 137      ``Zihpm``        (`See Note <#riscv-i2p1-note>`__)
 138      ``Zkn``          Supported
 139      ``Zknd``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 140      ``Zkne``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 141      ``Zknh``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 142      ``Zksed``        Supported (`See note <#riscv-scalar-crypto-note2>`__)
 143      ``Zksh``         Supported (`See note <#riscv-scalar-crypto-note2>`__)
 144      ``Zk``           Supported
 145      ``Zkr``          Supported
 146      ``Zks``          Supported
 147      ``Zkt``          Supported
 148      ``Zmmul``        Supported
 149      ``Zvbb``         Assembly Support
 150      ``Zvbc``         Assembly Support
 151      ``Zve32x``       (`Partially <#riscv-vlen-32-note>`__) Supported
 152      ``Zve32f``       (`Partially <#riscv-vlen-32-note>`__) Supported
 153      ``Zve64x``       Supported
 154      ``Zve64f``       Supported
 155      ``Zve64d``       Supported
 156      ``Zvfh``         Supported
 157      ``Zvkb``         Assembly Support
 158      ``Zvkg``         Assembly Support
 159      ``Zvkn``         Assembly Support
 160      ``Zvknc``        Assembly Support
 161      ``Zvkned``       Assembly Support
 162      ``Zvkng``        Assembly Support
 163      ``Zvknha``       Assembly Support
 164      ``Zvknhb``       Assembly Support
 165      ``Zvks``         Assembly Support
 166      ``Zvksc``        Assembly Support
 167      ``Zvksed``       Assembly Support
 168      ``Zvksg``        Assembly Support
 169      ``Zvksh``        Assembly Support
 170      ``Zvkt``         Assembly Support
 171      ``Zvl32b``       (`Partially <#riscv-vlen-32-note>`__) Supported
 172      ``Zvl64b``       Supported
 173      ``Zvl128b``      Supported
 174      ``Zvl256b``      Supported
 175      ``Zvl512b``      Supported
 176      ``Zvl1024b``     Supported
 177      ``Zvl2048b``     Supported
 178      ``Zvl4096b``     Supported
 179      ``Zvl8192b``     Supported
 180      ``Zvl16384b``    Supported
 181      ``Zvl32768b``    Supported
 182      ``Zvl65536b``    Supported
 183      ===============  =========================================================
 184
 185 Assembly Support
 186   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.
 187
 188 Supported
 189   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.
 190
 191 .. _riscv-rve-note:
 192
 193 ``E``
 194   Support of RV32E/RV64E and ilp32e/lp64e ABIs are experimental. To be compatible with the implementation of ilp32e in GCC, we don't use aligned registers to pass variadic arguments. Furthermore, we set the stack alignment to 4 bytes for types with length of 2*XLEN.
 195
 196 .. _riscv-scalar-crypto-note1:
 197
 198 ``Zbkb``, ``Zbkx``
 199   Pattern matching support for these instructions is incomplete.
 200
 201 .. _riscv-scalar-crypto-note2:
 202
 203 ``Zknd``, ``Zkne``, ``Zknh``, ``Zksed``, ``Zksh``
 204   No pattern matching exists.  As a result, these instructions can only be used from assembler or via intrinsic calls.
 205
 206 .. _riscv-vlen-32-note:
 207
 208 ``Zve32x``, ``Zve32f``, ``Zvl32b``
 209   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.
 210
 211 .. _riscv-i2p1-note:
 212
 213 ``zicntr``, ``zicsr``, ``zifencei``, ``zihpm``
 214   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.
 215
 216 .. _riscv-profiles-extensions-note:
 217
 218 ``Za128rs``, ``Za64rs``, ``Zic64b``, ``Ziccamoa``, ``Ziccif``, ``Zicclsm``, ``Ziccrse``
 219   These extensions are defined as part of the `RISC-V Profiles specification <https://github.com/riscv/riscv-profiles/releases/tag/v1.0>`_.  They do not introduce any new features themselves, but instead describe existing hardware features.
 220
 221 Experimental Extensions
 222 =======================
 223
 224 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.
 225
 226 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.
 227
 228 ``experimental-zacas``
 229   LLVM implements the `1.0-rc1 draft specification <https://github.com/riscv/riscv-zacas/releases/tag/v1.0-rc1>`_.
 230
 231 ``experimental-zfbfmin``, ``experimental-zvfbfmin``, ``experimental-zvfbfwma``
 232   LLVM implements assembler support for the `1.0.0-rc2 specification <https://github.com/riscv/riscv-bfloat16/releases/tag/v59042fc71c31a9bcb2f1957621c960ed36fac401>`_.
 233
 234 ``experimental-zicfilp``, ``experimental-zicfiss``
 235   LLVM implements the `0.4 draft specification <https://github.com/riscv/riscv-cfi/releases/tag/v0.4.0>`__.
 236
 237 ``experimental-zicond``
 238   LLVM implements the `1.0-rc1 draft specification <https://github.com/riscv/riscv-zicond/releases/tag/v1.0-rc1>`__.
 239
 240 ``experimental-ztso``
 241   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.
 242
 243 ``experimental-zimop``
 244   LLVM implements the `v0.1 proposed specification <https://github.com/riscv/riscv-isa-manual/blob/main/src/zimop.adoc>`__.
 245
 246 ``experimental-zcmop``
 247   LLVM implements the `v0.2 proposed specification <https://github.com/riscv/riscv-isa-manual/blob/main/src/zimop.adoc>`__.
 248
 249 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`.
 250
 251 Vendor Extensions
 252 =================
 253
 254 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.
 255
 256 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>`_.
 257
 258 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.
 259
 260 The current vendor extensions supported are:
 261
 262 ``XTHeadBa``
 263   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.
 264
 265 ``XTHeadBb``
 266   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.
 267
 268 ``XTHeadBs``
 269   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.
 270
 271 ``XTHeadCondMov``
 272   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.
 273
 274 ``XTHeadCmo``
 275   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.
 276
 277 ``XTHeadFMemIdx``
 278   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.
 279
 280 ``XTheadMac``
 281   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.
 282
 283 ``XTHeadMemIdx``
 284   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.
 285
 286 ``XTHeadMemPair``
 287   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.
 288
 289 ``XTHeadSync``
 290   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.
 291
 292 ``XTHeadVdot``
 293   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.
 294
 295 ``XVentanaCondOps``
 296   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.
 297
 298 ``XSfvcp``
 299   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.
 300
 301 ``XCVbitmanip``
 302   LLVM implements `version 1.0.0 of the CORE-V Bit Manipulation custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/62bec66b36182215e18c9cf10f723567e23878e9/docs/source/instruction_set_extensions.rst>`_ by OpenHW Group.  All instructions are prefixed with `cv.` as described in the specification.
 303
 304 ``XCVelw``
 305   LLVM implements `version 1.0.0 of the CORE-V Event load custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/master/docs/source/instruction_set_extensions.rst>`_ by OpenHW Group.  All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
 306
 307 ``XCVmac``
 308   LLVM implements `version 1.0.0 of the CORE-V Multiply-Accumulate (MAC) custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/4f024fe4b15a68b76615b0630c07a6745c620da7/docs/source/instruction_set_extensions.rst>`_ by OpenHW Group.  All instructions are prefixed with `cv.mac` as described in the specification. These instructions are only available for riscv32 at this time.
 309
 310 ``XCVmem``
 311   LLVM implements `version 1.0.0 of the CORE-V Post-Increment load and stores custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/master/docs/source/instruction_set_extensions.rst>`_ by OpenHW Group.  All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
 312
 313 ``XCValu``
 314   LLVM implements `version 1.0.0 of the Core-V ALU custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/4f024fe4b15a68b76615b0630c07a6745c620da7/docs/source/instruction_set_extensions.rst>`_ by Core-V.  All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
 315
 316 ``XCVsimd``
 317   LLVM implements `version 1.0.0 of the CORE-V SIMD custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/cv32e40p_v1.3.2/docs/source/instruction_set_extensions.rst>`_ by OpenHW Group.  All instructions are prefixed with `cv.` as described in the specification.
 318
 319 ``XCVbi``
 320   LLVM implements `version 1.0.0 of the CORE-V immediate branching custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/cv32e40p_v1.3.2/docs/source/instruction_set_extensions.rst>`_ by OpenHW Group.  All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
 321
 322 Experimental C Intrinsics
 323 =========================
 324
 325 In some cases an extension is non-experimental but the C intrinsics for that
 326 extension are still experimental.  To use C intrinsics for such an extension
 327 from `clang`, you must add `-menable-experimental-extensions` to the command
 328 line.  This currently applies to the following extensions:
 329
 330 * ``Zvbb``
 331 * ``Zvbc``
 332 * ``Zvkb``
 333 * ``Zvkg``
 334 * ``Zvkn``
 335 * ``Zvknc``
 336 * ``Zvkned``
 337 * ``Zvkng``
 338 * ``Zvknha``
 339 * ``Zvknhb``
 340 * ``Zvks``
 341 * ``Zvksc``
 342 * ``Zvksed``
 343 * ``Zvksg``
 344 * ``Zvksh``
 345 * ``Zvkt``