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