Guide du développeur

Guides et notes sur le développement pour LoongArch

Lorsqu'on développe pour des systèmes autres que x86, beaucoup se posent sans doute la question suivante :

Où se trouve le SDK de cet appareil ?

Grâce aux efforts des contributeurs de la communauté et des ingénieurs de Loongson depuis 2021, la plupart des chaînes d'outils bénéficient désormais d'un support en amont.

Qu'est-ce que cela signifie ?

Cela signifie que la procédure d'installation des différentes chaînes d'outils de programmation est désormais similaire, voire identique, à celle de la plateforme x86 : leur installation est donc aussi simple que celle à partir des dépôts de la distribution, et ne nécessite qu'une seule ligne de commande à copier-coller !

TIP

Étant donné qu'ABI 2.0 (« New World ») est utilisé par la plupart des utilisateurs et développeurs de la communauté, ce guide se concentre exclusivement sur la présentation des procédures d'installation et de configuration des systèmes ABI 2.0. ABI 1.0 (« Old World ») n'est pas abordé ici. Si vous vous trouvez dans une situation où vous devez développer pour ABI 1.0, nous vous recommandons de reconsidérer ce choix et de vous assurer qu'il est bien justifié. Si cela s'avère nécessaire, veuillez vous reporter à la documentation disponible sur Communauté open source Loongson (loongnix.cn).


Chaîne d'outils GNU

GCC et Binutils prennent officiellement en charge LoongArch. Ils sont disponibles directement depuis le dépôt de votre distribution, sous forme de binaires, ou peuvent être compilés par compilation croisée.

TIP

Remarque : les versions ultérieures de GCC et de Binutils offrent une prise en charge améliorée de LoongArch. Notamment, GCC 14 a introduit la prise en charge des extensions vectorielles de LoongArch, tandis que Binutils 2.41 a introduit la prise en charge de la relaxation de l'éditeur de liens et, plus tard avec GCC 16, du modèle de code moyen (améliorant considérablement la compatibilité avec les projets source de grande envergure). Toutes ces évolutions constituent des améliorations fonctionnelles essentielles. Par conséquent, veuillez les mettre à jour au moins vers les versions susmentionnées.

Si vous avez l'intention de publier des binaires universels pour des projets ou de gérer une distribution Linux, veuillez lire attentivement les spécifications et contraintes applicables décrites dans le Conventions de développement et de compilation pour les architectures LoongArch.

Pour installer la chaîne d'outils GNU sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationProcédure d'installation
AOSC OSoma install binutils gcc
Arch Linuxsudo pacman -S binutils gcc
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install build-essential
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install binutils gcc

Si vous ne disposez pas d'un appareil LoongArch ou si vous souhaitez effectuer une compilation croisée :

Système d'exploitationProcédure d'installation
AOSC OSoma install gcc+cross-loongarch64
Debian 13 et versions ultérieures, Ubuntu 24.04 et versions ultérieures, ainsi que leurs dérivés respectifssudo apt install gcc-loongarch64-linux-gnu
Windows et autres distributions LinuxVeuillez effectuer l'installation à partir du dépôt GitHub loongson/outils-de-compilation

Chaîne d'outils LLVM

LLVM prend officiellement en charge LoongArch. Il est disponible directement depuis le dépôt de votre distribution, sous forme de binaires, ou peut être compilé par compilation croisée.

TIP

Remarque : les versions récentes de LLVM offrent une prise en charge améliorée de LoongArch. LLVM 18 a introduit la prise en charge des extensions vectorielles LoongArch. Si cette version est disponible, veuillez effectuer la mise à jour vers cette version ou une version ultérieure.

Si vous avez l'intention de publier des binaires universels pour des projets ou de gérer une distribution Linux, veuillez lire attentivement les spécifications et contraintes applicables décrites dans le Conventions de développement et de compilation pour les architectures LoongArch.

Pour installer LLVM (y compris Clang) sur les distributions Linux et les systèmes d'exploitation courants :

Systèmes d'exploitationProcédure d'installation
AOSC OSoma install llvm
Arch Linuxsudo pacman -S clang llvm
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install clang llvm
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install clang llvm

La chaîne d'outils LLVM (en particulier le compilateur Clang) prend en charge nativement la compilation croisée. Pour compiler cette chaîne d'outils de manière croisée pour LoongArch, utilisez la version 17 ou une version ultérieure de LLVM et consultez cet article et spécifiez la cible LoongArch (par exemple, loongarch64-unknown-linux-gnu).

Rust

Rust prend officiellement en charge LoongArch. Il est disponible directement depuis le dépôt de votre distribution, sous forme de binaires, ou peut être compilé par compilation croisée.

Rust recommande d'utiliser se rouiller Pour installer la chaîne d'outils Rust :

bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Pour installer Rust (rustc) et le gestionnaire de paquets Cargo sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationProcédure d'installation
AOSC OSoma install rustc
Arch Linuxsudo pacman -S rustc
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install rust-all
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install rust cargo

Node.js

Node.js prend officiellement en charge LoongArch. Il est disponible directement depuis le dépôt de votre distribution, sous forme de binaires, ou peut être compilé par compilation croisée. Node.js fournit des binaires LoongArch via le Versions non officielles projet (classé sous le tag loong64 architecture).

Pour installer Node.js sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationProcédure d'installation
AOSC OSoma install nodejs
Arch Linuxsudo pacman -S nodejs
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install nodejs
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install nodejs

TIP

De nombreuses distributions Linux proposent plusieurs versions de Node.js afin de répondre aux besoins de différentes applications et de différents projets. Veuillez consulter la documentation de votre distribution et installer d'autres versions de Node.js si nécessaire.

Go

Go prend officiellement en charge LoongArch. Il est disponible directement depuis le dépôt de votre distribution, sous forme de binaires, ou peut être compilé par compilation croisée. L'équipe en amont de Go compile des binaires LoongArch, qui sont disponibles sur leur Télécharger la page.

Pour installer Go sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationProcédure d'installation
AOSC OSoma install go
Arch Linuxsudo pacman -S go
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install golang
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install golang

Go prend en charge nativement la compilation croisée. À partir de la version 1.21 de Go, suivez les instructions décrites dans cet article et spécifier la cible LoongArch (c'est-à-dire, GOARCH=loong64) pour effectuer une compilation croisée pour LoongArch.

Python

Python prend officiellement en charge LoongArch. Il est disponible directement depuis le dépôt de votre distribution, sous forme de binaires, ou peut être compilé via une compilation croisée.

Pour installer Python sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationProcédure d'installation
AOSC OSoma install python-3
Arch Linuxsudo pacman -S python
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install python3
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install python3

TIP

Étant donné que LoongArch ne dispose pas encore d'une définition pour une base de référence « manylinux », le dépôt officiel PyPI n'héberge pas de binaires pour LoongArch. Cela signifie que lors de l'installation de modules PyPI à l'aide de pip, les modules correspondants seront compilés à partir du code source et vous devrez peut-être installer les chaînes d'outils C/C++/Rust si nécessaire.

Loongson Technology héberge un dépôt binaire PyPI pour les systèmes ABI 2.0 à l'adresse lpypi.loongnix.cn. Vous pouvez modifier /etc/pip.conf vers et définir celui-ci comme référentiel par défaut. Sinon, le long64 Une organisation sur GitHub gère un dépôt binaire PyPI indépendant. Pour connaître les procédures de configuration, veuillez vous reporter à le fichier README de l'organisation.

.NET

.NET prend officiellement en charge LoongArch. Cependant, LoongArch étant classée comme une « architecture prise en charge par la communauté » au sein de .NET, Microsoft ne fournit pas de chaînes d'outils binaires pour LoongArch.

Toutefois, les fichiers binaires de la chaîne d'outils .NET peuvent être obtenus par les moyens suivants :

Pour les distributions Linux courantes, il suffit de télécharger le package SDK associé au RID (identifiant du runtime .NET). linux-loongarch64 pour obtenir la chaîne d'outils complète (c'est-à-dire, dotnet-runtime-10.0.1-linux-loongarch64.tar.gz). Pour savoir comment installer le SDK .NET à l'aide de paquets tar, consultez le documentation officielle de .NET.

Compilation croisée d'applications .NET pour LoongArch ​

.NET prend en charge nativement la compilation croisée et la publication multiplateforme. À partir de .NET 9, consultez cet article et de préciser le RID cible pour publier des applications .NET destinées à LoongArch. Cependant, LoongArch étant classée comme une « architecture prise en charge par la communauté » pour .NET, NuGet.org n'héberge pas de paquets d'exécution .NET ciblant LoongArch, ce qui peut entraîner des échecs de compilation.

Pour contourner ce problème, vous pouvez télécharger et installer localement tous les packages NuGet nécessaires. Pour ce faire, il vous suffit de télécharger les fichiers suivants à partir des pages de publication de la chaîne d'outils mentionnées ci-dessus (le signe * indique des numéros de version spécifiques) :

  • Microsoft.AspNetCore.App.Runtime.linux-loongarch64.*.nupkg
  • Microsoft.NETCore.App.Crossgen2.linux-loongarch64..nupkg Microsoft.NETCore.App.Host.linux-loongarch64..nupkg
  • Microsoft.NETCore.App.Runtime.linux-loongarch64.*.nupkg
  • runtime.linux-loongarch64.Microsoft.DotNet.ILCompiler.*.nupkg

TIP

La distribution fournie par loongson-community/dotnet-unofficial-build classe les fichiers susmentionnés dans la catégorie « artefacts de version ». Veuillez télécharger ce paquet pour obtenir les composants énumérés ci-dessus.

Placez les fichiers ci-dessus dans un répertoire de votre choix (par exemple, /data/loongarch64-nupkgs) et suivez les instructions données dans cet article pour ajouter ce répertoire à votre liste de sources NuGet, comme indiqué ci-dessous :

xml
<packageSources>
    <add key="LoongArch64 Packages" value="/data/loongarch64-nupkgs" />
</packageSources>

Vous devriez désormais pouvoir compiler de manière croisée des applications .NET pour LoongArch.

Compilation de la chaîne d'outils .NET ​

La compilation de la chaîne d'outils .NET est en soi un processus relativement complexe. Pour faciliter votre prise en main, veuillez vous reporter au Scripts de compilation CI utilisés par Loongson Technology. Cette méthode utilise le package de distribution des sources VMR officiellement recommandé par .NET pour la compilation.

Java

Pour des raisons non techniques, Oracle OpenJDK ne prend actuellement pas en charge le JIT LoongArch. Pour installer Java, il est recommandé de télécharger les paquets binaires compatibles avec le « noyau Linux 5.10.0 UAPI » sur le Communauté open source Loongson (loongnix.cn) ou via le dépôt de votre distribution.

Pour installer Java sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationProcédures d'installation
AOSC OSoma install openjdk
Arch Linuxsudo pacman -S java-openjdk
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install default-jdk
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install java-latest-openjdk

TIP

De nombreuses distributions Linux proposent plusieurs versions d'OpenJDK afin de répondre aux besoins de différentes applications et de différents projets. Veuillez consulter la documentation de votre distribution et installer d'autres versions d'OpenJDK si nécessaire.

Noyau Linux

Le noyau Linux prend officiellement en charge LoongArch. En règle générale, les distributions Linux basées sur l'ABI 2.0 utilisent le noyau en amont (accompagné de solutions de contournement spécifiques à la plate-forme et d'autres correctifs, voir ci-dessous). Cependant, certaines distributions commerciales fournissent le noyau 6.6 « longterm » avec un ensemble complet de correctifs spécifiques à la plate-forme.

TIP

Le noyau Linux prend en charge LoongArch depuis la version 5.19. Toutefois, pour tirer pleinement parti des capacités matérielles et des performances de LoongArch, veuillez utiliser la dernière version du noyau principal.

Guide de maintenance du noyau ​

Comme indiqué ci-dessus, les noyaux Linux plus récents sont généralement préférables en raison de leur meilleure prise en charge des périphériques LoongArch. Cependant, comme les distributions peuvent avoir leurs propres règles en matière de mises à jour du noyau, nous avons élaboré le guide ci-dessous à titre de référence.

Version LinuxNouveauté principale
7.1.4Correction de la vitesse PCIe pour les modèles 3B6000/3C6000
7.1.1Prise en charge de la région SystemIO ACPI
7.1Prise en charge du DMA multicanal pour les modèles 2K0300/2K3000/3B6000M
6.18Corrections GPIO pour les modèles 2K2000/2K3000/3B6000M
6.17Prise en charge DWMAC pour la carte réseau intégrée 2K3000/3B6000M ; correction de la modulation de fréquence PWM
6.16Prise en charge SDIO pour les modèles 2K2000/2K3000/3B6000M
6.14Prise en charge du multiplexage de la famille 3C6000
6.12Prise en charge de la famille 3B6000/3C6000 (modèle IRQ étendu avancé)
6.7Prise en charge de la virtualisation
6.4Prise en charge du multithreading simultané (SMT)

Correctifs non intégrés ​

En règle générale, les ingénieurs de Loongson Technology et les développeurs de la communauté transmettent au noyau en amont (branche principale) les mises en œuvre matérielles, les optimisations et les corrections. Cependant, pour des raisons techniques et non techniques, certains correctifs ne sont pas intégrés.

Le tableau ci-dessous répertorie tous les correctifs connus et indispensables gérés par divers acteurs en aval (développeurs, communautés de distribution, etc.), à titre de référence (la liste de correctifs ci-dessous est basée sur v7.1.4 et n'incluez pas les correctifs déjà intégrés dans le en amont):

DescriptionEntrée Kconfig (ajoutée/modifiée)LienRemarques
Périphériques PixArt PS/2Ajouté le : MOUSE_PS2_PIXART (booléen : oui/non)1Pour les ordinateurs portables tels que le Tongfang Chaorui L860-T2 et l'EA EXCELSIOR L71 équipés des puces 3A5000 et 3A6000, ce correctif résout un problème qui entraînait l'identification erronée des pavés tactiles comme des souris PS/2, ce qui empêchait la prise en charge des gestes et de la détection de la paume.
Prise en charge de HWMon (surveillance thermique et autres formes de surveillance matérielle), permettant le contrôle thermique du processeur pour la gamme Loongson 3Ajouté : CPU_HWMON (booléen : oui/non)1N'inclut pas la prise en charge de la surveillance thermique de la puce « 7A bridge » ; sur les plateformes 3C6000 et plus récentes, le micrologiciel version 202511 ou ultérieure représente déjà ce capteur comme une zone thermique ACPI, ce qui rend ce correctif inutile
Bus CAN-FD du SoC 2K3000/3B6000MAjouté : CAN_LSCANFD (booléen : oui/non), CAN_LSCANFD_PLATFORM (tristate : y/m/n)1Doit être utilisé avec le noyau Linux 7.1 ou une version plus récente prenant en charge le DMA multicanal
Prise en charge du micrologiciel BPI1000/1001 (« Old World »)N/A1, 2, 3, 4, 5, 6, 7, 8Indispensable pour démarrer les systèmes ABI 2.0 sur les serveurs à quatre sockets Lenovo Kaitian M540z et Gooxi 3C5000L, ainsi que sur certaines plateformes équipées du micrologiciel Kunlun commercialisées entre 2020 et 2022.
Prise en charge de l'analyse des propriétés d'horloge et du réglage de la vitesse du bus du contrôleur I2C LoongsonCONFIG_LS2X_I2C1L'absence de cette fonctionnalité entraîne un décalage au niveau du pavé tactile de certains ordinateurs portables 3B6000M.
Mise à jour du protocole du micrologiciel SMCv2CONFIG_LOONGSON3_CPUFREQ1L'absence de cette mise à jour peut entraîner un échec du démarrage avec la version 202605 du micrologiciel si la fonction DVFS est activée ; veuillez également noter que la version 202605 est expérimentale
Solution de contournement pour les GPIO inopérants en raison de descriptions de périphériques qui ne sont conformes qu'à une ancienne version de la Spécification d'architecture système unifiée des processeurs Loongson, dans laquelle les périphériques GPIO étaient décrits au sein de gsi_idx_mapCONFIG_GPIO_LOONGSON_64BIT1Ne devrait pas affecter les modèles 2K3000/3B6000M et les versions ultérieures
Solution de contournement pour les plantages, réinitialisations et blocages intermittents du pilote avec les cartes graphiques AMD GCN 1.0–4.0 sur les plateformes LoongArchCONFIG_DRM_AMDGPU1Le mécanisme à l'origine de cette solution de contournement n'est pas clair (correctif empirique) ; celle-ci ne permet pas d'éviter complètement ces problèmes, mais se contente d'en réduire la probabilité ; les noyaux 6.6 commerciaux, tels que ceux de Deepin, intègrent un ensemble de correctifs plus agressif (mais tout aussi inexpliqué). Voir cette demande de modification Deepin.
Solution de contournement pour les erreurs de données survenant sur les plateformes 7A lors de l'utilisation des pilotes graphiques AMD « Radeon » (pour les cartes graphiques TeraScale 2 et antérieures)CONFIG_DRM_RADEON1, 2, 3Mécanisme inconnu (le message de commit n'est pas techniquement correct) mais efficace ; le patch 3 limite cette solution de contournement aux plateformes MIPS et LoongArch64 (MACH_LOONGSON64)
Enregistrer le troisième contrôleur PWM LOON0006:03 sur le pont 7A2000 en tant que gsgpu_backlight dans le code d'initialisation ACPI au niveau de la carte mère pour prendre en charge le contrôle du rétroéclairage par LoongGPUCONFIG_PWM_LOONGSON1Correctif préalable pour la prise en charge du rétroéclairage par LoongGPU. Pour les correctifs liés au pilote LoongGPU, veuillez vous reporter à AOSC-Tracking/loonggpu-kernel-dkms @ aosc/v1.0.1-alpha-lnd25.5.
Activer la prise en charge du « réveil à distance » pour les concentrateurs USB de niveau supérieur (tels que les claviers USB, les souris et autres périphériques d'entrée)CONFIG_USB1, 2L'application de ce correctif active la fonction de réveil par le clavier pour les appareils LoongArch en mode ACPI S3 (mise en veille en mémoire vive), mais il est connu pour empêcher certains ordinateurs portables x86 de passer en mode veille. Le correctif 2 limite cette solution de contournement aux plateformes MIPS et LoongArch64 (MACH_LOONGSON64).
Réinitialisation de l'état d'activation du rétroéclairage dans la routine de mise en veille/reprise S3 du pilote loongson-laptopCONFIG_LOONGSON_LAPTOP1Solution de contournement du problème lié au micrologiciel de certains ordinateurs portables 3B6000M, qui entraîne la désactivation du rétroéclairage après la sortie du mode S3
Détecter et désactiver sc.q en cas de comportement erratiqueN/A1Cette solution de contournement est nécessaire pour démarrer le noyau sur certaines implémentations de micrologiciel de la plateforme 2K3000/3B6000M présentant des bogues, qui configurent incorrectement le cœur LA364E et entraînent l'écriture de données erronées par l'instruction sc.q ; cette solution de contournement est incomplète, car les programmes de l'espace utilisateur peuvent toujours obtenir des résultats erronés s'ils n'ont pas protégé l'utilisation de sc.q via AT_HWCAP Vérifiez ; il est recommandé de mettre à jour le micrologiciel pour résoudre le problème
Prise en charge des périphériques I2C HID décrits en tant qu'ACPI PRP0001 nœud avec _DSM méthodeCONFIG_I2C_HID_ACPI1Certains ordinateurs portables, comme le Lenovo Kaitian N60d-G1d et l'Inspur Yingzheng, décrivent le pavé tactile selon cette méthode et nécessitent donc ce correctif pour que celui-ci fonctionne
Prise en charge des pages de 16 KiB pour Intel XeCONFIG_DRM_XE1 2 3 4 5 6Nécessaire pour utiliser une carte graphique Intel avec le noyau à pages de 16 KiB privilégié par la plupart des distributions LoongArch ; il n'est toutefois pas recommandé d'acheter une carte Intel pour la plateforme LoongArch, car le micrologiciel ne peut pas l'utiliser comme périphérique de sortie

Docker

Docker (utilitaire) prend désormais officiellement en charge LoongArch, généralement disponible dans le dépôt de votre distribution.

Pour installer Docker sur les distributions Linux et les systèmes d'exploitation courants :

Système d'exploitationMéthode d'installation
AOSC OSoma install docker
Arch Linuxsudo pacman -S docker
Debian et ses dérivés tels que deepin, openKylin et Loongnix 25sudo apt install docker.io
Distributions dérivées de Red Hat telles que Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOSsudo dnf install docker

TIP

Il n'y a que très peu de conteneurs LoongArch disponibles dans le registre officiel de Docker. Loongson Technology gère un Référentiel d'images Docker destiné à l'ABI 2.0 de LoongArch. Vous pouvez modifier votre configuration Docker pour utiliser ce registre selon les besoins.

Exécuteurs CI

De nombreuses plateformes d'hébergement de code prennent en charge les environnements d'exécution d'intégration continue (CI), et certaines prennent déjà en charge LoongArch de manière native.

GitHub Actions ​

Le runner GitHub Actions n'a pas pu générer de versions binaires en raison de NuGet ne prend pas en charge LoongArch. Si vous souhaitez compiler et déployer vous-même cet agent CI, veuillez consulter ce demande de modification.

GitLab Runner ​

GitLab Runner prend officiellement en charge LoongArch. Pour effectuer le déploiement, il suffit de télécharger et d'installer les paquets ou les archives compressées portant la balise loong64 à partir de son page de publication.

Gitea act_runner ​

Gitea act_runner prend officiellement en charge LoongArch, bien que les binaires LoongArch ne soient pas encore disponibles. Pour l'instant, vous pouvez cloner le source code pour compiler et déployer ce runner.

Forgejo Runner ​

Forgejo Runner n'a pas encore intégré la prise en charge de LoongArch. Si vous souhaitez compiler et déployer ce runner vous-même, veuillez consulter cette page demande de modification.

Sourcehut ​

Sourcehut's CI proxy builds.sr.ht prend officiellement en charge LoongArch. Étant donné que ce runner CI ne distribue pas de binaires, vous devrez compiler et déployer ce runner à partir du code source.

GitHub

Gitee n'a pas encore intégré la prise en charge de LoongArch. Si vous souhaitez compiler et déployer vous-même ce runner, veuillez vous reporter aux pull requests suivantes :

GitCode ​

Comme l'ont demandé certains membres de la communauté, GitCode ne prend actuellement pas en charge les proxys CI auto-hébergés ; il n'est donc pas possible de prendre en charge LoongArch, du moins pour l'instant.