// Copyright 2025 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
Package riscv implements the riscv64 assembler.

# Register naming

The integer registers are named X0 through to X31, however X4 must be accessed
through its RISC-V ABI name, TP, and X27, which holds a pointer to the Go
routine structure, must be referred to as g. Additionally, when building in
shared mode, X3 is unavailable and must be accessed via its RISC-V ABI name,
GP.

The floating-point registers are named F0 through to F31.

The vector registers are named V0 through to V31.

Both integer and floating-point registers can be referred to by their RISC-V
ABI names, e.g., A0 or FT0, with the exception that X27 cannot be referred to
by its RISC-V ABI name, S11.  It must be referred to as g.

Some of the integer registers are used by the Go runtime and assembler - X26 is
the closure pointer, X27 points to the Go routine structure and X31 is a
temporary register used by the Go assembler. Use of X31 should be avoided in
hand written assembly code as its value could be altered by the instruction
sequences emitted by the assembler.

# Instruction naming

Many RISC-V instructions contain one or more suffixes in their names. In the
[RISC-V ISA Manual] these suffixes are separated from themselves and the
name of the instruction mnemonic with a dot ('.'). In the Go assembler, the
separators are omitted and the suffixes are written in upper case.

Example:

	FMVWX           <=>     fmv.w.x

# Rounding modes

The Go toolchain does not set the FCSR register and requires the desired
rounding mode to be explicitly encoded within floating-point instructions.
The syntax the Go assembler uses to specify the rounding modes differs
from the syntax in the RISC-V specifications. In the [RISC-V ISA Manual]
the rounding mode is given as an extra operand at the end of an
assembly language instruction. In the Go assembler, the rounding modes are
converted to uppercase and follow the instruction mnemonic from which they
are separated with a dot ('.').

Example:

	FCVTLUS.RNE F0, X5      <=>     fcvt.lu.s x5, f0, rne

RTZ is assumed if the rounding mode is omitted.

# RISC-V extensions

By default the Go compiler targets the [rva20u64] profile. This profile mandates
all the general RISC-V instructions, allowing Go to use integer, multiplication,
division, floating-point and atomic instructions without having to
perform compile time or runtime checks to verify that their use is appropriate
for the target hardware. All widely available riscv64 devices support at least
[rva20u64]. The Go toolchain can be instructed to target later RISC-V profiles,
including, [rva22u64] and [rva23u64], via the GORISCV64 environment variable.
Instructions that are provided by newer profiles cannot typically be used in
handwritten assembly code without compile time guards (or runtime checks)
that ensure they are hardware supported.

The file asm_riscv64.h defines macros for each RISC-V extension that is enabled
by setting the GORISCV64 environment variable to a value other than [rva20u64].
For example, if GORISCV64=rva22u64 the macros hasZba, hasZbb and hasZbs will be
defined. If GORISCV64=rva23u64 hasV will be defined in addition to hasZba,
hasZbb and hasZbs. These macros can be used to determine whether it's safe
to use an instruction in hand-written assembly.

It is not always necessary to include asm_riscv64.h and use #ifdefs in your
code to safely take advantage of instructions present in the [rva22u64]
profile. In some cases the assembler can generate [rva20u64] compatible code
even when an [rva22u64] instruction is used in an assembly source file. When
GORISCV64=rva20u64 the assembler will synthesize certain [rva22u64]
instructions, e.g., ANDN, using multiple [rva20u64] instructions. Instructions
such as ANDN can then be freely used in assembly code without checking to see
whether the instruction is supported by the target profile. When building a
source file containing the ANDN instruction with GORISCV64=rva22u64 the
assembler will emit the Zbb ANDN instruction directly. When building the same
source file with GORISCV64=rva20u64 the assembler will emit multiple [rva20u64]
instructions to synthesize ANDN.

The assembler will also use [rva22u64] instructions to implement the zero and
sign extension instructions, e.g., MOVB and MOVHU, when GORISCV64=rva22u64 or
greater.

The instructions not implemented in the default profile ([rva20u64]) that can
be safely used in assembly code without compile time checks are:

  - ANDN
  - MAX
  - MAXU
  - MIN
  - MINU
  - MOVB
  - MOVH
  - MOVHU
  - MOVWU
  - ORN
  - ROL
  - ROLW
  - ROR
  - RORI
  - RORIW
  - RORW
  - XNOR

# Operand ordering

The ordering used for instruction operands in the Go assembler differs from the
ordering defined in the [RISC-V ISA Manual].

1. R-Type instructions

R-Type instructions are written in the reverse order to that given in the
[RISC-V ISA Manual], with the register order being rs2, rs1, rd.

Examples:

	ADD X10, X11, X12       <=>     add x12, x11, x10
	FADDD F10, F11, F12     <=>     fadd.d f12, f11, f10

2. I-Type arithmetic instructions

I-Type arithmetic instructions (not loads, fences, ebreak, ecall) use the same
ordering as the R-Type instructions, typically, imm12, rs1, rd.

Examples:

	ADDI $1, X11, X12       <=>     add x12, x11, 1
	SLTI $1, X11, X12       <=>     slti x12, x11, 1

3. Loads and Stores

Load instructions are written with the source operand (whether it be a register
or a memory address), first followed by the destination operand.

Examples:

	MOV 16(X2), X10         <=>     ld x10, 16(x2)
	MOV X10, (X2)           <=>     sd x10, 0(x2)

4. Branch instructions

The branch instructions use the same operand ordering as is given in the
[RISC-V ISA Manual], e.g., rs1, rs2, label.

Example:

	BLT X12, X23, loop1     <=>     blt x12, x23, loop1

BLT X12, X23, label will jump to label if X12 < X23. Note this is not the
same ordering as is used for the SLT instructions.

5. FMA instructions

The Go assembler uses a different ordering for the RISC-V FMA operands to
the ordering given in the [RISC-V ISA Manual]. The operands are rotated one
place to the left, so that the destination operand comes last.

Example:

	FMADDS  F1, F2, F3, F4  <=>     fmadd.s f4, f1, f2, f3

6. AMO instructions

The ordering used for the AMO operations is rs2, rs1, rd, i.e., the operands
as specified in the [RISC-V ISA Manual] are rotated one place to the left.

Example:

	AMOSWAPW X5, (X6), X7   <=>     amoswap.w x7, x5, (x6)

7. Vector instructions

The VSETVLI instruction uses the same symbolic names as the [RISC-V ISA Manual]
to represent the components of vtype, with the exception
that they are written in upper case. The ordering of the operands in the Go
assembler differs from the [RISC-V ISA Manual] in that the operands are
rotated one place to the left so that the destination register, the register
that holds the new vl, is the last operand.

Example:

	VSETVLI X10, E8, M1, TU, MU, X12        <=>     vsetvli x12, x10, e8, m1, tu, mu

Vector load and store instructions follow the pattern set by scalar loads and
stores, i.e., the source is always the first operand and the destination the
last. However, the ordering of the operands of these instructions is
complicated by the optional mask register and, in some cases, the use of an
additional stride or index register. In the Go assembler the index and stride
registers appear as the second operand in indexed or strided loads and stores,
while the mask register, if present, is always the penultimate operand.

Examples:

	VLE8V (X10), V3                 <=>     vle8.v  v3, (x10)
	VSE8V V3, (X10)                 <=>     vse8.v  v3, (x10)
	VLE8V (X10), V0, V3             <=>     vle8.v  v3, (x10), v0.t
	VSE8V V3, V0, (X10)             <=>     vse8.v  v3, (x10), v0.t
	VLSE8V (X10), X11, V3           <=>     vlse8.v v3, (x10), x11
	VSSE8V V3, X11, (X10)           <=>     vsse8.v v3, (x10), x11
	VLSE8V (X10), X11, V0, V3       <=>     vlse8.v v3, (x10), x11, v0.t
	VSSE8V V3, X11, V0, (X10)       <=>     vsse8.v v3, (x10), x11, v0.t
	VLUXEI8V (X10), V2, V3          <=>     vluxei8.v v3, (x10), v2
	VSUXEI8V V3, V2, (X10)          <=>     vsuxei8.v v3, (x10), v2
	VLUXEI8V (X10), V2, V0, V3      <=>     vluxei8.v v3, (x10), v2, v0.t
	VSUXEI8V V3, V2, V0, (X10)      <=>     vsuxei8.v v3, (x10), v2, v0.t
	VL1RE8V (X10), V3               <=>     vl1re8.v v3, (x10)
	VS1RV V3, (X11)                 <=>     vs1r.v  v3, (x11)

The ordering of operands for two and three argument vector arithmetic instructions is
reversed in the Go assembler.

Examples:

	VMVVV V2, V3                    <=> vmv.v.v v3, v2
	VADDVV V1, V2, V3               <=> vadd.vv v3, v2, v1
	VADDVX X10, V2, V3              <=> vadd.vx v3, v2, x10
	VMADCVI $15, V2, V3             <=> vmadc.vi v3, v2, 15

The mask register, when specified, is always the penultimate operand in a vector
arithmetic instruction, appearing before the destination register.

Examples:

	VANDVV V1, V2, V0, V3           <=> vand.vv v3, v2, v1, v0.t

# Ternary instructions

The Go assembler allows the second operand to be omitted from most ternary
instructions if it matches the third (destination) operand.

Examples:

	ADD X10, X12, X12       <=>     ADD X10, X12
	ANDI $3, X12, X12       <=>     ANDI $3, X12

The use of this abbreviated syntax is encouraged.

# Ordering of atomic instructions

The FENCE instruction supports all of the bits in the predecessor and successor
sets. The predecessor set is specified before the successor set. The letters
representing the bits in both sets must be given in uppercase. For example,

	FENCE R, RW

specifies a FENCE instruction with the R bit set in the predecessor set and
the R and W bits set in the successor set.

If neither set is provided a full fence is emitted, e.g.,

	FENCE

and

	FENCE IORW, IORW

are equivalent.

The FENCE.TSO instruction is supported.

It is not possible to specify the ordering bits in the LR, SC or AMO
instructions. The acquire and release bits are always set for the AMO
instructions, the acquire bit is always set for the LR instructions while
the release bit is set for the SC instructions.

# Immediate operands

In many cases, where an R-Type instruction has a corresponding I-Type
instruction, the R-Type mnemonic can be used in place of the I-Type mnemonic.
The assembler assumes that the immediate form of the instruction was intended
when the first operand is given as an immediate value rather than a register.

Example:

	AND $3, X12, X13        <=>     ANDI $3, X12, X13

# Integer constant materialization

The MOV instruction can be used to set a register to the value of any 64 bit
constant literal. The way this is achieved by the assembler varies depending
on the value of the constant. Where possible the assembler will synthesize the
constant using one or more RISC-V arithmetic instructions. If it is unable
to easily materialize the constant it will load the 64 bit literal from memory.

A 32 bit constant literal can be specified as an argument to ADDI, ANDI, ORI and
XORI. If the specified literal does not fit into 12 bits the assembler will
generate extra instructions to synthesize it.

Integer constants provided as operands to all other instructions must fit into
the number of bits allowed by the instructions' encodings for immediate values.
Otherwise, an error will be generated.

# Floating point constant materialization

The MOVF and MOVD instructions can be used to set a register to the value
of any 32 bit or 64 bit floating point constant literal, respectively.  Unless
the constant literal is 0.0, MOVF and MOVD will be encoded as FLW and FLD
instructions that load the constant from a location within the program's
binary.

# Compressed instructions

The Go assembler converts 32 bit RISC-V instructions to compressed
instructions when generating machine code. This conversion happens
automatically without the need for any direct involvement from the programmer,
although judicious choice of registers can improve the compression rate for
certain instructions (see the [RISC-V ISA Manual] for more details). This
behaviour is enabled by default for all of the supported RISC-V profiles, i.e.,
it is not affected by the value of the GORISCV64 environment variable.

The use of compressed instructions can be disabled via a debug flag,
compressinstructions:

  - Use -gcflags=all=-d=compressinstructions=0 to disable compressed
    instructions in Go code.
  - Use -asmflags=all=-d=compressinstructions=0 to disable compressed
    instructions in assembly code.

To completely disable automatic instruction compression in a Go binary both
options must be specified.

The assembler also permits the use of compressed instructions in hand coded
assembly language, but this should generally be avoided. Note that the
compressinstructions flag only prevents the automatic compression of 32
bit instructions. It has no effect on compressed instructions that are
hand coded directly into an assembly file.

[RISC-V ISA Manual]: https://github.com/riscv/riscv-isa-manual
[rva20u64]: https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc#51-rva20u64-profile
[rva22u64]: https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc#rva22u64-profile
[rva23u64]: https://github.com/riscv/riscv-profiles/blob/main/src/rva23-profile.adoc#rva23u64-profile
*/
package riscv