Files
templates/tools/firmware-build/fpga/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

93 lines
16 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Паспорт ПЛИС и контроль готового образа через общий итератор firmware-info.""" # CLI используется из Tcl трёх систем сборки.
from __future__ import annotations # Откладывает вычисление аннотаций для Python 3.9+.
import argparse # Разбирает явные пути, чтобы рабочий каталог IDE не менял назначение файлов.
from datetime import datetime # Разбирает UTC-время, зафиксированное общим pre-build.
import hashlib # Сравнивает исходный и новый образы при защите от устаревшего результата.
import importlib.util # Подключает существующий генератор без второй реализации итератора.
import json # Читает и сохраняет переносимые метаданные сборки в UTF-8.
from pathlib import Path # Нормализует пути проектов, результатов и общей библиотеки.
TEMPLATES = Path(__file__).resolve().parents[3] # От fpga/ поднимается к корню templates.
SPEC = importlib.util.spec_from_file_location("firmware_identity_shared", TEMPLATES / "c/firmware-info/tools/identity.py") # Выбирает общий модуль из этой же поставки.
shared = importlib.util.module_from_spec(SPEC) # Создаёт пространство имён общего генератора без изменения sys.path.
SPEC.loader.exec_module(shared) # Загружает prepare, seal, verify и archive_build без запуска общего CLI.
FORMATS = {"ise": {".bit"}, "vivado": {".bit"}, "quartus": {".sof"}} # Полные сценарии выпускают нативный файл конфигурации своей САПР.
def registers(metadata): # Переносит публичный 12-словный контракт firmware-info v1 в константную HDL-память.
stamp = datetime.fromisoformat(metadata["built_at_utc"]) # Общий prepare всегда сохраняет дату с часовым поясом UTC.
words = [1, *metadata["version"], stamp.year, (stamp.month << 8) | stamp.day, (stamp.hour << 8) | stamp.minute, stamp.second] # Слова 0..7: контракт, SemVer и календарные поля; сдвиг на 8 размещает старший октет.
build_id = metadata["build_id"].encode("ascii") # Контракт использует ровно восемь печатных ASCII-символов.
words.extend((build_id[index] << 8) | build_id[index + 1] for index in range(0, 8, 2)) # Слова 8..11 содержат пары символов, первый в старших восьми битах.
return words # Порядок совпадает с firmware_info_to_registers(), включая дату в UTC.
def verilog(words): # Генерирует Verilog-2001 без примитивов конкретного производителя.
lines = ["module firmware_identity ( // Комбинационный паспорт сборки с адресацией 16-битными словами.", " input wire [3:0] word_addr, // Четыре бита адресуют слова 0..11; остальные адреса возвращают ноль.", " output reg [15:0] word_data // Данные выбранного слова; синхронизацию с шиной выполняет проект.", "); // Интерфейс не требует тактового сигнала и сброса.", "always @* begin // Полная комбинационная чувствительность исключает устаревшее значение при смене адреса.", " case (word_addr) // Каждому адресу соответствует константа, вычисленная до синтеза."] # Использует синтаксис, доступный старым XST и Quartus II.
lines.extend(f" 4'd{index}: word_data = 16'h{word:04X}; // Слово {index} общего контракта firmware-info v1, значение без знака." for index, word in enumerate(words)) # Явные размеры исключают расширение констант и зависимость от порядка байтов.
lines.extend([" default: word_data = 16'h0000; // Неиспользуемые адреса не создают защёлок и возвращают ноль.", " endcase // Все входные комбинации определяют выход.", "end // Завершает комбинационное чтение паспорта.", "endmodule // Проект должен подключить выход к доступной хосту карте регистров."]) # Выход обязательно используется верхним уровнем, иначе синтезатор удалит паспорт.
return "\n".join(lines) + "\n" # Сохраняет единый формат строк UTF-8 с завершающим переводом строки.
def vhdl(words): # Генерирует VHDL-93 с тем же интерфейсом для проектов без Verilog.
lines = ["library ieee; -- Подключает стандартную библиотеку логических типов.", "use ieee.std_logic_1164.all; -- Определяет std_logic_vector для адреса и 16-битного слова.", "entity firmware_identity is -- Объявляет паспорт, подключаемый к карте регистров проекта.", " port ( -- Описывает комбинационный интерфейс без тактового домена.", " word_addr : in std_logic_vector(3 downto 0); -- Адрес слова 0..11; четыре бита покрывают весь контракт.", " word_data : out std_logic_vector(15 downto 0) -- 16-битное значение общего регистра версии.", " ); -- Завершает описание портов.", "end firmware_identity; -- Закрывает внешний интерфейс паспорта.", "architecture rtl of firmware_identity is -- Реализует паспорт только константами без памяти производителя.", "begin -- Начинает комбинационную архитектуру.", " with word_addr select word_data <= -- При изменении адреса немедленно выбирает соответствующее слово."] # Выбор с others определяет выход для всех состояний входа.
lines.extend(f' x"{word:04X}" when "{index:04b}", -- Слово {index} контракта firmware-info v1, шестнадцатеричная константа 16 бит.' for index, word in enumerate(words)) # Двоичные селекторы не требуют numeric_std и преобразования адреса.
lines.extend([' x"0000" when others; -- Неиспользуемые и неопределённые адреса возвращают нулевое слово.', "end rtl; -- Завершает синтезируемый паспорт сборки."]) # Полный выбор исключает защёлки.
return "\n".join(lines) + "\n" # Возвращает текст для атомарной записи в UTF-8.
def fingerprint(image): # Фиксирует состояние результата перед сборкой для отказа при повторной упаковке старого файла.
if not image.exists(): # При первой сборке ожидаемого образа ещё нет.
return None # Любой непустой файл после успешной сборки будет новым результатом.
return {"mtime_ns": image.stat().st_mtime_ns, "sha256": hashlib.sha256(image.read_bytes()).hexdigest()} # Изменение времени допускает побайтно воспроизводимую пересборку.
def prepare(repository, config, output, image, toolchain, language): # Резервирует единственный номер до синтеза и создаёт оба варианта HDL.
repository, config, output, image = (path.resolve() for path in (repository, config, output, image)) # Все пути в метаданных независимы от последующих cd в САПР.
if image.suffix.lower() not in FORMATS[toolchain]: # Не выдаёт произвольный или служебный файл за нативный результат данного flow.
raise ValueError(f"{toolchain}: expected {sorted(FORMATS[toolchain])}") # Неверный путь останавливает подготовку до увеличения версии.
before = fingerprint(image) # Читает старый результат до резервирования номера, чтобы отказ чтения не занимал версию.
metadata = shared.prepare(repository, TEMPLATES, config, output) # Использует общий атомарный итератор, Git, SOURCE_DATE_EPOCH и UTC.
words = registers(metadata) # Упаковывает уже зарезервированную версию в общий контракт регистров.
metadata["fpga"] = {"toolchain": toolchain, "language": language, "image_path": str(image), "image_before": before, "register_words": words} # Связывает post-build с конкретным файлом и снимком pre-build.
shared.write_atomic(output / "firmware_identity.v", verilog(words)) # Даёт старым XST/Quartus синтезируемый Verilog-2001.
shared.write_atomic(output / "firmware_identity.vhd", vhdl(words)) # Даёт VHDL-проекту тот же паспорт без смешения языков.
shared.write_atomic(output / "firmware_identity.json", json.dumps(metadata, ensure_ascii=False, indent=2) + "\n") # Сохраняет FPGA-привязку в тех же метаданных, которые попадут в manifest.
return metadata # Вызывающий сценарий добавляет в проект только один выбранный язык.
def finish(metadata_path, output, export=None): # Вызывается только после успешной полной сборки нативного образа.
metadata_path = metadata_path.resolve() # Исключает зависимость пути от рабочего каталога post-build.
metadata = json.loads(metadata_path.read_text(encoding="utf-8")) # Использует сохранённый pre-build, не запрашивая Git и время повторно.
image = Path(metadata["fpga"]["image_path"]) # Упаковывает исключительно тот файл, который был указан перед синтезом.
if not image.is_file() or not image.stat().st_size: # Отсутствующий или пустой результат не может стать выпуском.
raise ValueError(f"Missing or empty FPGA image: {image}") # Ошибка блокирует создание manifest и архива.
if fingerprint(image) == metadata["fpga"]["image_before"]: # Старый файл с прежним временем и содержимым означает отсутствие нового результата.
raise ValueError("FPGA image was not updated after prepare") # Не связывает новый номер версии с прежней прошивкой после неудачного запуска.
shared.seal(image, metadata_path) # Считает SHA-256 точных байтов .bit/.sof, передаваемых программатору.
shared.verify(image, image.with_suffix(image.suffix + ".manifest.json")) # Проверяет размер и контрольную сумму до архивирования.
extension = "v" if metadata["fpga"]["language"] == "verilog" else "vhd" # Выбирает точный HDL-паспорт, зарегистрированный в проекте перед синтезом.
hdl = metadata_path.parent / ("firmware_identity." + extension) # Хранит исходник констант рядом с pre-build JSON.
return shared.archive_build(image, metadata_path, output, extra_files=(hdl,), export=export) # Сохраняет HDL с образом; общий архиватор проверяет локальную и экспортную копии.
def main(): # Разделяет подготовку и упаковку, чтобы Tcl мог остановиться между ними при ошибке САПР.
parser = argparse.ArgumentParser(description=__doc__) # Печатает назначение общего FPGA-инструмента в --help.
commands = parser.add_subparsers(dest="command", required=True) # Требует явный этап сборки.
before = commands.add_parser("prepare") # Создаёт интерфейс pre-build без запуска САПР из Python.
for name in ("repository", "config", "output", "image"): # Все входные и выходные пути передаются отдельными аргументами.
before.add_argument("--" + name, type=Path, required=True) # Path сохраняет пробелы и кириллицу без shell-подстановки.
before.add_argument("--toolchain", choices=FORMATS, required=True) # Ограничивает форматы результата выбранной САПР.
before.add_argument("--language", choices=("verilog", "vhdl"), default="verilog") # Позволяет выбрать один HDL для регистрации в проекте.
after = commands.add_parser("finish") # Создаёт интерфейс post-build только для готового результата.
after.add_argument("--metadata", dest="metadata_path", type=Path, required=True) # Требует тот же паспорт, что был создан перед синтезом.
after.add_argument("--output", type=Path, required=True) # Размещает архивы отдельно от файлов синтеза.
after.add_argument("--export", type=Path) # По явному запросу копирует проверенную архивную папку в локальный каталог.
arguments = vars(parser.parse_args()) # Преобразует именованные аргументы в параметры выбранной функции.
command = arguments.pop("command") # Удаляет служебное имя команды из аргументов функции.
result = {"prepare": prepare, "finish": finish}[command](**arguments) # Ошибки прерывают процесс с ненулевым кодом для Tcl catch.
print(json.dumps(result, ensure_ascii=False)) # Даёт журналу САПР путь архива и использованные метаданные.
if __name__ == "__main__": # Импорт в тестах не должен изменять проектную версию.
main() # Запускает CLI только при прямом вызове Python.