lift_indicator_suite/bsp

BSP — Board Support Package

Целевая платформа: NXP MIMXRT1052CVJ5B Используется в: firmware/bootloader, firmware/test, firmware/tft_app

---

Концепция

BSP — единственное место в монорепо где есть знание о конкретном железе. Все три прошивки работают с периферией только через BSP. Прямых вызовов NXP SDK (fsl_*.h) за пределами bsp/ быть не должно.

graph TB
    FW["firmware/test · firmware/bootloader · firmware/tft_app"]
    BSP["BSP"]
    SDK["NXP SDK / middleware\nfsl_lpuart · fsl_gpio · fsl_iomuxc · …"]

    FW --> BSP --> SDK

---

Структура

bsp/
├── CMakeLists.txt          # корневой: bsp_board + add_subdirectory для компонентов
├── README.md               # этот файл
│
├── generated/              # ← MCUXpresso Config Tools, не редактировать руками
│   ├── board.c / board.h
│   ├── clock_config.c / clock_config.h
│   ├── pin_mux.c / pin_mux.h
│   ├── syscalls.c
│   ├── TFT_Board.mex       # ← источник истины, открывать в Config Tools
│   └── startup/
│       └── startup_MIMXRT1052.S
│
├── common/                 # bsp_status_t и общие типы
├── led/                    # bsp_led          — два UserLed (GPIO3[3], GPIO3[4])
├── tick/                   # bsp_tick         — SysTick / FreeRTOS-совместимый таймер
├── uart_host/              # bsp_uart_host    — LPUART1 (MCU-Link VCOM, J2)
│   └── mocks/              # fff-заглушки для host-тестов
├── opto/                   # bsp_opto         — оптоизолированные входы PS2801-4
├── can/                    # bsp_can          — FlexCAN2 (трансивер SN65HVD230D)
│   └── mocks/              # fff-заглушки для host-тестов
├── button/                 # bsp_button       — тактовые кнопки SWT6x6 с debounce
├── display/                # bsp_display      — TFT-дисплей
├── usb_cdc/                # bsp_usb_cdc      — USB CDC ACM
├── sdram/                  # bsp_sdram        — внешний SDRAM через SEMC
├── qspi_flash/             # bsp_qspi_flash   — QSPI Flash W25Q64/128/256/512
├── sd/                     # bsp_sd           — SD host-контроллер (USDHC1)
├── mqs/                    # bsp_mqs          — MQS аудио-выход (SAI3, MQS, eDMA + управление громкостью)
└── provisioning/           # bsp_provisioning — OCOTP UID (уникальный идентификатор чипа)

---

Компоненты CMake

Каждый компонент — отдельная статическая библиотека bsp_<name>.

bsp_board — фундамент

target_link_libraries(bsp_<любой_компонент> PUBLIC bsp_board)

Содержит стартап, clock config, pin mux, board init. Формируется из generated/ и не должен меняться руками — только через MCUXpresso Config Tools.

Boot-стратегии — INTERFACE-библиотеки

Таргет CMake	Сценарий	Кто использует
bsp_boot_xip	XIP — исполнение из Flash	firmware/test, firmware/tft_app
bsp_boot_ram	Исполнение из ITCM/DTCM	HIL target-прошивки (tests/target/)

Подключается явно в каждом проекте:

target_link_libraries(firmware_test PRIVATE bsp_board bsp_boot_xip ...)
target_link_libraries(test_hil_opto PRIVATE bsp_board bsp_boot_ram ...)

Компоненты периферии

Библиотека	Модуль	README
bsp_led	led/	led/README.md
bsp_tick	tick/	tick/README.md
bsp_uart_host	uart_host/	uart_host/README.md
bsp_opto	opto/	opto/README.md
bsp_can	can/	can/README.md
bsp_button	button/	button/README.md
bsp_display	display/	display/README.md
bsp_usb_cdc	usb_cdc/	usb_cdc/README.md
bsp_sdram	sdram/	sdram/README.md
bsp_qspi_flash	qspi_flash/	qspi_flash/README.md
bsp_sd	sd/	sd/README.md
bsp_mqs	mqs/	mqs/README.md
bsp_provisioning	provisioning/	provisioning/README.md

---

Правила написания компонентов

Граница изоляции

Публичные заголовки (include/bsp/*.h) не должны содержать ни одного #include из NXP SDK. Снаружи BSP — только стандартные типы C и собственные типы проекта.

/* ПРАВИЛЬНО — bsp/opto/include/bsp/opto.h */
#include <stdint.h>
#include <stdbool.h>
#include "bsp/status.h"

/* НЕПРАВИЛЬНО */
#include "fsl_gpio.h"   /* ← утечка NXP SDK наружу */

Платформенные хедеры (fsl_*.h) живут только в src/ — как PRIVATE зависимости.

Структура одного компонента

bsp/<name>/
├── CMakeLists.txt
├── README.md
├── include/
│   └── bsp/
│       └── <name>.h        # публичный API — без NXP хедеров
└── src/
    └── <name>.c            # реализация — fsl_*.h только здесь

# bsp/<name>/CMakeLists.txt — шаблон
add_library(bsp_<name> STATIC src/<name>.c)

target_include_directories(bsp_<name>
    PUBLIC  include/
    PRIVATE src/
)

target_link_libraries(bsp_<name>
    PUBLIC  bsp_status
    PRIVATE bsp_board sdk_<driver>
)

Защита от host-сборки

Компоненты с зависимостью от железа закрываются guard-ом в CMakeLists:

if(BUILD_TESTS_HOST)
  return()
endif()

Компоненты которые тестируются на хосте предоставляют fff-заглушки в mocks/ (пример — uart_host/mocks/).

---

generated/ — MCUXpresso Config Tools

generated/ — выхлоп Config Tools. Содержит конфигурацию тактирования, пинов и периферии для конкретной платы. Источник истины — TFT_Board.mex.

Трогать нельзя: редактировать файлы из generated/ руками — изменения потеряются при следующей перегенерации.

Как добавить новый пин или периферию: открыть TFT_Board.mex в MCUXpresso Config Tools → внести изменения → Update Code → закоммитить изменённые файлы из generated/.

---

Добавление нового компонента — чеклист

[ ] bsp/<name>/include/bsp/<name>.h  — публичный API без NXP хедеров
[ ] bsp/<name>/src/<name>.c          — реализация
[ ] bsp/<name>/CMakeLists.txt        — guard BUILD_TESTS_HOST + зависимости
[ ] bsp/<name>/README.md             — аппаратура + API + использование
[ ] bsp/CMakeLists.txt               — add_subdirectory(<name>)
[ ] firmware/*/CMakeLists.txt        — добавить bsp_<name> в нужные прошивки