Initial commit

doc/input-output.md

@@ -0,0 +1,100 @@
+# Input and Output Protocol
+
+## Physical Dial Input
+
+The driver reads the `Surface Dial System Multi Axis` evdev device.
+
+Find it with:
+
+```bash
+rg -n -C 8 "Surface Dial System Multi Axis" /proc/bus/input/devices
+```
+
+Then inspect raw data:
+
+```bash
+sudo evtest /dev/input/eventXX
+```
+
+Expected raw events:
+
+```text
+EV_REL / REL_DIAL: rotation
+EV_KEY / BTN_0: button press and release
+EV_SYN and EV_MSC: ignored framing/scancode events
+```
+
+The `Surface Dial System Control` node is not used for scrolling. It exposes
+sleep/wakeup-style keys, not rotation.
+
+## Virtual Touchpad
+
+The multitouch output device is named:
+
+```text
+Surface Dial Renewed Touchpad
+```
+
+It exposes a type-B multitouch touchpad with slots. On gesture start it creates
+two active tracking IDs. On movement it moves both slots along the Y axis and
+updates the single-touch compatibility `ABS_Y` value.
+
+Important implementation details:
+
+- Two fingers are used because libinput interprets that as scroll.
+- `INPUT_PROP_POINTER` is enabled.
+- `INPUT_PROP_BUTTONPAD` is intentionally not enabled.
+- `BTN_LEFT` is intentionally not exposed.
+- Pressure/touch-major/tool-width axes are exposed to look more like a real
+  touchpad.
+
+The lack of buttonpad/left-button capability reduces accidental tap/click
+interpretation when a scroll gesture is short.
+
+## Gesture Lifecycle
+
+`multitouch_start`
+
+Creates slot 0 and slot 1 with tracking IDs, positions, pressure, touch major,
+and two-finger tool state.
+
+`multitouch_move`
+
+Moves both slots to the same new Y position. The driver keeps an accumulated
+`mt_position` relative to `MT_BASELINE`.
+
+`multitouch_settle`
+
+Emits one final stationary frame before ending. This reduces the chance that the
+final movement is interpreted as a flick.
+
+`multitouch_end`
+
+Sets both tracking IDs to `-1`, releases `BTN_TOUCH` and tool keys, and reports
+zero pressure.
+
+## Coordinate Model
+
+`MT_BASELINE` is `10_000`, with coordinates from `0` to `20_000`.
+
+The driver recenters the synthetic gesture if `mt_position` exceeds
+`MT_RECENTER_THRESHOLD`. This avoids running into coordinate limits during long
+scrolls.
+
+## Virtual Wheel
+
+The fallback wheel device is named:
+
+```text
+Surface Dial Renewed Wheel
+```
+
+It emits both:
+
+```text
+REL_WHEEL
+REL_WHEEL_HI_RES
+```
+
+Wheel mode is implemented but has not received the same tuning as multitouch
+mode.