Commit | Line | Data |
---|---|---|
b3adc24a | 1 | @c Copyright (C) 2016-2020 Free Software Foundation, Inc. |
e23eba97 NC |
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 | |
b57e49f7 JW |
18 | * RISC-V-Options:: RISC-V Options |
19 | * RISC-V-Directives:: RISC-V Directives | |
0e35537d | 20 | * RISC-V-Formats:: RISC-V Instruction Formats |
2dc8dd17 | 21 | * RISC-V-ATTRIBUTE:: RISC-V Object Attribute |
e23eba97 NC |
22 | @end menu |
23 | ||
b57e49f7 JW |
24 | @node RISC-V-Options |
25 | @section RISC-V Options | |
e23eba97 | 26 | |
b57e49f7 | 27 | The following table lists all available RISC-V specific options. |
e23eba97 NC |
28 | |
29 | @c man begin OPTIONS | |
30 | @table @gcctabopt | |
e23eba97 | 31 | |
19683c04 PD |
32 | @cindex @samp{-fpic} option, RISC-V |
33 | @item -fpic | |
b57e49f7 | 34 | @itemx -fPIC |
19683c04 PD |
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 | ||
4f7eddc4 PD |
41 | @cindex @samp{-march=ISA} option, RISC-V |
42 | @item -march=ISA | |
2922d21d AW |
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 | |
7f999549 JW |
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. | |
e23eba97 | 52 | |
71060565 JW |
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 | ||
bd3380bc NC |
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 | ||
2ca89224 NC |
76 | @cindex @samp{-mcsr-check} option, RISC-V |
77 | @item -mcsr-check | |
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. | |
81 | ||
82 | @cindex @samp{-mno-csr-check} option, RISC-V | |
83 | @item -mno-csr-check | |
84 | Don't do CSR cheching. | |
e23eba97 NC |
85 | @end table |
86 | @c man end | |
b57e49f7 JW |
87 | |
88 | @node RISC-V-Directives | |
fed44c60 | 89 | @section RISC-V Directives |
b57e49f7 JW |
90 | @cindex machine directives, RISC-V |
91 | @cindex RISC-V machine directives | |
92 | ||
b57e49f7 JW |
93 | The following table lists all available RISC-V specific directives. |
94 | ||
95 | @table @code | |
96 | ||
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 | |
100 | align to. | |
101 | ||
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. | |
107 | ||
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. | |
114 | ||
115 | @cindex BSS directive | |
116 | @item .bss | |
117 | Sets the current section to the BSS section. | |
118 | ||
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 | |
125 | time. | |
126 | ||
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 | |
135 | ||
136 | @smallexample | |
137 | .option push | |
138 | .option norelax | |
139 | la gp, __global_pointer$ | |
140 | .option pop | |
141 | @end smallexample | |
142 | ||
143 | in order to produce after linker relaxation the expected | |
144 | ||
145 | @smallexample | |
146 | auipc gp, %pcrel_hi(__global_pointer$) | |
147 | addi gp, gp, %pcrel_lo(__global_pointer$) | |
148 | @end smallexample | |
149 | ||
150 | instead of just | |
151 | ||
152 | @smallexample | |
153 | addi gp, gp, 0 | |
154 | @end smallexample | |
155 | ||
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: | |
160 | ||
161 | @table @code | |
162 | @item push | |
163 | @itemx pop | |
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. | |
167 | ||
168 | @item rvc | |
169 | @itemx norvc | |
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. | |
173 | ||
174 | @item pic | |
175 | @itemx nopic | |
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. | |
178 | ||
179 | @item relax | |
180 | @itemx norelax | |
181 | Enables or disables relaxation. The RISC-V assembler and linker | |
182 | opportunistically relax some code sequences, but sometimes this behavior is not | |
183 | desirable. | |
184 | @end table | |
185 | ||
2ca89224 NC |
186 | @item csr-check |
187 | @itemx no-csr-check | |
188 | Enables or disables the CSR checking. | |
189 | ||
0e35537d JW |
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}. | |
198 | ||
2dc8dd17 JW |
199 | @cindex @code{.attribute} directive, RISC-V |
200 | @item .attribute @var{tag}, @var{value} | |
201 | Set the object attribute @var{tag} to @var{value}. | |
202 | ||
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}. | |
207 | ||
b57e49f7 | 208 | @end table |
0e35537d JW |
209 | |
210 | @node RISC-V-Formats | |
211 | @section Instruction Formats | |
212 | @cindex instruction formats, risc-v | |
213 | @cindex RISC-V instruction formats | |
214 | ||
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 | |
218 | of the formats. | |
219 | Typically, the most general variant of the instruction format is used | |
220 | by the @samp{.insn} directive. | |
221 | ||
222 | The following table lists the abbreviations used in the table of | |
223 | instruction formats: | |
224 | ||
225 | @display | |
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. | |
4765cd61 | 230 | @item func6 @tab Unsigned immediate for 6-bits function code. |
0e35537d JW |
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. | |
248 | @end multitable | |
249 | @end display | |
250 | ||
251 | The following table lists all available opcode name: | |
252 | ||
253 | @table @code | |
254 | @item C0 | |
255 | @item C1 | |
256 | @item C2 | |
257 | Opcode space for compressed instructions. | |
258 | ||
259 | @item LOAD | |
260 | Opcode space for load instructions. | |
261 | ||
262 | @item LOAD_FP | |
263 | Opcode space for floating-point load instructions. | |
264 | ||
265 | @item STORE | |
266 | Opcode space for store instructions. | |
267 | ||
268 | @item STORE_FP | |
269 | Opcode space for floating-point store instructions. | |
270 | ||
271 | @item AUIPC | |
272 | Opcode space for auipc instruction. | |
273 | ||
274 | @item LUI | |
275 | Opcode space for lui instruction. | |
276 | ||
277 | @item BRANCH | |
278 | Opcode space for branch instructions. | |
279 | ||
280 | @item JAL | |
281 | Opcode space for jal instruction. | |
282 | ||
283 | @item JALR | |
284 | Opcode space for jalr instruction. | |
285 | ||
286 | @item OP | |
287 | Opcode space for ALU instructions. | |
288 | ||
289 | @item OP_32 | |
290 | Opcode space for 32-bits ALU instructions. | |
291 | ||
292 | @item OP_IMM | |
293 | Opcode space for ALU with immediate instructions. | |
294 | ||
295 | @item OP_IMM_32 | |
296 | Opcode space for 32-bits ALU with immediate instructions. | |
297 | ||
298 | @item OP_FP | |
299 | Opcode space for floating-point operation instructions. | |
300 | ||
301 | @item MADD | |
302 | Opcode space for madd instruction. | |
303 | ||
304 | @item MSUB | |
305 | Opcode space for msub instruction. | |
306 | ||
307 | @item NMADD | |
308 | Opcode space for nmadd instruction. | |
309 | ||
310 | @item NMSUB | |
311 | Opcode space for msub instruction. | |
312 | ||
313 | @item AMO | |
314 | Opcode space for atomic memory operation instructions. | |
315 | ||
98602811 | 316 | @item MISC_MEM |
0e35537d JW |
317 | Opcode space for misc instructions. |
318 | ||
319 | @item SYSTEM | |
320 | Opcode space for system instructions. | |
321 | ||
322 | @item CUSTOM_0 | |
323 | @item CUSTOM_1 | |
324 | @item CUSTOM_2 | |
325 | @item CUSTOM_3 | |
326 | Opcode space for customize instructions. | |
327 | ||
328 | @end table | |
329 | ||
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. | |
334 | ||
335 | The following table lists the RISC-V instruction formats that are available | |
336 | with the @samp{.insn} pseudo directive: | |
337 | ||
338 | @table @code | |
339 | @item R type: .insn r opcode, func3, func7, rd, rs1, rs2 | |
340 | @verbatim | |
341 | +-------+-----+-----+-------+----+-------------+ | |
342 | | func7 | rs2 | rs1 | func3 | rd | opcode | | |
343 | +-------+-----+-----+-------+----+-------------+ | |
344 | 31 25 20 15 12 7 0 | |
345 | @end verbatim | |
346 | ||
347 | @item R type with 4 register operands: .insn r opcode, func3, func2, rd, rs1, rs2, rs3 | |
98602811 | 348 | @itemx R4 type: .insn r4 opcode, func3, func2, rd, rs1, rs2, rs3 |
0e35537d JW |
349 | @verbatim |
350 | +-----+-------+-----+-----+-------+----+-------------+ | |
351 | | rs3 | func2 | rs2 | rs1 | func3 | rd | opcode | | |
352 | +-----+-------+-----+-----+-------+----+-------------+ | |
353 | 31 27 25 20 15 12 7 0 | |
354 | @end verbatim | |
355 | ||
356 | @item I type: .insn i opcode, func3, rd, rs1, simm12 | |
357 | @verbatim | |
358 | +-------------+-----+-------+----+-------------+ | |
359 | | simm12 | rs1 | func3 | rd | opcode | | |
360 | +-------------+-----+-------+----+-------------+ | |
361 | 31 20 15 12 7 0 | |
362 | @end verbatim | |
363 | ||
364 | @item S type: .insn s opcode, func3, rd, rs1, simm12 | |
365 | @verbatim | |
366 | +--------------+-----+-----+-------+-------------+-------------+ | |
367 | | simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode | | |
368 | +--------------+-----+-----+-------+-------------+-------------+ | |
369 | 31 25 20 15 12 7 0 | |
370 | @end verbatim | |
371 | ||
372 | @item SB type: .insn sb opcode, func3, rd, rs1, symbol | |
373 | @itemx SB type: .insn sb opcode, func3, rd, simm12(rs1) | |
98602811 JW |
374 | @itemx B type: .insn s opcode, func3, rd, rs1, symbol |
375 | @itemx B type: .insn s opcode, func3, rd, simm12(rs1) | |
0e35537d | 376 | @verbatim |
98602811 JW |
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 | |
0e35537d JW |
381 | @end verbatim |
382 | ||
383 | @item U type: .insn u opcode, rd, simm20 | |
384 | @verbatim | |
385 | +---------------------------+----+-------------+ | |
386 | | simm20 | rd | opcode | | |
387 | +---------------------------+----+-------------+ | |
388 | 31 12 7 0 | |
389 | @end verbatim | |
390 | ||
391 | @item UJ type: .insn uj opcode, rd, symbol | |
98602811 | 392 | @itemx J type: .insn j opcode, rd, symbol |
0e35537d JW |
393 | @verbatim |
394 | +------------+--------------+------------+---------------+----+-------------+ | |
395 | | simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode | | |
396 | +------------+--------------+------------+---------------+----+-------------+ | |
397 | 31 30 21 20 12 7 0 | |
398 | @end verbatim | |
399 | ||
4765cd61 | 400 | @item CR type: .insn cr opcode2, func4, rd, rs2 |
0e35537d JW |
401 | @verbatim |
402 | +---------+--------+-----+---------+ | |
403 | | func4 | rd/rs1 | rs2 | opcode2 | | |
404 | +---------+--------+-----+---------+ | |
405 | 15 12 7 2 0 | |
406 | @end verbatim | |
407 | ||
408 | @item CI type: .insn ci opcode2, func3, rd, simm6 | |
409 | @verbatim | |
410 | +---------+-----+--------+-----+---------+ | |
411 | | func3 | imm | rd/rs1 | imm | opcode2 | | |
412 | +---------+-----+--------+-----+---------+ | |
413 | 15 13 12 7 2 0 | |
414 | @end verbatim | |
415 | ||
416 | @item CIW type: .insn ciw opcode2, func3, rd, uimm8 | |
417 | @verbatim | |
418 | +---------+--------------+-----+---------+ | |
419 | | func3 | imm | rd' | opcode2 | | |
420 | +---------+--------------+-----+---------+ | |
421 | 15 13 7 2 0 | |
422 | @end verbatim | |
423 | ||
4765cd61 JW |
424 | @item CA type: .insn ca opcode2, func6, func2, rd, rs2 |
425 | @verbatim | |
426 | +---------+----------+-------+------+--------+ | |
427 | | func6 | rd'/rs1' | func2 | rs2' | opcode | | |
428 | +---------+----------+-------+------+--------+ | |
429 | 15 10 7 5 2 0 | |
430 | @end verbatim | |
431 | ||
0e35537d JW |
432 | @item CB type: .insn cb opcode2, func3, rs1, symbol |
433 | @verbatim | |
434 | +---------+--------+------+--------+---------+ | |
435 | | func3 | offset | rs1' | offset | opcode2 | | |
436 | +---------+--------+------+--------+---------+ | |
437 | 15 13 10 7 2 0 | |
438 | @end verbatim | |
439 | ||
440 | @item CJ type: .insn cj opcode2, symbol | |
441 | @verbatim | |
442 | +---------+--------------------+---------+ | |
443 | | func3 | jump target | opcode2 | | |
444 | +---------+--------------------+---------+ | |
445 | 15 13 7 2 0 | |
446 | @end verbatim | |
447 | ||
448 | ||
449 | @end table | |
450 | ||
451 | For the complete list of all instruction format variants see | |
452 | The RISC-V Instruction Set Manual Volume I: User-Level ISA. | |
2dc8dd17 JW |
453 | |
454 | @node RISC-V-ATTRIBUTE | |
455 | @section RISC-V Object Attribute | |
456 | @cindex Object Attribute, RISC-V | |
457 | ||
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. | |
460 | ||
461 | @table @r | |
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. | |
465 | ||
466 | The smallest value will be used if object files with different | |
467 | Tag_RISCV_stack_align values are merged. | |
468 | ||
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. | |
473 | ||
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. | |
483 | ||
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. | |
487 | ||
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. | |
494 | ||
495 | @end table |