4.2.1. About LLVM Toolchain

The current llvm toolchain is developed based on the upstream V19.1.7, for extensions we supported, check below:

You can find our llvm source code in https://github.com/riscv-mcu/llvm-project/tree/nuclei/19.x

Note

The LLVM toolchain is implemented based on the upstream version. Many features can be referenced in the official LLVM documentation: https://llvm.org/docs/. Please refer to the corresponding LLVM release version in the documentation for accurate details. Local documentation is also available under gcc/share/doc/llvm/docs/html within the toolchain directory.

4.2.2. Extensions Support

Ratified Extensions

  • Basic Extensions

    i, m, a, f, d, c, h(Assembly only), zaamo, zalrsc, zicsr, zifencei, zihintpause(Assembly only), zicond, zawrs(Assembly only), zfh, zfhmin, zmmul, svinval(Assembly only), svnapot(Assembly only), svpbmt.

  • Z*inx Extensions

    zfinx, zdinx, zhinx, zhinxmin.

  • CMO Extensions(Assembly only)

    zicboz, zicbom, zicbop.

  • Bitmanip Extensions

    zba, zbb, zbc, zbs

  • Crypto Extensions

    zbkb, zbkc, zbkx, zknd, zkne, zknh, zkr, zks, zksed, zksh, zkt.

  • Vector Extensions

    zve32x, zve32f, zve64x, zve64f, zve64d, zvfh, zvfhmin, v.

  • Zc Extensions

    zca, zcb, zce, zcf, zcd, zcmp(Assembly only), zcmt(Assembly only).

  • Zvb Extensions

    zvbb, zvbc

  • Zvk Extensions

    zvkg, zvkned, zvknha, zvknhb, zvksed, zvksh, zvkn, zvknc, zvkng, zvks, zvksc, zvksg, zvkt.

  • Zilsd Extensions

    Zilsd, Zclsd

  • Smrnmi & Double Trap Extensions(Assembly only, added since 2026.10)

    smrnmi, smdbltrp, ssdbltrp.

  • Xxlcz Extensions(Assembly only)

    xxlczpstinc, xxlczbmrk, xxlczbitop, xxlczslet, xxlczabs, xxlczmac, xxlczbri, xxlczbitrev, xxlczgp.

  • Packed SIMD Extension 0.5.4(assembly only before 2026.10, intrinsic support added since 2026.10)

    xxldsp, xxldspn1x, xxldspn2x, xxldspn3x.

    • xxldsp: P-spec-v0.54 + Nuclei Custom EXPD* instructions

    • xxldspn1x: xxldsp + Nuclei Custom N1

    • xxldspn2x: xxldsp + Nuclei Custom N1 & N2

    • xxldspn3x: xxldsp + Nuclei Custom N1 & N2 & N3

    Note

    Fixed in the 2026.10 toolchain: the r inline assembly constraint now allocates a register pair for 64-bit operands on rv32, and the new R constraint can be used to explicitly allocate a register pair.

    Before 2026.10, the xxldsp assembly instructions implemented in LLVM only support single registers, while instructions using register pairs under rv32 behave abnormally. See this issue.

  • Nuclei custom VPU Extensions

  • Nuclei custom BFloat16 Extensions

Experimental Extensions

LLVM supports (to various degrees) a number of experimental extensions. All experimental extensions have experimental- as a prefix. Listed below:

ssnpm, smnpm, smmpm, sspm, supm, ssqosid, zacas, zalasr, zicfilp, zicfiss.

Note

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

4.2.3. General Options

-march=<isa-string>

Generate code for the given RISC-V ISA string. ISA strings must be lower-case, for example rv64imafdc, rv32gcv, or with extension suffixes such as rv64imafdcv_xxlcz. When -march= is not specified, the default ISA string of the target triple is used.

-mcmodel=<arg>

-mcmodel=medany (equivalent to -mcmodel=medium), -mcmodel=medlow (equivalent to -mcmodel=small)

-mcpu=help, -mtune=help

Print out a list of supported processors for the given target (specified through --target=<architecture> or -arch <architecture>). If no target is specified, the system default target will be used.

-fno-vectorize

Use -fno-vectorize and -fno-slp-vectorize to disable LLVM19 automatic vectorization for RVV; by default, automatic vectorization is enabled.

Optimization Option

-O0

Means “no optimization”: this level compiles the fastest and generates the most debuggable code.

-O/-O1

Somewhere between -O0 and -O2.

-O2

Moderate level of optimization which enables most optimizations.

-O3

Like -O2, except that it enables optimizations that take longer to perform or that may generate larger code (in an attempt to make the program run faster).

-Ofast

Enables all the optimizations from -O3 along with other aggressive optimizations that may violate strict compliance with language standards.

-Os

Like -O2 with extra optimizations to reduce code size.

For more about RISC-V options used by LLVM toolchain, please check https://releases.llvm.org/19.1.0/docs/RISCVUsage.html

4.2.4. Nuclei Custom Options

In addition to the standard RISC-V options above, clang in the Nuclei LLVM toolchain provides the following Nuclei custom options:

Note

The actual functionality of these options is not implemented yet, currently clang only accepts them without reporting errors.

-mautovec-rvv/-mno-autovec-rvv

Controls the RISC-V RVV automatic vectorization. Enabled by default, use -mno-autovec-rvv to disable it. This option is added in 2026.10.

-mautovec-dsp/-mno-autovec-dsp

Controls the generation of automatic vectorization of Nuclei DSP instructions. Disabled by default, use -mautovec-dsp to enable it. This option is added in 2026.10.

-mautogen-xxlcz/-mno-autogen-xxlcz

Controls the auto-generation of the Nuclei xxlcz extension instructions. Disabled by default, use -mautogen-xxlcz to enable it. This option is added in 2026.10.

4.2.5. Install and Setup

More information on building and running LLVM, see https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm

4.2.6. Changelog

Please check Changelog here.

4.2.7. Checking LLVM Version

To check the basic version information of LLVM, you can use the command riscv64-unknown-elf-clang -v.

If you need to report an issue to the developers, please provide:

  1. The gcc/build.txt file (located in the toolchain directory) for toolchain build details.

  2. The gcc/gitrepo.txt file to confirm commit IDs of each tool, which helps determine more detailed build information.

4.2.8. Known Issues

Note

This chapter only lists the bugs that are still unfixed at present (or known usage limitations). For the bugs that have already been fixed, and for more bug issues, please refer to https://github.com/riscv-mcu/riscv-gnu-toolchain/issues/18.

Compared with the GCC toolchain, the LLVM toolchain generally has more limitations, and its support for Nuclei custom extensions is less complete (many of them are assembly-only or intrinsic-only). The missing support will be added in later releases.