qbuissondebon
70a6ff9b1a
AGENTS.md now documents the real workflow: single remote origin (SSH), push only on explicit request, never force-push or add remotes unasked. README gains the Gitea repo link and points the driver requirement at cmpunlocker's driver/VERSION (610.xx / 615.xx).
31 lines
3.5 KiB
Markdown
31 lines
3.5 KiB
Markdown
# Project instructions
|
|
|
|
## Purpose
|
|
|
|
This repository checks one NVIDIA CMP 170HX at a time on a fresh Ubuntu 26.04 x86-64 host. The normal sequence is: prepare driver and tools, check PCIe lane width, install cmpunlocker for stock memory, cold boot, confirm unlocked memory, then check the final PCIe link. The capacitor width check passes at **x16**, even if the link is Gen1. A completed post-unlock card check passes only at **Gen2 x16**.
|
|
|
|
## Source and outputs
|
|
|
|
- `check_cards.py` owns the CLI, per-card flow, report scoring, and terminal result.
|
|
- `cxlib.py` owns host setup, the cmpunlocker harness clone/update and opt-in installer, card identity, subprocess logging, PCIe inspection, and optional VBIOS backup.
|
|
- `README.md` is the operator guide. Keep its flags, output paths, reboot steps, and exit codes aligned with the code.
|
|
- `harness/`, `cards/`, and `unidentified/` contain generated source, logs, reports, or firmware backups. Do not commit their contents.
|
|
- The bundled `nvflash_5.867_linux/` contains the optional backup tool. Backups belong under `extras/`, not at repository root.
|
|
|
|
## Invariants
|
|
|
|
- A card folder is named from an automatically read **physical serial number**. Never request manual serial entry or substitute a GPU UUID or PCI address for a serial. When serial lookup fails, continue the run under `unidentified/` and report the missing serial.
|
|
- Match every card-sensitive operation to the detected PCI address. A host may have another NVIDIA GPU even though only one CMP 170HX is being checked.
|
|
- Measure capacitor-related lane width before unlocking. The width result is independent of cmpunlocker: Gen1 x16 passes the width check, while x4 fails it. Do not claim the capacitor is physically verified; the width is an observed link result on the current host.
|
|
- Keep the final PCIe acceptance check after unlock. Preserve a red `[ERROR]` message and failing exit for any final link other than Gen2 x16. Gen1 x16 passes the earlier width check but fails the final card check.
|
|
- Preserve cold-boot state by card identity. GPU UUID may be used internally for this purpose, but not as a folder name.
|
|
- The cmpunlocker harness is cloned from upstream **main** into `harness/cmpunlocker/`, and `git pull --ff-only` runs before every install (a failed pull warns and continues with the existing checkout). Invoke `install.sh` only with flags the checked-out version actually accepts — currently **no flags**; never pass `--no-passthrough` to older checkouts without verifying them first.
|
|
- VBIOS backup is optional and read-only. Select the detected PCI address for nvflash and sysfs ROM operations. Never add a flashing step to the normal workflow.
|
|
|
|
## Working in this repository
|
|
|
|
- The repository has a single remote, `origin` (`git@git.ssh.qbuissondebon.eu.org:qbuissondebon/cmp170hx_check.git`, web: https://git.qbuissondebon.eu.org/qbuissondebon/cmp170hx_check), default branch `main`. Local status, diff, and commits are allowed at any time. Push to `origin` only when the user explicitly asks for it. Never force-push, never rewrite pushed history, and never add another remote without an explicit request.
|
|
- Do not run host setup, unlock, VBIOS, or PCIe mutation commands on a development machine. Those actions belong on the intended Ubuntu host when the user requests them.
|
|
- Keep reports and long-running installation logs visible and useful to an operator. Save full output on disk; show installation progress in the terminal.
|
|
- If asked to verify without a card, `python3 check_cards.py --demo` is the synthetic path. It does not establish hardware correctness.
|