asm3042-flasher 0.3.6

CLI-утилита для чтения, runtime-загрузки и постоянной прошивки firmware ASMedia ASM3042 и ASM3142 под Linux

asm3042-flasher

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

Пакет поддерживает три режима работы:

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

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

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

Internal permanent-flash путь реализован по reverse-engineering Windows-пакета ASMTxHCI_MPTool и предназначен для Linux-систем, где нужно получить поведение, близкое к фирменной Windows-утилите, без внешнего программатора.

Возможности

• поиск ASMedia xHCI-устройств через /sys/bus/pci/devices;
• чтение текущей версии running firmware через mailbox-регистры;
• разбор .bin-файла и извлечение permanent payload из ASMedia-образов с тегами *_RCFG и *_FW;
• runtime-загрузка firmware в SRAM;
• чтение встроенного SPI ROM через внутренний PCIe-протокол;
• постоянная запись встроенного SPI ROM через внутренний PCIe-протокол;
• резервное копирование SPI ROM перед постоянной записью;
• альтернативная работа через flashrom и внешний SPI-программатор.

Поддерживаемые устройства

Подтверждённый safe allowlist пакета:

• 1b21:3042
• 1b21:3142

Для других ASMedia xHCI-устройств доступен --force-device, но использовать его нужно только после отдельной проверки совместимости.

Требования

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

Установка

Установка из PyPI:

python -m pip install asm3042-flasher

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

python -m pip install .

Запуск тестов в репозитории:

PYTHONPATH=src python -m pytest -q

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

Найти поддерживаемые устройства:

asm3042-fw discover

Посмотреть структуру firmware-файла:

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

Прочитать текущую running firmware version:

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

Сделать backup встроенного SPI ROM через внутренний ASMedia-протокол:

sudo asm3042-fw permanent-read-internal asm3142-backup.bin --bdf 0000:03:00.0

Постоянно записать встроенный SPI ROM без внешнего программатора:

sudo asm3042-fw permanent-write-internal /path/to/firmware.bin --bdf 0000:03:00.0

Постоянно записать внешнюю flash-память через flashrom:

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

Команды

asm3042-fw discover

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

asm3042-fw inspect <firmware.bin>

• показывает источник и размер файла;
• извлекает family-tag и header-tags;
• для поддерживаемых ASMedia-образов показывает permanent-raw-size.

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

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

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

• загружает firmware во внутреннюю SRAM;
• не меняет содержимое SPI ROM;
• требует root;
• по умолчанию временно отвязывает PCI-драйвер.

asm3042-fw permanent-read-internal <backup.bin> [--bdf ...]

• читает встроенный SPI ROM через внутренний ASMedia PCIe-протокол;
• требует root;
• по умолчанию читает весь обнаруженный SPI ROM;
• если устройство осталось в состоянии driver=-, сначала пытается автоматически восстановить xhci_hcd через bind, reset и remove/rescan;
• может использоваться для обязательного резервного копирования перед записью.

asm3042-fw permanent-write-internal <firmware.bin> [--bdf ...]

• извлекает permanent payload из ASMedia .bin;
• по умолчанию делает backup текущего SPI ROM;
• записывает firmware во встроенный SPI ROM без внешнего программатора;
• по умолчанию выполняет readback verification;
• если устройство осталось в состоянии driver=-, сначала пытается автоматически восстановить xhci_hcd через bind, reset и remove/rescan;
• после записи требует cold reboot или power cycle для проверки нового образа.

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

• читает SPI flash через flashrom и внешний программатор.

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

• пишет SPI flash через flashrom и внешний программатор;
• остаётся полезным fallback-режимом, если internal PCIe-путь не подходит.

Примеры

Постоянная запись встроенной flash-памяти без внешнего программатора:

sudo asm3042-fw permanent-write-internal \
  /software/firmware_collection/expansion_board/AQAIC1-USB31-A2.bin \
  --bdf 0000:01:00.0

Та же операция без автоматического backup:

sudo asm3042-fw permanent-write-internal \
  /software/firmware_collection/expansion_board/AQAIC1-USB31-A2.bin \
  --bdf 0000:01:00.0 \
  --skip-backup

Backup только первых 0x10000 байт:

sudo asm3042-fw permanent-read-internal partial-backup.bin --bdf 0000:01:00.0 --size 0x10000

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

• Internal permanent path основан на reverse-engineering Windows-утилиты ASMedia, а не на официально опубликованной документации.
• Для безопасной записи нужно использовать только firmware, совместимую с конкретной платой и ревизией контроллера.
• На время unbind/bind все USB-устройства за этим контроллером будут временно отключены.
• После permanent-write-internal running firmware может оставаться прежней до полного холодного перезапуска.
• Если контроллер после неудачной операции завис в состоянии driver=-, пакет сначала попробует bind, затем PCI reset, затем remove/rescan; если и это не помогает, нужен cold reboot.
• Если backup уже существует, пакет по умолчанию не перезапишет его без --overwrite-backup.
• Если устройство не входит в allowlist, пакет потребует явный --force-device.

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

Сборка:

python -m build

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

python -m twine check dist/*

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

python -m twine upload dist/*

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

Проект использует два источника протокола:

• публично доступную Linux-реализацию runtime firmware loader для ASMedia xHCI;
• reverse-engineering Windows-пакета ASMTxHCI_MPTool, включая ASMTxHCI_MPTool.exe, ASMxHCICtlDLL.dll и ASMxHCICtl64.sys.

Лицензия

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