asm3042-flasher 0.1.0

CLI-утилита для загрузки firmware в контроллеры ASMedia ASM3042 под Linux

asm3042-flasher

asm3042-flasher это Python-пакет с CLI-утилитой для Linux, предназначенной для загрузки firmware в PCIe-контроллеры ASMedia ASM3042 через PCI configuration space и BAR0 MMIO.

Пакет ориентирован на сценарий, когда у платы есть рабочий бинарный образ firmware в формате .bin, а загрузку нужно выполнить напрямую из Linux без сторонних графических утилит.

Статус проекта

Текущий статус: alpha.

Инструмент реализует подтверждённую последовательность runtime-загрузки firmware в SRAM контроллера. Это важно:

• пакет загружает firmware в работающий контроллер;
• пакет не реализует подтверждённую постоянную запись во внешний SPI ROM;
• после выключения питания или полного reboot загрузку, скорее всего, придётся повторить;
• для постоянной прошивки нужен отдельно подтверждённый SPI write-протокол или внешний SPI-программатор.

Возможности

• поиск ASMedia xHCI-устройств через /sys/bus/pci/devices;
• чтение текущей версии firmware через mailbox-регистры контроллера;
• проверка и разбор заголовков firmware-файла;
• загрузка firmware в SRAM по documented ASMedia upload sequence;
• автоматический unbind и bind PCI-драйвера на время загрузки.

Требования

• Linux;
• Python 3.10 или новее;
• права root для команд version и upload;
• PCIe-плата на базе ASMedia ASM3042 или совместимого контроллера, для которого вы отдельно подтвердили совместимость.

Установка

После публикации в PyPI:

python -m pip install asm3042-flasher

Установка из исходников:

python -m pip install .

Локальный запуск тестов из репозитория:

PYTHONPATH=src python -m pytest

Быстрый старт

Найти подходящие устройства:

asm3042-fw discover

Проверить firmware-файл:

asm3042-fw inspect /path/to/firmware.bin

Прочитать текущую версию firmware контроллера:

sudo asm3042-fw version --bdf 0000:03:00.0

Загрузить firmware:

sudo asm3042-fw upload /path/to/firmware.bin --bdf 0000:03:00.0

Если в системе найден ровно один ASMedia xHCI-контроллер, параметр --bdf можно не указывать.

Команды

asm3042-fw discover

• выводит список подходящих PCIe-устройств;
• показывает BDF, vendor, device, текущий драйвер и признак known-protocol.

asm3042-fw inspect <firmware.bin>

• показывает источник файла;
• показывает размер образа;
• извлекает распознанные header tags, например 2214A_RCFG и 2214A_FW.

asm3042-fw version [--bdf ...]

• читает версию firmware из контроллера;
• требует root;
• по умолчанию работает только с устройствами из allowlist.

asm3042-fw upload <firmware.bin> [--bdf ...]

• загружает образ в SRAM контроллера;
• требует root;
• отказывается перезаписывать уже загруженный runtime-образ без флага --force-running-firmware;
• по умолчанию временно отвязывает драйвер, если не указан --keep-driver-bound.

Ограничения и меры предосторожности

• Утилита рассчитана только на Linux.
• На время unbind/bind все устройства за этим USB-контроллером будут временно отключены.
• Перед загрузкой firmware нужно убедиться, что бинарный файл соответствует вашей ревизии платы.
• Пример файла AQAIC1-USB31-A2.bin содержит теги 2214A_RCFG и 2214A_FW; это повод отдельно проверить совместимость перед прошивкой.
• Если устройство не входит в текущий allowlist, пакет потребует явный --force-device.

Публикация пакета

Сборка дистрибутивов:

python -m build

Проверка метаданных и рендеринга README:

python -m twine check dist/*

Публикация в PyPI:

python -m twine upload dist/*

Основание реализации

Реализация основана на публично доступных источниках:

• ASMedia ASM3042 product page: https://www.asmedia.com.tw/product/jn8yQ5s8t8TP0o6o/9A2YQ78xZ0UR5Q5y
• Linux ASMedia xHCI firmware loader reference implementation: https://raw.githubusercontent.com/AsahiLinux/linux/asahi/drivers/usb/host/xhci-pci-asmedia.c
• Upstream Linux PCI device IDs and xHCI quirks: https://raw.githubusercontent.com/torvalds/linux/master/drivers/usb/host/xhci-pci.c

Лицензия

Проект распространяется под лицензией MIT. Текст лицензии находится в файле LICENSE.