Бывают ситуации, когда к разработке firmware надо подключить новых людей. Как объяснить им архитектуру нынешнего ПО?
Глобально в каждом Firmware репозитории весь код можно отсортировать на такие мега-части как sensitivity, connectivity, control, computing , security и storage.
Код из каждой части может быть как-то связан с частями из других программных компонентов. В программировании микроконтроллеров программы по-хорошему должны строится иерархично. То есть один программный компонент вызывает функции из другого программного компонента.
Например драйверу чтения SD‑карты нужны функции от драйвера SPI, драйвера GPIO, компонента CRC7, CRC16 и т. п.
Как бы представить эту взаимосвязь для каждой конкретной сборки прошивки? Очевидно, что надо нарисовать граф. То есть, картинку, где стрелочки и прямоугольники покажут как всё взаимно связано. И тут-то на помощь нам как раз и приходит язык разметки графов Graphviz.
Для кода на языке Graphviz можно сделать полуавтоматический кодо генератор. Надо обязать программиста, чтобы в папке каждого программного компонента был крохотный файлик *.gvi для явного указания высокоуровневых зависимостей. Для простоты поддержки этот *.gvi файл надо называть так же как имя папки в которой лежит *.gvi.
Смотришь в *.c код, примерно видишь, что там подключается #include «*.h», что вызывается в самих функциях и отражаешь это в *.gvi файле рядом. Вот примерное содержимое для pdm.gvi. PDM — это программный компонент для записи звука из MEMS микрофонов.
GPIO->PDM
NVIC->PDM
REG->PDM
DFT->PDM
RAM->PDM
AUDIO->PDM
DMA->PDM
В этом *.gvi файле надо вручную прописать какие у данного программного компонента есть зависимости от других программных компонентов. Сделать это можно на простеньком текстовом языке Graphviz. По факту, всё что понадобится из синтаксиса языка Graphviz — это оператор стрелка «->»
Также нужен корневой файл main.gvi в который будет всё вставляться утилитой препроцессором (cpp.exe).
strict digraph graphname {
rankdir=LR;
splines=ortho
node [shape="box"];
#ifdef HAS_BSP
#include "bsp.gvi"
#endif
#ifdef HAS_THIRD_PARTY
#include "third_party.gvi"
#endif
#ifdef HAS_PROTOCOLS
#include "protocols.gvi"
#endif
#ifdef HAS_ADT
#include "adt.gvi"
#endif
#ifdef HAS_ASICS
#include "asics.gvi"
#endif
#ifdef HAS_MCU
#include "mcu.gvi"
#endif
#ifdef HAS_COMMON
#include "common.gvi"
#endif
#include "components.gvi"
#ifdef HAS_UTILS
#include "utils.gvi"
#endif
#ifdef HAS_CORE
#include "core.gvi"
#endif
#ifdef HAS_DRIVERS
#include "drivers.gvi"
#endif
#ifdef HAS_INTERFACES
#include "interfaces.gvi"
#endif
}
Также нужен makefile скрипт, который будет собирать все отдельные файлы с зависимостями в один единый файл на языке Graphviz. План такой. Надо организовать вот такой программный конвейер.
Заметьте, тут работает самый обыкновенный препроцессор из программ на Си (утилита cpp). Препроцессору всё равно с каким кодом работать. Препроцессор просто вставляет и заменяет куски текста. Утилиту cpp.exe можно вообще порекомендовать писателям учебников или чертёжникам.
Далее сам скрипт generate_dependencies.mk, который определяет ToolChain для построения изображения в привычном *.pdf/*.svg файле.
#CC=C:/cygwin64/bin/dot.exe
$(info Generate Dependencies)
CC_DOT="C:/Program Files/Graphviz/bin/dot.exe"
RENDER="C:/Program Files/Google/Chrome/Application/chrome.exe"
$(info MK_PATH=$(MK_PATH))
MK_PATH_WIN := $(subst /cygdrive/c/,C:/, $(MK_PATH))
$(info MK_PATH_WIN=$(MK_PATH_WIN))
$(info WORKSPACE_LOC=$(WORKSPACE_LOC))
ARTEFACTS_DIR=$(MK_PATH_WIN)$(BUILD_DIR)
$(info ARTEFACTS_DIR=$(ARTEFACTS_DIR))
SOURCES_DOT=$(WORKSPACE_LOC)main.gvi
$(info SOURCES_DOT=$(SOURCES_DOT))
SOURCES_DOT:=$(subst /cygdrive/c/,C:/, $(SOURCES_DOT))
$(info SOURCES_DOT=$(SOURCES_DOT))
SOURCES_DOT_RES += $(ARTEFACTS_DIR)/$(TARGET)_dep.gv
$(info SOURCES_DOT_RES=$(SOURCES_DOT_RES))
ART_SVG = $(ARTEFACTS_DIR)/$(TARGET)_res.svg
ART_PDF = $(ARTEFACTS_DIR)/$(TARGET)_res.pdf
$(info ART_SVG=$(ART_SVG) )
$(info ART_PDF=$(ART_PDF) )
CPP_GV_OPT += -undef
CPP_GV_OPT += -P
CPP_GV_OPT += -E
CPP_GV_OPT += -nostdinc
CPP_GV_OPT += $(OPT)
DOT_OPT +=-Tsvg
#DOT_OPT +=-L10
#DOT_OPT +=-v
#LAYOUT_ENGINE = -Kneato
#LAYOUT_ENGINE = -Kfdp
#LAYOUT_ENGINE = -Ksfdp
#LAYOUT_ENGINE = -Ktwopi
#LAYOUT_ENGINE = -Kosage
#LAYOUT_ENGINE = -Kpatchwork
LAYOUT_ENGINE = -Kdot
DEPENDENCY_GRAPH += generate_dep
preproc_graphviz:$(SOURCES_DOT)
$(info Preproc...)
#mkdir $(ARTEFACTS_DIR)
cpp $(SOURCES_DOT) $(CPP_GV_OPT) $(INCDIR) -E -o $(SOURCES_DOT_RES)
generate_dep_pdf: preproc_graphviz
$(info route graph...)
$(CC_DOT) -V
$(CC_DOT) -Tpdf $(LAYOUT_ENGINE) $(SOURCES_DOT_RES) -o $(ARTEFACTS_DIR)/$(TARGET).pdf
generate_dep_svg: preproc_graphviz
$(info route graph...)
$(CC_DOT) -V
$(CC_DOT) $(DOT_OPT) $(SOURCES_DOT_RES) -o $(ARTEFACTS_DIR)/$(TARGET).svg
generate_dep: generate_dep_svg generate_dep_pdf
$(info All)
print_dep: generate_dep
$(info print_svg)
$(RENDER) -open $(ARTEFACTS_DIR)/$(TARGET).svg
$(RENDER) -open $(ARTEFACTS_DIR)/$(TARGET).pdf
#clean:
# $(info clean)
# rm $(MK_PATH)/artefacts/*.*
#$(ART_SVG):$(ART_SVG)
Скрипт generate_dependencies.mk следует условно подключить к основному скрипту сборки проекта rules.mk
DEPENDENCY_GRAPH=
ifeq ($(DEPENDENCIES_GRAPHVIZ), Y)
include $(WORKSPACE_LOC)/generate_dependencies.mk
endif
.......
# default action: build all
all: generate_definitions $(BUILD_DIR)/$(TARGET).elf $(BUILD_DIR)/$(TARGET).hex $(BUILD_DIR)/$(TARGET).bin $(DEPENDENCY_GRAPH)
generate_definitions:
cpp $(CPP_FLAGS) $(WORKSPACE_LOC)empty_sourse.c -dM -E> c_defines_generated.h
далее в основном make файле определить переменную окружения DEPENDENCIES_GRAPHVIZ=Y
MK_PATH:=$(dir $(realpath $(lastword $(MAKEFILE_LIST))))
#@echo $(error MK_PATH=$(MK_PATH))
WORKSPACE_LOC:=$(MK_PATH)../../
INCDIR += -I$(MK_PATH)
INCDIR += -I$(WORKSPACE_LOC)
DEBUG=Y
TARGET=board_name_build_name
DEPENDENCIES_GRAPHVIZ=Y
include $(MK_PATH)config.mk
ifeq ($(CLI),Y)
include $(MK_PATH)cli_config.mk
endif
ifeq ($(DIAG),Y)
include $(MK_PATH)diag_config.mk
endif
ifeq ($(UNIT_TEST),Y)
include $(MK_PATH)test_config.mk
endif
include $(WORKSPACE_LOC)code_base.mk
include $(WORKSPACE_LOC)rules.mk
Теперь достаточно просто открыть консоль и набрать make all и вместе с артефактами с прошивкой у Вас рядом появится и файлы документации с изображением зависимостей.
Скрипт сборки сгенерирует вот такой финальный Graphviz код
strict digraph graphname {
rankdir=LR;
splines=ortho
node [shape="box"];
REG->ADC
NVIC->ADC
REG->FLASH
REG->GPIO
REG->TIMER
TIMER->TIME
REG->I2S
NVIC->I2S
SW_DAC->I2S
NVIC->I2C
GPIO->I2C
REG->I2C
FLASH->NVS
GPIO->PDM
NVIC->PDM
REG->PDM
DFT->PDM
RAM->PDM
AUDIO->PDM
DMA->PDM
GPIO->SPI
NVIC->SPI
SYSTICK->TIME
GPIO->UART
UART->LOG
LOG->CLI
CLI->PROTOCOL
CRC8->TBFP
RAM->ARRAY
SPI->DW1000
GPIO->DW1000
TIME->DW1000
DW1000->DWM1000
CRC7->SD_CARD
CRC16->SD_CARD
SPI->SD_CARD
GPIO->SD_CARD
TIME->SD_CARD
DW1000->DECADRIVER
TIME->DECADRIVER
GPIP->DECADRIVER
SPI->DECADRIVER
I2S->MAX98357
GPIO->MAX98357
SD_DAC->MAX98357
NVIC->CORTEX_M33
SYSTICK->CORTEX_M33
}
В качеств примера у Вас получится примерно вот такой граф зависимостей.
Для расширения детализации дерева зависимостей надо просто добавлять новые *.gvi файлы. Их будет много (десятки) но они простые как правило по 3-6 строчек в каждом. В каждой папке с кодом должен лежать один *.gvi файл.
Вот, например, граф зависимости программных компонентов для прошивки хранителя паролей Pas~ r1.1
Достоинства графа зависимостей
Хорошая схема зависимостей программных компонентов поможет быстро ввести в курс дела новых людей. Прежде всего программистов.
Граф зависимостей позволит выявить паразитные зависимости и оптимизировать архитектуру всей программы.
Автогенератор зависимостей легко встраивается в сборку, если система сборки предварительно написана на make скриптах, так как утилита make она, в сущности, всеядная. Утилите make.exe как и cpp.exe всё равно для какого языка программирования Вы её вызвали. Make.exe — это просто дирижёр программного конвейера.
Для каждой отдельной сборки строится её собственный граф зависимостей. Лишний код из соседней папки не участвует.
Граф строится автоматически по коду из *.gv файла. Мышка тут абсолютно не нужна.
Недостатки графа зависимостей
Надо писать makefile надо освоить спецификацию GNU make (т. е. просмотреть по диагонали 200 страниц). Если Вы всё еще в 2023м собираете прошивки из GUI‑IDE, то могу Вам только посоветовать позвонить в техподдержку вашей IDE.
Надо вручную прописать *.gvi файл для каждого программного компонента.
Автоматический трассировщик графа от Graphviz не всегда удачно разводит граф
Вывод
Как видите, сборка из скриптов позволяет Вам помимо получения бинарных артефактов (*.bin, *.hex, *.map, *.elf) также авто генерировать всяческую документацию (*.pdf, *.svg, *.gv). Например, такую полезную схему как дерево зависимостей между программными компонентами. Это является хорошей причиной, чтобы собирать прошивки не из GUI-IDE, а из самописных скриптов.
Стоит отметить, что получившееся дерево зависимостей программных компонентов поймут скорее только программисты-микроконтроллеров нежели схемотехники. Чтобы читать дерево зависимостей надо примерно знать основы Computer Science. Надо понимать, что такое AES256, BASE64, CRC, CLI, CSV, FIFO, LIFO, DFT, FFT, XLM и прочие акронимы.
А вообще как по мне, дак самая лучшая документация к коду - это модульные тесты. https://habr.com/ru/articles/698092/
В модульных тестах сразу видно как заполнять прототипы функций и что делать с результатом работы функции.
Еще голый код и утилита grep при определенной сноровке могут позволить извлечь полезные сведения о коде.
Вариантов много.
У меня есть еще один текст про документацию. Это схема ToolChain(а). Про это можно почитать тут https://habr.com/ru/articles/688542/ . Тоже весьма полезная вещь для понимания происходящего под капотом.
Словарь
Акроним | Расшифровка |
GVI | Graphviz Include |
Links
https://dreampuf.github.io/GraphvizOnline/
Что Должно Быть в Каждом FirmWare Pепозитории https://habr.com/ru/articles/689542/
Синергия Graphviz и препроцессора C/C++
Почему Важно Собирать Код из Скриптов
Тандем Cpp/Dot для Описания Сложных ToolСhain(ов)
Язык Graphviz для Автогенерации Блок-Схем Сложных Электронных Цепей
Задача про две ёмкости для жидкости
