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
9 @chapter RISC-V Dependent Features
12 @node Machine Dependencies
13 @chapter RISC-V Dependent Features
16 @cindex RISC-V support
18 * RISC-V-Options:: RISC-V Options
19 * RISC-V-Directives:: RISC-V Directives
20 * RISC-V-Modifiers:: RISC-V Assembler Modifiers
21 * RISC-V-Formats:: RISC-V Instruction Formats
22 * RISC-V-ATTRIBUTE:: RISC-V Object Attribute
26 @section RISC-V Options
28 The following table lists all available RISC-V specific options.
33 @cindex @samp{-fpic} option, RISC-V
36 Generate position-independent code
38 @cindex @samp{-fno-pic} option, RISC-V
40 Don't generate position-independent code (default)
42 @cindex @samp{-march=ISA} option, RISC-V
44 Select the base isa, as specified by ISA. For example -march=rv32ima.
45 If this option and the architecture attributes aren’t set, then assembler
46 will check the default configure setting --with-arch=ISA.
48 @cindex @samp{-misa-spec=ISAspec} option, RISC-V
49 @item -misa-spec=ISAspec
50 Select the default isa spec version. If the version of ISA isn't set
51 by -march, then assembler helps to set the version according to
52 the default chosen spec. If this option isn't set, then assembler will
53 check the default configure setting --with-isa-spec=ISAspec.
55 @cindex @samp{-mpriv-spec=PRIVspec} option, RISC-V
56 @item -mpriv-spec=PRIVspec
57 Select the privileged spec version. We can decide whether the CSR is valid or
58 not according to the chosen spec. If this option and the privilege attributes
59 aren't set, then assembler will check the default configure setting
60 --with-priv-spec=PRIVspec.
62 @cindex @samp{-mabi=ABI} option, RISC-V
64 Selects the ABI, which is either "ilp32" or "lp64", optionally followed
65 by "f", "d", or "q" to indicate single-precision, double-precision, or
66 quad-precision floating-point calling convention, or none to indicate
67 the soft-float calling convention. Also, "ilp32" can optionally be followed
68 by "e" to indicate the RVE ABI, which is always soft-float.
70 @cindex @samp{-mrelax} option, RISC-V
72 Take advantage of linker relaxations to reduce the number of instructions
73 required to materialize symbol addresses. (default)
75 @cindex @samp{-mno-relax} option, RISC-V
77 Don't do linker relaxations.
79 @cindex @samp{-march-attr} option, RISC-V
81 Generate the default contents for the riscv elf attribute section if the
82 .attribute directives are not set. This section is used to record the
83 information that a linker or runtime loader needs to check compatibility.
84 This information includes ISA string, stack alignment requirement, unaligned
85 memory accesses, and the major, minor and revision version of privileged
88 @cindex @samp{-mno-arch-attr} option, RISC-V
90 Don't generate the default riscv elf attribute section if the .attribute
91 directives are not set.
93 @cindex @samp{-mcsr-check} option, RISC-V
95 Enable the CSR checking for the ISA-dependent CRS and the read-only CSR.
96 The ISA-dependent CSR are only valid when the specific ISA is set. The
97 read-only CSR can not be written by the CSR instructions.
99 @cindex @samp{-mno-csr-check} option, RISC-V
101 Don't do CSR cheching.
105 @node RISC-V-Directives
106 @section RISC-V Directives
107 @cindex machine directives, RISC-V
108 @cindex RISC-V machine directives
110 The following table lists all available RISC-V specific directives.
114 @cindex @code{align} directive
115 @item .align @var{size-log-2}
116 Align to the given boundary, with the size given as log2 the number of bytes to
119 @cindex Data directives
120 @item .half @var{value}
121 @itemx .word @var{value}
122 @itemx .dword @var{value}
123 Emits a half-word, word, or double-word value at the current position.
125 @cindex DTP-relative data directives
126 @item .dtprelword @var{value}
127 @itemx .dtpreldword @var{value}
128 Emits a DTP-relative word (or double-word) at the current position. This is
129 meant to be used by the compiler in shared libraries for DWARF debug info for
130 thread local variables.
132 @cindex BSS directive
134 Sets the current section to the BSS section.
136 @cindex LEB128 directives
137 @item .uleb128 @var{value}
138 @itemx .sleb128 @var{value}
139 Emits a signed or unsigned LEB128 value at the current position. This only
140 accepts constant expressions, because symbol addresses can change with
141 relaxation, and we don't support relocations to modify LEB128 values at link
144 @cindex Option directive
145 @cindex @code{option} directive
146 @item .option @var{argument}
147 Modifies RISC-V specific assembler options inline with the assembly code.
148 This is used when particular instruction sequences must be assembled with a
149 specific set of options. For example, since we relax addressing sequences to
150 shorter GP-relative sequences when possible the initial load of GP must not be
151 relaxed and should be emitted as something like
156 la gp, __global_pointer$
160 in order to produce after linker relaxation the expected
163 auipc gp, %pcrel_hi(__global_pointer$)
164 addi gp, gp, %pcrel_lo(__global_pointer$)
173 It's not expected that options are changed in this manner during regular use,
174 but there are a handful of esoteric cases like the one above where users need
175 to disable particular features of the assembler for particular code sequences.
176 The complete list of option arguments is shown below:
181 Pushes or pops the current option stack. These should be used whenever
182 changing an option in line with assembly code in order to ensure the user's
183 command-line options are respected for the bulk of the file being assembled.
187 Enables or disables the generation of compressed instructions. Instructions
188 are opportunistically compressed by the RISC-V assembler when possible, but
189 sometimes this behavior is not desirable.
193 Enables or disables position-independent code generation. Unless you really
194 know what you're doing, this should only be at the top of a file.
198 Enables or disables relaxation. The RISC-V assembler and linker
199 opportunistically relax some code sequences, but sometimes this behavior is not
205 Enables or disables the CSR checking.
207 @cindex INSN directives
208 @item .insn @var{value}
209 @itemx .insn @var{value}
210 This directive permits the numeric representation of an instructions
211 and makes the assembler insert the operands according to one of the
212 instruction formats for @samp{.insn} (@ref{RISC-V-Formats}).
213 For example, the instruction @samp{add a0, a1, a2} could be written as
214 @samp{.insn r 0x33, 0, 0, a0, a1, a2}.
216 @cindex @code{.attribute} directive, RISC-V
217 @item .attribute @var{tag}, @var{value}
218 Set the object attribute @var{tag} to @var{value}.
220 The @var{tag} is either an attribute number, or one of the following:
221 @code{Tag_RISCV_arch}, @code{Tag_RISCV_stack_align},
222 @code{Tag_RISCV_unaligned_access}, @code{Tag_RISCV_priv_spec},
223 @code{Tag_RISCV_priv_spec_minor}, @code{Tag_RISCV_priv_spec_revision}.
227 @node RISC-V-Modifiers
228 @section RISC-V Assembler Modifiers
230 The RISC-V assembler supports following modifiers for relocatable addresses
231 used in RISC-V instruction operands. However, we also support some pseudo
232 instructions that are easier to use than these modifiers.
235 @item %lo(@var{symbol})
236 The low 12 bits of absolute address for @var{symbol}.
238 @item %hi(@var{symbol})
239 The high 20 bits of absolute address for @var{symbol}. This is usually
240 used with the %lo modifier to represent a 32-bit absolute address.
243 lui a0, %hi(@var{symbol}) // R_RISCV_HI20
244 addi a0, a0, %lo(@var{symbol}) // R_RISCV_LO12_I
246 lui a0, %hi(@var{symbol}) // R_RISCV_HI20
247 load/store a0, %lo(@var{symbol})(a0) // R_RISCV_LO12_I/S
250 @item %pcrel_lo(@var{label})
251 The low 12 bits of relative address between pc and @var{symbol}.
252 The @var{symbol} is related to the high part instruction which is marked
255 @item %pcrel_hi(@var{symbol})
256 The high 20 bits of relative address between pc and @var{symbol}.
257 This is usually used with the %pcrel_lo modifier to represent a +/-2GB
262 auipc a0, %pcrel_hi(@var{symbol}) // R_RISCV_PCREL_HI20
263 addi a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
266 auipc a0, %pcrel_hi(@var{symbol}) // R_RISCV_PCREL_HI20
267 load/store a0, %pcrel_lo(@var{label})(a0) // R_RISCV_PCREL_LO12_I/S
270 Or you can use the pseudo lla/lw/sw/... instruction to do this.
276 @item %got_pcrel_hi(@var{symbol})
277 The high 20 bits of relative address between pc and the GOT entry of
278 @var{symbol}. This is usually used with the %pcrel_lo modifier to access
283 auipc a0, %got_pcrel_hi(@var{symbol}) // R_RISCV_GOT_HI20
284 addi a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
287 auipc a0, %got_pcrel_hi(@var{symbol}) // R_RISCV_GOT_HI20
288 load/store a0, %pcrel_lo(@var{label})(a0) // R_RISCV_PCREL_LO12_I/S
291 Also, the pseudo la instruction with PIC has similar behavior.
293 @item %tprel_add(@var{symbol})
294 This is used purely to associate the R_RISCV_TPREL_ADD relocation for
295 TLS relaxation. This one is only valid as the fourth operand to the normally
296 3 operand add instruction.
298 @item %tprel_lo(@var{symbol})
299 The low 12 bits of relative address between tp and @var{symbol}.
301 @item %tprel_hi(@var{symbol})
302 The high 20 bits of relative address between tp and @var{symbol}. This is
303 usually used with the %tprel_lo and %tprel_add modifiers to access the thread
304 local variable @var{symbol} in TLS Local Exec.
307 lui a5, %tprel_hi(@var{symbol}) // R_RISCV_TPREL_HI20
308 add a5, a5, tp, %tprel_add(@var{symbol}) // R_RISCV_TPREL_ADD
309 load/store t0, %tprel_lo(@var{symbol})(a5) // R_RISCV_TPREL_LO12_I/S
312 @item %tls_ie_pcrel_hi(@var{symbol})
313 The high 20 bits of relative address between pc and GOT entry. It is
314 usually used with the %pcrel_lo modifier to access the thread local
315 variable @var{symbol} in TLS Initial Exec.
318 la.tls.ie a5, @var{symbol}
323 The pseudo la.tls.ie instruction can be expended to
327 auipc a5, %tls_ie_pcrel_hi(@var{symbol}) // R_RISCV_TLS_GOT_HI20
328 load a5, %pcrel_lo(@var{label})(a5) // R_RISCV_PCREL_LO12_I
331 @item %tls_gd_pcrel_hi(@var{symbol})
332 The high 20 bits of relative address between pc and GOT entry. It is
333 usually used with the %pcrel_lo modifier to access the thread local variable
334 @var{symbol} in TLS Global Dynamic.
337 la.tls.gd a0, @var{symbol}
338 call __tls_get_addr@@plt
343 The pseudo la.tls.gd instruction can be expended to
347 auipc a0, %tls_gd_pcrel_hi(@var{symbol}) // R_RISCV_TLS_GD_HI20
348 addi a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
354 @section RISC-V Instruction Formats
355 @cindex instruction formats, risc-v
356 @cindex RISC-V instruction formats
358 The RISC-V Instruction Set Manual Volume I: User-Level ISA lists 12
359 instruction formats where some of the formats have multiple variants.
360 For the @samp{.insn} pseudo directive the assembler recognizes some
362 Typically, the most general variant of the instruction format is used
363 by the @samp{.insn} directive.
365 The following table lists the abbreviations used in the table of
369 @multitable @columnfractions .15 .40
370 @item opcode @tab Unsigned immediate or opcode name for 7-bits opcode.
371 @item opcode2 @tab Unsigned immediate or opcode name for 2-bits opcode.
372 @item func7 @tab Unsigned immediate for 7-bits function code.
373 @item func6 @tab Unsigned immediate for 6-bits function code.
374 @item func4 @tab Unsigned immediate for 4-bits function code.
375 @item func3 @tab Unsigned immediate for 3-bits function code.
376 @item func2 @tab Unsigned immediate for 2-bits function code.
377 @item rd @tab Destination register number for operand x, can be GPR or FPR.
378 @item rd' @tab Destination register number for operand x,
379 only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
380 @item rs1 @tab First source register number for operand x, can be GPR or FPR.
381 @item rs1' @tab First source register number for operand x,
382 only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
383 @item rs2 @tab Second source register number for operand x, can be GPR or FPR.
384 @item rs2' @tab Second source register number for operand x,
385 only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
386 @item simm12 @tab Sign-extended 12-bit immediate for operand x.
387 @item simm20 @tab Sign-extended 20-bit immediate for operand x.
388 @item simm6 @tab Sign-extended 6-bit immediate for operand x.
389 @item uimm8 @tab Unsigned 8-bit immediate for operand x.
390 @item symbol @tab Symbol or lable reference for operand x.
394 The following table lists all available opcode name:
400 Opcode space for compressed instructions.
403 Opcode space for load instructions.
406 Opcode space for floating-point load instructions.
409 Opcode space for store instructions.
412 Opcode space for floating-point store instructions.
415 Opcode space for auipc instruction.
418 Opcode space for lui instruction.
421 Opcode space for branch instructions.
424 Opcode space for jal instruction.
427 Opcode space for jalr instruction.
430 Opcode space for ALU instructions.
433 Opcode space for 32-bits ALU instructions.
436 Opcode space for ALU with immediate instructions.
439 Opcode space for 32-bits ALU with immediate instructions.
442 Opcode space for floating-point operation instructions.
445 Opcode space for madd instruction.
448 Opcode space for msub instruction.
451 Opcode space for nmadd instruction.
454 Opcode space for msub instruction.
457 Opcode space for atomic memory operation instructions.
460 Opcode space for misc instructions.
463 Opcode space for system instructions.
469 Opcode space for customize instructions.
473 An instruction is two or four bytes in length and must be aligned
474 on a 2 byte boundary. The first two bits of the instruction specify the
475 length of the instruction, 00, 01 and 10 indicates a two byte instruction,
476 11 indicates a four byte instruction.
478 The following table lists the RISC-V instruction formats that are available
479 with the @samp{.insn} pseudo directive:
482 @item R type: .insn r opcode, func3, func7, rd, rs1, rs2
484 +-------+-----+-----+-------+----+-------------+
485 | func7 | rs2 | rs1 | func3 | rd | opcode |
486 +-------+-----+-----+-------+----+-------------+
490 @item R type with 4 register operands: .insn r opcode, func3, func2, rd, rs1, rs2, rs3
491 @itemx R4 type: .insn r4 opcode, func3, func2, rd, rs1, rs2, rs3
493 +-----+-------+-----+-----+-------+----+-------------+
494 | rs3 | func2 | rs2 | rs1 | func3 | rd | opcode |
495 +-----+-------+-----+-----+-------+----+-------------+
496 31 27 25 20 15 12 7 0
499 @item I type: .insn i opcode, func3, rd, rs1, simm12
500 @itemx I type: .insn i opcode, func3, rd, simm12(rs1)
502 +-------------+-----+-------+----+-------------+
503 | simm12 | rs1 | func3 | rd | opcode |
504 +-------------+-----+-------+----+-------------+
508 @item S type: .insn s opcode, func3, rs2, simm12(rs1)
510 +--------------+-----+-----+-------+-------------+-------------+
511 | simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode |
512 +--------------+-----+-----+-------+-------------+-------------+
516 @item B type: .insn s opcode, func3, rs1, rs2, symbol
517 @itemx SB type: .insn sb opcode, func3, rs1, rs2, symbol
519 +------------+--------------+-----+-----+-------+-------------+-------------+--------+
520 | simm12[12] | simm12[10:5] | rs2 | rs1 | func3 | simm12[4:1] | simm12[11]] | opcode |
521 +------------+--------------+-----+-----+-------+-------------+-------------+--------+
522 31 30 25 20 15 12 7 0
525 @item U type: .insn u opcode, rd, simm20
527 +---------------------------+----+-------------+
528 | simm20 | rd | opcode |
529 +---------------------------+----+-------------+
533 @item J type: .insn j opcode, rd, symbol
534 @itemx UJ type: .insn uj opcode, rd, symbol
536 +------------+--------------+------------+---------------+----+-------------+
537 | simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode |
538 +------------+--------------+------------+---------------+----+-------------+
542 @item CR type: .insn cr opcode2, func4, rd, rs2
544 +---------+--------+-----+---------+
545 | func4 | rd/rs1 | rs2 | opcode2 |
546 +---------+--------+-----+---------+
550 @item CI type: .insn ci opcode2, func3, rd, simm6
552 +---------+-----+--------+-----+---------+
553 | func3 | imm | rd/rs1 | imm | opcode2 |
554 +---------+-----+--------+-----+---------+
558 @item CIW type: .insn ciw opcode2, func3, rd, uimm8
560 +---------+--------------+-----+---------+
561 | func3 | imm | rd' | opcode2 |
562 +---------+--------------+-----+---------+
566 @item CA type: .insn ca opcode2, func6, func2, rd, rs2
568 +---------+----------+-------+------+--------+
569 | func6 | rd'/rs1' | func2 | rs2' | opcode |
570 +---------+----------+-------+------+--------+
574 @item CB type: .insn cb opcode2, func3, rs1, symbol
576 +---------+--------+------+--------+---------+
577 | func3 | offset | rs1' | offset | opcode2 |
578 +---------+--------+------+--------+---------+
582 @item CJ type: .insn cj opcode2, symbol
584 +---------+--------------------+---------+
585 | func3 | jump target | opcode2 |
586 +---------+--------------------+---------+
593 For the complete list of all instruction format variants see
594 The RISC-V Instruction Set Manual Volume I: User-Level ISA.
596 @node RISC-V-ATTRIBUTE
597 @section RISC-V Object Attribute
598 @cindex Object Attribute, RISC-V
600 RISC-V attributes have a string value if the tag number is odd and an integer
601 value if the tag number is even.
604 @item Tag_RISCV_stack_align (4)
605 Tag_RISCV_strict_align records the N-byte stack alignment for this object. The
606 default value is 16 for RV32I or RV64I, and 4 for RV32E.
608 The smallest value will be used if object files with different
609 Tag_RISCV_stack_align values are merged.
611 @item Tag_RISCV_arch (5)
612 Tag_RISCV_arch contains a string for the target architecture taken from the
613 option @option{-march}. Different architectures will be integrated into a
614 superset when object files are merged.
616 Note that the version information of the target architecture must be presented
617 explicitly in the attribute and abbreviations must be expanded. The version
618 information, if not given by @option{-march}, must be in accordance with the
619 default specified by the tool. For example, the architecture @code{RV32I} has
620 to be recorded in the attribute as @code{RV32I2P0} in which @code{2P0} stands
621 for the default version of its base ISA. On the other hand, the architecture
622 @code{RV32G} has to be presented as @code{RV32I2P0_M2P0_A2P0_F2P0_D2P0} in
623 which the abbreviation @code{G} is expanded to the @code{IMAFD} combination
624 with default versions of the standard extensions.
626 @item Tag_RISCV_unaligned_access (6)
627 Tag_RISCV_unaligned_access is 0 for files that do not allow any unaligned
628 memory accesses, and 1 for files that do allow unaligned memory accesses.
630 @item Tag_RISCV_priv_spec (8)
631 @item Tag_RISCV_priv_spec_minor (10)
632 @item Tag_RISCV_priv_spec_revision (12)
633 Tag_RISCV_priv_spec contains the major/minor/revision version information of
634 the privileged specification. It will report errors if object files of
635 different privileged specification versions are merged.