Files
templates/tools/firmware-build/fpga/tests/test_identity.py
T
Andrey 62c0492bfd feat(firmware-build): Добавь сборку и паспорта проектов ПЛИС
Подключи ISE, Vivado и Quartus к общему итератору версии и HDL-паспорту. Проверяй новый bit/sof до создания manifest, SHA-256 и архива выпуска.

Добавь установку локальных команд ISE, инструкции переноса и регрессионные проверки успешных и прерванных сборок.
2026-10-23 14:16:21 +03:00

95 lines
13 KiB
Python

"""Проверяет FPGA-паспорт, общий итератор и точные байты архивов без лицензии САПР.""" # Запуск через unittest discover из корня репозитория.
import importlib.util # Импортирует реальный FPGA-адаптер без установки пакета.
import json # Сравнивает конфигурацию, метаданные и manifest готового образа.
import os # Управляет меткой времени файла в тесте воспроизводимой пересборки.
from pathlib import Path # Ограничивает изменения собственными временными каталогами.
import re # Извлекает значения из HDL для проверки общего регистрационного контракта.
import tempfile # Изолирует результаты от рабочих проектов пользователя.
import unittest # Проверяет успешные сборки и отказы при устаревших файлах.
from unittest.mock import patch # Делает Git и время независимыми от машины запуска.
TOOL = Path(__file__).resolve().parents[1] / "identity.py" # Находит инструмент рядом с тестами.
SPEC = importlib.util.spec_from_file_location("fpga_identity", TOOL) # Создаёт отдельное имя для адаптера.
fpga = importlib.util.module_from_spec(SPEC) # Подготавливает импорт без вызова CLI.
SPEC.loader.exec_module(fpga) # Загружает код, используемый всеми тремя сценариями САПР.
class IdentityTests(unittest.TestCase): # Проверяет границу между общим генератором и HDL.
def setUp(self): # Создаёт проект с кириллицей и пробелами в пути.
temporary = tempfile.TemporaryDirectory(prefix="ПЛИС project ") # Проверяет UTF-8 и корректную передачу путей.
self.addCleanup(temporary.cleanup) # Очищает только файлы данного теста.
self.root = Path(temporary.name) # Хранит все входы и выходы внутри временного проекта.
self.config = self.root / "firmware_identity.json" # Служит единственным источником ручного номера версии.
self.generated = self.root / "build/generated" # Имитирует каталог текущей конфигурации сборки.
self.image = self.root / "board.bit" # Нативный результат ISE или Vivado.
self.config.write_text(json.dumps({"product": "Плата", "target": "test-part", "version": [1, 2, 3], "increment_version": True}), encoding="utf-8") # Не изменяет пример или настройки реальных проектов.
self.git = patch.object(fpga.shared, "git_state", return_value={"commit": None, "dirty": None}) # Без Git должен получаться явный NOGIT000.
self.git.start() # Фиксирует отсутствие Git для всех вызовов данного теста.
self.addCleanup(self.git.stop) # Восстанавливает функцию после проверки.
self.epoch = patch.dict(os.environ, {"SOURCE_DATE_EPOCH": "1792413296"}) # UTC 2026-10-19 12:34:56 позволяет проверить точные календарные слова.
self.epoch.start() # Делает дату HDL детерминированной.
self.addCleanup(self.epoch.stop) # Не меняет окружение остальных тестов.
def prepare(self, toolchain="vivado", language="verilog"): # Вызывает публичную функцию адаптера теми же аргументами, что Tcl.
return fpga.prepare(self.root, self.config, self.generated, self.image, toolchain, language) # Делегирует резервирование версии общему prepare.
def test_hdl_matches_contract_and_iterator(self): # Одним вектором сравнивает обе HDL-реализации с контрактом C.
metadata = self.prepare() # Первый запуск должен увеличить patch ровно один раз.
expected = [1, 1, 2, 4, 2026, 0x0A13, 0x0C22, 56, 0x4E4F, 0x4749, 0x5430, 0x3030] # 12 слов: контракт, 1.2.4, UTC и ASCII NOGIT000.
self.assertEqual(metadata["fpga"]["register_words"], expected) # Фиксирует независимый эталон адресов и старшинства октетов.
verilog = (self.generated / "firmware_identity.v").read_text(encoding="utf-8") # Читает фактически записанный файл для синтеза XST.
vhdl = (self.generated / "firmware_identity.vhd").read_text(encoding="utf-8") # Читает альтернативный VHDL-93 паспорт.
self.assertEqual([int(value, 16) for value in re.findall(r"word_data = 16'h([0-9A-F]{4})", verilog)][:12], expected) # Проверяет константы без зависимости от пробелов и комментариев.
self.assertEqual([int(value, 16) for value in re.findall(r'x"([0-9A-F]{4})" when "[01]{4}"', vhdl)], expected) # Проверяет то же расположение слов в VHDL.
self.assertEqual(json.loads(self.config.read_text(encoding="utf-8"))["version"], [1, 2, 4]) # HDL и сохраняемый счётчик обязаны совпадать.
self.assertEqual(self.prepare()["version"], [1, 2, 5]) # Следующая попытка использует следующий номер общего итератора.
def test_seal_archive_export_and_tampering(self): # Проверяет реальную упаковку точных байтов и отказ при повреждении.
self.prepare() # Фиксирует паспорт до появления готового .bit.
data = b"test-only FPGA bitstream\x00\xff" # Произвольные байты моделируют файл программатора без разбора вендорного контейнера.
self.image.write_bytes(data) # Имитирует успешный выход полной сборки САПР.
result = fpga.finish(self.generated / "firmware_identity.json", self.root / "firmware", self.root / "export") # Запускает общий seal, verify, archive и проверку экспорта.
for folder in (Path(result["directory"]), Path(result["exported_directory"])): # Проверяет обе сохраняемые копии текущего выпуска.
self.assertEqual((folder / self.image.name).read_bytes(), data) # Архивы должны содержать точные исходные байты.
self.assertEqual((folder / "firmware_identity.v").read_bytes(), (self.generated / "firmware_identity.v").read_bytes()) # Вместе с образом сохраняется точный исходник паспорта, переданный синтезатору.
manifest = fpga.shared.verify(folder / self.image.name, folder / (self.image.name + ".manifest.json")) # Повторно считает размер и SHA-256 независимо от результата finish.
self.assertEqual(manifest["version"], [1, 2, 4]) # Post-build не увеличивает версию второй раз.
self.image.write_bytes(b"damaged") # Имитирует изменение файла после выпуска manifest.
with self.assertRaises(ValueError): # Проверка обязана обнаружить повреждение до программирования.
fpga.shared.verify(self.image, self.image.with_suffix(".bit.manifest.json")) # Использует публичную общую проверку образа.
def test_stale_missing_and_empty_images_are_rejected(self): # Отказы сборки не должны связывать новый паспорт со старым результатом.
self.image.write_bytes(b"old image") # Оставляет нативный файл от предыдущего выпуска.
self.prepare() # Запоминает его содержимое и время до синтеза.
with self.assertRaisesRegex(ValueError, "not updated"): # Неизменившийся старый файл не считается новым выпуском.
fpga.finish(self.generated / "firmware_identity.json", self.root / "firmware") # Отказывается до создания manifest.
self.image.unlink() # Моделирует отсутствие результата после сбоя САПР.
with self.assertRaisesRegex(ValueError, "Missing or empty"): # Нет образа — нет архива.
fpga.finish(self.generated / "firmware_identity.json", self.root / "firmware") # Проверяет отсутствие файла.
self.image.write_bytes(b"") # Моделирует оборванную запись выходного файла.
with self.assertRaisesRegex(ValueError, "Missing or empty"): # Пустой файл также блокирует выпуск.
fpga.finish(self.generated / "firmware_identity.json", self.root / "firmware") # Не допускает SHA-256 пустого файла как прошивки.
self.assertFalse((self.root / "firmware").exists()) # Ни один из отказов не должен создать архив.
def test_reproducible_image_with_new_mtime_is_accepted(self): # Ручная версия и воспроизводимый BitGen могут дать прежние байты.
self.image.write_bytes(b"same image") # Готовит существующий результат предыдущей сборки.
metadata = self.prepare() # Запоминает прежнее время записи.
stamp = metadata["fpga"]["image_before"]["mtime_ns"] + 2_000_000_000 # Две секунды покрывают даже грубую точность времени старых файловых систем.
os.utime(self.image, ns=(stamp, stamp)) # Имитирует реальную повторную запись тех же байтов.
fpga.finish(self.generated / "firmware_identity.json", self.root / "firmware") # Обновлённый файл допускается без требования отличающегося хеша.
def test_quartus_and_wrong_extension(self): # Проверяет нативный .sof и отказы до резервирования номера.
original = self.config.read_bytes() # Неверная команда не должна увеличивать счётчик.
with self.assertRaises(ValueError): # .bit не является нативным результатом Quartus.
self.prepare(toolchain="quartus") # Проверяет соответствие расширения выбранной САПР.
self.assertEqual(self.config.read_bytes(), original) # Конфигурация остаётся прежней после отказа.
self.image = self.root / "revision.sof" # Выбирает штатный выход Assembler.
metadata = self.prepare(toolchain="quartus", language="vhdl") # Использует тот же итератор для Altera и VHDL.
self.image.write_bytes(b"test SOF") # Моделирует успешную компиляцию Quartus.
result = fpga.finish(self.generated / "firmware_identity.json", self.root / "firmware") # Архивирует .sof через общий механизм.
self.assertEqual(result["file"], "revision.sof") # Сохраняет имя ревизии программатора.
self.assertEqual(metadata["fpga"]["language"], "vhdl") # Фиксирует язык для последующего аудита.
if __name__ == "__main__": # Позволяет запускать проверку отдельным файлом.
unittest.main() # Возвращает ненулевой код при нарушении контракта.