1@c Copyright (C) 2016-2018 Free Software Foundation, Inc. 2@c This is part of the GAS anual. 3@c For copying conditions, see the file as.texinfo 4@c man end 5 6@ifset GENERIC 7@page 8@node RISC-V-Dependent 9@chapter RISC-V Dependent Features 10@end ifset 11@ifclear GENERIC 12@node Machine Dependencies 13@chapter RISC-V Dependent Features 14@end ifclear 15 16@cindex RISC-V support 17@menu 18* RISC-V-Options:: RISC-V Options 19* RISC-V-Directives:: RISC-V Directives 20* RISC-V-Formats:: RISC-V Instruction Formats 21@end menu 22 23@node RISC-V-Options 24@section RISC-V Options 25 26The following table lists all available RISC-V specific options. 27 28@c man begin OPTIONS 29@table @gcctabopt 30 31@cindex @samp{-fpic} option, RISC-V 32@item -fpic 33@itemx -fPIC 34Generate position-independent code 35 36@cindex @samp{-fno-pic} option, RISC-V 37@item -fno-pic 38Don't generate position-independent code (default) 39 40@cindex @samp{-march=ISA} option, RISC-V 41@item -march=ISA 42Select the base isa, as specified by ISA. For example -march=rv32ima. 43 44@cindex @samp{-mabi=ABI} option, RISC-V 45@item -mabi=ABI 46Selects the ABI, which is either "ilp32" or "lp64", optionally followed 47by "f", "d", or "q" to indicate single-precision, double-precision, or 48quad-precision floating-point calling convention, or none to indicate 49the soft-float calling convention. Also, "ilp32" can optionally be followed 50by "e" to indicate the RVE ABI, which is always soft-float. 51 52@cindex @samp{-mrelax} option, RISC-V 53@item -mrelax 54Take advantage of linker relaxations to reduce the number of instructions 55required to materialize symbol addresses. (default) 56 57@cindex @samp{-mno-relax} option, RISC-V 58@item -mno-relax 59Don't do linker relaxations. 60 61@end table 62@c man end 63 64@node RISC-V-Directives 65@section RISC-V Directives 66@cindex machine directives, RISC-V 67@cindex RISC-V machine directives 68 69The following table lists all available RISC-V specific directives. 70 71@table @code 72 73@cindex @code{align} directive 74@item .align @var{size-log-2} 75Align to the given boundary, with the size given as log2 the number of bytes to 76align to. 77 78@cindex Data directives 79@item .half @var{value} 80@itemx .word @var{value} 81@itemx .dword @var{value} 82Emits a half-word, word, or double-word value at the current position. 83 84@cindex DTP-relative data directives 85@item .dtprelword @var{value} 86@itemx .dtpreldword @var{value} 87Emits a DTP-relative word (or double-word) at the current position. This is 88meant to be used by the compiler in shared libraries for DWARF debug info for 89thread local variables. 90 91@cindex BSS directive 92@item .bss 93Sets the current section to the BSS section. 94 95@cindex LEB128 directives 96@item .uleb128 @var{value} 97@itemx .sleb128 @var{value} 98Emits a signed or unsigned LEB128 value at the current position. This only 99accepts constant expressions, because symbol addresses can change with 100relaxation, and we don't support relocations to modify LEB128 values at link 101time. 102 103@cindex Option directive 104@cindex @code{option} directive 105@item .option @var{argument} 106Modifies RISC-V specific assembler options inline with the assembly code. 107This is used when particular instruction sequences must be assembled with a 108specific set of options. For example, since we relax addressing sequences to 109shorter GP-relative sequences when possible the initial load of GP must not be 110relaxed and should be emitted as something like 111 112@smallexample 113 .option push 114 .option norelax 115 la gp, __global_pointer$ 116 .option pop 117@end smallexample 118 119in order to produce after linker relaxation the expected 120 121@smallexample 122 auipc gp, %pcrel_hi(__global_pointer$) 123 addi gp, gp, %pcrel_lo(__global_pointer$) 124@end smallexample 125 126instead of just 127 128@smallexample 129 addi gp, gp, 0 130@end smallexample 131 132It's not expected that options are changed in this manner during regular use, 133but there are a handful of esoteric cases like the one above where users need 134to disable particular features of the assembler for particular code sequences. 135The complete list of option arguments is shown below: 136 137@table @code 138@item push 139@itemx pop 140Pushes or pops the current option stack. These should be used whenever 141changing an option in line with assembly code in order to ensure the user's 142command-line options are respected for the bulk of the file being assembled. 143 144@item rvc 145@itemx norvc 146Enables or disables the generation of compressed instructions. Instructions 147are opportunistically compressed by the RISC-V assembler when possible, but 148sometimes this behavior is not desirable. 149 150@item pic 151@itemx nopic 152Enables or disables position-independent code generation. Unless you really 153know what you're doing, this should only be at the top of a file. 154 155@item relax 156@itemx norelax 157Enables or disables relaxation. The RISC-V assembler and linker 158opportunistically relax some code sequences, but sometimes this behavior is not 159desirable. 160@end table 161 162@cindex INSN directives 163@item .insn @var{value} 164@itemx .insn @var{value} 165This directive permits the numeric representation of an instructions 166and makes the assembler insert the operands according to one of the 167instruction formats for @samp{.insn} (@ref{RISC-V-Formats}). 168For example, the instruction @samp{add a0, a1, a2} could be written as 169@samp{.insn r 0x33, 0, 0, a0, a1, a2}. 170 171@end table 172 173@node RISC-V-Formats 174@section Instruction Formats 175@cindex instruction formats, risc-v 176@cindex RISC-V instruction formats 177 178The RISC-V Instruction Set Manual Volume I: User-Level ISA lists 12 179instruction formats where some of the formats have multiple variants. 180For the @samp{.insn} pseudo directive the assembler recognizes some 181of the formats. 182Typically, the most general variant of the instruction format is used 183by the @samp{.insn} directive. 184 185The following table lists the abbreviations used in the table of 186instruction formats: 187 188@display 189@multitable @columnfractions .15 .40 190@item opcode @tab Unsigned immediate or opcode name for 7-bits opcode. 191@item opcode2 @tab Unsigned immediate or opcode name for 2-bits opcode. 192@item func7 @tab Unsigned immediate for 7-bits function code. 193@item func4 @tab Unsigned immediate for 4-bits function code. 194@item func3 @tab Unsigned immediate for 3-bits function code. 195@item func2 @tab Unsigned immediate for 2-bits function code. 196@item rd @tab Destination register number for operand x, can be GPR or FPR. 197@item rd' @tab Destination register number for operand x, 198only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5. 199@item rs1 @tab First source register number for operand x, can be GPR or FPR. 200@item rs1' @tab First source register number for operand x, 201only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5. 202@item rs2 @tab Second source register number for operand x, can be GPR or FPR. 203@item rs2' @tab Second source register number for operand x, 204only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5. 205@item simm12 @tab Sign-extended 12-bit immediate for operand x. 206@item simm20 @tab Sign-extended 20-bit immediate for operand x. 207@item simm6 @tab Sign-extended 6-bit immediate for operand x. 208@item uimm8 @tab Unsigned 8-bit immediate for operand x. 209@item symbol @tab Symbol or lable reference for operand x. 210@end multitable 211@end display 212 213The following table lists all available opcode name: 214 215@table @code 216@item C0 217@item C1 218@item C2 219Opcode space for compressed instructions. 220 221@item LOAD 222Opcode space for load instructions. 223 224@item LOAD_FP 225Opcode space for floating-point load instructions. 226 227@item STORE 228Opcode space for store instructions. 229 230@item STORE_FP 231Opcode space for floating-point store instructions. 232 233@item AUIPC 234Opcode space for auipc instruction. 235 236@item LUI 237Opcode space for lui instruction. 238 239@item BRANCH 240Opcode space for branch instructions. 241 242@item JAL 243Opcode space for jal instruction. 244 245@item JALR 246Opcode space for jalr instruction. 247 248@item OP 249Opcode space for ALU instructions. 250 251@item OP_32 252Opcode space for 32-bits ALU instructions. 253 254@item OP_IMM 255Opcode space for ALU with immediate instructions. 256 257@item OP_IMM_32 258Opcode space for 32-bits ALU with immediate instructions. 259 260@item OP_FP 261Opcode space for floating-point operation instructions. 262 263@item MADD 264Opcode space for madd instruction. 265 266@item MSUB 267Opcode space for msub instruction. 268 269@item NMADD 270Opcode space for nmadd instruction. 271 272@item NMSUB 273Opcode space for msub instruction. 274 275@item AMO 276Opcode space for atomic memory operation instructions. 277 278@item MISC_IMM 279Opcode space for misc instructions. 280 281@item SYSTEM 282Opcode space for system instructions. 283 284@item CUSTOM_0 285@item CUSTOM_1 286@item CUSTOM_2 287@item CUSTOM_3 288Opcode space for customize instructions. 289 290@end table 291 292An instruction is two or four bytes in length and must be aligned 293on a 2 byte boundary. The first two bits of the instruction specify the 294length of the instruction, 00, 01 and 10 indicates a two byte instruction, 29511 indicates a four byte instruction. 296 297The following table lists the RISC-V instruction formats that are available 298with the @samp{.insn} pseudo directive: 299 300@table @code 301@item R type: .insn r opcode, func3, func7, rd, rs1, rs2 302@verbatim 303+-------+-----+-----+-------+----+-------------+ 304| func7 | rs2 | rs1 | func3 | rd | opcode | 305+-------+-----+-----+-------+----+-------------+ 30631 25 20 15 12 7 0 307@end verbatim 308 309@item R type with 4 register operands: .insn r opcode, func3, func2, rd, rs1, rs2, rs3 310@verbatim 311+-----+-------+-----+-----+-------+----+-------------+ 312| rs3 | func2 | rs2 | rs1 | func3 | rd | opcode | 313+-----+-------+-----+-----+-------+----+-------------+ 31431 27 25 20 15 12 7 0 315@end verbatim 316 317@item I type: .insn i opcode, func3, rd, rs1, simm12 318@verbatim 319+-------------+-----+-------+----+-------------+ 320| simm12 | rs1 | func3 | rd | opcode | 321+-------------+-----+-------+----+-------------+ 32231 20 15 12 7 0 323@end verbatim 324 325@item S type: .insn s opcode, func3, rd, rs1, simm12 326@verbatim 327+--------------+-----+-----+-------+-------------+-------------+ 328| simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode | 329+--------------+-----+-----+-------+-------------+-------------+ 33031 25 20 15 12 7 0 331@end verbatim 332 333@item SB type: .insn sb opcode, func3, rd, rs1, symbol 334@itemx SB type: .insn sb opcode, func3, rd, simm12(rs1) 335@verbatim 336+--------------+-----+-----+-------+-------------+-------------+ 337| simm21[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode | 338+--------------+-----+-----+-------+-------------+-------------+ 33931 25 20 15 12 7 0 340@end verbatim 341 342@item U type: .insn u opcode, rd, simm20 343@verbatim 344+---------------------------+----+-------------+ 345| simm20 | rd | opcode | 346+---------------------------+----+-------------+ 34731 12 7 0 348@end verbatim 349 350@item UJ type: .insn uj opcode, rd, symbol 351@verbatim 352+------------+--------------+------------+---------------+----+-------------+ 353| simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode | 354+------------+--------------+------------+---------------+----+-------------+ 35531 30 21 20 12 7 0 356@end verbatim 357 358@item CR type: .insn cr opcode2, func4, rd, rs1 359@verbatim 360+---------+--------+-----+---------+ 361| func4 | rd/rs1 | rs2 | opcode2 | 362+---------+--------+-----+---------+ 36315 12 7 2 0 364@end verbatim 365 366@item CI type: .insn ci opcode2, func3, rd, simm6 367@verbatim 368+---------+-----+--------+-----+---------+ 369| func3 | imm | rd/rs1 | imm | opcode2 | 370+---------+-----+--------+-----+---------+ 37115 13 12 7 2 0 372@end verbatim 373 374@item CIW type: .insn ciw opcode2, func3, rd, uimm8 375@verbatim 376+---------+--------------+-----+---------+ 377| func3 | imm | rd' | opcode2 | 378+---------+--------------+-----+---------+ 37915 13 7 2 0 380@end verbatim 381 382@item CB type: .insn cb opcode2, func3, rs1, symbol 383@verbatim 384+---------+--------+------+--------+---------+ 385| func3 | offset | rs1' | offset | opcode2 | 386+---------+--------+------+--------+---------+ 38715 13 10 7 2 0 388@end verbatim 389 390@item CJ type: .insn cj opcode2, symbol 391@verbatim 392+---------+--------------------+---------+ 393| func3 | jump target | opcode2 | 394+---------+--------------------+---------+ 39515 13 7 2 0 396@end verbatim 397 398 399@end table 400 401For the complete list of all instruction format variants see 402The RISC-V Instruction Set Manual Volume I: User-Level ISA. 403