From Gentoo Wiki
Jump to:navigation Jump to:search
LoongArch Development
Description The LoongArch Development Project is devoted to keeping Gentoo in good shape on the LoongArch architecture.
Project email
Packages p.g.o/

IRC channel #gentoo-loong (webchat)
Bugs Related bugs
Lead(s) none
No lead election date set
(and inherited member(s))
Parent Project Gentoo
Project listing

The LoongArch Development Project is an effort to bring first-class support for the LoongArch CPU architecture (龙架构; 龍架構; Lóng-jiàgòu; 'Loong Architecture') to Gentoo. Because this is such a new platform with many fundamental pieces of software still under development, we also strive to make Gentoo/LoongArch the ideal testing ground for the wider community, so as to minimize the risk of overlooked mistakes going upstream.

Basic facts

  • We are ARCH=loong. We don't use stable keywords for the moment.
  • Target tuple is loongarch64-unknown-linux-gnu. (Official spec says the LP64D ABI is loongarch64-unknown-linux-gnuf64, at least for Debian, but loongarch64-unknown-linux-gnu without the suffix behaves the same for compatibility and aesthetics.)
  • All LoongArch systems are little-endian.
  • LoongArch is not binary compatible with either MIPS or RISC-V, although the ISA and ABI show heavy influence of the two.
  • There are six ABIs defined for LoongArch, much like those of RISC-V. But for Gentoo, we intend to focus on LP64D only first. Multilib support will come later if truly necessary.

Applicable CPU models

Loongson only recently abruptly switched to the in-house LoongArch architecture because of their breakup with MIPS. As a result, it can be hard to tell whether a particular Loongson chip is implementing LoongArch or MIPS, especially for casual users.

A rule of thumb is checking the release date of the model at hand -- all Loongson cores from before 2021 are MIPS. For your checking convenience, most currently known LoongArch models are listed below.

  • Loongson products
    • 2K0500
    • 2K1000LA
    • 3A5000
    • 3A5000L ("Low-power")
    • 3A5000HV ("High Voltage")
    • 3B5000
    • 3C5000
    • 3C5000L (4 3A5000 dies in one package)
    • 3C5000LL (may be early versions of the 3C5000L)
  • Licensed implementations
    • XL621xx from XeL Tech (LA264 micro-architecture; found in their network switch products)

All earlier models are MIPS, some of the more famous names are:

  • Loongson 2E/2F/2K1000
  • Loongson 3x4000 and earlier

Binary compatibility with other distros

Gentoo/LoongArch belongs to the new world, just like any other properly open-sourced community distribution for LoongArch.

This does mean that all current commercial/closed-source offerings for LoongArch are unusable on Gentoo, such as Kingsoft Office (WPS Office) or LATX (Loongson Architecture Translator for X86; the Loongson binary translation solution allegedly based on QEMU and Wine but not open-source, supporting a subset of Windows applications and games), which are all compiled on, and for commercial distributions like Loongnix (pseudo-open-source), Kylin and UOS, that are the collective old world.

The two worlds differ both in kernel and user-space ABIs, so neither mixing-and-matching of binaries and libraries, nor full-fledged chroots will work. One consequence is that one has to pay attention to the flavor of live media used for installation or system rescue purposes; in particular, only new-world distributions can be used for bootstrapping Gentoo.

There are a few currently known new-world distributions:

You can read more about the new-world vs. old-world situation in the unofficial FAQ.


Everything mostly works as of Oct 2022. Software-accelerated GUI (llvmpipe) and AMD discrete graphics work with bleeding-edge LLVM 16, while support for the LS7A integrated graphics is not upstream yet.

LiveCD used to work but was reported to have initrd problems, and is not currently officially produced. In the meantime, any other new-world boot media can be used to install Gentoo.

Starting from 2022-10-13, official stage tarballs are produced by releng and available at the official Gentoo mirrors.

Profiles and initial sets of keywords sufficient for building stage3 are already upstreamed as of 2022-04-29, further keywording work will primarily happen in ::gentoo. The loongson-overlay remains available for general experimentation.

State of important non-upstreamed packages

While most of the fundamental software already has LoongArch support, there are still some patches floating around, waiting for the respective upstream to pick up. For the Gentoo builds, the more intrusive ones are only applied when USE=experimental-loong, force-enabled on loong while being masked on other arches. The other safer patches are applied unconditionally.

The table lists the known-good versions for packages that still haven't merged LoongArch support. Status for other packages are simply represented with the proper keyword (i.e. ~loong).

Package Known-good version Reason
sys-libs/libseccomp 2.5.4-r1::gentoo Waiting to be merged; guarded by USE=experimental-loong.

How to run it?

Trying out the stages

It's of course best to have actual LoongArch hardware to play with; any model will do, as currently there is only one hardware implementation of LoongArch that is the 3A5000. There are many form factors available, from laptops and MATX boards to rack-mounted servers, but it can be hard to purchase outside of China right now.

Fortunately, there is working QEMU support for both linux-user and system emulation starting from QEMU 7.1.0. Just enable the loongarch64 target then:

FILE /etc/portage/package.use
app-emulation/qemu QEMU_SOFTMMU_TARGETS: loongarch64
app-emulation/qemu QEMU_USER_TARGETS: loongarch64

binfmt_misc configuration for both OpenRC and systemd should be automatically generated and installed. Afterwards just chroot like with any other Gentoo installation.

Cross-compiling for LoongArch

sys-devel/crossdev can be used to conveniently make LoongArch cross toolchains, just make sure you're using up-to-date crossdev:

user $sudo crossdev -t loongarch64-unknown-linux-gnu

You may optionally pin the versions for the various components to your liking, or in case you see failures.

Developer resources

Loongson has generously provided Gentoo with a 3C5000L server, available for arch testing and general Gentoo work. See the developer machines page for details.

External resources

Beware that for most of the resources, the Chinese version is the original, and there can be all sorts of translation errors, especially in those provided by Loongson. You can ask on IRC or consult one of your Chinese developer friends when in doubt.

Historical stages are still available at several Chinese mirrors:

  • [1] hosted by Aliyun (Alibaba Cloud; 阿里云; 阿里雲)
  • [2] hosted by Tencent Cloud (腾讯云; 騰訊雲)
  • [3] hosted by Tsinghua University (清华大学; 清華大學)
  • [4] hosted by Beijing Foreign Studies University (北京外国语大学; 北京外國語大學)
  • [5] hosted by University of Science and Technology of China (中国科学技术大学; 中國科學技術大學)