​

RISC-V Toolchain Conventions

Copyright and license information

This document is authored by:

  • Alex Bradbury ​​asb@lowrisc.org​​.

Licensed under the Creative Commons Attribution 4.0 International License (CC-BY 4.0). The full license text is available at ​​https://creativecommons.org/licenses/by/4.0/​​.

Aims

This effort aims to document the expected behaviour and command-line interface of RISC-V toolchains. In doing so, we can provide an avenue for members of the GNU and LLVM communities to collaborate on standardising and extending these conventions. A diverse range of RISC-V implementations and custom extensions will inevitably result in vendor-specific toolchains being created and distributed. By describing a clear preferred path for exposing vendor-specific
extensions or modifications, we can try to increase the likelihood that these vendor toolchain distributions have a common interface and aren’t gratuitously different.

Status and roadmap

This document is a work-in-progress, and contains many sections that serve mainly to enumerate current gaps or oddities. The plan is to seek feedback and further develop the proposal with the help of the RISC-V community, then to seek input from the wider GCC and Clang developer communities for extensions or changes beyond the current set of command-line options supported by GCC.

See the ​​issues list​​ to discuss any of the problems or TODO items described in this document.

This document is currently targeted at toolchain implementers and developers, but over time we hope it will also become a useful reference for RISC-V toolchain users.

See also

Specifying the target ISA with -march

The compiler and assembler both accept the ​​-march​​​ flag to specify the target ISA, e.g. “rv32imafd”. The abbreviation “g” can be used to represent the IMAFD base and extensions, e.g. ​​-march=rv64g​​​. A target ​​-march​​​ which includes floating point instructions implies a hardfloat calling convention, but can be overridden using the ​​-mabi​​ flag (see the next section).

The ISA subset naming conventions are described in Chapter 22 of the RISC-V user-level ISA specification. However, tools do not currently follow this specification (no support for parsing version specifiers, input is case
sensitive, …).

If the ‘C’ (compressed) instruction set extension is targeted, the compiler will generate compressed instructions where possible.

Issues for consideration

  • Whether ​​riscv32​​​ and ​​riscv64​​​ should be accepted as synonyms for ​​rv32​​​ and ​​rv64​​.
  • Whether the ​​-march​​ string should be parsed case insensitively.
  • Exposing the ability to specify version numbers for a target extension.
  • Specifying non-standard extensions. The ISA specification suggests naming such as ​​rv32gXfirstext_Xsecondext​​​. In GCC or Clang it would be more conventional to give a string such as ​​rv32g+firstext+secondext​​.
  • How to specify more fine-grained information about a target. e.g. an RV32I target that implements only M-mode and doesn’t support the ​​rdcycle​​ instruction, or an RV32IM target that doesn’t support the division instructions.
  • Whether ordering should be enforced on the ISA string (e.g. currently ​​rv32imafd​​​ is accepted by GCC but ​​rv32iamfd​​ is not).

Specifying the target ABI with -mabi

RISC-V compilers support the following ABIs, which can be specified using ​​-mabi​​:

  • ​​ilp32​​: int, long, pointers are 32-bit. GPRs and the stack are used for parameter passing.
  • ​​ilp32f​​: int, long, pointers are 32-bit. GPRs, 32-bit FPRs, and the stack are used for parameter passing.
  • ​​ilp32d​​: int, long, pointers are 32-bit. GPRs, 64-bit FPRs and the stack are used for parameter passing.
  • ​​lp64​​: long, pointers are 64-bit. GPRs and the the stack are used for parameter passing.
  • ​​lp64f​​: long, pointers are 64-bit. GPRs, 32-bit FPRs, and the stack are used for parameter passing.
  • ​​lp64d​​: long, pointers are 64-bit. GPRs, 64-bit FPRs, and the stack are used for parameter passing.

See the ​​RISC-V ELF psABI​​ for more information on these ABIs.

The default value for ​​-mabi​​​ is system dependent. For cross-compilation, both​​-march​​​ and ​​-mabi​​​ should be specified. An error will be produced for impossible combinations of ​​-march​​​ and ​​-mabi​​​ such as ​​-march=rv32i​​​ and ​​-mabi=ilp32f​​.

Issues for consideration

  • Should the ​​-mabi​​ string be parsed case insensitively?
  • How should the RV32E ABI be specified? ilp32e?

Specifying the target code model with -mcmodel

The target code model indicates constraints on symbols which the compiler can exploit these constraints to generate more efficient code. Two code models are currently defined for RISC-V:

  • ​​-mcmodel=medlow​​​. The program and its statically defined symbols must lie within a single 2GiB address range, between the absolute addresses -2GiB and +2GiB. ​​lui​​​ and ​​addi​​ pairs are used to generate addresses.
  • ​​-mcmodel=medany​​​. The program and its statically defined symbols must lie within a single 4GiB address range. ​​auipc​​​ and ​​addi​​ pairs are used to generate addresses.

TODO: interaction with PIC.

Issues for consideration

  • It has been proposed to deprecate the ​​medlow​​​ code model and rename ​​medany​​​ to ​​medium​​.

Disassembler (objdump) behaviour

A RISC-V ELF binary is not currently self-describing, in the sense that it doesn’t contain enough information to determine which variant of the RISC-V architecture is being targeted. GNU objdump will currently attempt disassemble any instruction whose encoding matches one of the standard RV32/RV64 IMAFDC extensions.

objdump will default to showing pseudoinstructions and ABI register names. The ​​numeric​​​ disassembler argument can be used to use architectural register names such as ​​x10​​​, while the ​​no-aliases​​​ disassembler argument will ensure only canonical instructions rather than pseudoinstructions or aliases are printed. These arguments are specified using ​​-M​​​, e.g. ​​-M numeric​​​ or ​​-M numeric,no-aliases​​.

Perhaps surprisingly, the disassembler will default to hiding the difference between compressed (16-bit) instructions and their 32-bit equivalent. e.g.​​c.addi sp, -16​​​ will be printed as ​​addi sp, sp, -16​​.

Issues for consideration

  • The current GNU objdump behaviour will not provide useful results for cases where non-standard extensions are implemented which reuse some of the standard extension’s encoding space. Making RISC-V ELF files self-describing (as discussed ​​here​​) would avoid this problem.
  • Would it be useful to have separate flags that control the printing of pseudoinstructions and whether compressed instructions are printed directly or not?

Assembler behaviour

See the ​​RISC-V Assembly Programmer’s Manual​​ for details on the syntax accepted by the assembler.

The assembler will produce compressed instructions whenever possible if the targeted RISC-V variant includes support for the ‘C’ compressed instruction set.

Issues for consideration

  • There is currently no way to enable support for the C ISA extension, but to disable the automatic ‘compression’ of instructions.

C/C++ preprocessor definitions

  • ​​__riscv​​​: defined for any RISC-V target. Older versions of the GCC toolchain defined ​​__riscv__​​.
  • ​​__riscv_xlen​​: 32 for RV32 and 64 for RV64.
  • ​​__riscv_float_abi_soft​​​, ​​__riscv_float_abi_single​​​,
    ​​​__riscv_float_abi_double​​: one of these three will be defined, depending on target ABI.
  • ​​__riscv_cmodel_medlow​​​, ​​__riscv_cmodel_medany​​: one of these two will be defined, depending on the target code model.
  • ​​__riscv_mul​​: defined when targeting the ‘M’ ISA extension.
  • ​​__riscv_muldiv​​​: defined when targeting the ‘M’ ISA extension and ​​-mno-div​​ has not been used.
  • ​​__riscv_div​​​: defined when targeting the ‘M’ ISA extension and ​​-mno-div​​ has not been used.
  • ​​__riscv_atomic​​: defined when targeting the ‘A’ ISA extension.
  • ​​__riscv_flen​​: 32 when targeting the ‘F’ ISA extension (but not ‘D’) and 64 when targeting ‘FD’.
  • ​​__riscv_fdiv​​​: defined when targeting the ‘F’ or ‘D’ ISA extensions and ​​-mno-fdiv​​ has not been used.
  • ​​__riscv_fsqrt​​​: defined when targeting the ‘F’ or ‘D’ ISA extensions and ​​-mno-fdiv​​ has not been used.
  • ​​__riscv_compressed​​: defined when targeting the ‘C’ ISA extension.

Issues for consideration

  • What should the naming convention be for defines that indicate support for non-standard extensions?
  • What additional information could/should be exposed via preprocessor defines?

Specifying stack alignment

The default stack alignment is 16 bytes in RV32I and RV64I, and 4 bytes on RV32E. There is not currently a way to specify an alternative stack alignment, but the ​​-mpreferred-stack-boundary​​​ and ​​-mincoming-stack-boundary​​ flags supported by GCC on X86 could be adopted.

TODO

  • mdiv, mno-div, mfdiv, mno-fdiv, msave-restore, mno-save-restore, mstrict-align, mno-strict-align, -mexplicit-relocs, -mno-explicit-relocs

Appendix: Exposing a vendor-specific extension across the toolchain

TODO.