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

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

Дистрибутив распространяется на странице https://dist.elvees.com/mcom03/buildroot/. Пример иерархии директорий 2023.10:

├── linux510
│   ├── graphs/
│   ├── images/
│   ├── git-info.json
│   ├── manifest.json
│   └── mcom03-defconfig-src.tar.gz
└── linux419
    └── ...

В директориях linux419 и linux510 хранятся исходные коды и образы на базе соответствующих версий ядра 4.19 и 5.10.

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

В директории 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, см. howto-flash-sd.

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

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

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

Важно

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

Примечание

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

make mcom03_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 на базе разных ядер 4.19 и 5.10 должны использоваться архивы с соответствующими исходными кодами, подробнее см. Получение дистрибутива.

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

make mcom03_defconfig
make

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

make mcom03_defconfig FRAGMENTS=linux510
make

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

Поддерживаемые фрагменты расположены в директории 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 mcom03_defconfig
./docker-build.sh make

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

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

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-buildrot.tag.gz в buildroot/output/images:
```
make sdk
```
Распаковать архив в произвольную директорию, вызвать скрипт для настройки путей (команда настроит переменную PATH):
```
source <your/sdk/path>/environment-setup
```
Примечание

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

Примечание

Несмотря на префикс «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-03 Buildroot содержит слепок коммитов различных репозиториев. SHA коммитов репозиториев перечислены в файле git-info.json (см. getting-source). Собираемость и работоспособность гарантируется только для указанных 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-03 запускается в режиме 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-03 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-сервиса 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-сервис set-hostname генерирует имя хоста из названия модуля и серийного номера из device-tree. Для установки фиксированного серийного номера использовать Заводские настройки.

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

elvees,elvmc03q7-r2.1.1-elvq7cb-r1.0.0        -> elvmc03q72
elvees,elvmc03smarc-r1.0-rockpi-n10           -> elvmc03smarc1
elvees,elvmc03smarc-r2.2                      -> elvmc03smarc2
elvees,elvmc03smarc-r2.7.1-elvsmarccb-r3.2.1  -> elvmc03smarc2
elvees,mcom03-bub-r1.3.0                      -> mcom03bub1

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

systemctl disable set-hostname

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

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

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

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

ROCK Pi N10,
ELV-SMARC-CB r1.0, r2.10.3.

При перестановке процессорного модуля из платы-носителя одной модели в другую требуется перепрошивка памяти QSPI соответствующим образом либо настройка переменной окружения board_override. В противном случае U-Boot и Linux будут использовать неверные DTB и часть интерфейсов платы-носителя будут недоступны.

Примечание

Информация об аппаратуре установленной на платах-носителях хранится в Device Tree Blob (DTB). U-Boot использует DTB, прошитый в памяти QSPI. Linux использует DTB, загружаемый U-Boot с eMMC, SD-карты.

Запуск ROCK Pi N10

Установить режим загрузки Boot 0 (XIP QSPI0) - установить джамер на контактах 25 и 26 40-пинового разъёма.
Подключить переходник USB-to-UART к UART2 модуля (пример подключения), подключить переходник к ПК.
Подключить HDMI-дисплей к модулю.
Подключить блок питания USB type C.
На ПК открыть терминал, залогиниться.
Если на HDMI-дисплей не выводится видео, выполнить перезапуск HDMI, см. Поддержка HDMI.

Запуск ELV-SMARC-CB r2.10.3

Установить режим загрузки c XIP QSPI0: BTSL2,1,0 в положения ON, ON, ON.
Установить прочие переключатели:
- SA1 - ON
- SA2 - ON
- SA6 - FRCOn
- SA4 - ON
- SA7 - OFF
- SA9 - OFF
Подключить 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, пароль не установлен.
Если на HDMI-дисплей не выводится видео, выполнить перезапуск HDMI, см. Поддержка HDMI.

Поддержка HDMI

При включении/сбросе СнК видео на HDMI может не выводиться или выводиться испорченным. Для перезапуска HDMI требуется перезапуск процессора или перенастройка PLL СнК. Перенастройка PLL выполняется скриптом mcom03-hdmi-setup.sh (установлен в ОС).

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

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

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

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

Примеры:

Записать SD-карту для модуля ROCK Pi N10 или ELV-SMARC-CB (загрузка будет выполняться с SD-карты):
```
sudo ROOT=/dev/mmcblk1p1 ./tar2dev -n newhostname rootfs.tar.gz /dev/sdX
```
Записать SD-карту для модуля ТрастФон_ПМ (загрузка будет выполняться с SD-карты):
```
sudo ROOT=/dev/sda1 ./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 (см. howto-flash-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-памяти указан в getting-source.