cschalle / hw-harness

# hw-harness
Tooling for working out how a piece of hardware behaves, so you can write a
Linux driver for it.
The premise: for most unsupported hardware, a working driver already exists —
the vendor's Windows one. You should not read it, and you do not need to. Run
it in a VM, give it the real device, and record what crosses the wire **from
outside the VM**. You get a ground-truth transcript of a working session
against your exact hardware, which you then reproduce from Linux.
`usbmon` runs on the host kernel, below the passthrough layer, so the guest
cannot tell it is being watched — and the same instrument records your Linux
driver doing the same operation. The two traces are directly comparable. That
comparison is the method; everything here exists to make it routine.
Built while writing a SANE backend for a Plustek film scanner and fixing an
Intel IPU7 + IMX471 laptop camera. Start with **doc/method.md**.
## What you get
| | |
|---|---|
| `harness` | scaffold a project, check your machine, build the guest bootstrap ISO |
| `winctl` | drive the Windows VM: SSH, off-screen RDP, synthetic input, device probes |
| `usbcap` | time-boxed `usbmon` capture of the device, with metadata sidecars |
| `hostdev` | move the device between host and guest |
| `hwdbg` | scoped root helper for Linux-side debugging: modules, debugfs, i2c, ACPI |
Plus `probes/`: a PowerShell device/driver/firmware dumper that collects
descriptors, PnP properties, registry trees, ACPI tables and INF files — and
deliberately does not touch vendor `.sys` code.
## Requirements
Developed and tested on Fedora. You need libvirt/KVM and a **Windows 11 Pro**
guest (Home has no RDP server):
 sudo dnf install libvirt virt-manager freerdp xorg-x11-server-Xvfb \
 xdotool libsecret wireshark-cli usbutils ImageMagick \
 acpica-tools xorriso
 sudo usermod -aG libvirt,wireshark $USER # then log out and back in
`harness doctor` checks all of it and tells you what is missing and why it
matters.
## Quickstart
One clone of this repo serves every investigation. The clone is the *tool*; a
*project directory* holds one device's configuration, keys and captures.
 git clone https://github.com/YOU/hw-harness ~/src/hw-harness
 export PATH="$HOME/src/hw-harness/bin:$PATH"
 harness doctor
 harness init ~/projects/myscanner
 cd ~/projects/myscanner
 $EDITOR harness.conf # VM_NAME, USB_VID/USB_PID from lsusb
 winctl auth # generates an SSH key, stores the RDP password
 harness iso # bootstrap.iso, carrying the PUBLIC key only
Attach `bootstrap.iso` to the VM and, in an **elevated** PowerShell in the
guest:
 powershell -ExecutionPolicy Bypass -File D:\win-bootstrap.ps1
Back on Linux:
 winctl status # ssh: ok
Then the actual work:
 hostdev to-vm # guest gets the hardware
 sudo -E ./bin/usbcap win-scan-300 90 & # host records it anyway
 winctl up # drive the vendor app off-screen
 winctl shot # see where its GUI really is
 winctl click 840 620
 hostdev to-host # take the device back
 sudo -E ./bin/usbcap linux-sc