Подключи ISE, Vivado и Quartus к общему итератору версии и HDL-паспорту. Проверяй новый bit/sof до создания manifest, SHA-256 и архива выпуска. Добавь установку локальных команд ISE, инструкции переноса и регрессионные проверки успешных и прерванных сборок.
93 lines
16 KiB
Python
93 lines
16 KiB
Python
"""Паспорт ПЛИС и контроль готового образа через общий итератор 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.
|