Candidate/driver alignment on par other drivers and captures (#11)

Driver alignment on par other drivers and captures

Motivation

- Align the T500RS driver’s runtime behavior with the T300/TS‑X pattern and with Windows usbmon captures to improve correctness and reduce in‑game dropouts.

- Ensure parameter updates don’t force re‑uploads, and preserve the device’s idiosyncrasies (EffectID=0 for 0x01/0x41, fixed constant linkage).

What’s changed

- Update path parity (parameter‑only updates; no STOP/0x01 re‑upload):
* FF_CONSTANT: send only Report 0x03 (code=0x0e) with new level.
* FF_PERIODIC: send only Report 0x04 with new magnitude + frequency (Hz×100).
* FF_SPRING/FF_DAMPER/FF_FRICTION/FF_INERTIA (conditions): send only two Report 0x05 packets (coeff/saturation via param_sub; deadband/center via env_sub_first).
* FF_RAMP: send only Report 0x04 with start/cur_val/duration.

- Subtype rules:
* Constant force uses fixed linkage (Report 0x03 code=0x0e; 0x01 b9=0x0e, b11=0x1c; 0x02 subtype=0x1c).
* Periodic/ramp/condition continue to use per‑effect subtypes (param_sub = 0x0e + 0x1c×index; env_sub_first = 0x1c + 0x1c×index).

- Upload sequence parity with captures:
* Pre‑upload STOP (0x41 00 01), dual 0x02 envelopes, 0x01 first/second, and effect‑specific parameter packets (0x03/0x04/0x05) as observed on Windows.

- Protocol correctness fixes and clarifications:
* Periodic parameter uses frequency in Hz×100 (not period in ms).
* EffectID semantics enforced: 0x01/0x41 use EffectID=0 (exception: init STOP for autocenter).

- Quality‑of‑life:
* Range setting simplified to a single 0x40 0x11 command (removed smoothing).
* Wine compatibility: ignore AC=100% requests to avoid permanent autocenter in titles like LFS; documented rationale.

Author: cazzoo

docs/FFB_T500RS.md

@@ -2,6 +2,17 @@
 
 This page documents the packet formats and ordering used by the T500RS when driven via the USB interrupt endpoint (0x01 OUT). It mirrors the style of docs/FFBEFFECTS.md for other wheels.
 
+
+Quick reference (Windows parity, at-a-glance)
+- EffectID rule: All 0x01 uploads and 0x41 START/STOP use EffectID=0x00
+- Subtypes per effect index n: param = 0x0e + 0x1c×n; envelope = 0x1c + 0x1c×n; second envelope = first + 0x1c
+- Periodic 0x04 uses frequency (Hz×100), not period (ms)
+- Upload sequences (per effect):
+  - Constant: STOP → 0x02 → 0x01 → 0x02 → 0x03 → 0x01 → START
+  - Periodic (sine/square/triangle/saw): STOP → 0x02 → 0x01 → 0x02 → 0x04 → 0x01 → START
+  - Ramp: STOP → 0x02 → 0x01 → 0x02 → 0x04 → 0x01 → START
+  - Condition (spring/damper/friction/inertia): STOP → 0x05(set1) → 0x05(set2) → 0x01 → START
+
 Key rules
 - Little‑endian for 16‑bit fields
 - DMA‑safe buffer length 32 bytes; typical messages are 2, 4, 9 or 15 bytes
@@ -10,6 +21,14 @@ Key rules
   - Report 0x41 START/STOP also uses EffectID = 0x00, except the init‑time STOP for autocenter which targets a fixed ID (15)
   - Using per‑effect IDs with 0x01 breaks playback (constant force fails completely)
 
+Special case — constant force subtypes
+
+- For FF_CONSTANT, the device uses fixed subtypes to link the 0x03 level update:
+  - Report 0x02 subtype = 0x1c
+  - Report 0x01 b9 = 0x0e (parameter), b11 = 0x1c (envelope)
+  - Report 0x03 code = 0x0e
+- Using per‑effect subtypes for constant breaks level updates (no force felt).
+
 Report glossary
 - 0x01 main upload (15 bytes)
   - Layout (unknown bytes kept for completeness):
@@ -22,9 +41,9 @@ Report glossary
     - b6 0x00
     - b7 0xff
     - b8 0xff
-    - b9 0x0e (parameter subtype)
+    - b9 param subtype = 0x0e + 0x1c×index
     - b10 0x00
-    - b11 0x1c (envelope subtype)
+    - b11 envelope subtype = 0x1c + 0x1c×index
     - b12 0x00
     - b13 0x00
     - b14 0x00
@@ -41,7 +60,7 @@ Report glossary
   - b0 0x04, b1 0x0e, b2 0x00
   - b3 magnitude u7 (0..127)
   - b4 offset = 0, b5 phase = 0
-  - b6..7 period (le16, ms)
+  - b6..7 frequency (le16, Hz×100)  (e.g., 10 Hz → 0x03e8)
 - 0x04 ramp params (9 bytes)
   - b0 0x04, b1 0x0e
   - b2..3 start (le16), b4..5 cur_val (le16), b6..7 duration (le16), b8 0x00
@@ -56,27 +75,76 @@ Report glossary
 - 0x42 apply/apply‑like, 0x43 gain
 
 Effect upload and play ordering
+
+- Subtype system (applies to 0x01/0x02/0x04/0x05 references)
+  - Envelope subtype base = 0x1c; Parameter subtype base = 0x0e
+  - For effect index n: envelope = 0x1c + 0x1c×n; parameter = 0x0e + 0x1c×n
+  - In 0x01: b9 = parameter subtype; b11 = envelope subtype
+
+- Global (Windows parity)
+  - Precede uploads with 0x41 STOP (command=0x00, arg=0x01), effect_id=0x00, to clear state
+
 - Constant (FF_CONSTANT)
-  1) 0x02 envelope
-  2) 0x01 main (type=0x00, effect_id=0x00)
-  Play: 0x03 level, then 0x41 START (effect_id=0x00)
+  1) 0x41 STOP
+  2) 0x02 envelope (first; subtype = 0x1c + 0x1c×index)
+  3) 0x01 main (first; b9/b11 reference current param/envelope subtypes)
+  4) 0x02 envelope (second; subtype += 0x1c)
+  5) 0x03 level
+  6) 0x01 main (second; update references)
+  Play: 0x41 START (effect_id=0x00)
+
 - Periodic (FF_SINE/FF_SQUARE/FF_TRIANGLE/FF_SAW)
-  1) 0x02 envelope
-  2) 0x01 main (type=0x20..0x24, effect_id=0x00)
-  3) 0x04 periodic params (magnitude/period)
-  4) 0x01 main (type repeated, effect_id=0x00)
+  1) 0x41 STOP
+  2) 0x02 envelope (first)
+  3) 0x01 main (first; type=0x20..0x24, effect_id=0x00)
+  4) 0x02 envelope (second; subtype += 0x1c)
+  5) 0x04 periodic params (magnitude/frequency)
+  6) 0x01 main (second; type repeated)
   Play: 0x41 START (effect_id=0x00)
+
 - Condition (FF_SPRING/FF_DAMPER/FF_FRICTION/FF_INERTIA)
-  1) 0x05 coeff/saturation (0x0e)
-  2) 0x05 deadband/center (0x1c)
-  3) 0x01 main (type reflects subkind, effect_id=0x00)
+  1) 0x41 STOP
+  2) 0x05 coeff/saturation (param subtype = 0x0e + 0x1c×index)
+  3) 0x05 deadband/center (envelope subtype = 0x1c + 0x1c×index)
+  4) 0x01 main (type reflects subkind, effect_id=0x00; b9/b11 reference above)
   Play: 0x41 START (effect_id=0x00)
+
 - Ramp (FF_RAMP)
-  1) 0x02 envelope
-  2) 0x04 ramp params (device behaves like hold of start level with duration)
-  3) 0x01 main (type=0x24, effect_id=0x00)
+  1) 0x41 STOP
+  2) 0x02 envelope (first)
+  3) 0x01 main (first; type=0x24, effect_id=0x00)
+  4) 0x02 envelope (second; subtype += 0x1c)
+  5) 0x04 ramp params (device behaves like hold of start level with duration)
+  6) 0x01 main (second)
   Play: 0x41 START (effect_id=0x00)
 
+
+Live update behavior (parameter‑only; Windows parity)
+
+- Overview
+  - Parameter updates do not re‑upload effects or send STOP; they modify parameters in place.
+  - This reduces USB traffic and avoids momentary dropouts during gameplay.
+  - 0x01/0x41 still follow the EffectID=0 rule; 0x04/0x05 carry subtypes, not effect IDs.
+
+- Constant (FF_CONSTANT)
+  - Send only 0x03 with new level; code must be 0x0e (fixed linkage to constant path).
+  - No 0x41 STOP and no 0x01 re‑upload for updates.
+
+- Periodic (FF_SINE/FF_SQUARE/FF_TRIANGLE/FF_SAW)
+  - Send only 0x04 with new magnitude and frequency.
+  - Frequency field is Hz×100 (e.g., 10 Hz → 1000); offset/phase remain 0 unless changed.
+  - Use per‑effect param_sub = 0x0e + 0x1c×index.
+
+- Condition (FF_SPRING/FF_DAMPER/FF_FRICTION/FF_INERTIA)
+  - Send 0x05 (coeff/saturation) with param_sub, then 0x05 (deadband/center) with env_sub_first.
+  - Subtypes are the same as in the upload path; spring uses subtype bytes 0x54, others 0x64 for the tail fields.
+  - No 0x01 re‑upload.
+
+- Ramp (FF_RAMP)
+  - Send only 0x04 (start/cur_val/duration, last byte 0x00) using param_sub.
+  - Device behavior approximates ramp via holding/stepping the start value over duration; matching observed Windows behavior.
+
+
 Notes
 - All 0x01 uploads must use EffectID=0x00. This was validated on hardware; using per‑effect IDs causes constant force to fail completely and can break other effects.
 - 16‑bit values are little‑endian (lo byte first).

src/hid-tmff2.c

@@ -6,20 +6,6 @@
 #include "hid-tmff2.h"
 
 
-/* Known vendor/opcode IDs managed by the driver (TX side) */
-static inline int tmff2_is_known_vendor_id(unsigned char id)
-{
-	switch (id) {
-	case 0x01: case 0x02: case 0x03: case 0x04: case 0x05:
-	case 0x40: case 0x41: case 0x42: case 0x43:
-	case 0x0a:
-		return 1;
-	default:
-		return 0;
-	}
-}
-
-
 int open_mode = 1;
 module_param(open_mode, int, 0660);
 MODULE_PARM_DESC(open_mode,
@@ -256,6 +242,22 @@ static ssize_t gain_store(struct device *dev,
 	}
 
 	gain = value;
+
+	/* Rationale: two-level gain model
+	* - The input API's set_gain (pg) is the in-game gain (0..GAIN_MAX).
+	* - This driver also exposes a device/system gain via sysfs param `gain`.
+	* - The device callback receives the product: (pg * gain) / GAIN_MAX.
+	*   See worker at tmff2->set_gain(... (pg * gain) / GAIN_MAX ).
+	* When the sysfs `gain` changes, we trigger a recompute by pushing
+	* pending_gain_value = GAIN_MAX here so the effective device gain becomes
+	* exactly the sysfs value (GAIN_MAX * gain / GAIN_MAX == gain) and future
+	* in-game set_gain calls continue to multiply in.
+	*
+	* References:
+	* - docs/FFBEFFECTS.md: section "FF_GAIN" shows a dedicated device gain path.
+	* - docs/FFB_T500RS.md: Report glossary mentions 0x43 (gain), i.e., device-side
+	*   gain separate from per-effect magnitudes; drivers should expose both levels.
+	*/
 	if (tmff2->set_gain) {
 		unsigned long flags;
 		spin_lock_irqsave(&tmff2->lock, flags);
@@ -376,7 +378,7 @@ static void tmff2_work_handler(struct work_struct *w)
 		effect_length = state->effect.replay.length;
 		/* If playing with a finite length, stop when (delay + length) elapses */
 		if (test_bit(FF_EFFECT_PLAYING, &state->flags) && effect_length) {
-			if ((time_now - state->start_time) >= 
+			if ((time_now - state->start_time) >=
 					(effect_delay + effect_length) * state->count) {
 				__clear_bit(FF_EFFECT_PLAYING, &state->flags);
 				__clear_bit(FF_EFFECT_QUEUE_UPDATE, &state->flags);
@@ -853,7 +855,6 @@ static void tmff2_remove(struct hid_device *hdev)
 	if (tmff2->params & PARAM_DAMPER_LEVEL)
 		device_remove_file(dev, &dev_attr_damper_level);
 
-
 	if (tmff2->params & PARAM_SPRING_LEVEL)
 		device_remove_file(dev, &dev_attr_spring_level);
 
@@ -889,6 +890,7 @@ static const struct hid_device_id tmff2_devices[] = {
 
 	{}
 };
+MODULE_DEVICE_TABLE(hid, tmff2_devices);
 
 static struct hid_driver tmff2_driver = {
 	.name = "tmff2",