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-Formats:: RISC-V Instruction Formats
21 * RISC-V-ATTRIBUTE:: RISC-V Object Attribute
25 @section RISC-V Options
27 The following table lists all available RISC-V specific options.
32 @cindex @samp{-fpic} option, RISC-V
35 Generate position-independent code
37 @cindex @samp{-fno-pic} option, RISC-V
39 Don't generate position-independent code (default)
41 @cindex @samp{-march=ISA} option, RISC-V
43 Select the base isa, as specified by ISA. For example -march=rv32ima.
45 @cindex @samp{-mabi=ABI} option, RISC-V
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.
53 @cindex @samp{-mrelax} option, RISC-V
55 Take advantage of linker relaxations to reduce the number of instructions
56 required to materialize symbol addresses. (default)
58 @cindex @samp{-mno-relax} option, RISC-V
60 Don't do linker relaxations.
62 @cindex @samp{-march-attr} option, RISC-V
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
71 @cindex @samp{-mno-arch-attr} option, RISC-V
73 Don't generate the default riscv elf attribute section if the .attribute
74 directives are not set.
76 @cindex @samp{-mcsr-check} option, RISC-V
78 Enable the CSR checking for the ISA-dependent CRS and the read-only CSR.
79 The ISA-dependent CSR are only valid when the specific ISA is set. The
80 read-only CSR can not be written by the CSR instructions.
82 @cindex @samp{-mno-csr-check} option, RISC-V
84 Don't do CSR cheching.
88 @node RISC-V-Directives
89 @section RISC-V Directives
90 @cindex machine directives, RISC-V
91 @cindex RISC-V machine directives
93 The following table lists all available RISC-V specific directives.
97 @cindex @code{align} directive
98 @item .align @var{size-log-2}
99 Align to the given boundary, with the size given as log2 the number of bytes to
102 @cindex Data directives
103 @item .half @var{value}
104 @itemx .word @var{value}
105 @itemx .dword @var{value}
106 Emits a half-word, word, or double-word value at the current position.
108 @cindex DTP-relative data directives
109 @item .dtprelword @var{value}
110 @itemx .dtpreldword @var{value}
111 Emits a DTP-relative word (or double-word) at the current position. This is
112 meant to be used by the compiler in shared libraries for DWARF debug info for
113 thread local variables.
115 @cindex BSS directive
117 Sets the current section to the BSS section.
119 @cindex LEB128 directives
120 @item .uleb128 @var{value}
121 @itemx .sleb128 @var{value}
122 Emits a signed or unsigned LEB128 value at the current position. This only
123 accepts constant expressions, because symbol addresses can change with
124 relaxation, and we don't support relocations to modify LEB128 values at link
127 @cindex Option directive
128 @cindex @code{option} directive
129 @item .option @var{argument}
130 Modifies RISC-V specific assembler options inline with the assembly code.
131 This is used when particular instruction sequences must be assembled with a
132 specific set of options. For example, since we relax addressing sequences to
133 shorter GP-relative sequences when possible the initial load of GP must not be
134 relaxed and should be emitted as something like
139 la gp, __global_pointer$
143 in order to produce after linker relaxation the expected
146 auipc gp, %pcrel_hi(__global_pointer$)
147 addi gp, gp, %pcrel_lo(__global_pointer$)
156 It's not expected that options are changed in this manner during regular use,
157 but there are a handful of esoteric cases like the one above where users need
158 to disable particular features of the assembler for particular code sequences.
159 The complete list of option arguments is shown below:
164 Pushes or pops the current option stack. These should be used whenever
165 changing an option in line with assembly code in order to ensure the user's
166 command-line options are respected for the bulk of the file being assembled.
170 Enables or disables the generation of compressed instructions. Instructions
171 are opportunistically compressed by the RISC-V assembler when possible, but
172 sometimes this behavior is not desirable.
176 Enables or disables position-independent code generation. Unless you really
177 know what you're doing, this should only be at the top of a file.
181 Enables or disables relaxation. The RISC-V assembler and linker
182 opportunistically relax some code sequences, but sometimes this behavior is not
188 Enables or disables the CSR checking.
190 @cindex INSN directives
191 @item .insn @var{value}
192 @itemx .insn @var{value}
193 This directive permits the numeric representation of an instructions
194 and makes the assembler insert the operands according to one of the
195 instruction formats for @samp{.insn} (@ref{RISC-V-Formats}).
196 For example, the instruction @samp{add a0, a1, a2} could be written as
197 @samp{.insn r 0x33, 0, 0, a0, a1, a2}.
199 @cindex @code{.attribute} directive, RISC-V
200 @item .attribute @var{tag}, @var{value}
201 Set the object attribute @var{tag} to @var{value}.
203 The @var{tag} is either an attribute number, or one of the following:
204 @code{Tag_RISCV_arch}, @code{Tag_RISCV_stack_align},
205 @code{Tag_RISCV_unaligned_access}, @code{Tag_RISCV_priv_spec},
206 @code{Tag_RISCV_priv_spec_minor}, @code{Tag_RISCV_priv_spec_revision}.
211 @section Instruction Formats
212 @cindex instruction formats, risc-v
213 @cindex RISC-V instruction formats
215 The RISC-V Instruction Set Manual Volume I: User-Level ISA lists 12
216 instruction formats where some of the formats have multiple variants.
217 For the @samp{.insn} pseudo directive the assembler recognizes some
219 Typically, the most general variant of the instruction format is used
220 by the @samp{.insn} directive.
222 The following table lists the abbreviations used in the table of
226 @multitable @columnfractions .15 .40
227 @item opcode @tab Unsigned immediate or opcode name for 7-bits opcode.
228 @item opcode2 @tab Unsigned immediate or opcode name for 2-bits opcode.
229 @item func7 @tab Unsigned immediate for 7-bits function code.
230 @item func6 @tab Unsigned immediate for 6-bits function code.
231 @item func4 @tab Unsigned immediate for 4-bits function code.
232 @item func3 @tab Unsigned immediate for 3-bits function code.
233 @item func2 @tab Unsigned immediate for 2-bits function code.
234 @item rd @tab Destination register number for operand x, can be GPR or FPR.
235 @item rd' @tab Destination register number for operand x,
236 only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
237 @item rs1 @tab First source register number for operand x, can be GPR or FPR.
238 @item rs1' @tab First source register number for operand x,
239 only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
240 @item rs2 @tab Second source register number for operand x, can be GPR or FPR.
241 @item rs2' @tab Second source register number for operand x,
242 only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
243 @item simm12 @tab Sign-extended 12-bit immediate for operand x.
244 @item simm20 @tab Sign-extended 20-bit immediate for operand x.
245 @item simm6 @tab Sign-extended 6-bit immediate for operand x.
246 @item uimm8 @tab Unsigned 8-bit immediate for operand x.
247 @item symbol @tab Symbol or lable reference for operand x.
251 The following table lists all available opcode name:
257 Opcode space for compressed instructions.
260 Opcode space for load instructions.
263 Opcode space for floating-point load instructions.
266 Opcode space for store instructions.
269 Opcode space for floating-point store instructions.
272 Opcode space for auipc instruction.
275 Opcode space for lui instruction.
278 Opcode space for branch instructions.
281 Opcode space for jal instruction.
284 Opcode space for jalr instruction.
287 Opcode space for ALU instructions.
290 Opcode space for 32-bits ALU instructions.
293 Opcode space for ALU with immediate instructions.
296 Opcode space for 32-bits ALU with immediate instructions.
299 Opcode space for floating-point operation instructions.
302 Opcode space for madd instruction.
305 Opcode space for msub instruction.
308 Opcode space for nmadd instruction.
311 Opcode space for msub instruction.
314 Opcode space for atomic memory operation instructions.
317 Opcode space for misc instructions.
320 Opcode space for system instructions.
326 Opcode space for customize instructions.
330 An instruction is two or four bytes in length and must be aligned
331 on a 2 byte boundary. The first two bits of the instruction specify the
332 length of the instruction, 00, 01 and 10 indicates a two byte instruction,
333 11 indicates a four byte instruction.
335 The following table lists the RISC-V instruction formats that are available
336 with the @samp{.insn} pseudo directive:
339 @item R type: .insn r opcode, func3, func7, rd, rs1, rs2
341 +-------+-----+-----+-------+----+-------------+
342 | func7 | rs2 | rs1 | func3 | rd | opcode |
343 +-------+-----+-----+-------+----+-------------+
347 @item R type with 4 register operands: .insn r opcode, func3, func2, rd, rs1, rs2, rs3
348 @itemx R4 type: .insn r4 opcode, func3, func2, rd, rs1, rs2, rs3
350 +-----+-------+-----+-----+-------+----+-------------+
351 | rs3 | func2 | rs2 | rs1 | func3 | rd | opcode |
352 +-----+-------+-----+-----+-------+----+-------------+
353 31 27 25 20 15 12 7 0
356 @item I type: .insn i opcode, func3, rd, rs1, simm12
358 +-------------+-----+-------+----+-------------+
359 | simm12 | rs1 | func3 | rd | opcode |
360 +-------------+-----+-------+----+-------------+
364 @item S type: .insn s opcode, func3, rd, rs1, simm12
366 +--------------+-----+-----+-------+-------------+-------------+
367 | simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode |
368 +--------------+-----+-----+-------+-------------+-------------+
372 @item SB type: .insn sb opcode, func3, rd, rs1, symbol
373 @itemx SB type: .insn sb opcode, func3, rd, simm12(rs1)
374 @itemx B type: .insn s opcode, func3, rd, rs1, symbol
375 @itemx B type: .insn s opcode, func3, rd, simm12(rs1)
377 +------------+--------------+-----+-----+-------+-------------+-------------+--------+
378 | simm12[12] | simm12[10:5] | rs2 | rs1 | func3 | simm12[4:1] | simm12[11]] | opcode |
379 +------------+--------------+-----+-----+-------+-------------+-------------+--------+
380 31 30 25 20 15 12 7 0
383 @item U type: .insn u opcode, rd, simm20
385 +---------------------------+----+-------------+
386 | simm20 | rd | opcode |
387 +---------------------------+----+-------------+
391 @item UJ type: .insn uj opcode, rd, symbol
392 @itemx J type: .insn j opcode, rd, symbol
394 +------------+--------------+------------+---------------+----+-------------+
395 | simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode |
396 +------------+--------------+------------+---------------+----+-------------+
400 @item CR type: .insn cr opcode2, func4, rd, rs2
402 +---------+--------+-----+---------+
403 | func4 | rd/rs1 | rs2 | opcode2 |
404 +---------+--------+-----+---------+
408 @item CI type: .insn ci opcode2, func3, rd, simm6
410 +---------+-----+--------+-----+---------+
411 | func3 | imm | rd/rs1 | imm | opcode2 |
412 +---------+-----+--------+-----+---------+
416 @item CIW type: .insn ciw opcode2, func3, rd, uimm8
418 +---------+--------------+-----+---------+
419 | func3 | imm | rd' | opcode2 |
420 +---------+--------------+-----+---------+
424 @item CA type: .insn ca opcode2, func6, func2, rd, rs2
426 +---------+----------+-------+------+--------+
427 | func6 | rd'/rs1' | func2 | rs2' | opcode |
428 +---------+----------+-------+------+--------+
432 @item CB type: .insn cb opcode2, func3, rs1, symbol
434 +---------+--------+------+--------+---------+
435 | func3 | offset | rs1' | offset | opcode2 |
436 +---------+--------+------+--------+---------+
440 @item CJ type: .insn cj opcode2, symbol
442 +---------+--------------------+---------+
443 | func3 | jump target | opcode2 |
444 +---------+--------------------+---------+
451 For the complete list of all instruction format variants see
452 The RISC-V Instruction Set Manual Volume I: User-Level ISA.
454 @node RISC-V-ATTRIBUTE
455 @section RISC-V Object Attribute
456 @cindex Object Attribute, RISC-V
458 RISC-V attributes have a string value if the tag number is odd and an integer
459 value if the tag number is even.
462 @item Tag_RISCV_stack_align (4)
463 Tag_RISCV_strict_align records the N-byte stack alignment for this object. The
464 default value is 16 for RV32I or RV64I, and 4 for RV32E.
466 The smallest value will be used if object files with different
467 Tag_RISCV_stack_align values are merged.
469 @item Tag_RISCV_arch (5)
470 Tag_RISCV_arch contains a string for the target architecture taken from the
471 option @option{-march}. Different architectures will be integrated into a
472 superset when object files are merged.
474 Note that the version information of the target architecture must be presented
475 explicitly in the attribute and abbreviations must be expanded. The version
476 information, if not given by @option{-march}, must be in accordance with the
477 default specified by the tool. For example, the architecture @code{RV32I} has
478 to be recorded in the attribute as @code{RV32I2P0} in which @code{2P0} stands
479 for the default version of its base ISA. On the other hand, the architecture
480 @code{RV32G} has to be presented as @code{RV32I2P0_M2P0_A2P0_F2P0_D2P0} in
481 which the abbreviation @code{G} is expanded to the @code{IMAFD} combination
482 with default versions of the standard extensions.
484 @item Tag_RISCV_unaligned_access (6)
485 Tag_RISCV_unaligned_access is 0 for files that do not allow any unaligned
486 memory accesses, and 1 for files that do allow unaligned memory accesses.
488 @item Tag_RISCV_priv_spec (8)
489 @item Tag_RISCV_priv_spec_minor (10)
490 @item Tag_RISCV_priv_spec_revision (12)
491 Tag_RISCV_priv_spec contains the major/minor/revision version information of
492 the privileged specification. It will report errors if object files of
493 different privileged specification versions are merged.