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

c/set-protocol/src/altera_logic.c

@@ -1,3 +1,9 @@
+/*
+ * Автомат UART-клиента логического анализатора Altera: запрос, накопление ответа и контроль
+ * времени. Одновременно выполняется одна операция; ARM нельзя безусловно повторять, поскольку
+ * повторный запуск меняет состояние захвата.
+ */
+
 #include "altera_logic.h"
 #include <string.h>
 typedef struct {

c/set-protocol/src/altera_stream.c

@@ -1,3 +1,9 @@
+/*
+ * Приём потока выборок Altera Logic через SETCAN/GAS по CAN или UART. Счётчики выборок
+ * сохраняют положение во времени; получение пакетов и обновление изображения должны
+ * обслуживаться независимо.
+ */
+
 #include "altera_stream.h"
 #include "pcan_id.h"
 #include <string.h>

c/set-protocol/src/balsam_can.c

@@ -1,3 +1,9 @@
+/*
+ * Исторический регистровый CAN-протокол BALZAM/TMS2812. Формат идентификаторов и порядок слов
+ * относятся именно к этому профилю; общий физический CAN не делает его совместимым с SET v2
+ * или протоколом ПМ35.
+ */
+
 #include "balsam_can.h"
 
 #include <stdio.h>

c/set-protocol/src/firmware_image.c

@@ -1,3 +1,9 @@
+/*
+ * Проверка Intel HEX и подготовка адресованного образа прошивки. Контрольные суммы записей,
+ * расширенные адреса и пересечения проверяются до использования результата; рабочая память
+ * C-парсера принадлежит вызывающему.
+ */
+
 #include "firmware_image.h"
 #include <stdlib.h>
 

c/set-protocol/src/gui_catalog.c

@@ -1,3 +1,9 @@
+/*
+ * Каталог объектов GUI v1 и подписка на выбранные значения. Записи каталога описывают типы,
+ * адреса и имена; поток наблюдения передаёт значения отдельно от описания, поэтому клиент
+ * должен сохранять соответствие выбранным объектам.
+ */
+
 #include "gui_catalog.h"
 
 static size_t name_len(const char *name)

c/set-protocol/src/gui_frame.c

@@ -1,3 +1,9 @@
+/*
+ * Кадрирование GUI v1 с сигнатурой A5 5A и CRC32. Потоковый разбор сохраняет незавершённое
+ * сообщение между вызовами; готовый кадр выдаётся только после проверки длины и контрольной
+ * суммы.
+ */
+
 #include "gui_frame.h"
 
 uint32_t gui_crc32(const uint8_t *data, size_t len)

c/set-protocol/src/pcan_abi.c

@@ -1,3 +1,9 @@
+/*
+ * Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры
+ * буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют
+ * согласованного обновления привязок.
+ */
+
 #include "pcan_abi.h"
 
 #include <string.h>

c/set-protocol/src/pcan_crc.c

@@ -1,3 +1,9 @@
+/*
+ * CRC-16/CCITT-FALSE для транспортного кадра ProtoCAN. Табличный и побитовый варианты должны
+ * давать одинаковый результат; CRC считается по оговорённым байтам кадра, без добавления
+ * сигнатуры.
+ */
+
 #include "pcan_crc.h"
 
 #if PCAN_CRC_TABLE

c/set-protocol/src/pcan_frame.c

@@ -1,6 +1,14 @@
+/*
+ * Преобразование CAN-кадра в поток AA 55 и обратный побайтный разбор. LEN описывает участок
+ * SEQ..DATA, CRC16 покрывает LEN..DATA; частичный пакет остаётся в состоянии parser до
+ * следующего фрагмента.
+ */
+
 #include "pcan_frame.h"
 #include "pcan_crc.h"
 
+/* Требуется буфер максимального кадра даже при коротком DATA. Возврат 0
+ * означает отказ до записи; успешный результат — фактически занятые байты. */
 size_t pcan_frame_encode(const pcan_frame_t *frame, uint8_t *out, size_t out_size)
 {
     if ((frame == NULL) || (out == NULL) || (out_size < PCAN_FRAME_MAX)) {
@@ -13,6 +21,7 @@ size_t pcan_frame_encode(const pcan_frame_t *frame, uint8_t *out, size_t out_siz
     out[n++] = PCAN_SOF0;
     out[n++] = PCAN_SOF1;
 
+    /* Сигнатура нужна для синхронизации, но не входит в защищённое CRC тело. */
     size_t body = n;
     out[n++] = (uint8_t)(PCAN_LEN_MIN + dlc);
     out[n++] = frame->seq;
@@ -31,6 +40,8 @@ size_t pcan_frame_encode(const pcan_frame_t *frame, uint8_t *out, size_t out_siz
     return n;
 }
 
+/* Полный сброс сеанса разбора, включая диагностические счётчики.
+ * Контекст p должен быть выделен вызывающим и не может быть NULL. */
 void pcan_parser_init(pcan_parser_t *p)
 {
     p->state = PCAN_ST_SOF0;
@@ -43,6 +54,9 @@ void pcan_parser_init(pcan_parser_t *p)
     p->stats.stray_bytes = 0U;
 }
 
+/* Один вызов потребляет один байт. false означает отсутствие готового кадра:
+ * это нормальный результат и для частичного сообщения, и для отброшенного.
+ * Значение out пригодно для чтения только при возврате true. */
 bool pcan_parser_push(pcan_parser_t *p, uint8_t byte, pcan_frame_t *out)
 {
     switch (p->state) {
@@ -98,6 +112,8 @@ bool pcan_parser_push(pcan_parser_t *p, uint8_t byte, pcan_frame_t *out)
             p->stats.crc_errors++;
             return false;
         }
+        /* Публикуем поля только после CRC: повреждённый пакет не должен
+         * оставлять у потребителя частично обновлённый результат. */
         out->seq = p->body[1];
         out->flags = p->body[2];
         out->id = ((uint32_t)p->body[3])
@@ -133,6 +149,8 @@ size_t pcan_parser_feed(pcan_parser_t *p, const uint8_t *data, size_t len,
         if (pcan_parser_push(p, data[i], &frame)) {
             count++;
             if (cb != NULL) {
+                /* frame находится на стеке: обработчик должен скопировать
+                 * данные, если они потребуются после завершения callback. */
                 cb(&frame, user);
             }
         }

c/set-protocol/src/pcan_gas.c

@@ -1,3 +1,9 @@
+/*
+ * Общее адресное пространство ProtoCAN, разбитое на регионы с обработчиками чтения и записи.
+ * Поиск региона и проверка доступа предшествуют обращению к приложению; номер регистра не
+ * является адресом памяти процессора.
+ */
+
 #include "pcan_gas.h"
 #include "pcan_id.h"
 

c/set-protocol/src/pcan_id.c

@@ -1,3 +1,8 @@
+/*
+ * Явная упаковка полей в 29-битный идентификатор ProtoCAN и их извлечение. Маски и сдвиги
+ * задают переносимый wire-формат без зависимости от расположения битовых полей компилятора.
+ */
+
 #include "pcan_id.h"
 
 uint32_t pcan_id_pack(const pcan_id_t *id)

c/set-protocol/src/pcan_link.c

@@ -1,3 +1,9 @@
+/*
+ * Канал ProtoCAN поверх произвольного потока байтов. Контекст хранит parser и параметры
+ * отправки; физический ввод-вывод подключается обратными вызовами, а готовые CAN-кадры
+ * передаются обработчику приложения.
+ */
+
 #include "pcan_link.h"
 
 bool pcan_link_init(pcan_link_t *link, const pcan_io_t *io,

c/set-protocol/src/pcan_modbus_server.c

@@ -1,3 +1,9 @@
+/*
+ * Доступ к окнам Modbus-регистров через один classic CAN-кадр ProtoCAN. Сервер сопоставляет
+ * команду с банком и диапазоном регистров; чтение и запись значений выполняет предоставленный
+ * приложением интерфейс.
+ */
+
 #include "pcan_modbus_server.h"
 
 #include <stddef.h>

c/set-protocol/src/pcan_ring.c

@@ -1,5 +1,13 @@
+/*
+ * Кольцевая очередь байтов для одного производителя и одного потребителя. Размер хранилища
+ * должен быть степенью двойки; одна позиция резервируется для различения пустого и полного
+ * состояния.
+ */
+
 #include "pcan_ring.h"
 
+/* storage живёт не меньше контекста очереди. Степень двойки позволяет
+ * заменять остаток от деления маской size - 1 во всех операциях. */
 bool pcan_ring_init(pcan_ring_t *rb, uint8_t *storage, uint16_t size)
 {
     if ((rb == NULL) || (storage == NULL) || (size < 2U) ||
@@ -19,6 +27,8 @@ uint16_t pcan_ring_count(const pcan_ring_t *rb)
     return (uint16_t)((rb->head - rb->tail) & (uint16_t)(rb->size - 1U));
 }
 
+/* head == tail обозначает пустую очередь, поэтому одна ячейка всегда
+ * остаётся незанятой: полезная вместимость равна size - 1. */
 uint16_t pcan_ring_free(const pcan_ring_t *rb)
 {
     return (uint16_t)(rb->size - 1U - pcan_ring_count(rb));
@@ -31,6 +41,8 @@ bool pcan_ring_put(pcan_ring_t *rb, uint8_t byte)
         rb->dropped++;
         return false;
     }
+    /* Сначала данные, затем публикация индекса: потребитель не должен
+     * увидеть новую позицию до того, как байт записан в хранилище. */
     rb->buf[rb->head] = byte;
     PCAN_BARRIER();
     rb->head = next;
@@ -48,6 +60,8 @@ bool pcan_ring_get(pcan_ring_t *rb, uint8_t *byte)
     return true;
 }
 
+/* Блок добавляется целиком либо отклоняется целиком. Это сохраняет
+ * границы отправляемого кадра при недостатке свободного места. */
 bool pcan_ring_write(pcan_ring_t *rb, const uint8_t *data, uint16_t len)
 {
     if (pcan_ring_free(rb) < len) {
@@ -68,6 +82,8 @@ bool pcan_ring_write(pcan_ring_t *rb, const uint8_t *data, uint16_t len)
     return true;
 }
 
+/* Возвращает непрерывный участок до конца массива, а не обязательно всё
+ * содержимое кольца. После обработки вызывающий сдвигает tail через consume. */
 uint16_t pcan_ring_linear(const pcan_ring_t *rb, const uint8_t **ptr)
 {
     uint16_t head = rb->head;
@@ -82,6 +98,8 @@ uint16_t pcan_ring_linear(const pcan_ring_t *rb, const uint8_t **ptr)
                          : (uint16_t)(rb->size - tail);
 }
 
+/* Предусловие: len не превышает число доступных байтов. Проверка здесь
+ * не выполняется; обычно передают размер реально обработанного участка. */
 void pcan_ring_consume(pcan_ring_t *rb, uint16_t len)
 {
     rb->tail = (uint16_t)((rb->tail + len) & (uint16_t)(rb->size - 1U));

c/set-protocol/src/periph28335.c

@@ -1,3 +1,9 @@
+/*
+ * Протокол периферийного контроллера ПМ35/TMS320F28335: регистры, команды и разбор ответов.
+ * Этот профиль имеет собственную адресацию и не должен подменяться протоколом основного
+ * TMS320F2812.
+ */
+
 #include "periph28335.h"
 
 #include <string.h>

c/set-protocol/src/set_boot.c

@@ -1,3 +1,9 @@
+/*
+ * Транспортно-независимый односекционный обновитель прошивки. Признак валидности снимается до
+ * стирания, а commit вызывается после проверки записанного образа чтением; порядок операций
+ * нужен для восстановления после прерывания питания.
+ */
+
 #include "set_boot.h"
 #include <string.h>
 
@@ -28,6 +34,8 @@ static uint16_t command(setp_boot *b, uint16_t type, const uint8_t *p, uint16_t
         if(begin.base_address!=b->base || begin.image_size<8 ||
            begin.image_size>b->capacity || begin.block_size>256)
             return SETP_STATUS_INVALID_ARGUMENT;
+        /* Сначала делаем старый образ невалидным, затем стираем. FAILED
+         * остаётся безопасным состоянием при отказе любого callback. */
         b->status.state=SETP_FW_FAILED;
         if(!b->ops.invalidate(b->user) || !b->ops.erase(b->user,begin.image_size))
             return SETP_STATUS_INTERNAL;
@@ -38,6 +46,8 @@ static uint16_t command(setp_boot *b, uint16_t type, const uint8_t *p, uint16_t
         if(b->status.state!=SETP_FW_RECEIVING) return SETP_STATUS_WRONG_STATE;
         if(!setp_fw_data_decode(p,n,&data)) return SETP_STATUS_CRC;
         if(data.flags || data.data_length>b->block_size) return SETP_STATUS_INVALID_ARGUMENT;
+        /* Здесь нет произвольной записи и повторной записи блока:
+         * принимается только следующий подтверждённый диапазон образа. */
         if(data.offset!=b->status.next_offset) return SETP_STATUS_SEQUENCE;
         if(data.data_length>b->status.image_size-b->status.next_offset)
             return SETP_STATUS_NO_SPACE;
@@ -52,6 +62,8 @@ static uint16_t command(setp_boot *b, uint16_t type, const uint8_t *p, uint16_t
         if(end.image_size!=b->status.image_size || end.image_crc32!=b->crc ||
            b->status.next_offset!=b->status.image_size) return SETP_STATUS_SEQUENCE;
         b->status.state=SETP_FW_FAILED;
+        /* Проверяется содержимое Flash, а не только принятые по линии байты.
+         * Только после этого commit разрешает считать образ запускаемым. */
         if(!b->ops.verify(b->user,end.image_size,b->crc)) return SETP_STATUS_VERIFY_FAILED;
         if(!b->ops.commit(b->user,end.image_size,b->crc)) return SETP_STATUS_INTERNAL;
         b->status.state=SETP_FW_READY; return SETP_STATUS_OK;
@@ -71,6 +83,7 @@ static uint16_t command(setp_boot *b, uint16_t type, const uint8_t *p, uint16_t
 uint16_t setp_boot_command(setp_boot *b, uint16_t type, const uint8_t *p, uint16_t n)
 {
     uint16_t result=command(b,type,p,n);
+    /* Опрос состояния не стирает причину предыдущей ошибки операции. */
     if(type!=SETP_MSG_FW_STATUS) b->status.last_error=result;
     return result;
 }

c/set-protocol/src/set_can.c

@@ -1,3 +1,9 @@
+/*
+ * Сегментация SET v2 и интерпретация CAN-данных зависят от выбранного слоя. Адрес и номер
+ * сегмента должны проверяться до объединения данных; classic CAN-пакет ограничен восемью
+ * байтами.
+ */
+
 #include "set_can.h"
 
 #include <string.h>

c/set-protocol/src/set_crc.c

@@ -1,3 +1,9 @@
+/*
+ * Общие контрольные суммы исторических протоколов SET. Алгоритмы с разными полиномами,
+ * начальными значениями и отражением битов не взаимозаменяемы, даже если возвращают одинаковый
+ * по ширине целый тип.
+ */
+
 #include "set_crc.h"
 
 uint16_t set_crc16_modbus(const uint8_t *data, size_t size)

c/set-protocol/src/set_emu_igbt.c

@@ -1,3 +1,9 @@
+/*
+ * Модель каналов IGBT для стенда: входные состояния, задержки и сформированные выходы. Логика
+ * времени отделена от аппаратного порта; модель предназначена для воспроизводимого обмена с
+ * эмулятором.
+ */
+
 #include "set_emu_igbt.h"
 #include <string.h>
 static void output(set_igbt_emu *s)

c/set-protocol/src/set_emu_server.c

@@ -1,3 +1,9 @@
+/*
+ * Эталонная композиция сервисов эмулятора: УМП, TMS, IGBT и генератор сигналов. Общая карта
+ * регистров маршрутизирует обращения; другой продукт может составить собственную карту через
+ * set_regmap.
+ */
+
 #include "set_emu_server.h"
 #include "set_crc.h"
 #include <string.h>

c/set-protocol/src/set_emu_tms.c

@@ -1,3 +1,9 @@
+/*
+ * Модель ответов TMS для эмулятора контроллера. Синтетические аналоговые и дискретные значения
+ * упаковываются в ожидаемый формат терминала, чтобы проверять клиент без подключения рабочего
+ * контроллера.
+ */
+
 #include "set_emu_tms.h"
 #include "set_crc.h"
 #include <string.h>

c/set-protocol/src/set_emu_ump.c

@@ -1,3 +1,9 @@
+/*
+ * Синтетические сигналы УМП и регистратор эмулятора. Хранилище предоставляет вызывающий код;
+ * обновление модели и выдача записей разделены, чтобы клиент мог получать воспроизводимые
+ * снимки.
+ */
+
 /* UMP synthetic signals and recorder. Storage belongs to the caller. */
 #include "set_emu_ump.h"
 #include <string.h>

c/set-protocol/src/set_firmware.c

@@ -1,3 +1,9 @@
+/*
+ * Кодирование метаданных и сообщений обновления SETProtocol v2. Размер образа, совместимость и
+ * параметры начала передачи передаются явно; сериализация команды сама по себе не выполняет
+ * запись Flash.
+ */
+
 #include "set_firmware.h"
 
 #include <string.h>

c/set-protocol/src/set_plot.c

@@ -1,3 +1,9 @@
+/*
+ * Математика взаимодействия с графиком: области просмотра, масштабирование, перемещение и
+ * координатные преобразования. Расчёты общие для JNI и ctypes; цвета, события GUI и рисование
+ * остаются в приложении.
+ */
+
 #include "set_plot.h"
 #include <math.h>
 

c/set-protocol/src/set_protocol.c

@@ -1,3 +1,9 @@
+/*
+ * Основной бинарный формат SETProtocol v2: поля кадра, контрольная сумма и потоковый parser.
+ * Числа сериализуются явно, поэтому выравнивание C-структур не влияет на байты линии;
+ * транспорт передаёт готовые массивы.
+ */
+
 #include "set_protocol.h"
 
 #include <string.h>

c/set-protocol/src/set_regmap.c

@@ -1,3 +1,9 @@
+/*
+ * Транспортно-независимая карта 16-битных регистров с отдельными регионами и обработчиками.
+ * Проверка диапазонов и прав доступа выполняется до вызова сервиса; относительное смещение
+ * региона отличается от общего адреса.
+ */
+
 #include "set_regmap.h"
 #include "set_crc.h"
 #include <string.h>

c/set-protocol/src/set_signal.c

@@ -1,3 +1,9 @@
+/*
+ * Восстановление сигнала по точкам и подготовка кодов 12-битного ЦАП. Совпадающие времена
+ * усредняются, экстраполяция не выполняется; для циклического периода конечная точка
+ * обрабатывается отдельно. Напряжения вне диапазона отклоняются, а не обрезаются.
+ */
+
 #include "set_signal.h"
 #include <math.h>
 #include <stdlib.h>

c/set-protocol/src/set_spectrum.c

@@ -1,3 +1,9 @@
+/*
+ * Общий расчёт FFT: оценка частоты дискретизации по времени, ресемплинг, фильтр, окно и
+ * спектр. Выход — односторонняя пиковая амплитуда; DC и частота Найквиста не удваиваются.
+ * Временные метки задаются в секундах.
+ */
+
 #include "set_spectrum.h"
 #include <math.h>
 #include <stdlib.h>

c/set-protocol/src/set_telemetry.c

@@ -1,3 +1,9 @@
+/*
+ * Сообщения подписки и телеметрии SETProtocol v2. Период, идентификатор подписки и перечень
+ * адресов сериализуются отдельно от значений; получатель должен связывать поток с
+ * соответствующей подпиской.
+ */
+
 #include "set_telemetry.h"
 
 #include <string.h>

c/set-protocol/src/set_trends.c

@@ -1,3 +1,9 @@
+/*
+ * Общий разбор числовых источников трендов, включая GAS и raw CAN. Знаковость слова, смещение
+ * и коэффициент преобразования относятся к описанию сигнала; визуальная история графика
+ * хранится на стороне клиента.
+ */
+
 #include "set_trends.h"
 #include "pcan_id.h"
 

c/set-protocol/src/set_wavegen.c

@@ -1,3 +1,9 @@
+/*
+ * Транзакционная загрузка таблицы и циклическое воспроизведение через ЦАП. Блоки принимаются
+ * до commit, а запуск использует согласованную таблицу; порт stop должен остановить DMA до
+ * возврата и освободить использование массива.
+ */
+
 #include "set_wavegen.h"
 #include "set_crc.h"
 #include <string.h>

c/set-protocol/src/tms2812.c

@@ -1,3 +1,9 @@
+/*
+ * Исторический протокол основного контроллера ПМ67/TMS320F2812. Формирование команд и проверка
+ * ответов находятся в общем ядре; адреса памяти C28x считаются словами, тогда как длины
+ * передачи могут задаваться байтами.
+ */
+
 #include "tms2812.h"
 
 #include <stdint.h>

c/set-protocol/src/ump_protocol.c

@@ -1,3 +1,8 @@
+/*
+ * Регистровый протокол УМП для UART/CAN с общей проверкой функций и диапазонов. Октеты
+ * извлекаются явно, чтобы формат оставался одинаковым на восьмибитных и C28x-платформах.
+ */
+
 #include "../include/ump_protocol.h"
 static uint16_t get16(const ump_octet *p)
 { return (uint16_t)(((p[0]&255U)<<8)|(p[1]&255U)); }