diff --git a/c/can-sensor/CMakeLists.txt b/c/can-sensor/CMakeLists.txt index 9171761..31787e6 100644 --- a/c/can-sensor/CMakeLists.txt +++ b/c/can-sensor/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки can_sensor. Состав исходников и публичные include-пути задают подключение +# к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их +# следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(can_sensor C) diff --git a/c/can-sensor/can_sensor.c b/c/can-sensor/can_sensor.c index 681b811..0181881 100644 --- a/c/can-sensor/can_sensor.c +++ b/c/can-sensor/can_sensor.c @@ -1,3 +1,9 @@ +/* + * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует + * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через + * интерфейс библиотеки. + */ + /** * @file can_sensor.c * @brief Однокадровый транспорт SETCAN SETTINGS для локаций DS18B20. diff --git a/c/can-sensor/can_sensor.h b/c/can-sensor/can_sensor.h index 06f4f46..6d9b583 100644 --- a/c/can-sensor/can_sensor.h +++ b/c/can-sensor/can_sensor.h @@ -1,3 +1,9 @@ +/* + * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует + * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через + * интерфейс библиотеки. + */ + /** * @file can_sensor.h * @brief Портируемый транспорт SETTINGS для привязки DS18B20 к локации. diff --git a/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c b/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c index 936d94f..8a813ba 100644 --- a/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c +++ b/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c @@ -1,3 +1,9 @@ +/* + * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и + * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация + * интерфейса can_sensor. + */ + /** * @file can_sensor_stm32f1.c * @brief Опросный порт can-sensor на bxCAN STM32F1 без STM32 HAL. diff --git a/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h b/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h index a0a7f81..3cbf11c 100644 --- a/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h +++ b/c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h @@ -1,3 +1,9 @@ +/* + * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и + * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация + * интерфейса can_sensor. + */ + /** * @file can_sensor_stm32f1.h * @brief Опросный порт can-sensor на bxCAN микроконтроллеров STM32F1. diff --git a/c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h b/c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h index a427612..73d218c 100644 --- a/c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h +++ b/c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация can-sensor для порта stm32f1. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + /** * @file can_sensor_stm32f1_config.f103.template.h * @brief Шаблон выводов CAN1 для STM32F103 без ремапа. diff --git a/c/can-sensor/tests/test_can_sensor.c b/c/can-sensor/tests/test_can_sensor.c index 5d0a010..0c887ba 100644 --- a/c/can-sensor/tests/test_can_sensor.c +++ b/c/can-sensor/tests/test_can_sensor.c @@ -1,3 +1,9 @@ +/* + * Проверки can_sensor: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "can_sensor.h" #include diff --git a/c/candle/CMakeLists.txt b/c/candle/CMakeLists.txt index e856010..1b11f4a 100644 --- a/c/candle/CMakeLists.txt +++ b/c/candle/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки candle. Состав исходников и публичные include-пути задают подключение к +# проекту потребителя. Платформенные зависимости и условия сборки задаются здесь, а не в +# прикладных исходниках. + cmake_minimum_required(VERSION 3.15) project(candle C) if(NOT WIN32) diff --git a/c/candle/candle.c b/c/candle/candle.c index 5437d97..afba292 100644 --- a/c/candle/candle.c +++ b/c/candle/candle.c @@ -19,6 +19,12 @@ */ +/* + * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств, + * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует + * прикладные регистры SETProtocol. + */ + #include "candle.h" #include diff --git a/c/candle/candle.def b/c/candle/candle.def index 02d71f9..e4321b6 100644 --- a/c/candle/candle.def +++ b/c/candle/candle.def @@ -1,3 +1,7 @@ +; Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств, +; открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует +; прикладные регистры SETProtocol. + EXPORTS candle_list_scan candle_list_free diff --git a/c/candle/candle.h b/c/candle/candle.h index 4db70c4..9f063d4 100644 --- a/c/candle/candle.h +++ b/c/candle/candle.h @@ -20,6 +20,12 @@ */ +/* + * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств, + * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует + * прикладные регистры SETProtocol. + */ + #pragma once #include #include diff --git a/c/candle/candle_ctrl_req.c b/c/candle/candle_ctrl_req.c index 8f3a8d2..1bbfe41 100644 --- a/c/candle/candle_ctrl_req.c +++ b/c/candle/candle_ctrl_req.c @@ -19,6 +19,11 @@ */ +/* + * Управляющие USB-запросы адаптера candleLight: конфигурация, временные параметры CAN и режим + * канала. Эти транзакции идут через control endpoint и отличаются от потока CAN-кадров. + */ + #include "candle_ctrl_req.h" #include "ch_9.h" diff --git a/c/candle/candle_ctrl_req.h b/c/candle/candle_ctrl_req.h index b3208c6..2ba23d6 100644 --- a/c/candle/candle_ctrl_req.h +++ b/c/candle/candle_ctrl_req.h @@ -20,6 +20,11 @@ */ +/* + * Управляющие USB-запросы адаптера candleLight: конфигурация, временные параметры CAN и режим + * канала. Эти транзакции идут через control endpoint и отличаются от потока CAN-кадров. + */ + #pragma once #include "candle_defs.h" diff --git a/c/candle/candle_defs.h b/c/candle/candle_defs.h index 2ba93d5..a0b12f9 100644 --- a/c/candle/candle_defs.h +++ b/c/candle/candle_defs.h @@ -20,6 +20,12 @@ */ +/* + * Двоичные структуры и константы gs_usb, общие для драйвера и USB-адаптера. Размеры полей и + * упаковка определяют совместимость с прошивкой: менять их как обычные внутренние структуры + * нельзя. + */ + #pragma once #include diff --git a/c/candle/ch_9.h b/c/candle/ch_9.h index ba1994b..a71b7e6 100644 --- a/c/candle/ch_9.h +++ b/c/candle/ch_9.h @@ -19,6 +19,11 @@ */ +/* + * Типы стандартных USB-дескрипторов и запросов из главы 9 спецификации USB. Драйвер использует + * их для описания устройства и конечных точек; это транспортные определения, а не формат CAN. + */ + #pragma once #define USB_DIR_OUT 0 /* to device */ diff --git a/c/ds18b20-ds2480/CMakeLists.txt b/c/ds18b20-ds2480/CMakeLists.txt index 1f24308..0d46056 100644 --- a/c/ds18b20-ds2480/CMakeLists.txt +++ b/c/ds18b20-ds2480/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки ds18b20_ds2480. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(ds18b20_ds2480 C) add_library(ds18b20_ds2480 STATIC ds2480.c ds18b20_ds2480.c) diff --git a/c/ds18b20-ds2480/ds18b20_ds2480.c b/c/ds18b20-ds2480/ds18b20_ds2480.c index b1c46a4..5cc3f3e 100644 --- a/c/ds18b20-ds2480/ds18b20_ds2480.c +++ b/c/ds18b20-ds2480/ds18b20_ds2480.c @@ -1,3 +1,9 @@ +/* + * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и + * scratchpad. Транспортный статус следует проверять до использования результата; сырая + * температура сохраняет знаковое представление датчика. + */ + #include "ds18b20_ds2480.h" #include diff --git a/c/ds18b20-ds2480/ds18b20_ds2480.h b/c/ds18b20-ds2480/ds18b20_ds2480.h index fc20cc9..12ec242 100644 --- a/c/ds18b20-ds2480/ds18b20_ds2480.h +++ b/c/ds18b20-ds2480/ds18b20_ds2480.h @@ -1,3 +1,9 @@ +/* + * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и + * scratchpad. Транспортный статус следует проверять до использования результата; сырая + * температура сохраняет знаковое представление датчика. + */ + #ifndef DS18B20_DS2480_H #define DS18B20_DS2480_H #include "ds2480.h" diff --git a/c/ds18b20-ds2480/ds2480.c b/c/ds18b20-ds2480/ds2480.c index 8d1a878..22e087e 100644 --- a/c/ds18b20-ds2480/ds2480.c +++ b/c/ds18b20-ds2480/ds2480.c @@ -1,3 +1,9 @@ +/* + * UART-мост DS2480B для операций 1-Wire: сброс, обмен битами и байтами, поиск устройств и + * управление питанием. После ошибки связи состояние готовности сбрасывается, чтобы следующий + * обмен не продолжался в неизвестном режиме моста. + */ + #include "ds2480.h" static ds2480_status fault(ds2480 *bus, ds2480_status status) diff --git a/c/ds18b20-ds2480/ds2480.h b/c/ds18b20-ds2480/ds2480.h index e4c2e97..f19385d 100644 --- a/c/ds18b20-ds2480/ds2480.h +++ b/c/ds18b20-ds2480/ds2480.h @@ -1,3 +1,9 @@ +/* + * UART-мост DS2480B для операций 1-Wire: сброс, обмен битами и байтами, поиск устройств и + * управление питанием. После ошибки связи состояние готовности сбрасывается, чтобы следующий + * обмен не продолжался в неизвестном режиме моста. + */ + #ifndef DS2480_H #define DS2480_H diff --git a/c/ds18b20-ds2480/examples/read_first.c b/c/ds18b20-ds2480/examples/read_first.c index 032174a..642fb91 100644 --- a/c/ds18b20-ds2480/examples/read_first.c +++ b/c/ds18b20-ds2480/examples/read_first.c @@ -1,3 +1,9 @@ +/* + * Минимальный блокирующий пример: подготовить мост DS2480B, найти первый датчик, запустить + * преобразование и прочитать температуру. Обратные вызовы UART и задержек предоставляет плата; + * ожидание преобразования входит во время вызова. + */ + #include "ds18b20_ds2480.h" /* board_port supplies the four callbacks documented in ds2480.h. diff --git a/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.c b/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.c index 70019be..48b48db 100644 --- a/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.c +++ b/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.c @@ -1,3 +1,9 @@ +/* + * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд + * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения + * работы с 1-Wire. + */ + #include "ds2480_stm32f4_hal.h" #define RX_ERRORS (USART_SR_ORE | USART_SR_NE | USART_SR_FE | USART_SR_PE) diff --git a/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.h b/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.h index 0830cc6..efede9b 100644 --- a/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.h +++ b/c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.h @@ -1,3 +1,9 @@ +/* + * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд + * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения + * работы с 1-Wire. + */ + #ifndef DS2480_STM32F4_HAL_H #define DS2480_STM32F4_HAL_H diff --git a/c/ds18b20-ds2480/ports/stm32f4/tests/stm32f4xx_hal.h b/c/ds18b20-ds2480/ports/stm32f4/tests/stm32f4xx_hal.h index fa40fc6..859e6ef 100644 --- a/c/ds18b20-ds2480/ports/stm32f4/tests/stm32f4xx_hal.h +++ b/c/ds18b20-ds2480/ports/stm32f4/tests/stm32f4xx_hal.h @@ -1,3 +1,11 @@ +/* + * Проверки stm32f4xx_hal: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_clear + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /* Host-only HAL model, never add this directory to a firmware include path. */ #ifndef TEST_STM32F4_HAL_H #define TEST_STM32F4_HAL_H diff --git a/c/ds18b20-ds2480/ports/stm32f4/tests/test_port.c b/c/ds18b20-ds2480/ports/stm32f4/tests/test_port.c index b6562b0..4ebedea 100644 --- a/c/ds18b20-ds2480/ports/stm32f4/tests/test_port.c +++ b/c/ds18b20-ds2480/ports/stm32f4/tests/test_port.c @@ -1,3 +1,11 @@ +/* + * Проверки port: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_clear + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "ds2480_stm32f4_hal.h" #include #include diff --git a/c/ds18b20-ds2480/tests/test_ds18b20_ds2480.c b/c/ds18b20-ds2480/tests/test_ds18b20_ds2480.c index efc5eec..494ab50 100644 --- a/c/ds18b20-ds2480/tests/test_ds18b20_ds2480.c +++ b/c/ds18b20-ds2480/tests/test_ds18b20_ds2480.c @@ -1,3 +1,9 @@ +/* + * Проверки ds18b20_ds2480: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "ds18b20_ds2480.h" #include #include diff --git a/c/ds18b20/CMakeLists.txt b/c/ds18b20/CMakeLists.txt index 59f0d60..c3c615e 100644 --- a/c/ds18b20/CMakeLists.txt +++ b/c/ds18b20/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки ds18b20. Состав исходников и публичные include-пути задают подключение к +# проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их +# следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(ds18b20 C) diff --git a/c/ds18b20/include/ds18b20.h b/c/ds18b20/include/ds18b20.h index 3f59403..e1127c6 100644 --- a/c/ds18b20/include/ds18b20.h +++ b/c/ds18b20/include/ds18b20.h @@ -1,3 +1,9 @@ +/* + * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и + * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя + * считать действительным до проверки статуса обмена и CRC. + */ + /** * @file ds18b20.h * @brief Драйвер термометров DS18B20 поверх шины 1-Wire. diff --git a/c/ds18b20/include/onewire.h b/c/ds18b20/include/onewire.h index fc71808..3ee2cf7 100644 --- a/c/ds18b20/include/onewire.h +++ b/c/ds18b20/include/onewire.h @@ -1,3 +1,9 @@ +/* + * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно, + * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические + * уровни и длительности импульсов задаёт порт. + */ + /** * @file onewire.h * @brief Программная шина 1-Wire на выводе с открытым стоком. diff --git a/c/ds18b20/instance/CMakeLists.txt b/c/ds18b20/instance/CMakeLists.txt index eb3fa80..fe68060 100644 --- a/c/ds18b20/instance/CMakeLists.txt +++ b/c/ds18b20/instance/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки ds18b20_instance. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(ds18b20_instance C) add_library(ds18b20_instance STATIC Src/ds18b20.c) diff --git a/c/ds18b20/instance/Inc/ds18b20.h b/c/ds18b20/instance/Inc/ds18b20.h index 138b6a2..29cad4c 100644 --- a/c/ds18b20/instance/Inc/ds18b20.h +++ b/c/ds18b20/instance/Inc/ds18b20.h @@ -1,3 +1,9 @@ +/* + * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и + * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя + * считать действительным до проверки статуса обмена и CRC. + */ + #ifndef PORTABLE_DS18B20_H #define PORTABLE_DS18B20_H diff --git a/c/ds18b20/instance/Inc/ds18b20_config.h b/c/ds18b20/instance/Inc/ds18b20_config.h index a2a8305..b76cb97 100644 --- a/c/ds18b20/instance/Inc/ds18b20_config.h +++ b/c/ds18b20/instance/Inc/ds18b20_config.h @@ -1,3 +1,9 @@ +/* + * Конфигурация ds18b20. Макросы задают параметры сборки и ограничения, используемые + * исходниками этого модуля. Смысл и единицы каждого параметра определяются местом его + * использования; размеры буферов должны быть согласованы у всех потребителей заголовка. + */ + #ifndef PORTABLE_DS18B20_CONFIG_H #define PORTABLE_DS18B20_CONFIG_H #define DS18B20_DEFAULT_TIMEOUT_MS 750U diff --git a/c/ds18b20/instance/Src/ds18b20.c b/c/ds18b20/instance/Src/ds18b20.c index 41e38e2..49f017b 100644 --- a/c/ds18b20/instance/Src/ds18b20.c +++ b/c/ds18b20/instance/Src/ds18b20.c @@ -1,3 +1,9 @@ +/* + * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и + * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя + * считать действительным до проверки статуса обмена и CRC. + */ + #include "ds18b20.h" #include "ds18b20_config.h" #include diff --git a/c/ds18b20/instance/Tests/run_host_tests.ps1 b/c/ds18b20/instance/Tests/run_host_tests.ps1 index b223b67..8a87dac 100644 --- a/c/ds18b20/instance/Tests/run_host_tests.ps1 +++ b/c/ds18b20/instance/Tests/run_host_tests.ps1 @@ -1,3 +1,7 @@ +# Сборка и запуск хостовых проверок экземплярного DS18B20. Скрипт готовит исполняемые тесты +# для проверки поиска ROM и задержек EEPROM без платы; ошибка компиляции или проверки должна +# завершить прогон неуспешно. + $ErrorActionPreference = "Stop" $out = Join-Path $env:TEMP "test_ds18b20_copy_delay.exe" $test = Join-Path $PSScriptRoot "test_ds18b20_copy_delay.c" diff --git a/c/ds18b20/instance/Tests/test_ds18b20_copy_delay.c b/c/ds18b20/instance/Tests/test_ds18b20_copy_delay.c index 13529f4..531c0ff 100644 --- a/c/ds18b20/instance/Tests/test_ds18b20_copy_delay.c +++ b/c/ds18b20/instance/Tests/test_ds18b20_copy_delay.c @@ -1,3 +1,10 @@ +/* + * Проверки ds18b20_copy_delay: фиксируют ожидаемое поведение на воспроизводимых входных + * данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "ds18b20.h" #include diff --git a/c/ds18b20/instance/Tests/test_ds18b20_incremental_search.c b/c/ds18b20/instance/Tests/test_ds18b20_incremental_search.c index 073ff62..d616c2c 100644 --- a/c/ds18b20/instance/Tests/test_ds18b20_incremental_search.c +++ b/c/ds18b20/instance/Tests/test_ds18b20_incremental_search.c @@ -1,3 +1,10 @@ +/* + * Проверки ds18b20_incremental_search: фиксируют ожидаемое поведение на воспроизводимых + * входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /* Model real SEARCH ROM participation: each branch filters the active slaves. * Fault injection tests transport recovery, not analog cable characteristics. */ #include "ds18b20.h" diff --git a/c/ds18b20/ports/stm32f1/onewire_config.f103.template.h b/c/ds18b20/ports/stm32f1/onewire_config.f103.template.h index 4cabc38..c538e8d 100644 --- a/c/ds18b20/ports/stm32f1/onewire_config.f103.template.h +++ b/c/ds18b20/ports/stm32f1/onewire_config.f103.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация ds18b20 для порта stm32f1. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + /** * @file onewire_config.f103.template.h * @brief Шаблон привязки шины 1-Wire для STM32F103 (порт stm32f1). diff --git a/c/ds18b20/ports/stm32f1/onewire_stm32f1.c b/c/ds18b20/ports/stm32f1/onewire_stm32f1.c index b95929f..77231a1 100644 --- a/c/ds18b20/ports/stm32f1/onewire_stm32f1.c +++ b/c/ds18b20/ports/stm32f1/onewire_stm32f1.c @@ -1,3 +1,9 @@ +/* + * Аппаратные временные слоты 1-Wire на STM32F1: управление линией, чтение уровня и + * микросекундные задержки. Конфигурация выбирает GPIO и таймер; общий алгоритм поиска ROM + * остаётся в onewire.c. + */ + /** * @file onewire_stm32f1.c * @brief Порт шины 1-Wire на STM32F1: тайминги, вывод и задержки. diff --git a/c/ds18b20/ports/stm32f4/onewire_config.f407.template.h b/c/ds18b20/ports/stm32f4/onewire_config.f407.template.h index dadfe17..3972fa3 100644 --- a/c/ds18b20/ports/stm32f4/onewire_config.f407.template.h +++ b/c/ds18b20/ports/stm32f4/onewire_config.f407.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация ds18b20 для порта stm32f4. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + /** * @file onewire_config.f407.template.h * @brief Шаблон привязки шины 1-Wire для STM32F407VET6 (порт stm32f4). diff --git a/c/ds18b20/ports/stm32f4/onewire_stm32f4.c b/c/ds18b20/ports/stm32f4/onewire_stm32f4.c index 42203fb..e750234 100644 --- a/c/ds18b20/ports/stm32f4/onewire_stm32f4.c +++ b/c/ds18b20/ports/stm32f4/onewire_stm32f4.c @@ -1,3 +1,9 @@ +/* + * Аппаратные временные слоты 1-Wire на STM32F4 с открытым стоком. Порт использует + * CMSIS-регистры и параметры onewire_config.h; частота таймера должна соответствовать расчёту + * задержек при обмене с датчиками. + */ + /** * @file onewire_stm32f4.c * @brief Порт шины 1-Wire на STM32F4: тайминги, вывод и задержки. diff --git a/c/ds18b20/ports/stm32g4/onewire_config.g431.template.h b/c/ds18b20/ports/stm32g4/onewire_config.g431.template.h index 4b02b91..c8d1e52 100644 --- a/c/ds18b20/ports/stm32g4/onewire_config.g431.template.h +++ b/c/ds18b20/ports/stm32g4/onewire_config.g431.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация ds18b20 для порта stm32g4. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + /** * @file onewire_config.g431.template.h * @brief Шаблон привязки шины 1-Wire для STM32G431 (порт stm32g4). diff --git a/c/ds18b20/ports/stm32g4/onewire_config.g474.template.h b/c/ds18b20/ports/stm32g4/onewire_config.g474.template.h index c659d60..e31c38f 100644 --- a/c/ds18b20/ports/stm32g4/onewire_config.g474.template.h +++ b/c/ds18b20/ports/stm32g4/onewire_config.g474.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация ds18b20 для порта stm32g4. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + /** * @file onewire_config.g474.template.h * @brief Шаблон привязки шины 1-Wire для STM32G474 (порт stm32g4). diff --git a/c/ds18b20/ports/stm32g4/onewire_stm32g4.c b/c/ds18b20/ports/stm32g4/onewire_stm32g4.c index 9506376..75fdfef 100644 --- a/c/ds18b20/ports/stm32g4/onewire_stm32g4.c +++ b/c/ds18b20/ports/stm32g4/onewire_stm32g4.c @@ -1,3 +1,9 @@ +/* + * Аппаратные временные слоты 1-Wire для STM32G431/G474. GPIO и таймер задаются конфигурацией + * проекта; чтение уровня выполняется с линии, поэтому паразитное питание и подтяжка относятся + * к схеме платы. + */ + /** * @file onewire_stm32g4.c * @brief Порт шины 1-Wire на STM32G4: тайминги, вывод и задержки. diff --git a/c/ds18b20/src/ds18b20.c b/c/ds18b20/src/ds18b20.c index cf0a07e..b035861 100644 --- a/c/ds18b20/src/ds18b20.c +++ b/c/ds18b20/src/ds18b20.c @@ -1,3 +1,9 @@ +/* + * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и + * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя + * считать действительным до проверки статуса обмена и CRC. + */ + /** test * @file ds18b20.c * @brief Реализация драйвера DS18B20: поиск, чтение и запись scratchpad. diff --git a/c/ds18b20/src/onewire.c b/c/ds18b20/src/onewire.c index f65b2c2..a842511 100644 --- a/c/ds18b20/src/onewire.c +++ b/c/ds18b20/src/onewire.c @@ -1,3 +1,9 @@ +/* + * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно, + * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические + * уровни и длительности импульсов задаёт порт. + */ + /** * @file onewire.c * @brief Переносимая часть шины 1-Wire: побайтовый обмен, CRC8 и поиск ROM. diff --git a/c/ds18b20/tests/fake_onewire.c b/c/ds18b20/tests/fake_onewire.c index eab668e..0a6db0b 100644 --- a/c/ds18b20/tests/fake_onewire.c +++ b/c/ds18b20/tests/fake_onewire.c @@ -1,3 +1,9 @@ +/* + * Проверки fake_onewire: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /** * @file fake_onewire.c * @brief Симулятор шины 1-Wire с виртуальными датчиками DS18B20. diff --git a/c/ds18b20/tests/fake_onewire.h b/c/ds18b20/tests/fake_onewire.h index 095bb72..09367fb 100644 --- a/c/ds18b20/tests/fake_onewire.h +++ b/c/ds18b20/tests/fake_onewire.h @@ -1,3 +1,9 @@ +/* + * Проверки fake_onewire: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /** * @file fake_onewire.h * @brief Модель шины 1-Wire с виртуальными датчиками для host-тестов. diff --git a/c/ds18b20/tests/test_ds18b20.c b/c/ds18b20/tests/test_ds18b20.c index 47007bc..4e1d365 100644 --- a/c/ds18b20/tests/test_ds18b20.c +++ b/c/ds18b20/tests/test_ds18b20.c @@ -1,3 +1,19 @@ +/* + * Проверки ds18b20: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_crc8 + * test_search_finds_all + * test_search_on_empty_bus + * test_search_single_device + * test_scan_filters_family + * test_read_all + * test_crc_error_does_not_stop_the_poll + * test_missing_device_is_reported + * Остальные сценарии продолжают эти проверки ниже в том же файле. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /** * Тесты драйвера DS18B20 и переносимой части 1-Wire на симуляторе шины. * diff --git a/c/eeprom-ft24c256/ft24c256.c b/c/eeprom-ft24c256/ft24c256.c index b02ab7b..30f3a5e 100644 --- a/c/eeprom-ft24c256/ft24c256.c +++ b/c/eeprom-ft24c256/ft24c256.c @@ -1,3 +1,9 @@ +/* + * Доступ к EEPROM семейства 24Cxx через операции I2C порта. Запись разбивается на страницы: + * пересечение аппаратной границы одной транзакцией может завернуть адрес внутри страницы. + * После записи учитывается время внутреннего программирования. + */ + /** * @file ft24c256.c * @brief Постраничная запись, сплошное чтение и ожидание готовности FT24C256. diff --git a/c/eeprom-ft24c256/ft24c256.h b/c/eeprom-ft24c256/ft24c256.h index fd0d75e..09d7d1a 100644 --- a/c/eeprom-ft24c256/ft24c256.h +++ b/c/eeprom-ft24c256/ft24c256.h @@ -1,3 +1,9 @@ +/* + * Доступ к EEPROM семейства 24Cxx через операции I2C порта. Запись разбивается на страницы: + * пересечение аппаратной границы одной транзакцией может завернуть адрес внутри страницы. + * После записи учитывается время внутреннего программирования. + */ + /** * @file ft24c256.h * @brief Портируемый драйвер последовательной EEPROM FT24C256 и её семейства. diff --git a/c/firmware-info/CMakeLists.txt b/c/firmware-info/CMakeLists.txt index 6444a95..80e2680 100644 --- a/c/firmware-info/CMakeLists.txt +++ b/c/firmware-info/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки firmware_info. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.16) project(firmware_info C) add_library(firmware_info src/firmware_info.c) diff --git a/c/firmware-info/include/firmware_info.h b/c/firmware-info/include/firmware_info.h index 07531f8..bc2961b 100644 --- a/c/firmware-info/include/firmware_info.h +++ b/c/firmware-info/include/firmware_info.h @@ -1,3 +1,9 @@ +/* + * Представление версии работающей прошивки, даты сборки и идентификатора исходников. Данные + * переводятся в формат, доступный потребителям библиотеки; build ID описывает сборку и не + * заменяет контрольную сумму образа. + */ + #ifndef FIRMWARE_INFO_H #define FIRMWARE_INFO_H diff --git a/c/firmware-info/include/firmware_info_port.h b/c/firmware-info/include/firmware_info_port.h index 15a82ea..e4cd9a1 100644 --- a/c/firmware-info/include/firmware_info_port.h +++ b/c/firmware-info/include/firmware_info_port.h @@ -1,3 +1,9 @@ +/* + * Заполнение описания прошивки из макросов конфигурации конкретного MCU-проекта. Заголовок + * firmware_info_config.h выбирается путями включения; общая библиотека не должна содержать + * версию чужого приложения. + */ + #ifndef FIRMWARE_INFO_PORT_H #define FIRMWARE_INFO_PORT_H diff --git a/c/firmware-info/ports/k1921vk028/firmware_info_config.template.h b/c/firmware-info/ports/k1921vk028/firmware_info_config.template.h index 128a14f..e1d077f 100644 --- a/c/firmware-info/ports/k1921vk028/firmware_info_config.template.h +++ b/c/firmware-info/ports/k1921vk028/firmware_info_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация firmware-info для порта k1921vk028. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef FIRMWARE_INFO_CONFIG_H #define FIRMWARE_INFO_CONFIG_H #define FIRMWARE_VERSION_MAJOR 1U diff --git a/c/firmware-info/ports/stm32f1/firmware_info_config.template.h b/c/firmware-info/ports/stm32f1/firmware_info_config.template.h index d4ce748..9ca8b3f 100644 --- a/c/firmware-info/ports/stm32f1/firmware_info_config.template.h +++ b/c/firmware-info/ports/stm32f1/firmware_info_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация firmware-info для порта stm32f1. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef FIRMWARE_INFO_CONFIG_H #define FIRMWARE_INFO_CONFIG_H #define FIRMWARE_VERSION_MAJOR 1U diff --git a/c/firmware-info/ports/stm32f4/firmware_info_config.template.h b/c/firmware-info/ports/stm32f4/firmware_info_config.template.h index 128a14f..41a6503 100644 --- a/c/firmware-info/ports/stm32f4/firmware_info_config.template.h +++ b/c/firmware-info/ports/stm32f4/firmware_info_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация firmware-info для порта stm32f4. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef FIRMWARE_INFO_CONFIG_H #define FIRMWARE_INFO_CONFIG_H #define FIRMWARE_VERSION_MAJOR 1U diff --git a/c/firmware-info/ports/stm32g4/firmware_info_config.template.h b/c/firmware-info/ports/stm32g4/firmware_info_config.template.h index 128a14f..ca51155 100644 --- a/c/firmware-info/ports/stm32g4/firmware_info_config.template.h +++ b/c/firmware-info/ports/stm32g4/firmware_info_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация firmware-info для порта stm32g4. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef FIRMWARE_INFO_CONFIG_H #define FIRMWARE_INFO_CONFIG_H #define FIRMWARE_VERSION_MAJOR 1U diff --git a/c/firmware-info/src/firmware_info.c b/c/firmware-info/src/firmware_info.c index a30cc19..db3fbf8 100644 --- a/c/firmware-info/src/firmware_info.c +++ b/c/firmware-info/src/firmware_info.c @@ -1,3 +1,9 @@ +/* + * Представление версии работающей прошивки, даты сборки и идентификатора исходников. Данные + * переводятся в формат, доступный потребителям библиотеки; build ID описывает сборку и не + * заменяет контрольную сумму образа. + */ + #include "firmware_info.h" static const char months[12][4] = { diff --git a/c/firmware-info/src/firmware_info_port.c b/c/firmware-info/src/firmware_info_port.c index cced115..db9fdff 100644 --- a/c/firmware-info/src/firmware_info_port.c +++ b/c/firmware-info/src/firmware_info_port.c @@ -1,3 +1,9 @@ +/* + * Заполнение описания прошивки из макросов конфигурации конкретного MCU-проекта. Заголовок + * firmware_info_config.h выбирается путями включения; общая библиотека не должна содержать + * версию чужого приложения. + */ + #include "firmware_info_port.h" firmware_info_status_t firmware_info_port_describe(firmware_info_t *info) diff --git a/c/firmware-info/tests/test_firmware_info.c b/c/firmware-info/tests/test_firmware_info.c index 4c52854..7dff883 100644 --- a/c/firmware-info/tests/test_firmware_info.c +++ b/c/firmware-info/tests/test_firmware_info.c @@ -1,3 +1,9 @@ +/* + * Проверки firmware_info: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "firmware_info.h" #include #include diff --git a/c/firmware-info/tools/make_build_id.ps1 b/c/firmware-info/tools/make_build_id.ps1 index e217f12..fa53c72 100644 --- a/c/firmware-info/tools/make_build_id.ps1 +++ b/c/firmware-info/tools/make_build_id.ps1 @@ -1,3 +1,7 @@ +# Создание firmware_build_id.h из идентификатора Git для включения в прошивку. При отсутствии +# Git используется предусмотренное скриптом резервное значение; выходной файл содержит +# метаданные сборки, а не исходный код протокола. + param( [string]$Repository = (Resolve-Path (Join-Path $PSScriptRoot '..\..\..\..\..')).Path, [string]$Output = (Join-Path $PSScriptRoot '..\generated\firmware_build_id.h') diff --git a/c/flash-storage/CMakeLists.txt b/c/flash-storage/CMakeLists.txt index e0fe422..f335001 100644 --- a/c/flash-storage/CMakeLists.txt +++ b/c/flash-storage/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки flash_storage. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(flash_storage C) add_library(flash_storage STATIC Src/flash_storage.c) diff --git a/c/flash-storage/Inc/flash_storage.h b/c/flash-storage/Inc/flash_storage.h index db59a6d..f6e0f51 100644 --- a/c/flash-storage/Inc/flash_storage.h +++ b/c/flash-storage/Inc/flash_storage.h @@ -1,3 +1,9 @@ +/* + * Переносимое хранение записей во Flash с распознаванием версии формата и маркера завершённой + * записи. Разделение полезных данных и commit-маркера позволяет отличать завершённую запись от + * оборванной при потере питания. + */ + #ifndef PORTABLE_FLASH_STORAGE_H #define PORTABLE_FLASH_STORAGE_H #include diff --git a/c/flash-storage/Inc/flash_storage_config.h b/c/flash-storage/Inc/flash_storage_config.h index f4b8fb7..11a6d0d 100644 --- a/c/flash-storage/Inc/flash_storage_config.h +++ b/c/flash-storage/Inc/flash_storage_config.h @@ -1,3 +1,9 @@ +/* + * Конфигурация flash-storage. Макросы задают параметры сборки и ограничения, используемые + * исходниками этого модуля. Смысл и единицы каждого параметра определяются местом его + * использования; размеры буферов должны быть согласованы у всех потребителей заголовка. + */ + #ifndef PORTABLE_FLASH_STORAGE_CONFIG_H #define PORTABLE_FLASH_STORAGE_CONFIG_H #define FLASH_STORAGE_MAGIC 0x474E4952UL diff --git a/c/flash-storage/Src/flash_storage.c b/c/flash-storage/Src/flash_storage.c index 2cbef71..841c9c8 100644 --- a/c/flash-storage/Src/flash_storage.c +++ b/c/flash-storage/Src/flash_storage.c @@ -1,3 +1,9 @@ +/* + * Переносимое хранение записей во Flash с распознаванием версии формата и маркера завершённой + * записи. Разделение полезных данных и commit-маркера позволяет отличать завершённую запись от + * оборванной при потере питания. + */ + #include "flash_storage.h" #include "flash_storage_config.h" #include diff --git a/c/flash-storage/Tests/test_flash_storage.c b/c/flash-storage/Tests/test_flash_storage.c index fe36ecd..30b4bc6 100644 --- a/c/flash-storage/Tests/test_flash_storage.c +++ b/c/flash-storage/Tests/test_flash_storage.c @@ -1,3 +1,13 @@ +/* + * Проверки flash_storage: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_ds + * test_flash + * test_instances + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "ds18b20.h" #include "flash_storage.h" #include diff --git a/c/gas-logger/CMakeLists.txt b/c/gas-logger/CMakeLists.txt index cfa4bdf..c777b6a 100644 --- a/c/gas-logger/CMakeLists.txt +++ b/c/gas-logger/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки gas_logger, gas_logger_pm35, gas_logger_pcan. Состав исходников и +# публичные include-пути задают подключение к проекту потребителя. Файл также собирает и +# регистрирует хостовые проверки; запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.16) project(gas_logger C) set(CMAKE_C_STANDARD 99) diff --git a/c/gas-logger/include/gas_logger.h b/c/gas-logger/include/gas_logger.h index a7eba35..0200d84 100644 --- a/c/gas-logger/include/gas_logger.h +++ b/c/gas-logger/include/gas_logger.h @@ -1,3 +1,9 @@ +/* + * Непрерывная запись каналов в два банка и выдача согласованного снимка через регистровый + * интерфейс. Адреса и количества регистратора считаются в 16-битных словах, включая C28x; + * чтение снимка отделено от текущего сбора. + */ + /* Portable continuous recorder. All addresses/counts are 16-bit WORDS, * including on C28x (CHAR_BIT=16). No heap, UART, HAL or global state. */ #ifndef GAS_LOGGER_H diff --git a/c/gas-logger/include/gas_logger_pcan.h b/c/gas-logger/include/gas_logger_pcan.h index 52b7e1d..62f469c 100644 --- a/c/gas-logger/include/gas_logger_pcan.h +++ b/c/gas-logger/include/gas_logger_pcan.h @@ -1,3 +1,9 @@ +/* + * Подключение регистратора к диспетчеру ProtoCAN GAS. Адаптер переводит относительное смещение + * региона в адрес регистратора и сопоставляет коды ошибок двух интерфейсов, сохраняя сам сбор + * данных в gas_logger. + */ + #ifndef GAS_LOGGER_PCAN_H #define GAS_LOGGER_PCAN_H #include "gas_logger.h" diff --git a/c/gas-logger/ports/c28x/gas_logger_c28x.c b/c/gas-logger/ports/c28x/gas_logger_c28x.c index 1a5136b..ff37139 100644 --- a/c/gas-logger/ports/c28x/gas_logger_c28x.c +++ b/c/gas-logger/ports/c28x/gas_logger_c28x.c @@ -1,3 +1,9 @@ +/* + * Критические секции регистратора для TI C28x. При входе сохраняется прежнее состояние + * прерываний, при выходе восстанавливается именно оно: безусловное разрешение нарушило бы + * вложенную критическую секцию. + */ + #include "gas_logger_c28x.h" /* __disable_interrupts/__restore_interrupts are TI C28x compiler intrinsics. */ uint32_t gl_c28x_enter(void *user) { (void)user; return __disable_interrupts(); } diff --git a/c/gas-logger/ports/c28x/gas_logger_c28x.h b/c/gas-logger/ports/c28x/gas_logger_c28x.h index a38d6b7..1ff3198 100644 --- a/c/gas-logger/ports/c28x/gas_logger_c28x.h +++ b/c/gas-logger/ports/c28x/gas_logger_c28x.h @@ -1,3 +1,9 @@ +/* + * Критические секции регистратора для TI C28x. При входе сохраняется прежнее состояние + * прерываний, при выходе восстанавливается именно оно: безусловное разрешение нарушило бы + * вложенную критическую секцию. + */ + #ifndef GAS_LOGGER_C28X_H #define GAS_LOGGER_C28X_H #include diff --git a/c/gas-logger/ports/pm35/gas_logger_pm35.c b/c/gas-logger/ports/pm35/gas_logger_pm35.c index fd109bc..d6ec2bd 100644 --- a/c/gas-logger/ports/pm35/gas_logger_pm35.c +++ b/c/gas-logger/ports/pm35/gas_logger_pm35.c @@ -1,3 +1,9 @@ +/* + * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с + * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка + * даже при успешном обмене. + */ + #include "gas_logger_pm35.h" #include "pm35_map.h" static uint32_t enter(void *u) { gl_pm35_context *p=u; return p->enter(p->irq_user); } diff --git a/c/gas-logger/ports/pm35/gas_logger_pm35.h b/c/gas-logger/ports/pm35/gas_logger_pm35.h index e6ce6a6..c129414 100644 --- a/c/gas-logger/ports/pm35/gas_logger_pm35.h +++ b/c/gas-logger/ports/pm35/gas_logger_pm35.h @@ -1,3 +1,9 @@ +/* + * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с + * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка + * даже при успешном обмене. + */ + #ifndef GAS_LOGGER_PM35_H #define GAS_LOGGER_PM35_H #include "gas_logger.h" diff --git a/c/gas-logger/ports/pm35/pm35_map.h b/c/gas-logger/ports/pm35/pm35_map.h index f0cfefa..15193e8 100644 --- a/c/gas-logger/ports/pm35/pm35_map.h +++ b/c/gas-logger/ports/pm35/pm35_map.h @@ -1,3 +1,9 @@ +/* + * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с + * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка + * даже при успешном обмене. + */ + /* Generated from pm35.json. Do not edit. */ #ifndef GL_PM35_MAP_H #define GL_PM35_MAP_H diff --git a/c/gas-logger/ports/stm32/gas_logger_stm32.c b/c/gas-logger/ports/stm32/gas_logger_stm32.c index 6c0822d..e1317be 100644 --- a/c/gas-logger/ports/stm32/gas_logger_stm32.c +++ b/c/gas-logger/ports/stm32/gas_logger_stm32.c @@ -1,3 +1,9 @@ +/* + * Критические секции регистратора для STM32 через состояние маски прерываний. Сохранённое + * значение передаётся из входа в выход, чтобы не разрешить прерывания, уже запрещённые + * вызывающим кодом. + */ + #include "gas_logger_stm32.h" #ifndef GL_STM32_DEVICE_HEADER #define GL_STM32_DEVICE_HEADER "stm32f4xx.h" diff --git a/c/gas-logger/ports/stm32/gas_logger_stm32.h b/c/gas-logger/ports/stm32/gas_logger_stm32.h index c42cb6d..bedbf32 100644 --- a/c/gas-logger/ports/stm32/gas_logger_stm32.h +++ b/c/gas-logger/ports/stm32/gas_logger_stm32.h @@ -1,3 +1,9 @@ +/* + * Критические секции регистратора для STM32 через состояние маски прерываний. Сохранённое + * значение передаётся из входа в выход, чтобы не разрешить прерывания, уже запрещённые + * вызывающим кодом. + */ + #ifndef GAS_LOGGER_STM32_H #define GAS_LOGGER_STM32_H #include diff --git a/c/gas-logger/src/gas_logger.c b/c/gas-logger/src/gas_logger.c index 6dd68e1..1ac392a 100644 --- a/c/gas-logger/src/gas_logger.c +++ b/c/gas-logger/src/gas_logger.c @@ -1,3 +1,9 @@ +/* + * Непрерывная запись каналов в два банка и выдача согласованного снимка через регистровый + * интерфейс. Адреса и количества регистратора считаются в 16-битных словах, включая C28x; + * чтение снимка отделено от текущего сбора. + */ + #include "gas_logger.h" #include #include diff --git a/c/gas-logger/src/gas_logger_pcan.c b/c/gas-logger/src/gas_logger_pcan.c index 1f316a3..044914a 100644 --- a/c/gas-logger/src/gas_logger_pcan.c +++ b/c/gas-logger/src/gas_logger_pcan.c @@ -1,3 +1,9 @@ +/* + * Подключение регистратора к диспетчеру ProtoCAN GAS. Адаптер переводит относительное смещение + * региона в адрес регистратора и сопоставляет коды ошибок двух интерфейсов, сохраняя сам сбор + * данных в gas_logger. + */ + #include "gas_logger_pcan.h" static pcan_gas_status_t result(gl_result r) { return r==GL_OK ? PCAN_GAS_OK : r==GL_ADDRESS ? PCAN_GAS_NO_REG : PCAN_GAS_REJECTED; } diff --git a/c/gas-logger/tests/host_device.c b/c/gas-logger/tests/host_device.c index e221b8b..428c7ee 100644 --- a/c/gas-logger/tests/host_device.c +++ b/c/gas-logger/tests/host_device.c @@ -1,3 +1,9 @@ +/* + * Проверки host_device: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /* Host-only firmware harness for the actual PM35 port and Python client. */ #include "gas_logger_pm35.h" #include "gas_logger_pcan.h" diff --git a/c/gas-logger/tests/run_tests.py b/c/gas-logger/tests/run_tests.py index d12fd16..fab55db 100644 --- a/c/gas-logger/tests/run_tests.py +++ b/c/gas-logger/tests/run_tests.py @@ -1,3 +1,7 @@ +# Проверки run_tests: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Build in a temporary directory; run core + Python/C end-to-end tests.""" import argparse import ctypes diff --git a/c/gas-logger/tests/test_client.py b/c/gas-logger/tests/test_client.py index bb8a2e0..c3162e4 100644 --- a/c/gas-logger/tests/test_client.py +++ b/c/gas-logger/tests/test_client.py @@ -1,3 +1,17 @@ +# Проверки client: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_download_keeps_recording_and_order +# test_cancel_retains_snapshot_and_explicit_resume +# test_partial_reply_leaves_pin +# test_no_writes_for_wrong_schema +# test_generation_mismatch_does_not_release +# test_classic_can_chunks_and_pcan_region +# test_json_rejects_collisions_and_drift +# test_replaced_snapshot_is_rejected_before_release +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Integration: Python client -> register callbacks -> compiled C PM35 logger.""" import copy import ctypes diff --git a/c/gas-logger/tests/test_gas_logger.c b/c/gas-logger/tests/test_gas_logger.c index 3582be3..f937a4e 100644 --- a/c/gas-logger/tests/test_gas_logger.c +++ b/c/gas-logger/tests/test_gas_logger.c @@ -1,3 +1,9 @@ +/* + * Проверки gas_logger: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "gas_logger.h" #include #include diff --git a/c/gas-logger/tools/generate_map.py b/c/gas-logger/tools/generate_map.py index 692f8c2..ef4aa09 100644 --- a/c/gas-logger/tools/generate_map.py +++ b/c/gas-logger/tools/generate_map.py @@ -1,3 +1,7 @@ +# Генерация C-представления карты сигналов из JSON и проверка его актуальности. Один источник +# карты связывает прошивку и клиента; ручная правка сгенерированной таблицы создаст +# расхождение при следующей генерации. + """Regenerate/verify the firmware mirror of the packaged JSON map.""" from pathlib import Path import argparse diff --git a/c/keypad/keypad.c b/c/keypad/keypad.c index 2647694..9fe7b60 100644 --- a/c/keypad/keypad.c +++ b/c/keypad/keypad.c @@ -1,3 +1,9 @@ +/* + * Опрос кнопок с антидребезгом, удержанием и автоповтором. Сырые уровни и подтверждённые + * состояния хранятся раздельно; события поступают в ограниченную очередь, переполнение которой + * можно обнаружить отдельно. + */ + /** * @file keypad.c * @brief Антидребезг, автоповтор и очередь событий шести кнопок. diff --git a/c/keypad/keypad.h b/c/keypad/keypad.h index f6c6794..08a5a0f 100644 --- a/c/keypad/keypad.h +++ b/c/keypad/keypad.h @@ -1,3 +1,9 @@ +/* + * Опрос кнопок с антидребезгом, удержанием и автоповтором. Сырые уровни и подтверждённые + * состояния хранятся раздельно; события поступают в ограниченную очередь, переполнение которой + * можно обнаружить отдельно. + */ + /** * @file keypad.h * @brief Портируемый опрос шести кнопок навигации с антидребезгом. diff --git a/c/led-indicator/CMakeLists.txt b/c/led-indicator/CMakeLists.txt index ffabcdf..8e684d4 100644 --- a/c/led-indicator/CMakeLists.txt +++ b/c/led-indicator/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки led_indicator. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(led_indicator C) diff --git a/c/led-indicator/led_indicator.c b/c/led-indicator/led_indicator.c index 930ff21..13e998d 100644 --- a/c/led-indicator/led_indicator.c +++ b/c/led-indicator/led_indicator.c @@ -1,3 +1,9 @@ +/* + * Неблокирующее воспроизведение режимов светодиодной индикации по переданному времени. + * Логический уровень канала отделён от полярности вывода; периодический вызов обслуживает + * рисунок без задержек в основном цикле. + */ + #include "led_indicator.h" #include diff --git a/c/led-indicator/led_indicator.h b/c/led-indicator/led_indicator.h index b63b07e..a910599 100644 --- a/c/led-indicator/led_indicator.h +++ b/c/led-indicator/led_indicator.h @@ -1,3 +1,9 @@ +/* + * Неблокирующее воспроизведение режимов светодиодной индикации по переданному времени. + * Логический уровень канала отделён от полярности вывода; периодический вызов обслуживает + * рисунок без задержек в основном цикле. + */ + /** * @file led_indicator.h * @brief Неблокирующая индикация состояния устройства на одном или нескольких LED. diff --git a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.c b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.c index fb44778..48b8e7e 100644 --- a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.c +++ b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.c @@ -1,3 +1,9 @@ +/* + * Порт светодиодной индикации через STM32 HAL. Логическое состояние канала преобразуется в + * GPIO-уровень с учётом активной полярности; ядро рисунков мигания не знает номера вывода и + * семейства MCU. + */ + #include "led_indicator_stm32_hal.h" static void stm32_write(void *context, uint8_t channel, uint8_t on) diff --git a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.h b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.h index 28b4aca..5a2f8e7 100644 --- a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.h +++ b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal.h @@ -1,3 +1,9 @@ +/* + * Порт светодиодной индикации через STM32 HAL. Логическое состояние канала преобразуется в + * GPIO-уровень с учётом активной полярности; ядро рисунков мигания не знает номера вывода и + * семейства MCU. + */ + /** * @file led_indicator_stm32_hal.h * @brief Порт LED Indicator для STM32F1/F4/G4 HAL и выбранного TIM. diff --git a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f1.template.h b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f1.template.h index 85038d3..8dd9b4f 100644 --- a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f1.template.h +++ b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f1.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация led-indicator для порта stm32-hal. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef LED_INDICATOR_STM32_HAL_CONFIG_H #define LED_INDICATOR_STM32_HAL_CONFIG_H diff --git a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f4.template.h b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f4.template.h index 10e25b1..162701d 100644 --- a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f4.template.h +++ b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.f4.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация led-indicator для порта stm32-hal. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef LED_INDICATOR_STM32_HAL_CONFIG_H #define LED_INDICATOR_STM32_HAL_CONFIG_H diff --git a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.g4.template.h b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.g4.template.h index d157754..ea99f1f 100644 --- a/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.g4.template.h +++ b/c/led-indicator/ports/stm32-hal/led_indicator_stm32_hal_config.g4.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация led-indicator для порта stm32-hal. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef LED_INDICATOR_STM32_HAL_CONFIG_H #define LED_INDICATOR_STM32_HAL_CONFIG_H diff --git a/c/led-indicator/tests/fakes/led_indicator_stm32_hal_config.h b/c/led-indicator/tests/fakes/led_indicator_stm32_hal_config.h index 6e9cf41..87d3705 100644 --- a/c/led-indicator/tests/fakes/led_indicator_stm32_hal_config.h +++ b/c/led-indicator/tests/fakes/led_indicator_stm32_hal_config.h @@ -1,3 +1,10 @@ +/* + * Проверки led_indicator_stm32_hal_config: фиксируют ожидаемое поведение на воспроизводимых + * входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #ifndef LED_INDICATOR_STM32_HAL_CONFIG_H #define LED_INDICATOR_STM32_HAL_CONFIG_H diff --git a/c/led-indicator/tests/test_led_indicator.c b/c/led-indicator/tests/test_led_indicator.c index b1aa9c6..b72cc9d 100644 --- a/c/led-indicator/tests/test_led_indicator.c +++ b/c/led-indicator/tests/test_led_indicator.c @@ -1,3 +1,9 @@ +/* + * Проверки led_indicator: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "led_indicator.h" #include diff --git a/c/led-indicator/tests/test_stm32_port.c b/c/led-indicator/tests/test_stm32_port.c index 134565d..c324a14 100644 --- a/c/led-indicator/tests/test_stm32_port.c +++ b/c/led-indicator/tests/test_stm32_port.c @@ -1,3 +1,9 @@ +/* + * Проверки stm32_port: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "led_indicator_stm32_hal.h" #include diff --git a/c/menu/menu.c b/c/menu/menu.c index 1453759..5d94f31 100644 --- a/c/menu/menu.c +++ b/c/menu/menu.c @@ -1,3 +1,9 @@ +/* + * Экранное меню со стеком переходов, курсором, прокруткой и отрисовкой через Menu_Painter. + * Состояние навигации отделено от физического дисплея; признак dirty позволяет перерисовывать + * только после изменений. + */ + /** * @file menu.c * @brief Навигация по экранам меню и их отрисовка через Menu_Painter. diff --git a/c/menu/menu.h b/c/menu/menu.h index d1bdc3a..b83a74b 100644 --- a/c/menu/menu.h +++ b/c/menu/menu.h @@ -1,3 +1,9 @@ +/* + * Экранное меню со стеком переходов, курсором, прокруткой и отрисовкой через Menu_Painter. + * Состояние навигации отделено от физического дисплея; признак dirty позволяет перерисовывать + * только после изменений. + */ + /** * @file menu.h * @brief Портируемое меню для дисплея и шести кнопок навигации. diff --git a/c/modbus/CMakeLists.txt b/c/modbus/CMakeLists.txt index 96237ac..ee5d77e 100644 --- a/c/modbus/CMakeLists.txt +++ b/c/modbus/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки set_modbus. Состав исходников и публичные include-пути задают подключение +# к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их +# следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(set_modbus C) add_library(set_modbus STATIC src/modbus_data.c) diff --git a/c/modbus/include/modbus_data.h b/c/modbus/include/modbus_data.h index 878897d..09a4ba2 100644 --- a/c/modbus/include/modbus_data.h +++ b/c/modbus/include/modbus_data.h @@ -1,3 +1,9 @@ +/* + * Проверка количества данных и перенос значений Modbus между сообщением и банком регистров. + * Coils упакованы младшим битом вперёд, а пары байтов сообщения имеют собственный порядок; + * адресный диапазон проверяет вызывающий порт. + */ + #ifndef SET_MODBUS_DATA_H #define SET_MODBUS_DATA_H #include diff --git a/c/modbus/ports/stm32-legacy/modbus.c b/c/modbus/ports/stm32-legacy/modbus.c index 8b7c965..3ad1ae4 100644 --- a/c/modbus/ports/stm32-legacy/modbus.c +++ b/c/modbus/ports/stm32-legacy/modbus.c @@ -1,3 +1,9 @@ +/* + * Исторический STM32-порт Modbus с привязкой к окружению прошивки. Здесь находятся транспорт и + * обслуживание запросов конкретной платформы; переносимые операции над данными вынесены в + * modbus_data. + */ + /** ************************************************************************** * @file modbus.c diff --git a/c/modbus/src/modbus_data.c b/c/modbus/src/modbus_data.c index a2e867d..0fe1361 100644 --- a/c/modbus/src/modbus_data.c +++ b/c/modbus/src/modbus_data.c @@ -1,3 +1,9 @@ +/* + * Проверка количества данных и перенос значений Modbus между сообщением и банком регистров. + * Coils упакованы младшим битом вперёд, а пары байтов сообщения имеют собственный порядок; + * адресный диапазон проверяет вызывающий порт. + */ + #include "../include/modbus_data.h" uint8_t mb_data_validate(uint8_t function, uint16_t quantity, uint16_t bytes, size_t capacity) diff --git a/c/modbus/tests/test_modbus_data.c b/c/modbus/tests/test_modbus_data.c index 14064f5..aa41462 100644 --- a/c/modbus/tests/test_modbus_data.c +++ b/c/modbus/tests/test_modbus_data.c @@ -1,3 +1,9 @@ +/* + * Проверки modbus_data: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "modbus_data.h" #include #include diff --git a/c/parallel-nand/CMakeLists.txt b/c/parallel-nand/CMakeLists.txt index 0960b91..ff54096 100644 --- a/c/parallel-nand/CMakeLists.txt +++ b/c/parallel-nand/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки parallel_nand, parallel_nand_pcan_gas. Состав исходников и публичные +# include-пути задают подключение к проекту потребителя. Файл также собирает и регистрирует +# хостовые проверки; запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.16) project(parallel_nand C) diff --git a/c/parallel-nand/include/parallel_nand.h b/c/parallel-nand/include/parallel_nand.h index 615ab30..5b3a359 100644 --- a/c/parallel-nand/include/parallel_nand.h +++ b/c/parallel-nand/include/parallel_nand.h @@ -1,3 +1,9 @@ +/* + * Команды параллельной NAND x8: идентификация, чтение, программирование, стирание и проверка + * bad-block marker. Геометрия страницы и блока определяется профилем микросхемы; операции + * записи требуют корректного управления WP#. + */ + #ifndef PARALLEL_NAND_H #define PARALLEL_NAND_H diff --git a/c/parallel-nand/include/parallel_nand_gas.h b/c/parallel-nand/include/parallel_nand_gas.h index 261f0e9..6190807 100644 --- a/c/parallel-nand/include/parallel_nand_gas.h +++ b/c/parallel-nand/include/parallel_nand_gas.h @@ -1,3 +1,8 @@ +/* + * Банковое окно доступа к NAND через регистры GAS. Пары октетов упаковываются в слова явно; + * переключение банка задаёт видимую область памяти и не меняет физическую геометрию NAND. + */ + #ifndef PARALLEL_NAND_GAS_H #define PARALLEL_NAND_GAS_H diff --git a/c/parallel-nand/include/parallel_nand_pcan_gas.h b/c/parallel-nand/include/parallel_nand_pcan_gas.h index 939cd71..d5488f2 100644 --- a/c/parallel-nand/include/parallel_nand_pcan_gas.h +++ b/c/parallel-nand/include/parallel_nand_pcan_gas.h @@ -1,3 +1,8 @@ +/* + * Связка окна NAND с сервером ProtoCAN GAS. Относительные адреса региона и результаты операций + * переводятся в контракт GAS, а выполнение команд памяти остаётся в parallel_nand_gas. + */ + #ifndef PARALLEL_NAND_PCAN_GAS_H #define PARALLEL_NAND_PCAN_GAS_H diff --git a/c/parallel-nand/include/parallel_nand_port.h b/c/parallel-nand/include/parallel_nand_port.h index 8bf93e3..c3a006a 100644 --- a/c/parallel-nand/include/parallel_nand_port.h +++ b/c/parallel-nand/include/parallel_nand_port.h @@ -1,3 +1,9 @@ +/* + * Контракт аппаратного доступа к NAND: команды, адреса, данные и ожидание готовности. Один + * octet хранится в целом типе, чтобы восемь значащих бит оставались переносимыми на C28x с + * 16-битным char. + */ + #ifndef PARALLEL_NAND_PORT_H #define PARALLEL_NAND_PORT_H diff --git a/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.c b/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.c index cfa5f39..591d978 100644 --- a/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.c +++ b/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.c @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32F103RC через программное управление GPIO: на этом корпусе нет доступного + * FSMC. Передача команды, адреса и данных использует разные управляющие линии; WP# должен + * разрешать запись только по контракту порта. + */ + #include "parallel_nand_port_stm32f103rc.h" #include "stm32f1xx_hal.h" diff --git a/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.h b/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.h index 7d76f27..4f6f5ec 100644 --- a/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.h +++ b/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.h @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32F103RC через программное управление GPIO: на этом корпусе нет доступного + * FSMC. Передача команды, адреса и данных использует разные управляющие линии; WP# должен + * разрешать запись только по контракту порта. + */ + #ifndef PARALLEL_NAND_PORT_STM32F103RC_H #define PARALLEL_NAND_PORT_STM32F103RC_H diff --git a/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.c b/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.c index 83134ef..d238fc3 100644 --- a/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.c +++ b/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.c @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32F103ZE через FSMC NAND Bank 3. Отдельные окна команды, адреса и данных + * отображаются в пространство процессора; их адреса относятся к шине FSMC, а не к физической + * странице NAND. + */ + #include "parallel_nand_port_stm32f103ze.h" #include "stm32f1xx_hal.h" diff --git a/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.h b/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.h index d5483a4..fc73351 100644 --- a/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.h +++ b/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.h @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32F103ZE через FSMC NAND Bank 3. Отдельные окна команды, адреса и данных + * отображаются в пространство процессора; их адреса относятся к шине FSMC, а не к физической + * странице NAND. + */ + #ifndef PARALLEL_NAND_PORT_STM32F103ZE_H #define PARALLEL_NAND_PORT_STM32F103ZE_H diff --git a/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.c b/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.c index d2fab45..a1760d7 100644 --- a/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.c +++ b/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.c @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32F407VE через FSMC Bank 2. Область данных начинается с 0x70000000, а + * управляющие адресные биты выбирают команду и адрес; геометрией памяти управляет переносимое + * ядро. + */ + #include "parallel_nand_port_stm32f407ve.h" #include "stm32f4xx_hal.h" #include "stm32f4xx_hal_nand.h" diff --git a/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.h b/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.h index 36c1e8d..523399e 100644 --- a/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.h +++ b/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.h @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32F407VE через FSMC Bank 2. Область данных начинается с 0x70000000, а + * управляющие адресные биты выбирают команду и адрес; геометрией памяти управляет переносимое + * ядро. + */ + #ifndef PARALLEL_NAND_PORT_STM32F407VE_H #define PARALLEL_NAND_PORT_STM32F407VE_H diff --git a/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.c b/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.c index b9819b6..0b96bda 100644 --- a/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.c +++ b/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.c @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32G474CE через GPIO, где PB0..PB7 образуют шину данных. Порт формирует + * управляющие импульсы программно; переключение направления данных необходимо для чтения и + * записи одной двунаправленной шиной. + */ + #include "parallel_nand_port_stm32g474ce.h" #include "stm32g4xx_hal.h" diff --git a/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.h b/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.h index 409e52d..61b41fc 100644 --- a/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.h +++ b/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.h @@ -1,3 +1,9 @@ +/* + * NAND x8 на STM32G474CE через GPIO, где PB0..PB7 образуют шину данных. Порт формирует + * управляющие импульсы программно; переключение направления данных необходимо для чтения и + * записи одной двунаправленной шиной. + */ + #ifndef PARALLEL_NAND_PORT_STM32G474CE_H #define PARALLEL_NAND_PORT_STM32G474CE_H diff --git a/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.c b/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.c index d82f325..7d5abbc 100644 --- a/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.c +++ b/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.c @@ -1,3 +1,8 @@ +/* + * NAND через XINTF TMS320F2812 с адресными линиями XA0/XA1 для CLE/ALE. Адреса C28x измеряются + * 16-битными словами, но полезные данные NAND остаются восьмибитными октетами. + */ + #include "parallel_nand_port_tms320f2812.h" #include "DSP281x_Device.h" diff --git a/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.h b/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.h index ecddb38..9b5f064 100644 --- a/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.h +++ b/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.h @@ -1,3 +1,8 @@ +/* + * NAND через XINTF TMS320F2812 с адресными линиями XA0/XA1 для CLE/ALE. Адреса C28x измеряются + * 16-битными словами, но полезные данные NAND остаются восьмибитными октетами. + */ + #ifndef PARALLEL_NAND_PORT_TMS320F2812_H #define PARALLEL_NAND_PORT_TMS320F2812_H diff --git a/c/parallel-nand/src/parallel_nand.c b/c/parallel-nand/src/parallel_nand.c index 90d28b1..d086a0f 100644 --- a/c/parallel-nand/src/parallel_nand.c +++ b/c/parallel-nand/src/parallel_nand.c @@ -1,3 +1,9 @@ +/* + * Команды параллельной NAND x8: идентификация, чтение, программирование, стирание и проверка + * bad-block marker. Геометрия страницы и блока определяется профилем микросхемы; операции + * записи требуют корректного управления WP#. + */ + #include "parallel_nand.h" #define PNAND_CMD_READ_1 0x00U diff --git a/c/parallel-nand/src/parallel_nand_gas.c b/c/parallel-nand/src/parallel_nand_gas.c index 996d24d..5368e16 100644 --- a/c/parallel-nand/src/parallel_nand_gas.c +++ b/c/parallel-nand/src/parallel_nand_gas.c @@ -1,3 +1,8 @@ +/* + * Банковое окно доступа к NAND через регистры GAS. Пары октетов упаковываются в слова явно; + * переключение банка задаёт видимую область памяти и не меняет физическую геометрию NAND. + */ + #include "parallel_nand_gas.h" static unsigned int pack_pair(const pnand_octet_t *data, unsigned int index) diff --git a/c/parallel-nand/src/parallel_nand_pcan_gas.c b/c/parallel-nand/src/parallel_nand_pcan_gas.c index 9e7f6a8..a793055 100644 --- a/c/parallel-nand/src/parallel_nand_pcan_gas.c +++ b/c/parallel-nand/src/parallel_nand_pcan_gas.c @@ -1,3 +1,8 @@ +/* + * Связка окна NAND с сервером ProtoCAN GAS. Относительные адреса региона и результаты операций + * переводятся в контракт GAS, а выполнение команд памяти остаётся в parallel_nand_gas. + */ + #include "parallel_nand_pcan_gas.h" static pcan_gas_status_t convert(parallel_nand_gas_result_t result) diff --git a/c/parallel-nand/tests/test_parallel_nand.c b/c/parallel-nand/tests/test_parallel_nand.c index 82dc797..753ca5f 100644 --- a/c/parallel-nand/tests/test_parallel_nand.c +++ b/c/parallel-nand/tests/test_parallel_nand.c @@ -1,3 +1,9 @@ +/* + * Проверки parallel_nand: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include #include diff --git a/c/protocan-boot/CMakeLists.txt b/c/protocan-boot/CMakeLists.txt index d984ca5..47d6c8e 100644 --- a/c/protocan-boot/CMakeLists.txt +++ b/c/protocan-boot/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки protocan_boot. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(protocan_boot C) diff --git a/c/protocan-boot/include/pcan_boot.h b/c/protocan-boot/include/pcan_boot.h index f984296..7118b51 100644 --- a/c/protocan-boot/include/pcan_boot.h +++ b/c/protocan-boot/include/pcan_boot.h @@ -1,3 +1,9 @@ +/* + * Автомат адресной загрузки прошивки по ProtoCAN с сессией, контрольной суммой и A/B-слотами. + * Приём блоков, проверка образа и активация разделены на этапы; операции Flash и метаданные + * слотов предоставляет платформа. + */ + #ifndef PCAN_BOOT_H #define PCAN_BOOT_H diff --git a/c/protocan-boot/src/pcan_boot.c b/c/protocan-boot/src/pcan_boot.c index fa4c918..7b92239 100644 --- a/c/protocan-boot/src/pcan_boot.c +++ b/c/protocan-boot/src/pcan_boot.c @@ -1,3 +1,9 @@ +/* + * Автомат адресной загрузки прошивки по ProtoCAN с сессией, контрольной суммой и A/B-слотами. + * Приём блоков, проверка образа и активация разделены на этапы; операции Flash и метаданные + * слотов предоставляет платформа. + */ + #include "pcan_boot.h" #include diff --git a/c/protocan-boot/tests/test_pcan_boot.c b/c/protocan-boot/tests/test_pcan_boot.c index 1ccd603..d871412 100644 --- a/c/protocan-boot/tests/test_pcan_boot.c +++ b/c/protocan-boot/tests/test_pcan_boot.c @@ -1,3 +1,16 @@ +/* + * Проверки pcan_boot: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_id_layout + * test_crc32_reference + * test_complete_update + * test_rejects_wrong_address_and_sequence + * test_rejects_wrong_session_and_compatibility + * test_single_slot_update + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "pcan_boot.h" #include diff --git a/c/rs485-boot/CMakeLists.txt b/c/rs485-boot/CMakeLists.txt index 714d420..6ac161c 100644 --- a/c/rs485-boot/CMakeLists.txt +++ b/c/rs485-boot/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки rs485_boot. Состав исходников и публичные include-пути задают подключение +# к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их +# следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.16) project(rs485_boot C) add_library(rs485_boot src/rs485_boot.c) diff --git a/c/rs485-boot/include/rs485_boot.h b/c/rs485-boot/include/rs485_boot.h index c4072c4..9068cf8 100644 --- a/c/rs485-boot/include/rs485_boot.h +++ b/c/rs485-boot/include/rs485_boot.h @@ -1,3 +1,9 @@ +/* + * Потоковый загрузчик по RS-485 с кадрированием, CRC32 и продолжением передачи. Автомат + * принимает части входного потока и вызывает операции Flash через порт; неполный кадр не + * является готовой командой. + */ + #ifndef RS485_BOOT_H #define RS485_BOOT_H diff --git a/c/rs485-boot/ports/c28x/rs_boot_transport.c b/c/rs485-boot/ports/c28x/rs_boot_transport.c index a783384..4d94966 100644 --- a/c/rs485-boot/ports/c28x/rs_boot_transport.c +++ b/c/rs485-boot/ports/c28x/rs_boot_transport.c @@ -1,3 +1,9 @@ +/* + * Транспорт загрузчика для C28x, где элемент памяти шире передаваемого октета. Кадры + * собираются из восьми значащих бит каждого элемента; адреса памяти нельзя автоматически + * трактовать как байтовые адреса ПК. + */ + #include "rs_boot_transport.h" #define SOF0 0xA5U diff --git a/c/rs485-boot/ports/c28x/rs_boot_transport.h b/c/rs485-boot/ports/c28x/rs_boot_transport.h index 7447509..fa7b72b 100644 --- a/c/rs485-boot/ports/c28x/rs_boot_transport.h +++ b/c/rs485-boot/ports/c28x/rs_boot_transport.h @@ -1,3 +1,9 @@ +/* + * Транспорт загрузчика для C28x, где элемент памяти шире передаваемого октета. Кадры + * собираются из восьми значащих бит каждого элемента; адреса памяти нельзя автоматически + * трактовать как байтовые адреса ПК. + */ + #ifndef RS_BOOT_TRANSPORT_H #define RS_BOOT_TRANSPORT_H diff --git a/c/rs485-boot/ports/stm32f103/rs485_boot_port_config.template.h b/c/rs485-boot/ports/stm32f103/rs485_boot_port_config.template.h index e416160..a6770ee 100644 --- a/c/rs485-boot/ports/stm32f103/rs485_boot_port_config.template.h +++ b/c/rs485-boot/ports/stm32f103/rs485_boot_port_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация rs485-boot для порта stm32f103. Макросы задают параметры сборки и ограничения, + * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров + * памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef RS485_BOOT_PORT_CONFIG_H #define RS485_BOOT_PORT_CONFIG_H #define RS485_BOOT_BAUDRATE 512000UL diff --git a/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.c b/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.c index 942f4f0..0fac9fa 100644 --- a/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.c +++ b/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.c @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для STM32F103 с прямым доступом к Flash-регистрам. Завершение BUSY и + * флаги ошибок проверяются перед продолжением; расположение области приложения задаётся + * rs485_boot_port_config.h. + */ + #include "rs485_boot_stm32f103.h" #include "rs485_boot_port_config.h" #include "stm32f10x.h" diff --git a/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.h b/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.h index fc6c3cb..a0ad124 100644 --- a/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.h +++ b/c/rs485-boot/ports/stm32f103/rs485_boot_stm32f103.h @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для STM32F103 с прямым доступом к Flash-регистрам. Завершение BUSY и + * флаги ошибок проверяются перед продолжением; расположение области приложения задаётся + * rs485_boot_port_config.h. + */ + #ifndef RS485_BOOT_STM32F103_H #define RS485_BOOT_STM32F103_H #include "rs485_boot.h" diff --git a/c/rs485-boot/ports/stm32g474vet/rs485_boot_port_config.template.h b/c/rs485-boot/ports/stm32g474vet/rs485_boot_port_config.template.h index c14af95..fa4b0b6 100644 --- a/c/rs485-boot/ports/stm32g474vet/rs485_boot_port_config.template.h +++ b/c/rs485-boot/ports/stm32g474vet/rs485_boot_port_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация rs485-boot для порта stm32g474vet. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef RS485_BOOT_PORT_CONFIG_H #define RS485_BOOT_PORT_CONFIG_H #define RS485_BOOT_BAUDRATE 512000UL diff --git a/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.c b/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.c index e7ab260..36e75b8 100644 --- a/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.c +++ b/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.c @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для STM32G474VET с аппаратными операциями Flash. Конфигурация задаёт + * область приложения, а обработчик проверяет BUSY и ошибки программирования до подтверждения + * операции. + */ + #include "rs485_boot_stm32g474vet.h" #include "rs485_boot_port_config.h" #include "stm32g474xx.h" diff --git a/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.h b/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.h index f10350b..8ab1d9b 100644 --- a/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.h +++ b/c/rs485-boot/ports/stm32g474vet/rs485_boot_stm32g474vet.h @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для STM32G474VET с аппаратными операциями Flash. Конфигурация задаёт + * область приложения, а обработчик проверяет BUSY и ошибки программирования до подтверждения + * операции. + */ + #ifndef RS485_BOOT_STM32G474VET_H #define RS485_BOOT_STM32G474VET_H #include "rs485_boot.h" diff --git a/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.c b/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.c index 6f45b92..89789b9 100644 --- a/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.c +++ b/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.c @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для TMS320F2812 через окружение RS485 и flash_tools проекта. + * Передача, запись памяти и перезапуск выполняются платформой; общий транспорт обслуживает + * команды и контроль целостности. + */ + #include "DSP281x_Device.h" #include "RS485.h" #include "flash_tools.h" diff --git a/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.h b/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.h index c163e11..b52bd42 100644 --- a/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.h +++ b/c/rs485-boot/ports/tms320f2812/rs_boot_port_f2812.h @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для TMS320F2812 через окружение RS485 и flash_tools проекта. + * Передача, запись памяти и перезапуск выполняются платформой; общий транспорт обслуживает + * команды и контроль целостности. + */ + #ifndef RS_BOOT_PORT_F2812_H #define RS_BOOT_PORT_F2812_H diff --git a/c/rs485-boot/ports/tms320f28335/rs_boot_port_config.template.h b/c/rs485-boot/ports/tms320f28335/rs_boot_port_config.template.h index 5de2e04..fdade12 100644 --- a/c/rs485-boot/ports/tms320f28335/rs_boot_port_config.template.h +++ b/c/rs485-boot/ports/tms320f28335/rs_boot_port_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация rs485-boot для порта tms320f28335. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef RS_BOOT_PORT_CONFIG_H #define RS_BOOT_PORT_CONFIG_H #include "DSP2833x_Device.h" diff --git a/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.c b/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.c index 7fd39e2..3b4c5b5 100644 --- a/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.c +++ b/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.c @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для TMS320F28335 с настраиваемым SCI. Макросы проекта выбирают + * периферию и направление RS-485; данные передаются как восьмибитные значения внутри слов + * C28x. + */ + #include "rs_boot_port_config.h" #include "rs_boot_port_f28335.h" static rsbt_t boot; diff --git a/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.h b/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.h index dd2c83b..07c0b73 100644 --- a/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.h +++ b/c/rs485-boot/ports/tms320f28335/rs_boot_port_f28335.h @@ -1,3 +1,9 @@ +/* + * Порт RS-485-загрузчика для TMS320F28335 с настраиваемым SCI. Макросы проекта выбирают + * периферию и направление RS-485; данные передаются как восьмибитные значения внутри слов + * C28x. + */ + #ifndef RS_BOOT_PORT_F28335_H #define RS_BOOT_PORT_F28335_H #include "rs_boot_transport.h" diff --git a/c/rs485-boot/src/rs485_boot.c b/c/rs485-boot/src/rs485_boot.c index a2bf615..631f13c 100644 --- a/c/rs485-boot/src/rs485_boot.c +++ b/c/rs485-boot/src/rs485_boot.c @@ -1,3 +1,9 @@ +/* + * Потоковый загрузчик по RS-485 с кадрированием, CRC32 и продолжением передачи. Автомат + * принимает части входного потока и вызывает операции Flash через порт; неполный кадр не + * является готовой командой. + */ + #include "rs485_boot.h" #include diff --git a/c/rs485-boot/tests/test_rs485_boot.c b/c/rs485-boot/tests/test_rs485_boot.c index c4ec1bb..bb4659b 100644 --- a/c/rs485-boot/tests/test_rs485_boot.c +++ b/c/rs485-boot/tests/test_rs485_boot.c @@ -1,3 +1,9 @@ +/* + * Проверки rs485_boot: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "rs485_boot.h" #include #include diff --git a/c/rtc-service/rtc_service.h b/c/rtc-service/rtc_service.h index 3edf7b5..396e4de 100644 --- a/c/rtc-service/rtc_service.h +++ b/c/rtc-service/rtc_service.h @@ -1,3 +1,9 @@ +/* + * Единое представление календарного времени и логика RTC с резервированием. Проверка полей + * календаря отделена от регистров часов и backup-памяти; аппаратные операции выполняются через + * контракт rtc_service_port. + */ + /** **************************************************************************** * @file rtc_service.h diff --git a/c/rtc-service/rtc_service_core.c b/c/rtc-service/rtc_service_core.c index d204a8c..95bb7eb 100644 --- a/c/rtc-service/rtc_service_core.c +++ b/c/rtc-service/rtc_service_core.c @@ -1,3 +1,9 @@ +/* + * Единое представление календарного времени и логика RTC с резервированием. Проверка полей + * календаря отделена от регистров часов и backup-памяти; аппаратные операции выполняются через + * контракт rtc_service_port. + */ + /** **************************************************************************** * @file rtc_service_core.c diff --git a/c/rtc-service/rtc_service_port.h b/c/rtc-service/rtc_service_port.h index cf9465d..cc58f59 100644 --- a/c/rtc-service/rtc_service_port.h +++ b/c/rtc-service/rtc_service_port.h @@ -1,3 +1,9 @@ +/* + * Граница между календарной логикой и аппаратными RTC/backup-регистрами. Порт предоставляет + * операции чтения и записи, благодаря чему ядро сервиса можно использовать с другим + * контроллером без изменения правил проверки времени. + */ + /** **************************************************************************** * @file rtc_service_port.h diff --git a/c/rtc-service/rtc_service_port_k1921vk028.c b/c/rtc-service/rtc_service_port_k1921vk028.c index bafe9eb..f1f502a 100644 --- a/c/rtc-service/rtc_service_port_k1921vk028.c +++ b/c/rtc-service/rtc_service_port_k1921vk028.c @@ -1,3 +1,9 @@ +/* + * Аппаратный порт RTC и backup-памяти K1921VK028 через plib028. Доступная реализация принимает + * выбор источника AUTO; запросы принудительного LSE/LSI возвращают неподдерживаемый режим, а + * не молча выбирают другой источник. + */ + /** **************************************************************************** * @file rtc_service_port_k1921vk028.c diff --git a/c/rtc-service/rtc_service_types.h b/c/rtc-service/rtc_service_types.h index 358bf79..b85b443 100644 --- a/c/rtc-service/rtc_service_types.h +++ b/c/rtc-service/rtc_service_types.h @@ -1,3 +1,9 @@ +/* + * Единое представление календарного времени и логика RTC с резервированием. Проверка полей + * календаря отделена от регистров часов и backup-памяти; аппаратные операции выполняются через + * контракт rtc_service_port. + */ + /** **************************************************************************** * @file rtc_service_types.h diff --git a/c/sd-file-browser/CMakeLists.txt b/c/sd-file-browser/CMakeLists.txt index 527cc11..3b117b8 100644 --- a/c/sd-file-browser/CMakeLists.txt +++ b/c/sd-file-browser/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки sd_file_browser. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(sd_file_browser C) add_library(sd_file_browser STATIC Src/sd_file_browser.c) diff --git a/c/sd-file-browser/Inc/sd_file_browser.h b/c/sd-file-browser/Inc/sd_file_browser.h index 81918fd..96a0874 100644 --- a/c/sd-file-browser/Inc/sd_file_browser.h +++ b/c/sd-file-browser/Inc/sd_file_browser.h @@ -1,3 +1,9 @@ +/* + * Просмотр файлов SD-карты через ограниченный переносимый интерфейс. Размеры пути и имени + * фиксированы контрактом; операции файловой системы предоставляет приложение, а ответ должен + * укладываться в общий формат клиента и прошивки. + */ + #ifndef SD_FILE_BROWSER_H #define SD_FILE_BROWSER_H diff --git a/c/sd-file-browser/Src/sd_file_browser.c b/c/sd-file-browser/Src/sd_file_browser.c index 6c414e2..05347ed 100644 --- a/c/sd-file-browser/Src/sd_file_browser.c +++ b/c/sd-file-browser/Src/sd_file_browser.c @@ -1,3 +1,9 @@ +/* + * Просмотр файлов SD-карты через ограниченный переносимый интерфейс. Размеры пути и имени + * фиксированы контрактом; операции файловой системы предоставляет приложение, а ответ должен + * укладываться в общий формат клиента и прошивки. + */ + #include "sd_file_browser.h" #include diff --git a/c/sd-file-browser/Tests/test_sd_file_browser.c b/c/sd-file-browser/Tests/test_sd_file_browser.c index 497d938..4b9826a 100644 --- a/c/sd-file-browser/Tests/test_sd_file_browser.c +++ b/c/sd-file-browser/Tests/test_sd_file_browser.c @@ -1,3 +1,9 @@ +/* + * Проверки sd_file_browser: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "sd_file_browser.h" #include diff --git a/c/set-protocol/CMakeLists.txt b/c/set-protocol/CMakeLists.txt index 4274aba..a69c92a 100644 --- a/c/set-protocol/CMakeLists.txt +++ b/c/set-protocol/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки setprotocol_static, set_protocol, setprotocol. Состав исходников и +# публичные include-пути задают подключение к проекту потребителя. Файл также собирает и +# регистрирует хостовые проверки; запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(setprotocol C) diff --git a/c/set-protocol/include/altera_logic.h b/c/set-protocol/include/altera_logic.h index 00136e2..4f500f7 100644 --- a/c/set-protocol/include/altera_logic.h +++ b/c/set-protocol/include/altera_logic.h @@ -1,3 +1,9 @@ +/* + * Автомат UART-клиента логического анализатора Altera: запрос, накопление ответа и контроль + * времени. Одновременно выполняется одна операция; ARM нельзя безусловно повторять, поскольку + * повторный запуск меняет состояние захвата. + */ + /** Altera logic analyzer UART client. C99, caller-owned memory, no OS/heap. * One request at a time; no automatic retries (ARM is not idempotent). * Initialize aligned storage of la_context_size() bytes, then call la_next, diff --git a/c/set-protocol/include/altera_stream.h b/c/set-protocol/include/altera_stream.h index 18c5d53..d8b1b78 100644 --- a/c/set-protocol/include/altera_stream.h +++ b/c/set-protocol/include/altera_stream.h @@ -1,3 +1,9 @@ +/* + * Приём потока выборок Altera Logic через SETCAN/GAS по CAN или UART. Счётчики выборок + * сохраняют положение во времени; получение пакетов и обновление изображения должны + * обслуживаться независимо. + */ + /** SETCAN/GAS Altera Logic online stream, shared by CAN and UART. * Caller-owned context; one serialized caller. No heap, OS or Qt dependencies. */ diff --git a/c/set-protocol/include/balsam_can.h b/c/set-protocol/include/balsam_can.h index e982fef..9d32331 100644 --- a/c/set-protocol/include/balsam_can.h +++ b/c/set-protocol/include/balsam_can.h @@ -1,3 +1,9 @@ +/* + * Исторический регистровый CAN-протокол BALZAM/TMS2812. Формат идентификаторов и порядок слов + * относятся именно к этому профилю; общий физический CAN не делает его совместимым с SET v2 + * или протоколом ПМ35. + */ + /** * @file balsam_can.h * @brief CAN_Bal_2812 extended-CAN register space. diff --git a/c/set-protocol/include/firmware_image.h b/c/set-protocol/include/firmware_image.h index 418b6d7..570be84 100644 --- a/c/set-protocol/include/firmware_image.h +++ b/c/set-protocol/include/firmware_image.h @@ -1,3 +1,9 @@ +/* + * Проверка Intel HEX и подготовка адресованного образа прошивки. Контрольные суммы записей, + * расширенные адреса и пересечения проверяются до использования результата; рабочая память + * C-парсера принадлежит вызывающему. + */ + #ifndef SET_FIRMWARE_IMAGE_H #define SET_FIRMWARE_IMAGE_H #include "pcan_abi.h" diff --git a/c/set-protocol/include/gui_catalog.h b/c/set-protocol/include/gui_catalog.h index 0dd2f9b..9e7c8e6 100644 --- a/c/set-protocol/include/gui_catalog.h +++ b/c/set-protocol/include/gui_catalog.h @@ -1,3 +1,9 @@ +/* + * Каталог объектов GUI v1 и подписка на выбранные значения. Записи каталога описывают типы, + * адреса и имена; поток наблюдения передаёт значения отдельно от описания, поэтому клиент + * должен сохранять соответствие выбранным объектам. + */ + /** * @file gui_catalog.h * @brief Каталог общего адресного пространства и поток выбранных значений. diff --git a/c/set-protocol/include/gui_frame.h b/c/set-protocol/include/gui_frame.h index 2b3d490..7b8a784 100644 --- a/c/set-protocol/include/gui_frame.h +++ b/c/set-protocol/include/gui_frame.h @@ -1,3 +1,9 @@ +/* + * Кадрирование GUI v1 с сигнатурой A5 5A и CRC32. Потоковый разбор сохраняет незавершённое + * сообщение между вызовами; готовый кадр выдаётся только после проверки длины и контрольной + * суммы. + */ + /** * @file gui_frame.h * @brief Транспорт GUI-протокола SETGUI на стороне МК. diff --git a/c/set-protocol/include/pcan_abi.h b/c/set-protocol/include/pcan_abi.h index 1417723..18ffe67 100644 --- a/c/set-protocol/include/pcan_abi.h +++ b/c/set-protocol/include/pcan_abi.h @@ -1,3 +1,9 @@ +/* + * Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры + * буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют + * согласованного обновления привязок. + */ + /** * @file pcan_abi.h * @brief Stable C ABI for desktop, Android and other foreign runtimes. diff --git a/c/set-protocol/include/pcan_config.h b/c/set-protocol/include/pcan_config.h index 5d1df61..73a8599 100644 --- a/c/set-protocol/include/pcan_config.h +++ b/c/set-protocol/include/pcan_config.h @@ -1,3 +1,9 @@ +/* + * Параметры сборки транспорта ProtoCAN: размеры и выбор реализации CRC. Они участвуют в + * компиляции ядра и потребителей заголовков; согласованность настроек важна для размеров + * структур и буферов. + */ + /** * @file pcan_config.h * @brief Настройки времени компиляции. diff --git a/c/set-protocol/include/pcan_crc.h b/c/set-protocol/include/pcan_crc.h index ac8de69..d8715ab 100644 --- a/c/set-protocol/include/pcan_crc.h +++ b/c/set-protocol/include/pcan_crc.h @@ -1,3 +1,9 @@ +/* + * CRC-16/CCITT-FALSE для транспортного кадра ProtoCAN. Табличный и побитовый варианты должны + * давать одинаковый результат; CRC считается по оговорённым байтам кадра, без добавления + * сигнатуры. + */ + /** * @file pcan_crc.h * @brief CRC-16/CCITT-FALSE: poly 0x1021, init 0xFFFF, без рефлексии, diff --git a/c/set-protocol/include/pcan_frame.h b/c/set-protocol/include/pcan_frame.h index 2c0a178..66bd163 100644 --- a/c/set-protocol/include/pcan_frame.h +++ b/c/set-protocol/include/pcan_frame.h @@ -1,3 +1,9 @@ +/* + * Преобразование CAN-кадра в поток AA 55 и обратный побайтный разбор. LEN описывает участок + * SEQ..DATA, CRC16 покрывает LEN..DATA; частичный пакет остаётся в состоянии parser до + * следующего фрагмента. + */ + /** * @file pcan_frame.h * @brief Транспортный кадр и потоковый разборщик. diff --git a/c/set-protocol/include/pcan_gas.h b/c/set-protocol/include/pcan_gas.h index 4f97dd8..312e910 100644 --- a/c/set-protocol/include/pcan_gas.h +++ b/c/set-protocol/include/pcan_gas.h @@ -1,3 +1,9 @@ +/* + * Общее адресное пространство ProtoCAN, разбитое на регионы с обработчиками чтения и записи. + * Поиск региона и проверка доступа предшествуют обращению к приложению; номер регистра не + * является адресом памяти процессора. + */ + /** * @file pcan_gas.h * @brief Общее адресное пространство (General Address Space). diff --git a/c/set-protocol/include/pcan_id.h b/c/set-protocol/include/pcan_id.h index 29f5b10..dd88b9e 100644 --- a/c/set-protocol/include/pcan_id.h +++ b/c/set-protocol/include/pcan_id.h @@ -1,3 +1,8 @@ +/* + * Явная упаковка полей в 29-битный идентификатор ProtoCAN и их извлечение. Маски и сдвиги + * задают переносимый wire-формат без зависимости от расположения битовых полей компилятора. + */ + /** * @file pcan_id.h * @brief Упаковка и разбор 29-битного идентификатора ProtoCAN. diff --git a/c/set-protocol/include/pcan_link.h b/c/set-protocol/include/pcan_link.h index 9c8cedf..613e95c 100644 --- a/c/set-protocol/include/pcan_link.h +++ b/c/set-protocol/include/pcan_link.h @@ -1,3 +1,9 @@ +/* + * Канал ProtoCAN поверх произвольного потока байтов. Контекст хранит parser и параметры + * отправки; физический ввод-вывод подключается обратными вызовами, а готовые CAN-кадры + * передаются обработчику приложения. + */ + /** * @file pcan_link.h * @brief Экземпляр канала связи поверх произвольного байтового потока. diff --git a/c/set-protocol/include/pcan_modbus_server.h b/c/set-protocol/include/pcan_modbus_server.h index a8e4c01..0552d22 100644 --- a/c/set-protocol/include/pcan_modbus_server.h +++ b/c/set-protocol/include/pcan_modbus_server.h @@ -1,3 +1,9 @@ +/* + * Доступ к окнам Modbus-регистров через один classic CAN-кадр ProtoCAN. Сервер сопоставляет + * команду с банком и диапазоном регистров; чтение и запись значений выполняет предоставленный + * приложением интерфейс. + */ + /** * @file pcan_modbus_server.h * @brief Modbus register windows transported in one classic ProtoCAN frame. diff --git a/c/set-protocol/include/pcan_ring.h b/c/set-protocol/include/pcan_ring.h index b02cd5a..79c4ddb 100644 --- a/c/set-protocol/include/pcan_ring.h +++ b/c/set-protocol/include/pcan_ring.h @@ -1,3 +1,9 @@ +/* + * Кольцевая очередь байтов для одного производителя и одного потребителя. Размер хранилища + * должен быть степенью двойки; одна позиция резервируется для различения пустого и полного + * состояния. + */ + /** * @file pcan_ring.h * @brief Кольцевой буфер байтов: один писатель, один читатель. diff --git a/c/set-protocol/include/periph28335.h b/c/set-protocol/include/periph28335.h index 408353e..a9b3010 100644 --- a/c/set-protocol/include/periph28335.h +++ b/c/set-protocol/include/periph28335.h @@ -1,3 +1,9 @@ +/* + * Протокол периферийного контроллера ПМ35/TMS320F28335: регистры, команды и разбор ответов. + * Этот профиль имеет собственную адресацию и не должен подменяться протоколом основного + * TMS320F2812. + */ + /** * @file periph28335.h * @brief Shared PM35/TMS320F28335 register protocol. diff --git a/c/set-protocol/include/protocan_transport.h b/c/set-protocol/include/protocan_transport.h index bd9090c..34084ae 100644 --- a/c/set-protocol/include/protocan_transport.h +++ b/c/set-protocol/include/protocan_transport.h @@ -1,3 +1,9 @@ +/* + * Общий заголовок подключения библиотеки протокола. Он собирает публичные определения в одной + * точке; конкретные контракты кадров, буферов и кодов ошибок описаны в подключаемых + * специализированных заголовках. + */ + /** * @file protocan_transport.h * @brief Зонтичный заголовок библиотеки. Достаточно подключить его одного. diff --git a/c/set-protocol/include/set_boot.h b/c/set-protocol/include/set_boot.h index 2b5ac4d..d8e7fc9 100644 --- a/c/set-protocol/include/set_boot.h +++ b/c/set-protocol/include/set_boot.h @@ -1,3 +1,9 @@ +/* + * Транспортно-независимый односекционный обновитель прошивки. Признак валидности снимается до + * стирания, а commit вызывается после проверки записанного образа чтением; порядок операций + * нужен для восстановления после прерывания питания. + */ + #ifndef SET_BOOT_H #define SET_BOOT_H #include "set_firmware.h" diff --git a/c/set-protocol/include/set_can.h b/c/set-protocol/include/set_can.h index 9931542..47f704d 100644 --- a/c/set-protocol/include/set_can.h +++ b/c/set-protocol/include/set_can.h @@ -1,3 +1,9 @@ +/* + * Сегментация SET v2 и интерпретация CAN-данных зависят от выбранного слоя. Адрес и номер + * сегмента должны проверяться до объединения данных; classic CAN-пакет ограничен восемью + * байтами. + */ + #ifndef SET_CAN_H #define SET_CAN_H diff --git a/c/set-protocol/include/set_crc.h b/c/set-protocol/include/set_crc.h index efa9cf0..1ca765f 100644 --- a/c/set-protocol/include/set_crc.h +++ b/c/set-protocol/include/set_crc.h @@ -1,3 +1,9 @@ +/* + * Общие контрольные суммы исторических протоколов SET. Алгоритмы с разными полиномами, + * начальными значениями и отражением битов не взаимозаменяемы, даже если возвращают одинаковый + * по ширине целый тип. + */ + /** @file set_crc.h @brief Shared checksums used by legacy SET controllers. */ #ifndef SET_CRC_H #define SET_CRC_H diff --git a/c/set-protocol/include/set_emu_igbt.h b/c/set-protocol/include/set_emu_igbt.h index 45e4b76..5709b66 100644 --- a/c/set-protocol/include/set_emu_igbt.h +++ b/c/set-protocol/include/set_emu_igbt.h @@ -1,3 +1,9 @@ +/* + * Модель каналов IGBT для стенда: входные состояния, задержки и сформированные выходы. Логика + * времени отделена от аппаратного порта; модель предназначена для воспроизводимого обмена с + * эмулятором. + */ + #ifndef SET_EMU_IGBT_H #define SET_EMU_IGBT_H #include "set_regmap.h" diff --git a/c/set-protocol/include/set_emu_server.h b/c/set-protocol/include/set_emu_server.h index 6d18842..c87a7b3 100644 --- a/c/set-protocol/include/set_emu_server.h +++ b/c/set-protocol/include/set_emu_server.h @@ -1,3 +1,9 @@ +/* + * Эталонная композиция сервисов эмулятора: УМП, TMS, IGBT и генератор сигналов. Общая карта + * регистров маршрутизирует обращения; другой продукт может составить собственную карту через + * set_regmap. + */ + /* Reference service composition for emulator boards; use set_regmap directly * for a different map, subset, or multiple instances of any module. */ #ifndef SET_EMU_SERVER_H diff --git a/c/set-protocol/include/set_emu_tms.h b/c/set-protocol/include/set_emu_tms.h index 0f640b1..a979b25 100644 --- a/c/set-protocol/include/set_emu_tms.h +++ b/c/set-protocol/include/set_emu_tms.h @@ -1,3 +1,9 @@ +/* + * Модель ответов TMS для эмулятора контроллера. Синтетические аналоговые и дискретные значения + * упаковываются в ожидаемый формат терминала, чтобы проверять клиент без подключения рабочего + * контроллера. + */ + #ifndef SET_EMU_TMS_H #define SET_EMU_TMS_H #include "set_regmap.h" diff --git a/c/set-protocol/include/set_emu_ump.h b/c/set-protocol/include/set_emu_ump.h index 492bd84..bc3fb6b 100644 --- a/c/set-protocol/include/set_emu_ump.h +++ b/c/set-protocol/include/set_emu_ump.h @@ -1,3 +1,9 @@ +/* + * Синтетические сигналы УМП и регистратор эмулятора. Хранилище предоставляет вызывающий код; + * обновление модели и выдача записей разделены, чтобы клиент мог получать воспроизводимые + * снимки. + */ + #ifndef SET_EMU_UMP_H #define SET_EMU_UMP_H #include "set_regmap.h" diff --git a/c/set-protocol/include/set_firmware.h b/c/set-protocol/include/set_firmware.h index 521d7d4..87060ce 100644 --- a/c/set-protocol/include/set_firmware.h +++ b/c/set-protocol/include/set_firmware.h @@ -1,3 +1,9 @@ +/* + * Кодирование метаданных и сообщений обновления SETProtocol v2. Размер образа, совместимость и + * параметры начала передачи передаются явно; сериализация команды сама по себе не выполняет + * запись Flash. + */ + #ifndef SET_FIRMWARE_H #define SET_FIRMWARE_H diff --git a/c/set-protocol/include/set_plot.h b/c/set-protocol/include/set_plot.h index 8e0b006..ed91f87 100644 --- a/c/set-protocol/include/set_plot.h +++ b/c/set-protocol/include/set_plot.h @@ -1,3 +1,9 @@ +/* + * Математика взаимодействия с графиком: области просмотра, масштабирование, перемещение и + * координатные преобразования. Расчёты общие для JNI и ctypes; цвета, события GUI и рисование + * остаются в приложении. + */ + /** @file set_plot.h * @brief Toolkit-independent plot interaction math shared by JNI and ctypes. * Coordinates are doubles in the caller's units. No allocation or global state. diff --git a/c/set-protocol/include/set_protocol.h b/c/set-protocol/include/set_protocol.h index 34e7992..de60f9c 100644 --- a/c/set-protocol/include/set_protocol.h +++ b/c/set-protocol/include/set_protocol.h @@ -1,3 +1,9 @@ +/* + * Основной бинарный формат SETProtocol v2: поля кадра, контрольная сумма и потоковый parser. + * Числа сериализуются явно, поэтому выравнивание C-структур не влияет на байты линии; + * транспорт передаёт готовые массивы. + */ + #ifndef SET_PROTOCOL_H #define SET_PROTOCOL_H diff --git a/c/set-protocol/include/set_regmap.h b/c/set-protocol/include/set_regmap.h index a94677b..b6c1083 100644 --- a/c/set-protocol/include/set_regmap.h +++ b/c/set-protocol/include/set_regmap.h @@ -1,3 +1,9 @@ +/* + * Транспортно-независимая карта 16-битных регистров с отдельными регионами и обработчиками. + * Проверка диапазонов и прав доступа выполняется до вызова сервиса; относительное смещение + * региона отличается от общего адреса. + */ + /* Transport-independent 16-bit word address space. No heap, clocks or board headers. */ #ifndef SET_REGMAP_H #define SET_REGMAP_H diff --git a/c/set-protocol/include/set_signal.h b/c/set-protocol/include/set_signal.h index a27fcd2..5626c97 100644 --- a/c/set-protocol/include/set_signal.h +++ b/c/set-protocol/include/set_signal.h @@ -1,3 +1,9 @@ +/* + * Восстановление сигнала по точкам и подготовка кодов 12-битного ЦАП. Совпадающие времена + * усредняются, экстраполяция не выполняется; для циклического периода конечная точка + * обрабатывается отдельно. Напряжения вне диапазона отклоняются, а не обрезаются. + */ + /** @file set_signal.h Portable interpolation and DAC waveform preparation. */ #ifndef SET_SIGNAL_H #define SET_SIGNAL_H diff --git a/c/set-protocol/include/set_spectrum.h b/c/set-protocol/include/set_spectrum.h index 8747924..5fd76a4 100644 --- a/c/set-protocol/include/set_spectrum.h +++ b/c/set-protocol/include/set_spectrum.h @@ -1,3 +1,9 @@ +/* + * Общий расчёт FFT: оценка частоты дискретизации по времени, ресемплинг, фильтр, окно и + * спектр. Выход — односторонняя пиковая амплитуда; DC и частота Найквиста не удваиваются. + * Временные метки задаются в секундах. + */ + /** Shared host-side FFT for Android/JNI and desktop/ctypes; no GUI dependencies. */ #ifndef SET_SPECTRUM_H #define SET_SPECTRUM_H diff --git a/c/set-protocol/include/set_telemetry.h b/c/set-protocol/include/set_telemetry.h index d945714..3b40590 100644 --- a/c/set-protocol/include/set_telemetry.h +++ b/c/set-protocol/include/set_telemetry.h @@ -1,3 +1,9 @@ +/* + * Сообщения подписки и телеметрии SETProtocol v2. Период, идентификатор подписки и перечень + * адресов сериализуются отдельно от значений; получатель должен связывать поток с + * соответствующей подпиской. + */ + #ifndef SET_TELEMETRY_H #define SET_TELEMETRY_H diff --git a/c/set-protocol/include/set_trends.h b/c/set-protocol/include/set_trends.h index b187f0c..ec5d5c0 100644 --- a/c/set-protocol/include/set_trends.h +++ b/c/set-protocol/include/set_trends.h @@ -1,3 +1,9 @@ +/* + * Общий разбор числовых источников трендов, включая GAS и raw CAN. Знаковость слова, смещение + * и коэффициент преобразования относятся к описанию сигнала; визуальная история графика + * хранится на стороне клиента. + */ + /** @file set_trends.h * @brief Shared GUI trend decoding and GUI v1 GAS subscription payloads. * No transport, rendering, allocation or global state. JNI/ctypes call the diff --git a/c/set-protocol/include/set_wavegen.h b/c/set-protocol/include/set_wavegen.h index 06bbce7..7ca876c 100644 --- a/c/set-protocol/include/set_wavegen.h +++ b/c/set-protocol/include/set_wavegen.h @@ -1,3 +1,9 @@ +/* + * Транзакционная загрузка таблицы и циклическое воспроизведение через ЦАП. Блоки принимаются + * до commit, а запуск использует согласованную таблицу; порт stop должен остановить DMA до + * возврата и освободить использование массива. + */ + /** @file set_wavegen.h Transactional table upload and cyclic DAC playback. */ #ifndef SET_WAVEGEN_H #define SET_WAVEGEN_H diff --git a/c/set-protocol/include/setprotocol.h b/c/set-protocol/include/setprotocol.h index 793f782..6cf501f 100644 --- a/c/set-protocol/include/setprotocol.h +++ b/c/set-protocol/include/setprotocol.h @@ -1,3 +1,9 @@ +/* + * Общий заголовок подключения библиотеки протокола. Он собирает публичные определения в одной + * точке; конкретные контракты кадров, буферов и кодов ошибок описаны в подключаемых + * специализированных заголовках. + */ + /** * @file setprotocol.h * @brief Единственная C99-точка включения полного SETProtocol. diff --git a/c/set-protocol/include/setprotocol_abi.h b/c/set-protocol/include/setprotocol_abi.h index ce7b48a..abb2bc1 100644 --- a/c/set-protocol/include/setprotocol_abi.h +++ b/c/set-protocol/include/setprotocol_abi.h @@ -1,3 +1,9 @@ +/* + * Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры + * буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют + * согласованного обновления привязок. + */ + /** * @file setprotocol_abi.h * @brief Стабильная FFI-граница SETProtocol ABI v1. diff --git a/c/set-protocol/include/tms2812.h b/c/set-protocol/include/tms2812.h index a2a25df..68a5631 100644 --- a/c/set-protocol/include/tms2812.h +++ b/c/set-protocol/include/tms2812.h @@ -1,3 +1,9 @@ +/* + * Исторический протокол основного контроллера ПМ67/TMS320F2812. Формирование команд и проверка + * ответов находятся в общем ядре; адреса памяти C28x считаются словами, тогда как длины + * передачи могут задаваться байтами. + */ + /** * @file tms2812.h * @brief Shared PM67/TMS320F2812 legacy terminal and memory protocol. diff --git a/c/set-protocol/include/ump_protocol.h b/c/set-protocol/include/ump_protocol.h index 2cee035..fbb27cf 100644 --- a/c/set-protocol/include/ump_protocol.h +++ b/c/set-protocol/include/ump_protocol.h @@ -1,3 +1,8 @@ +/* + * Регистровый протокол УМП для UART/CAN с общей проверкой функций и диапазонов. Октеты + * извлекаются явно, чтобы формат оставался одинаковым на восьмибитных и C28x-платформах. + */ + /* UMP logger v2 (PM35), independent of PM67 and SET protocol v2. * Octets use 16-bit storage: C28x has CHAR_BIT=16 and no uint8_t. * All lengths below count wire octets or register words, never sizeof bytes. diff --git a/c/set-protocol/ports/android/Android.mk b/c/set-protocol/ports/android/Android.mk index 530093f..de1ba13 100644 --- a/c/set-protocol/ports/android/Android.mk +++ b/c/set-protocol/ports/android/Android.mk @@ -1,3 +1,6 @@ +# Сборка общей библиотеки SETProtocol средствами Android NDK. C-ядро и JNI-обёртки входят в +# один модуль; список исходников должен включать реализации всех native-методов Kotlin. + LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/CanBridgeProtocol.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/CanBridgeProtocol.kt index 103f7fd..bcfb281 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/CanBridgeProtocol.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/CanBridgeProtocol.kt @@ -1,3 +1,8 @@ +/* + * Kotlin-модель обмена с мостом CAN/RS485. Преобразование wire-кадров делегируется общему + * ядру; пользовательский интерфейс получает типизированные поля, не зависящие от JNI-массивов. + */ + package ru.setcorp.setflash.core import ru.setcorp.setprotocol.NativeSetProtocol as NativeProtoCan diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/GuiProtocol.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/GuiProtocol.kt index 43faf5b..5527849 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/GuiProtocol.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/GuiProtocol.kt @@ -1,3 +1,9 @@ +/* + * Кадрирование исторического GUI protocol v1. Parser накапливает части входного потока и + * проверяет сообщение до выдачи результата; этот формат следует выбирать по профилю + * соединения, а не только по сигнатуре. + */ + package ru.setcorp.setflash.core import java.util.zip.CRC32 diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/ProtoCanCatalog.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/ProtoCanCatalog.kt index 385865f..00dc1ab 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/ProtoCanCatalog.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/ProtoCanCatalog.kt @@ -1,3 +1,8 @@ +/* + * Общий каталог типов сообщений ProtoCAN для Android-клиентов. Числовые коды являются частью + * протокола; подписи служат отображению и не должны использоваться вместо кодов в обмене. + */ + package ru.setcorp.setflash.core /** Canonical ProtoCAN message-type registry shared by Android protocol clients. */ diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/Tms2812Protocol.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/Tms2812Protocol.kt index 58cbfd6..668606c 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/Tms2812Protocol.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/Tms2812Protocol.kt @@ -1,3 +1,8 @@ +/* + * Kotlin-фасад протокола BALZAM/TMS320F2812. Кадрирование и контрольные суммы выполняет + * C99-ядро через NativeSetProtocol; модели Kotlin описывают аргументы и результаты операций. + */ + package ru.setcorp.setflash.core import ru.setcorp.setprotocol.NativeSetProtocol diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/NativeSetProtocol.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/NativeSetProtocol.kt index f910841..cab62ec 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/NativeSetProtocol.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/NativeSetProtocol.kt @@ -1,3 +1,8 @@ +/* + * Kotlin-объявления JNI-вызовов общего SETProtocol. Порядок и типы аргументов должны совпадать + * с setprotocol_jni.c; библиотека должна содержать все объявленные нативные символы. + */ + package ru.setcorp.setprotocol /** Thin Kotlin facade over the shared C99 SETProtocol core. */ diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/balsam/BalsamCanProtocol.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/balsam/BalsamCanProtocol.kt index 542813a..2d9a488 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/balsam/BalsamCanProtocol.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/balsam/BalsamCanProtocol.kt @@ -1,3 +1,8 @@ +/* + * Android-представление исторического CAN-протокола BALZAM. Код связывает Kotlin-модели с + * общим ядром; регистры и формат идентификаторов не относятся к протоколу ПМ35. + */ + package ru.setcorp.setprotocol.balsam import ru.setcorp.setprotocol.NativeSetProtocol diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/legacycan/LegacyCanTerminal.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/legacycan/LegacyCanTerminal.kt index 0a3cf26..2886744 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/legacycan/LegacyCanTerminal.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/legacycan/LegacyCanTerminal.kt @@ -1,3 +1,9 @@ +/* + * Android-модель исторического CAN-терминала и выбора проекта. Каталог определяет семантику + * команд, а транспорт только доставляет CAN-кадры; UI не должен создавать собственную копию + * wire-формата. + */ + package ru.setcorp.setprotocol.legacycan /** Wire formats implemented by the historical CAN_terminal application. */ diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/periph28335/Periph28335Protocol.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/periph28335/Periph28335Protocol.kt index 0856830..1fa2ba6 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/periph28335/Periph28335Protocol.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/periph28335/Periph28335Protocol.kt @@ -1,3 +1,8 @@ +/* + * Android-фасад отдельного протокола ПМ35/TMS320F28335. Запросы и ответы преобразуются через + * общее ядро; профиль периферийного контроллера сохраняется отдельно от TMS320F2812. + */ + package ru.setcorp.setprotocol.periph28335 import ru.setcorp.setprotocol.NativeSetProtocol diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/GuiGasWatch.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/GuiGasWatch.kt index 924ed9c..66ffa48 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/GuiGasWatch.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/GuiGasWatch.kt @@ -1,3 +1,9 @@ +/* + * Android-поддержка наблюдения за объектами GAS через GUI-протокол. Подписка связывает список + * выбранных адресов с поступающими значениями; смена выбора требует согласования состояния + * клиента. + */ + package ru.setcorp.setprotocol.trends import ru.setcorp.setprotocol.NativeSetProtocol diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/NativePlot.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/NativePlot.kt index 1ce5a53..772f747 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/NativePlot.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/NativePlot.kt @@ -1,3 +1,9 @@ +/* + * Адаптер общей математики графика из set_plot.c. Область просмотра и координатные + * преобразования рассчитываются ядром; приложение отвечает за единицы, получение измерений и + * отрисовку. + */ + package ru.setcorp.setprotocol.trends /** Shared C99 plot math, also used by the Python/Qt port. No UI dependency. */ diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/PlotViewport.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/PlotViewport.kt index 7ec4442..1a621d6 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/PlotViewport.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/PlotViewport.kt @@ -1,3 +1,8 @@ +/* + * Модель области просмотра графика для Android. Границы и преобразования координат связывают + * жесты интерфейса с общей математикой; изменение видимой области не меняет измеренные данные. + */ + package ru.setcorp.setprotocol.trends /** Normalized top-left viewport; independent of pixels, units, toolkit and samples. */ diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendDecoder.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendDecoder.kt index 6173d96..f5dd747 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendDecoder.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendDecoder.kt @@ -1,3 +1,8 @@ +/* + * Android-адаптер декодирования источников трендов. Сырые данные интерпретируются по типу + * источника и его параметрам, а результаты передаются модели отображения в числовом виде. + */ + package ru.setcorp.setprotocol.trends import ru.setcorp.setprotocol.NativeSetProtocol diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendMarkers.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendMarkers.kt index 57dabf6..b4c25be 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendMarkers.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendMarkers.kt @@ -1,3 +1,9 @@ +/* + * Состояние измерительных маркеров и линеек графика. Маркер относится к координатам + * отображаемого сигнала; его перемещение не изменяет полученные выборки или настройки + * транспорта. + */ + package ru.setcorp.setprotocol.trends import kotlin.math.abs diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendModels.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendModels.kt index 54bc95a..da6fb1d 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendModels.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendModels.kt @@ -1,3 +1,9 @@ +/* + * Модели источников и настроек трендов, используемые клиентскими приложениями. Идентификатор + * сигнала связывает историю с источником независимо от имени и порядка; визуальное + * переименование не должно менять физический источник. + */ + package ru.setcorp.setprotocol.trends import java.util.UUID diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSettingsJson.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSettingsJson.kt index 763eb2c..85fab1b 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSettingsJson.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSettingsJson.kt @@ -1,3 +1,9 @@ +/* + * Чтение и запись общего JSON-контракта настроек трендов. Стабильные идентификаторы и версия + * формата нужны для обмена настройками между Android и Python; UI-порядок не заменяет + * идентичность сигнала. + */ + package ru.setcorp.setprotocol.trends import org.json.JSONArray diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSpectrum.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSpectrum.kt index cf8679c..57b94ff 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSpectrum.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/TrendSpectrum.kt @@ -1,3 +1,9 @@ +/* + * Привязка общего расчёта спектра C99 к клиенту. Входные временные метки задаются в секундах; + * частота дискретизации и нормировка определяются ядром, поэтому отображение не должно + * повторно нормировать амплитуды. + */ + package ru.setcorp.setprotocol.trends import ru.setcorp.setprotocol.NativeSetProtocol diff --git a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/update/FirmwareCatalog.kt b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/update/FirmwareCatalog.kt index 1148676..83211e5 100644 --- a/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/update/FirmwareCatalog.kt +++ b/c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/update/FirmwareCatalog.kt @@ -1,3 +1,9 @@ +/* + * Модель каталога firmware.releases и проверка записей update.json. Метаданные выпуска + * описывают совместимость и расположение образа; выбор записи и последующее скачивание + * являются отдельными операциями. + */ + package ru.setcorp.setprotocol.update import android.util.Base64 diff --git a/c/set-protocol/ports/android/set_plot_jni.c b/c/set-protocol/ports/android/set_plot_jni.c index 9e60651..033e0b6 100644 --- a/c/set-protocol/ports/android/set_plot_jni.c +++ b/c/set-protocol/ports/android/set_plot_jni.c @@ -1,3 +1,9 @@ +/* + * Граница JNI между Kotlin и общим C-ядром. Массивы и примитивные значения Java преобразуются + * в аргументы C; полученные через JNI указатели имеют ограниченное время жизни и должны + * освобождаться по правилам JNI. + */ + #include #include "set_plot.h" diff --git a/c/set-protocol/ports/android/setprotocol_jni.c b/c/set-protocol/ports/android/setprotocol_jni.c index c786d93..1d9c264 100644 --- a/c/set-protocol/ports/android/setprotocol_jni.c +++ b/c/set-protocol/ports/android/setprotocol_jni.c @@ -1,3 +1,9 @@ +/* + * Граница JNI между Kotlin и общим C-ядром. Массивы и примитивные значения Java преобразуются + * в аргументы C; полученные через JNI указатели имеют ограниченное время жизни и должны + * освобождаться по правилам JNI. + */ + #include #include #include diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/ProtoCanCatalogTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/ProtoCanCatalogTest.kt index 4b682d5..4cbc58e 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/ProtoCanCatalogTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/ProtoCanCatalogTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки ProtoCanCatalog: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setflash.core import org.junit.Assert.assertEquals diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/TmsTerminalSharedTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/TmsTerminalSharedTest.kt index 6fa2097..71f65b2 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/TmsTerminalSharedTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setflash/core/TmsTerminalSharedTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки TmsTerminalShared: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setflash.core import org.junit.Assert.* diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/balsam/BalsamCanProtocolTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/balsam/BalsamCanProtocolTest.kt index 7e536cc..fc82705 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/balsam/BalsamCanProtocolTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/balsam/BalsamCanProtocolTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки BalsamCanProtocol: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.balsam import org.junit.Assert.assertEquals diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/legacycan/LegacyCanTerminalTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/legacycan/LegacyCanTerminalTest.kt index a4c63c0..e03199c 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/legacycan/LegacyCanTerminalTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/legacycan/LegacyCanTerminalTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки LegacyCanTerminal: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.legacycan import org.junit.Assert.assertEquals diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/periph28335/Periph28335ProtocolTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/periph28335/Periph28335ProtocolTest.kt index 93b7ef0..e110a53 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/periph28335/Periph28335ProtocolTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/periph28335/Periph28335ProtocolTest.kt @@ -1,3 +1,10 @@ +/* + * Проверки Periph28335Protocol: фиксируют ожидаемое поведение на воспроизводимых входных + * данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.periph28335 import org.junit.Assert.assertEquals diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/GuiGasWatchTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/GuiGasWatchTest.kt index cfa281d..6c67c50 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/GuiGasWatchTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/GuiGasWatchTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки GuiGasWatch: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.trends import org.junit.Assert.* diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotContractTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotContractTest.kt index 024b85b..cf84ca9 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotContractTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotContractTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки PlotContract: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.trends import org.json.JSONObject diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotViewportTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotViewportTest.kt index af6962b..93c7991 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotViewportTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/PlotViewportTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки PlotViewport: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.trends import org.junit.Assert.* diff --git a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/TrendSettingsJsonTest.kt b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/TrendSettingsJsonTest.kt index 3a1c6ec..d234a49 100644 --- a/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/TrendSettingsJsonTest.kt +++ b/c/set-protocol/ports/android/tests/ru/setcorp/setprotocol/trends/TrendSettingsJsonTest.kt @@ -1,3 +1,9 @@ +/* + * Проверки TrendSettingsJson: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + package ru.setcorp.setprotocol.trends import org.json.JSONObject diff --git a/c/set-protocol/ports/example-emulator/service.c b/c/set-protocol/ports/example-emulator/service.c index 15890cc..72e8df7 100644 --- a/c/set-protocol/ports/example-emulator/service.c +++ b/c/set-protocol/ports/example-emulator/service.c @@ -1,3 +1,9 @@ +/* + * Пример композиции сервисов эмулятора поверх общей карты регистров. Он показывает подключение + * контекста приложения к переносимому обработчику, а не задаёт обязательную карту для всех + * устройств. + */ + /* Minimal board-independent composition. This compiles without any MCU headers. * Adapt these entry points to the selected board's network/USB/UART/CAN port. * Run every call in one task (or protect the entire call with the same lock). */ diff --git a/c/set-protocol/ports/stm32-bxcan/protocan.c b/c/set-protocol/ports/stm32-bxcan/protocan.c index 153320d..eef7c68 100644 --- a/c/set-protocol/ports/stm32-bxcan/protocan.c +++ b/c/set-protocol/ports/stm32-bxcan/protocan.c @@ -1,3 +1,9 @@ +/* + * Прикладной ProtoCAN-порт STM32 bxCAN с совместимым API PROTOCAN. Контекст прошивки + * поставляет HAL и настройки периферии; упаковка идентификатора опирается на общее ядро + * pcan_id. + */ + #include "protocan.h" ProtoCanDevice_t CurrentDevice; diff --git a/c/set-protocol/ports/stm32-bxcan/protocan.h b/c/set-protocol/ports/stm32-bxcan/protocan.h index ea07e45..2fac9b8 100644 --- a/c/set-protocol/ports/stm32-bxcan/protocan.h +++ b/c/set-protocol/ports/stm32-bxcan/protocan.h @@ -1,3 +1,8 @@ +/* + * Публичный интерфейс прикладного ProtoCAN для STM32 bxCAN. Объявления сохраняют исторические + * имена PROTOCAN; конфигурацию CAN и зависимые HAL-типы предоставляет проект прошивки. + */ + //тест #ifndef _protocan diff --git a/c/set-protocol/ports/stm32-usb-boot/boot_usb_protocol.inc b/c/set-protocol/ports/stm32-usb-boot/boot_usb_protocol.inc index 7784fb0..5d91861 100644 --- a/c/set-protocol/ports/stm32-usb-boot/boot_usb_protocol.inc +++ b/c/set-protocol/ports/stm32-usb-boot/boot_usb_protocol.inc @@ -1,3 +1,9 @@ +/* + * Обслуживание SETProtocol v2 поверх USB CDC для загрузчика. Поток USB разбирается на полные + * команды, после чего операции передаются общему автомату обновления; граница USB-пакета не + * является границей SET-кадра. + */ + /* Shared SET USB boot dispatcher. The MCU wrapper supplies BOOT_* macros. */ #include "usb_setp_stream.h" #include diff --git a/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.c b/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.c index f2e4c39..875e6bc 100644 --- a/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.c +++ b/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.c @@ -1,3 +1,9 @@ +/* + * UART/DMA-порт ProtoCAN для STM32F4 с управлением направлением RS-485. Флаги DMA зависят от + * номера stream; перед перенастройкой требуется дождаться фактического снятия EN, а не только + * записать ноль в регистр. + */ + #include #include "pcan_uart_stm32f4.h" diff --git a/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.h b/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.h index 933cf19..4e8a1a5 100644 --- a/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.h +++ b/c/set-protocol/ports/stm32f4/pcan_uart_stm32f4.h @@ -1,3 +1,9 @@ +/* + * UART/DMA-порт ProtoCAN для STM32F4 с управлением направлением RS-485. Флаги DMA зависят от + * номера stream; перед перенастройкой требуется дождаться фактического снятия EN, а не только + * записать ноль в регистр. + */ + /** * @file pcan_uart_stm32f4.h * @brief Порт транспорта на USART + DMA для STM32F4. diff --git a/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.c b/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.c index 2566f87..113ee54 100644 --- a/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.c +++ b/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.c @@ -1,3 +1,9 @@ +/* + * Обслуживание Modbus-регистров F407 через CAN485 DevBoard_V1. Порт опрашивает bxCAN FIFO0, + * передаёт запросы серверу регистров и учитывает ошибки отправки; необработанные кадры можно + * передать обработчику приложения. + */ + #include "set_devboard_v1_stm32f407.h" static bool transmit(set_devboard_v1_stm32f407_t *port, diff --git a/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.h b/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.h index 862154d..4cde4b9 100644 --- a/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.h +++ b/c/set-protocol/ports/stm32f407-devboard-v1/set_devboard_v1_stm32f407.h @@ -1,3 +1,9 @@ +/* + * Обслуживание Modbus-регистров F407 через CAN485 DevBoard_V1. Порт опрашивает bxCAN FIFO0, + * передаёт запросы серверу регистров и учитывает ошибки отправки; необработанные кадры можно + * передать обработчику приложения. + */ + /** STM32F407 bxCAN port for SETGUI through CAN485 DevBoard_V1. */ #ifndef SET_DEVBOARD_V1_STM32F407_H #define SET_DEVBOARD_V1_STM32F407_H diff --git a/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.c b/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.c index 5c97d87..2faf525 100644 --- a/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.c +++ b/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.c @@ -1,3 +1,9 @@ +/* + * STM32F407-порт периферийного протокола УМП. Адаптирует аппаратный обмен и регистровое + * состояние к общему ump_protocol; таблица доступных регистров и конфигурация периферии + * относятся к проекту платы. + */ + #include "ump_stm32f407.h" size_t ump_stm32f407_rtu(const ump_backend *b, unsigned device, const uint8_t *request, size_t length, uint8_t *reply, size_t capacity) diff --git a/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.h b/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.h index c9351dc..19fd5fd 100644 --- a/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.h +++ b/c/set-protocol/ports/stm32f407-periph/ump_stm32f407.h @@ -1,3 +1,9 @@ +/* + * STM32F407-порт периферийного протокола УМП. Адаптирует аппаратный обмен и регистровое + * состояние к общему ump_protocol; таблица доступных регистров и конфигурация периферии + * относятся к проекту платы. + */ + #ifndef UMP_STM32F407_H #define UMP_STM32F407_H #include "../../include/ump_protocol.h" diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_config.template.h b/c/set-protocol/ports/stm32f407-usb-boot/boot_config.template.h index 3ad3c59..aa58f6e 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_config.template.h +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_config.template.h @@ -1,3 +1,9 @@ +/* + * Конфигурация set-protocol для порта stm32f407-usb-boot. Макросы задают параметры сборки и + * ограничения, используемые исходниками этого модуля. Это образец для проекта: значения + * выводов, размеров памяти и параметров устройства необходимо согласовать с целевой платой. + */ + #ifndef F407_BOOT_CONFIG_H #define F407_BOOT_CONFIG_H /* Copy to the board include directory as boot_config.h. diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_flash.c b/c/set-protocol/ports/stm32f407-usb-boot/boot_flash.c index 63a65f7..c4e65c9 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_flash.c +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_flash.c @@ -1,3 +1,9 @@ +/* + * Аппаратные операции Flash односекционного USB-загрузчика: стирание, запись, проверка и + * фиксация образа. Геометрия разделов берётся из конфигурации платы; признак завершения нельзя + * записывать до успешной проверки данных. + */ + /* Flash geometry and jump sequence derived from climate's F407 bootloader. * Sector 3 is a durable commit record; sectors 4..7 hold the application. * Reset checks vectors like climate; USB END always verifies Flash. */ diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_image.h b/c/set-protocol/ports/stm32f407-usb-boot/boot_image.h index 0988055..c23b44d 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_image.h +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_image.h @@ -1,3 +1,9 @@ +/* + * Проверки образа перед передачей управления приложению. Адрес стека и вектор сброса должны + * соответствовать памяти целевой платы; наличие байтов во Flash само по себе не означает + * готовность образа к запуску. + */ + #ifndef F407_BOOT_IMAGE_H #define F407_BOOT_IMAGE_H #include "boot_port.h" diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_main.c b/c/set-protocol/ports/stm32f407-usb-boot/boot_main.c index ad6f4fd..e4a8540 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_main.c +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_main.c @@ -1,3 +1,9 @@ +/* + * Старт USB-загрузчика и выбор между обслуживанием обновления и запуском приложения. Здесь + * настраиваются аппаратные часы и цикл обслуживания; код выполняется в окружении конкретного + * MCU. + */ + #include "stm32f4xx_hal.h" #include "boot_config.h" #include "usb_cdc.h" diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_port.h b/c/set-protocol/ports/stm32f407-usb-boot/boot_port.h index dc562ef..943b5a2 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_port.h +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_port.h @@ -1,3 +1,9 @@ +/* + * Контракт аппаратного USB-загрузчика: доступ к образу, запрос перезапуска и операции Flash. + * Его реализация зависит от семейства MCU, тогда как последовательность обновления задаётся + * общим set_boot. + */ + #ifndef F407_BOOT_PORT_H #define F407_BOOT_PORT_H #include "set_boot.h" diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_request.c b/c/set-protocol/ports/stm32f407-usb-boot/boot_request.c index c0a2f46..b401b9b 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_request.c +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_request.c @@ -1,3 +1,8 @@ +/* + * Передача запроса входа в загрузчик через backup-состояние и отложенный сброс. Флаг должен + * пережить перезапуск, чтобы загрузчик отличил обновление от обычного старта приложения. + */ + #include "boot_port.h" #include "stm32f4xx_hal.h" #define REQUEST_MAGIC 0x42555342UL diff --git a/c/set-protocol/ports/stm32f407-usb-boot/boot_usb_stream.c b/c/set-protocol/ports/stm32f407-usb-boot/boot_usb_stream.c index 017296d..6ab81f3 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/boot_usb_stream.c +++ b/c/set-protocol/ports/stm32f407-usb-boot/boot_usb_stream.c @@ -1,3 +1,9 @@ +/* + * Обслуживание SETProtocol v2 поверх USB CDC для загрузчика. Поток USB разбирается на полные + * команды, после чего операции передаются общему автомату обновления; граница USB-пакета не + * является границей SET-кадра. + */ + #include "stm32f4xx_hal.h" #include "boot_port.h" #include "boot_config.h" diff --git a/c/set-protocol/ports/stm32f407-usb-boot/test_boot_image.c b/c/set-protocol/ports/stm32f407-usb-boot/test_boot_image.c index 1b39c25..cb24400 100644 --- a/c/set-protocol/ports/stm32f407-usb-boot/test_boot_image.c +++ b/c/set-protocol/ports/stm32f407-usb-boot/test_boot_image.c @@ -1,3 +1,9 @@ +/* + * Проверки boot_image: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "boot_image.h" #include #include diff --git a/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.c b/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.c index 0e354af..4c141b9 100644 --- a/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.c +++ b/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.c @@ -1,3 +1,9 @@ +/* + * Воспроизведение таблицы ЦАП STM32F407 через TIM6 и DMA1 Stream5. Частота должна точно делить + * частоту таймера, а массив находиться в доступной DMA-памяти; старт предварительно загружает + * последний отсчёт циклической таблицы. + */ + #include "set_wave_f407.h" #include "stm32f4xx.h" static void stop(void *context) { diff --git a/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.h b/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.h index b535770..d81276c 100644 --- a/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.h +++ b/c/set-protocol/ports/stm32f407-wavegen/set_wave_f407.h @@ -1,3 +1,9 @@ +/* + * Воспроизведение таблицы ЦАП STM32F407 через TIM6 и DMA1 Stream5. Частота должна точно делить + * частоту таймера, а массив находиться в доступной DMA-памяти; старт предварительно загружает + * последний отсчёт циклической таблицы. + */ + #ifndef SET_WAVE_F407_H #define SET_WAVE_F407_H #include "../../include/set_wavegen.h" diff --git a/c/set-protocol/ports/stm32g474-periph/board.c b/c/set-protocol/ports/stm32g474-periph/board.c index 417ef3d..2b09af5 100644 --- a/c/set-protocol/ports/stm32g474-periph/board.c +++ b/c/set-protocol/ports/stm32g474-periph/board.c @@ -1,3 +1,9 @@ +/* + * Аппаратная подготовка периферийного стенда STM32G474. Конфигурация GPIO и периферии + * относится к плате; сервисы регистров и протоколы подключаются поверх уже подготовленного + * оборудования. + */ + /** * Аппаратный порт STM32G474RB: векторы приложения, тактирование и GPIO. * Алгоритмы UMP/TMS/IGBT находятся в общем C-ядре templates; здесь только пины. diff --git a/c/set-protocol/ports/stm32g474-periph/main.c b/c/set-protocol/ports/stm32g474-periph/main.c index 79d7976..79281e7 100644 --- a/c/set-protocol/ports/stm32g474-periph/main.c +++ b/c/set-protocol/ports/stm32g474-periph/main.c @@ -1,3 +1,9 @@ +/* + * Точка входа примера периферийного стенда STM32G474. Инициализация платы предшествует + * обслуживанию транспорта и сервисов; этот файл связывает переносимую библиотеку с жизненным + * циклом прошивки. + */ + /** * Точка входа прошивки. Здесь только порядок запуска и совместное обслуживание модулей. * Настройки оборудования находятся в board.c, обмен — в transport.c, генератор — в wave_hal.c. diff --git a/c/set-protocol/ports/stm32g474-periph/transport.c b/c/set-protocol/ports/stm32g474-periph/transport.c index c9306be..307f74f 100644 --- a/c/set-protocol/ports/stm32g474-periph/transport.c +++ b/c/set-protocol/ports/stm32g474-periph/transport.c @@ -1,3 +1,8 @@ +/* + * UART/USB-транспорт стенда STM32G474 для регистровых сервисов. Входные байты передаются + * обработчику общего протокола; аппаратные очереди и отправка ответа относятся к этому порту. + */ + /** * USART2/VCP и FDCAN1 в режиме Classic CAN. Формат запросов совпадает с F407: * UART RTU, CAN extended ID 0xBA0000+mode-1; ответы 0xBA0020+mode-1. diff --git a/c/set-protocol/ports/stm32g474-periph/wave_hal.c b/c/set-protocol/ports/stm32g474-periph/wave_hal.c index f6eb670..92ba7a6 100644 --- a/c/set-protocol/ports/stm32g474-periph/wave_hal.c +++ b/c/set-protocol/ports/stm32g474-periph/wave_hal.c @@ -1,3 +1,9 @@ +/* + * Аппаратное воспроизведение таблицы сигналов на STM32G474. Таймер, ЦАП и DMA реализуют + * операции порта генератора; массив выборок должен оставаться доступным до полной остановки + * передачи. + */ + /** * Аппаратный исполнитель генератора: таблица uint16_t в SRAM -> DMA1 -> DAC1/PA4. * TIM6 задаёт частоту выборок аппаратными событиями TRGO; CPU не отправляет каждый отсчёт. diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_config.template.h b/c/set-protocol/ports/stm32g474-usb-boot/boot_config.template.h index fcc99c5..3e039f5 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_config.template.h +++ b/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 diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_flash.c b/c/set-protocol/ports/stm32g474-usb-boot/boot_flash.c index 598d11c..76e5c56 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_flash.c +++ b/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" diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_image.h b/c/set-protocol/ports/stm32g474-usb-boot/boot_image.h index 6a4e2ba..fccc8e4 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_image.h +++ b/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" diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_main.c b/c/set-protocol/ports/stm32g474-usb-boot/boot_main.c index 8897565..a8f6425 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_main.c +++ b/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" diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_port.h b/c/set-protocol/ports/stm32g474-usb-boot/boot_port.h index 9328a62..e594591 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_port.h +++ b/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" diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_request.c b/c/set-protocol/ports/stm32g474-usb-boot/boot_request.c index 5c00e6c..2b8b63a 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_request.c +++ b/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 diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_usb_port.c b/c/set-protocol/ports/stm32g474-usb-boot/boot_usb_port.c index 8e9c615..cb1f68c 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_usb_port.c +++ b/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" diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_usb_stream.c b/c/set-protocol/ports/stm32g474-usb-boot/boot_usb_stream.c index 1a845ff..6bf7c16 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_usb_stream.c +++ b/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" diff --git a/c/set-protocol/ports/stm32g474-usb-boot/boot_writer.h b/c/set-protocol/ports/stm32g474-usb-boot/boot_writer.h index 38d56af..f9c1666 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/boot_writer.h +++ b/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 @@ -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; } diff --git a/c/set-protocol/ports/stm32g474-usb-boot/test_boot_port.c b/c/set-protocol/ports/stm32g474-usb-boot/test_boot_port.c index b2bb928..dad68a3 100644 --- a/c/set-protocol/ports/stm32g474-usb-boot/test_boot_port.c +++ b/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 diff --git a/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.c b/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.c index aa79594..77c1641 100644 --- a/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.c +++ b/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.c @@ -1,3 +1,9 @@ +/* + * HAL-порт генератора STM32G474: DAC1, TIM6 и циклический DMA с 16-битными элементами. + * Проверяются конфигурация DMA и точная достижимость частоты, ограниченной 50 кГц; остановка + * выводит нулевой уровень без ожидания следующего триггера. + */ + #include "set_wave_g474.h" static void stop(void *context) { set_wave_g474 *c=(set_wave_g474 *)context; diff --git a/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.h b/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.h index 908500e..ce9f760 100644 --- a/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.h +++ b/c/set-protocol/ports/stm32g474-wavegen/set_wave_g474.h @@ -1,3 +1,9 @@ +/* + * HAL-порт генератора STM32G474: DAC1, TIM6 и циклический DMA с 16-битными элементами. + * Проверяются конфигурация DMA и точная достижимость частоты, ограниченной 50 кГц; остановка + * выводит нулевой уровень без ожидания следующего триггера. + */ + #ifndef SET_WAVE_G474_H #define SET_WAVE_G474_H #include "stm32g4xx_hal.h" diff --git a/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.c b/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.c index fe89157..1cca8b7 100644 --- a/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.c +++ b/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.c @@ -1,3 +1,9 @@ +/* + * Сервис обновления TMS320F2812 по SETProtocol v2 через сегментированный CAN. Поддерживает + * проверку метаданных и SHA-256; фактические операции Flash, отправка CAN и политика подписи + * задаются интерфейсом платформы. + */ + #include "setp_tms2812_boot.h" #include diff --git a/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.h b/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.h index 4c2c0c0..d3c5254 100644 --- a/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.h +++ b/c/set-protocol/ports/tms320f2812/setp_tms2812_boot.h @@ -1,3 +1,9 @@ +/* + * Сервис обновления TMS320F2812 по SETProtocol v2 через сегментированный CAN. Поддерживает + * проверку метаданных и SHA-256; фактические операции Flash, отправка CAN и политика подписи + * задаются интерфейсом платформы. + */ + #ifndef SETP_TMS2812_BOOT_H #define SETP_TMS2812_BOOT_H diff --git a/c/set-protocol/ports/tms320f28335/ump_tms28335.c b/c/set-protocol/ports/tms320f28335/ump_tms28335.c index c1f2343..1135c88 100644 --- a/c/set-protocol/ports/tms320f28335/ump_tms28335.c +++ b/c/set-protocol/ports/tms320f28335/ump_tms28335.c @@ -1,3 +1,9 @@ +/* + * Порт УМП для TMS320F28335. Аппаратное представление данных C28x связывается с общим + * регистровым протоколом; восьмибитные октеты линии нельзя приравнивать к размеру char + * целевого компилятора. + */ + #include "ump_tms28335.h" extern unsigned int ump_log_read(unsigned int address); extern int ump_log_write(unsigned int address, unsigned int value); diff --git a/c/set-protocol/ports/tms320f28335/ump_tms28335.h b/c/set-protocol/ports/tms320f28335/ump_tms28335.h index d19d420..b79acc4 100644 --- a/c/set-protocol/ports/tms320f28335/ump_tms28335.h +++ b/c/set-protocol/ports/tms320f28335/ump_tms28335.h @@ -1,3 +1,9 @@ +/* + * Порт УМП для TMS320F28335. Аппаратное представление данных C28x связывается с общим + * регистровым протоколом; восьмибитные октеты линии нельзя приравнивать к размеру char + * целевого компилятора. + */ + #ifndef UMP_TMS28335_H #define UMP_TMS28335_H #include "../../include/ump_protocol.h" diff --git a/c/set-protocol/src/altera_logic.c b/c/set-protocol/src/altera_logic.c index 2c97957..ab71067 100644 --- a/c/set-protocol/src/altera_logic.c +++ b/c/set-protocol/src/altera_logic.c @@ -1,3 +1,9 @@ +/* + * Автомат UART-клиента логического анализатора Altera: запрос, накопление ответа и контроль + * времени. Одновременно выполняется одна операция; ARM нельзя безусловно повторять, поскольку + * повторный запуск меняет состояние захвата. + */ + #include "altera_logic.h" #include typedef struct { diff --git a/c/set-protocol/src/altera_stream.c b/c/set-protocol/src/altera_stream.c index a99d8a9..eac6505 100644 --- a/c/set-protocol/src/altera_stream.c +++ b/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 diff --git a/c/set-protocol/src/balsam_can.c b/c/set-protocol/src/balsam_can.c index e9eb3de..a8644bd 100644 --- a/c/set-protocol/src/balsam_can.c +++ b/c/set-protocol/src/balsam_can.c @@ -1,3 +1,9 @@ +/* + * Исторический регистровый CAN-протокол BALZAM/TMS2812. Формат идентификаторов и порядок слов + * относятся именно к этому профилю; общий физический CAN не делает его совместимым с SET v2 + * или протоколом ПМ35. + */ + #include "balsam_can.h" #include diff --git a/c/set-protocol/src/firmware_image.c b/c/set-protocol/src/firmware_image.c index 6070efd..8ee930c 100644 --- a/c/set-protocol/src/firmware_image.c +++ b/c/set-protocol/src/firmware_image.c @@ -1,3 +1,9 @@ +/* + * Проверка Intel HEX и подготовка адресованного образа прошивки. Контрольные суммы записей, + * расширенные адреса и пересечения проверяются до использования результата; рабочая память + * C-парсера принадлежит вызывающему. + */ + #include "firmware_image.h" #include diff --git a/c/set-protocol/src/gui_catalog.c b/c/set-protocol/src/gui_catalog.c index 40030c2..19f8c4d 100644 --- a/c/set-protocol/src/gui_catalog.c +++ b/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) diff --git a/c/set-protocol/src/gui_frame.c b/c/set-protocol/src/gui_frame.c index 602fd92..eb36afd 100644 --- a/c/set-protocol/src/gui_frame.c +++ b/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) diff --git a/c/set-protocol/src/pcan_abi.c b/c/set-protocol/src/pcan_abi.c index 70581c6..5a9d318 100644 --- a/c/set-protocol/src/pcan_abi.c +++ b/c/set-protocol/src/pcan_abi.c @@ -1,3 +1,9 @@ +/* + * Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры + * буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют + * согласованного обновления привязок. + */ + #include "pcan_abi.h" #include diff --git a/c/set-protocol/src/pcan_crc.c b/c/set-protocol/src/pcan_crc.c index 7607378..1a29da0 100644 --- a/c/set-protocol/src/pcan_crc.c +++ b/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 diff --git a/c/set-protocol/src/pcan_frame.c b/c/set-protocol/src/pcan_frame.c index 4d395c7..c757cbb 100644 --- a/c/set-protocol/src/pcan_frame.c +++ b/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); } } diff --git a/c/set-protocol/src/pcan_gas.c b/c/set-protocol/src/pcan_gas.c index b941e40..27132b4 100644 --- a/c/set-protocol/src/pcan_gas.c +++ b/c/set-protocol/src/pcan_gas.c @@ -1,3 +1,9 @@ +/* + * Общее адресное пространство ProtoCAN, разбитое на регионы с обработчиками чтения и записи. + * Поиск региона и проверка доступа предшествуют обращению к приложению; номер регистра не + * является адресом памяти процессора. + */ + #include "pcan_gas.h" #include "pcan_id.h" diff --git a/c/set-protocol/src/pcan_id.c b/c/set-protocol/src/pcan_id.c index 910b199..82dbcbb 100644 --- a/c/set-protocol/src/pcan_id.c +++ b/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) diff --git a/c/set-protocol/src/pcan_link.c b/c/set-protocol/src/pcan_link.c index c3065ad..ffb4e80 100644 --- a/c/set-protocol/src/pcan_link.c +++ b/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, diff --git a/c/set-protocol/src/pcan_modbus_server.c b/c/set-protocol/src/pcan_modbus_server.c index 7b304e6..46081f6 100644 --- a/c/set-protocol/src/pcan_modbus_server.c +++ b/c/set-protocol/src/pcan_modbus_server.c @@ -1,3 +1,9 @@ +/* + * Доступ к окнам Modbus-регистров через один classic CAN-кадр ProtoCAN. Сервер сопоставляет + * команду с банком и диапазоном регистров; чтение и запись значений выполняет предоставленный + * приложением интерфейс. + */ + #include "pcan_modbus_server.h" #include diff --git a/c/set-protocol/src/pcan_ring.c b/c/set-protocol/src/pcan_ring.c index 374c88c..1b1037a 100644 --- a/c/set-protocol/src/pcan_ring.c +++ b/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)); diff --git a/c/set-protocol/src/periph28335.c b/c/set-protocol/src/periph28335.c index 3641ba3..a088666 100644 --- a/c/set-protocol/src/periph28335.c +++ b/c/set-protocol/src/periph28335.c @@ -1,3 +1,9 @@ +/* + * Протокол периферийного контроллера ПМ35/TMS320F28335: регистры, команды и разбор ответов. + * Этот профиль имеет собственную адресацию и не должен подменяться протоколом основного + * TMS320F2812. + */ + #include "periph28335.h" #include diff --git a/c/set-protocol/src/set_boot.c b/c/set-protocol/src/set_boot.c index 4b2922f..af1b71f 100644 --- a/c/set-protocol/src/set_boot.c +++ b/c/set-protocol/src/set_boot.c @@ -1,3 +1,9 @@ +/* + * Транспортно-независимый односекционный обновитель прошивки. Признак валидности снимается до + * стирания, а commit вызывается после проверки записанного образа чтением; порядок операций + * нужен для восстановления после прерывания питания. + */ + #include "set_boot.h" #include @@ -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; } diff --git a/c/set-protocol/src/set_can.c b/c/set-protocol/src/set_can.c index 00e84a7..efb0d6e 100644 --- a/c/set-protocol/src/set_can.c +++ b/c/set-protocol/src/set_can.c @@ -1,3 +1,9 @@ +/* + * Сегментация SET v2 и интерпретация CAN-данных зависят от выбранного слоя. Адрес и номер + * сегмента должны проверяться до объединения данных; classic CAN-пакет ограничен восемью + * байтами. + */ + #include "set_can.h" #include diff --git a/c/set-protocol/src/set_crc.c b/c/set-protocol/src/set_crc.c index 65a2792..1dc342d 100644 --- a/c/set-protocol/src/set_crc.c +++ b/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) diff --git a/c/set-protocol/src/set_emu_igbt.c b/c/set-protocol/src/set_emu_igbt.c index 4226e78..7e17112 100644 --- a/c/set-protocol/src/set_emu_igbt.c +++ b/c/set-protocol/src/set_emu_igbt.c @@ -1,3 +1,9 @@ +/* + * Модель каналов IGBT для стенда: входные состояния, задержки и сформированные выходы. Логика + * времени отделена от аппаратного порта; модель предназначена для воспроизводимого обмена с + * эмулятором. + */ + #include "set_emu_igbt.h" #include static void output(set_igbt_emu *s) diff --git a/c/set-protocol/src/set_emu_server.c b/c/set-protocol/src/set_emu_server.c index 4e5b265..7dd7924 100644 --- a/c/set-protocol/src/set_emu_server.c +++ b/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 diff --git a/c/set-protocol/src/set_emu_tms.c b/c/set-protocol/src/set_emu_tms.c index e6d9908..b06e231 100644 --- a/c/set-protocol/src/set_emu_tms.c +++ b/c/set-protocol/src/set_emu_tms.c @@ -1,3 +1,9 @@ +/* + * Модель ответов TMS для эмулятора контроллера. Синтетические аналоговые и дискретные значения + * упаковываются в ожидаемый формат терминала, чтобы проверять клиент без подключения рабочего + * контроллера. + */ + #include "set_emu_tms.h" #include "set_crc.h" #include diff --git a/c/set-protocol/src/set_emu_ump.c b/c/set-protocol/src/set_emu_ump.c index 8e67f76..3826b41 100644 --- a/c/set-protocol/src/set_emu_ump.c +++ b/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 diff --git a/c/set-protocol/src/set_firmware.c b/c/set-protocol/src/set_firmware.c index 131592f..1878bce 100644 --- a/c/set-protocol/src/set_firmware.c +++ b/c/set-protocol/src/set_firmware.c @@ -1,3 +1,9 @@ +/* + * Кодирование метаданных и сообщений обновления SETProtocol v2. Размер образа, совместимость и + * параметры начала передачи передаются явно; сериализация команды сама по себе не выполняет + * запись Flash. + */ + #include "set_firmware.h" #include diff --git a/c/set-protocol/src/set_plot.c b/c/set-protocol/src/set_plot.c index ab9d99f..37e17ea 100644 --- a/c/set-protocol/src/set_plot.c +++ b/c/set-protocol/src/set_plot.c @@ -1,3 +1,9 @@ +/* + * Математика взаимодействия с графиком: области просмотра, масштабирование, перемещение и + * координатные преобразования. Расчёты общие для JNI и ctypes; цвета, события GUI и рисование + * остаются в приложении. + */ + #include "set_plot.h" #include diff --git a/c/set-protocol/src/set_protocol.c b/c/set-protocol/src/set_protocol.c index 68989fd..f41441c 100644 --- a/c/set-protocol/src/set_protocol.c +++ b/c/set-protocol/src/set_protocol.c @@ -1,3 +1,9 @@ +/* + * Основной бинарный формат SETProtocol v2: поля кадра, контрольная сумма и потоковый parser. + * Числа сериализуются явно, поэтому выравнивание C-структур не влияет на байты линии; + * транспорт передаёт готовые массивы. + */ + #include "set_protocol.h" #include diff --git a/c/set-protocol/src/set_regmap.c b/c/set-protocol/src/set_regmap.c index 89dbc40..67f2d02 100644 --- a/c/set-protocol/src/set_regmap.c +++ b/c/set-protocol/src/set_regmap.c @@ -1,3 +1,9 @@ +/* + * Транспортно-независимая карта 16-битных регистров с отдельными регионами и обработчиками. + * Проверка диапазонов и прав доступа выполняется до вызова сервиса; относительное смещение + * региона отличается от общего адреса. + */ + #include "set_regmap.h" #include "set_crc.h" #include diff --git a/c/set-protocol/src/set_signal.c b/c/set-protocol/src/set_signal.c index 9f17bd6..45b9b7c 100644 --- a/c/set-protocol/src/set_signal.c +++ b/c/set-protocol/src/set_signal.c @@ -1,3 +1,9 @@ +/* + * Восстановление сигнала по точкам и подготовка кодов 12-битного ЦАП. Совпадающие времена + * усредняются, экстраполяция не выполняется; для циклического периода конечная точка + * обрабатывается отдельно. Напряжения вне диапазона отклоняются, а не обрезаются. + */ + #include "set_signal.h" #include #include diff --git a/c/set-protocol/src/set_spectrum.c b/c/set-protocol/src/set_spectrum.c index 259f0ec..0b48820 100644 --- a/c/set-protocol/src/set_spectrum.c +++ b/c/set-protocol/src/set_spectrum.c @@ -1,3 +1,9 @@ +/* + * Общий расчёт FFT: оценка частоты дискретизации по времени, ресемплинг, фильтр, окно и + * спектр. Выход — односторонняя пиковая амплитуда; DC и частота Найквиста не удваиваются. + * Временные метки задаются в секундах. + */ + #include "set_spectrum.h" #include #include diff --git a/c/set-protocol/src/set_telemetry.c b/c/set-protocol/src/set_telemetry.c index 980c81e..f3842d7 100644 --- a/c/set-protocol/src/set_telemetry.c +++ b/c/set-protocol/src/set_telemetry.c @@ -1,3 +1,9 @@ +/* + * Сообщения подписки и телеметрии SETProtocol v2. Период, идентификатор подписки и перечень + * адресов сериализуются отдельно от значений; получатель должен связывать поток с + * соответствующей подпиской. + */ + #include "set_telemetry.h" #include diff --git a/c/set-protocol/src/set_trends.c b/c/set-protocol/src/set_trends.c index 4c3da43..9936220 100644 --- a/c/set-protocol/src/set_trends.c +++ b/c/set-protocol/src/set_trends.c @@ -1,3 +1,9 @@ +/* + * Общий разбор числовых источников трендов, включая GAS и raw CAN. Знаковость слова, смещение + * и коэффициент преобразования относятся к описанию сигнала; визуальная история графика + * хранится на стороне клиента. + */ + #include "set_trends.h" #include "pcan_id.h" diff --git a/c/set-protocol/src/set_wavegen.c b/c/set-protocol/src/set_wavegen.c index b713c47..1b8d199 100644 --- a/c/set-protocol/src/set_wavegen.c +++ b/c/set-protocol/src/set_wavegen.c @@ -1,3 +1,9 @@ +/* + * Транзакционная загрузка таблицы и циклическое воспроизведение через ЦАП. Блоки принимаются + * до commit, а запуск использует согласованную таблицу; порт stop должен остановить DMA до + * возврата и освободить использование массива. + */ + #include "set_wavegen.h" #include "set_crc.h" #include diff --git a/c/set-protocol/src/tms2812.c b/c/set-protocol/src/tms2812.c index 184633f..3222bda 100644 --- a/c/set-protocol/src/tms2812.c +++ b/c/set-protocol/src/tms2812.c @@ -1,3 +1,9 @@ +/* + * Исторический протокол основного контроллера ПМ67/TMS320F2812. Формирование команд и проверка + * ответов находятся в общем ядре; адреса памяти C28x считаются словами, тогда как длины + * передачи могут задаваться байтами. + */ + #include "tms2812.h" #include diff --git a/c/set-protocol/src/ump_protocol.c b/c/set-protocol/src/ump_protocol.c index 9f217aa..e8b4aa5 100644 --- a/c/set-protocol/src/ump_protocol.c +++ b/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)); } diff --git a/c/set-protocol/tests/test_abi.c b/c/set-protocol/tests/test_abi.c index 09ce2e0..5c30f58 100644 --- a/c/set-protocol/tests/test_abi.c +++ b/c/set-protocol/tests/test_abi.c @@ -1,3 +1,9 @@ +/* + * Проверки abi: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include #include diff --git a/c/set-protocol/tests/test_altera_logic.c b/c/set-protocol/tests/test_altera_logic.c index 3e68221..7ce7082 100644 --- a/c/set-protocol/tests/test_altera_logic.c +++ b/c/set-protocol/tests/test_altera_logic.c @@ -1,3 +1,9 @@ +/* + * Проверки altera_logic: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "altera_logic.h" #include #include diff --git a/c/set-protocol/tests/test_altera_stream.c b/c/set-protocol/tests/test_altera_stream.c index 4e1b04f..5261662 100644 --- a/c/set-protocol/tests/test_altera_stream.c +++ b/c/set-protocol/tests/test_altera_stream.c @@ -1,3 +1,9 @@ +/* + * Проверки altera_stream: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "altera_stream.h" #include #include diff --git a/c/set-protocol/tests/test_balsam_can.c b/c/set-protocol/tests/test_balsam_can.c index b283303..c7c43c1 100644 --- a/c/set-protocol/tests/test_balsam_can.c +++ b/c/set-protocol/tests/test_balsam_can.c @@ -1,3 +1,9 @@ +/* + * Проверки balsam_can: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include diff --git a/c/set-protocol/tests/test_boot.c b/c/set-protocol/tests/test_boot.c index a1d672f..5ae25a6 100644 --- a/c/set-protocol/tests/test_boot.c +++ b/c/set-protocol/tests/test_boot.c @@ -1,3 +1,9 @@ +/* + * Проверки boot: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "set_boot.h" #include #include diff --git a/c/set-protocol/tests/test_emulator_services.c b/c/set-protocol/tests/test_emulator_services.c index 1096096..8a8c22a 100644 --- a/c/set-protocol/tests/test_emulator_services.c +++ b/c/set-protocol/tests/test_emulator_services.c @@ -1,3 +1,9 @@ +/* + * Проверки emulator_services: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /* Portable contract tests. Assertions stay enabled even in Release builds. */ #include "set_emu_server.h" #include "set_crc.h" diff --git a/c/set-protocol/tests/test_firmware_image.c b/c/set-protocol/tests/test_firmware_image.c index d75ceb5..40a7355 100644 --- a/c/set-protocol/tests/test_firmware_image.c +++ b/c/set-protocol/tests/test_firmware_image.c @@ -1,3 +1,9 @@ +/* + * Проверки firmware_image: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "firmware_image.h" #include #include diff --git a/c/set-protocol/tests/test_gui.c b/c/set-protocol/tests/test_gui.c index 631bf08..4733c9a 100644 --- a/c/set-protocol/tests/test_gui.c +++ b/c/set-protocol/tests/test_gui.c @@ -1,3 +1,19 @@ +/* + * Проверки gui: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_crc32 + * test_ping_reference + * test_parser + * test_max_payload + * test_catalog_validate + * test_catalog_encode + * test_watch + * test_watch_timing + * Остальные сценарии продолжают эти проверки ниже в том же файле. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /** * Тесты GUI-протокола и каталога общего адресного пространства. * Эталонные байты совпадают с SETGUI/tests/test_gas_catalog.py. diff --git a/c/set-protocol/tests/test_modbus_server.c b/c/set-protocol/tests/test_modbus_server.c index 7b6f89b..eb264cc 100644 --- a/c/set-protocol/tests/test_modbus_server.c +++ b/c/set-protocol/tests/test_modbus_server.c @@ -1,3 +1,9 @@ +/* + * Проверки modbus_server: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include diff --git a/c/set-protocol/tests/test_periph28335.c b/c/set-protocol/tests/test_periph28335.c index 424ba70..c59260f 100644 --- a/c/set-protocol/tests/test_periph28335.c +++ b/c/set-protocol/tests/test_periph28335.c @@ -1,3 +1,9 @@ +/* + * Проверки periph28335: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include diff --git a/c/set-protocol/tests/test_plot.c b/c/set-protocol/tests/test_plot.c index 640621c..64f23db 100644 --- a/c/set-protocol/tests/test_plot.c +++ b/c/set-protocol/tests/test_plot.c @@ -1,3 +1,9 @@ +/* + * Проверки plot: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "set_plot.h" #include #include diff --git a/c/set-protocol/tests/test_set_protocol.c b/c/set-protocol/tests/test_set_protocol.c index aaf1416..43dbe0a 100644 --- a/c/set-protocol/tests/test_set_protocol.c +++ b/c/set-protocol/tests/test_set_protocol.c @@ -1,3 +1,17 @@ +/* + * Проверки set_protocol: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_crc_and_reference_frame + * test_parser + * test_status + * test_system_payloads + * test_can_binding + * test_firmware + * test_telemetry + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "set_firmware.h" #include "set_can.h" #include "set_protocol.h" diff --git a/c/set-protocol/tests/test_signal_wave.c b/c/set-protocol/tests/test_signal_wave.c index 0b99c8c..44e360f 100644 --- a/c/set-protocol/tests/test_signal_wave.c +++ b/c/set-protocol/tests/test_signal_wave.c @@ -1,3 +1,9 @@ +/* + * Проверки signal_wave: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "set_signal.h" #include "set_wavegen.h" #include diff --git a/c/set-protocol/tests/test_spectrum.c b/c/set-protocol/tests/test_spectrum.c index 64a36b7..fc80033 100644 --- a/c/set-protocol/tests/test_spectrum.c +++ b/c/set-protocol/tests/test_spectrum.c @@ -1,3 +1,9 @@ +/* + * Проверки spectrum: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "set_spectrum.h" #include #include diff --git a/c/set-protocol/tests/test_tms2812.c b/c/set-protocol/tests/test_tms2812.c index 677a614..864f8c2 100644 --- a/c/set-protocol/tests/test_tms2812.c +++ b/c/set-protocol/tests/test_tms2812.c @@ -1,3 +1,11 @@ +/* + * Проверки tms2812: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_terminal + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include diff --git a/c/set-protocol/tests/test_tms2812_boot.c b/c/set-protocol/tests/test_tms2812_boot.c index f1065b0..d706511 100644 --- a/c/set-protocol/tests/test_tms2812_boot.c +++ b/c/set-protocol/tests/test_tms2812_boot.c @@ -1,3 +1,9 @@ +/* + * Проверки tms2812_boot: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include #include diff --git a/c/set-protocol/tests/test_transport.c b/c/set-protocol/tests/test_transport.c index cc0f9bb..b25bcc3 100644 --- a/c/set-protocol/tests/test_transport.c +++ b/c/set-protocol/tests/test_transport.c @@ -1,3 +1,19 @@ +/* + * Проверки transport: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Сценарии для навигации по файлу: + * test_crc + * test_encode + * test_encode_max + * test_roundtrip + * test_resync + * test_bad_crc + * test_id + * test_ring + * Остальные сценарии продолжают эти проверки ниже в том же файле. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + /** * Тесты библиотеки. Платформенных зависимостей нет, собирается любым C99: * diff --git a/c/set-protocol/tests/test_trends.c b/c/set-protocol/tests/test_trends.c index f357bd2..e759008 100644 --- a/c/set-protocol/tests/test_trends.c +++ b/c/set-protocol/tests/test_trends.c @@ -1,3 +1,9 @@ +/* + * Проверки trends: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include #include #include diff --git a/c/set-protocol/tools/build_host.py b/c/set-protocol/tools/build_host.py index 67759a5..911da88 100644 --- a/c/set-protocol/tools/build_host.py +++ b/c/set-protocol/tools/build_host.py @@ -1,3 +1,7 @@ +# Сборка нативной SETProtocol для текущего хоста с выбором доступного инструментария. +# Предпочтителен CMake; предусмотрены отдельные пути MSVC и системного C-компилятора, чтобы +# ctypes-клиенты получили совместимую библиотеку. + """Build the SETProtocol shared library without imposing one host toolchain. CMake remains the primary build. On a Windows workstation where CMake is diff --git a/c/settings-backup/CMakeLists.txt b/c/settings-backup/CMakeLists.txt index a7cc47b..81a2fc3 100644 --- a/c/settings-backup/CMakeLists.txt +++ b/c/settings-backup/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки settings_backup. Состав исходников и публичные include-пути задают +# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; +# запускать их следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(settings_backup C) add_library(settings_backup STATIC Src/settings_backup.c) diff --git a/c/settings-backup/Inc/settings_backup.h b/c/settings-backup/Inc/settings_backup.h index 43f8310..063011b 100644 --- a/c/settings-backup/Inc/settings_backup.h +++ b/c/settings-backup/Inc/settings_backup.h @@ -1,3 +1,9 @@ +/* + * Автомат создания и восстановления резервных копий настроек. Формат и политика повторов + * отделены от файловой системы; ошибки ввода-вывода не должны превращать неполную копию в + * подтверждённое состояние. + */ + #ifndef SETTINGS_BACKUP_H #define SETTINGS_BACKUP_H diff --git a/c/settings-backup/Inc/settings_backup_config.h b/c/settings-backup/Inc/settings_backup_config.h index cd16620..229c759 100644 --- a/c/settings-backup/Inc/settings_backup_config.h +++ b/c/settings-backup/Inc/settings_backup_config.h @@ -1,3 +1,9 @@ +/* + * Конфигурация settings-backup. Макросы задают параметры сборки и ограничения, используемые + * исходниками этого модуля. Смысл и единицы каждого параметра определяются местом его + * использования; размеры буферов должны быть согласованы у всех потребителей заголовка. + */ + #ifndef SETTINGS_BACKUP_CONFIG_H #define SETTINGS_BACKUP_CONFIG_H diff --git a/c/settings-backup/Src/settings_backup.c b/c/settings-backup/Src/settings_backup.c index efdeb21..4338111 100644 --- a/c/settings-backup/Src/settings_backup.c +++ b/c/settings-backup/Src/settings_backup.c @@ -1,3 +1,9 @@ +/* + * Автомат создания и восстановления резервных копий настроек. Формат и политика повторов + * отделены от файловой системы; ошибки ввода-вывода не должны превращать неполную копию в + * подтверждённое состояние. + */ + #include "../Inc/settings_backup.h" #include "../Inc/settings_backup_config.h" diff --git a/c/settings-backup/Tests/test_settings_backup.c b/c/settings-backup/Tests/test_settings_backup.c index 87e2c23..b0c9880 100644 --- a/c/settings-backup/Tests/test_settings_backup.c +++ b/c/settings-backup/Tests/test_settings_backup.c @@ -1,3 +1,9 @@ +/* + * Проверки settings_backup: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "settings_backup.h" #include #include diff --git a/c/settings-backup/Tests/test_settings_backup_model.py b/c/settings-backup/Tests/test_settings_backup_model.py index e7156e7..3b33c42 100644 --- a/c/settings-backup/Tests/test_settings_backup_model.py +++ b/c/settings-backup/Tests/test_settings_backup_model.py @@ -1,3 +1,18 @@ +# Проверки settings_backup_model: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_calendar_tree_and_fat_safe_english_month +# test_json_schema_contains_all_32_rooms_full_rom_and_units +# test_hash_excludes_rtc_and_prevents_restart_duplicate +# test_confirmed_revision_change_creates_copy_not_periodic_tick +# test_collision_survives_restart_and_checks_temp_too +# test_atomic_failures_preserve_last_good +# test_absent_removed_or_full_card_is_non_destructive +# test_invalid_rtc_uses_revision_and_never_fake_date +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Модельные проверки полного контракта JSON backup без реальной SD-карты.""" import json diff --git a/c/spi-nor/CMakeLists.txt b/c/spi-nor/CMakeLists.txt index c570eda..404be52 100644 --- a/c/spi-nor/CMakeLists.txt +++ b/c/spi-nor/CMakeLists.txt @@ -1,3 +1,7 @@ +# Сборка библиотеки spi_nor. Состав исходников и публичные include-пути задают подключение к +# проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их +# следует через CTest из каталога сборки. + cmake_minimum_required(VERSION 3.13) project(spi_nor C) add_library(spi_nor STATIC Src/spi_nor.c) diff --git a/c/spi-nor/Diagnostics/Inc/spi_nor_command_service.h b/c/spi-nor/Diagnostics/Inc/spi_nor_command_service.h index 0440fda..d396703 100644 --- a/c/spi-nor/Diagnostics/Inc/spi_nor_command_service.h +++ b/c/spi-nor/Diagnostics/Inc/spi_nor_command_service.h @@ -1,3 +1,9 @@ +/* + * Ограниченный диагностический сервис коротких команд SPI NOR. Допускаются только чтение + * данных, статуса и JEDEC ID; allowlist не позволяет использовать этот интерфейс как + * произвольную командную консоль Flash. + */ + #ifndef SPI_NOR_COMMAND_SERVICE_H #define SPI_NOR_COMMAND_SERVICE_H diff --git a/c/spi-nor/Diagnostics/Inc/spi_nor_read_service.h b/c/spi-nor/Diagnostics/Inc/spi_nor_read_service.h index cae0f01..e21c92d 100644 --- a/c/spi-nor/Diagnostics/Inc/spi_nor_read_service.h +++ b/c/spi-nor/Diagnostics/Inc/spi_nor_read_service.h @@ -1,3 +1,9 @@ +/* + * Диагностическое чтение SPI NOR с явной ёмкостью памяти и обратным вызовом чтения. Интерфейс + * не содержит операций программирования и стирания; диапазон запроса проверяется до доступа к + * памяти. + */ + #ifndef SPI_NOR_READ_SERVICE_H #define SPI_NOR_READ_SERVICE_H diff --git a/c/spi-nor/Diagnostics/Src/spi_nor_command_service.c b/c/spi-nor/Diagnostics/Src/spi_nor_command_service.c index 6b895f8..22755fa 100644 --- a/c/spi-nor/Diagnostics/Src/spi_nor_command_service.c +++ b/c/spi-nor/Diagnostics/Src/spi_nor_command_service.c @@ -1,3 +1,9 @@ +/* + * Ограниченный диагностический сервис коротких команд SPI NOR. Допускаются только чтение + * данных, статуса и JEDEC ID; allowlist не позволяет использовать этот интерфейс как + * произвольную командную консоль Flash. + */ + #include "spi_nor_command_service.h" #include diff --git a/c/spi-nor/Diagnostics/Src/spi_nor_read_service.c b/c/spi-nor/Diagnostics/Src/spi_nor_read_service.c index f18f60a..b799f68 100644 --- a/c/spi-nor/Diagnostics/Src/spi_nor_read_service.c +++ b/c/spi-nor/Diagnostics/Src/spi_nor_read_service.c @@ -1,3 +1,9 @@ +/* + * Диагностическое чтение SPI NOR с явной ёмкостью памяти и обратным вызовом чтения. Интерфейс + * не содержит операций программирования и стирания; диапазон запроса проверяется до доступа к + * памяти. + */ + #include "spi_nor_read_service.h" #include diff --git a/c/spi-nor/Inc/spi_nor.h b/c/spi-nor/Inc/spi_nor.h index 306cf3f..7ff3382 100644 --- a/c/spi-nor/Inc/spi_nor.h +++ b/c/spi-nor/Inc/spi_nor.h @@ -1,3 +1,9 @@ +/* + * Команды SPI NOR через обратные вызовы порта: определение устройства, чтение, запись и + * стирание. Ограничения страницы, сектора и состояния BUSY относятся к микросхеме; GPIO и + * SPI-периферию настраивает приложение. + */ + #ifndef PORTABLE_SPI_NOR_H #define PORTABLE_SPI_NOR_H diff --git a/c/spi-nor/Src/spi_nor.c b/c/spi-nor/Src/spi_nor.c index 8f914e8..03e5170 100644 --- a/c/spi-nor/Src/spi_nor.c +++ b/c/spi-nor/Src/spi_nor.c @@ -1,3 +1,9 @@ +/* + * Команды SPI NOR через обратные вызовы порта: определение устройства, чтение, запись и + * стирание. Ограничения страницы, сектора и состояния BUSY относятся к микросхеме; GPIO и + * SPI-периферию настраивает приложение. + */ + #include "spi_nor.h" #include diff --git a/c/spi-nor/Tests/test_spi_nor.c b/c/spi-nor/Tests/test_spi_nor.c index 4433d45..ee08709 100644 --- a/c/spi-nor/Tests/test_spi_nor.c +++ b/c/spi-nor/Tests/test_spi_nor.c @@ -1,3 +1,9 @@ +/* + * Проверки spi_nor: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "spi_nor.h" #include diff --git a/c/spi-nor/Tests/test_spi_nor_command_service.c b/c/spi-nor/Tests/test_spi_nor_command_service.c index 167b5ac..d31d039 100644 --- a/c/spi-nor/Tests/test_spi_nor_command_service.c +++ b/c/spi-nor/Tests/test_spi_nor_command_service.c @@ -1,3 +1,10 @@ +/* + * Проверки spi_nor_command_service: фиксируют ожидаемое поведение на воспроизводимых входных + * данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "spi_nor_command_service.h" #include diff --git a/c/spi-nor/Tests/test_spi_nor_read_service.c b/c/spi-nor/Tests/test_spi_nor_read_service.c index db29f8c..ec3c349 100644 --- a/c/spi-nor/Tests/test_spi_nor_read_service.c +++ b/c/spi-nor/Tests/test_spi_nor_read_service.c @@ -1,3 +1,10 @@ +/* + * Проверки spi_nor_read_service: фиксируют ожидаемое поведение на воспроизводимых входных + * данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "spi_nor_read_service.h" #include diff --git a/c/st7789/st7789.c b/c/st7789/st7789.c index 0fcb65f..8839aa7 100644 --- a/c/st7789/st7789.c +++ b/c/st7789/st7789.c @@ -1,3 +1,8 @@ +/* + * Вывод на TFT ST7789 в RGB565 через SPI-порт без полного кадрового буфера. Окно адресации + * дисплея задаётся до передачи пикселей; команды и данные различаются состоянием линии DC. + */ + /** * @file st7789.c * @brief Реализация драйвера ST7789V: инициализация панели и графика. diff --git a/c/st7789/st7789.h b/c/st7789/st7789.h index 0960cc6..60c8632 100644 --- a/c/st7789/st7789.h +++ b/c/st7789/st7789.h @@ -1,3 +1,8 @@ +/* + * Вывод на TFT ST7789 в RGB565 через SPI-порт без полного кадрового буфера. Окно адресации + * дисплея задаётся до передачи пикселей; команды и данные различаются состоянием линии DC. + */ + /** * @file st7789.h * @brief Портируемый драйвер TFT-дисплеев ST7789V (SPI, RGB565). diff --git a/c/st7789/st7789_font.c b/c/st7789/st7789_font.c index fb96f19..d8b057d 100644 --- a/c/st7789/st7789_font.c +++ b/c/st7789/st7789_font.c @@ -1,3 +1,9 @@ +/* + * Растровый шрифт для текстового вывода ST7789. Метаданные глифов и порядок битов должны + * соответствовать обходу в драйвере; таблица описывает пиксели символов, а не строки в + * кодировке терминала. + */ + /** * @file st7789_font.c * @brief Таблица знакогенератора 5x7 для кодов 0x20..0x7F. diff --git a/c/st7789/st7789_font.h b/c/st7789/st7789_font.h index 3c6ec57..30da8e5 100644 --- a/c/st7789/st7789_font.h +++ b/c/st7789/st7789_font.h @@ -1,3 +1,9 @@ +/* + * Растровый шрифт для текстового вывода ST7789. Метаданные глифов и порядок битов должны + * соответствовать обходу в драйвере; таблица описывает пиксели символов, а не строки в + * кодировке терминала. + */ + /** * @file st7789_font.h * @brief Знакогенератор 5x7 для драйвера ST7789V. diff --git a/doc/build-doxygen.ps1 b/doc/build-doxygen.ps1 index 4207978..994ed5d 100644 --- a/doc/build-doxygen.ps1 +++ b/doc/build-doxygen.ps1 @@ -1,3 +1,7 @@ +# Генерация справочника API из Doxygen-комментариев исходников. Скрипт связывает конфигурацию +# Doxyfile с каталогом результата; HTML является производным артефактом и не заменяет +# комментарии в коде. + [CmdletBinding()] param() diff --git a/doc/build-html.bat b/doc/build-html.bat index 4c64977..abc5205 100644 --- a/doc/build-html.bat +++ b/doc/build-html.bat @@ -1,4 +1,8 @@ @echo off +rem Windows-точка запуска генератора HTML-документации. Передаёт управление скрипту сборки +rem относительно своего каталога, чтобы запуск из другого рабочего каталога находил правильные +rem исходники. + setlocal EnableExtensions set "SCRIPT_DIR=%~dp0" diff --git a/doc/build-setprotocol-html.ps1 b/doc/build-setprotocol-html.ps1 index e783583..21f762e 100644 --- a/doc/build-setprotocol-html.ps1 +++ b/doc/build-setprotocol-html.ps1 @@ -1,3 +1,7 @@ +# Формирование HTML-справочника SETProtocol из исходной документации. Пути и шаблон определяют +# состав выходной страницы; изменение справочника следует вносить в источник, используемый +# этим генератором. + [CmdletBinding()] param() diff --git a/doc/setcan/build-html.bat b/doc/setcan/build-html.bat index 4891a17..0cd0e37 100644 --- a/doc/setcan/build-html.bat +++ b/doc/setcan/build-html.bat @@ -1,4 +1,8 @@ @echo off +rem Windows-точка запуска генератора HTML-документации. Передаёт управление скрипту сборки +rem относительно своего каталога, чтобы запуск из другого рабочего каталога находил правильные +rem исходники. + setlocal set "SCRIPT_DIR=%~dp0" diff --git a/doc/setcan/build-html.ps1 b/doc/setcan/build-html.ps1 index 47c6e7c..bb8f5dc 100644 --- a/doc/setcan/build-html.ps1 +++ b/doc/setcan/build-html.ps1 @@ -1,3 +1,7 @@ +# Сборка HTML-документации SETCAN из файлов исходного описания. Скрипт подготавливает +# навигацию и содержимое страниц; выходные HTML-файлы предназначены для чтения вне среды +# разработки. + [CmdletBinding()] param() diff --git a/hdl/logic-analyzer/rtl/la_capture_buffer.v b/hdl/logic-analyzer/rtl/la_capture_buffer.v index 4665139..75292f7 100644 --- a/hdl/logic-analyzer/rtl/la_capture_buffer.v +++ b/hdl/logic-analyzer/rtl/la_capture_buffer.v @@ -1,3 +1,9 @@ +/* + * Двухтактовая память захвата FPGA: запись и чтение обслуживаются независимыми тактовыми + * входами. Чтение регистровое, выход обновляется по rd_clk; одновременный доступ к одному + * адресу требует учёта поведения выбранной FPGA-памяти. + */ + // Portable dual-clock capture RAM for FPGA logic analyzers. // The module intentionally contains no vendor primitives: Quartus infers M9K // blocks on Cyclone IV, while other tools may infer their native block RAM. @@ -14,16 +20,22 @@ module la_capture_buffer #( input wire [ADDR_WIDTH-1:0] rd_addr, output reg [SAMPLE_WIDTH-1:0] rd_data ); + // ADDR_WIDTH задаёт логарифм ёмкости: каждый дополнительный адресный бит + // удваивает число хранимых отсчётов, не меняя разрядность одного отсчёта. localparam DEPTH = (1 << ADDR_WIDTH); reg [SAMPLE_WIDTH-1:0] memory [0:DEPTH-1]; + // Разрешение записи действует только на фронте wr_clk. Память не имеет + // сброса: до первой записи содержимое адреса не считается определённым. always @(posedge wr_clk) begin if (wr_en) memory[wr_addr] <= wr_data; end // Registered read is supported directly by Cyclone IV M9K blocks. + // Нет rd_en: на каждом фронте читается текущий адрес. Согласование + // владения областями между доменами частот выполняет внешняя логика. always @(posedge rd_clk) rd_data <= memory[rd_addr]; endmodule diff --git a/python/altera_logic/__init__.py b/python/altera_logic/__init__.py index 228f588..7c28b64 100644 --- a/python/altera_logic/__init__.py +++ b/python/altera_logic/__init__.py @@ -1,3 +1,7 @@ +# Входная точка пакета altera_logic. Определяет доступные при импорте имена; подробные +# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на +# существующие import у потребителей. + """Portable Altera analyzer client. Wire protocol and sequencing live in C99.""" from .native import Capture, NativeAnalyzer diff --git a/python/altera_logic/markers.py b/python/altera_logic/markers.py index b559b35..2e1476a 100644 --- a/python/altera_logic/markers.py +++ b/python/altera_logic/markers.py @@ -1,3 +1,7 @@ +# Состояние измерительных маркеров и линеек графика. Маркер относится к координатам +# отображаемого сигнала; его перемещение не изменяет полученные выборки или настройки +# транспорта. + """Presentation state for waveform rulers; no transport or wire processing.""" from dataclasses import dataclass diff --git a/python/altera_logic/native.py b/python/altera_logic/native.py index e638a4a..f0e83ee 100644 --- a/python/altera_logic/native.py +++ b/python/altera_logic/native.py @@ -1,3 +1,8 @@ +# Автомат UART-клиента логического анализатора Altera: запрос, накопление ответа и контроль +# времени. Одновременно выполняется одна операция; ARM нельзя безусловно повторять, поскольку +# повторный запуск меняет состояние захвата. Здесь только ctypes-привязка: протокольного +# fallback на Python нет. + """ctypes binding only: no Python packet codec or protocol fallback.""" from __future__ import annotations diff --git a/python/altera_logic/plot_scroll.py b/python/altera_logic/plot_scroll.py index 2139443..6138e5d 100644 --- a/python/altera_logic/plot_scroll.py +++ b/python/altera_logic/plot_scroll.py @@ -1,3 +1,6 @@ +# Qt-прокрутка области графика анализатора: колесо перемещает X, Ctrl с колесом — Y. +# Обработчик меняет область просмотра, сохраняя масштаб и исходный массив захвата. + """Qt presentation port: wheel pans X; Ctrl+wheel pans Y, never zooms.""" from PySide6.QtCore import Qt, Signal from PySide6.QtWidgets import QScrollArea diff --git a/python/altera_logic/qt_port.py b/python/altera_logic/qt_port.py index 737d9e9..580ecf5 100644 --- a/python/altera_logic/qt_port.py +++ b/python/altera_logic/qt_port.py @@ -1,3 +1,6 @@ +# Последовательный Qt-порт анализатора Altera. Порт обслуживает соединение, таймеры и события, +# а решения о запросах, ответах и таймаутах принимает автомат C99. + """Qt serial/lifecycle port. Protocol decisions are exclusively in C99.""" from __future__ import annotations diff --git a/python/altera_logic/stream.py b/python/altera_logic/stream.py index 0a6b733..dea64eb 100644 --- a/python/altera_logic/stream.py +++ b/python/altera_logic/stream.py @@ -1,3 +1,7 @@ +# Клиентский приём потока SETCAN логического анализатора. CAN-события или UART-оболочка +# передаются общему приёмнику; накопление выборок и частота перерисовки разделены, чтобы поток +# пакетов не перегружал GUI. + """SETCAN streaming FFI and immutable display/export models. No wire codec.""" from __future__ import annotations import csv diff --git a/python/altera_logic/stream_port.py b/python/altera_logic/stream_port.py index 30d7691..e1131de 100644 --- a/python/altera_logic/stream_port.py +++ b/python/altera_logic/stream_port.py @@ -1,3 +1,7 @@ +# Клиентский приём потока SETCAN логического анализатора. CAN-события или UART-оболочка +# передаются общему приёмнику; накопление выборок и частота перерисовки разделены, чтобы поток +# пакетов не перегружал GUI. + """Qt transport/lifecycle port for the C SETCAN stream receiver. CAN ingress accepts canonical RX events from an existing bus connection. diff --git a/python/examples/plot_processing.py b/python/examples/plot_processing.py index f76057e..849b19c 100644 --- a/python/examples/plot_processing.py +++ b/python/examples/plot_processing.py @@ -1,3 +1,7 @@ +# Контракт обработки снимков графика: входные ряды, запрос расчёта и результирующие кривые. +# Вычисленные данные отделены от исходных измерений; численная обработка делегируется общему +# ядру C99. + """Sparse sine reconstruction using the public contract, independent of a GUI.""" import argparse import math diff --git a/python/firmware_image/__init__.py b/python/firmware_image/__init__.py index 9c962cc..938f0ed 100644 --- a/python/firmware_image/__init__.py +++ b/python/firmware_image/__init__.py @@ -1,2 +1,6 @@ +# Входная точка пакета firmware_image. Определяет доступные при импорте имена; подробные +# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на +# существующие import у потребителей. + """Shared firmware images and flash layout plans.""" from .core import * diff --git a/python/firmware_image/core.py b/python/firmware_image/core.py index ffa3c9d..226831c 100644 --- a/python/firmware_image/core.py +++ b/python/firmware_image/core.py @@ -1,3 +1,7 @@ +# Проверка Intel HEX и подготовка адресованного образа прошивки. Контрольные суммы записей, +# расширенные адреса и пересечения проверяются до использования результата; рабочая память +# C-парсера принадлежит вызывающему. + """Переносимое ядро проверки образа прошивки STM32. Модуль не знает ни про HTTP, ни про Modbus, ни про файловую систему, ни про diff --git a/python/firmware_image/native.py b/python/firmware_image/native.py index c68ddc3..a712dce 100644 --- a/python/firmware_image/native.py +++ b/python/firmware_image/native.py @@ -1,3 +1,8 @@ +# Проверка Intel HEX и подготовка адресованного образа прошивки. Контрольные суммы записей, +# расширенные адреса и пересечения проверяются до использования результата; рабочая память +# C-парсера принадлежит вызывающему. Python-слой предоставляет модели и ctypes-вызовы без +# резервного парсера на Python. + """Models for the C99 Intel HEX parser. No Python parser fallback.""" import ctypes as ct from functools import lru_cache diff --git a/python/logic_analyzer/__init__.py b/python/logic_analyzer/__init__.py index fc6c605..6dac711 100644 --- a/python/logic_analyzer/__init__.py +++ b/python/logic_analyzer/__init__.py @@ -1 +1,5 @@ +# Входная точка пакета logic_analyzer. Определяет доступные при импорте имена; подробные +# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на +# существующие import у потребителей. + """Reusable device libraries from setcorp/templates.""" diff --git a/python/logic_analyzer/analysis.py b/python/logic_analyzer/analysis.py index 07368ed..5210d7a 100644 --- a/python/logic_analyzer/analysis.py +++ b/python/logic_analyzer/analysis.py @@ -1,3 +1,7 @@ +# Офлайн-анализ логических фронтов с временными метками. Интервалы считаются по переходам, без +# разворачивания в массив каждой выборки; аппаратное подключение для анализа уже сохранённого +# захвата не требуется. + """Offline analysis of timestamped edges; no resampling or hardware access.""" from __future__ import annotations diff --git a/python/logic_analyzer/conversion.py b/python/logic_analyzer/conversion.py index 75b30cc..57735aa 100644 --- a/python/logic_analyzer/conversion.py +++ b/python/logic_analyzer/conversion.py @@ -1,3 +1,6 @@ +# Преобразование цифровых захватов между CSV, JSON, SAL и DSL. Используются общие читатели +# фронтов; аналоговые данные и настройки анализатора не переносятся как цифровые сигналы. + """Digital CSV/JSON/SAL/DSL conversion using the shared capture readers. SAL v3 encoding follows DSLogic_Logic_2/dslogic_script/tests/generate_test_sal.py. diff --git a/python/logic_analyzer/csv_import.py b/python/logic_analyzer/csv_import.py index ca5aeec..0d80258 100644 --- a/python/logic_analyzer/csv_import.py +++ b/python/logic_analyzer/csv_import.py @@ -1,3 +1,6 @@ +# Потоковый импорт цифрового CSV в захват DSView v3. Интервалы между переходами сохраняются +# явно, поэтому длинный неизменный уровень не требует хранения каждой отдельной выборки. + """Stream digital CSV into DSView v3, preserving intervals between transitions.""" from contextlib import contextmanager import csv diff --git a/python/logic_analyzer/csv_options.py b/python/logic_analyzer/csv_options.py index 11703ce..44f4094 100644 --- a/python/logic_analyzer/csv_options.py +++ b/python/logic_analyzer/csv_options.py @@ -1,3 +1,7 @@ +# Нормализация настраиваемого CSV-ввода: временная колонка, цифровые каналы и правила чтения +# строк. Преобразование выполняется потоково, чтобы размер исходного файла не определял объём +# оперативной памяти. + """Streaming normalization of configurable digital CSV input.""" import csv from decimal import Decimal, InvalidOperation diff --git a/python/logic_analyzer/decoders/__init__.py b/python/logic_analyzer/decoders/__init__.py index fc6c605..0870be9 100644 --- a/python/logic_analyzer/decoders/__init__.py +++ b/python/logic_analyzer/decoders/__init__.py @@ -1 +1,5 @@ +# Входная точка пакета logic_analyzer.decoders. Определяет доступные при импорте имена; +# подробные контракты находятся в специализированных модулях пакета. Изменение реэкспортов +# влияет на существующие import у потребителей. + """Reusable device libraries from setcorp/templates.""" diff --git a/python/logic_analyzer/decoders/gate_timing.py b/python/logic_analyzer/decoders/gate_timing.py index 9172fed..a75c497 100644 --- a/python/logic_analyzer/decoders/gate_timing.py +++ b/python/logic_analyzer/decoders/gate_timing.py @@ -1,3 +1,7 @@ +# Проверка временных характеристик драйвера затвора по цифровым фронтам. Параметры профилей +# задаются в наносекундах; типичная задержка ACK используется для предупреждения, а +# нормированная длительность импульса — для PASS/FAIL. + """Pure timing checker used by the DSView decoder and unit tests. All time values in profiles are nanoseconds. The ACK delay in the vendor diff --git a/python/logic_analyzer/decoders/pm35_uart.py b/python/logic_analyzer/decoders/pm35_uart.py index 0d90397..07cab2e 100644 --- a/python/logic_analyzer/decoders/pm35_uart.py +++ b/python/logic_analyzer/decoders/pm35_uart.py @@ -1,3 +1,7 @@ +# Декодирование UART-обмена ПМ35 с командами Modbus 03/06. Учитывается исторический ответ на +# 128 слов с нулевым полем числа байтов; универсальный Modbus-parser без этого правила +# потеряет границу сообщения. + """PM35 MODBUS 03/06, including the legacy 128-word/zero-byte-count reply.""" from .set_uart import crc16, number diff --git a/python/logic_analyzer/decoders/set_can.py b/python/logic_analyzer/decoders/set_can.py index e396ab4..f0d0867 100644 --- a/python/logic_analyzer/decoders/set_can.py +++ b/python/logic_analyzer/decoders/set_can.py @@ -1,3 +1,7 @@ +# Офлайн-интерпретация CAN-захвата для ProtoCAN, BALZAM и SET v2. Выбранный формат определяет +# разбор адреса и данных; сегментированные SET-пакеты требуют сборки до интерпретации полезной +# нагрузки. + """ProtoCAN, Balsam and SET v2 classic CAN binding.""" from .set_uart import number, parse_frame diff --git a/python/logic_analyzer/decoders/set_uart.py b/python/logic_analyzer/decoders/set_uart.py index f871a41..6aa65c4 100644 --- a/python/logic_analyzer/decoders/set_uart.py +++ b/python/logic_analyzer/decoders/set_uart.py @@ -1,3 +1,7 @@ +# Декодирование потоков UART протоколов SET по накопленным байтам. Поиск сигнатуры и проверка +# сообщения должны переживать границу входного фрагмента; неверная контрольная сумма не +# выдаётся как успешный пакет. + """Portable wire readers based on templates/c/set-protocol (no native DLL).""" import binascii diff --git a/python/logic_analyzer/decoders/transistor_pair.py b/python/logic_analyzer/decoders/transistor_pair.py index 851406b..a75c95c 100644 --- a/python/logic_analyzer/decoders/transistor_pair.py +++ b/python/logic_analyzer/decoders/transistor_pair.py @@ -1,3 +1,7 @@ +# Анализ двух комплементарных входов транзисторной пары. Совместное включение, паузы и +# интервалы определяются только по этим входам; ACK/Vstat драйвера не участвуют в данной +# модели. + """Independent complementary transistor input timing; no ACK/Vstat dependency.""" import math from .gate_timing import InputTimingChecker, format_ns diff --git a/python/logic_analyzer/dslogic.py b/python/logic_analyzer/dslogic.py index e64e03b..e486e0a 100644 --- a/python/logic_analyzer/dslogic.py +++ b/python/logic_analyzer/dslogic.py @@ -1,3 +1,7 @@ +# Онлайн-захват DSLogic через отдельный процесс DSView/libsigrok4DSL. Изоляция оставляет +# нативные зависимости драйвера вне основного Qt-приложения; результат процесса затем +# преобразуется в клиентскую модель. + """DSLogic ONLINE through an isolated DSView/libsigrok4DSL host.""" from array import array from dataclasses import dataclass, asdict diff --git a/python/logic_analyzer/dslogic_trigger.py b/python/logic_analyzer/dslogic_trigger.py index f365071..079d5d4 100644 --- a/python/logic_analyzer/dslogic_trigger.py +++ b/python/logic_analyzer/dslogic_trigger.py @@ -1,3 +1,7 @@ +# Проверка и настройка условий запуска DSView без зависимости от Qt/cffi. Представление +# условия проверяется до программирования API, чтобы неверные каналы или комбинации не попали +# в аппаратный захват. + """DSView trigger validation and API programming, independent of Qt/cffi.""" import math diff --git a/python/logic_analyzer/dsview_helper.py b/python/logic_analyzer/dsview_helper.py index e69dea0..01e7ec9 100644 --- a/python/logic_analyzer/dsview_helper.py +++ b/python/logic_analyzer/dsview_helper.py @@ -1,3 +1,7 @@ +# Изолированный процесс драйвера DSView с JSON-запросом и результатом. Ссылки на нативные +# callbacks сохраняются до выхода процесса; сырые CROSS_DATA выгружаются отдельно от +# управляющих метаданных. + """Isolated DSView driver host. JSON request/result files, raw CROSS_DATA spool. Native callbacks and their references live until process exit. Never import diff --git a/python/logic_analyzer/dsview_host.py b/python/logic_analyzer/dsview_host.py index 809cfd6..bdfdd62 100644 --- a/python/logic_analyzer/dsview_host.py +++ b/python/logic_analyzer/dsview_host.py @@ -1,3 +1,7 @@ +# Управление отдельным процессом и окном модифицированного DSView по host protocol 1. Qt, +# Python и libusb DSView остаются внутри дочернего процесса; владелец управляет только своим +# запущенным экземпляром. + """Process boundary for the patched DSView GUI (host protocol 1, Windows). The host owns only its child process/window. Qt 5, Python and libusb remain diff --git a/python/logic_analyzer/files.py b/python/logic_analyzer/files.py index eab2bf0..f8f2939 100644 --- a/python/logic_analyzer/files.py +++ b/python/logic_analyzer/files.py @@ -1,3 +1,6 @@ +# Чтение цифровых захватов с хранением фронтов вместо массива всех выборок. Версия бинарного +# формата проверяется явно; неизвестную раскладку нельзя угадывать по похожему заголовку. + """Digital capture readers. Store edges, never expand captures to sample arrays. DSView layout: DreamSourceLab/DSView libsigrok4DSL/session_driver.c. diff --git a/python/logic_analyzer/sal_metadata.py b/python/logic_analyzer/sal_metadata.py index 710ad06..9ba5250 100644 --- a/python/logic_analyzer/sal_metadata.py +++ b/python/logic_analyzer/sal_metadata.py @@ -1,3 +1,7 @@ +# Шаблон метаданных Logic 2 для цифрового SAL-захвата, schema 22. Метаданные описывают +# контейнер и не заменяют массивы цифровых переходов; версия должна соответствовать формату +# записываемого архива. + """Empty Logic 2 metadata based on the DSLogic_Logic_2 SAL fixture (schema 22).""" from copy import deepcopy diff --git a/python/logic_analyzer/saleae.py b/python/logic_analyzer/saleae.py index 51c2fb6..a20db65 100644 --- a/python/logic_analyzer/saleae.py +++ b/python/logic_analyzer/saleae.py @@ -1,3 +1,6 @@ +# Захват через локальную Logic 2 Automation API. Зависимость от API опциональна; настройка +# сеанса и получение результата отделены от последующего офлайн-разбора цифровых сигналов. + """Local Logic 2 acquisition through the optional Saleae Automation API.""" from __future__ import annotations diff --git a/python/protocan/__init__.py b/python/protocan/__init__.py index 914dd0e..108e82c 100644 --- a/python/protocan/__init__.py +++ b/python/protocan/__init__.py @@ -1,3 +1,7 @@ +# Входная точка пакета protocan. Определяет доступные при импорте имена; подробные контракты +# находятся в специализированных модулях пакета. Изменение реэкспортов влияет на существующие +# import у потребителей. + """Переносимые модули и тонкая Python-обёртка SETProtocol.""" # Consumers may supply additional platform ports from their pinned templates diff --git a/python/protocan/balsam.py b/python/protocan/balsam.py index 6397d36..8b7fef8 100644 --- a/python/protocan/balsam.py +++ b/python/protocan/balsam.py @@ -1,3 +1,6 @@ +# Python-привязка исторического CAN-протокола Balsam к общему C99-ядру. Модуль представляет +# результат в объектах Python; двоичный контракт регистров остаётся в balsam_can. + """Balsam 167 legacy CAN register decoder backed by the shared C99 core.""" from __future__ import annotations diff --git a/python/protocan/can_boot.py b/python/protocan/can_boot.py index e909c8c..8b80446 100644 --- a/python/protocan/can_boot.py +++ b/python/protocan/can_boot.py @@ -1,3 +1,7 @@ +# Клиент A/B-загрузчика ProtoCAN с оконной передачей блоков по восемь байт. Ответы принимаются +# только для целевого адреса и текущей сессии; продвижение по этапам зависит от подтверждения, +# а не от факта отправки. + """Legacy ProtoCAN Boot client ported from Gui_Android CanFirmwareProtocol.kt.""" from __future__ import annotations @@ -66,6 +70,8 @@ class CanBootTransfer: and p.msg_type == 12 and p.pm == 1 and p.device_type == t.device_type and p.device == t.device and p.body >> 8 == t.session_id and len(frame.data) == 8) + # Окно содержит до 16 блоков. Последний неполный блок заполняется 0xFF, + # но метаданные образа сохраняют исходную длину без этого дополнения. def _window(self): total = (len(self.image.data) + 7) // 8 self._window_end = min(total, self.next_block + 16) @@ -78,6 +84,8 @@ class CanBootTransfer: command = ProtoCanId.parse(frame.can_id).body & 255 expected_command = {"enter": 2, "image": 3, "compat": 4, "erase": 5, "data": 0, "verify": 6, "commit": 7, "reboot": 9}.get(self.stage) + # Позднее подтверждение предыдущего этапа нельзя применять к новому: + # оно не продвигает автомат и не считается ошибкой текущего запроса. if command != expected_command: return [], "" status, slot, expected = struct.unpack_from(" RS485. Это не протокол SETGUI (``A5 5A``) из ``protocol.py``, а кадр полевого diff --git a/python/protocan/trends.py b/python/protocan/trends.py index 71b6f38..8110a9b 100644 --- a/python/protocan/trends.py +++ b/python/protocan/trends.py @@ -1,3 +1,7 @@ +# Модели источников и настроек трендов, используемые клиентскими приложениями. Идентификатор +# сигнала связывает историю с источником независимо от имени и порядка; визуальное +# переименование не должно менять физический источник. + """Portable trend configuration shared by SETGUI and Android (no Qt/Android). Numeric CAN decoding uses set_trends.c through NativeTrends. JSON adapters diff --git a/python/set_devices/__init__.py b/python/set_devices/__init__.py index fc6c605..9d6441a 100644 --- a/python/set_devices/__init__.py +++ b/python/set_devices/__init__.py @@ -1 +1,5 @@ +# Входная точка пакета set_devices. Определяет доступные при импорте имена; подробные +# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на +# существующие import у потребителей. + """Reusable device libraries from setcorp/templates.""" diff --git a/python/set_devices/balsam_can.py b/python/set_devices/balsam_can.py index 7b42162..53b7574 100644 --- a/python/set_devices/balsam_can.py +++ b/python/set_devices/balsam_can.py @@ -1,3 +1,7 @@ +# Исторический регистровый CAN-протокол BALZAM/TMS2812. Формат идентификаторов и порядок слов +# относятся именно к этому профилю; общий физический CAN не делает его совместимым с SET v2 +# или протоколом ПМ35. + """GUI-neutral adapter for the shared templates Balsam 167 CAN decoder.""" from __future__ import annotations diff --git a/python/set_devices/bus_demo.py b/python/set_devices/bus_demo.py index 1a49d1d..ee81014 100644 --- a/python/set_devices/bus_demo.py +++ b/python/set_devices/bus_demo.py @@ -1,3 +1,7 @@ +# Демонстрационная модель шины и устройств для интерфейса без оборудования. Синтетические +# ответы служат проверке пользовательского сценария; они не являются измерениями физической +# линии. + """@file bus_demo.py @brief Генератор трафика полевой шины: разбор проверяется без железа. diff --git a/python/set_devices/can485_board.py b/python/set_devices/can485_board.py index 08aa866..c06d3ad 100644 --- a/python/set_devices/can485_board.py +++ b/python/set_devices/can485_board.py @@ -1,3 +1,7 @@ +# Команды и кадры USB-моста CAN485 DevBoard_V1. Преобразование между представлением адаптера и +# CAN отделено от последовательного порта, чтобы один контракт использовался в GUI и проверках +# без устройства. + """@file can485_board.py @brief Плата WeAct CAN485 DevBoard V1 (ESP32): её текстовый вывод и пакеты RS485. diff --git a/python/set_devices/can_bridge.py b/python/set_devices/can_bridge.py index 5fbd009..2ac0add 100644 --- a/python/set_devices/can_bridge.py +++ b/python/set_devices/can_bridge.py @@ -1,3 +1,7 @@ +# Клиентская логика CAN-моста, связывающая команды приложения и кадры адаптера. Транспортная +# оболочка отделена от прикладного протокола устройства, поэтому один мост может обслуживать +# разные профили. + """Служебный уровень моста CAN <-> RS485: его кадры и его регистры. Мост пересылает кадры шины прозрачно, но два вида трафика принадлежат diff --git a/python/set_devices/can_log_trends.py b/python/set_devices/can_log_trends.py index 9e0b5eb..8c33407 100644 --- a/python/set_devices/can_log_trends.py +++ b/python/set_devices/can_log_trends.py @@ -1,3 +1,6 @@ +# Импорт журнала CAN485 в ограниченные по объёму кривые. Каждый канал сохраняет собственные +# временные метки: пропуск сообщения на одном канале не должен искусственно сдвигать другой. + """Convert ESP CAN485 logs into bounded, independently timestamped curves.""" from __future__ import annotations diff --git a/python/set_devices/can_ping.py b/python/set_devices/can_ping.py index 677d363..e717368 100644 --- a/python/set_devices/can_ping.py +++ b/python/set_devices/can_ping.py @@ -1,3 +1,7 @@ +# Адресный PING SETProtocol v2 через сегментированный classic CAN. Ответ сопоставляется с +# ожидаемым обменом; успешная отправка CAN-пакета ещё не подтверждает доступность прикладного +# сервиса. + """Addressed SETProtocol v2 PING exchange over segmented classic CAN.""" from __future__ import annotations diff --git a/python/set_devices/can_transport.py b/python/set_devices/can_transport.py index 086b472..9b2834b 100644 --- a/python/set_devices/can_transport.py +++ b/python/set_devices/can_transport.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +# Потоковый транспорт моста CAN/RS485 с сигнатурой AA 55 и CRC16. Приём может доставлять +# произвольные фрагменты; parser сохраняет незавершённый кадр и отделяет CAN-идентификатор от +# служебных флагов моста. + """Транспортный кадр моста CAN <-> RS485. Это не протокол SETGUI (``A5 5A``) из ``protocol.py``, а кадр полевого diff --git a/python/set_devices/ds18b20.py b/python/set_devices/ds18b20.py index 45a3e5a..2b2478a 100644 --- a/python/set_devices/ds18b20.py +++ b/python/set_devices/ds18b20.py @@ -1,3 +1,7 @@ +# Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и +# настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя +# считать действительным до проверки статуса обмена и CRC. + """@file ds18b20.py @brief Модель и кодеки датчиков DS18B20 на шине 1-Wire STM32F103C8T6. diff --git a/python/set_devices/eeprom.py b/python/set_devices/eeprom.py index de33a89..fc22655 100644 --- a/python/set_devices/eeprom.py +++ b/python/set_devices/eeprom.py @@ -1,3 +1,7 @@ +# Клиентские структуры каталога EEPROM датчиков DS18B20 и экспорт данных. ROM датчика и +# назначенная позиция имеют разный смысл; проверка конфликтов позиций нужна до сохранения +# конфигурации. + """Каталог «датчик — позиция» во внешней EEPROM прибора DS18B20.""" from __future__ import annotations diff --git a/python/set_devices/firmware.py b/python/set_devices/firmware.py index 760a686..1dd655f 100644 --- a/python/set_devices/firmware.py +++ b/python/set_devices/firmware.py @@ -1,3 +1,7 @@ +# Клиентское представление образа и подготовки передачи прошивки. Парсинг и проверки образа +# отделены от физического программатора; этап передачи использует уже проверенные данные и +# метаданные. + """@file firmware.py @brief Проверка образов и переносимая машина блочной передачи прошивки. diff --git a/python/set_devices/gas_catalog.py b/python/set_devices/gas_catalog.py index 510c242..6b44e9c 100644 --- a/python/set_devices/gas_catalog.py +++ b/python/set_devices/gas_catalog.py @@ -1,3 +1,7 @@ +# Описание объектов общего адресного пространства и подписок на значения. Каталог задаёт +# адреса, типы и имена, а пакеты наблюдения несут текущие данные; сборка частей каталога +# должна завершиться до использования всей схемы. + """Каталог общего адресного пространства и поток выбранных значений. Прибор объявляет, какие регистры у него есть и как они называются, GUI diff --git a/python/set_devices/gas_logger.py b/python/set_devices/gas_logger.py index 1aff229..61d3e70 100644 --- a/python/set_devices/gas_logger.py +++ b/python/set_devices/gas_logger.py @@ -1,3 +1,7 @@ +# Клиент согласованных снимков GAS-регистратора и проверка карты сигналов. Скачивание +# выполняется в рабочем потоке транспорта; записи с истёкшим ожиданием нельзя автоматически +# повторять, поскольку устройство уже могло применить команду. + """Experimental GAS recorder map and transport-independent snapshot client. read(address, count) -> words; write(address, value) must await a confirmed @@ -84,7 +88,13 @@ def schema_id(mapping): def c_header(mapping): """Generate the checked-in C mirror; --check in CI catches drift.""" validate_map(mapping) - lines = ['/* Generated from pm35.json. Do not edit. */', + lines = ['/*\n' + ' * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с\n' + ' * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка\n' + ' * даже при успешном обмене.\n' + ' */\n' + '\n' + '/* Generated from pm35.json. Do not edit. */', '#ifndef GL_PM35_MAP_H', '#define GL_PM35_MAP_H', '#include "gas_logger.h"', 'static const gl_channel gl_pm35_channels[] = {'] for c in mapping['channels']: diff --git a/python/set_devices/generator_data.py b/python/set_devices/generator_data.py index 18db39c..c18f667 100644 --- a/python/set_devices/generator_data.py +++ b/python/set_devices/generator_data.py @@ -1,3 +1,7 @@ +# Подготовка точек генератора из встроенных форм, рецептов и CSV. Частота выборок и +# длительность таблицы согласуются с возможностями устройства; импортированные каналы проходят +# явный выбор и ресемплинг. + """Built-in waveforms and CSV input for the point-based signal generator.""" import csv import io diff --git a/python/set_devices/models.py b/python/set_devices/models.py index 12d00dc..2c87047 100644 --- a/python/set_devices/models.py +++ b/python/set_devices/models.py @@ -1,3 +1,7 @@ +# Модели дискретных и числовых сигналов, каталога и снимка состояния. Эти структуры не зависят +# от GUI и контроллера; демонстрационный источник позволяет заполнять их для проверки +# отображения. + """Модель нейтральных сигналов для шаблона без привязки к ТЗ.""" from __future__ import annotations diff --git a/python/set_devices/panel.py b/python/set_devices/panel.py index 7e1c1a1..bbd6e53 100644 --- a/python/set_devices/panel.py +++ b/python/set_devices/panel.py @@ -1,3 +1,7 @@ +# Клиентский протокол удалённого меню: нажатия клавиш, запрос экрана и состояние строк. Ответ +# прибора описывает экран, а не пиксели дисплея; mock-модель воспроизводит взаимодействие без +# реальной платы. + """@file panel.py @brief Зеркало экрана прибора и кнопки его панели. diff --git a/python/set_devices/plot_formula.py b/python/set_devices/plot_formula.py index ac4c8a2..6718466 100644 --- a/python/set_devices/plot_formula.py +++ b/python/set_devices/plot_formula.py @@ -1,3 +1,7 @@ +# Кусочно-полиномиальное описание кривых для математических подписей графика. Коэффициенты +# должны описывать именно отображаемую реконструкцию, включая преобразование нормированных +# координат обратно в единицы осей. + """Local polynomial representation of the curves actually drawn on a plot.""" from dataclasses import dataclass import math diff --git a/python/set_devices/plot_processing.py b/python/set_devices/plot_processing.py index afd5a78..ef4fa9a 100644 --- a/python/set_devices/plot_processing.py +++ b/python/set_devices/plot_processing.py @@ -1,3 +1,7 @@ +# Контракт обработки снимков графика: входные ряды, запрос расчёта и результирующие кривые. +# Вычисленные данные отделены от исходных измерений; численная обработка делегируется общему +# ядру C99. + """Renderer-independent processing contract. Numerical work stays in C99. Adapters publish immutable snapshots in the displayed units. Calculated curves diff --git a/python/set_devices/protocol.py b/python/set_devices/protocol.py index de68959..dcf93a1 100644 --- a/python/set_devices/protocol.py +++ b/python/set_devices/protocol.py @@ -1,3 +1,7 @@ +# Кадрирование исторического GUI protocol v1. Parser накапливает части входного потока и +# проверяет сообщение до выдачи результата; этот формат следует выбирать по профилю +# соединения, а не только по сигнатуре. + """Совместимое с ``lib/gui_transport`` кадрирование GUI protocol v1.""" from __future__ import annotations diff --git a/python/set_devices/protocol_capture.py b/python/set_devices/protocol_capture.py index d1783f9..7b78d36 100644 --- a/python/set_devices/protocol_capture.py +++ b/python/set_devices/protocol_capture.py @@ -1,3 +1,7 @@ +# Ограниченная запись наблюдаемого на хосте трафика и экспорт синтетического логического +# захвата. Время событий отражает наблюдение программой, а не аппаратные фронты; +# перекрывающиеся пакеты одной линии сериализуются. + """Bounded host traffic recording and synthetic DSView v3 logic captures. No hardware timing is inferred: timestamps are host observations and overlapping diff --git a/python/set_devices/protocol_router.py b/python/set_devices/protocol_router.py index 9411d47..32060bf 100644 --- a/python/set_devices/protocol_router.py +++ b/python/set_devices/protocol_router.py @@ -1,3 +1,7 @@ +# Выбор parser для текущего профиля соединения. Только выбранный протокол получает входные +# байты; при смене режима выполняется reset, чтобы хвост старого пакета не попал в новый +# parser. + """Выбор wire-протокола для одного последовательного канала SETGUI. Во время подключения оба потоковых parser-а получают одинаковые байты. Первый diff --git a/python/set_devices/qt_ports/__init__.py b/python/set_devices/qt_ports/__init__.py index fc6c605..0e8813f 100644 --- a/python/set_devices/qt_ports/__init__.py +++ b/python/set_devices/qt_ports/__init__.py @@ -1 +1,5 @@ +# Входная точка пакета set_devices.qt_ports. Определяет доступные при импорте имена; подробные +# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на +# существующие import у потребителей. + """Reusable device libraries from setcorp/templates.""" diff --git a/python/set_devices/qt_ports/candle_adapter.py b/python/set_devices/qt_ports/candle_adapter.py index 5a8e105..8ede2ee 100644 --- a/python/set_devices/qt_ports/candle_adapter.py +++ b/python/set_devices/qt_ports/candle_adapter.py @@ -1,3 +1,7 @@ +# Qt-совместимый транспорт WinUSB для candleLight/gs_usb. Детали ctypes скрыты в адаптере; +# жизненный цикл устройства и канала должен завершаться закрытием ресурсов независимо от +# состояния интерфейса. + """WinUSB transport for candleLight/gs_usb CAN adapters. The native library is the same Candle API used by CANgaroo. This module keeps diff --git a/python/set_devices/qt_ports/f407_usb_bootloader.py b/python/set_devices/qt_ports/f407_usb_bootloader.py index 3243f92..aa49735 100644 --- a/python/set_devices/qt_ports/f407_usb_bootloader.py +++ b/python/set_devices/qt_ports/f407_usb_bootloader.py @@ -1,3 +1,7 @@ +# Асинхронный обновитель односекционного STM32F407 через SET v2 USB. Проверка образа +# предшествует передаче, а продвижение по этапам зависит от ответов загрузчика; интерфейс не +# должен блокироваться ожиданием Flash. + """Asynchronous SET v2 USB updater for the STM32F407VE single-slot port.""" from __future__ import annotations import struct diff --git a/python/set_devices/qt_ports/mock_port.py b/python/set_devices/qt_ports/mock_port.py index e6221a9..d3e542b 100644 --- a/python/set_devices/qt_ports/mock_port.py +++ b/python/set_devices/qt_ports/mock_port.py @@ -1,3 +1,7 @@ +# Qt-порт виртуального устройства для разработки интерфейса без COM-подключения. Сигналы и +# ответы повторяют контракт обычного порта, чтобы UI мог переключать источник без изменения +# обработчиков. + """@file mock_port.py @brief Qt-таймер, имитирующий подключённый контроллер без COM-порта. diff --git a/python/set_devices/qt_ports/plot_annotations.py b/python/set_devices/qt_ports/plot_annotations.py index 44529b8..e3f360c 100644 --- a/python/set_devices/qt_ports/plot_annotations.py +++ b/python/set_devices/qt_ports/plot_annotations.py @@ -1,3 +1,7 @@ +# Отрисовка математических подписей кривых средствами Qt. Выравнивание и координаты текста +# относятся к представлению; сами коэффициенты и данные реконструкции должны приходить из +# модели расчёта. + """Small right-aligned mathematical annotations shared by Qt plots.""" try: from PySide6.QtCore import QRectF, Qt diff --git a/python/set_devices/qt_ports/plot_navigation.py b/python/set_devices/qt_ports/plot_navigation.py index 2c44f4c..70e04e9 100644 --- a/python/set_devices/qt_ports/plot_navigation.py +++ b/python/set_devices/qt_ports/plot_navigation.py @@ -1,3 +1,7 @@ +# Общие жесты клавиатуры и колеса для Qt-графиков. Обработчики переводят пользовательские +# события в изменения области просмотра; настройки осей и сохранение данных остаются в +# владельце графика. + """Common keyboard and wheel gestures for all plot canvases (Qt 5/6).""" try: from PySide6.QtCore import Qt diff --git a/python/set_devices/qt_ports/plot_processing.py b/python/set_devices/qt_ports/plot_processing.py index 307a95d..385de58 100644 --- a/python/set_devices/qt_ports/plot_processing.py +++ b/python/set_devices/qt_ports/plot_processing.py @@ -1,3 +1,7 @@ +# Qt-панель обработки графиков с выполнением расчётов в рабочей задаче. Снимок входных данных +# отделён от живого графика; сигналы доставляют результат обратно в UI для добавления +# самостоятельной вычисленной кривой. + """Reusable Qt processing panel and plot attachment; no SETGUI dependency.""" from __future__ import annotations from dataclasses import replace diff --git a/python/set_devices/qt_ports/port_selection.py b/python/set_devices/qt_ports/port_selection.py index e8516c0..10a282f 100644 --- a/python/set_devices/qt_ports/port_selection.py +++ b/python/set_devices/qt_ports/port_selection.py @@ -1,3 +1,6 @@ +# Единое отображение и выбор последовательного порта в Qt-интерфейсе. Пользовательская подпись +# может содержать описание устройства, но для открытия сохраняется системное имя порта. + """Shared serial-port labels and selection for Qt project interfaces.""" diff --git a/python/set_devices/qt_ports/qt_compat.py b/python/set_devices/qt_ports/qt_compat.py index 952ba94..cdc5a43 100644 --- a/python/set_devices/qt_ports/qt_compat.py +++ b/python/set_devices/qt_ports/qt_compat.py @@ -1,3 +1,7 @@ +# Точка импорта зависимостей Qt для транспортных адаптеров. Базовый пакет устройств не должен +# загружать Qt при обычном импорте: это позволяет использовать переносимые модели в консольных +# инструментах. + """Qt transport dependencies; importing set_devices itself never loads Qt.""" try: from PySide6.QtCore import QObject, Signal, QTimer, QElapsedTimer diff --git a/python/set_devices/qt_ports/serial_port.py b/python/set_devices/qt_ports/serial_port.py index cc1a291..a2a8b78 100644 --- a/python/set_devices/qt_ports/serial_port.py +++ b/python/set_devices/qt_ports/serial_port.py @@ -1,3 +1,7 @@ +# Асинхронный QSerialPort с передачей входных фрагментов потоковому parser. Сигнал readyRead +# не гарантирует целый кадр; открытие, закрытие и ошибки соединения обслуживаются в жизненном +# цикле Qt. + """@file serial_port.py @brief Неблокирующий QSerialPort и потоковый parser GUI transport. diff --git a/python/set_devices/qt_ports/slcan_adapter.py b/python/set_devices/qt_ports/slcan_adapter.py index 1968398..e047202 100644 --- a/python/set_devices/qt_ports/slcan_adapter.py +++ b/python/set_devices/qt_ports/slcan_adapter.py @@ -1,3 +1,7 @@ +# Последовательный транспорт Lawicel/SLCAN для CAN-адаптера. Текстовое представление кодирует +# ID, длину и данные кадра; окончания строк разделяют команды и требуют накопления неполной +# строки. + """Serial Line CAN (Lawicel/SLCAN) transport.""" from __future__ import annotations diff --git a/python/set_devices/qt_ports/stm32_bootloader.py b/python/set_devices/qt_ports/stm32_bootloader.py index 8f69312..6b4d2b2 100644 --- a/python/set_devices/qt_ports/stm32_bootloader.py +++ b/python/set_devices/qt_ports/stm32_bootloader.py @@ -1,3 +1,6 @@ +# Неблокирующий клиент ROM UART-загрузчика STM32. Команды и ACK/NACK обслуживаются +# последовательными состояниями, чтобы ожидание устройства не блокировало цикл Qt. + """Non-blocking client for the STM32 ROM UART bootloader described by AN3155.""" from __future__ import annotations diff --git a/python/set_devices/qt_ports/stm_settings.py b/python/set_devices/qt_ports/stm_settings.py index bbb5bac..3f41bee 100644 --- a/python/set_devices/qt_ports/stm_settings.py +++ b/python/set_devices/qt_ports/stm_settings.py @@ -1,3 +1,7 @@ +# Транзакционное изменение настроек STM через регистровые команды FC03/FC06. Чтение, проверка +# ответа и подтверждение записи составляют один клиентский обмен; отправка запроса не равна +# успешному применению. + """Transactional STM configuration extension (FC03/FC06, 0x1210).""" import struct diff --git a/python/set_devices/qt_ports/tms_bootloader.py b/python/set_devices/qt_ports/tms_bootloader.py index f1451c7..510dffe 100644 --- a/python/set_devices/qt_ports/tms_bootloader.py +++ b/python/set_devices/qt_ports/tms_bootloader.py @@ -1,3 +1,6 @@ +# Неблокирующая последовательность INITLOAD/LOAD/TFLASH для TMS. Ответы и таймауты управляют +# переходами между этапами; размеры блоков и адреса берутся из протокола целевого контроллера. + """Non-blocking port of Gui_Android's INITLOAD / LOAD / TFLASH workflow.""" from .qt_compat import QObject, QTimer, Signal from .qt_compat import QSerialPort diff --git a/python/set_devices/qt_ports/ump_can_client.py b/python/set_devices/qt_ports/ump_can_client.py index 98420a5..c181902 100644 --- a/python/set_devices/qt_ports/ump_can_client.py +++ b/python/set_devices/qt_ports/ump_can_client.py @@ -1,3 +1,6 @@ +# Асинхронный клиент CAN-запросов УМП поверх существующего соединения. Ожидаемый ответ +# привязан к активному запросу; транспортный цикл Qt отделён от модели регистратора. + """Последовательный клиент CAN-логгера поверх уже подключённого Dima-адаптера.""" import secrets from .qt_compat import QObject, QTimer, Signal diff --git a/python/set_devices/qt_ports/wavegen.py b/python/set_devices/qt_ports/wavegen.py index b45b920..a2ede47 100644 --- a/python/set_devices/qt_ports/wavegen.py +++ b/python/set_devices/qt_ports/wavegen.py @@ -1,3 +1,7 @@ +# Рабочий транспорт генератора по USB CDC/COM для WG и блочной загрузки SET v2. Ожидания +# выполняются в рабочем потоке; результаты возвращаются через сигналы, сохраняя отзывчивость +# интерфейса. + """USB CDC/COM worker for WG v1/v2/v3, with SET v2 block uploads. All waits run in a worker, never the GUI thread.""" import time from PySide6.QtCore import QObject, QRunnable, Signal, QIODevice diff --git a/python/set_devices/shared_protocol.py b/python/set_devices/shared_protocol.py index 5083e91..c83fe6a 100644 --- a/python/set_devices/shared_protocol.py +++ b/python/set_devices/shared_protocol.py @@ -1,3 +1,7 @@ +# Точка получения нативного SETProtocol для клиентских модулей. Загрузка отделена от +# пользовательского интерфейса; настройка SETPROTOCOL_LIBRARY выбирает библиотеку, которую +# должны использовать привязки. + """Optional native SETProtocol backend, configured by SETPROTOCOL_LIBRARY.""" from __future__ import annotations diff --git a/python/set_devices/signal_reconstruction.py b/python/set_devices/signal_reconstruction.py index 3172526..470c031 100644 --- a/python/set_devices/signal_reconstruction.py +++ b/python/set_devices/signal_reconstruction.py @@ -1,3 +1,7 @@ +# Тонкий адаптер реконструкции сигнала и преобразования напряжений в коды ЦАП. Массивы и +# рабочая память подготавливаются в Python, а численный алгоритм и проверки диапазонов +# выполняет общее C-ядро. + """Thin host adapter for the shared C99 reconstruction/DAC algorithms.""" from __future__ import annotations import ctypes as C diff --git a/python/set_devices/spectrum_demo.py b/python/set_devices/spectrum_demo.py index 47878fa..d170cbd 100644 --- a/python/set_devices/spectrum_demo.py +++ b/python/set_devices/spectrum_demo.py @@ -1,3 +1,7 @@ +# Демонстрационный источник спектра и гармоник для проверки интерфейса без STM32. Управляемые +# частоты и амплитуды позволяют увидеть реакцию графика; эти данные не следует смешивать с +# реальными измерениями. + """@file spectrum_demo.py @brief Демонстрационный источник спектра для проверки вкладки без прибора. diff --git a/python/set_devices/spectrum_stream.py b/python/set_devices/spectrum_stream.py index e6578d0..4dceb64 100644 --- a/python/set_devices/spectrum_stream.py +++ b/python/set_devices/spectrum_stream.py @@ -1,3 +1,7 @@ +# Разбор строкового потока спектра и гармоник STM32. Строка должна быть получена целиком и +# пройти проверку до выдачи кадра; накопитель учитывает, что чтение порта может завершиться +# посреди строки. + """@file spectrum_stream.py @brief Разбор потока спектра и гармоник от прибора на STM32. diff --git a/python/set_devices/tektronix.py b/python/set_devices/tektronix.py index 408d977..e6f2569 100644 --- a/python/set_devices/tektronix.py +++ b/python/set_devices/tektronix.py @@ -1,3 +1,7 @@ +# Получение осциллограмм Tektronix DPO4034 через SCPI/VISA. Параметры масштаба из прибора +# переводят сырые отсчёты в физические значения; выбор VISA-ресурса отделён от графического +# интерфейса. + """DPO4034 SCPI acquisition over VISA (GPIB or Ethernet), without Qt. See docs/tektronix-dpo4034.md for wiring, commands and scaling. diff --git a/python/set_devices/tms_flash.py b/python/set_devices/tms_flash.py index 433ed75..3497458 100644 --- a/python/set_devices/tms_flash.py +++ b/python/set_devices/tms_flash.py @@ -1,3 +1,7 @@ +# Планирование дампа внешней памяти TMS и сборка ответов CMD_UPLOAD. Адреса XINTF считаются +# 16-битными словами, размер передачи — байтами; прогресс и смещение рассчитываются с явным +# переводом единиц. + """Legacy BALZAM/TMS parallel-memory dump protocol. The TMS320F2812 addresses external XINTF memory in 16-bit words, while diff --git a/python/set_devices/tms_terminal.py b/python/set_devices/tms_terminal.py index 6af9afb..d51f17a 100644 --- a/python/set_devices/tms_terminal.py +++ b/python/set_devices/tms_terminal.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +# Обмен с историческим терминалом TMS. Формат обычных ответов и телеметрии зависит от +# используемого адаптера; состояние parser сохраняется между фрагментами, а профиль +# контроллера выбирается вызывающим приложением. + """Посылка ПЧ -> терминал прошивки ТМС (``TMS_TO_TERMINAL``). Это третий формат в проекте: не протокол SETGUI (``A5 5A``) из ``protocol.py`` diff --git a/python/set_devices/ump_logger.py b/python/set_devices/ump_logger.py index 01004d7..048d407 100644 --- a/python/set_devices/ump_logger.py +++ b/python/set_devices/ump_logger.py @@ -1,3 +1,7 @@ +# Клиент регистратора УМП v2 с выбором аналоговых каналов и чтением снимка. Индексы каналов и +# регистровые адреса разделены; отображение результата не должно менять порядок слов принятого +# снимка. + """Протокол кольцевого логгера УМП v2. Технологические регистры 0..127 не изменены. Расширение 0x1000 сначала diff --git a/python/set_devices/ump_logger_can.py b/python/set_devices/ump_logger_can.py index b9843da..08b98cc 100644 --- a/python/set_devices/ump_logger_can.py +++ b/python/set_devices/ump_logger_can.py @@ -1,3 +1,7 @@ +# CAN-представление запросов регистратора periph_28335. Идентификаторы запросов и ответов +# зависят от режима; обратное преобразование выполняется по этому контракту, а не по формату +# общего моста. + """CAN-транспорт расширения регистратора periph_28335. Служебные запросы идут на штатный RX ID платы 0xBA0000 + Mode - 1. diff --git a/python/set_devices/ump_logger_demo.py b/python/set_devices/ump_logger_demo.py index b31d0e8..0796372 100644 --- a/python/set_devices/ump_logger_demo.py +++ b/python/set_devices/ump_logger_demo.py @@ -1,3 +1,7 @@ +# Синтетический снимок регистратора УМП для работы GUI без контроллера. Данные формируются в +# ожидаемом представлении клиента, чтобы проверять выбор каналов и отображение одной и той же +# моделью. + """Синтетические записи УМП для проверки графиков без подключения платы.""" import math diff --git a/python/set_devices/waveform.py b/python/set_devices/waveform.py index 09abdb0..6660730 100644 --- a/python/set_devices/waveform.py +++ b/python/set_devices/waveform.py @@ -1,3 +1,7 @@ +# Рецепты и таблицы периодических сигналов для генератора. Интерполяция и квантование +# передаются общему ядру; экспорт таблицы сохраняет подготовленный порядок отсчётов для +# циклического воспроизведения. + """Reusable recipes and tables; interpolation/quantization live in C.""" from __future__ import annotations import math diff --git a/python/set_devices/wavegen_protocol.py b/python/set_devices/wavegen_protocol.py index 18f57b3..0dce33b 100644 --- a/python/set_devices/wavegen_protocol.py +++ b/python/set_devices/wavegen_protocol.py @@ -1,3 +1,6 @@ +# ctypes-привязка RTU-кодека генератора сигналов. Модуль преобразует аргументы и результаты, а +# построение запросов и проверка ответов выполняются общей реализацией set_wavegen. + """ctypes port of the shared wave generator RTU codec.""" import ctypes as C from .signal_reconstruction import library diff --git a/python/setprotocol/__init__.py b/python/setprotocol/__init__.py index fc0d384..f887014 100644 --- a/python/setprotocol/__init__.py +++ b/python/setprotocol/__init__.py @@ -1,3 +1,7 @@ +# Входная точка пакета setprotocol. Определяет доступные при импорте имена; подробные +# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на +# существующие import у потребителей. + """Cross-platform Python facade for the canonical SETProtocol core.""" from .core import * # noqa: F401,F403 diff --git a/python/setprotocol/can.py b/python/setprotocol/can.py index 30c0e6d..b9585f6 100644 --- a/python/setprotocol/can.py +++ b/python/setprotocol/can.py @@ -1,3 +1,7 @@ +# Сегментация кадров SETProtocol v2 в classic CAN: первый пакет несёт длину и пять байт +# данных, последующие — номер и до семи байт. Сборщик обслуживает один источник и канал; +# таймаут или нарушение последовательности сбрасывает неполный кадр. + """Classic-CAN segmentation for canonical SETProtocol v2 frames.""" from __future__ import annotations @@ -90,6 +94,8 @@ def segment(packet: bytes, address: CanAddress) -> list[CanFrame]: + packet[:FIRST_DATA_SIZE], ) ] + # Номер занимает младшую тетраду PCI и циклически переходит 15 -> 0. + # Он проверяет порядок фрагментов, но не является полным номером блока. sequence = 1 for offset in range(FIRST_DATA_SIZE, len(packet), CONSECUTIVE_DATA_SIZE): chunk = packet[offset : offset + CONSECUTIVE_DATA_SIZE] @@ -115,6 +121,8 @@ class CanReassembler: self._next_sequence = 1 def feed(self, frame: CanFrame, now_ms: int) -> bytes | None: + # now_ms должен поступать из одной монотонной шкалы времени клиента. + # Таймаут относится к интервалу между принятыми сегментами. if self._can_id is not None and now_ms >= self._deadline_ms: self.reset() raise SetProtocolError("таймаут сборки SETProtocol CAN") @@ -125,6 +133,8 @@ class CanReassembler: total = int.from_bytes(frame.data[1:3], "little") if not HEADER_SIZE + CRC_SIZE <= total <= FRAME_MAX: raise SetProtocolError("неверная полная длина SETP CAN") + # FIRST начинает новую сборку, заменяя ранее накопленный хвост. + # Сохраняем полный CAN ID, чтобы не смешать источники и каналы. self._buffer = bytearray(frame.data[3:]) self._expected_length = total self._can_id = frame.can_id @@ -151,6 +161,8 @@ class CanReassembler: self._deadline_ms = now_ms + self.timeout_ms if len(self._buffer) != self._expected_length: return None + # Создаём независимый неизменяемый результат до сброса контекста. + # Проверка согласованности адресов ниже уже не удерживает сборку. packet = bytes(self._buffer) can_id = self._can_id self.reset() @@ -167,6 +179,8 @@ class CanReassembler: or priority != address.priority ): raise SetProtocolError("SETP header не совпадает с CAN ID") + # Здесь проверена транспортная сборка. CRC самого SET-кадра + # проверяет следующий слой декодирования протокола. return packet if pci == PCI_FLOW_CONTROL: return None diff --git a/python/setprotocol/core.py b/python/setprotocol/core.py index 77caa6d..70dcba8 100644 --- a/python/setprotocol/core.py +++ b/python/setprotocol/core.py @@ -1,3 +1,7 @@ +# Основной бинарный формат SETProtocol v2: поля кадра, контрольная сумма и потоковый parser. +# Числа сериализуются явно, поэтому выравнивание C-структур не влияет на байты линии; +# транспорт передаёт готовые массивы. + """Эталонная Python-реализация SET protocol v2. Источник wire-контракта находится в ``templates/c/set-protocol/PROTOCOL.md``. diff --git a/python/setprotocol/firmware_catalog.py b/python/setprotocol/firmware_catalog.py index ab7da72..462fed3 100644 --- a/python/setprotocol/firmware_catalog.py +++ b/python/setprotocol/firmware_catalog.py @@ -1,3 +1,7 @@ +# Модель каталога firmware.releases и проверка записей update.json. Метаданные выпуска +# описывают совместимость и расположение образа; выбор записи и последующее скачивание +# являются отдельными операциями. + """Shared firmware release catalog contract from ``update.json``.""" from __future__ import annotations diff --git a/python/setprotocol/firmware_database.py b/python/setprotocol/firmware_database.py index 276d82f..7eef308 100644 --- a/python/setprotocol/firmware_database.py +++ b/python/setprotocol/firmware_database.py @@ -1,3 +1,7 @@ +# Самостоятельный доступ к базе прошивок: HTTPS, проверяемая загрузка, кэш и публикация в +# Gitea. Проверка SHA-256 связывает скачанные байты с записью каталога; сетевые полномочия +# передаются явно через клиент. + """Standalone firmware database: HTTPS catalog, verified downloads and Gitea publishing. No Qt, desktop application, credential store or MCU dependencies. diff --git a/python/setprotocol/firmware_publish.py b/python/setprotocol/firmware_publish.py index c1f86a2..d618933 100644 --- a/python/setprotocol/firmware_publish.py +++ b/python/setprotocol/firmware_publish.py @@ -1,3 +1,7 @@ +# Общие правила метаданных публикации прошивки: SHA-256, release tag и обновление каталога. +# Формирование записи отделено от сетевой загрузки; идентичность выпуска нужна для +# предсказуемой замены существующей записи. + """Reusable helpers for publishing the shared firmware release catalog.""" from __future__ import annotations diff --git a/python/tests/test_altera_logic.py b/python/tests/test_altera_logic.py index 55d86d9..94c28d5 100644 --- a/python/tests/test_altera_logic.py +++ b/python/tests/test_altera_logic.py @@ -1,3 +1,12 @@ +# Проверки altera_logic: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_rtl_info_and_first_configuration_vector +# test_error_response_is_short_even_for_info +# test_partial_response_times_out_without_retry +# test_demo_export_uses_capture_rate_not_current_ui_settings +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Golden RTL vectors through the Python FFI (no Python production codec).""" import tempfile import unittest diff --git a/python/tests/test_altera_stream.py b/python/tests/test_altera_stream.py index a312f5a..3f20a30 100644 --- a/python/tests/test_altera_stream.py +++ b/python/tests/test_altera_stream.py @@ -1,3 +1,13 @@ +# Проверки altera_stream: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_can_uart_identical_and_duplicates +# test_gap_old_session_and_counter_wrap +# test_malformed_filter_crc_and_recovery +# test_bounded_history_and_export +# test_sparse_trace_does_not_connect_across_lost_samples +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import tempfile import unittest from pathlib import Path diff --git a/python/tests/test_devboard_v1.py b/python/tests/test_devboard_v1.py index c9ff90b..17cdcd2 100644 --- a/python/tests/test_devboard_v1.py +++ b/python/tests/test_devboard_v1.py @@ -1,3 +1,10 @@ +# Проверки devboard_v1: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_parse_can_and_rs485_lines +# test_commands_are_firmware_compatible_and_lf_terminated +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from protocan.devboard_v1 import BoardFrame, command_setup, command_transmit, parse_frame_line diff --git a/python/tests/test_dslogic_trigger.py b/python/tests/test_dslogic_trigger.py index 5cca789..2645d7f 100644 --- a/python/tests/test_dslogic_trigger.py +++ b/python/tests/test_dslogic_trigger.py @@ -1,3 +1,13 @@ +# Проверки dslogic_trigger: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_invalid_modes_and_disabled_conditions +# test_simple_maps_physical_channels_and_stream_position +# test_stage_count_logic_and_masks_match_driver_abi +# test_serial_mapping_and_data_channel_validation +# test_driver_errors_propagate +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import unittest from dataclasses import replace from unittest.mock import Mock diff --git a/python/tests/test_firmware_clients.py b/python/tests/test_firmware_clients.py index e829ff7..ced0d52 100644 --- a/python/tests/test_firmware_clients.py +++ b/python/tests/test_firmware_clients.py @@ -1,3 +1,16 @@ +# Проверки firmware_clients: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_android_packet_layout_and_crc +# test_only_reserved_tail_may_be_missing +# test_tms_word_offsets_and_odd_final_byte_readback +# test_peripheral_flashing_and_verification +# test_load_only_never_writes_flash +# test_invalid_targets_fail_before_transmission +# test_legacy_can_full_transaction_and_retransmission +# test_can_rejects_unsent_blocks_wrong_slot_and_foreign_session +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Android wire compatibility and complete host-side flashing transactions.""" from dataclasses import replace from types import SimpleNamespace diff --git a/python/tests/test_firmware_database.py b/python/tests/test_firmware_database.py index 63497a7..fe026cf 100644 --- a/python/tests/test_firmware_database.py +++ b/python/tests/test_firmware_database.py @@ -1,3 +1,17 @@ +# Проверки firmware_database: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_publish_read_and_download_round_trip_and_idempotency +# test_failed_image_verification_never_writes_catalog +# test_rebuilt_image_keeps_old_asset_and_manifest_on_conflict +# test_preflight_is_offline +# test_missing_release_is_created +# test_download_size_limit_and_catalog_readback_failure +# test_bad_download_cleans_staging_and_rejects_unsafe_filename +# test_https_credentials_do_not_follow_cross_origin_redirect +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from __future__ import annotations import base64 diff --git a/python/tests/test_firmware_publish.py b/python/tests/test_firmware_publish.py index a50b354..366a77e 100644 --- a/python/tests/test_firmware_publish.py +++ b/python/tests/test_firmware_publish.py @@ -1,3 +1,12 @@ +# Проверки firmware_publish: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_publication_validates_file_and_metadata +# test_entry_and_tag_are_deterministic +# test_update_preserves_sections_and_replaces_same_release +# test_legacy_array_is_migrated_without_data_loss +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from __future__ import annotations import tempfile diff --git a/python/tests/test_generator_data.py b/python/tests/test_generator_data.py index 1782f54..07b1fdd 100644 --- a/python/tests/test_generator_data.py +++ b/python/tests/test_generator_data.py @@ -1,3 +1,10 @@ +# Проверки generator_data: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_processing_csv_roundtrip_into_generator +# test_samples_recipe_and_resampling +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Waveform data helpers run independently of SETGUI and Qt.""" import io import json diff --git a/python/tests/test_legacycan.py b/python/tests/test_legacycan.py index ae3c004..5d464f6 100644 --- a/python/tests/test_legacycan.py +++ b/python/tests/test_legacycan.py @@ -1,3 +1,11 @@ +# Проверки legacycan: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_catalog_matches_legacy_projects +# test_rotating_three_word_codec_and_bank +# test_address_in_identifier_codec_and_command +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from protocan.legacycan import ( LegacyCanFormat, LegacyCanSource, PROJECTS, apply_packet, decode, empty_register_bank, encode_command, encode_write, signed_word, diff --git a/python/tests/test_logic_analyzer_analysis.py b/python/tests/test_logic_analyzer_analysis.py index 56f396d..8126e0e 100644 --- a/python/tests/test_logic_analyzer_analysis.py +++ b/python/tests/test_logic_analyzer_analysis.py @@ -1,3 +1,18 @@ +# Проверки logic_analyzer_analysis: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_uart_byte_values_inverted_and_parity +# test_uart_errors_are_not_accepted_as_set_frames +# test_set_ping_bridge_crc_and_resynchronization +# test_pm35_request_and_special_response +# test_uart_end_flush_and_gap +# test_crc15_known_check_value +# test_can_standard_extended_remote_and_nack +# test_can_crc_error_recovery_and_application +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from array import array from collections import Counter from pathlib import Path diff --git a/python/tests/test_logic_analyzer_dslogic.py b/python/tests/test_logic_analyzer_dslogic.py index 95ae396..a781823 100644 --- a/python/tests/test_logic_analyzer_dslogic.py +++ b/python/tests/test_logic_analyzer_dslogic.py @@ -1,3 +1,18 @@ +# Проверки logic_analyzer_dslogic: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_cross_words_preserve_physical_channels_boundary_edges_and_tail +# test_padding_is_not_imported_as_samples +# test_empty_truncated_wrong_mapping_and_cancel +# test_validation_rejects_old_driver_and_invalid_parameters +# test_host_does_not_inherit_frozen_gui_bootloader_state +# test_real_process_scan +# test_stop_is_graceful_and_imports_result +# test_cancel_reaps_process_and_discards_result +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from dataclasses import replace from io import BytesIO import json diff --git a/python/tests/test_logic_analyzer_files.py b/python/tests/test_logic_analyzer_files.py index aed5ccf..0474b60 100644 --- a/python/tests/test_logic_analyzer_files.py +++ b/python/tests/test_logic_analyzer_files.py @@ -1,3 +1,16 @@ +# Проверки logic_analyzer_files: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_csv_preserves_irregular_time_and_channel_names +# test_dsview_csv_metadata_and_units +# test_csv_rejects_invalid_data +# test_sal_chunks_levels_and_long_runs +# test_sal_rejects_truncated_and_unknown_version +# test_dsl_sparse_channels_blocks_and_padding +# test_cancelled_import +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import csv import json from pathlib import Path diff --git a/python/tests/test_logic_analyzer_saleae.py b/python/tests/test_logic_analyzer_saleae.py index 1920f87..14ec3b5 100644 --- a/python/tests/test_logic_analyzer_saleae.py +++ b/python/tests/test_logic_analyzer_saleae.py @@ -1,3 +1,14 @@ +# Проверки logic_analyzer_saleae: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_constant_channel_tail_and_sparse_channel_numbers +# test_reject_bad_binary_and_cancel +# test_settings_validation +# test_stop_exports_and_closes_exactly_once +# test_cancel_stops_without_export_and_failure_closes +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from dataclasses import replace from pathlib import Path import struct diff --git a/python/tests/test_logic_csv_import.py b/python/tests/test_logic_csv_import.py index 2d87966..2f8f3b8 100644 --- a/python/tests/test_logic_csv_import.py +++ b/python/tests/test_logic_csv_import.py @@ -1,3 +1,16 @@ +# Проверки logic_csv_import: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_regular_samples_preserve_levels_and_names +# test_sparse_transitions_preserve_short_pulses_across_blocks +# test_initial_snapshot_need_not_be_on_edge_clock +# test_comments_tab_delimiter_and_negative_origin +# test_bad_csv_leaves_no_output +# test_output_is_not_overwritten_and_size_limit_precedes_expansion +# test_cancel_during_packing_cleans_temporary_output +# test_changed_source_rejected_before_publication +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from decimal import Decimal from pathlib import Path import tempfile diff --git a/python/tests/test_periph28335.py b/python/tests/test_periph28335.py index 5338089..601213d 100644 --- a/python/tests/test_periph28335.py +++ b/python/tests/test_periph28335.py @@ -1,3 +1,11 @@ +# Проверки periph28335: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_read_request_matches_delphi_byte_order +# test_write_and_command_use_register_127 +# test_bits_keep_original_lsb_first_order +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from protocan.periph28335 import ( bits_lsb_first, build_command, build_read_registers, build_write_register, crc16_modbus, word_from_bits, diff --git a/python/tests/test_plot.py b/python/tests/test_plot.py index ba3281f..142b547 100644 --- a/python/tests/test_plot.py +++ b/python/tests/test_plot.py @@ -1,3 +1,12 @@ +# Проверки plot: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_shared_numeric_fixtures +# test_markers_stay_in_data_coordinates_and_cross +# test_invalid_numeric_inputs_do_not_escape_to_painter +# test_locked_viewport_and_decibel_delta +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Cross-port contract: Python/ctypes and Kotlin/JNI consume the same fixtures.""" import ctypes import json diff --git a/python/tests/test_plot_formula.py b/python/tests/test_plot_formula.py index e30915d..b298b43 100644 --- a/python/tests/test_plot_formula.py +++ b/python/tests/test_plot_formula.py @@ -1,3 +1,11 @@ +# Проверки plot_formula: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_all_methods_match_native_values_on_irregular_and_duplicate_knots +# test_polynomial_model_with_fewer_output_samples_than_coefficients +# test_source_line_and_formula_use_displayed_origin +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Formula coefficients must reproduce the native reconstruction, not a refit.""" import unittest from set_devices.signal_reconstruction import reconstruct diff --git a/python/tests/test_plot_processing.py b/python/tests/test_plot_processing.py index 5a3f7bf..37cd575 100644 --- a/python/tests/test_plot_processing.py +++ b/python/tests/test_plot_processing.py @@ -1,3 +1,14 @@ +# Проверки plot_processing: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_snapshot_copies_mutable_samples_and_excludes_hidden_and_digital +# test_all_methods_use_same_contract_and_keep_source +# test_window_is_inclusive_and_never_extrapolates +# test_sparse_spline_and_noisy_polynomial_work_in_shared_pipeline +# test_csv_respects_explicit_axis_domain_and_units +# test_request_tracks_selected_channel_units_source_and_window +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Portable processing contract: no Qt or application imports.""" import csv import io diff --git a/python/tests/test_plot_processing_qt.py b/python/tests/test_plot_processing_qt.py index d846863..b0194e8 100644 --- a/python/tests/test_plot_processing_qt.py +++ b/python/tests/test_plot_processing_qt.py @@ -1,3 +1,18 @@ +# Проверки plot_processing_qt: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_all_methods_accumulate_and_parameter_changes_keep_results +# test_repeated_request_does_not_duplicate_curve +# test_repeated_fft_workers_keep_gui_owned_signal_emitters +# test_switching_channel_preserves_results_and_invalidates_only_changed_source +# test_navigation_during_second_calculation_preserves_both_results +# test_failed_calculation_keeps_previous_curve +# test_hidden_source_preserves_result_but_changed_samples_invalidate_it +# test_source_units_and_blocking_invalidate_result +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Reusable Qt adapter tests, runnable with PySide2 or PySide6, without a GUI app repo.""" import os os.environ.setdefault("QT_QPA_PLATFORM", "offscreen") diff --git a/python/tests/test_setprotocol_can.py b/python/tests/test_setprotocol_can.py index e288286..762507f 100644 --- a/python/tests/test_setprotocol_can.py +++ b/python/tests/test_setprotocol_can.py @@ -1,3 +1,11 @@ +# Проверки setprotocol_can: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_can_id_roundtrip +# test_segmented_setp_frame_roundtrip +# test_reassembler_rejects_wrong_sequence +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + from setprotocol import Frame, FrameFlag, MessageType, build_frame, decode_datagram from setprotocol.can import CanAddress, CanFrame, CanReassembler, segment diff --git a/python/tests/test_shared_library_boundary.py b/python/tests/test_shared_library_boundary.py index cb3f4bb..7bd3ea3 100644 --- a/python/tests/test_shared_library_boundary.py +++ b/python/tests/test_shared_library_boundary.py @@ -1,3 +1,11 @@ +# Проверки shared_library_boundary: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_cores_import_with_gui_and_qt_blocked +# test_no_reverse_imports_in_sources +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Shared libraries must import without the desktop application or Qt.""" import os from pathlib import Path diff --git a/python/tests/test_spectrum.py b/python/tests/test_spectrum.py index 60be5ac..6310265 100644 --- a/python/tests/test_spectrum.py +++ b/python/tests/test_spectrum.py @@ -1,3 +1,16 @@ +# Проверки spectrum: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_fft_matches_independent_direct_dft +# test_all_windows_preserve_bin_centered_peak_amplitude +# test_dc_and_nyquist_are_not_doubled +# test_windows_suppress_far_leakage_and_flattop_recovers_off_bin_amplitude +# test_filters_attenuate_expected_bands +# test_timestamp_rate_not_requested_rate_and_jitter_interpolation +# test_rejects_gaps_duplicates_bad_values_and_cutoffs +# test_size_limits_tail_selection_and_inputs_unchanged +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import cmath import ctypes import math diff --git a/python/tests/test_tms_terminal_shared.py b/python/tests/test_tms_terminal_shared.py index 18ef1d5..1a8c095 100644 --- a/python/tests/test_tms_terminal_shared.py +++ b/python/tests/test_tms_terminal_shared.py @@ -1,3 +1,14 @@ +# Проверки tms_terminal_shared: фиксируют ожидаемое поведение на воспроизводимых входных +# данных. +# Сценарии для навигации по файлу: +# test_ping_and_poke_vectors +# test_test_all_vector +# test_response_accepts_only_missing_reserved_bytes +# test_rejects_out_of_range_before_native_conversion +# test_uart_response_ignores_noise_and_preliminary_ack +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Wire vectors shared with Android and the native TMS2812 host test.""" import pytest from protocan import tms_terminal as tms diff --git a/python/tests/test_trends.py b/python/tests/test_trends.py index 3613823..78337a0 100644 --- a/python/tests/test_trends.py +++ b/python/tests/test_trends.py @@ -1,3 +1,16 @@ +# Проверки trends: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_multiplier_and_iq_scale_display_and_old_json_defaults +# test_shared_kotlin_fixture_and_round_trip +# test_profile_specific_defaults +# test_invalid_import_and_types +# test_duplicates_and_limits +# test_addresses_and_signedness +# test_bounded_history +# test_actual_shared_c_core +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import ctypes import json import os diff --git a/tools/dsview/build.py b/tools/dsview/build.py index 860f555..9e1b36c 100644 --- a/tools/dsview/build.py +++ b/tools/dsview/build.py @@ -1,3 +1,7 @@ +# Сборка и упаковка модифицированного DSView на существующем MSYS2 UCRT64. Хеш рецепта +# помогает определить актуальность runtime; декодеры включаются в пакет вместе с поддержкой +# host protocol 1. + """Build and package DSView host protocol 1 using an existing MSYS2 UCRT64 SDK.""" import argparse import hashlib diff --git a/tools/dsview/decoders/gate_driver_timing/__init__.py b/tools/dsview/decoders/gate_driver_timing/__init__.py index d0a29e0..df9ad63 100644 --- a/tools/dsview/decoders/gate_driver_timing/__init__.py +++ b/tools/dsview/decoders/gate_driver_timing/__init__.py @@ -1,3 +1,7 @@ +# Точка обнаружения декодера gate_driver_timing в DSView/libsigrokdecode. Экспорт класса +# Decoder из pd.py позволяет загрузчику зарегистрировать плагин; сам разбор потока выполняется +# в модуле декодера. + """DSView protocol decoder for SCALE gate-driver timing checks.""" from .pd import Decoder diff --git a/tools/dsview/decoders/gate_driver_timing/pd.py b/tools/dsview/decoders/gate_driver_timing/pd.py index 5b59ec8..4c34b38 100644 --- a/tools/dsview/decoders/gate_driver_timing/pd.py +++ b/tools/dsview/decoders/gate_driver_timing/pd.py @@ -1,3 +1,9 @@ +# Проверка временных характеристик драйвера затвора по цифровым фронтам. Параметры профилей +# задаются в наносекундах; типичная задержка ACK используется для предупреждения, а +# нормированная длительность импульса — для PASS/FAIL. Этот адаптер переводит события +# libsigrokdecode в аннотации DSView; координаты выборок пересчитываются с учётом частоты +# захвата. + """DSView/libsigrokdecode front end for SCALE gate-driver timing checks.""" import sigrokdecode as srd diff --git a/tools/dsview/decoders/pm35_uart/__init__.py b/tools/dsview/decoders/pm35_uart/__init__.py index e99f16b..6325acb 100644 --- a/tools/dsview/decoders/pm35_uart/__init__.py +++ b/tools/dsview/decoders/pm35_uart/__init__.py @@ -1 +1,5 @@ +# Точка обнаружения декодера pm35_uart в DSView/libsigrokdecode. Экспорт класса Decoder из +# pd.py позволяет загрузчику зарегистрировать плагин; сам разбор потока выполняется в модуле +# декодера. + from .pd import Decoder diff --git a/tools/dsview/decoders/pm35_uart/pd.py b/tools/dsview/decoders/pm35_uart/pd.py index 2922af5..272caf9 100644 --- a/tools/dsview/decoders/pm35_uart/pd.py +++ b/tools/dsview/decoders/pm35_uart/pd.py @@ -1,3 +1,8 @@ +# Декодирование UART-обмена ПМ35 с командами Modbus 03/06. Учитывается исторический ответ на +# 128 слов с нулевым полем числа байтов; универсальный Modbus-parser без этого правила +# потеряет границу сообщения. Этот адаптер переводит события libsigrokdecode в аннотации +# DSView; координаты выборок пересчитываются с учётом частоты захвата. + import sigrokdecode as srd from common.setgui_decoders.pm35_uart import PM35Parser diff --git a/tools/dsview/decoders/set_can/__init__.py b/tools/dsview/decoders/set_can/__init__.py index e99f16b..2ceef70 100644 --- a/tools/dsview/decoders/set_can/__init__.py +++ b/tools/dsview/decoders/set_can/__init__.py @@ -1 +1,5 @@ +# Точка обнаружения декодера set_can в DSView/libsigrokdecode. Экспорт класса Decoder из pd.py +# позволяет загрузчику зарегистрировать плагин; сам разбор потока выполняется в модуле +# декодера. + from .pd import Decoder diff --git a/tools/dsview/decoders/set_can/pd.py b/tools/dsview/decoders/set_can/pd.py index 0a775e5..40b84b6 100644 --- a/tools/dsview/decoders/set_can/pd.py +++ b/tools/dsview/decoders/set_can/pd.py @@ -1,3 +1,8 @@ +# Сегментация SET v2 и интерпретация CAN-данных зависят от выбранного слоя. Адрес и номер +# сегмента должны проверяться до объединения данных; classic CAN-пакет ограничен восемью +# байтами. Этот адаптер переводит события libsigrokdecode в аннотации DSView; координаты +# выборок пересчитываются с учётом частоты захвата. + import sigrokdecode as srd from common.setgui_decoders.set_can import Reassembler, legacy diff --git a/tools/dsview/decoders/set_uart/__init__.py b/tools/dsview/decoders/set_uart/__init__.py index e99f16b..3ce15ea 100644 --- a/tools/dsview/decoders/set_uart/__init__.py +++ b/tools/dsview/decoders/set_uart/__init__.py @@ -1 +1,5 @@ +# Точка обнаружения декодера set_uart в DSView/libsigrokdecode. Экспорт класса Decoder из +# pd.py позволяет загрузчику зарегистрировать плагин; сам разбор потока выполняется в модуле +# декодера. + from .pd import Decoder diff --git a/tools/dsview/decoders/set_uart/pd.py b/tools/dsview/decoders/set_uart/pd.py index e2e0645..4401c19 100644 --- a/tools/dsview/decoders/set_uart/pd.py +++ b/tools/dsview/decoders/set_uart/pd.py @@ -1,3 +1,8 @@ +# Декодирование потоков UART протоколов SET по накопленным байтам. Поиск сигнатуры и проверка +# сообщения должны переживать границу входного фрагмента; неверная контрольная сумма не +# выдаётся как успешный пакет. Этот адаптер переводит события libsigrokdecode в аннотации +# DSView; координаты выборок пересчитываются с учётом частоты захвата. + import sigrokdecode as srd from common.setgui_decoders.set_uart import StreamParser diff --git a/tools/dsview/decoders/transistor_pair/__init__.py b/tools/dsview/decoders/transistor_pair/__init__.py index e99f16b..453d320 100644 --- a/tools/dsview/decoders/transistor_pair/__init__.py +++ b/tools/dsview/decoders/transistor_pair/__init__.py @@ -1 +1,5 @@ +# Точка обнаружения декодера transistor_pair в DSView/libsigrokdecode. Экспорт класса Decoder +# из pd.py позволяет загрузчику зарегистрировать плагин; сам разбор потока выполняется в +# модуле декодера. + from .pd import Decoder diff --git a/tools/dsview/decoders/transistor_pair/pd.py b/tools/dsview/decoders/transistor_pair/pd.py index a5b1f2f..67b74c4 100644 --- a/tools/dsview/decoders/transistor_pair/pd.py +++ b/tools/dsview/decoders/transistor_pair/pd.py @@ -1,3 +1,8 @@ +# Анализ двух комплементарных входов транзисторной пары. Совместное включение, паузы и +# интервалы определяются только по этим входам; ACK/Vstat драйвера не участвуют в данной +# модели. Этот адаптер переводит события libsigrokdecode в аннотации DSView; координаты +# выборок пересчитываются с учётом частоты захвата. + """Two-input transistor pair analyzer, independent of driver feedback.""" import sigrokdecode as srd from common.setgui_decoders.transistor_pair import PairTimingChecker diff --git a/tools/dsview/install_decoders.ps1 b/tools/dsview/install_decoders.ps1 index ffedc86..8ea6321 100644 --- a/tools/dsview/install_decoders.ps1 +++ b/tools/dsview/install_decoders.ps1 @@ -1,3 +1,7 @@ +# Установка декодеров в найденный каталог DSView и проверка размещения. Режим CheckOnly +# проверяет состояние установки; фактическое копирование зависит от выбранного режима и +# доступности каталогов назначения. + [CmdletBinding()] param( [string]$DsViewPath = (Join-Path $env:ProgramFiles 'DSView'), diff --git a/tools/dsview/native/gate_summary.h b/tools/dsview/native/gate_summary.h index c888b31..f6de13f 100644 --- a/tools/dsview/native/gate_summary.h +++ b/tools/dsview/native/gate_summary.h @@ -1,3 +1,9 @@ +/* + * Сводные измерения цифровых каналов для нативного DSView. Обработка фронтов и длительностей + * выполняется без зависимости от Python-декодера; результат предназначен для представления + * итогов захвата. + */ + #pragma once #include #include diff --git a/tools/dsview/tests/gate_summary_test.cpp b/tools/dsview/tests/gate_summary_test.cpp index 8801ccd..ce975a8 100644 --- a/tools/dsview/tests/gate_summary_test.cpp +++ b/tools/dsview/tests/gate_summary_test.cpp @@ -1,3 +1,9 @@ +/* + * Проверки gate_summary_test: фиксируют ожидаемое поведение на воспроизводимых входных данных. + * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются + * настройками рабочего устройства. + */ + #include "gate_summary.h" #include int main() { diff --git a/tools/dsview/tests/test_decoders.py b/tools/dsview/tests/test_decoders.py index b1fd85e..eae67b4 100644 --- a/tools/dsview/tests/test_decoders.py +++ b/tools/dsview/tests/test_decoders.py @@ -1,3 +1,17 @@ +# Проверки decoders: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_reference_crc +# test_documented_ping +# test_documented_bridge +# test_v1_big_endian_header +# test_noise_crc_and_resync +# test_bad_version_and_length +# test_max_payload +# test_unknown_message_preserved +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Wire vectors and DSView API boundary tests; no sigrok installation needed.""" import binascii import importlib diff --git a/tools/dsview/tests/test_gate_summary.py b/tools/dsview/tests/test_gate_summary.py index 39df4a0..4f70bb4 100644 --- a/tools/dsview/tests/test_gate_summary.py +++ b/tools/dsview/tests/test_gate_summary.py @@ -1,3 +1,9 @@ +# Проверки gate_summary: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_verdict_priority_completion_and_reset +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import os from pathlib import Path import shutil diff --git a/tools/dsview/tests/test_gate_timing.py b/tools/dsview/tests/test_gate_timing.py index ed8e0d2..89bfcca 100644 --- a/tools/dsview/tests/test_gate_timing.py +++ b/tools/dsview/tests/test_gate_timing.py @@ -1,3 +1,17 @@ +# Проверки gate_timing: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_1sp0635_nominal_ack_at_100_mhz +# test_1sd536f2_nominal_ack_at_100_mhz_active_low +# test_late_delay_is_warning_but_valid_width_passes +# test_too_short_ack_fails +# test_long_status_is_fault +# test_missing_ack_expires +# test_both_directions_and_independent_minimums +# test_atomic_handover_and_active_low +# Остальные сценарии продолжают эти проверки ниже в том же файле. +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import importlib.util from pathlib import Path import unittest diff --git a/tools/dsview/tests/test_install_decoders.py b/tools/dsview/tests/test_install_decoders.py index 19302b8..e2d22a8 100644 --- a/tools/dsview/tests/test_install_decoders.py +++ b/tools/dsview/tests/test_install_decoders.py @@ -1,3 +1,13 @@ +# Проверки install_decoders: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_install_import_and_update_backup +# test_check_only_does_not_install +# test_copy_failure_restores_previous_decoders +# test_incomplete_target_is_untouched +# test_missing_source_is_detected_before_changes +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Exercise the standalone PowerShell installer without modifying installed DSView.""" import os from pathlib import Path diff --git a/tools/dsview/tests/test_runtime.py b/tools/dsview/tests/test_runtime.py index c085793..6cc908a 100644 --- a/tools/dsview/tests/test_runtime.py +++ b/tools/dsview/tests/test_runtime.py @@ -1,3 +1,10 @@ +# Проверки runtime: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_legacy_runtime_and_mismatched_binary_or_recipe_require_rebuild +# test_patch_adapters_and_shared_cores_all_invalidate_runtime +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + """Prevent packaging a new GUI with a stale native DSView component.""" import hashlib import importlib.util diff --git a/tools/dsview/tests/test_transistor_pair.py b/tools/dsview/tests/test_transistor_pair.py index 538894d..e0ba9a3 100644 --- a/tools/dsview/tests/test_transistor_pair.py +++ b/tools/dsview/tests/test_transistor_pair.py @@ -1,3 +1,13 @@ +# Проверки transistor_pair: фиксируют ожидаемое поведение на воспроизводимых входных данных. +# Сценарии для навигации по файлу: +# test_directional_deadtime_limits_and_equality +# test_independent_on_off_times_frequency_and_duty +# test_atomic_handover_active_low_and_overlap +# test_capture_boundary_does_not_invent_complete_pulses +# test_invalid_limits +# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются +# настройками рабочего устройства. + import sys from pathlib import Path import unittest diff --git a/tools/firmware-publish/PUBLISH_FIRMWARE.bat b/tools/firmware-publish/PUBLISH_FIRMWARE.bat index 60c727a..fa49ba7 100644 --- a/tools/firmware-publish/PUBLISH_FIRMWARE.bat +++ b/tools/firmware-publish/PUBLISH_FIRMWARE.bat @@ -1,4 +1,8 @@ @echo off +rem Командный вход выпуска прошивки: чтение конфигурации проекта, предварительная проверка и +rem выбранный режим публикации. По умолчанию выполняется preflight; успешная проверка не +rem равнозначна загрузке артефакта в каталог. + setlocal EnableExtensions DisableDelayedExpansion set "FW_TOOL_DIR=%~dp0" diff --git a/tools/firmware-publish/examples/ccs12-firmware-release.cmd b/tools/firmware-publish/examples/ccs12-firmware-release.cmd index ef3ae21..326d979 100644 --- a/tools/firmware-publish/examples/ccs12-firmware-release.cmd +++ b/tools/firmware-publish/examples/ccs12-firmware-release.cmd @@ -1,4 +1,7 @@ @echo off +rem Пример конфигурации выпуска прошивки CCS 12. Пути проекта и артефакта подставляются в общий +rem PUBLISH_FIRMWARE.bat; перед использованием образец согласуется с расположением репозиториев. + rem Copy this file to the firmware repository root as firmware-release.cmd. set "FW_PROJECT_ROOT=%~dp0" diff --git a/tools/firmware-publish/examples/keil-firmware-release.cmd b/tools/firmware-publish/examples/keil-firmware-release.cmd index 40b7a95..c749b18 100644 --- a/tools/firmware-publish/examples/keil-firmware-release.cmd +++ b/tools/firmware-publish/examples/keil-firmware-release.cmd @@ -1,4 +1,7 @@ @echo off +rem Пример конфигурации выпуска прошивки Keil. Скрипт задаёт пути проекта и передаёт запуск +rem общему инструменту публикации; относительные пути считаются от расположения этого файла. + rem Copy this file to the firmware repository root as firmware-release.cmd. set "FW_PROJECT_ROOT=%~dp0" diff --git a/tools/firmware-publish/firmware_db.py b/tools/firmware-publish/firmware_db.py index 53fdaa1..8f02246 100644 --- a/tools/firmware-publish/firmware_db.py +++ b/tools/firmware-publish/firmware_db.py @@ -1,3 +1,7 @@ +# Консольный доступ к базе прошивок без SETGUI: аргументы CLI выбирают операции общего +# firmware_database. Сетевой доступ и проверка образов выполняются библиотекой; этот файл +# отвечает за входные параметры и результат команды. + """Standalone firmware database CLI; requires Python 3.10+, no SETGUI.""" from __future__ import annotations