Re: [PATCH V9 01/24] Documentation: LoongArch: Add basic documentations
From: Bagas Sanjaya
Date: Sun May 01 2022 - 03:51:32 EST
On Sat, Apr 30, 2022 at 05:04:55PM +0800, Huacai Chen wrote:
> +Instruction names (Mnemonics)
> +-----------------------------
> +
> +We only list the instruction names here, for details please read the references.
> +
> +Arithmetic Operation Instructions::
> +
> + ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D
> + SLT SLTU SLTI SLTUI
> + AND OR NOR XOR ANDN ORN ANDI ORI XORI
> + MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU
> + MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU
> + PCADDI PCADDU12I PCADDU18I
> + LU12I.W LU32I.D LU52I.D ADDU16I.D
> +
> +Bit-shift Instructions::
> +
> + SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W
> + SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D
> +
> +Bit-manipulation Instructions::
> +
> + EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D
> + BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D
> + REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D
> + MASKEQZ MASKNEZ
> +
> +Branch Instructions::
> +
> + BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL
> +
> +Load/Store Instructions::
> +
> + LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D
> + LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D
> + LDPTR.W LDPTR.D STPTR.W STPTR.D
> + PRELD PRELDX
> +
> +Atomic Operation Instructions::
> +
> + LL.W SC.W LL.D SC.D
> + AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D
> + AMMAX.W AMMAX.D AMMIN.W AMMIN.D
> +
> +Barrier Instructions::
> +
> + IBAR DBAR
> +
> +Special Instructions::
> +
> + SYSCALL BREAK CPUCFG NOP IDLE ERTN DBCL RDTIMEL.W RDTIMEH.W RDTIME.D ASRTLE.D ASRTGT.D
> +
> +Privileged Instructions::
> +
> + CSRRD CSRWR CSRXCHG
> + IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D
> + CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE
> +
Since these above are list of instruction categories, it's better to use
enumerated lists. Also, make use of ReST labels to link to References
sections, like this:
-- >8 --
diff --git a/Documentation/loongarch/introduction.rst b/Documentation/loongarch/introduction.rst
index 420c0d2ebcfbe7..2d83283ecf28b9 100644
--- a/Documentation/loongarch/introduction.rst
+++ b/Documentation/loongarch/introduction.rst
@@ -194,60 +194,61 @@ can see I21L/I21H and I26L/I26H here.
Instruction names (Mnemonics)
-----------------------------
-We only list the instruction names here, for details please read the references.
+We only list the instruction names here, for details please read the
+:ref:`references <loongarch-references>`.
-Arithmetic Operation Instructions::
+1. Arithmetic Operation Instructions::
- ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D
- SLT SLTU SLTI SLTUI
- AND OR NOR XOR ANDN ORN ANDI ORI XORI
- MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU
- MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU
- PCADDI PCADDU12I PCADDU18I
- LU12I.W LU32I.D LU52I.D ADDU16I.D
+ ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D
+ SLT SLTU SLTI SLTUI
+ AND OR NOR XOR ANDN ORN ANDI ORI XORI
+ MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU
+ MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU
+ PCADDI PCADDU12I PCADDU18I
+ LU12I.W LU32I.D LU52I.D ADDU16I.D
-Bit-shift Instructions::
+2. Bit-shift Instructions::
- SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W
- SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D
+ SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W
+ SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D
-Bit-manipulation Instructions::
+3. Bit-manipulation Instructions::
- EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D
- BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D
- REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D
- MASKEQZ MASKNEZ
+ EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D
+ BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D
+ REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D
+ MASKEQZ MASKNEZ
-Branch Instructions::
+4. Branch Instructions::
- BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL
+ BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL
-Load/Store Instructions::
+5. Load/Store Instructions::
- LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D
- LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D
- LDPTR.W LDPTR.D STPTR.W STPTR.D
- PRELD PRELDX
+ LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D
+ LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D
+ LDPTR.W LDPTR.D STPTR.W STPTR.D
+ PRELD PRELDX
-Atomic Operation Instructions::
+6. Atomic Operation Instructions::
- LL.W SC.W LL.D SC.D
- AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D
- AMMAX.W AMMAX.D AMMIN.W AMMIN.D
+ LL.W SC.W LL.D SC.D
+ AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D
+ AMMAX.W AMMAX.D AMMIN.W AMMIN.D
-Barrier Instructions::
+7. Barrier Instructions::
- IBAR DBAR
+ IBAR DBAR
-Special Instructions::
+8. Special Instructions::
- SYSCALL BREAK CPUCFG NOP IDLE ERTN DBCL RDTIMEL.W RDTIMEH.W RDTIME.D ASRTLE.D ASRTGT.D
+ SYSCALL BREAK CPUCFG NOP IDLE ERTN DBCL RDTIMEL.W RDTIMEH.W RDTIME.D ASRTLE.D ASRTGT.D
-Privileged Instructions::
+9. Privileged Instructions::
- CSRRD CSRWR CSRXCHG
- IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D
- CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE
+ CSRRD CSRWR CSRXCHG
+ IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D
+ CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE
Virtual Memory
==============
@@ -315,6 +316,8 @@ MIPS, while New Loongson is based on LoongArch. Take Loongson-3 as an example:
Loongson-3A1000/3B1500/3A2000/3A3000/3A4000 are MIPS-compatible, while Loongson-
3A5000 (and future revisions) are all based on LoongArch.
+.. _loongarch-references:
+
References
==========
> +
> + +---------------------------------------------+
> + |:: |
> + | |
> + | +-----+ +---------+ +-------+ |
> + | | IPI | --> | CPUINTC | <-- | Timer | |
> + | +-----+ +---------+ +-------+ |
> + | ^ |
> + | | |
> + | +---------+ +-------+ |
> + | | LIOINTC | <-- | UARTs | |
> + | +---------+ +-------+ |
> + | ^ |
> + | | |
> + | +-----------+ |
> + | | HTVECINTC | |
> + | +-----------+ |
> + | ^ ^ |
> + | | | |
> + | +---------+ +---------+ |
> + | | PCH-PIC | | PCH-MSI | |
> + | +---------+ +---------+ |
> + | ^ ^ ^ |
> + | | | | |
> + | +---------+ +---------+ +---------+ |
> + | | PCH-LPC | | Devices | | Devices | |
> + | +---------+ +---------+ +---------+ |
> + | ^ |
> + | | |
> + | +---------+ |
> + | | Devices | |
> + | +---------+ |
> + | |
> + | |
> + +---------------------------------------------+
> +
...
> +
> + +--------------------------------------------------------+
> + |:: |
> + | |
> + | +-----+ +---------+ +-------+ |
> + | | IPI | --> | CPUINTC | <-- | Timer | |
> + | +-----+ +---------+ +-------+ |
> + | ^ ^ |
> + | | | |
> + | +---------+ +---------+ +-------+ |
> + | | EIOINTC | | LIOINTC | <-- | UARTs | |
> + | +---------+ +---------+ +-------+ |
> + | ^ ^ |
> + | | | |
> + | +---------+ +---------+ |
> + | | PCH-PIC | | PCH-MSI | |
> + | +---------+ +---------+ |
> + | ^ ^ ^ |
> + | | | | |
> + | +---------+ +---------+ +---------+ |
> + | | PCH-LPC | | Devices | | Devices | |
> + | +---------+ +---------+ +---------+ |
> + | ^ |
> + | | |
> + | +---------+ |
> + | | Devices | |
> + | +---------+ |
> + | |
> + | |
> + +--------------------------------------------------------+
> +
I think just literal blocks is enough for the diagrams above.
--
An old man doll... just what I always wanted! - Clara