Metadata-Version: 2.4
Name: asm3042-flasher
Version: 0.4.17
Summary: CLI-утилита для чтения, runtime-загрузки и постоянной прошивки firmware ASMedia ASM3042 и ASM3142 под Linux
License: MIT
Keywords: asmedia,asm3042,firmware,pci,linux,xhci
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# asm3042-flasher

`asm3042-flasher` — CLI-утилита для Linux для работы с контроллерами ASMedia ASM3042/ASM3142.

## Установка

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

## Основные команды

### `asm3042-fw discover`

Показывает найденные ASMedia PCIe USB-контроллеры.

Пример:

```bash
asm3042-fw discover
```

### `asm3042-fw inspect <firmware.bin>`

Показывает сведения о firmware-файле: размер, теги, family.

Пример:

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

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

Читает running firmware version из контроллера.

Ключи:

- `--bdf` — PCI BDF, например `0000:01:00.0`
- `--force-device` — разрешить работу вне known-safe allowlist

Пример:

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

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

Загружает firmware во временную SRAM, не пишет SPI ROM.

Ключи:

- `--bdf` — PCI BDF
- `--force-device` — разрешить работу вне allowlist
- `--force-running-firmware` — разрешить upload поверх уже загруженной firmware
- `--keep-driver-bound` — не отвязывать драйвер на время операции

Пример:

```bash
sudo asm3042-fw upload /path/to/firmware.bin --bdf 0000:01:00.0
```

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

Читает встроенный SPI ROM через внутренний ASMedia PCIe-протокол.

Ключи:

- `--bdf` — PCI BDF
- `--force-device` — разрешить работу вне allowlist
- `--keep-driver-bound` — не отвязывать драйвер
- `--size` — прочитать только указанное число байт

Пример:

```bash
sudo asm3042-fw permanent-read-internal /root/asm.backup.bin --bdf 0000:01:00.0
```

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

Пишет firmware во встроенный SPI ROM.

Ключи:

- `--ini` — путь к `ASMTxHCIMPTool.ini`
- `--unsafe-allow-ini-overrides` — включить internal Windows-style overrides path
- `--bdf` — PCI BDF
- `--force-device` — разрешить работу вне allowlist
- `--keep-driver-bound` — не отвязывать драйвер
- `--backup-file` — путь для обязательного backup
- `--overwrite-backup` — разрешить перезапись backup
- `--no-verify` — отключить post-write verify
- `--plan` — только preflight и backup, без записи
- `--require-primary-device-id` — потребовать ожидаемый primary device id
- `--require-subsystem-device-id` — потребовать ожидаемый subsystem device id
- `--require-subsystem-vendor-id` — потребовать ожидаемый subsystem vendor id

Пример безопасного preflight:

```bash
sudo asm3042-fw permanent-write-internal \
  /path/to/firmware.bin \
  --bdf 0000:01:00.0 \
  --backup-file /root/asm.backup.bin \
  --plan
```

### `asm3042-fw crossflash-internal <firmware.bin> --ini ... [--bdf ...]`

Упрощённый high-level wrapper вокруг internal write path.

Ключи:

- `--ini` — путь к `ASMTxHCIMPTool.ini`
- `--bdf` — PCI BDF
- `--force-device` — разрешить работу вне allowlist
- `--backup-file` — путь для backup
- `--overwrite-backup` — разрешить перезапись backup
- `--no-verify` — отключить verify
- `--plan` — только план и backup
- `--apply` — реально писать SPI

По умолчанию без `--apply` команда только строит план и сохраняет backup.

Примеры:

```bash
sudo asm3042-fw crossflash-internal \
  /path/to/firmware.bin \
  --ini /path/to/ASMTxHCIMPTool.ini \
  --bdf 0000:01:00.0
```

```bash
sudo asm3042-fw crossflash-internal \
  /path/to/firmware.bin \
  --ini /path/to/ASMTxHCIMPTool.ini \
  --backup-file /root/asm.backup.bin \
  --bdf 0000:01:00.0 \
  --apply
```

### `asm3042-fw audit-internal <firmware.bin> [--ini ...] [--bdf ...]`

Сравнивает live PCI identity и текущий SPI с целевым образом, который будет собран из `firmware.bin` и optional `.ini`.

Ключи:

- `--ini` — путь к `ASMTxHCIMPTool.ini`
- `--bdf` — PCI BDF
- `--force-device` — разрешить работу вне allowlist

Пример:

```bash
sudo asm3042-fw audit-internal \
  /path/to/firmware.bin \
  --ini /path/to/ASMTxHCIMPTool.ini \
  --bdf 0000:01:00.0
```

### `asm3042-fw permanent-restore-internal <backup.bin> [--bdf ...]`

Восстанавливает встроенный SPI ROM из backup.

Ключи:

- `--bdf` — PCI BDF
- `--force-device` — разрешить работу вне allowlist
- `--keep-driver-bound` — не отвязывать драйвер
- `--no-verify` — отключить verify после restore

Пример:

```bash
sudo asm3042-fw permanent-restore-internal /root/asm.backup.bin --bdf 0000:01:00.0
```

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

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

Ключи:

- `--programmer` — строка программатора для `flashrom`
- `--chip` — имя SPI-чипа
- `--flashrom-bin` — путь к бинарю `flashrom`

Пример:

```bash
asm3042-fw permanent-read /root/asm.backup.bin --programmer ch341a_spi
```

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

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

Ключи:

- `--programmer` — строка программатора для `flashrom`
- `--chip` — имя SPI-чипа
- `--flashrom-bin` — путь к бинарю `flashrom`
- `--backup-file` — путь для обязательного backup
- `--overwrite-backup` — разрешить перезапись backup
- `--no-verify` — отключить verify

Пример:

```bash
asm3042-fw permanent-write \
  /path/to/firmware.bin \
  --programmer ch341a_spi \
  --backup-file /root/asm.backup.bin
```

## Логи

Опасные операции автоматически пишут `*.log` рядом с рабочим файлом или в текущую директорию. Этот лог можно сразу присылать для разбора ошибок.
