Дистрибутив Buildroot

Получение дистрибутива

Дистрибутив распространяется на странице https://dist.elvees.com/mcom03r/buildroot/2025.09. Иерархия директорий:

└── linux66
    ├── graphs/
    ├── images/
    ├── legal-info/
    ├── artifact-files.txt
    ├── git-info.json
    ├── manifest.json
    └── mcom03r-defconfig-src.tar.gz

В директории linux66 хранятся исходные коды и образы на базе ядра 6.6.

В файле git-info.json перечислены SHA-версии пакетов Buildroot.

В файле manifest.json содержится Идентификатор сборки BUILD_ID.

В файле artifact-files.txt содержатся относительные пути до файлов дистрибутива. Пример скачивания файлов в Bash:

files_url=https://dist.elvees.com/mcom03r/buildroot/<release>/linux<version>/artifact-files.txt
files=$(wget -O- -q $files_url)
echo "$files" | xargs -I {} wget --force-directories --no-host-directories $files_url/../{}

В директории images хранятся собранные образы и архивы:

sbl/sbl-xip-<board>.bin — для прошивки QSPI0.
rootfs.tar.gz — для прошивки SD-карты или eMMC.
aarch64-buildroot-linux-gnu_sdk-buildroot.tar.gz — комплект тулчейнов ARM, MIPS, DSP (подробнее см. Средства сборки).
baremetal-tools/* — образы, собранные из репозитория https://github.com/elvees/mcom03-baremetal-tools
efi-part/* — файлы поддержки загрузки по UEFI, см. Обзор загрузки ОС (boot flow).

Файл images/tar2dev используется для прошивки SD-карты в режиме загрузки Generic Distro, см. Прошивка SD-карты.

Файл images/tar2dev-uefi используется для прошивки SD-карты в режиме UEFI.

Для сборки необходимо скачать содержимое директории, распаковать архив с исходными кодами *-defconfig-src.tar.gz, перейти в распакованную директорию:

tar -xf ..-defconfig-src.tag.gz
cd ..-defconfig-src

Важно

Путь до директории, в которой выполняется распаковка и сборка, не должен содержать символов кириллицы и пробелов.

Примечание

Архив *-defconfig.src подготовлен командами:

make mcom03r_defconfig
make source
tar -czf ...defconfig-src.tag.gz ...

Сборка в «родной» ОС (native)

Перед сборкой необходимо установить системные пакеты, пакеты брать из соответствующих файлов Dockerfile.* (например centos8stream, ubuntujammy, и т.д.).

Примечание

Распространяемый архив был собран в Docker-контейнере DOCKERFILE=Dockerfile.centos8stream. Примененный файл конфигурации buildroot/.config содержит список пакетов строго для данной среды. В случае смены ОС требуется повторное применение конфигурации docker-build.sh make ..._defconfig .... При запуске make из сети могут скачиваться дополнительные пакеты.

Для сборки Buildroot на базе разных ядер должны использоваться архивы с соответствующими исходными кодами, подробнее см. Получение дистрибутива.

Для сборки Buildroot для любого поддерживаемого модуля необходимо выполнить:

make mcom03r_defconfig
make

Собранные образы доступны в директории buildroot/output/images, описание файлов см. Получение дистрибутива.

Поддерживаемые фрагменты расположены в директории external-mcom03/fragments.

При сборке Buildroot могут быть использованы любые стандартные команды: make source, make <package>-reconfigure, make menuconfig. Подробнее см. официальный Buildroot manual.

Сборка в среде Docker

Установите и настройте Docker: добавьте пользователя в группу docker, настройте прокси для клиента и сервера.

Собрать в среде Docker:

export DOCKERFILE=Dockerfile.centos8stream
export ENABLE_NETWORK=1  # container is allowed to access network

./docker-build.sh make mcom03r_defconfig
./docker-build.sh make

Средства сборки

В состав Buildroot входят средства сборки (далее — тулчейны) для процессорных ядер MCom-03R:

baremetal mipsel-elvees-elf32 на базе GCC для MIPS32 RISC0. Тулчейн портирован компанией ЭЛВИС. Тулчейн содержит обходы ошибок процессора.

Использовать другие тулчейны для MIPS32 RISC0 не рекомендуется.
Linux GCC для ARM CPU0. Тулчейн собирается из исходных кодов во время сборки Buildroot.
LLVM Clang для DSP. Тулчейн портирован компанией ЭЛВИС.

Варианты использования тулчейнов:

Собрать Buildroot и использовать тулчейны, добавляя пути до исполняемых файлов в PATH:

# ARM toolchain
export PATH=$PWD/buildroot/output/host/bin:$PATH

# MIPS toolchain
export PATH=$PWD/buildroot/output/host/opt/toolchain-mipsel-elvees-elf32/bin:$PATH

# DSP toolchain
export PATH=$PWD/buildroot/output/host/opt/toolchain-elcore50/bin:$PATH

Собрать набор тулчейнов (aka relocatable Buildroot SDK) c использованием встроенного механизма Buildroot (подробнее см. «Using the generated toolchain outside Buildroot» в Buildroot manual).

Создать архив тулчейнов ..._sdk-buildroot.tag.gz в buildroot/output/images:
```
make sdk
```
Распаковать архив в произвольную директорию, в корне распакованной директории вызвать скрипт relocate-sdk.sh для обновления путей в утилитах SDK (выполняется однократно).

При каждом открытии терминала вызвать скрипт для настройки путей (команда настроит переменную PATH и т.п.):
```
source <your/sdk/path>/environment-setup
```
Примечание

Предсобранный ..._sdk-buildroot.tar.gz распространяется в составе артефактов MCom-03R Buildroot, см. Получение дистрибутива.

Примечание

Несмотря на префикс «aarch64» в названии архива, архив содержит тулчейны для всех процессоров.

Для поддержки сборки проектов на базе CMake для каждого из тулчейнов создаётся toolchain.cmake-файл. toolchain.cmake-файлы присутствуют в сборочной директории buildroot/output/host и копируются в архив тулчейнов:

buildroot/output/host/share/buildroot/toolchainfile.cmake
buildroot/output/host/opt/toolchain-mipsel-elvees-elf32/share/cmake/toolchain.cmake
buildroot/output/host/opt/toolchain-elcore50/share/cmake/elcore50-toolchain.cmake

Проекты CMake могут собираться с использованием стандартного механизма (см. CMake cross-compiling):

cmake -DCMAKE_TOOLCHAIN_FILE=<absolute-path-to-toolchain.cmake> ...

Сборка произвольных версий пакетов

Сборка с произвольной версией пакета выполняется согласно стандартному механизму override file local.mk, см. «Using Buildroot during development» в главе https://buildroot.org/downloads/manual/manual.html#_advanced_usage.

Важно

Выпуск MCom-03R Buildroot содержит слепок коммитов различных репозиториев. SHA коммитов репозиториев перечислены в файле git-info.json (см. Получение дистрибутива). Собираемость и работоспособность гарантируется только для указанных SHA.

Для сборки произвольных версий пакетов mcom03-sbl, ddrinit, U-Boot, Linux необходимо:

Склонировать в произвольную директорию перечисленные выше компоненты (U-Boot, Linux, mcom03-sbl), выгрузить необходимую версию:
```
git clone https://github.com/elvees/...
git checkout ...
```

Создать файл buildroot/local.mk. В файле добавить строки с путями до склонированных репозиториев:

ARM_TRUSTED_FIRMWARE_OVERRIDE_SRCDIR = <abspath to local TF-A>
DDRINIT_OVERRIDE_SRCDIR = <abspath to local ddrinit>
LINUX_OVERRIDE_SRCDIR = <abspath to local Linux>
MCOM03_SBL_OVERRIDE_SRCDIR = <abspath to local mcom03-sbl>
UBOOT_OVERRIDE_SRCDIR = <abspath to local U-Boot>

Запустить сборку:

make

# or to build in docker
ENABLE_NETWORK=1 ./docker-build.sh make

Обзор загрузки ОС (boot flow)

MCom-03R запускается в режиме QSPI0 XIP. Память QSPI0 содержит образы SBL, ddrinit, TF-A, U-Boot и DTB для U-Boot. SD-карта содержит ядро, DTB, extlinux.conf. Основным методом загрузки является Generic Distro. Опционально поддерживается загрузка по UEFI (в цепочку загрузки добавляется GRUB2). Подробнее про выбор метода загрузки см. Загрузка ядра Linux.

Последовательность загрузки приведена на диаграмме:

digraph G {

node [ shape = box, style = filled, width=2.5, height=0.4]

poweron [label = "User Power On", fillcolor=darkolivegreen1]
sbl1 [label = "SBL @ RISC0 (QSPI0 XIP)", fillcolor=azure2]
ddrinit [label = "DDR init @ RISC0 (SPRAM)", fillcolor=azure2]
sbl2 [label = "SBL @ RISC0 (QSPI0 XIP)", fillcolor=azure2]
tfa [label = "TF-A @ CPU (DDR)", fillcolor=lightsalmon]
uboot [label = "U-Boot @ CPU (DDR)", fillcolor=lightsalmon]
linux [label = "Linux @ CPU (DDR)", fillcolor=lightsalmon]

poweron -> sbl1 -> ddrinit -> sbl2 -> tfa -> uboot -> linux
} — Рис. 1 Последовательность загрузки Linux (в скобках указан источник исполнения)

Загрузка ОС по UEFI

Конфигурация MCom-03R Buildroot включает необходимые пакеты для демонстрации загрузки по UEFI. Для подготовки загрузочного устройства используется утилита tar2dev-uefi. Для просмотра списка поддерживаемых опций см. tar2dev-uefi -h. Утилита размечает устройство:

создаёт таблицу разделов типа GUID Partition table (далее — GPT);
создаёт раздел EFI System Partition (далее — ESP), содержание раздела:
- директория /dtb с файлами *.dtb для ядра;
- загрузчик ОС GRUB2 /EFI/BOOT/bootaa64.efi (EFI fallback);
- конфигурационный файл для GRUB2 /EFI/BOOT/grub.cfg.
создаёт раздел с корневой файловой системой.

Прошивка SD-карты

Важно

Утилита tar2dev-uefi зависит от tar2dev. Утилиты должны находиться в одной директории.

Прошивка SD-карты с установкой раздела ESP размером 300 MиБ (значение по умолчанию):
```
chmod +x ./tar2dev-uefi
sudo ./tar2dev-uefi rootfs.tar.gz efi-part/EFI /dev/sdX
```
Прошивка SD-карты с установкой раздела ESP размером 600 MиБ:
```
chmod +x ./tar2dev-uefi
sudo ./tar2dev-uefi -s 600 rootfs.tar.gz efi-part/EFI /dev/sdX
```

Имя хоста (hostname)

По умолчанию, установлено имя хоста buildroot. Это значение может быть изменено:

автоматически при загрузке при помощи systemd-сервиса mcom03-set-hostname;
редактированием файла /etc/hostname;
вызовом команды:
```
hostnamectl hostname <HOSTNAME>
```
Примечание

При загрузке при помощи TFTP и NFS приведенные выше способы не гарантируют регистрацию указанного имени хоста на DHCP-сервере, т.к. DHCP-запрос отправляется раньше, чем выполняется монтирование файловой системы, содержащей имя хоста. В этом случае имя хоста следует передавать через параметры командной строки ядра (переменная окружения U-Boot bootargs), аргумент ip.
при записи образа на SD-карту при помощи ключа -n:
```
sudo ./tar2dev -n <HOSTNAME> rootfs.tar.gz /dev/sdX
```

systemd-сервис mcom03-set-hostname генерирует имя хоста из названия модуля и серийного номера из device-tree. Для установки фиксированного серийного номера использовать Заводские настройки.

Примеры генерируемых имен:

elvees,elvmc03smarc-r3.0.0-elvsmarccb-r3.3.0  -> elvmc03smarc3

Если сервис включен, то сервис перезаписывает /etc/hostname при каждой загрузке. Для отключения сервиса выполнить:

systemctl disable mcom03-set-hostname

Отключить сервис при прошивке образа:

sudo ./tar2dev -n <HOSTNAME> -d mcom03-set-hostname rootfs.tar.gz /dev/sdX

Идентификатор сборки BUILD_ID

Поддерживается запись в образы уникального идентификатора сборки. Идентификатор задаётся переменной окружения BUILD_ID:

export BUILD_ID=<unique build id>
make ..._defconfig && make

Примеры использования идентификатора:

BUILD_ID записывается в /etc/os-release на rootfs.
BUILD_ID записывается в образы SBL-XIP и U-Boot и печатается компонентами при загрузке.

BUILD_ID публикуемых образов содержится в manifest.json (см. Получение дистрибутива).

Пример печати в терминал образов собранных с BUILD_ID=24cdac606c8e45e08368d8205d7c672e:

SBL-XIP (Apr  6 2025 - 02:49:22): 3f2111e
SBL-XIP: Build: 24cdac606c8e45e08368d8205d7c672e
...
U-Boot 2024.07 (Apr 06 2025 - 02:38:26 +0000), Build: 24cdac606c8e45e08368d8205d7c672e
...
[    0.000000] Linux version 5.10.179 (zuulbot@049204495b62) (...Buildroot v1.0-1158-ga40d968-24cdac606c8e45e08368d8205d7c672e) ...
...
# cat /etc/os-release
NAME=Buildroot
VERSION=v1.0-1158-ga40d968-24cdac606c8e45e08368d8205d7c672e
ID=buildroot
VERSION_ID=1.0.0
PRETTY_NAME="Buildroot 1.0.0"
...
# cat /proc/device-tree/chosen/u-boot,version
U-Boot 2024.07 (Apr 06 2025 - 02:38:26 +0000), Build: 24cdac606c8e45e08368d8205d7c672e

Поддержка ELV-MC03-SMARC

Процессорный модуль ELV-MC03-SMARC r3.0.0 может быть установлен в совместимые платы-носители (aka Carrier Board, CB):

ELV-SMARC-CB r3.3.0.

Подробнее о методах загрузки на платах-носителях SMARC см. Выбор DTB ядра.

Запуск ELV-SMARC-CB r3.3.0

Установить режим загрузки c XIP QSPI0: BTSL2,1,0 в положения ON, ON, ON.

См. также

Перед первым запуском модуля может требоваться установка дополнительных переключателей, настройка всех переключателей перечислена в главе «Быстрый старт» Руководства Пользователя на модуль.
Подключить HDMI-дисплей к модулю.
Подключить разъём DBG USB модуля к ПК USB-кабелем.
Подключить блок питания к модулю.
На модуле включить питание выключателем SA5 PWR ON.
На ПК открыть терминал minicom -D /dev/ttyUSBx.

Настроить порт в minicom: открыть настройки CTRL-A O, выбрать Serial port setup):

+-----------------------------------------------------------------------+
| A -    Serial Device      : /dev/ttyUSB0                              |
|                                                                       |
| C -   Callin Program      :                                           |
| D -  Callout Program      :                                           |
| E -    Bps/Par/Bits       : 115200 8N1                                |
| F - Hardware Flow Control : No                                        |
| G - Software Flow Control : No                                        |
|                                                                       |
|    Change which setting?                                              |
+-----------------------------------------------------------------------+

Залогиниться: логин - root, пароль не установлен.

Прошивка SD-карты

Прошивка SD-карты выполняется на ПК или на устройстве (при условии загрузки c eMMC):

Определить имя устройства SD-карты на ПК (извлечь SD-карту из считывателя карт ПЭВМ, считать список устройств командой ls -la /dev/sd*, установить SD-карту в ПК, повторно считать список устройств, обнаружить новое устройство /dev/sdX).
Записать архив корневой файловой системы на SD-карту с помощью утилиты tar2dev (утилита входит в состав сборки, см. Получение дистрибутива):
```
chmod +x ./tar2dev
sudo ./tar2dev rootfs-....tar.gz /dev/sdX
```
Для загрузки с SD-карты в /boot/extlinux.conf SD-карты требуется изменить путь до корневой файловой системы и FDT.

Утилита tar2dev поддерживает опции и переменные для установки раздела root, fdt в extlinux.conf, установки имени хоста устройства, подробнее см. tar2dev -h.

Примеры:

Записать SD-карту для модуля ELV-SMARC-CB (загрузка будет выполняться с SD-карты):
```
sudo ROOT=/dev/mmcblk1p1 ./tar2dev -n newhostname rootfs.tar.gz /dev/sdX
```

Прошивка eMMC

Память eMMC на ELV-MC03-SMARC доступна как стандартное блочное устройство Linux /dev/mmcblk0. eMMC может прошиваться тем же образом, что и SD-карта.

Для прошивки достаточно:

загрузить Linux с карты памяти SD;
скопировать rootfs.tar.gz для прошивки eMMC и tar2dev на SD-карту;
прошить eMMC утилитой tar2dev (см. Прошивка SD-карты);
обновить корневую файловую систему в extlinux.conf на eMMC.

Пример прошивки eMMC с ПК по SSH (rootfs.tar.gz располагается на ПК, tar2dev — на файловой системе ОС модуля):

ssh root@<board-ip> zcat \| tar2dev - /dev/mmcblk0 < rootfs.tar.gz

где <board-ip> — IP-адрес загруженного модуля. IP-адрес можно узнать, выполнив команду ifconfig в терминале модуля.

Прошивка QSPI-памяти

Прошивка QSPI-памяти выполняется с ПК. Python-пакет утилит для прошивки QSPI-памятей mcom03-flash-tools и инструкция по прошивке расположены по адресу https://github.com/elvees/mcom03-flash-tools.

Образ прошивки QSPI-памяти указан в Получение дистрибутива.

Прошивка ID EEPROM платы-носителя SMARC

Прошивка EEPROM-памяти выполняется с ПК. Python-пакет утилит для прошивки EEPROM-памятей mcom03-flash-tools и инструкция по прошивке расположены по адресу https://github.com/elvees/mcom03-flash-tools.

Запуск образов в QEMU

Примечание

В инструкции используется неизменённый (upstream) эмулятор QEMU aarch64. В эмуляторе отсутствует поддержка аппаратных блоков специфичных для архитектуры процессора MCom-03R (ISP/VPU/GPU/DSP/PCIe и т.п).

Для запуска образов в QEMU необходимо:

Собрать Buildroot с поддержкой QEMU:

make mcom03r_defconfig FRAGMENTS=qemu
make

# or to build in docker
export ENABLE_NETWORK=1
./docker-build.sh make mcom03r_defconfig FRAGMENTS=qemu
./docker-build.sh make

Запустить QEMU:

buildroot/output/host/bin/qemu-system-aarch64 -machine virt -cpu cortex-a53 \
    -machine type=virt -nographic -smp 4 -m 2048 \
    -kernel buildroot/output/images/Image -append "console=ttyAMA0 root=/dev/vda rootwait" \
    -drive file=buildroot/output/images/rootfs.ext2,if=none,format=raw,id=hd0 \
    -device virtio-blk-device,drive=hd0 \
    -netdev user,id=eth0,hostfwd=tcp::10022-:22 -device virtio-net-device,netdev=eth0

В случае успешной загрузки в текущем терминале выведется приглашение командной строки для логина в ОС виртуальной машины:

[    0.000000] Booting Linux on physical CPU 0x0000000000 [0x410fd034]
[    0.000000] Linux version 6.6 (...) (aarch64-buildroot-linux-gnu-gcc.br_real (...) 11.4.0, GNU ld (GNU Binutils) 2.38) #1 SMP Wed Jan 22 16:48:10 UTC 2025
...

Welcome to Buildroot
buildroot login: root

# cat /proc/device-tree/compatible
linux,dummy-virt