Skip to content

HID: magicmouse: J813/J815 trackpad touch states, palm rules and palm-free click - #2613

Open
m0d16l14n1 wants to merge 7 commits into
aurora-silicon:integration/aurorafrom
m0d16l14n1:j815/touch-parity
Open

m0d16l14n1 wants to merge 7 commits into
aurora-silicon:integration/aurorafrom
m0d16l14n1:j815/touch-parity

Conversation

@m0d16l14n1

@m0d16l14n1 m0d16l14n1 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Carries #2116, which gig3m closed in favour of this PR. The first two commits are its J813 palm commit (751b6d50, Kyle's) and the J815 follow-up (6bfbc998), rebased but otherwise unchanged. The five after them:

  • e143d679 dt-bindings: input: apple,dockchannel-hid: Describe trackpad touch states and palm rules
  • 3fa72f8a arm64: dts: apple: t8142-j813, t8142-j815: Describe the trackpads' palm rules
  • c99a772f HID: magicmouse: report only touching MTP contacts, in path-ID slots
  • a89f8bc5 HID: magicmouse: give the J815 trackpad its own palm rule, from its DT node
  • f5b7717b HID: magicmouse: leave a resting hand's force out of the J815 click

The palm-rule commit replaces the J815 rule from the second commit, which turned out to mark some fingers as palms (details below).

Changed on this head (f5b7717b), from DjDeveloperr's and Ryan's last reviews:

  • Signed thresholds: mtp_palm_area[] is now int, so a raw tool_major with bit 15 set (sign-extended by le16_to_int()) compares as negative instead of as a huge unsigned value that would mark a palm. The binding gives both apple,palm-tool-area values maximum: 32767, and probe warns and leaves the rule off for a value above S16_MAX (a89f8bc5, e143d679).
  • On the surface is an allowlist: with apple,touch-states, only make touch (3) and touching (4) can be on the surface. Every other state, including the J813's zero-size state-0 records, is off it (c99a772f). For states 0-7 that is the same result as before, because state 0 already failed the size test.
  • The ABS_MT_TOOL_TYPE comment and the mtp_palms kernel-doc name the J815 as well.
  • The tree is otherwise the same as f2c267cb. The two carried HID: magicmouse: report the J813 trackpad's palms #2116 commits are byte-identical.

Changed on the previous head:

  • J813 gets apple,touch-states (3fa72f8a). gig3m's J813 recordings (MTP firmware 6310.85.7: 85,862 + 25,093 frames, 1,659 contacts) show the same lifecycles and path IDs as the J815, with no path ID twice in a frame. The records in state 0 between a contact's out of range and its path ID's next start have zero sizes, so the on-surface test already drops them. With the driver commits and both J813 properties, over 8 minutes: 358 make-touch records gave 358 touches, the one hovering contact and 1,252 off-surface records started none, and 22 simultaneous landings each got their own touch.
  • Ordering of apple,palm-tool-area: the binding says the first value is below the second. The driver warns at probe and leaves the rule off if they are swapped.
  • Rebased onto integration/aurora cc14570. My commits carry only my Signed-off-by.

Selected by the trackpad node, not the machine

The trackpad's behaviour is now described by three properties on the multi-touch node, in the same way apple,j700-multitouch selects the C1FE layout:

property meaning J813 J815
apple,touch-states the record's first word carries the touch state and the path ID ✓ ✓
apple,palm-debounce two consecutive palm classes mark a palm (#2116's J813 rule) ✓ —
apple,palm-tool-area = <a b> the J815 rule, with the pad's own thresholds: a hand class past a on two consecutive reports, or any contact on the surface past b. Its force is left out of the click. — <1200 2200>

The binding allows neither apple,palm-debounce together with apple,palm-tool-area, nor any of the three with apple,j700-multitouch. dt_binding_check passes, and the J813/J815 DTBs pass dtbs_check. A J815 DTS with an unknown property, or with both palm rules, is rejected. The T6041 and J616s selections already in the driver still use the machine compatible. I left them as they are; they can move to the node in a follow-up.

How the data was collected

The J815's standard MTP record was decoded against macOS's own parse of the same frames. A small tool registered MTRegisterFullFrameCallback from MultitouchSupport. For each frame it logged the raw 0x75 report next to macOS's parsed contacts (path ID, state, finger class, hand ID, ellipse, pressure) and the cursor and button state. The session ran 10 minutes on macOS 27.2 (MTP firmware 6300.85.6) and covered typing with resting palms, pointing, scrolling and gestures: 607 contacts, 34 of them hands. Every claim below was checked record by record against those labels. The Linux numbers come from evdev traces of A/B runs on the same machine.

1. Touch states and path-ID slots

The low byte of the record's first word is the firmware path ID. The high byte is the touch state:

state meaning reported now
1 start in range no
2 hover in range no
3 make touch yes
4 touching yes
5 break touch no
6 linger in range no
7 out of range no
0 or any other (J813: zero-size records between a contact and the next under its path ID) no

A finger approaching or leaving the pad still has a position and nonzero sizes, so the touch-size test reported it as a touch: 374 such reports in 10 minutes. These states are now dropped.

Contacts now stay in their path ID's slot (input_mt_get_slot_by_key) instead of being matched by distance. Distance matching swaps slots when one finger lifts as another lands in the same frame, which happened in about 100 frames in 10 minutes. The slot is looked up inside the report loop, so contacts that land together get different free slots. INPUT_MT_DROP_UNUSED releases the slots of path IDs that are gone.

The firmware also reuses a path ID in the report right after the old contact goes out of range (40 times in 10 minutes). An out-of-range record no longer keeps its ID's palm mark, so the new contact doesn't inherit it.

2. J815 palm rule

Two consecutive palm classes (≥ 6) mark a palm in the J813 rule, which #2116 currently applies to the J815 too. Against the macOS labels, it marked two finger contacts as palms until they lifted, losing 966 finger reports:

  • a finger-sized contact in the bottom-left corner, flickering between classes 10 and 12;
  • a finger whose class flipped between 3 and 7 for up to 17 reports.

On the J815 the hand classes are 6, 7, 8 and 12; class 10 isn't a hand. The new rule:

  • a hand class with a tool area above 1200, on two consecutive reports, marks a palm;
  • a contact on the surface with a tool area above 2200 is a palm at once, whatever its class. Some resting palms on Linux were never classed as hands: two of them, 28 and 38 mm wide, stayed fingers for 0.6 s, and one made a click. No finger or thumb on the surface passed 2097 on macOS.
  • The test applies only on the surface because a thumb's start-in-range record measured 2428. Without that limit, the mark stayed on for all 35 of its touching reports.
rule, on the macOS session hands marked fingers marked hand reports before the mark
J813 rule, as in #2116 34 / 34 2 (966 reports) 1
hand class > 1400, twice 32 / 34 0 28
hand class > 1200, twice 33 / 34 0 18
this commit: 1200 twice, or > 2200 on the surface 33 / 34 0 8

1400 also missed 4 of 25 palms that rested while typing on Linux (they peaked at 1325-1400). 1100 would mark one finger from the macOS session.

3. A resting hand never clicks

The host derives the click from the summed contact force, and a resting palm reaches the press threshold of 120 on its own. On macOS a resting hand neither clicks nor moves the pointer, while a finger of the other hand still clicks and Force Clicks. This commit leaves out the force of every hand contact:

  • one marked as a palm;
  • one in a hand class with a tool area above 1200 in its first report;
  • one wider than 2200.

I ran pointing, typing, and pointing with one palm resting while the other hand clicked 5 times, in two passes. Each click was attributed from the evdev trace; a hand is a palm-marked contact or one wider than 2200.

commit 1 + class rule only all three commits
clicks 58 59
reached the threshold on finger force alone 9 59
no finger on the pad 10 0
fingers present, below the threshold without the hand 39 0
palm-click phase, pass 1 (5 clicks made) 37 registered 5 registered

Testing

  • Tested on the J815: kernel 7.3 (integration/aurora + this stack), KDE Plasma 6.8, libinput 1.32. The palm, click and touch-state behaviour was tested with the board-matched form of these commits. With the DT above, the code paths are the same: the diff against that form is the property reads and the surface check in magicmouse_mtp_hand().
  • Hardware rows owed on this head (f5b7717b) and its DTB, default command line:
    • J815: a Force Click with one palm resting and the other hand clicking;
    • J815: a thumb landing that starts above 2200, still reported as a finger (the surface-only limit on the 2200 test);
    • J813: a palm resting while typing, under apple,touch-states;
    • pass: no palm click, Force Click registers, palms marked with no finger lost, and the regression line (0 failed units, 0 AVC denials, 0 new kernel errors).
  • Palm click is gone, and clicks from the other hand still register. In the pointing runs, two-finger scroll and 3/4-finger swipes worked as before.
  • J813: it keeps HID: magicmouse: report the J813 trackpad's palms #2116's rule, now from apple,palm-debounce, and gets apple,touch-states, so it needs this series' DTB. No palm landed in gig3m's run with the states on, so the J813 palm rule under the states is still to be exercised.
  • On this head, each changed commit builds with W=1 and no warnings, checkpatch --strict is clean on all seven, and dt_binding_check (apple,dockchannel-hid.yaml) and CHECK_DTBS pass on the J813/J815 DTBs.

Not in this PR:

  • Reporting the contact ellipse as the touch size. touch_major/minor carry the controller's signal total and density, not sizes. Changing that needs a libinput quirk too.
  • libinput jump detection, which drops the start of fast flicks. That belongs in a libinput quirk.

Assisted-by: LLM (Claude:Opus 5.5)

@RyanTheTide

Copy link
Copy Markdown
Contributor

The path-ID slots look right to me: each contact's slot is looked up just before it is reported, so input_mt_report_slot_state() has already marked the earlier contacts of the frame as used and two contacts that land together can't share a slot. Skipping the palm update on out-of-range records also handles the reused path IDs cleanly.

  • hid-magicmouse.c:3045 and :3062: the touch-state decoding is a property of the MTP firmware's report format (6300.85.6) rather than of the J815 chassis, and the PR body expects the J813 runs the same family. Gating it on of_machine_is_compatible("apple,j815") means the J813 and later boards need a driver change to get it. Could mtp_states be keyed on the firmware version or a DT property on the trackpad node, with the 1200/2200 tool-area thresholds as per-pad DT values? If that is too much for this series, a short note in the commit saying why the board match is used would help.
  • magicmouse_mtp_hand(): the > 2200 test there has no magicmouse_mtp_on_surface() guard, unlike the one in magicmouse_mtp_update_palms(). It can't matter today because off-surface records are never reported, but using the same check in both places would keep the two rules from drifting apart.
  • Force Click with the other hand resting is the one behaviour left unchecked. A short run would cover it before this leaves draft.

Assisted-by: LLM (Claude:Opus 5.5)

@RyanTheTide

Copy link
Copy Markdown
Contributor

In magicmouse_probe(), mtp_palm_debounce, mtp_palm_large and mtp_states are set from of_machine_is_compatible("apple,j813") / ("apple,j815"), so the palm rules and touch-state decoding follow the board name rather than the trackpad. The multitouch node np is already in hand here; key these on its compatible (e.g. a per-controller compatible) or on a DT property of that node, the same way mtp_c1fe is selected. That way another board with the same controller gets the behaviour without a code change. Until then this should stay a draft.

@m0d16l14n1

Copy link
Copy Markdown
Contributor Author

@RyanTheTide thanks. All three code points are in the new head 17f519cd, which is rebased onto current integration/aurora (5b596e6e).

Selected by the trackpad node. mtp_states, mtp_palm_debounce and mtp_palm_large now come from properties of the multi-touch node, read from np next to mtp_c1fe:

  • apple,touch-states (bool): the record carries the touch state and path ID.
  • apple,palm-debounce (bool): HID: magicmouse: report the J813 trackpad's palms #2116's J813 rule.
  • apple,palm-tool-area = <1200 2200>: the J815 rule. Its two values are now per-pad DT values instead of MAGICMOUSE_MTP_J815_* constants; they live in msc->mtp_palm_area[].

The series is now:

  1. the binding (07d16112);
  2. the J813/J815 DTS (a233c6ea);
  3. the three driver commits.

Another board with the same controller only needs its DT. The binding rejects apple,palm-debounce together with apple,palm-tool-area, and all three with apple,j700-multitouch. dt_binding_check passes and the J813/J815 DTBs pass dtbs_check; a J815 DTS with a bogus property, or with both palm rules, fails as expected. I went with DT properties rather than the firmware version because the version isn't known at probe, and the thresholds belong to the pad, not the firmware.

magicmouse_mtp_hand(). The > 2200 test (now > mtp_palm_area[1]) has the same magicmouse_mtp_on_surface() guard as in magicmouse_mtp_update_palms(), with a comment that the two use the same tests.

Force Click with the other hand resting: not run yet. I'll do it on the J815 together with the surface-only 2200 change and this DT-selected build, and post the row before taking it out of draft.

The T6041 and J616s selections in the same block still use the machine compatible. I left them out of this series; they could move to the node in a follow-up if you want.

Checks:

  • each commit builds with W=1 and no warnings;
  • checkpatch --strict 0/0/0 on all five;
  • apart from the property reads and the guard, the driver code is the same as the tested a36e1f45.

Assisted-by: Claude Opus 5.5

@RyanTheTide

Copy link
Copy Markdown
Contributor

Checked 17f519c. The three rules now come from the multi-touch node, magicmouse_mtp_hand() uses the same on-surface test as the palm update, and the binding rejects the conflicting combinations. One small thing: nothing checks that apple,palm-tool-area's first value is below the second. A minimum/maximum pair or an ordering note in the binding, or a dev_warn at probe when mtp_palm_area[0] >= mtp_palm_area[1], would catch a swapped pair. Moving the T6041/J616s selections in a follow-up sounds good.

Assisted-by: LLM (Claude:Opus 5.5)

@gig3m

gig3m commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

J813 (MacBook Air 13" M5, macOS 27.2 stub, MTP firmware AppleMTPFirmwareMac-6310.85.7): the pad sends the same touch states and path IDs as the J815, so its node can take apple,touch-states.

Raw records (HID debugfs: a recording from 11-16 of normal use and typing, 85,862 frames and 1,300 contacts, plus today's 25,093 frames and 359 contacts):

  • Contacts go through the same lifecycles, most often start > make > touching > break > linger > out, or start > hover > out for a finger that never lands. No frame has the same path ID twice.
  • One difference: between a contact's out of range and the next start under its path ID come two records in state 0 (2,555 in the 11-16 recording). They keep a position but have zero sizes, so magicmouse_mtp_on_surface() already drops them through the size test. I'd guess this is MultitouchSupport's "not tracking", but I haven't checked it against macOS.

Without the states, the size test in today's driver, on the 11-16 recording:

  • 290 of the 1,300 contacts never touched the pad but were reported as touches: 5,062 reports of a hovering or approaching finger.
  • All 1,010 contacts that did touch were reported from their start-in-range record, before they landed.

With this series' driver commits (5e1f8699, c220932c, 17f519cd) on my J813 kernel, with the J813 node's properties set in a local test build instead of a new DTB (apple,palm-debounce, apple,touch-states), over 8 minutes of normal use:

  • 358 make-touch records in the raw stream, 358 touches started on the evdev side (tracking IDs).
  • The one contact that only hovered started no touch, and none of the 1,252 off-surface records with a touch size was reported.
  • In 22 frames two contacts made touch together, and each got its own touch.
  • Not covered: no palm landed in that run, so the J813 palm rule wasn't exercised under the states.

So apple,touch-states; could go on the J813 multi-touch node in a233c6ea as well.

🤖 Generated with Claude Code

gig3m and others added 2 commits November 21, 2026 19:40
The J813 (MacBook Air 13" M5) trackpad sends the standard MTP report
and classes its contacts like the T6041 and J616s ones: low byte of a
record's second word, 2 and 3 for fingers, 6 and above for palms.

Most J813 palms stay below the classed tool area of 1400 that the
T6041 rule needs: recorded in normal use and while typing, 221 of 370
palm-classed contacts never passed it, and fingers reached 1560, so
lowering it would not separate them. The class flickers to a palm for
single reports on fingers (4 of 868), so on the J813 a contact also
counts as a palm once two consecutive reports class it as one. That
caught all 370 palms by their second report, and one finger, classed a
palm for its last reports while lifting.

As on the J616s, the J813 trackpad now also advertises ABS_MT_TOOL_TYPE
and the full 16-bit range of its touch and width areas. Other machines
are unchanged.

Signed-off-by: Kyle Arrington <kyle@arrington.co>
The J815 (MacBook Air 15" M5) has the J813's T8142 and MTP transport, and
its trackpad sends the standard MTP report the previous commit reads on
the J813, with the same contact classes. Take the J813's rule there as
well: the controller's palm classes are trusted, and two consecutive palm
classes mark a palm whatever its tool area.

The pads differ: the J813 ADT's multi-touch hid-merge-personality is
C1FD1,4, the J815's C1FD3,3 (a larger pad, firmware tpmtfw-j815.bin), so
the rule was checked on a J815 recording (one contact line per lift):

  30 s typing with both palms resting on the pad: 77 contacts the
  controller classed as palms, all 77 marked (36 by their second report);
  15 short contacts with fewer palm classes, 11 of them marked, all with
  large tool areas (up to 5245) at the palms' edges.

  30 s pointing, tapping and two-finger scrolling: 54 finger contacts,
  none marked and none with a palm class; the largest finger tool area
  was 1028, below the 1400 the area rule needs. (6 more contacts lifted
  in the first second: palms still resting from the typing phase, all
  classed as palms.)

Signed-off-by: Nick <nekreshen@yandex.ru>
Signed-off-by: Kyle Arrington <kyle@arrington.co>
@m0d16l14n1 m0d16l14n1 changed the title HID: magicmouse: J815 trackpad touch states, palm rule and palm-free click (stacked on #2116) HID: magicmouse: J813/J815 trackpad touch states, palm rules and palm-free click Nov 21, 2026
@m0d16l14n1

Copy link
Copy Markdown
Contributor Author

@RyanTheTide added both:

  • the binding now says the first apple,palm-tool-area value is below the second;
  • the driver warns at probe and turns the rule off if they're swapped.

@gig3m thanks for the J813 run. apple,touch-states is now on the J813 node, with your numbers in the commit message. The J813 palm rule under the states still needs a run with a palm.

Rebased onto cc14570; #2116's two commits are carried, since it's closed.

Assisted-by: LLM (Claude:Opus 5.5)

@m0d16l14n1
m0d16l14n1 marked this pull request as ready for review November 21, 2026 14:38
@RyanTheTide

Copy link
Copy Markdown
Contributor

Re-review of f2c267c: No blockers.

From the last comments:

  • Rules selected by the board: resolved earlier and still so. drivers/hid/hid-magicmouse.c:3051-3075 reads apple,palm-debounce, apple,palm-tool-area and apple,touch-states from the multi-touch node.
  • Surface test in magicmouse_mtp_hand(): resolved, hid-magicmouse.c:1118 uses the same magicmouse_mtp_on_surface() guard as the palm update.
  • Swapped apple,palm-tool-area: resolved. The binding states the order, and hid-magicmouse.c:3056-3060 warns and turns the rule off.
  • Force Click with a hand resting: still not run (see HW row).

Since then the series also puts apple,touch-states on the J813 node (t8142-j813.dts:239-242). The out-of-range skip in magicmouse_mtp_update_palms() comes before both palm rules, so the J813's debounce path handles reused path IDs the same way. Its zero-size state-0 records are dropped by the size test in magicmouse_mtp_on_surface().

  1. Nit: hid-magicmouse.c:1118, :1120, :1150 and :1154 compare int tool (sign-extended by le16_to_int()) with the u32 mtp_palm_area[]. A raw field with bit 15 set becomes a huge unsigned value and marks a palm. Store the thresholds as int (and give the binding a maximum: 32767), or compare as (int)msc->mtp_palm_area[n].
  2. The PR is no longer a draft, but the body still lists three hardware runs to do "before this leaves draft".

HW row: J815 on this head and its DTB, default command line. (a) A Force Click with one palm resting and the other hand clicking. (b) A thumb landing that starts above the second threshold, still reported as a finger. Plus one J813 run with a palm resting while typing. Pass: no palm click, Force Click registers, palms marked with no finger lost, and the regression line shows 0 failed units, 0 AVC denials and 0 new kernel errors.

Assisted-by: LLM (Claude:Opus 5.5)

@DjDeveloperr DjDeveloperr left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pre-PR checklist review at f2c267cba17c (CI: dt-checks and host-tests passing).

The DT-driven architecture is clean (§1): board gating is replaced by per-pad multi-touch properties (apple,touch-states, apple,palm-debounce, apple,palm-tool-area) with binding mutual-exclusion rules, path-ID slot assignment (input_mt_get_slot_by_key() inside the report loop with INPUT_MT_DROP_UNUSED) and out-of-range palm clearing are sound, and §4 attribution is clean (#2116 commits carried unchanged, human Signed-off-by: only across all 7 commits, Assisted-by: in PR body).

Blockers:

  1. Signed/unsigned comparison bug (drivers/hid/hid-magicmouse.c:1114, 1118, 1120, 1139, 1150, 1154): int tool = le16_to_int(f->tool_major) sign-extends the 16-bit LE field (-32768..32767), while msc->mtp_palm_area[2] is u32. In tool > msc->mtp_palm_area[0] and tool > msc->mtp_palm_area[1], C usual arithmetic conversions promote int tool to u32, so any raw tool_major with bit 15 set (tool < 0) becomes >= 0x80000000U and falsely triggers both the immediate palm mark (> area[1]) and hand-force click suppression. Additionally, apple,palm-tool-area in Documentation/devicetree/bindings/input/apple,dockchannel-hid.yaml has no maximum: 32767, and magicmouse_probe() does not reject values > S16_MAX (which would silently disable the rule). Please add maximum: 32767 to the binding, validate <= S16_MAX at probe, and store/compare mtp_palm_area as int.
  2. PR readiness & missing §5 hardware evidence on live head: The PR is out of draft, yet the PR body still lists three hardware checks "before this leaves draft" (surface-only >2200 thumb approach test, this DT-selected build on f2c267cb, and Force Click with a resting palm). Please post the live-head HW rows (J815 on this head + DTB covering Force Click with resting palm and >2200 thumb approach; J813 with a resting palm under apple,touch-states) along with the §5 regression line (0 SELinux denials, 0 failed units, 0 new kernel errors), and update the PR body.

Minor hardening / nits (non-blocking):

  • magicmouse_mtp_on_surface() (drivers/hid/hid-magicmouse.c:1052-1062) states that only make-touch (3) and touching (4) are on the surface, but uses a denylist (1, 2, 5, 6, 7) instead of allowlisting 3, 4 — leaving state 0 (observed 2,555 times on J813) reliant on touch_major == 0 and not cleared in magicmouse_mtp_update_palms().
  • drivers/hid/hid-magicmouse.c:1930 comment (/* The T6041, J616s, J813 and Trackpad26 controllers classify palms. */) omits J815.

Assisted-by: LLM (Gemini 4 Neon)

…ates and palm rules

The J813 and J815 (MacBook Air M5) trackpads send the standard MTP
report, with a touch state and a firmware path ID in each contact
record, and they need their own palm rules. Describe both on the
multi-touch node, so the driver selects them by the trackpad and not by
the machine, and another board with the same controller only needs its
device tree:

- apple,touch-states: the record's first word holds the touch state and
  the path ID; only touching contacts are reported, each in its path
  ID's slot.
- apple,palm-debounce: two consecutive palm classes mark a palm (J813).
- apple,palm-tool-area: the J815 rule, with the pad's two tool-area
  thresholds as values: a hand class past the first on two consecutive
  reports, or any contact on the surface past the second, is a palm,
  and its force doesn't count towards the host-derived click.

The J700 report layout (compatible apple,j700-multitouch) has none of
these fields, so the properties are not allowed with it.

Signed-off-by: Nick <nekreshen@yandex.ru>
…lm rules

Give the multi-touch nodes the properties the driver will select the
trackpad behaviour by, instead of the machine compatible:

- J813: apple,palm-debounce, the rule its palms are reported with now,
  and apple,touch-states: gig3m's J813 recordings (MTP firmware
  6310.85.7, 1,659 contacts) show the same state lifecycles and path IDs
  as the J815, with no path ID twice in a frame. Between a contact going
  out of range and the next start under its path ID come records in
  state 0 with zero sizes, which the on-surface test already drops.
- J815: apple,touch-states (decoded on this pad against macOS's own
  parse of the same frames) and apple,palm-tool-area = <1200 2200>,
  the thresholds checked against macOS's labels for 607 contacts.

Signed-off-by: Nick <nekreshen@yandex.ru>
The high byte of a standard MTP record's first word is the contact's
touch state and the low byte its firmware path ID. Decoded on a J815
(MacBook Air 15" M5, MTP firmware 6300.85.6) against macOS's own parse of
the same frames: MultitouchSupport's full-frame callback, matched record
by record on path ID, state, finger class and hand ID over 10 minutes of
use. The states are 1 start in range, 2 hover in range, 3 make touch,
4 touching, 5 break touch, 6 linger in range, 7 out of range.

A finger approaching or leaving the pad (states 1, 2, 5, 6) still has a
position and nonzero sizes, so the touch-size test reports it as a touch:
374 such reports in the 10 minutes, each a hovering or lifting finger
seen as a touch. Report only make touch and touching there; any other
state is off the surface, including the zero-size state-0 records a
pad sends between a contact going out of range and the next start under
its path ID.

The firmware keeps a contact under its path ID until it leaves the pad,
so report each contact in that ID's slot instead of matching by distance,
which hands a slot over when one finger lifts as another lands nearby in
the same frame (two or more contacts landed in one frame about 100 times
in the 10 minutes). The slot is looked up inside the report loop, so
contacts landing in the same frame get different free slots; the MTP
slots are set up with INPUT_MT_DROP_UNUSED, which releases the slot of a
path ID that is gone.

The firmware also reuses a path ID for a new contact in the report right
after the old one goes out of range (40 times in the 10 minutes), so an
out-of-range record no longer keeps the palm mark of its ID.

The trackpad node's apple,touch-states selects this, so it follows the
trackpad's firmware rather than the machine: the J815 has it, and the
J813 (the same firmware family on the same SoC, not checked yet) or a
later board only needs the property.

Signed-off-by: Nick <nekreshen@yandex.ru>
…T node

The previous J815 commit took the J813's rule: two consecutive palm
classes (6 and above) mark a palm whatever its tool area. Checked against
macOS's own labels for the same contacts (MultitouchSupport's full-frame
callback, 10 minutes of typing with resting palms, pointing, scrolling and
gestures, 607 contacts, 34 of them hands), that rule marked two finger
contacts as palms until they lifted, 966 finger reports lost:

  a finger-sized contact in the bottom-left corner whose class flickered
  between 10 and 12;
  a finger whose class flipped between 3 and 7 for up to 17 reports, with
  a tool area up to 1606.

Class 10 is not a hand on the J815; its hand classes are 6, 7, 8 and 12.
Mark a contact as a palm when a hand class comes with a tool area above
1200 on two consecutive reports: no finger contact and 33 of the 34 hands
on the macOS session. 1400 missed 4 of 25 palms resting while typing on
Linux (they peaked at 1325-1400); 1100 would mark one finger of the macOS
session.

Some resting palms are never classed as hands: in one Linux typing run
two of them, 28 and 38 mm wide, stayed fingers for 0.6 s and one of them
made a click. No finger or thumb contact on the surface passed a tool
area of 2097 on macOS, while 21 of the 34 hands passed 2200, so a contact
on the surface wider than that is a palm at once, whatever its class.
Only on the surface: a thumb's start-in-range record had a tool area of
2428, and the mark would have stayed for its 35 touching reports. With
both tests, the macOS session gives 33 of 34 hands, no finger, and 8 hand
reports before the mark (18 with the class test alone). The 2200 margin
comes from one 10-minute macOS session and Linux runs on the same
machine; on Linux, fingers reached 1879 (99th percentile).

Both rules are selected by the trackpad node instead of the machine
compatible: apple,palm-debounce for the J813 rule, and
apple,palm-tool-area for this one, whose two values are the pad's own
thresholds (1200 and 2200 on the J815), so another board with the same
controller gets either rule from its device tree.

A swapped apple,palm-tool-area (first value not below the second), or a
value above 32767, is warned about at probe and leaves the rule off. The
record's tool area is a signed 16-bit field, and the thresholds are kept
as int so that a raw field with bit 15 set compares as negative, not as
a huge unsigned value that would mark a palm.

Signed-off-by: Nick <nekreshen@yandex.ru>
The J815's MTP click is derived on the host from the summed contact
force. A palm resting while typing presses hard enough to reach the press
threshold on its own: in one Linux typing run all 4 clicks came from
palms (3 with only palm-marked contacts on the pad, summed force
121-139 against the press threshold of 120; 1 from a 27 mm contact in
its first report, before the palm mark).

On macOS a resting hand neither clicks nor moves the pointer, while a
finger of the other hand still clicks and Force Clicks. Leave out the
force of every hand contact, with the same tests as the palm rule and
the pad's apple,palm-tool-area values: one marked as a palm, one in a
hand class past the first value (1200 on the J815) already in its first
report (the palm mark waits for a second one), and one on the surface
wider than any finger (past the second value, 2200).

On the J815, two A/B runs of pointing, typing, and pointing and clicking
with the other hand while a palm rests (each click attributed from the
evdev trace: a hand is a palm-marked contact or one above 2200): with
this change, 59 of 59 clicks reached the press threshold on the fingers'
force alone. With the previous commits' palm marking but without this
change, 49 of 58 clicks did not: 10 with no finger on the pad, 39 with
fingers whose own force stayed below the threshold. The two builds also
differ in the 2200 test, and no palm-made click was felt with this one.

Signed-off-by: Nick <nekreshen@yandex.ru>
@RyanTheTide

Copy link
Copy Markdown
Contributor

Re-review of f5b7717: no blockers.

  • Signed thresholds: fixed. mtp_palm_area[] is int (drivers/hid/hid-magicmouse.c:328). Probe rejects a swapped pair or a second value above S16_MAX before it stores them (:3060-3069). The binding caps both items at 32767 (apple,dockchannel-hid.yaml:204, :207). The palm and hand tests now compare int with int.
  • PR body: fixed. It now lists the rows owed at this head instead of "before this leaves draft".
  • The on-surface test is now an allowlist of make touch and touching (:1050-1062), so state 0 and any state the decoder doesn't know are off the surface. The out-of-range skip in magicmouse_mtp_update_palms() still runs before both palm rules.

Optional: the comment at hid-magicmouse.c:1030-1033 and the messages of c99a772 and a89f8bc name the macOS component used as the reference. "Checked against macOS's own contact labels" says the same without naming it.

HW row (still owed, at f5b7717 and its DTB, default command line): J815 Force Click with one palm resting and the other hand clicking; J815 thumb landing that starts above the second threshold and is still reported as a finger; J813 palm resting while typing under apple,touch-states. Pass: no palm click, Force Click registers, no finger lost, 0 failed units, 0 AVC denials, 0 new kernel errors.

Assisted-by: LLM (Claude:Opus 5.5)

@m0d16l14n1

Copy link
Copy Markdown
Contributor Author

@DjDeveloperr @RyanTheTide fixed in f5b7717b, squashed into the commits that introduced each line. The two carried #2116 commits are byte-identical.

  1. Signed thresholds: mtp_palm_area[] is now int. tool comes from le16_to_int() and is sign-extended, so a raw field with bit 15 set compares as negative and can't mark a palm. The binding gives both apple,palm-tool-area values maximum: 32767. Probe now also refuses a value above S16_MAX, warning and leaving the rule off, as it does for a swapped pair (e143d679, a89f8bc5).
  2. On the surface is an allowlist: with apple,touch-states, only make touch (3) and touching (4) pass magicmouse_mtp_on_surface(), and every other state is off the surface (c99a772f). For states 0-7 the result is the same as before, because the J813's state-0 records already failed the size test.
    On clearing state 0 in magicmouse_mtp_update_palms(): no change is needed. The palm and class bitmaps are rebuilt from each report's records. The out-of-range record that comes before state 0 is skipped, so its ID's mark is already gone, and a zero-size state-0 record can't mark it again.
  3. Comments: the ABS_MT_TOOL_TYPE comment and the mtp_palms kernel-doc name the J815.
  4. Body: the "before this leaves draft" list is replaced by the rows owed on this head.

Checks: each changed commit builds hid-magicmouse.o with W=1 and no warnings, checkpatch --strict is clean on all seven, and dt_binding_check (apple,dockchannel-hid.yaml) and CHECK_DTBS on the J813/J815 DTBs pass.

Still owed on f5b7717b:

  • J815: Force Click with a palm resting, and a thumb landing above 2200;
  • J813: a palm resting while typing;
  • the regression line for both.

Assisted-by: LLM (Claude:Opus 5.5)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants