gas/doc/c-riscv.texi

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