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*, and x* 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:

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.

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.

Ratified Extensions by Status

Extension

Status

A

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

Smepmp

Supported

Ssaia

Supported

Ssccptr

Assembly Support (See note)

Sscofpmf

Assembly Support

Sscounterenw

Assembly Support (See note)

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)

Zacas

Supported (See note)

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

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

Zvbb

Assembly Support

Zvbc

Assembly Support

Zve32x

(Partially) Supported

Zve32f

(Partially) Supported

Zve64x

Supported

Zve64f

Supported

Zve64d

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 and Zve32f 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 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.

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.

Zacas

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.

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 v0.8.1 draft specification.

experimental-ssqosid

LLVM implements assembler support for the v1.0-rc1 draft specification.

experimental-zabha

LLVM implements the v1.0-rc1 draft specification.

experimental-zalasr

LLVM implements the 0.0.5 draft specification.

experimental-zfbfmin, experimental-zvfbfmin, experimental-zvfbfwma

LLVM implements assembler support for the 1.0.0-rc2 specification.

experimental-zicfilp, experimental-zicfiss

LLVM implements the 0.4 draft specification.

experimental-ztso

LLVM implements the v0.1 proposed specification (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.

experimental-zaamo, experimental-zalrsc

LLVM implements the v0.2 proposed 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.0.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.

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