Skip to content

Latest commit

 

History

History
128 lines (98 loc) · 5.39 KB

touchpad.md

File metadata and controls

128 lines (98 loc) · 5.39 KB

Touchpad PS2 Emulation

The touchpad in all Framework Laptops uses I2C to connect to the CPU. That means the OS needs to have an I2C driver for the touchpad to work.

Windows does not ship the Intel I2C driver in the official installer. For prebuilt systems, we include this driver in the factory image, so that everything works out of the box. But when users install Windows manually, this driver is not included and the touchpad wouldn't work.

To make sure the touchpad works anyways, Framework Laptops with Intel CPUs have the touchpad I2C bus also connected to the embedded controller (EC). The EC firmware detects if the touchpad is generating interrupt but no OS driver is requesting touch data. If this happens, the EC jumps into action. It switches the touchpad from PTP (Precision Touchpad Protocol) mode to mouse mode reporting (relative mouse movement and left-click only) and forwards that data to the CPU via the PS2 protocol over eSPI.

If the EC detects the OS communicating with the touchpad (i.e. driver installed), it steps back and let's the OS handle things with the native PTP driver.

While rare, PS2 emulation may kick in when it shouldn't, so if your touchpad is behaving strangely, you can determine if PS2 emulation is the root-cause by the instructions in this document.

Disabling PS2 Emulation

It is enabled by default but can be disabled in the BIOS settings under the "Advanced" menu.

"Auto" means EC detects if it's necessary - enables/disables as needed.

"Off" means PS2 emulation is never enabled - this setting is fine, if you never plan to use the touchpad in the Windows installer.

Check if PS2 emulation is used

By testing functionality

The following features (and more) are not supported by PS2 mouse emulation, so if moving the cursor works but these features don't, PS2 emulation is currently active:

  • Two finger scroll
  • Two finger tap right-click
  • Three finger tap middle-click
  • Any other multi-finger gesture

With libinput on Linux

  1. By listing devices check if the I2C PTP driver is working.

The PS2 device is always shown, no matter if PS2 emulation is enabled or not, so this is not a conclusive test.

# I2C PTP driver is working
> sudo libinput list-devices | grep -e Touchpad -e Mouse
Device:                  PIXA3854:00 093A:0274 Touchpad
Device:                  PIXA3854:00 093A:0274 Mouse
Device:                  ImExPS/2 Generic Explorer Mouse

# I2C PTP driver is not working
> sudo libinput list-devices | grep -e Touchpad -e Mouse
Device:                  ImExPS/2 Generic Explorer Mouse
  1. By checking functionality

Run sudo libinput debug-events and touch the touchpad.

Pointer motion events are generated by any mouse/touchpad driver:

>  event7   POINTER_MOTION           39  +121.521s         18.00/-38.00 ( +9.00/-19.00)

Touch the touchpad with multiple fingers, like a 2 finger scrolling gesture. If nothing appears, the PS2 driver is used. It does not support multitouch. If the following gesture events (or similar) appear, the I2C PTP driver is correctly working:

-event4   GESTURE_HOLD_BEGIN           +255.667s        2
 event4   GESTURE_HOLD_END             +255.760s        2
 event4   GESTURE_HOLD_BEGIN           +258.876s        1
 event4   GESTURE_HOLD_END             +258.918s        1
 event4   GESTURE_HOLD_BEGIN           +260.079s        2
 event4   GESTURE_HOLD_END             +260.137s        2
 event4   GESTURE_HOLD_BEGIN           +261.982s        2
 event4   GESTURE_HOLD_END             +262.034s        2 cancelled
 event4   POINTER_SCROLL_FINGER        +262.041s        vert 3.08/0.0* horiz 0.00/0.0 (finger)
 event4   POINTER_SCROLL_FINGER     2  +262.047s        vert 2.64/0.0* horiz 0.00/0.0 (finger)
 event4   POINTER_SCROLL_FINGER     3  +262.062s        vert 0.44/0.0* horiz 0.00/0.0 (finger)
 event4   POINTER_SCROLL_FINGER     4  +262.076s        vert 1.76/0.0* horiz 0.00/0.0 (finger)
 event4   POINTER_SCROLL_FINGER     5  +262.083s        vert 1.32/0.0* horiz 0.00/0.0 (finger)

With hid-recorder on Linux

Use hid-recorder and select TBD or quicki2c-hid. Then touch the touchpad - if reports are appearing and they look like below, the proper I2C precision touchpad (PTP) driver is working.

> sudo hid-recorder
Available devices:
/dev/hidraw0:   FRMW0005:00 32AC:001B
/dev/hidraw1:   PIXA3854:00 093A:0274
/dev/hidraw2:   FRMW0004:00 32AC:0006
Select the device event number [0-2]: 1
[...]
E: 000024.454466 35 01 03 00 78 02 fe 02 03 01 49 01 56 02 03 02 af 02 77 00 03 03 12 01 33 01 03 04 cb 01 cb 00 05 00 da 82
# ReportID: 1 / Confidence: 1 | Tip Switch: 1 | # | Contact Id:    0 | X:    632 | Y:    766
#             | Confidence: 1 | Tip Switch: 0 | # | Contact Id:    1 | X:    329 | Y:    598
#             | Confidence: 1 | Tip Switch: 1 | # | Contact Id:    2 | X:    687 | Y:    119
#             | Confidence: 1 | Tip Switch: 1 | # | Contact Id:    3 | X:    274 | Y:    309
#             | Confidence: 1 | Tip Switch: 1 | # | Contact Id:    4 | X:    458 | Y:    204 | Contact Count:    5 | Button: 0  0  0 | # | Scan Time:  33568

## EC Console

EC console when no I2C Touchpad driver present and you touch the touchpad for
the first time, causing the EC to enable PS2 emulation:

sudo framework_tool --console follow [223356.619900 PS2M renabling] [223356.623800 Touchpad detected!] [223356.730300 PS2M Touchpad need to reset] [223356.731900 PS2M Unexpected Report ID 0 reconfiguring] [223356.734700 Touchpad detected!]