Skip to content

fix(hardware): prevent ~130s sleep wake stall on MacBook Pro 2016-2017 - #9899

Closed
tcholewa wants to merge 1 commit into
omacom:quattrofrom
tcholewa:fix/macbook-thunderbolt-suspend
Closed

tcholewa wants to merge 1 commit into
omacom:quattrofrom
tcholewa:fix/macbook-thunderbolt-suspend

Conversation

@tcholewa

@tcholewa tcholewa commented Sep 2, 2026

Copy link
Copy Markdown

Summary

Fixes a ~130-second system freeze on wake from ACPI S3 (deep) sleep on MacBook Pro 2016–2017 models (MacBookPro13,x and MacBookPro14,x).

Root Cause

On MacBook Pro 2016–2017 models equipped with Intel Alpine Ridge Thunderbolt 3 controllers (8086:15d2 NHI / 8086:15d4 integrated xHCI), Apple firmware cuts power to the controller during S3 sleep. On wake, xhci_hcd polls the unpowered PCIe device (0000:07:00.0), hitting exponential backoff timeouts (1023ms -> 2047ms -> ... -> 65535ms) totalling ~130 seconds before pciehp drops the dead device.

Solution

  1. Adds install/hardware/apple/fix-suspend-thunderbolt.sh to remove unpowered 8086:15d4 PCIe devices prior to S3 sleep.
  2. Unloads thunderbolt and facetimehd before sleep to prevent kernel call traces and unneeded sensor power-on.
  3. Automatically dispatches hl.dsp.dpms({ action = "enable" }) upon resume across active Hyprland user sessions so the display backlight lights up immediately.
  4. Rescans the Thunderbolt root port (0000:00:1c.4) after resume.
  5. Updates manual/44-mac-support.md with documentation.

@ari-ahm

ari-ahm commented Sep 4, 2026

Copy link
Copy Markdown

Tested this on a MacBookPro14,1 (Omarchy 4.0.2, systemd 261.2, kernel 7.1.9-arch1-2). The diagnosis matches what I see here, and with the hook actually running the xHCI backoff and the tb_cfg_read trace disappear and the USB-C ports survive sleep.

Worth noting this is not covered by fix-suspend-nvme.sh: that service was installed and applied (d3cold_allowed=0) on a machine that still hung hard on resume from S3 and needed a power cycle.

Three notes on the patch as written — the first prevented it from running on my system.

1. The hook directory isn't scanned on systemd 261

fix-suspend-thunderbolt.sh writes to /etc/systemd/system-sleep/. On systemd 261.2 that directory doesn't appear to be searched: systemd-sleep(8) documents only /usr/lib/systemd/system-sleep/, and that's the only such path in the shipped binaries:

$ strings /usr/lib/systemd/systemd-sleep /usr/lib/systemd/libsystemd-shared-261.2-1.so \
    | grep -o '[/A-Za-z0-9._-]*system-sleep[/A-Za-z0-9._-]*' | sort -u
/usr/lib/systemd/system-sleep

With the script in /etc/... the hook silently never ran here — the xHCI was still present going into S3, and resume showed the full backoff plus a call trace:

xhci_hcd 0000:07:00.0: not ready 1023ms after resume; waiting
  ... 2047 / 4095 / 8191 / 16383 / 32767 ...
xhci_hcd 0000:07:00.0: not ready 65535ms after resume; giving up
thunderbolt 0000:06:00.0: not ready 1023ms after resume; giving up
WARNING: drivers/thunderbolt/ctl.c:1131 at tb_cfg_read+0x94/0xf0 [thunderbolt]

Moving the identical script to /usr/lib/systemd/system-sleep/ fixed it — those messages and the tb_cfg_read trace both went to zero, and the USB-C ports survived sleep instead of staying dead until reboot. That's also where the repo's existing unmount-fuse hook already lives, so it may be worth matching it regardless of which systemd versions searched /etc.

2. The dpms dispatch blocks resume for ~5.4s

systemd keeps user.slice frozen until every post hook returns, so the runuser ... hyprctl dispatch call delays the session coming back:

04:15:33.128  post hook starts
04:15:33.140  runuser session opened
04:15:33.199  systemd: Cannot start frozen unit Session 3 of User <user>.
04:15:33.200  pam_systemd: CreateSession failed: io.systemd.Login.UnitAllocationFailed
04:15:38.530  runuser session closed          <- 5.33s
04:15:40.617  user.slice thawed

Note pam fails immediately (60 ms) — the 5.33s is hyprctl waiting on a Hyprland that is itself frozen and cannot reply. systemd-sleep(8) warns about precisely this:

user.slice will be frozen while the executables are running, so they should not attempt to communicate with any user services expecting a reply.

This repo's own unmount-fuse hook already documents the hazard and backgrounds its work for that reason.

The dispatch also wasn't necessary here — ACPI restores the panel on its own (acpi LNXVIDEO:00: Restoring backlight state). Dropping it, and making the sleep 2 + rescan conditional, took the frozen window from 7.49s to 0.057s across two otherwise identical sleep cycles:

suspend exit -> user.slice thawed
  with dpms + unconditional sleep 2 : 7.490s
  without                           : 0.057s

The unconditional sleep 2 before the rescan is likewise unnecessary on the happy path: after a clean pre-removal the xHCI re-enumerates by itself, so the rescan only earns its keep as a fallback.

3. The hardcoded 0000:07:00.0 removal is redundant and risky

[[ -d /sys/bus/pci/devices/0000:07:00.0 ]] && echo 1 > /sys/bus/pci/devices/0000:07:00.0/remove 2>/dev/null || true

The loop above it already removes every 8086:15d4. On this machine 07:00.0 is that device, so the line is a no-op; on other hardware that address can be an unrelated device, which would then be removed before every suspend. Suggest dropping it.

A data point supporting the approach

Once a resume has wedged the controller it cannot be recovered without a power cycle — I tried rescanning the root port, the xHCI's immediate parent bridge (0000:05:02.0), and a global /sys/bus/pci/rescan, and none brought it back. That supports the PR's core premise of removing the device before firmware cuts power rather than trying to restore it afterwards.

Minor: blacklist thunderbolt in /etc/modprobe.d disables Thunderbolt devices entirely. Since the pre hook already unloads the module, reloading it in post instead keeps docks/eGPU usable while awake and still avoids the NHI traces.

@orospakr

Copy link
Copy Markdown

Hi @tcholewa, @ari-ahm — I've been chasing exactly this failure on a MacBookPro14,1 for the last two weeks and I think it's worth cross-linking, because we ended up at a different diagnosis and a different fix. The log signature you both posted (xhci_hcd 0000:07:00.0: not ready 1023ms … 65535ms after resume; giving up, thunderbolt 0000:06:00.0: not ready 1023ms, the tb_cfg_read WARNING at ctl.c:1131) is line-for-line what I captured on the stock kernel, so it is the same bug.

Write-up: #10593. Patches: omacom/omarchy-pkgs#349 (tb-ar-shim-dkms, the kernel-side fix) and #10758 (detection, install and a migration that depend on it).

Root cause is a PCI save-ordering hazard, not a firmware power cut

Instrumented on the machine (config-space reads from a shim module at each PM phase):

  1. dpm_suspend_noirq runs children before parents. The NHI (06:00.0) is the deepest child, and its nhi_suspend_noirq → tb_switch_suspend → tb_lc_set_sleep puts the Alpine Ridge router into LC sleep. From that moment config reads of the whole chip — the downstream bridges and the upstream bridge 04:00.0 — return ffffffff. (This is the "Unable to change power state from D0 to D3hot, device inaccessible" trio on 05:02.0 / 05:00.0 / 04:00.0 in the stock suspend log.)
  2. Only after that does pci_pm_suspend_noirq run for the bridges and call pci_save_state(). It saves all-ones.
  3. Across S3 the platform resets and re-powers the chip on its own — the rails are up and RP05's link is retrained to Gen3 x4 before the first noirq resume callback. Nothing needs to (or does) cut power.
  4. pci_pm_resume_noirq(04:00.0) restores the all-ones snapshot into the fresh chip: bus numbers ff, so every downstream bridge is "inaccessible", the NHI's pci_dev_wait gives up after 1 s, the xHCI's after 65 s, and pciehp removes it. That is the ~130 s.

For S3, saving the bridge and its subtree in suspend_late — i.e. before the NHI's noirq callback — is the entire fix. With that alone, resume of the subtree takes 1.3 s and the NHI, the Thunderbolt domain and the xHCI all survive. (Under s2idle there is a second, mirror-image bug: the PCI core's skip_bus_pm policy skips the restore entirely, on the assumption that devices keep their config space across s2idle, which this chip doesn't. So the module also has to do the parents-first restore itself in resume_noirq.) 28/28 cycles on 14,1 with both in place.

A supporting data point: hibernate works on the stock kernel. The thunderbolt driver's freeze_noirq deliberately does not LC-sleep ("we just disable hotplug, the pci-tunnels stay alive"), so the snapshot that goes into the image is valid, and restore writes it back into the cold-reset chip. That is the same ordering the shim manufactures for S3.

Why this hook works, and what it costs

modprobe -r thunderbolt in the pre hook means tb_lc_set_sleep is never called, so the core's own pci_save_state() in noirq sees a readable chip. That is the operative line; the remove of the 15d4 xHCI is most likely redundant once the NHI driver is gone. The cost is that blacklist thunderbolt disables Thunderbolt for good — docks, tunneled PCIe, eGPUs — and, as @ari-ahm found, even the reload-in-post variant keeps the driver off for the whole sleep window.

The second failure mode this hook does not reach

There is a separate, worse failure that only happens when something is physically present on a Thunderbolt port at S3 entry: the Mac's EFI S3 resume boot script function-disables the PCH root port 00:1c.4 (RP05) itself, ~4–6 ms after "Waking up from system sleep state S3" and before the kernel runs a single instruction. RP05 reads ffffffff from then on and nothing short of a power cycle brings it back — rescanning the root port, its parent, and a global /sys/bus/pci/rescan all do nothing. Reproduced 8/8; we eliminated 11 OS-side countermeasures one at a time (wake-source disarming, D-state pinning, driver unbinding, link-state forcing, PD-controller mailbox commands, …). Unbinding the xHCI driver before suspend in particular does not help: the SuperSpeed link stays trained at U0 with nothing bound, and it is physical presence, not the driver, that trips the firmware. I'd expect echo 1 > remove to behave the same. @ari-ahm's "still hung hard on resume from S3 and needed a power cycle" looks like this mode.

Since s2idle never executes the EFI S3 boot script, that firmware behaviour cannot fire at all — which is why #10758 defaults these models to mem_sleep_default=s2idle via a limine cmdline drop-in. That is an honest trade: s2idle draws more in the bag than S3 does (no firmware S0ix assist on this platform). In exchange, both failure modes are gone (validated with a hub + stick attached, lid-close with Wi-Fi loaded, and cold-boot persistence), and Thunderbolt keeps working. macOS clearly slept in S3 with devices attached, so there is presumably a pre-sleep handshake it performs that we haven't found; that is the open research item in the issue.

Scope notes

  • The DKMS module is ~200 lines and gates on the on-board controller only (ACPI path DSB0.NHI0.SXFP under the bridge). The in-tree version is being prepared as a drivers/pci/quirks.c fixup for linux-pci; module, patch and CI live at https://github.com/orospakr/linux-apple-alpine-ridge-suspend.
  • I've only validated on MacBookPro14,1. The mechanism should be identical on 13,x/14,2/14,3 (same DSL6540 controller, same ACPI shape), but I haven't had one to test.

Happy to compare notes or logs — the full account, including the experiments that ruled things out, is in the issue. If the project would rather ship a hook-based workaround in the short term, the one-line takeaway from the above is that unloading thunderbolt is what makes it work, and the SS-device-attached case still needs s2idle.

🤖 Generated with Claude Code

https://claude.ai/code/session_014SjBV8RAyo6et6LMmurU9W

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at 0fc6f98 by Claude Opus 5.5, with Codex Medium as a second opinion. Both read this diff against quattro, along with the two other open pull requests for the same Alpine Ridge suspend bug, #10758 and #11570. Codex was asked which of the three is the best fix before it saw my answer. We both picked #11570, though that agreement may not be independent. Nothing was run: this is a hardware fix a VM cannot reproduce, and a fix that is not going ahead would only use up a worker.

Why #11570 rather than this one. Each of the following was checked against quattro and the systemd and kernel documentation, not taken from the comments:

  • install/hardware/apple/fix-suspend-thunderbolt.sh:10-11: the hook is written to /etc/systemd/system-sleep/. systemd-sleep(8) only runs executables in /usr/lib/systemd/system-sleep/, which is where quattro installs keyboard-backlight, force-igpu and unmount-fuse. As written, the hook never runs. This matches what @ari-ahm saw on a MacBookPro14,1.
  • There is no migration, so existing installs never get it. Suspend on 2016-2017 MacBook Pros: keep USB-C and Thunderbolt working across S3 #11570 ships one.
  • Line 48 adds a permanent blacklist thunderbolt. The module stops autoloading even while the machine is awake, so docks and other Thunderbolt devices stop working. Suspend on 2016-2017 MacBook Pros: keep USB-C and Thunderbolt working across S3 #11570 leaves the driver alone and removes the Thunderbolt upstream ports instead, finding them from the bound NHIs.
  • Line 22 removes 0000:07:00.0 before every sleep without checking what it is. On these machines it is the 15d4 the loop above it has already removed. On a different layout it could be an unrelated device.
  • Nothing checks for a mounted filesystem before removing a controller, so a USB-C disk could be pulled out from under its filesystem. Suspend on 2016-2017 MacBook Pros: keep USB-C and Thunderbolt working across S3 #11570 skips any side that has a mount behind it.
  • Lines 29-35 and 40: the hyprctl dispatch and the delayed rescan run as background children of systemd-suspend.service, which is KillMode=control-group. When the service stops, they are killed. While they do run, user.slice is still frozen, so they cannot get an answer from Hyprland. Suspend on 2016-2017 MacBook Pros: keep USB-C and Thunderbolt working across S3 #11570 hands its retries to a transient unit for exactly this reason.
  • Lines 14 and 28 match pre/* and post/*, so the hook also runs around hibernate, which is outside the S3 problem it addresses.

#11570 has open findings of its own, raised on that pull request. #10758 is the deeper kernel-side approach, but it depends on omacom/omarchy-pkgs#349, which is still open, and it covers only the 14,1. Which approach Omarchy takes for these Macs is the maintainer's decision, so this pull request stays open for them. The reports here from @ari-ahm and @orospakr were part of that comparison.

@tcholewa

tcholewa commented Nov 8, 2026

Copy link
Copy Markdown
Author

Closing this older hook-based proposal in favor of the proposed tb_ar_shim approach in #10758 and omacom/omarchy-pkgs#349. Those PRs remain open; this is withdrawal of my alternative, not a claim that a replacement has already shipped.

I independently tested the unchanged module on my MacBookPro14,1 with s2idle, including module autoloading and the first suspend after a complete shutdown and power-on. That first post-boot device resume measured 0.5322 s, and the wired download test after wake reported roughly 925–934 Mbps. The normal Thunderbolt driver stayed loaded, without this proposal's controller-removal hook, blacklist or my intermediate D3cold override.

The full report includes three module cycles, the comparison method and explicit limits: Thunderbolt peripherals, overnight battery drain, hibernation and other models remain untested.

Thank you to the reviewers for the hook-location, frozen-session and device-removal findings. The original installer here should not be used as the implementation of the validated module configuration. I am preserving the local workaround as a rollback and contributing the measurements to the existing module effort instead.

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

Labels

bug Something isn't working compatibility Make Omarchy work better on everything!

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants