45 lines
6.5 KiB
C
45 lines
6.5 KiB
C
#ifndef UART_USB_H /* Защищает общий ABI протокола от повторного включения. */
|
|
#define UART_USB_H /* Обозначает подключённый заголовок переносимого C99-ядра. */
|
|
#include <stdint.h> /* Задаёт одинаковые размеры полей MCU и настольного клиента. */
|
|
#if defined(_WIN32) /* Экспортирует кодек в отдельную DLL для ctypes на Windows. */
|
|
#define UB_API __declspec(dllexport) /* Делает публичные функции доступными без второго кодека в Python. */
|
|
#else /* Остальные платформы используют обычную видимость функций C. */
|
|
#define UB_API /* Оставляет интерфейс пригодным для статической линковки прошивки. */
|
|
#endif /* Завершает выбор способа экспорта ABI. */
|
|
#define UB_MAGIC 0xA7U /* Служебный байт выбран для восстановления границы записи в потоке USB. */
|
|
#define UB_PAYLOAD 60U /* Вместе с четырьмя байтами заголовка заполняет пакет USB FS длиной 64 байта. */
|
|
#define UB_CONFIG 1U /* Команда задаёт скорость одного выключенного приёмника в битах в секунду. */
|
|
#define UB_START 2U /* Команда запускает все включённые каналы захвата. */
|
|
#define UB_STOP 3U /* Команда останавливает DMA и освобождает USART после завершения TX. */
|
|
#define UB_TX 4U /* Команда передаёт необработанные байты только через логический канал 1. */
|
|
#define UB_ACK 8U /* Ответ содержит исходную команду, результат и число аппаратных каналов. */
|
|
#define UB_RX 9U /* Запись переносит принятые байты одного USART без текстового преобразования. */
|
|
#define UB_STATS 10U /* Запись сообщает накопленные потери и аппаратные ошибки одного канала. */
|
|
#define UB_OK 0U /* Нулевой статус подтверждает выполнение команды. */
|
|
#define UB_INVALID 1U /* Некорректные канал, длина или скорость не меняют состояние устройства. */
|
|
#define UB_BUSY 2U /* Занятый передатчик или работающий захват требуют повторения команды. */
|
|
typedef struct { /* Представляет разобранную запись без упаковки структур в wire-формат. */
|
|
uint8_t type; /* Хранит старшие четыре бита тега как отдельный тип сообщения. */
|
|
uint8_t channel; /* Хранит логический номер 1…4; номер 0 относится ко всему устройству. */
|
|
uint16_t length; /* Показывает фактическое количество байтов в payload, не более 60. */
|
|
uint8_t data[UB_PAYLOAD]; /* Передаёт бинарные данные без указателя на временную USB-память. */
|
|
} ub_frame; /* Сохраняет стабильное естественное выравнивание структуры для ctypes. */
|
|
typedef struct { /* Сохраняет состояние разбора между произвольно разделёнными USB-пакетами. */
|
|
uint8_t bytes[64]; /* Вмещает максимальную запись: заголовок 4 байта и данные 60 байт. */
|
|
uint16_t used; /* Показывает число уже накопленных байтов текущей записи. */
|
|
} ub_parser; /* Вся память принадлежит вызывающему; глобальное состояние отсутствует. */
|
|
typedef struct { /* Передаёт разобранный смысл ответа GUI через стабильный ABI без знания смещений payload. */
|
|
uint32_t kind, channel, length, command, status, channels, tx_channel, lost, errors; /* Хранит тип события и уже проверенные числовые поля ACK или статистики. */
|
|
uint8_t data[UB_PAYLOAD]; /* Содержит исключительно полезные байты RX для вывода и двоичного журнала. */
|
|
} ub_event; /* Размеры uint32 исключают разное представление enum и bool в языковых FFI. */
|
|
UB_API uint16_t ub_make_config(uint8_t channel, uint32_t baud, uint8_t *out); /* Формирует настройку скорости без сборки wire-полей в Python. */
|
|
UB_API uint16_t ub_make_start(uint8_t *out); /* Формирует общую команду запуска захвата. */
|
|
UB_API uint16_t ub_make_stop(uint8_t *out); /* Формирует общую команду остановки захвата. */
|
|
UB_API uint16_t ub_make_tx(const uint8_t *data, uint16_t length, uint8_t *out); /* Формирует передачу через единственный разрешённый канал 1. */
|
|
UB_API int ub_describe(const ub_frame *frame, ub_event *event); /* Проверяет семантику ответа и возвращает готовые поля либо 0 при ошибке. */
|
|
UB_API uint16_t ub_encode(uint8_t type, uint8_t channel, const uint8_t *data, uint16_t length, uint8_t *out); /* Записывает максимум 64 байта в буфер вызывающего и возвращает длину либо 0. */
|
|
UB_API uint16_t ub_feed(ub_parser *parser, const uint8_t *data, uint16_t length, ub_frame *frame); /* Возвращает число потреблённых байтов; type=0 означает незавершённую запись. */
|
|
UB_API uint32_t ub_get_u32(const uint8_t *data); /* Читает четыре байта little-endian независимо от архитектуры хоста. */
|
|
UB_API void ub_put_u32(uint8_t *data, uint32_t value); /* Записывает скорость или счётчик как четыре байта little-endian. */
|
|
#endif /* Завершает описание единственного общего кодека. */
|