Documentation/loongarch/introduction.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================
   4 Introduction to LoongArch
   5 =========================
   6
   7 LoongArch is a new RISC ISA, which is a bit like MIPS or RISC-V. There are
   8 currently 3 variants: a reduced 32-bit version (LA32R), a standard 32-bit
   9 version (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
  11 while applications run at PLV3. This document introduces the registers, basic
  12 instruction set, virtual memory and some other topics of LoongArch.
  13
  14 Registers
  15 =========
  16
  17 LoongArch registers include general purpose registers (GPRs), floating point
  18 registers (FPRs), vector registers (VRs) and control status registers (CSRs)
  19 used in privileged mode (PLV0).
  20
  21 GPRs
  22 ----
  23
  24 LoongArch has 32 GPRs ( ``$r0`` ~ ``$r31`` ); each one is 32-bit wide in LA32
  25 and 64-bit wide in LA64. ``$r0`` is hard-wired to zero, and the other registers
  26 are not architecturally special. (Except ``$r1``, which is hard-wired as the
  27 link register of the BL instruction.)
  28
  29 The kernel uses a variant of the LoongArch register convention, as described in
  30 the LoongArch ELF psABI spec, in :ref:`References <loongarch-references>`:
  31
  32 ================= =============== =================== ============
  33 Name              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
  55 FPRs
  56 ----
  57
  58 LoongArch has 32 FPRs ( ``$f0`` ~ ``$f31`` ) when FPU is present. Each one is
  59 64-bit wide on the LA64 cores.
  60
  61 The floating-point register convention is the same as described in the
  62 LoongArch ELF psABI spec:
  63
  64 ================= ================== =================== ============
  65 Name              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
  78 VRs
  79 ----
  80
  81 There 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
  86 LSX brings ``$v0`` ~ ``$v31`` while LASX brings ``$x0`` ~ ``$x31`` as the vector
  87 registers.
  88
  89 The VRs overlap with FPRs: for example, on a core implementing LSX and LASX,
  90 the 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
  93 CSRs
  94 ----
  95
  96 CSRs can only be accessed from privileged mode (PLV0):
  97
  98 ================= ===================================== ==============
  99 Address           Full Name                             Abbrev Name
 100 ================= ===================================== ==============
 101 0x0               Current Mode Information              CRMD
 102 0x1               Pre-exception Mode Information        PRMD
 103 0x2               Extension Unit Enable                 EUEN
 104 0x3               Miscellaneous Control                 MISC
 105 0x4               Exception Configuration               ECFG
 106 0x5               Exception Status                      ESTAT
 107 0x6               Exception Return Address              ERA
 108 0x7               Bad (Faulting) Virtual Address        BADV
 109 0x8               Bad (Faulting) Instruction Word       BADI
 110 0xC               Exception Entrypoint Address          EENTRY
 111 0x10              TLB Index                             TLBIDX
 112 0x11              TLB Entry High-order Bits             TLBEHI
 113 0x12              TLB Entry Low-order Bits 0            TLBELO0
 114 0x13              TLB Entry Low-order Bits 1            TLBELO1
 115 0x18              Address Space Identifier              ASID
 116 0x19              Page Global Directory Address for     PGDL
 117                   Lower-half Address Space
 118 0x1A              Page Global Directory Address for     PGDH
 119                   Higher-half Address Space
 120 0x1B              Page Global Directory Address         PGD
 121 0x1C              Page Walk Control for Lower-          PWCL
 122                   half Address Space
 123 0x1D              Page Walk Control for Higher-         PWCH
 124                   half Address Space
 125 0x1E              STLB Page Size                        STLBPS
 126 0x1F              Reduced Virtual Address Configuration RVACFG
 127 0x20              CPU Identifier                        CPUID
 128 0x21              Privileged Resource Configuration 1   PRCFG1
 129 0x22              Privileged Resource Configuration 2   PRCFG2
 130 0x23              Privileged Resource Configuration 3   PRCFG3
 131 0x30+n (0≤n≤15)   Saved Data register                   SAVEn
 132 0x40              Timer Identifier                      TID
 133 0x41              Timer Configuration                   TCFG
 134 0x42              Timer Value                           TVAL
 135 0x43              Compensation of Timer Count           CNTC
 136 0x44              Timer Interrupt Clearing              TICLR
 137 0x60              LLBit Control                         LLBCTL
 138 0x80              Implementation-specific Control 1     IMPCTL1
 139 0x81              Implementation-specific Control 2     IMPCTL2
 140 0x88              TLB Refill Exception Entrypoint       TLBRENTRY
 141                   Address
 142 0x89              TLB Refill Exception BAD (Faulting)   TLBRBADV
 143                   Virtual Address
 144 0x8A              TLB Refill Exception Return Address   TLBRERA
 145 0x8B              TLB Refill Exception Saved Data       TLBRSAVE
 146                   Register
 147 0x8C              TLB Refill Exception Entry Low-order  TLBRELO0
 148                   Bits 0
 149 0x8D              TLB Refill Exception Entry Low-order  TLBRELO1
 150                   Bits 1
 151 0x8E              TLB Refill Exception Entry High-order TLBEHI
 152                   Bits
 153 0x8F              TLB Refill Exception Pre-exception    TLBRPRMD
 154                   Mode Information
 155 0x90              Machine Error Control                 MERRCTL
 156 0x91              Machine Error Information 1           MERRINFO1
 157 0x92              Machine Error Information 2           MERRINFO2
 158 0x93              Machine Error Exception Entrypoint    MERRENTRY
 159                   Address
 160 0x94              Machine Error Exception Return        MERRERA
 161                   Address
 162 0x95              Machine Error Exception Saved Data    MERRSAVE
 163                   Register
 164 0x98              Cache TAGs                            CTAG
 165 0x180+n (0≤n≤3)   Direct Mapping Configuration Window n DMWn
 166 0x200+2n (0≤n≤31) Performance Monitor Configuration n   PMCFGn
 167 0x201+2n (0≤n≤31) Performance Monitor Overall Counter n PMCNTn
 168 0x300             Memory Load/Store WatchPoint          MWPC
 169                   Overall Control
 170 0x301             Memory Load/Store WatchPoint          MWPS
 171                   Overall Status
 172 0x310+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG1
 173                   Configuration 1
 174 0x311+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG2
 175                   Configuration 2
 176 0x312+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG3
 177                   Configuration 3
 178 0x313+8n (0≤n≤7)  Memory Load/Store WatchPoint n        MWPnCFG4
 179                   Configuration 4
 180 0x380             Instruction Fetch WatchPoint          FWPC
 181                   Overall Control
 182 0x381             Instruction Fetch WatchPoint          FWPS
 183                   Overall Status
 184 0x390+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG1
 185                   Configuration 1
 186 0x391+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG2
 187                   Configuration 2
 188 0x392+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG3
 189                   Configuration 3
 190 0x393+8n (0≤n≤7)  Instruction Fetch WatchPoint n        FWPnCFG4
 191                   Configuration 4
 192 0x500             Debug Register                        DBG
 193 0x501             Debug Exception Return Address        DERA
 194 0x502             Debug Exception Saved Data Register   DSAVE
 195 ================= ===================================== ==============
 196
 197 ERA, TLBRERA, MERRERA and DERA are sometimes also known as EPC, TLBREPC, MERREPC
 198 and DEPC respectively.
 199
 200 Basic Instruction Set
 201 =====================
 202
 203 Instruction formats
 204 -------------------
 205
 206 LoongArch instructions are 32 bits wide, belonging to 9 basic instruction
 207 formats (and variants of them):
 208
 209 =========== ==========================
 210 Format name Composition
 211 =========== ==========================
 212 2R          Opcode + Rj + Rd
 213 3R          Opcode + Rk + Rj + Rd
 214 4R          Opcode + Ra + Rk + Rj + Rd
 215 2RI8        Opcode + I8 + Rj + Rd
 216 2RI12       Opcode + I12 + Rj + Rd
 217 2RI14       Opcode + I14 + Rj + Rd
 218 2RI16       Opcode + I16 + Rj + Rd
 219 1RI21       Opcode + I21L + Rj + I21H
 220 I26         Opcode + I26L + I26H
 221 =========== ==========================
 222
 223 Rd is the destination register operand, while Rj, Rk and Ra ("a" stands for
 224 "additional") are the source register operands. I8/I12/I16/I21/I26 are
 225 immediate operands of respective width. The longer I21 and I26 are stored
 226 in separate higher and lower parts in the instruction word, denoted by the "L"
 227 and "H" suffixes.
 228
 229 List of Instructions
 230 --------------------
 231
 232 For brevity, only instruction names (mnemonics) are listed here; please see the
 233 :ref:`References <loongarch-references>` for details.
 234
 235
 236 1. 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
 246 2. 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
 251 3. 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
 258 4. Branch Instructions::
 259
 260     BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL
 261
 262 5. 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
 269 6. 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
 275 7. Barrier Instructions::
 276
 277     IBAR DBAR
 278
 279 8. 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
 284 9. 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
 290 Virtual Memory
 291 ==============
 292
 293 LoongArch supports direct-mapped virtual memory and page-mapped virtual memory.
 294
 295 Direct-mapped virtual memory is configured by CSR.DMWn (n=0~3), it has a simple
 296 relationship between virtual address (VA) and physical address (PA)::
 297
 298  VA = PA + FixedOffset
 299
 300 Page-mapped virtual memory has arbitrary relationship between VA and PA, which
 301 is recorded in TLB and page tables. LoongArch's TLB includes a fully-associative
 302 MTLB (Multiple Page Size TLB) and set-associative STLB (Single Page Size TLB).
 303
 304 By default, the whole virtual address space of LA32 is configured like this:
 305
 306 ============ =========================== =============================
 307 Name         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
 315 User mode (PLV3) can only access UVRANGE. For direct-mapped KPRANGE0 and
 316 KPRANGE1, PA is equal to VA with bit30~31 cleared. For example, the uncached
 317 direct-mapped VA of 0x00001000 is 0x80001000, and the cached direct-mapped
 318 VA of 0x00001000 is 0xA0001000.
 319
 320 By default, the whole virtual address space of LA64 is configured like this:
 321
 322 ============ ====================== ======================================
 323 Name         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
 335 User mode (PLV3) can only access XUVRANGE. For direct-mapped XSPRANGE and
 336 XKPRANGE, PA is equal to VA with bits 60~63 cleared, and the cache attribute
 337 is configured by bits 60~61 in VA: 0 is for strongly-ordered uncached, 1 is
 338 for coherent cached, and 2 is for weakly-ordered uncached.
 339
 340 Currently we only use XKPRANGE for direct mapping and XSPRANGE is reserved.
 341
 342 To put this in action: the strongly-ordered uncached direct-mapped VA (in
 343 XKPRANGE) of 0x00000000_00001000 is 0x80000000_00001000, the coherent cached
 344 direct-mapped VA (in XKPRANGE) of 0x00000000_00001000 is 0x90000000_00001000,
 345 and the weakly-ordered uncached direct-mapped VA (in XKPRANGE) of 0x00000000
 346 _00001000 is 0xA0000000_00001000.
 347
 348 Relationship of Loongson and LoongArch
 349 ======================================
 350
 351 LoongArch is a RISC ISA which is different from any other existing ones, while
 352 Loongson is a family of processors. Loongson includes 3 series: Loongson-1 is
 353 the 32-bit processor series, Loongson-2 is the low-end 64-bit processor series,
 354 and Loongson-3 is the high-end 64-bit processor series. Old Loongson is based on
 355 MIPS, while New Loongson is based on LoongArch. Take Loongson-3 as an example:
 356 Loongson-3A1000/3B1500/3A2000/3A3000/3A4000 are MIPS-compatible, while Loongson-
 357 3A5000 (and future revisions) are all based on LoongArch.
 358
 359 .. _loongarch-references:
 360
 361 References
 362 ==========
 363
 364 Official web site of Loongson Technology Corp. Ltd.:
 365
 366   http://www.loongson.cn/
 367
 368 Developer 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
 376 Documentation of LoongArch ISA:
 377
 378   https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-CN.pdf (in Chinese)
 379
 380   https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-EN.pdf (in English)
 381
 382 Documentation of LoongArch ELF psABI:
 383
 384   https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-CN.pdf (in Chinese)
 385
 386   https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-EN.pdf (in English)
 387
 388 Linux kernel repository of Loongson and LoongArch:
 389
 390   https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson.git