0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =========================
0004 Introduction to LoongArch
0005 =========================
0006
0007 LoongArch is a new RISC ISA, which is a bit like MIPS or RISC-V. There are
0008 currently 3 variants: a reduced 32-bit version (LA32R), a standard 32-bit
0009 version (LA32S) and a 64-bit version (LA64). There are 4 privilege levels
0010 (PLVs) defined in LoongArch: PLV0~PLV3, from high to low. Kernel runs at PLV0
0011 while applications run at PLV3. This document introduces the registers, basic
0012 instruction set, virtual memory and some other topics of LoongArch.
0013
0014 Registers
0015 =========
0016
0017 LoongArch registers include general purpose registers (GPRs), floating point
0018 registers (FPRs), vector registers (VRs) and control status registers (CSRs)
0019 used in privileged mode (PLV0).
0020
0021 GPRs
0022 ----
0023
0024 LoongArch has 32 GPRs ( ``$r0`` ~ ``$r31`` ); each one is 32-bit wide in LA32
0025 and 64-bit wide in LA64. ``$r0`` is hard-wired to zero, and the other registers
0026 are not architecturally special. (Except ``$r1``, which is hard-wired as the
0027 link register of the BL instruction.)
0028
0029 The kernel uses a variant of the LoongArch register convention, as described in
0030 the LoongArch ELF psABI spec, in :ref:`References <loongarch-references>`:
0031
0032 ================= =============== =================== ============
0033 Name Alias Usage Preserved
0034 across calls
0035 ================= =============== =================== ============
0036 ``$r0`` ``$zero`` Constant zero Unused
0037 ``$r1`` ``$ra`` Return address No
0038 ``$r2`` ``$tp`` TLS/Thread pointer Unused
0039 ``$r3`` ``$sp`` Stack pointer Yes
0040 ``$r4``-``$r11`` ``$a0``-``$a7`` Argument registers No
0041 ``$r4``-``$r5`` ``$v0``-``$v1`` Return value No
0042 ``$r12``-``$r20`` ``$t0``-``$t8`` Temp registers No
0043 ``$r21`` ``$u0`` Percpu base address Unused
0044 ``$r22`` ``$fp`` Frame pointer Yes
0045 ``$r23``-``$r31`` ``$s0``-``$s8`` Static registers Yes
0046 ================= =============== =================== ============
0047
0048 .. Note::
0049 The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
0050 kernel for storing the percpu base address. It normally has no ABI name,
0051 but is called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1``
0052 in some old code,however they are deprecated aliases of ``$a0`` and ``$a1``
0053 respectively.
0054
0055 FPRs
0056 ----
0057
0058 LoongArch has 32 FPRs ( ``$f0`` ~ ``$f31`` ) when FPU is present. Each one is
0059 64-bit wide on the LA64 cores.
0060
0061 The floating-point register convention is the same as described in the
0062 LoongArch ELF psABI spec:
0063
0064 ================= ================== =================== ============
0065 Name Alias Usage Preserved
0066 across calls
0067 ================= ================== =================== ============
0068 ``$f0``-``$f7`` ``$fa0``-``$fa7`` Argument registers No
0069 ``$f0``-``$f1`` ``$fv0``-``$fv1`` Return value No
0070 ``$f8``-``$f23`` ``$ft0``-``$ft15`` Temp registers No
0071 ``$f24``-``$f31`` ``$fs0``-``$fs7`` Static registers Yes
0072 ================= ================== =================== ============
0073
0074 .. Note::
0075 You may see ``$fv0`` or ``$fv1`` in some old code, however they are
0076 deprecated aliases of ``$fa0`` and ``$fa1`` respectively.
0077
0078 VRs
0079 ----
0080
0081 There are currently 2 vector extensions to LoongArch:
0082
0083 - LSX (Loongson SIMD eXtension) with 128-bit vectors,
0084 - LASX (Loongson Advanced SIMD eXtension) with 256-bit vectors.
0085
0086 LSX brings ``$v0`` ~ ``$v31`` while LASX brings ``$x0`` ~ ``$x31`` as the vector
0087 registers.
0088
0089 The VRs overlap with FPRs: for example, on a core implementing LSX and LASX,
0090 the lower 128 bits of ``$x0`` is shared with ``$v0``, and the lower 64 bits of
0091 ``$v0`` is shared with ``$f0``; same with all other VRs.
0092
0093 CSRs
0094 ----
0095
0096 CSRs can only be accessed from privileged mode (PLV0):
0097
0098 ================= ===================================== ==============
0099 Address Full Name Abbrev Name
0100 ================= ===================================== ==============
0101 0x0 Current Mode Information CRMD
0102 0x1 Pre-exception Mode Information PRMD
0103 0x2 Extension Unit Enable EUEN
0104 0x3 Miscellaneous Control MISC
0105 0x4 Exception Configuration ECFG
0106 0x5 Exception Status ESTAT
0107 0x6 Exception Return Address ERA
0108 0x7 Bad (Faulting) Virtual Address BADV
0109 0x8 Bad (Faulting) Instruction Word BADI
0110 0xC Exception Entrypoint Address EENTRY
0111 0x10 TLB Index TLBIDX
0112 0x11 TLB Entry High-order Bits TLBEHI
0113 0x12 TLB Entry Low-order Bits 0 TLBELO0
0114 0x13 TLB Entry Low-order Bits 1 TLBELO1
0115 0x18 Address Space Identifier ASID
0116 0x19 Page Global Directory Address for PGDL
0117 Lower-half Address Space
0118 0x1A Page Global Directory Address for PGDH
0119 Higher-half Address Space
0120 0x1B Page Global Directory Address PGD
0121 0x1C Page Walk Control for Lower- PWCL
0122 half Address Space
0123 0x1D Page Walk Control for Higher- PWCH
0124 half Address Space
0125 0x1E STLB Page Size STLBPS
0126 0x1F Reduced Virtual Address Configuration RVACFG
0127 0x20 CPU Identifier CPUID
0128 0x21 Privileged Resource Configuration 1 PRCFG1
0129 0x22 Privileged Resource Configuration 2 PRCFG2
0130 0x23 Privileged Resource Configuration 3 PRCFG3
0131 0x30+n (0≤n≤15) Saved Data register SAVEn
0132 0x40 Timer Identifier TID
0133 0x41 Timer Configuration TCFG
0134 0x42 Timer Value TVAL
0135 0x43 Compensation of Timer Count CNTC
0136 0x44 Timer Interrupt Clearing TICLR
0137 0x60 LLBit Control LLBCTL
0138 0x80 Implementation-specific Control 1 IMPCTL1
0139 0x81 Implementation-specific Control 2 IMPCTL2
0140 0x88 TLB Refill Exception Entrypoint TLBRENTRY
0141 Address
0142 0x89 TLB Refill Exception BAD (Faulting) TLBRBADV
0143 Virtual Address
0144 0x8A TLB Refill Exception Return Address TLBRERA
0145 0x8B TLB Refill Exception Saved Data TLBRSAVE
0146 Register
0147 0x8C TLB Refill Exception Entry Low-order TLBRELO0
0148 Bits 0
0149 0x8D TLB Refill Exception Entry Low-order TLBRELO1
0150 Bits 1
0151 0x8E TLB Refill Exception Entry High-order TLBEHI
0152 Bits
0153 0x8F TLB Refill Exception Pre-exception TLBRPRMD
0154 Mode Information
0155 0x90 Machine Error Control MERRCTL
0156 0x91 Machine Error Information 1 MERRINFO1
0157 0x92 Machine Error Information 2 MERRINFO2
0158 0x93 Machine Error Exception Entrypoint MERRENTRY
0159 Address
0160 0x94 Machine Error Exception Return MERRERA
0161 Address
0162 0x95 Machine Error Exception Saved Data MERRSAVE
0163 Register
0164 0x98 Cache TAGs CTAG
0165 0x180+n (0≤n≤3) Direct Mapping Configuration Window n DMWn
0166 0x200+2n (0≤n≤31) Performance Monitor Configuration n PMCFGn
0167 0x201+2n (0≤n≤31) Performance Monitor Overall Counter n PMCNTn
0168 0x300 Memory Load/Store WatchPoint MWPC
0169 Overall Control
0170 0x301 Memory Load/Store WatchPoint MWPS
0171 Overall Status
0172 0x310+8n (0≤n≤7) Memory Load/Store WatchPoint n MWPnCFG1
0173 Configuration 1
0174 0x311+8n (0≤n≤7) Memory Load/Store WatchPoint n MWPnCFG2
0175 Configuration 2
0176 0x312+8n (0≤n≤7) Memory Load/Store WatchPoint n MWPnCFG3
0177 Configuration 3
0178 0x313+8n (0≤n≤7) Memory Load/Store WatchPoint n MWPnCFG4
0179 Configuration 4
0180 0x380 Instruction Fetch WatchPoint FWPC
0181 Overall Control
0182 0x381 Instruction Fetch WatchPoint FWPS
0183 Overall Status
0184 0x390+8n (0≤n≤7) Instruction Fetch WatchPoint n FWPnCFG1
0185 Configuration 1
0186 0x391+8n (0≤n≤7) Instruction Fetch WatchPoint n FWPnCFG2
0187 Configuration 2
0188 0x392+8n (0≤n≤7) Instruction Fetch WatchPoint n FWPnCFG3
0189 Configuration 3
0190 0x393+8n (0≤n≤7) Instruction Fetch WatchPoint n FWPnCFG4
0191 Configuration 4
0192 0x500 Debug Register DBG
0193 0x501 Debug Exception Return Address DERA
0194 0x502 Debug Exception Saved Data Register DSAVE
0195 ================= ===================================== ==============
0196
0197 ERA, TLBRERA, MERRERA and DERA are sometimes also known as EPC, TLBREPC, MERREPC
0198 and DEPC respectively.
0199
0200 Basic Instruction Set
0201 =====================
0202
0203 Instruction formats
0204 -------------------
0205
0206 LoongArch instructions are 32 bits wide, belonging to 9 basic instruction
0207 formats (and variants of them):
0208
0209 =========== ==========================
0210 Format name Composition
0211 =========== ==========================
0212 2R Opcode + Rj + Rd
0213 3R Opcode + Rk + Rj + Rd
0214 4R Opcode + Ra + Rk + Rj + Rd
0215 2RI8 Opcode + I8 + Rj + Rd
0216 2RI12 Opcode + I12 + Rj + Rd
0217 2RI14 Opcode + I14 + Rj + Rd
0218 2RI16 Opcode + I16 + Rj + Rd
0219 1RI21 Opcode + I21L + Rj + I21H
0220 I26 Opcode + I26L + I26H
0221 =========== ==========================
0222
0223 Rd is the destination register operand, while Rj, Rk and Ra ("a" stands for
0224 "additional") are the source register operands. I8/I12/I14/I16/I21/I26 are
0225 immediate operands of respective width. The longer I21 and I26 are stored
0226 in separate higher and lower parts in the instruction word, denoted by the "L"
0227 and "H" suffixes.
0228
0229 List of Instructions
0230 --------------------
0231
0232 For brevity, only instruction names (mnemonics) are listed here; please see the
0233 :ref:`References <loongarch-references>` for details.
0234
0235
0236 1. Arithmetic Instructions::
0237
0238 ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D
0239 SLT SLTU SLTI SLTUI
0240 AND OR NOR XOR ANDN ORN ANDI ORI XORI
0241 MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU
0242 MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU
0243 PCADDI PCADDU12I PCADDU18I
0244 LU12I.W LU32I.D LU52I.D ADDU16I.D
0245
0246 2. Bit-shift Instructions::
0247
0248 SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W
0249 SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D
0250
0251 3. Bit-manipulation Instructions::
0252
0253 EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D
0254 BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D
0255 REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D
0256 MASKEQZ MASKNEZ
0257
0258 4. Branch Instructions::
0259
0260 BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL
0261
0262 5. Load/Store Instructions::
0263
0264 LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D
0265 LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D
0266 LDPTR.W LDPTR.D STPTR.W STPTR.D
0267 PRELD PRELDX
0268
0269 6. Atomic Operation Instructions::
0270
0271 LL.W SC.W LL.D SC.D
0272 AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D
0273 AMMAX.W AMMAX.D AMMIN.W AMMIN.D
0274
0275 7. Barrier Instructions::
0276
0277 IBAR DBAR
0278
0279 8. Special Instructions::
0280
0281 SYSCALL BREAK CPUCFG NOP IDLE ERTN(ERET) DBCL(DBGCALL) RDTIMEL.W RDTIMEH.W RDTIME.D
0282 ASRTLE.D ASRTGT.D
0283
0284 9. Privileged Instructions::
0285
0286 CSRRD CSRWR CSRXCHG
0287 IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D
0288 CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE
0289
0290 Virtual Memory
0291 ==============
0292
0293 LoongArch supports direct-mapped virtual memory and page-mapped virtual memory.
0294
0295 Direct-mapped virtual memory is configured by CSR.DMWn (n=0~3), it has a simple
0296 relationship between virtual address (VA) and physical address (PA)::
0297
0298 VA = PA + FixedOffset
0299
0300 Page-mapped virtual memory has arbitrary relationship between VA and PA, which
0301 is recorded in TLB and page tables. LoongArch's TLB includes a fully-associative
0302 MTLB (Multiple Page Size TLB) and set-associative STLB (Single Page Size TLB).
0303
0304 By default, the whole virtual address space of LA32 is configured like this:
0305
0306 ============ =========================== =============================
0307 Name Address Range Attributes
0308 ============ =========================== =============================
0309 ``UVRANGE`` ``0x00000000 - 0x7FFFFFFF`` Page-mapped, Cached, PLV0~3
0310 ``KPRANGE0`` ``0x80000000 - 0x9FFFFFFF`` Direct-mapped, Uncached, PLV0
0311 ``KPRANGE1`` ``0xA0000000 - 0xBFFFFFFF`` Direct-mapped, Cached, PLV0
0312 ``KVRANGE`` ``0xC0000000 - 0xFFFFFFFF`` Page-mapped, Cached, PLV0
0313 ============ =========================== =============================
0314
0315 User mode (PLV3) can only access UVRANGE. For direct-mapped KPRANGE0 and
0316 KPRANGE1, PA is equal to VA with bit30~31 cleared. For example, the uncached
0317 direct-mapped VA of 0x00001000 is 0x80001000, and the cached direct-mapped
0318 VA of 0x00001000 is 0xA0001000.
0319
0320 By default, the whole virtual address space of LA64 is configured like this:
0321
0322 ============ ====================== ======================================
0323 Name Address Range Attributes
0324 ============ ====================== ======================================
0325 ``XUVRANGE`` ``0x0000000000000000 - Page-mapped, Cached, PLV0~3
0326 0x3FFFFFFFFFFFFFFF``
0327 ``XSPRANGE`` ``0x4000000000000000 - Direct-mapped, Cached / Uncached, PLV0
0328 0x7FFFFFFFFFFFFFFF``
0329 ``XKPRANGE`` ``0x8000000000000000 - Direct-mapped, Cached / Uncached, PLV0
0330 0xBFFFFFFFFFFFFFFF``
0331 ``XKVRANGE`` ``0xC000000000000000 - Page-mapped, Cached, PLV0
0332 0xFFFFFFFFFFFFFFFF``
0333 ============ ====================== ======================================
0334
0335 User mode (PLV3) can only access XUVRANGE. For direct-mapped XSPRANGE and
0336 XKPRANGE, PA is equal to VA with bits 60~63 cleared, and the cache attribute
0337 is configured by bits 60~61 in VA: 0 is for strongly-ordered uncached, 1 is
0338 for coherent cached, and 2 is for weakly-ordered uncached.
0339
0340 Currently we only use XKPRANGE for direct mapping and XSPRANGE is reserved.
0341
0342 To put this in action: the strongly-ordered uncached direct-mapped VA (in
0343 XKPRANGE) of 0x00000000_00001000 is 0x80000000_00001000, the coherent cached
0344 direct-mapped VA (in XKPRANGE) of 0x00000000_00001000 is 0x90000000_00001000,
0345 and the weakly-ordered uncached direct-mapped VA (in XKPRANGE) of 0x00000000
0346 _00001000 is 0xA0000000_00001000.
0347
0348 Relationship of Loongson and LoongArch
0349 ======================================
0350
0351 LoongArch is a RISC ISA which is different from any other existing ones, while
0352 Loongson is a family of processors. Loongson includes 3 series: Loongson-1 is
0353 the 32-bit processor series, Loongson-2 is the low-end 64-bit processor series,
0354 and Loongson-3 is the high-end 64-bit processor series. Old Loongson is based on
0355 MIPS, while New Loongson is based on LoongArch. Take Loongson-3 as an example:
0356 Loongson-3A1000/3B1500/3A2000/3A3000/3A4000 are MIPS-compatible, while Loongson-
0357 3A5000 (and future revisions) are all based on LoongArch.
0358
0359 .. _loongarch-references:
0360
0361 References
0362 ==========
0363
0364 Official web site of Loongson Technology Corp. Ltd.:
0365
0366 http://www.loongson.cn/
0367
0368 Developer web site of Loongson and LoongArch (Software and Documentation):
0369
0370 http://www.loongnix.cn/
0371
0372 https://github.com/loongson/
0373
0374 https://loongson.github.io/LoongArch-Documentation/
0375
0376 Documentation of LoongArch ISA:
0377
0378 https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-CN.pdf (in Chinese)
0379
0380 https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-EN.pdf (in English)
0381
0382 Documentation of LoongArch ELF psABI:
0383
0384 https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-CN.pdf (in Chinese)
0385
0386 https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-EN.pdf (in English)
0387
0388 Linux kernel repository of Loongson and LoongArch:
0389
0390 https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson.git
