-@c Copyright (C) 2016-2017 Free Software Foundation, Inc.
+@c Copyright (C) 2016-2020 Free Software Foundation, Inc.
@c This is part of the GAS anual.
@c For copying conditions, see the file as.texinfo
@c man end
@menu
* RISC-V-Options:: RISC-V Options
* RISC-V-Directives:: RISC-V Directives
+* RISC-V-Modifiers:: RISC-V Assembler Modifiers
+* RISC-V-Formats:: RISC-V Instruction Formats
+* RISC-V-ATTRIBUTE:: RISC-V Object Attribute
@end menu
@node RISC-V-Options
Selects the ABI, which is either "ilp32" or "lp64", optionally followed
by "f", "d", or "q" to indicate single-precision, double-precision, or
quad-precision floating-point calling convention, or none to indicate
-the soft-float calling convention.
+the soft-float calling convention. Also, "ilp32" can optionally be followed
+by "e" to indicate the RVE ABI, which is always soft-float.
+@cindex @samp{-mrelax} option, RISC-V
+@item -mrelax
+Take advantage of linker relaxations to reduce the number of instructions
+required to materialize symbol addresses. (default)
+
+@cindex @samp{-mno-relax} option, RISC-V
+@item -mno-relax
+Don't do linker relaxations.
+
+@cindex @samp{-march-attr} option, RISC-V
+@item -march-attr
+Generate the default contents for the riscv elf attribute section if the
+.attribute directives are not set. This section is used to record the
+information that a linker or runtime loader needs to check compatibility.
+This information includes ISA string, stack alignment requirement, unaligned
+memory accesses, and the major, minor and revision version of privileged
+specification.
+
+@cindex @samp{-mno-arch-attr} option, RISC-V
+@item -mno-arch-attr
+Don't generate the default riscv elf attribute section if the .attribute
+directives are not set.
+
+@cindex @samp{-mcsr-check} option, RISC-V
+@item -mcsr-check
+Enable the CSR checking for the ISA-dependent CRS and the read-only CSR.
+The ISA-dependent CSR are only valid when the specific ISA is set. The
+read-only CSR can not be written by the CSR instructions.
+
+@cindex @samp{-mno-csr-check} option, RISC-V
+@item -mno-csr-check
+Don't do CSR cheching.
@end table
@c man end
@node RISC-V-Directives
+@section RISC-V Directives
@cindex machine directives, RISC-V
@cindex RISC-V machine directives
-@section RISC-V Directives
-
The following table lists all available RISC-V specific directives.
@table @code
desirable.
@end table
+@item csr-check
+@itemx no-csr-check
+Enables or disables the CSR checking.
+
+@cindex INSN directives
+@item .insn @var{value}
+@itemx .insn @var{value}
+This directive permits the numeric representation of an instructions
+and makes the assembler insert the operands according to one of the
+instruction formats for @samp{.insn} (@ref{RISC-V-Formats}).
+For example, the instruction @samp{add a0, a1, a2} could be written as
+@samp{.insn r 0x33, 0, 0, a0, a1, a2}.
+
+@cindex @code{.attribute} directive, RISC-V
+@item .attribute @var{tag}, @var{value}
+Set the object attribute @var{tag} to @var{value}.
+
+The @var{tag} is either an attribute number, or one of the following:
+@code{Tag_RISCV_arch}, @code{Tag_RISCV_stack_align},
+@code{Tag_RISCV_unaligned_access}, @code{Tag_RISCV_priv_spec},
+@code{Tag_RISCV_priv_spec_minor}, @code{Tag_RISCV_priv_spec_revision}.
+
+@end table
+
+@node RISC-V-Modifiers
+@section RISC-V Assembler Modifiers
+
+The RISC-V assembler supports following modifiers for relocatable addresses
+used in RISC-V instruction operands. However, we also support some pseudo
+instructions that are easier to use than these modifiers.
+
+@table @code
+@item %lo(@var{symbol})
+The low 12 bits of absolute address for @var{symbol}.
+
+@item %hi(@var{symbol})
+The high 20 bits of absolute address for @var{symbol}. This is usually
+used with the %lo modifier to represent a 32-bit absolute address.
+
+@smallexample
+ lui a0, %hi(@var{symbol}) // R_RISCV_HI20
+ addi a0, a0, %lo(@var{symbol}) // R_RISCV_LO12_I
+
+ lui a0, %hi(@var{symbol}) // R_RISCV_HI20
+ load/store a0, %lo(@var{symbol})(a0) // R_RISCV_LO12_I/S
+@end smallexample
+
+@item %pcrel_lo(@var{label})
+The low 12 bits of relative address between pc and @var{symbol}.
+The @var{symbol} is related to the high part instruction which is marked
+by @var{label}.
+
+@item %pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and @var{symbol}.
+This is usually used with the %pcrel_lo modifier to represent a +/-2GB
+pc-relative range.
+
+@smallexample
+@var{label}:
+ auipc a0, %pcrel_hi(@var{symbol}) // R_RISCV_PCREL_HI20
+ addi a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
+
+@var{label}:
+ auipc a0, %pcrel_hi(@var{symbol}) // R_RISCV_PCREL_HI20
+ load/store a0, %pcrel_lo(@var{label})(a0) // R_RISCV_PCREL_LO12_I/S
+@end smallexample
+
+Or you can use the pseudo lla/lw/sw/... instruction to do this.
+
+@smallexample
+ lla a0, @var{symbol}
+@end smallexample
+
+@item %got_pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and the GOT entry of
+@var{symbol}. This is usually used with the %pcrel_lo modifier to access
+the GOT entry.
+
+@smallexample
+@var{label}:
+ auipc a0, %got_pcrel_hi(@var{symbol}) // R_RISCV_GOT_HI20
+ addi a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
+
+@var{label}:
+ auipc a0, %got_pcrel_hi(@var{symbol}) // R_RISCV_GOT_HI20
+ load/store a0, %pcrel_lo(@var{label})(a0) // R_RISCV_PCREL_LO12_I/S
+@end smallexample
+
+Also, the pseudo la instruction with PIC has similar behavior.
+
+@item %tprel_add(@var{symbol})
+This is used purely to associate the R_RISCV_TPREL_ADD relocation for
+TLS relaxation. This one is only valid as the fourth operand to the normally
+3 operand add instruction.
+
+@item %tprel_lo(@var{symbol})
+The low 12 bits of relative address between tp and @var{symbol}.
+
+@item %tprel_hi(@var{symbol})
+The high 20 bits of relative address between tp and @var{symbol}. This is
+usually used with the %tprel_lo and %tprel_add modifiers to access the thread
+local variable @var{symbol} in TLS Local Exec.
+
+@smallexample
+ lui a5, %tprel_hi(@var{symbol}) // R_RISCV_TPREL_HI20
+ add a5, a5, tp, %tprel_add(@var{symbol}) // R_RISCV_TPREL_ADD
+ load/store t0, %tprel_lo(@var{symbol})(a5) // R_RISCV_TPREL_LO12_I/S
+@end smallexample
+
+@item %tls_ie_pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and GOT entry. It is
+usually used with the %pcrel_lo modifier to access the thread local
+variable @var{symbol} in TLS Initial Exec.
+
+@smallexample
+ la.tls.ie a5, @var{symbol}
+ add a5, a5, tp
+ load/store t0, 0(a5)
+@end smallexample
+
+The pseudo la.tls.ie instruction can be expended to
+
+@smallexample
+@var{label}:
+ auipc a5, %tls_ie_pcrel_hi(@var{symbol}) // R_RISCV_TLS_GOT_HI20
+ load a5, %pcrel_lo(@var{label})(a5) // R_RISCV_PCREL_LO12_I
+@end smallexample
+
+@item %tls_gd_pcrel_hi(@var{symbol})
+The high 20 bits of relative address between pc and GOT entry. It is
+usually used with the %pcrel_lo modifier to access the thread local variable
+@var{symbol} in TLS Global Dynamic.
+
+@smallexample
+ la.tls.gd a0, @var{symbol}
+ call __tls_get_addr@@plt
+ mv a5, a0
+ load/store t0, 0(a5)
+@end smallexample
+
+The pseudo la.tls.gd instruction can be expended to
+
+@smallexample
+@var{label}:
+ auipc a0, %tls_gd_pcrel_hi(@var{symbol}) // R_RISCV_TLS_GD_HI20
+ addi a0, a0, %pcrel_lo(@var{label}) // R_RISCV_PCREL_LO12_I
+@end smallexample
+
+@end table
+
+@node RISC-V-Formats
+@section RISC-V Instruction Formats
+@cindex instruction formats, risc-v
+@cindex RISC-V instruction formats
+
+The RISC-V Instruction Set Manual Volume I: User-Level ISA lists 12
+instruction formats where some of the formats have multiple variants.
+For the @samp{.insn} pseudo directive the assembler recognizes some
+of the formats.
+Typically, the most general variant of the instruction format is used
+by the @samp{.insn} directive.
+
+The following table lists the abbreviations used in the table of
+instruction formats:
+
+@display
+@multitable @columnfractions .15 .40
+@item opcode @tab Unsigned immediate or opcode name for 7-bits opcode.
+@item opcode2 @tab Unsigned immediate or opcode name for 2-bits opcode.
+@item func7 @tab Unsigned immediate for 7-bits function code.
+@item func6 @tab Unsigned immediate for 6-bits function code.
+@item func4 @tab Unsigned immediate for 4-bits function code.
+@item func3 @tab Unsigned immediate for 3-bits function code.
+@item func2 @tab Unsigned immediate for 2-bits function code.
+@item rd @tab Destination register number for operand x, can be GPR or FPR.
+@item rd' @tab Destination register number for operand x,
+only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
+@item rs1 @tab First source register number for operand x, can be GPR or FPR.
+@item rs1' @tab First source register number for operand x,
+only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
+@item rs2 @tab Second source register number for operand x, can be GPR or FPR.
+@item rs2' @tab Second source register number for operand x,
+only accept s0-s1, a0-a5, fs0-fs1 and fa0-fa5.
+@item simm12 @tab Sign-extended 12-bit immediate for operand x.
+@item simm20 @tab Sign-extended 20-bit immediate for operand x.
+@item simm6 @tab Sign-extended 6-bit immediate for operand x.
+@item uimm8 @tab Unsigned 8-bit immediate for operand x.
+@item symbol @tab Symbol or lable reference for operand x.
+@end multitable
+@end display
+
+The following table lists all available opcode name:
+
+@table @code
+@item C0
+@item C1
+@item C2
+Opcode space for compressed instructions.
+
+@item LOAD
+Opcode space for load instructions.
+
+@item LOAD_FP
+Opcode space for floating-point load instructions.
+
+@item STORE
+Opcode space for store instructions.
+
+@item STORE_FP
+Opcode space for floating-point store instructions.
+
+@item AUIPC
+Opcode space for auipc instruction.
+
+@item LUI
+Opcode space for lui instruction.
+
+@item BRANCH
+Opcode space for branch instructions.
+
+@item JAL
+Opcode space for jal instruction.
+
+@item JALR
+Opcode space for jalr instruction.
+
+@item OP
+Opcode space for ALU instructions.
+
+@item OP_32
+Opcode space for 32-bits ALU instructions.
+
+@item OP_IMM
+Opcode space for ALU with immediate instructions.
+
+@item OP_IMM_32
+Opcode space for 32-bits ALU with immediate instructions.
+
+@item OP_FP
+Opcode space for floating-point operation instructions.
+
+@item MADD
+Opcode space for madd instruction.
+
+@item MSUB
+Opcode space for msub instruction.
+
+@item NMADD
+Opcode space for nmadd instruction.
+
+@item NMSUB
+Opcode space for msub instruction.
+
+@item AMO
+Opcode space for atomic memory operation instructions.
+
+@item MISC_MEM
+Opcode space for misc instructions.
+
+@item SYSTEM
+Opcode space for system instructions.
+
+@item CUSTOM_0
+@item CUSTOM_1
+@item CUSTOM_2
+@item CUSTOM_3
+Opcode space for customize instructions.
+
+@end table
+
+An instruction is two or four bytes in length and must be aligned
+on a 2 byte boundary. The first two bits of the instruction specify the
+length of the instruction, 00, 01 and 10 indicates a two byte instruction,
+11 indicates a four byte instruction.
+
+The following table lists the RISC-V instruction formats that are available
+with the @samp{.insn} pseudo directive:
+
+@table @code
+@item R type: .insn r opcode, func3, func7, rd, rs1, rs2
+@verbatim
++-------+-----+-----+-------+----+-------------+
+| func7 | rs2 | rs1 | func3 | rd | opcode |
++-------+-----+-----+-------+----+-------------+
+31 25 20 15 12 7 0
+@end verbatim
+
+@item R type with 4 register operands: .insn r opcode, func3, func2, rd, rs1, rs2, rs3
+@itemx R4 type: .insn r4 opcode, func3, func2, rd, rs1, rs2, rs3
+@verbatim
++-----+-------+-----+-----+-------+----+-------------+
+| rs3 | func2 | rs2 | rs1 | func3 | rd | opcode |
++-----+-------+-----+-----+-------+----+-------------+
+31 27 25 20 15 12 7 0
+@end verbatim
+
+@item I type: .insn i opcode, func3, rd, rs1, simm12
+@verbatim
++-------------+-----+-------+----+-------------+
+| simm12 | rs1 | func3 | rd | opcode |
++-------------+-----+-------+----+-------------+
+31 20 15 12 7 0
+@end verbatim
+
+@item S type: .insn s opcode, func3, rd, rs1, simm12
+@verbatim
++--------------+-----+-----+-------+-------------+-------------+
+| simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode |
++--------------+-----+-----+-------+-------------+-------------+
+31 25 20 15 12 7 0
+@end verbatim
+
+@item SB type: .insn sb opcode, func3, rd, rs1, symbol
+@itemx SB type: .insn sb opcode, func3, rd, simm12(rs1)
+@itemx B type: .insn s opcode, func3, rd, rs1, symbol
+@itemx B type: .insn s opcode, func3, rd, simm12(rs1)
+@verbatim
++------------+--------------+-----+-----+-------+-------------+-------------+--------+
+| simm12[12] | simm12[10:5] | rs2 | rs1 | func3 | simm12[4:1] | simm12[11]] | opcode |
++------------+--------------+-----+-----+-------+-------------+-------------+--------+
+31 30 25 20 15 12 7 0
+@end verbatim
+
+@item U type: .insn u opcode, rd, simm20
+@verbatim
++---------------------------+----+-------------+
+| simm20 | rd | opcode |
++---------------------------+----+-------------+
+31 12 7 0
+@end verbatim
+
+@item UJ type: .insn uj opcode, rd, symbol
+@itemx J type: .insn j opcode, rd, symbol
+@verbatim
++------------+--------------+------------+---------------+----+-------------+
+| simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode |
++------------+--------------+------------+---------------+----+-------------+
+31 30 21 20 12 7 0
+@end verbatim
+
+@item CR type: .insn cr opcode2, func4, rd, rs2
+@verbatim
++---------+--------+-----+---------+
+| func4 | rd/rs1 | rs2 | opcode2 |
++---------+--------+-----+---------+
+15 12 7 2 0
+@end verbatim
+
+@item CI type: .insn ci opcode2, func3, rd, simm6
+@verbatim
++---------+-----+--------+-----+---------+
+| func3 | imm | rd/rs1 | imm | opcode2 |
++---------+-----+--------+-----+---------+
+15 13 12 7 2 0
+@end verbatim
+
+@item CIW type: .insn ciw opcode2, func3, rd, uimm8
+@verbatim
++---------+--------------+-----+---------+
+| func3 | imm | rd' | opcode2 |
++---------+--------------+-----+---------+
+15 13 7 2 0
+@end verbatim
+
+@item CA type: .insn ca opcode2, func6, func2, rd, rs2
+@verbatim
++---------+----------+-------+------+--------+
+| func6 | rd'/rs1' | func2 | rs2' | opcode |
++---------+----------+-------+------+--------+
+15 10 7 5 2 0
+@end verbatim
+
+@item CB type: .insn cb opcode2, func3, rs1, symbol
+@verbatim
++---------+--------+------+--------+---------+
+| func3 | offset | rs1' | offset | opcode2 |
++---------+--------+------+--------+---------+
+15 13 10 7 2 0
+@end verbatim
+
+@item CJ type: .insn cj opcode2, symbol
+@verbatim
++---------+--------------------+---------+
+| func3 | jump target | opcode2 |
++---------+--------------------+---------+
+15 13 7 2 0
+@end verbatim
+
+
+@end table
+
+For the complete list of all instruction format variants see
+The RISC-V Instruction Set Manual Volume I: User-Level ISA.
+
+@node RISC-V-ATTRIBUTE
+@section RISC-V Object Attribute
+@cindex Object Attribute, RISC-V
+
+RISC-V attributes have a string value if the tag number is odd and an integer
+value if the tag number is even.
+
+@table @r
+@item Tag_RISCV_stack_align (4)
+Tag_RISCV_strict_align records the N-byte stack alignment for this object. The
+default value is 16 for RV32I or RV64I, and 4 for RV32E.
+
+The smallest value will be used if object files with different
+Tag_RISCV_stack_align values are merged.
+
+@item Tag_RISCV_arch (5)
+Tag_RISCV_arch contains a string for the target architecture taken from the
+option @option{-march}. Different architectures will be integrated into a
+superset when object files are merged.
+
+Note that the version information of the target architecture must be presented
+explicitly in the attribute and abbreviations must be expanded. The version
+information, if not given by @option{-march}, must be in accordance with the
+default specified by the tool. For example, the architecture @code{RV32I} has
+to be recorded in the attribute as @code{RV32I2P0} in which @code{2P0} stands
+for the default version of its base ISA. On the other hand, the architecture
+@code{RV32G} has to be presented as @code{RV32I2P0_M2P0_A2P0_F2P0_D2P0} in
+which the abbreviation @code{G} is expanded to the @code{IMAFD} combination
+with default versions of the standard extensions.
+
+@item Tag_RISCV_unaligned_access (6)
+Tag_RISCV_unaligned_access is 0 for files that do not allow any unaligned
+memory accesses, and 1 for files that do allow unaligned memory accesses.
+
+@item Tag_RISCV_priv_spec (8)
+@item Tag_RISCV_priv_spec_minor (10)
+@item Tag_RISCV_priv_spec_revision (12)
+Tag_RISCV_priv_spec contains the major/minor/revision version information of
+the privileged specification. It will report errors if object files of
+different privileged specification versions are merged.
+
@end table
projects / deliverable / binutils-gdb.git / blobdiff