Добавить протокол Altera Logic и общие клиенты прошивки

c/set-protocol/ALTERA_LOGIC.md

@@ -0,0 +1,93 @@
+# Altera Logic: общее ядро и порты
+
+Потоковый SETCAN/GAS-профиль и общие порты описаны отдельно:
+[Altera Logic ONLINE](../../doc/setcan/ALTERA_LOGIC_STREAM.md).
+Ниже — совместимый прежний буферный протокол UART `A5 CMD`.
+
+Клиент UART-протокола FPGA-анализатора Cyclone IV: 16 каналов, 4096 выборок.
+Работает с существующим RTL `altera_loganalisator`, версия протокола 1.
+Ядро C99 не зависит от Qt, ОС, системных часов и динамической памяти.
+
+Слои: SETGUI → Python ctypes → C99 → Python Qt-порт → COM / USB–UART.
+GUI передаёт числовые настройки и получает готовый массив; формат пакетов,
+XOR, endian, последовательность команд, парсер и состояния тайм-аутов находятся в C.
+
+| Файл | Назначение и зависимости |
+|---|---|
+| `include/altera_logic.h` | Публичный ABI, макрос экспорта из `pcan_abi.h` |
+| `src/altera_logic.c` | Кодек и автомат обмена; только стандартная библиотека C |
+| `tests/test_altera_logic.c` | Эталонные пакеты RTL, полный захват, ошибки |
+| `../../python/altera_logic/native.py` | ctypes-модели, загрузка DLL, экспорт CSV; stdlib |
+| `../../python/altera_logic/qt_port.py` | Асинхронный COM-порт; PySide6 QtSerialPort |
+
+## Сборка
+
+Из корня `templates`:
+
+```powershell
+python c/set-protocol/tools/build_host.py --output python/altera_logic/native/setprotocol.dll
+```
+
+На Linux выходной файл — `python/altera_logic/native/libsetprotocol.so`.
+Также поддерживается основная CMake-сборка `c/set-protocol`; путь к результату
+задаётся через `ALTERA_LOGIC_LIBRARY`. Библиотека без символов `la_*`
+не поддерживается: тихого Python-fallback нет.
+
+## Контракт порта
+
+Выделить выровненную память размером `la_context_size()`; все обращения к
+одному контексту выполняются в одном потоке.
+
+- `la_init(ctx)` — начать с INFO.
+- `la_next(ctx, out, capacity)` — получить следующий запрос, либо 0, если отправлять нечего.
+- `la_feed(ctx, bytes, size)` — передать принятые байты, включая частичные ответы.
+- `la_tick(ctx, elapsed_ms)` — сообщить прошедшее время; тайм-аут ответа 1000 мс.
+- `la_start(ctx, divider, mask, value, edge_mask, edge_value)` — настройка и новый захват.
+- `la_get(ctx, field)` — состояние и прогресс; `la_samples` — завершённая запись.
+- `la_fail(ctx, LA_IO_ERROR)` — сообщить ошибку транспорта.
+
+COM: 921600 бод, 8N1, без управления потоком. Одновременно ожидается только
+один ответ. После ARM STATUS опрашивается каждые 25 мс; ожидание самого
+триггера не ограничено. После done читаются 64 блока по 64 выборки.
+Ошибки закрывают сеанс без автоматического повтора ARM. Неверный размер,
+код команды или XOR прекращает сеанс. При рассинхронизации запроса на FPGA
+может потребоваться аппаратный RESET_N; переподключение не гарантирует её сброс.
+
+Клиент намеренно принимает только профиль 16 × 4096 версии 1.
+Поддержка внешней SDRAM и расширенных адресов сюда пока не входит.
+Прерывание в GUI закрывает порт ПК: STOP в протоколе FPGA отсутствует.
+
+## Быстрый старт без платы
+
+Добавить `templates/python` в PYTHONPATH:
+
+```python
+from altera_logic import NativeAnalyzer
+
+client = NativeAnalyzer()
+client.reset(demo=True)
+client.start(divider=49)
+capture = client.capture()
+print(len(capture.samples))  # 4096
+print(capture.sample_rate)   # 1_000_000
+print(capture.trigger_index) # 2048
+capture.save_csv("demo.csv")
+```
+
+Демо создаёт синтетическую запись в C; не моделирует заданные условия триггера.
+CSV содержит явный признак demo, время относительно триггера и состояния D0…D15.
+
+## Потребители и проверка
+
+Используется вкладкой SETGUI «Altera Logic». Для Android/JNI новый потребитель
+может использовать тот же ABI; интерфейс Android в этой задаче не изменяется.
+Существующий ABI SETProtocol не изменён, добавлены только символы `la_*`.
+
+```powershell
+$env:PYTHONPATH = "$PWD/python"
+python -m unittest discover -s python/tests -p test_altera_logic.py
+```
+
+CMake включает `test_altera_logic` и CTest `altera_logic`.
+На плате требуется отдельно проверить разводку пинов, RAM-модуль и прошивку;
+программные проверки не заменяют аппаратную проверку.