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