Skip to content

Add opt-in MacBook8,1 SPI LPSS recovery for deep S3 - #18886

Open
geeknees wants to merge 1 commit into
omacom:quattrofrom
geeknees:macbook81/s3-lpss-opt-in
Open

geeknees wants to merge 1 commit into
omacom:quattrofrom
geeknees:macbook81/s3-lpss-opt-in

Conversation

@geeknees

Copy link
Copy Markdown

Summary

Add an opt-in, MacBook8,1-only SPI LPSS state recovery hook for deep/S3 suspend. This is a follow-up to the in-tree SPI PIO workaround in #9735, not another implementation of PIO or an automatic change to the default sleep mode.

On the 2015 12-inch MacBook (MacBook8,1), the SPI controller can lose its Intel LPSS private register state across S3. The hook unloads applespi, unbinds the SPI PCI driver, snapshots nine LPSS registers before deep suspend, then restores the controller's state and rebinds/reloads applespi after resume.

Scope and safety

  • Strict MacBook8,1 model gate, deep mode check, and required initcall_blacklist=dw_pci_driver_init in the running cmdline.
  • A single allowed PCI function, 0000:00:15.4. No Bluetooth UART MMIO changes and no iomem=relaxed requirement.
  • User opt-in: omarchy setup macbook81-s3 enable installs the hook but does not switch from s2idle to deep or make deep persistent.
  • If the SPI module cannot be unloaded or state cannot be saved, the hook attempts to return to s2idle for that suspend. If SPI does not recover, it switches back to s2idle until reboot.
  • Explicit disable; collision checks prevent overwriting an existing hook from a custom installation. No bootloader/mkinitcpio modifications, migrations, third-party DKMS packages, or automatic first-boot execution.
  • This uses privileged PCI MMIO and module unbind/rebind, so it remains experimental and requires recovery access when manually testing.

Physical hardware evidence (the source integration PoC, not this extracted PR)

On a real MacBook8,1 (Early 2015), Omarchy edge runtime commit 9f98609, kernel 7.2.15-2-omarchy, with SPI PIO:

  • Three confirmed PM: suspend entry (deep) / PM: suspend exit cycles in the journal.
  • LPSS save and restore logs for 0000:00:15.4 and applespi OK after deep S3 for every cycle.
  • An approximately 8 h 14 m and an approximately 27 h 32 m sleep resumed successfully.
  • Keyboard and trackpad were responsive after wake, including after repeated lid cycles. The broader test setup also verified LUKS keyboard input, Wi-Fi, camera and audio, but those features are not implemented by this PR.

Existing integrated PoC and original recovery sources: https://github.com/geeknees/omarchy/tree/macbook81/poc-2026-11

Limitations: This isolated PR branch has not been installed and revalidated on fresh hardware. Battery drain is not quantified. Bluetooth reconnection after deep sleep is outside scope. Other models and kernels are untested. s2idle should remain the default.

Verification

  • bash test/shell.d/macbook81-s3-test.sh: mock resource0 test for allowlist, malformed snapshots, inactive controller, 9-register save/restore.
  • bash -n for setup command and system-sleep hook, git diff --check.
  • Pending: exercise the isolated patch on fresh MacBook8,1 installation, confirm both success and failure/rollback behavior.

Existing work

@geeknees
geeknees marked this pull request as ready for review November 14, 2026 11:45
@greptile-apps

greptile-apps Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 3/5

[Medium impact] The change reaches the suspend and resume workflow on opted-in MacBook8,1 systems.

The PR still needs fixes for the documented setup commands and the removal check for persistent deep sleep.

Findings

  1. P1 Setup rejects desktop users ▶
  2. P1 Deep sleep outlives recovery ▶

Summary

Adds experimental, opt-in SPI recovery for MacBook8,1 deep sleep.

  • MacBook8,1 deep sleep saves SPI state for the keyboard to return on wake.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[User enables recovery] --> B[Check model and PIO workaround]
  B --> C[Install helper and sleep hook]
  C --> D[User selects deep sleep]
  D --> E[Unload applespi and unbind SPI]
  E --> F{Save registers}
  F -->|Success| G[Deep sleep]
  F -->|Failure| H[Try to rebind and select s2idle]
  G --> I[Restore registers]
  I --> J[Rebind SPI and reload applespi]
  J --> K{Keyboard found}
  K -->|Yes| L[Log recovery]
  K -->|No| M[Select s2idle]
Loading

Reviews (2) · Last reviewed commit: "Add opt-in MacBook8,1 SPI LPSS recovery ..." · Reviewed by Greptile

require_model() {
[[ $(cat /sys/class/dmi/id/product_name 2>/dev/null) == "MacBook8,1" ]] || fail 'Only MacBook8,1 is supported'
}
require_root() { (( EUID == 0 )) || fail 'Run via omarchy setup macbook81-s3 (sudo required)'; }

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.

P1 Setup rejects desktop users

A normal desktop user running the documented omarchy setup macbook81-s3 enable command hits require_root and exits without installing anything. The router uses plain exec; requires-sudo=true does not request elevation. The documented disable command fails the same way. Use sudo inside the command for privileged work so both advertised commands work.

require_model
require_root
# Do not leave boot-time deep mode enabled without a restore hook.
if grep -RsEq 'mem_sleep_default=deep' /etc/limine-entry-tool.d /etc/kernel 2>/dev/null; then

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.

P1 Deep sleep outlives recovery

If a user saves mem_sleep_default=deep in /etc/default/limine, this check passes and disable removes the recovery hook. That file is a supported source of the kernel command line, but the search skips it. The temporary switch to s2idle leaves the boot setting unchanged, so deep sleep returns after reboot without SPI recovery and can leave the keyboard and trackpad unusable after suspend. Check /etc/default/limine before allowing removal.

Suggested change
if grep -RsEq 'mem_sleep_default=deep' /etc/limine-entry-tool.d /etc/kernel 2>/dev/null; then
if grep -RsEq 'mem_sleep_default=deep' /etc/default/limine /etc/limine-entry-tool.d /etc/kernel 2>/dev/null; then

@omarchybot omarchybot added the enhancement New feature or request label Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants