templates/c/set-protocol/PORTING.md

Перенос set-protocol

Общая граница

Ядро кодирует и разбирает кадры, но не владеет UART, CAN-контроллером, сокетом, Flash или таймером. Порт приложения должен предоставить:

• неблокирующую очередь передачи целого кадра;
• передачу принятых chunks в setp_parser_feed();
• монотонное время для телеметрии;
• callback-и общей карты и загрузчика прошивки.

UART / RS-232 / RS-485

DMA/ISR складывает байты в кольцевой буфер. Главный цикл отдаёт непрерывные участки parser-у. Для RS-485 DE остаётся включённым до физического окончания последнего stop-бита. Кадр нельзя считать отправленным по событию «DMA закончил читать память».

USB CDC

USB packet boundaries не являются границами SETP-кадра. Каждый принятый USB chunk передаётся обычному stream-parser.

Ethernet TCP

Каждый результат recv() передаётся stream-parser. send() может принять не весь буфер, поэтому порт хранит offset до полной отправки кадра. Закрытие TCP соединения удаляет его подписки на телеметрию.

Ethernet UDP

UDP payload сначала проверяется parser-ом. Принимается ровно один кадр и ноль остаточных байт. Адрес peer хранится портом до отправки ответа. Для broadcast и multicast запрещены WRITE, FW_BEGIN и FW_ACTIVATE.

CAN

Не вызывайте прикладной router из ISR. ISR принимает CAN-кадры в очередь, сегментация собирается в главном цикле, и только полный SETP-кадр передаётся parser/router. Сборка должна иметь timeout, контроль номера сегмента и одного активного отправителя на канал.

Firmware backend

Протокол не заменяет безопасный загрузчик. Backend обязан:

1. писать только в неактивный слот или staging-область;
2. проверять границы до erase/program;
3. принимать повтор подтверждённого блока идемпотентно;
4. хранить next_offset так, чтобы пережить reset;
5. проверить CRC32, SHA-256 и, если требуется, подпись;
6. атомарно пометить слот READY;
7. иметь rollback, если новая прошивка не подтвердила успешный старт.

Во время обновления ответы и FW_* имеют приоритет над PUBLISH. Подписки можно временно приостановить, но соединение и FW_STATUS должны продолжать работать.