1============================= 2User Guide for RISC-V Target 3============================= 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11The RISC-V target provides code generation for processors implementing 12supported variations of the RISC-V specification. It lives in the 13``llvm/lib/Target/RISCV`` directory. 14 15Specification Documents 16======================= 17 18There have been a number of revisions to the RISC-V specifications. LLVM aims 19to implement the most recent ratified version of the standard RISC-V base ISAs 20and ISA extensions with pragmatic variances. The most recent specification can 21be 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 25tends to significantly lag the specifications linked above. Make sure to check 26the `wiki for not yet integrated extensions 27<https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`__ and note 28that in addition, we sometimes carry support for extensions that have not yet 29been ratified (these will be marked as experimental - see below) and support 30various vendor-specific extensions (see below). 31 32The 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 46We are actively deciding not to support multiple specification revisions 47at this time. We acknowledge a likely future need, but actively defer the 48decisions making around handling this until we have a concrete example of 49real hardware having shipped and an incompatible change to the 50specification made afterwards. 51 52Base ISAs 53========= 54 55The specification defines five base instruction sets: RV32I, RV32E, RV64I, 56RV64E, and RV128I. Currently, LLVM fully supports RV32I, and RV64I. RV32E and 57RV64E are supported by the assembly-based tools only. RV128I is not supported. 58 59To 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 70To select an E variant ISA (e.g. RV32E instead of RV32I), use the base 71architecture string (e.g. ``riscv32``) with the extension ``e``. 72 73Profiles 74======== 75 76Supported profile names can be passed using ``-march`` instead of a standard 77ISA naming string. Currently supported profiles: 78 79* ``rvi20u32`` 80* ``rvi20u64`` 81* ``rva20u64`` 82* ``rva20s64`` 83* ``rva22u64`` 84* ``rva22s64`` 85* ``rva23u64`` 86* ``rva23s64`` 87* ``rvb23u64`` 88* ``rvb23s64`` 89 90Note that you can also append additional extension names to be enabled, e.g. 91``rva20u64_zicond`` will enable the ``zicond`` extension in addition to those 92in the ``rva20u64`` profile. 93 94Profiles that are not yet ratified cannot be used unless 95``-menable-experimental-extensions`` (or equivalent for other tools) is 96specified. This applies to the following profiles: 97 98* ``rvm23u32`` 99 100.. _riscv-extensions: 101 102Extensions 103========== 104 105The following table provides a status summary for extensions which have been 106ratified and thus have finalized specifications. When relevant, detailed notes 107on support follow. 108 109 .. table:: Ratified Extensions by Status 110 111 ================ ================================================================= 112 Extension Status 113 ================ ================================================================= 114 ``A`` Supported 115 ``B`` Supported 116 ``C`` Supported 117 ``D`` Supported 118 ``F`` Supported 119 ``E`` Supported (`See note <#riscv-rve-note>`__) 120 ``H`` Assembly Support 121 ``M`` Supported 122 ``Sha`` Supported 123 ``Shcounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 124 ``Shgatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 125 ``Shtvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 126 ``Shvsatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 127 ``Shvstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 128 ``Shvstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 129 ``Smaia`` Supported 130 ``Smcdeleg`` Supported 131 ``Smcsrind`` Supported 132 ``Smdbltrp`` Supported 133 ``Smepmp`` Supported 134 ``Smmpm`` Supported 135 ``Smnpm`` Supported 136 ``Smrnmi`` Assembly Support 137 ``Smstateen`` Assembly Support 138 ``Ssaia`` Supported 139 ``Ssccfg`` Supported 140 ``Ssccptr`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 141 ``Sscofpmf`` Assembly Support 142 ``Sscounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 143 ``Sscsrind`` Supported 144 ``Ssdbltrp`` Supported 145 ``Ssnpm`` Supported 146 ``Sspm`` Supported 147 ``Ssqosid`` Assembly Support 148 ``Ssstateen`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 149 ``Ssstrict`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 150 ``Sstc`` Assembly Support 151 ``Sstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 152 ``Sstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 153 ``Ssu64xl`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 154 ``Supm`` Supported 155 ``Svade`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 156 ``Svadu`` Assembly Support 157 ``Svbare`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) 158 ``Svinval`` Assembly Support 159 ``Svnapot`` Assembly Support 160 ``Svpbmt`` Supported 161 ``Svvptc`` Supported 162 ``V`` Supported 163 ``Za128rs`` Supported (`See note <#riscv-profiles-extensions-note>`__) 164 ``Za64rs`` Supported (`See note <#riscv-profiles-extensions-note>`__) 165 ``Zaamo`` Assembly Support 166 ``Zabha`` Supported 167 ``Zacas`` Supported (`See note <#riscv-zacas-note>`__) 168 ``Zalrsc`` Assembly Support 169 ``Zama16b`` Supported (`See note <#riscv-profiles-extensions-note>`__) 170 ``Zawrs`` Assembly Support 171 ``Zba`` Supported 172 ``Zbb`` Supported 173 ``Zbc`` Supported 174 ``Zbkb`` Supported (`See note <#riscv-scalar-crypto-note1>`__) 175 ``Zbkc`` Supported 176 ``Zbkx`` Supported (`See note <#riscv-scalar-crypto-note1>`__) 177 ``Zbs`` Supported 178 ``Zca`` Supported 179 ``Zcb`` Supported 180 ``Zcd`` Supported 181 ``Zcf`` Supported 182 ``Zcmop`` Supported 183 ``Zcmp`` Supported 184 ``Zcmt`` Assembly Support 185 ``Zdinx`` Supported 186 ``Zfa`` Supported 187 ``Zfbfmin`` Supported 188 ``Zfh`` Supported 189 ``Zfhmin`` Supported 190 ``Zfinx`` Supported 191 ``Zhinx`` Supported 192 ``Zhinxmin`` Supported 193 ``Zic64b`` Supported (`See note <#riscv-profiles-extensions-note>`__) 194 ``Zicbom`` Assembly Support 195 ``Zicbop`` Supported 196 ``Zicboz`` Assembly Support 197 ``Ziccamoa`` Supported (`See note <#riscv-profiles-extensions-note>`__) 198 ``Ziccif`` Supported (`See note <#riscv-profiles-extensions-note>`__) 199 ``Zicclsm`` Supported (`See note <#riscv-profiles-extensions-note>`__) 200 ``Ziccrse`` Supported (`See note <#riscv-profiles-extensions-note>`__) 201 ``Zicntr`` (`See Note <#riscv-i2p1-note>`__) 202 ``Zicond`` Supported 203 ``Zicsr`` (`See Note <#riscv-i2p1-note>`__) 204 ``Zifencei`` (`See Note <#riscv-i2p1-note>`__) 205 ``Zihintntl`` Supported 206 ``Zihintpause`` Assembly Support 207 ``Zihpm`` (`See Note <#riscv-i2p1-note>`__) 208 ``Zimop`` Supported 209 ``Zkn`` Supported 210 ``Zknd`` Supported (`See note <#riscv-scalar-crypto-note2>`__) 211 ``Zkne`` Supported (`See note <#riscv-scalar-crypto-note2>`__) 212 ``Zknh`` Supported (`See note <#riscv-scalar-crypto-note2>`__) 213 ``Zksed`` Supported (`See note <#riscv-scalar-crypto-note2>`__) 214 ``Zksh`` Supported (`See note <#riscv-scalar-crypto-note2>`__) 215 ``Zk`` Supported 216 ``Zkr`` Supported 217 ``Zks`` Supported 218 ``Zkt`` Supported 219 ``Zmmul`` Supported 220 ``Ztso`` Supported 221 ``Zvbb`` Supported 222 ``Zvbc`` Supported (`See note <#riscv-vector-crypto-note>`__) 223 ``Zve32x`` (`Partially <#riscv-vlen-32-note>`__) Supported 224 ``Zve32f`` (`Partially <#riscv-vlen-32-note>`__) Supported 225 ``Zve64x`` Supported 226 ``Zve64f`` Supported 227 ``Zve64d`` Supported 228 ``Zvfbfmin`` Supported 229 ``Zvfbfwma`` Supported 230 ``Zvfh`` Supported 231 ``Zvfhmin`` Supported 232 ``Zvkb`` Supported 233 ``Zvkg`` Supported (`See note <#riscv-vector-crypto-note>`__) 234 ``Zvkn`` Supported (`See note <#riscv-vector-crypto-note>`__) 235 ``Zvknc`` Supported (`See note <#riscv-vector-crypto-note>`__) 236 ``Zvkned`` Supported (`See note <#riscv-vector-crypto-note>`__) 237 ``Zvkng`` Supported (`See note <#riscv-vector-crypto-note>`__) 238 ``Zvknha`` Supported (`See note <#riscv-vector-crypto-note>`__) 239 ``Zvknhb`` Supported (`See note <#riscv-vector-crypto-note>`__) 240 ``Zvks`` Supported (`See note <#riscv-vector-crypto-note>`__) 241 ``Zvksc`` Supported (`See note <#riscv-vector-crypto-note>`__) 242 ``Zvksed`` Supported (`See note <#riscv-vector-crypto-note>`__) 243 ``Zvksg`` Supported (`See note <#riscv-vector-crypto-note>`__) 244 ``Zvksh`` Supported (`See note <#riscv-vector-crypto-note>`__) 245 ``Zvkt`` Supported 246 ``Zvl32b`` (`Partially <#riscv-vlen-32-note>`__) Supported 247 ``Zvl64b`` Supported 248 ``Zvl128b`` Supported 249 ``Zvl256b`` Supported 250 ``Zvl512b`` Supported 251 ``Zvl1024b`` Supported 252 ``Zvl2048b`` Supported 253 ``Zvl4096b`` Supported 254 ``Zvl8192b`` Supported 255 ``Zvl16384b`` Supported 256 ``Zvl32768b`` Supported 257 ``Zvl65536b`` Supported 258 ================ ================================================================= 259 260Assembly Support 261 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. 262 263Supported 264 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. 265 266.. _riscv-rve-note: 267 268``E`` 269 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. 270 271.. _riscv-scalar-crypto-note1: 272 273``Zbkb``, ``Zbkx`` 274 Pattern matching support for these instructions is incomplete. 275 276.. _riscv-scalar-crypto-note2: 277 278``Zknd``, ``Zkne``, ``Zknh``, ``Zksed``, ``Zksh`` 279 No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls. 280 281.. _riscv-vector-crypto-note: 282 283``Zvbc``, ``Zvkg``, ``Zvkn``, ``Zvknc``, ``Zvkned``, ``Zvkng``, ``Zvknha``, ``Zvknhb``, ``Zvks``, ``Zvks``, ``Zvks``, ``Zvksc``, ``Zvksed``, ``Zvksg``, ``Zvksh``. 284 No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls. 285 286.. _riscv-vlen-32-note: 287 288``Zve32x``, ``Zve32f``, ``Zvl32b`` 289 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. 290 291.. _riscv-i2p1-note: 292 293``Zicntr``, ``Zicsr``, ``Zifencei``, ``Zihpm`` 294 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. 295 296.. _riscv-profiles-extensions-note: 297 298``Za128rs``, ``Za64rs``, ``Zama16b``, ``Zic64b``, ``Ziccamoa``, ``Ziccif``, ``Zicclsm``, ``Ziccrse``, ``Shcounterenvw``, ``Shgatpa``, ``Shtvala``, ``Shvsatpa``, ``Shvstvala``, ``Shvstvecd``, ``Ssccptr``, ``Sscounterenw``, ``Ssstateen``, ``Ssstrict``, ``Sstvala``, ``Sstvecd``, ``Ssu64xl``, ``Svade``, ``Svbare`` 299 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. 300 301.. _riscv-zacas-note: 302 303``Zacas`` 304 The compiler will not generate amocas.d on RV32 or amocas.q on RV64 due to ABI compatibilty. These can only be used in the assembler. 305 306Atomics ABIs 307============ 308 309At the time of writing there are three atomics mappings (ABIs) `defined for RISC-V <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#tag_riscv_atomic_abi-14-uleb128version>`__. As of LLVM 19, LLVM defaults to "A6S", which is compatible with both the original "A6" and the future "A7" ABI. See `the psABI atomics document <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-atomic.adoc>`__ for more information on these mappings. 310 311Note that although the "A6S" mapping is used, the ELF attribute recording the mapping isn't currently emitted by default due to a bug causing a crash in older versions of binutils when processing files containing this attribute. 312 313Experimental Extensions 314======================= 315 316LLVM 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. 317 318The 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. 319 320``experimental-zalasr`` 321 LLVM implements the `0.0.5 draft specification <https://github.com/mehnadnerd/riscv-zalasr>`__. 322 323``experimental-zicfilp``, ``experimental-zicfiss`` 324 LLVM implements the `1.0 release specification <https://github.com/riscv/riscv-cfi/releases/tag/v1.0>`__. 325 326``experimental-zvbc32e``, ``experimental-zvkgs`` 327 LLVM implements the `0.7 release specification <https://github.com/user-attachments/files/16450464/riscv-crypto-spec-vector-extra_v0.0.7.pdf>`__. 328 329``experimental-sdext``, ``experimental-sdtrig`` 330 LLVM implements the `1.0-rc4 specification <https://github.com/riscv/riscv-debug-spec/releases/download/1.0.0-rc4/riscv-debug-specification.pdf>`__. 331 332``experimental-smctr``, ``experimental-ssctr`` 333 LLVM implements the `1.0-rc3 specification <https://github.com/riscv/riscv-control-transfer-records/releases/tag/v1.0_rc3>`__. 334 335``experimental-svukte`` 336 LLVM implements the `0.3 draft specification <https://github.com/riscv/riscv-isa-manual/pull/1564>`__. 337 338To 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`. 339 340Vendor Extensions 341================= 342 343Vendor 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. 344 345Inclusion 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>`__. 346 347It 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. 348 349The current vendor extensions supported are: 350 351``XTHeadBa`` 352 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. 353 354``XTHeadBb`` 355 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. 356 357``XTHeadBs`` 358 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. 359 360``XTHeadCondMov`` 361 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. 362 363``XTHeadCmo`` 364 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. 365 366``XTHeadFMemIdx`` 367 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. 368 369``XTheadMac`` 370 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. 371 372``XTHeadMemIdx`` 373 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. 374 375``XTHeadMemPair`` 376 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. 377 378``XTHeadSync`` 379 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. 380 381``XTHeadVdot`` 382 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. 383 384``XVentanaCondOps`` 385 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. 386 387``XSfvcp`` 388 LLVM implements `version 1.1.0 of the SiFive Vector Coprocessor Interface (VCIX) Software Specification <https://sifive.cdn.prismic.io/sifive/Zn3m1R5LeNNTwnLS_vcix-spec-software-v1p1.pdf>`__ by SiFive. All instructions are prefixed with `sf.vc.` as described in the specification, and the riscv-toolchain-convention document linked above. 389 390``XSfvqmaccdod``, ``XSfvqmaccqoq`` 391 LLVM implements `version 1.1.0 of the SiFive Int8 Matrix Multiplication Extensions Specification <https://sifive.cdn.prismic.io/sifive/1a2ad85b-d818-49f7-ba83-f51f1731edbe_int8-matmul-spec.pdf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above. 392 393``Xsfvfnrclipxfqf`` 394 LLVM implements `version 1.0.0 of the FP32-to-int8 Ranged Clip Instructions Extension Specification <https://sifive.cdn.prismic.io/sifive/0aacff47-f530-43dc-8446-5caa2260ece0_xsfvfnrclipxfqf-spec.pdf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above. 395 396``Xsfvfwmaccqqq`` 397 LLVM implements `version 1.0.0 of the Matrix Multiply Accumulate Instruction Extension Specification <https://sifive.cdn.prismic.io/sifive/c391d53e-ffcf-4091-82f6-c37bf3e883ed_xsfvfwmaccqqq-spec.pdf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above. 398 399``XCVbitmanip`` 400 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. 401 402``XCVelw`` 403 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. 404 405``XCVmac`` 406 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. 407 408``XCVmem`` 409 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. 410 411``XCValu`` 412 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. 413 414``XCVsimd`` 415 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. 416 417``XCVbi`` 418 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. 419 420``XSiFivecdiscarddlone`` 421 LLVM implements `the SiFive sf.cdiscard.d.l1 instruction specified in <https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf>`_ by SiFive. 422 423``XSiFivecflushdlone`` 424 LLVM implements `the SiFive sf.cflush.d.l1 instruction specified in <https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf>`_ by SiFive. 425 426``XSfcease`` 427 LLVM implements `the SiFive sf.cease instruction specified in <https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf>`_ by SiFive. 428 429``Xwchc`` 430 LLVM implements `the custom compressed opcodes present in some QingKe cores` by WCH / Nanjing Qinheng Microelectronics. The vendor refers to these opcodes by the name "XW". 431 432``experimental-Xqcia`` 433 LLVM implements `version 0.2 of the Qualcomm uC Arithmetic extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 434 435``experimental-Xqciac`` 436 LLVM implements `version 0.3 of the Qualcomm uC Load-Store Address Calculation extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 437 438``experimental-Xqcicli`` 439 LLVM implements `version 0.2 of the Qualcomm uC Conditional Load Immediate extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 440 441``experimental-Xqcicm`` 442 LLVM implements `version 0.2 of the Qualcomm uC Conditional Move extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 443 444``experimental-Xqcics`` 445 LLVM implements `version 0.2 of the Qualcomm uC Conditional Select extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 446 447``experimental-Xqcicsr`` 448 LLVM implements `version 0.2 of the Qualcomm uC CSR extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 449 450``experimental-Xqciint`` 451 LLVM implements `version 0.2 of the Qualcomm uC Interrupts extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 452 453``experimental-Xqcilo`` 454 LLVM implements `version 0.2 of the Qualcomm uC Large Offset Load Store extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 455 456``experimental-Xqcilsm`` 457 LLVM implements `version 0.2 of the Qualcomm uC Load Store Multiple extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 458 459``experimental-Xqcisls`` 460 LLVM implements `version 0.2 of the Qualcomm uC Scaled Load Store extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32. 461 462``Xmipscmove`` 463 LLVM implements conditional move for the `p8700 processor <https://mips.com/products/hardware/p8700/>` by MIPS. 464 465``Xmipslsp`` 466 LLVM implements load/store pair instructions for the `p8700 processor <https://mips.com/products/hardware/p8700/>` by MIPS. 467 468Experimental C Intrinsics 469========================= 470 471In some cases an extension is non-experimental but the C intrinsics for that 472extension are still experimental. To use C intrinsics for such an extension 473from `clang`, you must add `-menable-experimental-extensions` to the command 474line. This currently applies to the following extensions: 475 476No extensions have experimental intrinsics. 477 478Long (>32-bit) Instruction Support 479================================== 480 481RISC-V is a variable-length ISA, but the standard currently only defines 16- and 32-bit instructions. The specification describes longer instruction encodings, but these are not ratified. 482 483The LLVM disassembler, `llvm-objdump`, does use the longer instruction encodings described in the specification to guess the instruction length (up to 176 bits) and will group the disassembly view of encoding bytes correspondingly. 484 485The LLVM integrated assembler for RISC-V supports two different kinds of ``.insn`` directive, for assembling instructions that LLVM does not yet support: 486 487* ``.insn type, args*`` which takes a known instruction type, and a list of fields. You are strongly recommended to use this variant of the directive if your instruction fits an existing instruction type. 488* ``.insn [ length , ] encoding`` which takes an (optional) explicit length (in bytes) and a raw encoding for the instruction. When given an explicit length, this variant can encode instructions up to 64 bits long. The encoding part of the directive must be given all bits for the instruction, none are filled in for the user. When used without the optional length, this variant of the directive will use the LSBs of the raw encoding to work out if an instruction is 16 or 32 bits long. LLVM does not infer that an instruction might be longer than 32 bits - in this case, the user must give the length explicitly. 489 490It is strongly recommended to use the ``.insn`` directive for assembling unsupported instructions instead of ``.word`` or ``.hword``, because it will produce the correct mapping symbols to mark the word as an instruction, not data. 491 492Global Pointer (GP) Relaxation and the Small Data Limit 493======================================================= 494 495Some of the RISC-V psABI variants reserve ``gp`` (``x3``) for use as a "Global Pointer", to make generating data addresses more efficient. 496 497To use this functionality, you need to be doing all of the following: 498 499* Use the ``medlow`` (aka ``small``) code model; 500* Not use the ``gp`` register for any other uses (some platforms use it for the shadow stack and others as a temporary -- as denoted by the ``Tag_RISCV_x3_reg_usage`` build attribute); 501* Compile your objects with Clang's ``-mrelax`` option, to enable relaxation annotations on relocatable objects (this is the default, but ``-mno-relax`` disables these relaxation annotations); 502* Compile for a position-dependent static executable (not a shared library, and ``-fno-PIC`` / ``-fno-pic`` / ``-fno-pie``); and 503* Use LLD's ``--relax-gp`` option. 504 505LLD will relax (rewrite) any code sequences that materialize an address within 2048 bytes of ``__global_pointer$`` (which will be defined if it is used and does not already exist) to instead generate the address using ``gp`` and the correct (signed) 12-bit immediate. This usually saves at least one instruction compared to materialising a full 32-bit address value. 506 507There can only be one ``gp`` value in a process (as ``gp`` is not changed when calling into a function in a shared library), so the symbol is is only defined and this relaxation is only done for executables, and not for shared libraries. The linker expects executable startup code to put the value of ``__global_pointer$`` (from the executable) into ``gp`` before any user code is run. 508 509Arguably, the most efficient use for this addressing mode is for smaller global variables, as larger global variables likely need many more loads or stores when they are being accessed anyway, so the cost of materializing the upper bits can be shared. 510 511Therefore the compiler can place smaller global variables into sections with names starting with ``.sdata`` or ``.sbss`` (matching sections with names starting with ``.data`` and ``.bss`` respectively). LLD knows to define the ``global_pointer$`` symbol close to these sections, and to lay these sections out adjacent to the ``.data`` section. 512 513Clang's ``-msmall-data-limit=`` option controls what the threshold size is (in bytes) for a global variable to be considered small. ``-msmall-data-limit=0`` disables the use of sections starting ``.sdata`` and ``.sbss``. The ``-msmall-data-limit=`` option will not move global variables that have an explicit data section, and will keep globals in separate sections if you are using ``-fdata-sections``. 514 515The small data limit threshold is also used to separate small constants into sections with names starting with ``.srodata``. LLD does not place these with the ``.sdata`` and ``.sbss`` sections as ``.srodata`` sections are read only and the other two are writable. Instead the ``.srodata`` sections are placed adjacent to ``.rodata``. 516 517Data suggests that these options can produce significant improvements across a range of benchmarks. 518