1.. SPDX-License-Identifier: GPL-2.0
2
3=========================
4Introduction to LoongArch
5=========================
6
7LoongArch is a new RISC ISA, which is a bit like MIPS or RISC-V. There are
8currently 3 variants: a reduced 32-bit version (LA32R), a standard 32-bit
9version (LA32S) and a 64-bit version (LA64). There are 4 privilege levels
10(PLVs) defined in LoongArch: PLV0~PLV3, from high to low. Kernel runs at PLV0
11while applications run at PLV3. This document introduces the registers, basic
12instruction set, virtual memory and some other topics of LoongArch.
13
14Registers
15=========
16
17LoongArch registers include general purpose registers (GPRs), floating point
18registers (FPRs), vector registers (VRs) and control status registers (CSRs)
19used in privileged mode (PLV0).
20
21GPRs
22----
23
24LoongArch has 32 GPRs ( ``$r0`` ~ ``$r31`` ); each one is 32-bit wide in LA32
25and 64-bit wide in LA64. ``$r0`` is hard-wired to zero, and the other registers
26are not architecturally special. (Except ``$r1``, which is hard-wired as the
27link register of the BL instruction.)
28
29The kernel uses a variant of the LoongArch register convention, as described in
30the LoongArch ELF psABI spec, in :ref:`References <loongarch-references>`:
31
32================= =============== =================== ============
33Name              Alias           Usage               Preserved
34                                                      across calls
35================= =============== =================== ============
36``$r0``           ``$zero``       Constant zero       Unused
37``$r1``           ``$ra``         Return address      No
38``$r2``           ``$tp``         TLS/Thread pointer  Unused
39``$r3``           ``$sp``         Stack pointer       Yes
40``$r4``-``$r11``  ``$a0``-``$a7`` Argument registers  No
41``$r4``-``$r5``   ``$v0``-``$v1`` Return value        No
42``$r12``-``$r20`` ``$t0``-``$t8`` Temp registers      No
43``$r21``          ``$u0``         Percpu base address Unused
44``$r22``          ``$fp``         Frame pointer       Yes
45``$r23``-``$r31`` ``$s0``-``$s8`` Static registers    Yes
46================= =============== =================== ============
47
48.. Note::
49    The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
50    kernel for storing the percpu base address. It normally has no ABI name,
51    but is called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1``
52    in some old code,however they are deprecated aliases of ``$a0`` and ``$a1``
53    respectively.
54
55FPRs
56----
57
58LoongArch has 32 FPRs ( ``$f0`` ~ ``$f31`` ) when FPU is present. Each one is
5964-bit wide on the LA64 cores.
60
61The floating-point register convention is the same as described in the
62LoongArch ELF psABI spec:
63
64================= ================== =================== ============
65Name              Alias              Usage               Preserved
66                                                         across calls
67================= ================== =================== ============
68``$f0``-``$f7``   ``$fa0``-``$fa7``  Argument registers  No
69``$f0``-``$f1``   ``$fv0``-``$fv1``  Return value        No
70``$f8``-``$f23``  ``$ft0``-``$ft15`` Temp registers      No
71``$f24``-``$f31`` ``$fs0``-``$fs7``  Static registers    Yes
72================= ================== =================== ============
73
74.. Note::
75    You may see ``$fv0`` or ``$fv1`` in some old code, however they are
76    deprecated aliases of ``$fa0`` and ``$fa1`` respectively.
77
78VRs
79----
80
81There are currently 2 vector extensions to LoongArch:
82
83- LSX (Loongson SIMD eXtension) with 128-bit vectors,
84- LASX (Loongson Advanced SIMD eXtension) with 256-bit vectors.
85
86LSX brings ``$v0`` ~ ``$v31`` while LASX brings ``$x0`` ~ ``$x31`` as the vector
87registers.
88
89The VRs overlap with FPRs: for example, on a core implementing LSX and LASX,
90the lower 128 bits of ``$x0`` is shared with ``$v0``, and the lower 64 bits of
91``$v0`` is shared with ``$f0``; same with all other VRs.
92
93CSRs
94----
95
96CSRs can only be accessed from privileged mode (PLV0):
97
98================= ===================================== ==============
99Address           Full Name                             Abbrev Name
100================= ===================================== ==============
1010x0               Current Mode Information              CRMD
1020x1               Pre-exception Mode Information        PRMD
1030x2               Extension Unit Enable                 EUEN
1040x3               Miscellaneous Control                 MISC
1050x4               Exception Configuration               ECFG
1060x5               Exception Status                      ESTAT
1070x6               Exception Return Address              ERA
1080x7               Bad (Faulting) Virtual Address        BADV
1090x8               Bad (Faulting) Instruction Word       BADI
1100xC               Exception Entrypoint Address          EENTRY
1110x10              TLB Index                             TLBIDX
1120x11              TLB Entry High-order Bits             TLBEHI
1130x12              TLB Entry Low-order Bits 0            TLBELO0
1140x13              TLB Entry Low-order Bits 1            TLBELO1
1150x18              Address Space Identifier              ASID
1160x19              Page Global Directory Address for     PGDL
117                  Lower-half Address Space
1180x1A              Page Global Directory Address for     PGDH
119                  Higher-half Address Space
1200x1B              Page Global Directory Address         PGD
1210x1C              Page Walk Control for Lower-          PWCL
122                  half Address Space
1230x1D              Page Walk Control for Higher-         PWCH
124                  half Address Space
1250x1E              STLB Page Size                        STLBPS
1260x1F              Reduced Virtual Address Configuration RVACFG
1270x20              CPU Identifier                        CPUID
1280x21              Privileged Resource Configuration 1   PRCFG1
1290x22              Privileged Resource Configuration 2   PRCFG2
1300x23              Privileged Resource Configuration 3   PRCFG3
1310x30+n (0≤n≤15)   Saved Data register                   SAVEn
1320x40              Timer Identifier                      TID
1330x41              Timer Configuration                   TCFG
1340x42              Timer Value                           TVAL
1350x43              Compensation of Timer Count           CNTC
1360x44              Timer Interrupt Clearing              TICLR
1370x60              LLBit Control                         LLBCTL
1380x80              Implementation-specific Control 1     IMPCTL1
1390x81              Implementation-specific Control 2     IMPCTL2
1400x88              TLB Refill Exception Entrypoint       TLBRENTRY
141                  Address
1420x89              TLB Refill Exception BAD (Faulting)   TLBRBADV
143                  Virtual Address
1440x8A              TLB Refill Exception Return Address   TLBRERA
1450x8B              TLB Refill Exception Saved Data       TLBRSAVE
146                  Register
1470x8C              TLB Refill Exception Entry Low-order  TLBRELO0
148                  Bits 0
1490x8D              TLB Refill Exception Entry Low-order  TLBRELO1
150                  Bits 1
1510x8E              TLB Refill Exception Entry High-order TLBEHI
152                  Bits
1530x8F              TLB Refill Exception Pre-exception    TLBRPRMD
154                  Mode Information
1550x90              Machine Error Control                 MERRCTL
1560x91              Machine Error Information 1           MERRINFO1
1570x92              Machine Error Information 2           MERRINFO2
1580x93              Machine Error Exception Entrypoint    MERRENTRY
159                  Address
1600x94              Machine Error Exception Return        MERRERA
161                  Address
1620x95              Machine Error Exception Saved Data    MERRSAVE
163                  Register
1640x98              Cache TAGs                            CTAG
1650x180+n (0≤n≤3)   Direct Mapping Configuration Window n DMWn
1660x200+2n (0≤n≤31) Performance Monitor Configuration n   PMCFGn
1670x201+2n (0≤n≤31) Performance Monitor Overall Counter n PMCNTn
1680x300             Memory Load/Store WatchPoint          MWPC
169                  Overall Control
1700x301             Memory Load/Store WatchPoint          MWPS
171                  Overall Status
1720x310+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG1
173                  Configuration 1
1740x311+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG2
175                  Configuration 2
1760x312+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG3
177                  Configuration 3
1780x313+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG4
179                  Configuration 4
1800x380             Instruction Fetch WatchPoint          FWPC
181                  Overall Control
1820x381             Instruction Fetch WatchPoint          FWPS
183                  Overall Status
1840x390+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG1
185                  Configuration 1
1860x391+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG2
187                  Configuration 2
1880x392+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG3
189                  Configuration 3
1900x393+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG4
191                  Configuration 4
1920x500             Debug Register                        DBG
1930x501             Debug Exception Return Address        DERA
1940x502             Debug Exception Saved Data Register   DSAVE
195================= ===================================== ==============
196
197ERA, TLBRERA, MERRERA and DERA are sometimes also known as EPC, TLBREPC, MERREPC
198and DEPC respectively.
199
200Basic Instruction Set
201=====================
202
203Instruction formats
204-------------------
205
206LoongArch instructions are 32 bits wide, belonging to 9 basic instruction
207formats (and variants of them):
208
209=========== ==========================
210Format name Composition
211=========== ==========================
2122R          Opcode + Rj + Rd
2133R          Opcode + Rk + Rj + Rd
2144R          Opcode + Ra + Rk + Rj + Rd
2152RI8        Opcode + I8 + Rj + Rd
2162RI12       Opcode + I12 + Rj + Rd
2172RI14       Opcode + I14 + Rj + Rd
2182RI16       Opcode + I16 + Rj + Rd
2191RI21       Opcode + I21L + Rj + I21H
220I26         Opcode + I26L + I26H
221=========== ==========================
222
223Rd is the destination register operand, while Rj, Rk and Ra ("a" stands for
224"additional") are the source register operands. I8/I12/I14/I16/I21/I26 are
225immediate operands of respective width. The longer I21 and I26 are stored
226in separate higher and lower parts in the instruction word, denoted by the "L"
227and "H" suffixes.
228
229List of Instructions
230--------------------
231
232For brevity, only instruction names (mnemonics) are listed here; please see the
233:ref:`References <loongarch-references>` for details.
234
235
2361. Arithmetic Instructions::
237
238    ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D
239    SLT SLTU SLTI SLTUI
240    AND OR NOR XOR ANDN ORN ANDI ORI XORI
241    MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU
242    MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU
243    PCADDI PCADDU12I PCADDU18I
244    LU12I.W LU32I.D LU52I.D ADDU16I.D
245
2462. Bit-shift Instructions::
247
248    SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W
249    SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D
250
2513. Bit-manipulation Instructions::
252
253    EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D
254    BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D
255    REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D
256    MASKEQZ MASKNEZ
257
2584. Branch Instructions::
259
260    BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL
261
2625. Load/Store Instructions::
263
264    LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D
265    LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D
266    LDPTR.W LDPTR.D STPTR.W STPTR.D
267    PRELD PRELDX
268
2696. Atomic Operation Instructions::
270
271    LL.W SC.W LL.D SC.D
272    AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D
273    AMMAX.W AMMAX.D AMMIN.W AMMIN.D
274
2757. Barrier Instructions::
276
277    IBAR DBAR
278
2798. Special Instructions::
280
281    SYSCALL BREAK CPUCFG NOP IDLE ERTN(ERET) DBCL(DBGCALL) RDTIMEL.W RDTIMEH.W RDTIME.D
282    ASRTLE.D ASRTGT.D
283
2849. Privileged Instructions::
285
286    CSRRD CSRWR CSRXCHG
287    IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D
288    CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE
289
290Virtual Memory
291==============
292
293LoongArch supports direct-mapped virtual memory and page-mapped virtual memory.
294
295Direct-mapped virtual memory is configured by CSR.DMWn (n=0~3), it has a simple
296relationship between virtual address (VA) and physical address (PA)::
297
298 VA = PA + FixedOffset
299
300Page-mapped virtual memory has arbitrary relationship between VA and PA, which
301is recorded in TLB and page tables. LoongArch's TLB includes a fully-associative
302MTLB (Multiple Page Size TLB) and set-associative STLB (Single Page Size TLB).
303
304By default, the whole virtual address space of LA32 is configured like this:
305
306============ =========================== =============================
307Name         Address Range               Attributes
308============ =========================== =============================
309``UVRANGE``  ``0x00000000 - 0x7FFFFFFF`` Page-mapped, Cached, PLV0~3
310``KPRANGE0`` ``0x80000000 - 0x9FFFFFFF`` Direct-mapped, Uncached, PLV0
311``KPRANGE1`` ``0xA0000000 - 0xBFFFFFFF`` Direct-mapped, Cached, PLV0
312``KVRANGE``  ``0xC0000000 - 0xFFFFFFFF`` Page-mapped, Cached, PLV0
313============ =========================== =============================
314
315User mode (PLV3) can only access UVRANGE. For direct-mapped KPRANGE0 and
316KPRANGE1, PA is equal to VA with bit30~31 cleared. For example, the uncached
317direct-mapped VA of 0x00001000 is 0x80001000, and the cached direct-mapped
318VA of 0x00001000 is 0xA0001000.
319
320By default, the whole virtual address space of LA64 is configured like this:
321
322============ ====================== ======================================
323Name         Address Range          Attributes
324============ ====================== ======================================
325``XUVRANGE`` ``0x0000000000000000 - Page-mapped, Cached, PLV0~3
326             0x3FFFFFFFFFFFFFFF``
327``XSPRANGE`` ``0x4000000000000000 - Direct-mapped, Cached / Uncached, PLV0
328             0x7FFFFFFFFFFFFFFF``
329``XKPRANGE`` ``0x8000000000000000 - Direct-mapped, Cached / Uncached, PLV0
330             0xBFFFFFFFFFFFFFFF``
331``XKVRANGE`` ``0xC000000000000000 - Page-mapped, Cached, PLV0
332             0xFFFFFFFFFFFFFFFF``
333============ ====================== ======================================
334
335User mode (PLV3) can only access XUVRANGE. For direct-mapped XSPRANGE and
336XKPRANGE, PA is equal to VA with bits 60~63 cleared, and the cache attribute
337is configured by bits 60~61 in VA: 0 is for strongly-ordered uncached, 1 is
338for coherent cached, and 2 is for weakly-ordered uncached.
339
340Currently we only use XKPRANGE for direct mapping and XSPRANGE is reserved.
341
342To put this in action: the strongly-ordered uncached direct-mapped VA (in
343XKPRANGE) of 0x00000000_00001000 is 0x80000000_00001000, the coherent cached
344direct-mapped VA (in XKPRANGE) of 0x00000000_00001000 is 0x90000000_00001000,
345and the weakly-ordered uncached direct-mapped VA (in XKPRANGE) of 0x00000000
346_00001000 is 0xA0000000_00001000.
347
348Relationship of Loongson and LoongArch
349======================================
350
351LoongArch is a RISC ISA which is different from any other existing ones, while
352Loongson is a family of processors. Loongson includes 3 series: Loongson-1 is
353the 32-bit processor series, Loongson-2 is the low-end 64-bit processor series,
354and Loongson-3 is the high-end 64-bit processor series. Old Loongson is based on
355MIPS, while New Loongson is based on LoongArch. Take Loongson-3 as an example:
356Loongson-3A1000/3B1500/3A2000/3A3000/3A4000 are MIPS-compatible, while Loongson-
3573A5000 (and future revisions) are all based on LoongArch.
358
359.. _loongarch-references:
360
361References
362==========
363
364Official web site of Loongson Technology Corp. Ltd.:
365
366  http://www.loongson.cn/
367
368Developer web site of Loongson and LoongArch (Software and Documentation):
369
370  http://www.loongnix.cn/
371
372  https://github.com/loongson/
373
374  https://loongson.github.io/LoongArch-Documentation/
375
376Documentation of LoongArch ISA:
377
378  https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-CN.pdf (in Chinese)
379
380  https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-EN.pdf (in English)
381
382Documentation of LoongArch ELF psABI:
383
384  https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-CN.pdf (in Chinese)
385
386  https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-EN.pdf (in English)
387
388Linux kernel repository of Loongson and LoongArch:
389
390  https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson.git
391