User Guide for RISC-V Target¶
Introduction¶
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.
The ordering of
z*
,s*
, andx*
prefixed extension names is not enforced in user-specified ISA naming strings (e.g.-march
).
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¶
The specification defines five base instruction sets: RV32I, RV32E, RV64I, RV64E, and RV128I. Currently, LLVM fully supports RV32I, and RV64I. RV32E and RV64E are supported by the assembly-based tools only. RV128I is not supported.
To specify the target triple:
Table 110 RISC-V Architectures¶ Architecture
Description
riscv32
RISC-V with XLEN=32 (i.e. RV32I or RV32E)
riscv64
RISC-V with XLEN=64 (i.e. RV64I or RV64E)
To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
architecture string (e.g. riscv32
) with the extension e
.
Profiles¶
Supported profile names can be passed using -march
instead of a standard
ISA naming string. Currently supported profiles:
rvi20u32
rvi20u64
rva20u64
rva20s64
rva22u64
rva22s64
Note that you can also append additional extension names to be enabled, e.g.
rva20u64_zicond
will enable the zicond
extension in addition to those
in the rva20u64
profile.
Profiles that are not yet ratified cannot be used unless
-menable-experimental-extensions
(or equivalent for other tools) is
specified. This applies to the following profiles:
rva23u64
rva23s64
rvb23u64
rvb23s64
rvm23u32
Extensions¶
The following table provides a status summary for extensions which have been ratified and thus have finalized specifications. When relevant, detailed notes on support follow.
Table 111 Ratified Extensions by Status¶ Extension
Status
A
Supported
B
Supported
C
Supported
D
Supported
F
Supported
E
Supported (See note)
H
Assembly Support
M
Supported
Shcounterenw
Assembly Support (See note)
Shgatpa
Assembly Support (See note)
Shtvala
Assembly Support (See note)
Shvsatpa
Assembly Support (See note)
Shvstvala
Assembly Support (See note)
Shvstvecd
Assembly Support (See note)
Smaia
Supported
Smcdeleg
Supported
Smcsrind
Supported
Smepmp
Supported
Smstateen
Assembly Support
Ssaia
Supported
Ssccfg
Supported
Ssccptr
Assembly Support (See note)
Sscofpmf
Assembly Support
Sscounterenw
Assembly Support (See note)
Sscsrind
Supported
Ssqosid
Assembly Support
Ssstateen
Assembly Support (See note)
Ssstrict
Assembly Support (See note)
Sstc
Assembly Support
Sstvala
Assembly Support (See note)
Sstvecd
Assembly Support (See note)
Ssu64xl
Assembly Support (See note)
Svade
Assembly Support (See note)
Svadu
Assembly Support
Svbare
Assembly Support (See note)
Svinval
Assembly Support
Svnapot
Assembly Support
Svpbmt
Supported
V
Supported
Za128rs
Supported (See note)
Za64rs
Supported (See note)
Zaamo
Assembly Support
Zabha
Supported
Zalrsc
Assembly Support
Zama16b
Supported (See note)
Zawrs
Assembly Support
Zba
Supported
Zbb
Supported
Zbc
Supported
Zbkb
Supported (See note)
Zbkc
Supported
Zbkx
Supported (See note)
Zbs
Supported
Zca
Supported
Zcb
Supported
Zcd
Supported
Zcf
Supported
Zcmop
Supported
Zcmp
Supported
Zcmt
Assembly Support
Zdinx
Supported
Zfa
Supported
Zfbfmin
Supported
Zfh
Supported
Zfhmin
Supported
Zfinx
Supported
Zhinx
Supported
Zhinxmin
Supported
Zic64b
Supported (See note)
Zicbom
Assembly Support
Zicbop
Supported
Zicboz
Assembly Support
Ziccamoa
Supported (See note)
Ziccif
Supported (See note)
Zicclsm
Supported (See note)
Ziccrse
Supported (See note)
Zicntr
(See Note)
Zicond
Supported
Zicsr
(See Note)
Zifencei
(See Note)
Zihintntl
Supported
Zihintpause
Assembly Support
Zihpm
(See Note)
Zimop
Supported
Zkn
Supported
Zknd
Supported (See note)
Zkne
Supported (See note)
Zknh
Supported (See note)
Zksed
Supported (See note)
Zksh
Supported (See note)
Zk
Supported
Zkr
Supported
Zks
Supported
Zkt
Supported
Zmmul
Supported
Ztso
Supported
Zvbb
Assembly Support
Zvbc
Assembly Support
Zve32x
(Partially) Supported
Zve32f
(Partially) Supported
Zve64x
Supported
Zve64f
Supported
Zve64d
Supported
Zvfbfmin
Supported
Zvfbfwma
Supported
Zvfh
Supported
Zvkb
Assembly Support
Zvkg
Assembly Support
Zvkn
Assembly Support
Zvknc
Assembly Support
Zvkned
Assembly Support
Zvkng
Assembly Support
Zvknha
Assembly Support
Zvknhb
Assembly Support
Zvks
Assembly Support
Zvksc
Assembly Support
Zvksed
Assembly Support
Zvksg
Assembly Support
Zvksh
Assembly Support
Zvkt
Assembly Support
Zvl32b
(Partially) Supported
Zvl64b
Supported
Zvl128b
Supported
Zvl256b
Supported
Zvl512b
Supported
Zvl1024b
Supported
Zvl2048b
Supported
Zvl4096b
Supported
Zvl8192b
Supported
Zvl16384b
Supported
Zvl32768b
Supported
Zvl65536b
Supported
- Assembly Support
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.
- Supported
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.
E
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.
Zbkb
,Zbkx
Pattern matching support for these instructions is incomplete.
Zknd
,Zkne
,Zknh
,Zksed
,Zksh
No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls.
Zve32x
,Zve32f
,Zvl32b
LLVM currently assumes a minimum VLEN (vector register width) of 64 bits during compilation, and as a result
Zve32x
andZve32f
are supported only for VLEN>=64. Assembly support doesn’t have this restriction.
Zicntr
,Zicsr
,Zifencei
,Zihpm
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
andzihpm
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.
Za128rs
,Za64rs
,Zama16b
,Zic64b
,Ziccamoa
,Ziccif
,Zicclsm
,Ziccrse
,Shcounterenvw
,Shgatpa
,Shtvala
,Shvsatpa
,Shvstvala
,Shvstvecd
,Ssccptr
,Sscounterenw
,Ssstateen
,Ssstrict
,Sstvala
,Sstvecd
,Ssu64xl
,Svade
,Svbare
These extensions are defined as part of the RISC-V Profiles specification. They do not introduce any new features themselves, but instead describe existing hardware features.
Experimental Extensions¶
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.
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.
experimental-ssnpm
,experimental-smnpm
,experimental-smmpm
,experimental-sspm
,experimental-supm
LLVM implements the v1.0.0-rc2 specification.
experimental-zacas
LLVM implements the 1.0 release specification. amocas.w will be used for i32 cmpxchg. amocas.d will be used i64 cmpxchg on RV64. 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. The extension will be left as experimental until an ABI issue is resolved.
experimental-zalasr
LLVM implements the 0.0.5 draft specification.
experimental-zicfilp
,experimental-zicfiss
LLVM implements the 1.0 release specification.
experimental-zvbc32e
,experimental-zvkgs
LLVM implements the 0.7 release specification.
experimental-smctr
,experimental-ssctr
LLVM implements the 1.0-rc3 specification.
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.
Vendor Extensions¶
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.
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.
It is our intention to follow the naming conventions described in riscv-non-isa/riscv-toolchain-conventions. Exceptions to this naming will need to be strongly motivated.
The current vendor extensions supported are:
XTHeadBa
LLVM implements the THeadBa (address-generation) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadBb
LLVM implements the THeadBb (basic bit-manipulation) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadBs
LLVM implements the THeadBs (single-bit operations) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadCondMov
LLVM implements the THeadCondMov (conditional move) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadCmo
LLVM implements the THeadCmo (cache management operations) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadFMemIdx
LLVM implements the THeadFMemIdx (indexed memory operations for floating point) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTheadMac
LLVM implements the XTheadMac (multiply-accumulate instructions) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadMemIdx
LLVM implements the THeadMemIdx (indexed memory operations) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadMemPair
LLVM implements the THeadMemPair (two-GPR memory operations) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadSync
LLVM implements the THeadSync (multi-core synchronization instructions) vendor-defined instructions specified in by T-HEAD of Alibaba. Instructions are prefixed with th. as described in the specification.
XTHeadVdot
LLVM implements version 1.0.0 of the THeadV-family custom instructions specification by T-HEAD of Alibaba. All instructions are prefixed with th. as described in the specification, and the riscv-toolchain-convention document linked above.
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.
XSfvcp
LLVM implements version 1.1.0 of the SiFive Vector Coprocessor Interface (VCIX) Software Specification by SiFive. All instructions are prefixed with sf.vc. as described in the specification, and the riscv-toolchain-convention document linked above.
XSfvqmaccdod
,XSfvqmaccqoq
LLVM implements version 1.1.0 of the SiFive Int8 Matrix Multiplication Extensions Specification by SiFive. All instructions are prefixed with sf. as described in the specification linked above.
Xsfvfnrclipxfqf
LLVM implements version 1.0.0 of the FP32-to-int8 Ranged Clip Instructions Extension Specification by SiFive. All instructions are prefixed with sf. as described in the specification linked above.
Xsfvfwmaccqqq
LLVM implements version 1.0.0 of the Matrix Multiply Accumulate Instruction Extension Specification by SiFive. All instructions are prefixed with sf. as described in the specification linked above.
XCVbitmanip
LLVM implements version 1.0.0 of the CORE-V Bit Manipulation custom instructions specification by OpenHW Group. All instructions are prefixed with cv. as described in the specification.
XCVelw
LLVM implements version 1.0.0 of the CORE-V Event load custom instructions specification by OpenHW Group. All instructions are prefixed with cv. as described in the specification. These instructions are only available for riscv32 at this time.
XCVmac
LLVM implements version 1.0.0 of the CORE-V Multiply-Accumulate (MAC) custom instructions specification 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.
XCVmem
LLVM implements version 1.0.0 of the CORE-V Post-Increment load and stores custom instructions specification by OpenHW Group. All instructions are prefixed with cv. as described in the specification. These instructions are only available for riscv32 at this time.
XCValu
LLVM implements version 1.0.0 of the Core-V ALU custom instructions specification by Core-V. All instructions are prefixed with cv. as described in the specification. These instructions are only available for riscv32 at this time.
XCVsimd
LLVM implements version 1.0.0 of the CORE-V SIMD custom instructions specification by OpenHW Group. All instructions are prefixed with cv. as described in the specification.
XCVbi
LLVM implements version 1.0.0 of the CORE-V immediate branching custom instructions specification by OpenHW Group. All instructions are prefixed with cv. as described in the specification. These instructions are only available for riscv32 at this time.
XSiFivecdiscarddlone
LLVM implements the SiFive sf.cdiscard.d.l1 instruction specified in by SiFive.
XSiFivecflushdlone
LLVM implements the SiFive sf.cflush.d.l1 instruction specified in by SiFive.
XSfcease
LLVM implements the SiFive sf.cease instruction specified in by SiFive.
Xwchc
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”.
Experimental C Intrinsics¶
In some cases an extension is non-experimental but the C intrinsics for that extension are still experimental. To use C intrinsics for such an extension from clang, you must add -menable-experimental-extensions to the command line. This currently applies to the following extensions:
Zvbb
Zvbc
Zvkb
Zvkg
Zvkn
Zvknc
Zvkned
Zvkng
Zvknha
Zvknhb
Zvks
Zvksc
Zvksed
Zvksg
Zvksh
Zvkt