Add some tips for writing assembly

Add some tips for writing assembly which were added in Chinese manual in version 1.02. Signed-off-by: Qi Hu <[email protected]>
loongson · Aug 12, 2022 · 11c35f0 · 11c35f0
1 parent 35a3ecc
commit 11c35f0
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 0 deletions.
diff --git a/...overview-of-floating-point-instructions/floating-point-branch-instructions.adoc b/...overview-of-floating-point-instructions/floating-point-branch-instructions.adoc
@@ -25,3 +25,8 @@ BCNEZ:
     if CFR[cj] != 0:
         PC = PC + SignExtend({offs21, 2'b0}, GRLEN)
 ----
+
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(offs21<<2)`.
+====
diff --git a/...s/overview-of-basic-integer-instructions/arithmetic-operation-instructions.adoc b/...s/overview-of-basic-integer-instructions/arithmetic-operation-instructions.adoc
@@ -132,6 +132,11 @@ ALSL.D:
 
 When the above instructions are executed, no special handling will be done on overflow.
 
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real shift value*, i.e. `(sa2+1)`, not the value in the immediate field of the instruction code.
+====
+
 ===== `LU12I.W`, `LU32I.D`, `LU52I.D`
 
 Instruction formats:

diff --git a/...er-instructions/overview-of-basic-integer-instructions/branch-instructions.adoc b/...er-instructions/overview-of-basic-integer-instructions/branch-instructions.adoc
@@ -75,6 +75,11 @@ BGEU:
 
 The calculation method of the jump target address of the above-mentioned six branch instructions is to logically shift the 16-bit immediate `offs16` in the instruction code by 2 bits and then sign expand, and the resulting offset value is added to the PC of the branch instruction.
 
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(offs16<<2)`.
+====
+
 ===== `BEQZ`, `BNEZ`
 
 Instruction formats:
@@ -105,6 +110,11 @@ BNEZ:
 
 The jump target address of the above two branch instructions is to logical left shift the 21-bit immediate `offs21` in the instruction code by 2 bits and then sign extension, and the resulting offset value is added to the `PC` of the branch instruction.
 
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(offs21<<2)`.
+====
+
 ===== `B`
 
 Instruction formats:
@@ -123,6 +133,11 @@ B:
     PC = PC + SignExtend({offs26, 2' b0}, GRLEN)
 ----
 
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(offs26<<2)`.
+====
+
 ===== `BL`
 
 Instruction formats:
@@ -146,6 +161,11 @@ BL:
 
 In LA ABI, the No.1 general register `r1` serves as the return address register `ra`.
 
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(offs26<<2)`.
+====
+
 ===== `JIRL`
 
 Instruction formats:
@@ -169,3 +189,8 @@ JIRL:
 When `rd` is equal to `0`, the function of `JIRL` is a common non-call indirect jump instruction.
 
 `JIRL` with rd equal to `0`, `rj` equal to `1` and `offs16` equal to `0` is often used as an indirect jump from call return.
+
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(offs16<<2)`.
+====
diff --git a/...s/overview-of-basic-integer-instructions/common-memory-access-instructions.adoc b/...s/overview-of-basic-integer-instructions/common-memory-access-instructions.adoc
@@ -269,6 +269,11 @@ STPTR.D:
 
 The memory access address calculation method of the above instruction is to logical left shift the 14-bit immediate data `si14` by 2 bits, sign extension, and then sum the value in the general register `rj`.
 
+[TIP]
+====
+When writing assembly, you need to fill in the immediate field with the *real offset value* in bytes, i.e. `(si14<<2)`.
+====
+
 For `LDPTR.{W/D}` and `STPTR.{W/D}` instructions, no matter what kind of hardware implementation and environmental configuration, as long as the memory access address is naturally aligned, the non-aligned exception will not be triggered; when the memory address is not naturally aligned, if the hardware implementation supports unaligned memory access and the current computing environment is configured to allow unaligned memory access, then the unaligned exception will not be triggered, otherwise it will trigger the unaligned exception.
 
 `LDPTR.{W/D}`, `STPTR.{W/D}` instructions are used in conjunction with `ADDU16I.D` instructions to accelerate GOT table-based access in position-independent codes.