docs: добавь поясняющие комментарии к модулям и инструментам

c/set-protocol/ports/stm32g474-usb-boot/boot_config.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация set-protocol для порта stm32g474-usb-boot. Макросы задают параметры сборки и
+ * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения
+ * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 #ifndef G474_BOOT_CONFIG_H
 #define G474_BOOT_CONFIG_H
 #define G474_BOOT_NODE 16U

c/set-protocol/ports/stm32g474-usb-boot/boot_flash.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные операции Flash односекционного USB-загрузчика: стирание, запись, проверка и
+ * фиксация образа. Геометрия разделов берётся из конфигурации платы; признак завершения нельзя
+ * записывать до успешной проверки данных.
+ */
+
 #include "boot_port.h"
 #include "boot_image.h"
 #include "boot_writer.h"

c/set-protocol/ports/stm32g474-usb-boot/boot_image.h

@@ -1,3 +1,9 @@
+/*
+ * Проверки образа перед передачей управления приложению. Адрес стека и вектор сброса должны
+ * соответствовать памяти целевой платы; наличие байтов во Flash само по себе не означает
+ * готовность образа к запуску.
+ */
+
 #ifndef G474_BOOT_IMAGE_H
 #define G474_BOOT_IMAGE_H
 #include "boot_port.h"

c/set-protocol/ports/stm32g474-usb-boot/boot_main.c

@@ -1,3 +1,9 @@
+/*
+ * Старт USB-загрузчика и выбор между обслуживанием обновления и запуском приложения. Здесь
+ * настраиваются аппаратные часы и цикл обслуживания; код выполняется в окружении конкретного
+ * MCU.
+ */
+
 #include "stm32g4xx_hal.h"
 #include "boot_port.h"
 #include "usb_cdc.h"

c/set-protocol/ports/stm32g474-usb-boot/boot_port.h

@@ -1,3 +1,9 @@
+/*
+ * Контракт аппаратного USB-загрузчика: доступ к образу, запрос перезапуска и операции Flash.
+ * Его реализация зависит от семейства MCU, тогда как последовательность обновления задаётся
+ * общим set_boot.
+ */
+
 #ifndef G474_BOOT_PORT_H
 #define G474_BOOT_PORT_H
 #include "set_boot.h"

c/set-protocol/ports/stm32g474-usb-boot/boot_request.c

@@ -1,3 +1,8 @@
+/*
+ * Передача запроса входа в загрузчик через backup-состояние и отложенный сброс. Флаг должен
+ * пережить перезапуск, чтобы загрузчик отличил обновление от обычного старта приложения.
+ */
+
 #include "boot_port.h"
 #include "stm32g4xx_hal.h"
 #define REQUEST_MAGIC 0x42555342UL

c/set-protocol/ports/stm32g474-usb-boot/boot_usb_port.c

@@ -1,3 +1,8 @@
+/*
+ * Низкоуровневая связка USB FS и CDC на STM32G474. Используется статическое состояние одного
+ * CDC-класса и PMA; обработка конечных точек отделена от разбора протокола обновления.
+ */
+
 /* STM32G474 USB FS device, dedicated PA11/PA12 pins, single-buffer PMA. */
 #include "usbd_core.h"
 #include "usbd_cdc.h"

c/set-protocol/ports/stm32g474-usb-boot/boot_usb_stream.c

@@ -1,3 +1,9 @@
+/*
+ * Обслуживание SETProtocol v2 поверх USB CDC для загрузчика. Поток USB разбирается на полные
+ * команды, после чего операции передаются общему автомату обновления; граница USB-пакета не
+ * является границей SET-кадра.
+ */
+
 #include "stm32g4xx_hal.h"
 #include "boot_port.h"
 #include "boot_config.h"

c/set-protocol/ports/stm32g474-usb-boot/boot_writer.h

@@ -1,3 +1,9 @@
+/*
+ * Накопление неполного 64-битного слова Flash STM32G474 между пакетами. ECC требует
+ * программировать слово один раз; только последний хвост дополняется 0xFF, а длина исходного
+ * образа остаётся неизменной.
+ */
+
 #ifndef G474_BOOT_WRITER_H
 #define G474_BOOT_WRITER_H
 #include <stdbool.h>
@@ -17,6 +23,9 @@ static inline void g474_writer_init(g474_writer *w, uint32_t size)
     memset(w, 0, sizeof(*w)); w->size = size;
     memset(w->pending, 0xff, sizeof(w->pending));
 }
+/* offset и length описывают байты исходного образа. Хвост пакета остаётся
+ * в pending до следующего вызова; повтор или перестановка пакетов запрещены.
+ * После отказа program контекст помечается failed до новой инициализации. */
 static inline bool g474_writer_write(g474_writer *w, uint32_t offset,
     const uint8_t *data, uint16_t length, g474_program_word program, void *user)
 {
@@ -26,6 +35,8 @@ static inline bool g474_writer_write(g474_writer *w, uint32_t offset,
         w->pending[w->used++] = *data++; ++w->received;
         if (w->used == 8 || w->received == w->size) {
             uint64_t word;
+            /* Адрес берётся от начала накопленного слова, а не от границы
+             * текущего пакета, которая может проходить внутри этого слова. */
             uint32_t start = w->received - w->used;
             memcpy(&word, w->pending, sizeof(word));
             if (!program(user, start, word)) { w->failed = true; return false; }

c/set-protocol/ports/stm32g474-usb-boot/test_boot_port.c

@@ -1,3 +1,11 @@
+/*
+ * Проверки boot_port: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_writer
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "boot_image.h"
 #include "boot_writer.h"
 #include <assert.h>