# 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:

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

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

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

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

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

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

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

```bash
asm3042-fw discover
```

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

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

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

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

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

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

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

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

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

```bash
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;
- может использоваться для обязательного резервного копирования перед записью.

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

- извлекает permanent payload из ASMedia `.bin`;
- по умолчанию делает backup текущего SPI ROM;
- записывает firmware во встроенный SPI ROM без внешнего программатора;
- по умолчанию выполняет readback verification;
- после записи требует 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-памяти без внешнего программатора:

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

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

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

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

```bash
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 может оставаться прежней до полного холодного перезапуска.
- Если backup уже существует, пакет по умолчанию не перезапишет его без `--overwrite-backup`.
- Если устройство не входит в allowlist, пакет потребует явный `--force-device`.

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

Сборка:

```bash
python -m build
```

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

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

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

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