# cmp170hx_check

Guided, one-card-at-a-time batch checker for **NVIDIA CMP 170HX** cards (PCI IDs `10de:20c2` / `10de:2082`) — verifies the PCIe capacitor mod, records PCIe bus health, backs up VBIOS, runs the cmpunlocker verification, and optionally stresses VRAM. Built for a 23-card run, with one folder + JSON report per card serial.

Reference harness (auto-cloned into `harness/` by preflight):

- [170th-Street](https://github.com/amoghmunikote/170th-Street) — community docs, incl. `modifications/pcie-capacitor-mod.md` (the pass criteria: `LnkSta Width x16` after the mod, `x4` when missing)
- [cmpunlocker](https://github.com/amoghmunikote/cmpunlocker) — `verify.sh` is executed **read-only** per card (nothing is installed or patched by this tool)

## Requirements

- Linux x86-64, Python 3.8+
- `pciutils` (`lspci`, `setpci`) — auto-installed if a package manager is present
- Root (`sudo`) for: PCI bus rescan, link retrain, sysfs ROM read, `dmesg`, `verify.sh`
- NVIDIA driver with `nvidia-smi` (nvidia-open 610.xx+, see cmpunlocker) for unlock verification
- `nvflash` (not packaged — download from NVIDIA or pass `--nvflash /path/to/nvflash`) for VBIOS backup and serial auto-read
- Optional: `vkmark` or `vulkan-tools` for the 5-minute VRAM stress test

Missing tools are reported by preflight; packages are auto-installed where possible, otherwise instructions are printed.

## Usage

```bash
python3 check_cards.py               # full run, 23 cards, guided
python3 check_cards.py --preflight   # tool check / install / harness clone only
python3 check_cards.py --demo        # self-test with fake hardware (no GPU needed)
python3 check_cards.py --help        # all flags
```

Normal run flow, repeated per card:

1. `Insert card N/23, then press Enter` (`s` = skip, `q` = quit)
2. GPU auto-detected on the bus (PCI rescan retry offered if absent)
3. Serial auto-read from nvflash UUID; falls back to a manual label prompt
4. VBIOS backup → `cards/<serial>/bios.rom` (nvflash, sysfs ROM fallback)
5. PCIe checks: link speed/width, AER counters, full config-space dump
6. Link retrain test + full bus rescan test (device must survive both)
7. Kernel log scrape (`dmesg`/`journalctl`) for this BDF: Xid / AER / NVRM lines
8. `nvidia-smi` snapshot + `harness/cmpunlocker/verify.sh` (read-only)
9. **Last step, optional**: `Run 5-min Vulkan VRAM stress test now? (y/N)` — refused by default, `--vulkan always|never` to override
10. Result + `report.json` written; progress saved to `progress.json` (resumable)

## Checks & scoring (lenient)

| Result | Criteria |
|--------|----------|
| **FAIL** | no device detected, link down/untrained, device lost after rescan, link failed retrain, active uncorrectable AER errors |
| **WARN** | link width ≠ `x16` (capacitor mod missing/incomplete), Gen1 only (Gen2 unlock patch not active), correctable AER errors, kernel errors / Xid, VBIOS backup failed, cmpunlocker verify not `unlocked-ok`, errors during VRAM stress |
| **PASS** | everything clean |

## Output

```
cards/
└── <serial>/
    ├── bios.rom              # VBIOS backup (+ sha256 in report)
    ├── report.json           # full result: link, AER before/after, retrain,
    │                          #   rescan, dmesg, verify, vulkan, PASS/WARN/FAIL
    ├── lspci.txt             # lspci -vvv (before)
    ├── lspci_after.txt       # lspci -vvv (after retrain/rescan)
    ├── config_space.hex      # lspci -nnvvxxxx full hex dump
    ├── dmesg.log             # kernel lines related to this card
    └── verify_unlocker.log   # cmpunlocker verify.sh output
progress.json                 # which card indices are done (resume support)
```

## Useful flags

| Flag | Meaning |
|------|---------|
| `--cards N` / `--start N` | total cards (default 23) / first index |
| `--nvflash PATH` | explicit nvflash binary |
| `--serial XYZ` | override serial for the next card |
| `--vulkan ask\|always\|never` | VRAM test policy (default: ask, last step) |
| `--skip-bios` | skip VBIOS backup |
| `--no-install` / `--no-clone` | don't auto-install packages / don't clone harness |
| `--restart` | ignore `progress.json` and start over |
| `--no-pause` | don't wait for the insert prompt |

## Safety

This tool only **reads** card state: `verify.sh` is run without installing anything, no modules are patched, no firmware is flashed. The only writes are local files, PCI link retrain/rescan sysfs triggers, and your own reports.