Руководство для разработчиков
Руководства и рекомендации по разработке для LoongArch
При разработке для систем, отличных от x86, у многих может возникнуть вопрос:
Где можно найти SDK для этого устройства?
Благодаря усилиям участников сообщества и инженеров Loongson, предпринимаемым с 2021 года, большинство наборов инструментов теперь поддерживаются в основных репозиториях.
Что это значит?
Это означает, что процесс установки различных наборов инструментов для программирования теперь аналогичен, если не идентичен, процессу на платформе x86 — то есть их установка стала такой же простой, как установка из репозиториев дистрибутива, и для этого достаточно ввести всего одну команду!
TIP
Учитывая, что ABI 2.0 («New World») используется большинством пользователей и разработчиков сообщества, данное руководство посвящено исключительно описанию процедур установки и настройки систем ABI 2.0. ABI 1.0 («Old World») в данном документе не рассматривается. Если вам приходится вести разработку для ABI 1.0, мы рекомендуем пересмотреть это решение и убедиться в его обоснованности. В случае возникновения такой необходимости, пожалуйста, обратитесь к документации по адресу Сообщество открытого исходного кода Loongson (loongnix.cn).
Набор инструментов GNU
GCC и Binutils официально поддерживают LoongArch. Их можно получить напрямую из репозитория вашего дистрибутива в виде бинарных файлов или скомпилировать с помощью кросс-компиляции.
TIP
Примечание: В более поздних версиях GCC и Binutils реализована расширенная поддержка LoongArch. В частности, в GCC 14 появилась поддержка векторных расширений LoongArch, а в Binutils 2.41 — поддержка смягчения ограничений компоновщика, а позже, начиная с GCC 16, — поддержка модели кода среднего уровня (что значительно улучшило совместимость с крупными проектами исходного кода). Все эти изменения представляют собой важные функциональные усовершенствования. В связи с этим рекомендуется обновить их как минимум до указанных выше версий.
Если вы планируете выпускать универсальные бинарные файлы для проектов или заниматься поддержкой дистрибутива Linux, пожалуйста, внимательно ознакомьтесь с соответствующими требованиями и ограничениями, изложенными в Правила разработки и сборки программного обеспечения для архитектур LoongArch.
Чтобы установить набор инструментов GNU в распространенных дистрибутивах Linux и операционных системах:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install binutils gcc |
| Arch Linux | sudo pacman -S binutils gcc |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install build-essential |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install binutils gcc |
Если у вас нет устройства LoongArch или вы хотите выполнить кросс-компиляцию:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install gcc+cross-loongarch64 |
| Debian 13 и более поздние версии, Ubuntu 24.04 и более поздние версии, а также их соответствующие производные | sudo apt install gcc-loongarch64-linux-gnu |
| Windows и другие дистрибутивы Linux | Пожалуйста, установите из репозитория GitHub loongson/инструменты сборки |
Набор инструментов LLVM
LLVM официально поддерживает LoongArch. Его можно установить напрямую из репозитория вашего дистрибутива в виде бинарных файлов или скомпилировать с помощью кросс-компиляции.
TIP
Примечание: В более поздних версиях LLVM реализована расширенная поддержка LoongArch. В LLVM 18 добавлена поддержка векторных расширений LoongArch. Если такая версия доступна, рекомендуется обновиться до неё или более поздней версии.
Если вы планируете выпускать универсальные бинарные файлы для проектов или заниматься поддержкой дистрибутива Linux, пожалуйста, внимательно ознакомьтесь с соответствующими требованиями и ограничениями, изложенными в Правила разработки и сборки программного обеспечения для архитектур LoongArch.
Чтобы установить LLVM (включая Clang) в распространенных дистрибутивах Linux и операционных системах:
| Операционные системы | Порядок установки |
|---|---|
| ОС AOSC | oma install llvm |
| Arch Linux | sudo pacman -S clang llvm |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install clang llvm |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install clang llvm |
Набор инструментов LLVM (в частности, компилятор Clang) изначально поддерживает кросс-компиляцию. Для кросс-компиляции этого набора инструментов под LoongArch используйте LLVM версии 17 или более поздней и ознакомьтесь с эта статья и укажите целевую платформу LoongArch (например, loongarch64-unknown-linux-gnu).
Rust
Rust официально поддерживает LoongArch. Его можно установить напрямую из репозитория вашего дистрибутива в виде бинарных файлов или скомпилировать с помощью кросс-компиляции.
Rust рекомендует использовать заржаветь Чтобы установить инструментарий Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shЧтобы установить Rust (rustc) и менеджер пакетов Cargo в распространенных дистрибутивах Linux и операционных системах:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install rustc |
| Arch Linux | sudo pacman -S rustc |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install rust-all |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install rust cargo |
Node.js
Node.js официально поддерживает LoongArch. Его можно установить напрямую из репозитория вашего дистрибутива в виде бинарных файлов или скомпилировать с помощью кросс-компиляции. Бинарные файлы Node.js для LoongArch распространяются через Неофициальные сборки проект (отмеченный как loong64 архитектура).
Чтобы установить Node.js в популярных дистрибутивах Linux и операционных системах:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install nodejs |
| Arch Linux | sudo pacman -S nodejs |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install nodejs |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install nodejs |
TIP
Многие дистрибутивы Linux предоставляют несколько версий Node.js, чтобы удовлетворить потребности различных приложений и проектов. Ознакомьтесь с документацией по дистрибутиву и установите альтернативные версии Node.js по мере необходимости.
Go
Go официально поддерживает LoongArch. Его можно получить напрямую из репозитория вашего дистрибутива в виде бинарных файлов или скомпилировать с помощью кросс-компиляции. Разработчики Go создают бинарные файлы для LoongArch, которые доступны на их Скачать страницу.
Чтобы установить Go в популярных дистрибутивах Linux и операционных системах:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install go |
| Arch Linux | sudo pacman -S go |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install golang |
| Дистрибутивы, основанные на Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install golang |
Go изначально поддерживает кросс-компиляцию. Начиная с версии Go 1.21, следуйте инструкциям, изложенным в эта статья и указать целевую платформу LoongArch (т. е., GOARCH=loong64) для кросс-компиляции под LoongArch.
Python
Python официально поддерживает LoongArch. Его можно установить напрямую из репозитория вашего дистрибутива в виде бинарных файлов или скомпилировать с помощью кросс-компиляции.
Чтобы установить Python в распространенных дистрибутивах Linux и операционных системах:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install python-3 |
| Arch Linux | sudo pacman -S python |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install python3 |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install python3 |
TIP
Поскольку для LoongArch пока не определена базовая конфигурация «manylinux», в официальном репозитории PyPI нет бинарных файлов для LoongArch. Это означает, что при установке модулей PyPI с помощью pip... соответствующие модули будут скомпилированы из исходного кода, и вам, возможно, понадобится установить инструментальные средства C/C++/Rust по мере необходимости.
Компания Loongson Technology ведёт репозиторий бинарных файлов PyPI для систем ABI 2.0 по адресу lpypi.loongnix.cn. Вы можете отредактировать /etc/pip.conf и установить его в качестве репозитория по умолчанию. В качестве альтернативы можно длинный 64-разрядный Организация на GitHub ведет независимый репозиторий бинарных файлов PyPI. Инструкции по настройке см. в файл README организации.
.NET
.NET официально поддерживает LoongArch. Однако, поскольку LoongArch в рамках .NET относится к категории «архитектур, поддерживаемых сообществом», Microsoft не поставляет бинарных инструментальных средств для LoongArch.
Однако бинарные файлы инструментария .NET можно получить следующими способами:
Для распространенных дистрибутивов Linux достаточно просто загрузить пакет SDK с RID (идентификатор среды выполнения .NET) linux-loongarch64 чтобы получить полный набор инструментов (т. е., dotnet-runtime-10.0.1-linux-loongarch64.tar.gz). Инструкции по установке .NET SDK с помощью пакетов tar см. в официальная документация по .NET.
Кросс-компиляция приложений .NET для LoongArch
.NET изначально поддерживает кросс-компиляцию и кроссплатформенную публикацию. В .NET 9 и более поздних версиях см. эта статья и укажите целевой RID для публикации приложений .NET для LoongArch. Однако, поскольку LoongArch относится к категории «архитектур, поддерживаемых сообществом» для .NET, на NuGet.org не размещаются пакеты среды выполнения .NET, предназначенные для LoongArch, что может привести к сбоям при сборке.
Чтобы обойти эту проблему, вы можете загрузить и установить все необходимые пакеты NuGet локально. Для этого просто загрузите следующие файлы со страниц релизов инструментария, указанных выше (* обозначает конкретные номера версий):
- 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
В дистрибутиве, предоставляемом loongson-community/dotnet-unofficial-build, вышеупомянутые файлы относятся к категории «артефакты выпуска». Чтобы получить перечисленные выше компоненты, загрузите этот пакет.
Поместите указанные выше файлы в папку, удобную для вас (например, /data/loongarch64-nupkgs) и следуйте инструкциям в эта статья чтобы добавить этот каталог в список источников NuGet, как показано ниже:
<packageSources>
<add key="LoongArch64 Packages" value="/data/loongarch64-nupkgs" />
</packageSources>Теперь у вас должна появиться возможность выполнять кросс-компиляцию приложений .NET для LoongArch.
Сборка инструментария .NET
Сборка самой среды разработки .NET — это довольно сложный процесс. Чтобы упростить освоение, ознакомьтесь с Скрипты сборки CI, используемые компанией Loongson Technology. В этом методе для компиляции используется пакет распространения исходных кодов VMR, официально рекомендованный платформой .NET.
Java
По нетехническим причинам Oracle OpenJDK в настоящее время не поддерживает LoongArch JIT. Для установки Java рекомендуется загрузить бинарные пакеты, совместимые с «ядром Linux 5.10.0 UAPI», на сайте Сообщество открытого исходного кода Loongson (loongnix.cn) или через репозиторий вашего дистрибутива.
Чтобы установить Java в распространенных дистрибутивах Linux и операционных системах:
| Операционная система | Порядок установки |
|---|---|
| ОС AOSC | oma install openjdk |
| Arch Linux | sudo pacman -S java-openjdk |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install default-jdk |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install java-latest-openjdk |
TIP
Многие дистрибутивы Linux предоставляют несколько версий OpenJDK, чтобы удовлетворить потребности различных приложений и проектов. Ознакомьтесь с документацией по дистрибутиву и установите альтернативные версии OpenJDK по мере необходимости.
Ядро Linux
Ядро Linux официально поддерживает LoongArch. Как правило, дистрибутивы Linux, основанные на ABI 2.0, используют исходное ядро (вместе с платформозависимыми обходными решениями и другими исправлениями, см. ниже). Однако некоторые коммерческие дистрибутивы поставляются с ядром версии 6.6 «longterm», содержащим обширный набор платформозависимых исправлений.
TIP
Поддержка LoongArch была добавлена в ядро Linux начиная с версии 5.19. Однако для полного использования аппаратных возможностей и производительности LoongArch рекомендуется использовать последнюю версию основного ядра.
Справочник по обслуживанию ядра
Как отмечалось выше, более новые версии ядра Linux, как правило, предпочтительнее благодаря лучшей поддержке устройств LoongArch. Однако, поскольку дистрибутивы могут иметь свои собственные правила в отношении обновления ядра, мы подготовили приведенное ниже руководство для вашей справки.
| Версия Linux | Внедренные ключевые функции |
|---|---|
| 6.18 | Исправления для GPIO в 2K2000/2K3000/3B6000M |
| 6.17 | Поддержка DWMAC для встроенного сетевого адаптера 2K3000/3B6000M; исправление модуляции частоты PWM |
| 6.16 | Поддержка SDIO для 2K2000/2K3000/3B6000M |
| 6.14 | Поддержка мультиплексирования семейства 3C6000 |
| 6.12 | Поддержка семейства 3B6000/3C6000 (расширенная модель IRQ) |
| 6.7 | Поддержка виртуализации |
| 6.4 | Поддержка технологии одновременного многопоточного выполнения (SMT) |
Необъединенные патчи
Как правило, инженеры компании Loongson Technology и разработчики из сообщества отправляют патчи по поддержке оборудования, оптимизации и исправлениям в основную ветку ядра. Однако по техническим и нетехническим причинам некоторые патчи остаются не включенными в ядро.
В приведенной ниже таблице перечислены все известные и важные патчи, поддерживаемые различными последующими разработчиками (разработчиками, сообществами дистрибутивов и т. д.), для справки (приведенный ниже список патчей основан на v6.19-rc1 и не включайте патчи, которые уже были отправлены в основной проект длинная арка (список рассылки)):
| Описание | Тип | Запись в Kconfig | Ссылка | Примечания |
|---|---|---|---|---|
| Устройства PixArt PS/2 | Особенности | MOUSE_PS2_PIXART (bool: да/нет) | 1 | Для ноутбуков, таких как Tongfang Chaorui L860-T2 и EA EXCELSIOR L71 на базе чипсетов 3A5000 и 3A6000, этот патч устраняет проблему, из-за которой тачпады ошибочно распознавались как мыши PS/2, что приводило к сбою поддержки жестов и функции распознавания ладони. |
| Поддержка HWMon (мониторинг температуры и других параметров оборудования), обеспечивающая управление температурой процессора для семейства Loongson 3 | Функция | CPU_HWMON (bool: да/нет) | 1 | Не включает поддержку мониторинга температуры микросхемы моста 7A; этот патч может привести к sensors(1) для считывания данных с неисправных датчиков температуры на платформах SoC, таких как 2K3000/3B6000M. |
| Многоканальный контроллер DMA | Характеристика | Н/Д | 1 | |
| SoC 2K3000/3B6000M с шиной CAN-FD | Характеристика | CAN_LSCANFD (bool: да/нет), CAN_LSCANFD_PLATFORM (tristate: м/ж/н) | 1 | Необходимо использовать вместе с патчем для многоканального контроллера DMA |
| Поддержка прошивки BPI1000/1001 («Old World») | Функция | Не применимо | 1, 2, 3, 4, 5, 6, 7, 8 | Необходимо для загрузки систем ABI 2.0 на серверах Lenovo Kaitian M540z, Gooxi 3C5000L с четырьмя сокетами, а также на некоторых платформах с прошивкой Kunlun, выпускавшихся в период с 2020 по 2022 год. |
| Ошибка определения скорости шины PCIe в некоторых процессорах семейств 3B6000 и 3C6000, при которой скорость PCIe неверно ограничивалась до уровня PCIe 1.0 | Способ обхода | Не применимо | 1 | Масштаб воздействия различных версий/партий процессоров остается неясным. Подробности см. объяснение здесь |
Способ обхода проблемы с неработающими GPIO, вызванной несоответствием описаний устройств спецификации Loongson CPU Unified System Architecture Specification, в которой устройства GPIO описывались в рамках gsi_idx_map | Обходной путь | Не применимо | 1 | Не должно влиять на модели 2K3000/3B6000M и более поздние версии |
| Способ устранения периодических сбоев, перезапусков и зависаний драйвера при использовании графических процессоров AMD GCN версий 1.0–4.0 на платформах LoongArch | Способ устранения | Н/Д | 1 | Механизм, лежащий в основе этого исправления, неясен (эмпирический патч); коммерческие ядра версии 6.6, такие как deepin, включают более агрессивный (хотя и столь же необъяснимый) набор патчей. См. этот пул-реквест для Deepin. |
| Способ устранения ошибок с данными, возникающих на платформах 7A при использовании графических драйверов AMD «Radeon» (для видеокарт TeraScale 2 и более ранних моделей) | Способ устранения | Не применимо | 1, 2, 3 | Механизм неизвестен, но эффективен; патч 3 ограничивает применение этого обходного решения платформами MIPS и LoongArch64 (MACH_LOONGSON64) |
Зарегистрировать третий ШИМ-контроллер LOON0006:03 на мосту 7A2000 в качестве gsgpu_backlight в коде инициализации ACPI на уровне платы для поддержки управления подсветкой LoongGPU | Обходной путь | Н/Д | 1 | Патч, необходимый для поддержки подсветки LoongGPU. Информацию о патчах, связанных с драйвером LoongGPU, см. в AOSC-Tracking/loonggpu-kernel-dkms @ aosc/v1.0.1-alpha-lnd25.5. |
| Включить поддержку функции «Удаленное пробуждение» для корневых концентраторов USB (таких как USB-клавиатуры, мыши и другие устройства ввода) | Временное решение | Не применимо | 1, 2 | Установка этого патча включает функцию пробуждения с клавиатуры для устройств LoongArch в режиме ACPI S3 (переход в режим ожидания с сохранением данных в ОЗУ), однако известно, что это мешает некоторым ноутбукам на базе x86 переходить в режим сна. Патч 2 ограничивает действие этого обходного решения платформами MIPS и LoongArch64 (MACH_LOONGSON64). |
Docker
Утилита Docker теперь официально поддерживает LoongArch; как правило, её можно найти в репозитории вашего дистрибутива.
Чтобы установить Docker в популярных дистрибутивах Linux и операционных системах:
| Операционная система | Способ установки |
|---|---|
| ОС AOSC | oma install docker |
| Arch Linux | sudo pacman -S docker |
| Debian и его производные, такие как Deepin, openKylin и Loongnix 25 | sudo apt install docker.io |
| Дистрибутивы, созданные на базе Red Hat, такие как Fedora LoongArch Remix, openEuler, Anolis OS, OpenCloudOS | sudo dnf install docker |
TIP
В официальном реестре Docker доступно лишь несколько контейнеров LoongArch. Компания Loongson Technology ведет Репозиторий образов Docker, ориентированный на LoongArch ABI 2.0. Вы можете изменить настройки Docker использовать этот реестр по мере необходимости.
CI-раннеры
Многие платформы для хостинга кода предлагают поддержку CI-раннеров, а некоторые из них уже изначально поддерживают LoongArch
GitHub Actions
GitHub Actions Runner не смог создать бинарные сборки из-за В NuGet отсутствует поддержка LoongArch. Если вы хотите самостоятельно скомпилировать и развернуть этот агент CI, ознакомьтесь с этим запрос на слияние.
GitLab Runner
GitLab Runner официально поддерживает LoongArch. Для развертывания достаточно загрузить и установить пакеты или сжатые архивы с тегом loong64 из его страница выпуска.
Gitea act_runner
Gitea act_runner официально поддерживает LoongArch, хотя бинарные файлы для LoongArch пока недоступны. На данный момент вы можете клонировать исходный код чтобы скомпилировать и развернуть этот запускающий модуль.
Forgejo Runner
В Forgejo Runner пока не реализована поддержка LoongArch. Если вы хотите самостоятельно скомпилировать и развернуть этот раннер, ознакомьтесь с этой запрос на слияние.
Sourcehut
Прокси-сервер Sourcehut builds.sr.ht официально поддерживает LoongArch. Поскольку этот CI-раннер не распространяет бинарные файлы, вам потребуется скомпилировать и развернуть этот раннер из исходного кода.
GitHub
В Gitee поддержка LoongArch пока не включена. Если вы хотите самостоятельно скомпилировать и развернуть этот раннер, ознакомьтесь со следующими пулл-реквестами:
GitCode
Как уточняли участники сообщества, GitCode в настоящее время не поддерживает самостоятельно развернутые прокси-серверы CI, поэтому поддержка LoongArch, по крайней мере на данный момент, невозможна.