|Description||The LoongArch Development Project is devoted to keeping Gentoo in good shape on the LoongArch architecture.|
|IRC channel||#gentoo-loong (webchat)|
No lead election date set
(and inherited member(s))
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.
- 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.
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 except the GUI (no upstream LLVM support = no AMDGPU support = no discrete graphics; support for the LS7A integrated graphics is not upstream), but serial console and networking works perfectly.
LiveCD used to work but is reported to have initrd problems; in the meantime, any other new-world boot media can be used to install Gentoo.
Depending on code review progress and release cadence of various projects, the possibility of forced re-installation currently cannot be ruled out. This would happen, for example, if the glibc port doesn't make it into the 2.36 release due August 2022; that necessitates changing the default version of libc symbols to 2.37 instead of the currently projected 2.36, rendering all previously built dynamic-linked binaries incompatible. This is brand-new architecture with limited corporate-backing R&D power, and users should be aware of the fact.
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 packages
Because the architecture is still in its infancy, LoongArch support for many essential packages is still missing from upstream, aggravated by the fact that Loongson has not much experience in developing and upstreaming a brand-new architecture like this (and limited English communication abilities). Hence, many packages require patching to work on LoongArch; the more intrusive patches are only applied when USE=experimental-loong, force-enabled on loong while being masked on other arches. The other safer patches are applied unconditionally.
||Linux port not upstreamed. Guarded by USE=experimental-loong.|
||All necessary patches are included in the Gentoo patchset.|
||Already upstream; suitable for consumption.|
||Still pending review; this is technically 2.36, but it applies cleanly to 2.35 too so we don't have to use live ebuild. Guarded by USE=experimental-loong.|
||Waiting to be merged; guarded by USE=experimental-loong.|
||Blocked by inclusion of Linux port; guarded by USE=experimental-loong.|
||With LoongArch ABI support.|
How to run this?
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 linux-user emulation, provided by the app-emulation/qemu package in ::loongson. Just enable the loongarch64 target:
# System emulation is present, but buggy, so not shown here (would be "loongarch64" too) 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.
System emulation support for LoongArch is present in this forked qemu version, but is too buggy to be usable. The package will be updated in ::loongson once the situation improves.
The Loongson development fork of qemu is even more unusable. As of 04/17/2022, the linux-user support was temporarily removed due to it being not mergeable before upstream acceptance of the Linux port; and system emulation was heavily stripped down, to the point that only make check-tcg tests would work.
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:
sudo crossdev -t loongarch64-unknown-linux-gnu
You may optionally pin the versions for the various components to your liking, or if you see failures.
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.
- The unofficial yet comprehensive FAQ for LoongArch by xen0n
- Unofficial collection of various Loongson docs by the community (not all of them are LoongArch-related)
- The official LoongArch documentation by Loongson
Historical stages are still available at several Chinese mirrors: