From 4e53bd880c31223ceb51c39b3f2e8928fa977318 Mon Sep 17 00:00:00 2001
From: Quentin BUISSON-DEBON <contact@qbuissondebon.eu.org>
Date: Sat, 26 Sep 2026 17:11:25 +0200
Subject: [PATCH] Add README

---
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/README.md b/README.md
index e69de29..67b15ee 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,82 @@
+# 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.