Руководство для разработчиков
Руководства и рекомендации по разработке для 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 и указать его в качестве репозитория по умолчанию. В качестве альтернативы можно использовать long64 Организация на 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
В ядре Linux поддержка LoongArch была реализована начиная с версии 5.19. Однако для полного использования аппаратных возможностей и производительности LoongArch рекомендуется использовать последнюю версию основного ядра.
Справочник по обслуживанию ядра
Как отмечалось выше, более новые версии ядра Linux, как правило, предпочтительнее благодаря лучшей поддержке устройств LoongArch. Однако, поскольку дистрибутивы могут иметь свои собственные правила в отношении обновлений ядра, мы подготовили приведенное ниже руководство для вашей справки.
| Версия Linux | Внедренные ключевые функции |
|---|---|
| 7.1.4 | Исправление скорости PCIe для 3B6000/3C6000 |
| 7.1.1 | Поддержка области SystemIO в ACPI |
| 7.1 | Поддержка многоканального DMA для моделей 2K0300/2K3000/3B6000M |
| 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 и разработчики из сообщества направляют патчи, связанные с поддержкой оборудования, оптимизацией и исправлениями, в основную ветку ядра (upstream). Однако по техническим и нетехническим причинам некоторые патчи остаются несливанными.
В приведенной ниже таблице перечислены все известные и важные патчи, поддерживаемые различными сторонами, занимающимися дальнейшей разработкой (разработчиками, сообществами дистрибутивов и т. д.), для вашего сведения (приведенный ниже список патчей основан на v7.1.4 и не включайте патчи, которые уже зафиксированы в вверх по течению):
| Описание | Запись в 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; на платформах 3C6000 и более поздних версий прошивка версии 202511 или более поздней уже представляет этот датчик в виде тепловой зоны ACPI, поэтому данный патч не требуется |
| SoC 2K3000/3B6000M с шиной CAN-FD | Добавлено: CAN_LSCANFD (bool: да/нет), CAN_LSCANFD_PLATFORM (тристат: y/m/n) | 1 | Требуется использование с ядром Linux версии 7.1 или более поздней, поддерживающим многоканальный DMA |
| Поддержка прошивки BPI1000/1001 («Old World») | Не применимо | 1, 2, 3, 4, 5, 6, 7, 8 | Необходимо для загрузки систем ABI2.0 на серверах Lenovo Kaitian M540z, Gooxi 3C5000L с четырьмя сокетами, а также на некоторых платформах с прошивкой Kunlun, выпускавшихся в период с 2020 по 2022 год. |
| Анализ свойств тактовой частоты контроллера I2C Loongson и поддержка настройки скорости шины | CONFIG_LS2X_I2C | 1 | Отсутствие этой функции приводит к задержкам в работе тачпада на некоторых ноутбуках модели 3B6000M. |
| Обновление протокола прошивки SMCv2 | CONFIG_LOONGSON3_CPUFREQ | 1 | Отсутствие этого обновления может привести к сбою при загрузке на версии прошивки 202605, если включена функция DVFS; также обратите внимание, что версия 202605 является экспериментальной |
Способ обхода проблемы с неработающим GPIO, вызванной тем, что описания устройств соответствуют только старой версии Спецификации унифицированной системной архитектуры процессоров Loongson, в которой устройства GPIO описывались в рамках gsi_idx_map | CONFIG_GPIO_LOONGSON_64BIT | 1 | Не должно влиять на модели 2K3000/3B6000M и более поздние версии |
| Способ устранения периодических сбоев, перезапусков и зависаний драйверов при использовании графических процессоров AMD GCN версий 1.0–4.0 на платформах LoongArch | CONFIG_DRM_AMDGPU | 1 | Механизм действия этого обходного решения неясен (эмпирический патч); данный обходный путь не позволяет полностью избежать этих проблем, а лишь снижает вероятность их возникновения; коммерческие ядра версии 6.6, такие как deepin, включают более агрессивный (хотя и столь же необъяснимый) набор патчей. См. этот пул-реквест для Deepin. |
| Способ устранения ошибок с данными, возникающих на платформах 7A при использовании графических драйверов AMD «Radeon» (для видеокарт TeraScale 2 и более ранних моделей) | CONFIG_DRM_RADEON | 1, 2, 3 | Механизм неизвестен (сообщение о фиксации не соответствует техническим стандартам), но эффективен; патч 3 ограничивает применение этого обходного решения платформами MIPS и LoongArch64 (MACH_LOONGSON64) |
Зарегистрировать третий ШИМ-контроллер LOON0006:03 на мосту 7A2000 в качестве gsgpu_backlight в коде инициализации ACPI на уровне платы для поддержки управления подсветкой LoongGPU | CONFIG_PWM_LOONGSON | 1 | Патч, необходимый для поддержки подсветки LoongGPU. Информацию о патчах, связанных с драйвером LoongGPU, см. в AOSC-Tracking/loonggpu-kernel-dkms @ aosc/v1.0.1-alpha-lnd25.5. |
| Включить поддержку функции «Удаленное пробуждение» для корневых концентраторов USB (таких как USB-клавиатуры, мыши и другие устройства ввода) | CONFIG_USB | 1, 2 | Установка этого патча включает функцию пробуждения с клавиатуры для устройств LoongArch в режиме ACPI S3 (переход в режим ожидания в ОЗУ), однако известно, что это мешает некоторым ноутбукам на базе x86 переходить в режим сна. Патч 2 ограничивает действие этого обходного решения платформами MIPS и LoongArch64 (MACH_LOONGSON64). |
| Сброс состояния включения подсветки в процедуре перехода в режим ожидания S3 и выхода из него драйвера loongson-laptop | CONFIG_LOONGSON_LAPTOP | 1 | Решение проблемы в прошивке EC некоторых ноутбуков 3B6000M, приводящей к отключению подсветки после выхода из режима S3 |
| Обнаружить и отключить sc.q в случае нестабильной работы | Не применимо | 1 | Этот обходной путь необходим для загрузки ядра на некоторых ошибочных реализациях прошивки платформы 2K3000/3B6000M, в которых ядро LA364E настроено некорректно, что приводит к записи некорректных данных при выполнении инструкции sc.q; этот обходной способ является неполным, поскольку программы пользовательского пространства по-прежнему могут получать некорректные результаты, если они не защитили использование sc.q с помощью AT_HWCAP Проверьте; для устранения проблемы рекомендуется обновить прошивку |
Поддержка устройств I2C HID, описанных в рамках ACPI PRP0001 узел с _DSM метод | CONFIG_I2C_HID_ACPI | 1 | В некоторых ноутбуках, например Lenovo Kaitian N60d-G1d и Inspur Yingzheng, тачпад описывается именно таким образом, поэтому для его работы требуется этот патч |
| Поддержка страниц размером 16 КиБ для процессоров Intel Xe | CONFIG_DRM_XE | 1 2 3 4 5 6 | Требуется использование видеокарты Intel в ядре с размером страницы 16 КиБ, которое предпочитают большинство дистрибутивов LoongArch; тем не менее, по-прежнему не рекомендуется приобретать видеокарту Intel для платформы LoongArch, поскольку прошивка не может использовать такую видеокарту в качестве устройства вывода |
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
Прокси CI от Sourcehut builds.sr.ht официально поддерживает LoongArch. Поскольку этот CI-раннер не распространяет бинарные файлы, вам потребуется скомпилировать и развернуть этот раннер из исходного кода.
GitHub
Gitee пока не включил поддержку LoongArch. Если вы хотите самостоятельно скомпилировать и развернуть этот раннер, ознакомьтесь со следующими пулл-реквестами:
GitCode
Как уточнили участники сообщества, GitCode в настоящее время не поддерживает самостоятельно развернутые прокси CI, поэтому поддержка LoongArch, по крайней мере на данный момент, невозможна.