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
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
24 @section RISC-V Options
26 The following table lists all available RISC-V specific options.
31 @cindex @samp{-fpic} option, RISC-V
34 Generate position-independent code
36 @cindex @samp{-fno-pic} option, RISC-V
38 Don't generate position-independent code (default)
40 @cindex @samp{-march=ISA} option, RISC-V
42 Select the base isa, as specified by ISA. For example -march=rv32ima.
44 @cindex @samp{-mabi=ABI} option, RISC-V
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.
51 @cindex @samp{-mrelax} option, RISC-V
53 Take advantage of linker relaxations to reduce the number of instructions
54 required to materialize symbol addresses. (default)
56 @cindex @samp{-mno-relax} option, RISC-V
58 Don't do linker relaxations.
63 @node RISC-V-Directives
64 @section RISC-V Directives
65 @cindex machine directives, RISC-V
66 @cindex RISC-V machine directives
68 The following table lists all available RISC-V specific directives.
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
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.
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.
92 Sets the current section to the BSS section.
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
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
114 la gp, __global_pointer$
118 in order to produce after linker relaxation the expected
121 auipc gp, %pcrel_hi(__global_pointer$)
122 addi gp, gp, %pcrel_lo(__global_pointer$)
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:
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.
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.
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.
156 Enables or disables relaxation. The RISC-V assembler and linker
157 opportunistically relax some code sequences, but sometimes this behavior is not
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}.
173 @section Instruction Formats
174 @cindex instruction formats, risc-v
175 @cindex RISC-V instruction formats
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
181 Typically, the most general variant of the instruction format is used
182 by the @samp{.insn} directive.
184 The following table lists the abbreviations used in the table of
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.
212 The following table lists all available opcode name:
218 Opcode space for compressed instructions.
221 Opcode space for load instructions.
224 Opcode space for floating-point load instructions.
227 Opcode space for store instructions.
230 Opcode space for floating-point store instructions.
233 Opcode space for auipc instruction.
236 Opcode space for lui instruction.
239 Opcode space for branch instructions.
242 Opcode space for jal instruction.
245 Opcode space for jalr instruction.
248 Opcode space for ALU instructions.
251 Opcode space for 32-bits ALU instructions.
254 Opcode space for ALU with immediate instructions.
257 Opcode space for 32-bits ALU with immediate instructions.
260 Opcode space for floating-point operation instructions.
263 Opcode space for madd instruction.
266 Opcode space for msub instruction.
269 Opcode space for nmadd instruction.
272 Opcode space for msub instruction.
275 Opcode space for atomic memory operation instructions.
278 Opcode space for misc instructions.
281 Opcode space for system instructions.
287 Opcode space for customize instructions.
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.
296 The following table lists the RISC-V instruction formats that are available
297 with the @samp{.insn} pseudo directive:
300 @item R type: .insn r opcode, func3, func7, rd, rs1, rs2
302 +-------+-----+-----+-------+----+-------------+
303 | func7 | rs2 | rs1 | func3 | rd | opcode |
304 +-------+-----+-----+-------+----+-------------+
308 @item R type with 4 register operands: .insn r opcode, func3, func2, rd, rs1, rs2, rs3
310 +-----+-------+-----+-----+-------+----+-------------+
311 | rs3 | func2 | rs2 | rs1 | func3 | rd | opcode |
312 +-----+-------+-----+-----+-------+----+-------------+
313 31 27 25 20 15 12 7 0
316 @item I type: .insn i opcode, func3, rd, rs1, simm12
318 +-------------+-----+-------+----+-------------+
319 | simm12 | rs1 | func3 | rd | opcode |
320 +-------------+-----+-------+----+-------------+
324 @item S type: .insn s opcode, func3, rd, rs1, simm12
326 +--------------+-----+-----+-------+-------------+-------------+
327 | simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode |
328 +--------------+-----+-----+-------+-------------+-------------+
332 @item SB type: .insn sb opcode, func3, rd, rs1, symbol
333 @itemx SB type: .insn sb opcode, func3, rd, simm12(rs1)
335 +--------------+-----+-----+-------+-------------+-------------+
336 | simm21[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode |
337 +--------------+-----+-----+-------+-------------+-------------+
341 @item U type: .insn u opcode, rd, simm20
343 +---------------------------+----+-------------+
344 | simm20 | rd | opcode |
345 +---------------------------+----+-------------+
349 @item UJ type: .insn uj opcode, rd, symbol
351 +------------+--------------+------------+---------------+----+-------------+
352 | simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode |
353 +------------+--------------+------------+---------------+----+-------------+
357 @item CR type: .insn cr opcode2, func4, rd, rs1
359 +---------+--------+-----+---------+
360 | func4 | rd/rs1 | rs2 | opcode2 |
361 +---------+--------+-----+---------+
365 @item CI type: .insn ci opcode2, func3, rd, simm6
367 +---------+-----+--------+-----+---------+
368 | func3 | imm | rd/rs1 | imm | opcode2 |
369 +---------+-----+--------+-----+---------+
373 @item CIW type: .insn ciw opcode2, func3, rd, uimm8
375 +---------+--------------+-----+---------+
376 | func3 | imm | rd' | opcode2 |
377 +---------+--------------+-----+---------+
381 @item CB type: .insn cb opcode2, func3, rs1, symbol
383 +---------+--------+------+--------+---------+
384 | func3 | offset | rs1' | offset | opcode2 |
385 +---------+--------+------+--------+---------+
389 @item CJ type: .insn cj opcode2, symbol
391 +---------+--------------------+---------+
392 | func3 | jump target | opcode2 |
393 +---------+--------------------+---------+
400 For the complete list of all instruction format variants see
401 The RISC-V Instruction Set Manual Volume I: User-Level ISA.