gas/doc/c-riscv.texi

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