asm3042-flasher 0.2.0

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

asm3042-flasher

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

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

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

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

Инструмент поддерживает два разных сценария:

• upload: runtime-загрузка firmware в SRAM контроллера;
• permanent-write: постоянная запись во внешний SPI flash через внешний программатор и flashrom.

Для internal ASMedia PCIe-пути это важно:

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

Возможности

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

Требования

• Linux;
• Python 3.10 или новее;
• права root для команд version и upload;
• установленный flashrom и внешний SPI-программатор для permanent-read и permanent-write;
• PCIe-плата на базе ASMedia ASM3042, ASM3142 или совместимого контроллера, для которого вы отдельно подтвердили совместимость.

Установка

После публикации в 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

Считать резервную копию внешней SPI flash через flashrom:

asm3042-fw permanent-read backup.bin --programmer ch341a_spi

Постоянно записать firmware через внешний программатор:

asm3042-fw permanent-write /path/to/firmware.bin --programmer ch341a_spi

Если в системе найден ровно один 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.

asm3042-fw permanent-read <backup.bin> --programmer ...

• вызывает flashrom -r через внешний SPI-программатор;
• предназначена для чтения внешней flash-памяти и создания резервной копии;
• не зависит от runtime-состояния xHCI-драйвера.

asm3042-fw permanent-write <firmware.bin> --programmer ...

• вызывает flashrom -w через внешний SPI-программатор;
• по умолчанию сначала читает обязательный backup внешней flash-памяти;
• является рекомендованным режимом для постоянной прошивки.

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

• Утилита рассчитана только на Linux.
• На время unbind/bind все устройства за этим USB-контроллером будут временно отключены.
• permanent-write предполагает внешний SPI-программатор, например ch341a_spi или serprog.
• Перед загрузкой 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
• flashrom README: https://www.flashrom.org/
• flashrom supported programmers: https://flashrom.org/supported_hw/supported_prog/index.html

Лицензия

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