Auto-restore the rotation range after the SDK's launch-time 90-degree reset

Closes the '90 degrees on game launch' saga with an automatic fix,
built on the usbmon root cause (games' SDK sessions push an operating
range of 90 via a TrueForce interface-2 packet once at session start,
invisible to HID++) and verified end-to-end against a faithful
reproduction of the game traffic: detection to restore in under
100 ms, and the restored range holds while the session streams.

Mechanism: the 20 s range poll already detects the silent change; when
the external value is exactly 90 and the previous value was not, a
pending restore is recorded and retried on every poll tick until it
lands, strikes out, or becomes moot. Safety gates, each earned from a
real incident during development:

- only the known pathology (external change landing exactly on 90) is
  restored; any other externally-set value is a game applying its
  configured steering lock and is respected;
- desktop mode only, never an automatic mode switch (mode churn under
  load is what historically desynced the centre);
- the wheel must be stationary, measured with two on-demand HID++
  encoder reads 50 ms apart (the cached position only updates when
  the wheel emits input reports, and the raw encoder's centre is
  wherever calibration put it, so only deltas are compared - both
  discovered the hard way when earlier gates deferred forever);
- restores only ever widen the range, which cannot snap the wheel
  against new soft stops;
- at most 3 restores per session, then log and yield; an explicit
  wheel_range write supersedes everything.

New sysfs attribute wheel_range_restore (default 1; 0 = the previous
detect-and-report-only behaviour). Also extracted rs50_set_range_hw
from wheel_range_store for shared use, and added gate-visibility
hid_dbg lines used to verify the mechanism live.

Author: mescon

README.md

@@ -146,13 +146,15 @@ All effects are routed to the wheel's single direct-drive motor
 
 > **Caveats:**
 > - Some sims (AC EVO observed) reset the wheel's rotation range to
->   **90° once at session start**, via the game's own SDK path. The
->   driver detects this within 20 seconds, corrects the reported
->   `wheel_range`, and logs `rotation range changed externally` in
->   dmesg. Recover by re-applying it from the game's pause menu:
->   `wheel_profile=0` then `wheel_range=<degrees>` - the re-applied
->   range sticks for the rest of the session (verified through full
->   laps). The in-game FFB gain is the master force control;
+>   **90° once at session start**, via the game's own SDK path (a
+>   TrueForce operating-range packet, usbmon-verified). The driver
+>   detects this within 20 seconds and **restores your range
+>   automatically** (`wheel_range_restore`, default on, heavily
+>   safety-gated - see `docs/SYSFS_API.md`), logging both the
+>   external change and the restore in dmesg. Also check the game's
+>   own steering-rotation setting (AC EVO: "Steering lock") - once
+>   touched and re-applied, the game pushes its configured value
+>   itself. The in-game FFB gain is the master force control;
 >   `wheel_strength` is the wheel-side multiplier.
 > - AC EVO's **map-load centring force** has once been observed ringing
 >   the wheel into its over-torque failsafe (the base shuts itself off;

docs/SYSFS_API.md

@@ -123,12 +123,40 @@ stall the force stream; it catches up within one interval of the
 effects stopping); if it changed externally,
 the reported `wheel_range` value is updated to the real one, the
 change is logged in dmesg (`rotation range changed externally`), and
-`poll()`ers on the attribute are notified via `sysfs_notify()`. The
-driver deliberately does NOT write the old range back on its own:
-re-applying range or mode while a game holds active FFB desyncs the
-centre on a direct-drive wheel. To recover, write `0` to
-`wheel_profile` and re-set `wheel_range` yourself (safe once FFB is
-idle, e.g. in the game's menus).
+`poll()`ers on the attribute are notified via `sysfs_notify()`.
+When the external value is exactly 90 (the known SDK session-init
+pathology - see `wheel_range_restore` below), the driver also
+restores the previous range automatically.
+
+### wheel_range_restore
+**Access**: Read/Write
+**Values**: `0` or `1`
+**Default**: `1`
+
+Automatic recovery from the launch-time 90-degree reset. Root cause
+(usbmon-verified): some games' SDK sessions push an operating range
+of 90 degrees once at session start via a TrueForce interface-2
+packet, invisible to HID++. With this enabled, the driver restores
+the pre-reset range automatically. Verified end-to-end against a
+faithful reproduction of the game traffic: detection to restore in
+under 100 ms once the poll samples the change.
+
+Safety gates, each earned from a real incident:
+- fires only for an EXTERNAL silent change landing exactly on 90;
+  any other externally-set value (a game applying its configured
+  steering lock: 540, 850, ...) is respected as legitimate intent;
+- desktop mode only, and never an automatic mode switch;
+- the wheel must be stationary (two encoder reads 50 ms apart);
+  restores only ever widen the range, which cannot snap the wheel;
+- at most 3 restores per session, then the driver logs and yields
+  (`an external writer keeps changing the rotation range`);
+- an explicit `wheel_range` write supersedes any pending restore
+  and resets the strike counter.
+
+`0` = detect-and-report only (the pre-2026-07-03 behaviour): the
+change is still logged and `wheel_range` stays honest, but recovery
+is manual (`wheel_profile=0` then `wheel_range=<degrees>` once FFB
+is idle).
 
 ### wheel_strength
 **Access**: Read/Write