gas/doc/c-riscv.texi

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