# asm3042-flasher

`asm3042-flasher` это Python-пакет с CLI-утилитой для Linux, предназначенной для загрузки firmware в PCIe-контроллеры ASMedia ASM3042 и ASM3142 через 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, ASM3142 или совместимого контроллера, для которого вы отдельно подтвердили совместимость.

## Установка

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

```bash
python -m pip install asm3042-flasher
```

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

```bash
python -m pip install .
```

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

```bash
PYTHONPATH=src python -m pytest
```

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

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

```bash
asm3042-fw discover
```

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

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

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

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

Загрузить firmware:

```bash
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`.

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

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

```bash
python -m build
```

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

```bash
python -m twine check dist/*
```

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

```bash
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`.
