 |
ОСРВ MULTEX-ARM
Руководство программиста
|
|
ОСРВ MULTEX-ARM
Руководство программиста
|
Сборку проекта пользователя с использованием библиотек MULTEX-ARM рекомендуется производить на инструментальной машине под управлением ОС Debian, либо Ubuntu с использованием Linaro toolchain. Для настройки проекта пользователя, включения опций и подключения модулей, используются файлы config.h и Makefile. Оба файла должны лежать в директории проекта. Подробнее о структуре проекта смотри в соответствующем разделе.
Результатом сборки является бинарный файл, содержащий скомпилированный проект пользователя собранный вместе с библиотеками ядра MULTEX-ARM, пригодный для исполнения в качестве программы на целевой платформе. Такой файл вместе с дополнительными файлами проекта должен быть записан на загрузочную карту памяти целевой платформы.
Карта памяти — постоянное запоминающее устройство, с которого выполняется загрузка операционной системы на целевой платформе. В общем случае в качестве загрузочной используется карта памяти uSD вставленная в один из слотов целевой платформы. В некоторых случаях это может быть установленная на целевой платформе микросхема памяти NAND или eMMC. Иногда загрузка целевой платформы начинается с загрузчика записанного в памяти NAND или eMMC, который проверяет наличие карты памяти uSD и передаёт управление найденному там бинарному файлу. В любом случае под загрузочным будет пониматься постоянное запоминающее устройство, с которого выполняется загрузка и запуск исполняемого бинарного файла, содержащего MULTEX-ARM с процедурами пользователя.
Целевая платформа — физическое устройство (плата, вычислитель, контроллер управления и т.п.) на базе одного из поддерживаемых процессоров, для которого выполняется сборка MULTEX-ARM вместе с процедурами пользователя.
Инструментальная машина — персональный компьютер с установленным инструментарием для компиляции, сборки и копирования собранных файлов на целевую платформу (по сети, либо через интерфейс UART).
Предполагается, что сборка пользовательского проекта ведётся на инструментальной машине под управлением Debian. Для сборки проекта под Windows рекомендуется использовать виртуальную машину WSL.
Этот раздел нужен только пользователям Windows для запуска и настройки виртуальной машины Linux. Изначально WSL не содержит ни одной установленной виртуальной машины. Для сборки проектов рекомендуется установить дистрибутив Debian. Для этого из командной строки Windows следует выполнить следующую команду:
wsl --install -d Debian
В процессе установки потребуется создать нового пользователя и задать пароль.
На инструментальной машине может быть установлено несколько дистрибутивов Linux. Просмотреть список установленных можно с помощью команды:
wsl -l -v
Удобно использовать дистрибутив Debian как дистрибутив по умолчанию. Если это не так, выбрать основной дистрибутив можно с помощью команды:
wsl -s Debian
Далее предполагается что все действия в ОС Windows производятся через консоль WSL с запущенной виртуальной машиной Debian.
Для сборки проектов понадобятся следующие пакеты:
Все последующие команды набираются в консоли Linux либо в консоли WSL при работе в ОС Windows. Для установки необходимых пакетов рекомендуется воспользоваться следующей последовательностью команд:
sudo apt update sudo apt install make sudo dpkg --add-architecture armhf sudo apt update sudo apt install g++-arm-linux-gnueabihf sudo apt install build-essential git debootstrap u-boot-tools device-tree-compiler
Проверить установку компиляторов можно с помощью следующих команд:
arm-linux-gnueabihf-gcc --h arm-linux-gnueabihf-gcc --version
При компиляции проекта используются специальные утилиты, поставляемые вместе с библиотеками MULTEX-ARM. При сборке в Linux все пути прописываются в Makefile и никаких дополнительных действий предпринимать не нужно. В Windows путь к утилитам удобно прописать в переменную окружения PATH. Для сборки на виртуальной машине WSL, пути можно прописать в Переменных среды. После перезагрузки компьютера виртуальная машина подключит прописанные пути. Проверить переменные окружения WSL можно из командной строки с помощью команды:
wsl env
Частью Makefile каждого проекта является файл multex.mk поставляемый вместе с библиотеками MULTEX-ARM, в котором задана предполагаемая структура проекта пользователя. Данная структура может быть изменена, но в этом разделе будет описана структура проекта заданная по умолчанию. Подкаталоги проекта создаются автоматически (если ещё не созданы) при первом запуске сборки проекта.
Новые проекты рекомендуется размещать в директориях, создаваемых на том же уровне, на котором расположена папка с библиотеками multex_arm. В новую папку проекта следует скопировать файлы config.h и Makefile. Эти файлы можно скачать на сайте set-code.ru в составе демонстрационных примеров для различных плат, либо создать самостоятельно по описаниям приведённым ниже.
Рекомендованная структура проекта выглядит следующим образом:
config.h — это файл, содержащий набор макросов, используемых ядром MULTEX-ARM для настройки аппаратных и программных модулей. В данном разделе описаны макросы такого файла.
Для начала необходимо указать целевой процессор с помощью макроса ARCH_PROC. Значение следует выбирать из из соответствующей группы макросов. Например, для процессора V3s в файле config.h следует записать следующую строку:
#define ARCH_PROC ARCH_PROC_V3S
Для того, чтобы иметь возможность использовать в проекте инструкции сопроцессора NEON, необходимо указать макрос:
#define INCLUDE_NEON
Для задействования внутреннего кэша процессора задается макрос:
#define DCACHE_ENABLE
Так как при отключении кэша быстродействие процессора существенно снижается, не рекомендуется использовать проекты с отключенным макросом разрешения кэша. Так, работа с сетью будет приводить к ошибкам при сильной нагрузке на нее. Поэтому работа в таком режиме желательна только в отладочных целях.
Для подключения отладочной консоли по последовательному интерфейсу UART следует указать макрос:
#define INCLUDE_SIO_CONSOLE
Для подключения в проекте файловой системы ОС MS-DOS следует использовать макрос:
#define INCLUDE_DOSFS
Если в проекте предусматривается использование сети Ethernet, то нужно указать макрос:
#define INCLUDE_NETINET
Кроме того, необходимо задать IP-адрес целевой платформы, например:
#define IP_ADDRESS "10.0.3.27"
Для активации стека протоколов TCP/IP и библиотеки сетевых сокетов следует указать:
#define INCLUDE_TCP
Если планируется взаимодействие с целевой платформой через консоль по протоколу UDP, следует указать:
#define INCLUDE_NET_CONSOLE
Если же взаимодействие необходимо по протоколу TCP/IP, то следует указать:
#define INCLUDE_TCP_CONSOLE
Если в проекте необходимо использование FTP-сервера (для копирования файлов, или быстрой замены версии), следует указать:
#define FTP_SERVER
В файле config.h есть возможность указать две процедуры пользователя, которые будут вызваны на различных этапах загрузки MULTEX-ARM.
Первая из них может быть вызвана в середине загрузки — сразу после загрузки ядра. Такая процедура может быть использована, например, для вывода логотипа на дисплей (если такой имеется на целевой платформе). После вывода логотипа загрузка будет продолжена, что визуально может сократить время реакции системы на включение питания. Такое поведение актуально для процессоров с низкой производительностью. Для указания имени процедуры исполняемой после загрузки ядра следует записать макрос вида:
#define DRAW_LOGO usrDraw
Вторая процедура запускается после окончания всех программных модулей. Например, для запуска такой процедуры с именем mainProc() следует записать:
#define USER_PROC mainProc
Если макрос USER_PROC не указан, то после запуска системы будет вызван Интерпретатор команд SHELL.
Ниже приведён пример файла конфигурации для проекта пользователя на базе процессора V3s, который может использоваться как основа для файлов конфигурации пользователя.
Конфигурация аппаратной части — это текстовое описание целевой платформы составленное пользователем в определённом формате и предназначенное для настройки библиотечных модулей при запуске ядра MULTEX-ARM. Такое описание содержит в себе название процессора, название платы, описание подключения используемых периферийных устройств. Описание составляется пользователем в текстовом виде и размещается в файле с расширением arc на карте памяти целевой платформы. В начале загрузки ядра MULTEX-ARM преобразует текстовый файл в список параметров.
Список параметров конфигурации — набор пар ключ – значение созданный ядром MULTEX-ARM на этапе загрузки на базе текстового описания конфигурации аппаратной части. Созданный системой список параметров доступен для проекта пользователя только на чтение и добавление данных и может быть дополнен в исходном коде пользователя с помощью функций описанных в arch.h. Для описания аппаратной части используются зарезервированные строки-ключи описанные в файле archdef.h.
Описание аппаратной части строится на базе списков программного модуля mapstr.h. Структура списка параметоров не является жёсткой в отличие от структур и перечислений стандарта языка Си. В процессе развития операционной системы и добавления новых полей параметров структура описания аппаратной части не будет нарушена и все библиотеки будут иметь доступ к используемым ими полям списка параметоров без необходимости пересборки.
Пример чтения списка параметоров конфигурации — блок настройки аппаратных модулей характерных для каждого процессора:
Записи в созданном ядром MULTEX-ARM списке параметоров могут дублироваться, так как заполняются системой из разных источников. Поиск параметров по ключу в списке выполняется с начала списка до первого совпадения. Следовательно, записи в начале списка параметоров имеют более высокий приоритет. Загрузка списка выполняется ядром системы с учётом этой особенности – вначале грузится список из файла с расширением arc на карте памяти (если таковой имеется). Для плат, название которых содержится в файле archdef.h, список параметоров может содержать только название платы, остальные параметры конфигурации для таких плат будут подгружены автоматически из ядра системы. Далее подгружаются данные о типе процессора и затем данные из библиотек, основанные на типе процессора. Итоговый список выводится в консоль в сборке debug. Если какие-то из загруженных параметров нужно изменить их следует внести в файл конфигурации (файл с расширением arc на карте памяти).
Файл описания конфигурации аппаратной части может размещаться на одном из дисков, монтируемых при старте системы (uSD, eMMC, NAND). Название файла не имеет значения, так как поиск файла производится системой по расширению arc. Все найденные файлы с таким расширением будут загружены в общий список до инициализации основных модулей системы. В таком файле рекомендуется указать как минимум название платы, выбрав его из зарезервированных строк-ключей файла arch.h. Остальные параметры будут подгружены позже при старте программных модулей, на основании выбранной платы. Также в файле можно указать некоторые параметры конфигурации, используемые программными модулями. Так как файлы конфигурации загружаются до инициализации модулей — такие записи будут иметь более высокий приоритет, чем записи, вносимые библиотеками. Это позволяет изменять параметры конфигурации, заложенные в библиотеках. Для новых (ещё не поддержанных) плат возможно составить полное описание аппаратной части с помощью такого файла.
Файл описания является текстовым, где каждая строка является одной записью. Каждая запись состоит из набора полей, разделённых точкой с запятой. Некоторые поля могут содержать набор значений разделённых запятой. В файле могут содержаться закомментированные строки, начинающиеся со знака решётки. Первая строка файла конфигурации обязательно должна содержать подпись #MAPSTORE. Стандартный набор полей одной записи описан ниже.
Набор полей файла описания конфигурации:
Пример файла конфигурации приведён в листинге ниже. Для примера взята плата SE8351-00, описание аппаратной части которой уже содержится в ядре MULTEX-ARM (см. ARCH_BOARD_SE8350_00 в файле archdef.h). Описание такой платы может быть сгенерировано автоматически, а значит достаточно указать её название. Остальные параметры будут подгружены системой в список после загрузки файла. Параметр backlight-pwm (выбор канала ШИМ для подсветки дисплея) показан для примера. Но, при желании, можно изменить этот параметр на единицу, чтобы перенаправить управление подсветкой на другой вывод процессора.
#MAPSTORE
# parameter; type; value; desc.
#--------------------- ------------------
board-name; STR; SE8351-00;
backlight-pwm; INT; 0; PWM0
led-system; STR;
led-disk; STR;
Makefile — это файл, содержащий набор инструкций, используемых утилитой make в инструментарии автоматизации сборки. В данном разделе описаны параметры такого файла, используемого при сборке MULTEX-ARM.
При создании директории нового проекта в неё следует скопировать уже имеющийся Makefile из аналогичного проекта, например из одного из примеров на сайте set-code.ru. Либо данный файл можно составить самостоятельно. Пример готового Makefile приведён в конце раздела. Основная (универсальная для всех проектов) часть инструкций функции и цели сборки, находится в файле include/all/multex.mk, поставляемом вместе с библиотеками MULTEX-ARM. Этот файл следует включить в Makefile проекта после определения всех переменных.
include $(MULTEX_PATH)/include/all/multex.mk
Остальные инструкции, уникальные для каждого проекта, следует записать в Makefile самостоятельно, либо изменить уже имеющиеся. Ниже приведено описание используемых в Makefile уникальных инструкций.
Результатом сборки проекта является исполняемый бинарный файл, либо библиотека. Имя собираемого файла можно настроить. Указывать имя файла следует без расширения. Расширение будет добавлено в зависимости от выбранной цели сборки. Для проектов пользователя рекомендуемое имя — multex, так как именно такое имя указано по умолчанию в используемых загрузчиках. Для определения имени выходного файла следует записать инструкцию:
PROJ_NAME = multex
Компиляция файлов исходных кодов осуществляется с оптимальным набором флагов компилятора. Пользовательские флаги компилятора могут быть добавлены при необходимости с помощью переменной USR_CFLAGS:
USR_CFLAGS =
В Makefile выполняется управление распределением памяти ОЗУ. При сборке итогового проекта линковщику передаётся значение адреса, по которому будет размещена запускающая процедура MULTEX-ARM. Данное значение размещается в переменной MX_TEXT. Это значение должно совпадать со значением записанным в загрузчике в качестве адреса запуска. Кроме того, в здесь же определяются значения адресов начала и конца ОЗУ. Они записываются в переменные DRAM_START и MEM_POOL_END соответственно и используются самой операционной системой для корректного выделения памяти. Ниже приведены адреса, записываемые в Makefile по умолчанию:
DRAM_START = 0x40000000 MX_TEXT = 0x48000000 MEM_POOL_END = 0x80000000
Переменные DRAM_START и MX_TEXT одинаковы для большинства поддерживаемых плат и их значения можно не указывать в Makefile проекта. Значение адреса MEM_POOL_END соответствует 1 Гб используемого ОЗУ и должно быть изменено, если на плате установлена память меньшего объёма. Максимальные значения переменной MEM_POOL_END для разных объёмов памяти приведены ниже:
В разделе Описание структуры проекта пользователя описана структура проекта по умолчанию. Такое взаимное расположение директорий учтено в файле include/all/multex.mk и если придерживаться структуры директорий по умолчанию, то дополнительная настройка путей не потребуется. Однако в некоторых случаях структуру проекта можно изменить или дополнить. Такие изменения взаимного расположения директорий проекта и MULTEX-ARM можно сделать с помощью инструкций описанных в этом разделе.
Путь к текущей версии MULTEX-ARM можно задать с помощью следующей инструкции:
MULTEX_PATH = ../multex_arm
Список исходных файлов проекта и директорий, содержащих исходные файлы можно изменить или дополнить с помощью инструкции SRC_PATHS. В процессе компиляции и сборки проекта утилита make пройдёт по указанным директориям и всем вложенным в неё и соберёт все исходные файлы. По умолчанию подключается одна папка src, лежащая в корне проекта. Если директории по умолчанию не существует, то она будет создана при первом запуске сборки. Все дополнительные файлы и папки следует добавить в переменную SRC_PATHS. Если используется директория по умолчанию — переменную добавлять не нужно. Пример определения пути к исходным файлам проекта:
SRC_PATHS = ./src
Путь к собираемому бинарному файлу или библиотеке следует задать, если он отличается от значения по умолчанию out. Указанная папка будет создана при сборке, если ещё не создана. Если используется директория по умолчанию — переменную добавлять не нужно. Пример определения пути к собираемому бинарному файлу:
OUT_PATH = ./out
В переменную INCLUDES по умолчанию помещается путь к заголовочным файлам MULTEX-ARM. Если в проекте используются дополнительные папки с заголовочными файлам их следует добавить к этой переменной, например:
INCLUDES += ../my_includes
При сборке библиотеки имеет смысл указать заголовочные файлы, которые будут скопированы в multex_arm/include. При этом сама библиотека копируется в multex_arm/lib. Например, для копирования двух заголовочных файлов библиотеки шрифтов можно записать:
OUT_HEADERS += src/fonts.h OUT_HEADERS += src/fontsdefines.h
Для размещения заголовочных файлов копируемых библиотек в подкаталоге директории multex_arm/include следует указать имя подкаталога в переменной OUT_HEADERS_PATH. Иначе заголовочные файлы библиотек будут скопированы непосредственно в multex_arm/include. Например для копирования заголовочных файлов библиотеки в папку multex_arm/include/multimedia следует записать:
OUT_HEADERS_PATH = multimedia
К каждому проекту при сборке подключается набор библиотек. Часть библиотек (например, библиотеки ядра MULTEX-ARM) подключаются неявно, остальные подключаемые библиотеки нужно указывать в Makefile с помощью инструкции LIBRARIES. Все файлы библиотек MULTEX-ARM по умолчанию находятся в папке multex_arm/lib. Библиотеки пользователя рекомендуется помещать сюда же. Сборка ядра MULTEX-ARM возможна с минимальным набором библиотек. Их набор может варьироваться в зависимости от использования в проекте различных аппаратных модулей. Рекомендации по подключению конкретных файлов библиотек содержатся в описаниях подсистем операционной системы. Например, для подключения библиотеки аппаратной поддержки графики с поддержкой формата PNG следует указать:
LIBRARIES += -l_a20graph LIBRARIES += -l_png -l_z
В комплект поставки MULTEX-ARM входят файлы исходных кодов, содержащих примеры использования различных библиотек операционной системы. Для подключения этих функций к собираемому бинарному файлу следует добавить путь к одной из папок с примерами в переменную SRC_PATHS. Например, подключить примеры для процессора V3s можно с помощью следующей записи:
SRC_PATHS += $(MULTEX_PATH)/include/examples/v3s
Все подключенные тестовые функции можно вызывать из консоли Shell.
Ниже приведён пример простого Makefile для процессора V3s, который можно использовать в качестве основы для проектов пользователя:
#------------------------------------------ # Makefile сборки проектов и библиотек # для запуска Multex-ARM на процессоре V3s # © ООО «Сэт Код», 2023 (set-code.ru) #------------------------------------------ PROJ_NAME = multex MX_TEXT = 0x41000000 MEM_POOL_END = 0x44000000 MULTEX_PATH = ../multex_arm LIBRARIES += -l_enet -l_tcp include $(MULTEX_PATH)/include/all/multex.mk
Файлы проекта вместе с библиотеками и ядром MULTEX-ARM собираются с помощью утилиты make из директории проекта. В результате сборки в проекте появится папка (по умолчанию out) с бинарным файлом (по умолчанию multex.bin), который следует скопировать на запоминающее устройство целевой платформы. Это и есть запускаемый файл проекта.
Сборка проекта осуществляется с помощью Makefile поставляемого вместе с библиотеками. В файле уже имеются специализированные цели сборки проектов, библиотек и объектных файлов. Ниже описаны основные цели сборки, имеющиеся в предоставляемом Makefile.
Краткую помощь по целям сборки можно получить с помощью цели:
make help
Для сборки отладочной версии проекта используется цель debug. В итоге такой сборки получается версия бинарного файла содержащая таблицу символов. При этом появляется возможность вызывать функции по имени из консоли. Кроме того, при компиляции файлов определяется макрос DEBUG, который можно использовать для отладочного вывода. Для отладочной сборки следует использовать цель:
make debug
Для сборки поставочной версии проекта используется цель release. В такой версии не собирается таблица символов и определяется макрос RELEASE. Для сборки поставочной версии следует использовать цель:
make release
Для сборки библиотеки и копирования её вместе с указанными заголовочными файлам в директорию MULTEX-ARM следует использовать цель:
make lib
Если пересборка библиотеки не нужна а нужно только скопировать итоговый бинарный файл библиотеки вместе с заголовочными файлами в директорию MULTEX-ARM, то можно использовать цель:
make copy
Очистка проекта от временных и объектных файлов выполняется с помощью цели:
make clean
Также реализована возможность компилировать объектные файлы из исходных по имени. Например для файла filename.c команда компиляции будет выглядеть так:
make filename.o
Для запуска собранного проекта на целевой платформе следует:
Для копирования файлов на карту памяти uSD через кардридер инструментальной машины можно воспользоваться целями сборки Makefile. Для копирования всех файлов из папки out:
make install
Для обновления только собранного бинарного файла:
make update
export DEVNAME=sda
Кроме того, бинарный файл можно заменить по сети на уже работающей целевой платформе. Для этого на ней должен быть запущен FTP-сервер. За запуск сервера отвечает параметр FTP_SERVER файла конфигурации. При подключении к серверу будет доступна файловая система целевой платформы и бинарный файл можно заменить стандартными командами FTP.
Параметры для соединения с запущенным FTP-сервером:
1.9.1