Skip to content

adds suspend.md, updates state, removes some contradictions #732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
deqrocks wants to merge 1 commit into from
Closed

adds suspend.md, updates state, removes some contradictions #732

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 0 additions & 16 deletions docs/distributions/fedora/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,3 @@ If you try to upgrade to a new stable release (ex: f42 -> f43), and you reboot i
# Wi-Fi was working in the ISO, but broke after installing

Run `sudo systemctl enable --now get-apple-firmware.service` in a terminal, then reboot.

# My Wi-Fi stops working after suspending

Add this to `/etc/systemd/system-sleep/unload-wifi.sh`:

```bash
#!/usr/bin/env bash
if [ "${1}" = "pre" ]; then
systemctl stop NetworkManager
modprobe -r brcmfmac_wcc
modprobe -r brcmfmac
elif [ "${1}" = "post" ]; then
modprobe brcmfmac
systemctl start NetworkManager
fi
```
6 changes: 3 additions & 3 deletions docs/guides/audio-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ An EasyEffects preset (tested on MacBook Pro 15,1) is available [here](https://g

All of apple's fancy tuning of the speakers is done in macOS, but a similar configuration is currently available for only the MacBook Pro 16 inch 2019.

## MacBook Pro 16" 2019
## MacBook Pro A2141 16" 2019, MacBook Air A2179 2020

Currently we have an experimental DSP (Digital Signal Processing) config for MacBook Pro 16" 2019 with 6 speakers.
Currently we have an experimental DSP (Digital Signal Processing) config for MacBook Pro 16" 2019 with 6 speakers and for the 2020 MacBook Air with 2 speakers.
Note that each model needs specific settings. Do not use it with other models as it could damage the speakers. Also do not expect same sound quality as in macOS.

[DSP config instructions](https://github.com/lemmyg/t2-apple-audio-dsp/tree/speakers_161)
[DSP config instructions](https://github.com/lemmyg/t2-apple-audio-dsp/)
7 changes: 0 additions & 7 deletions docs/guides/hybrid-graphics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,13 +100,6 @@ We can take this a step further and save substantial amounts of energy by deacti
2:DIS: :Pwr:0000:01:00.0
```

### Suspend workaround

If using the iGPU causes the screen to be black after waking up from suspend, then try one of these workarounds:

- Add `i915.enable_guc=3` to [your kernel parameters](https://wiki.t2linux.org/guides/postinstall/#add-necessary-kernel-parameters). If that has a problem, try setting the value to 2 instead of 3.
- Turn the screen off and on after the backlight turns on. For GNOME: type your password then press enter, press Command + L to lock (this should turn off the backlight), then press any key.

## Using iGPU as primary gpu (Mutter)

Mutter-based desktop environments (e.g. GNOME) pick one GPU to use as the "primary GPU", and it's not necessarily the same as the one connected to the display. Even if apple-gmux is configured with `force_igd=y`, Mutter's primary GPU might be the AMD GPU, which makes the AMD GPU active when screen contents change.
Expand Down
118 changes: 1 addition & 117 deletions docs/guides/postinstall.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ sudo modprobe hid-appletb-kbd

# Wi-Fi and Bluetooth

The drivers for Wi-Fi and Bluetooth are included in a kernel with T2 support. But, we also need firmware to get them working from macOS.
The drivers for Wi-Fi and Bluetooth are included in a kernel with T2 support. But, we also need firmware to get Wifi working from macOS.

@AdityaGarg8 AdityaGarg8 Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Some models need Bluetooth from macOS as well. Let's just avoid this change.

@deqrocks deqrocks Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Disagreed


Instructions for the same are given in the [Wi-Fi and Bluetooth](https://wiki.t2linux.org/guides/wifi-bluetooth/) guide.

Expand All @@ -178,119 +178,3 @@ cat <<EOF | sudo tee /etc/NetworkManager/conf.d/99-network-t2-ncm.conf
no-auto-default=t2_ncm
EOF
```

# Suspend Workaround

## Fedora and Arch based distros

S3 suspend has been broken since macOS Sonoma, it has never been fixed, but this workaround will make deep suspend work. Currently this workaround works only on Arch based distros and Fedora.

1. Create and edit this file: `/etc/systemd/system/suspend-fix-t2.service`

2. Check your `modprobe` and `rmmod` location by running:

```bash
which modprobe
which rmmod
```

3. Taking the example as `/usr/bin` for location of `modprobe` and `rmmod`, copy the following to `/etc/systemd/system/suspend-fix-t2.service`. If the location is different, do the changes accordingly.

```service
[Unit]
Description=Disable and Re-Enable Apple BCE Module (and Wi-Fi)
Before=sleep.target
StopWhenUnneeded=yes

[Service]
User=root
Type=oneshot
RemainAfterExit=yes

#ExecStart=/usr/bin/modprobe -r brcmfmac_wcc
#ExecStart=/usr/bin/modprobe -r brcmfmac
ExecStart=/usr/bin/rmmod -f apple-bce

ExecStop=/usr/bin/modprobe apple-bce
#ExecStop=/usr/bin/modprobe brcmfmac
#ExecStop=/usr/bin/modprobe brcmfmac_wcc

[Install]
WantedBy=sleep.target
```

4. Enable the service by running: `sudo systemctl enable suspend-fix-t2.service`

5. If you are facing issues with Wi-Fi on resume, uncomment the lines having `brcmfmac` and `brcmfmac_wcc` in the above file.

!!! note
Make sure you have `CONFIG_MODULE_FORCE_UNLOAD=y` in the kernel config.
To check, run: `zcat /proc/config.gz | grep "CONFIG_MODULE_FORCE_UNLOAD"` on Arch based distros, or `grep "CONFIG_MODULE_FORCE_UNLOAD" /boot/config-$(uname -r)` on Fedora.

## Gentoo/OpenRC

S3 suspend has been broken since macOS Sonoma, it has never been fixed, but this workaround will make deep suspend work on Gentoo Linux using OpenRC and elogind.

Prerequisites:

1. Make sure elogind is installed and running:

```bash
rc-update add elogind boot
rc-service elogind start
```

For T2 MacBooks, while unloading only the apple-bce module is sufficient for basic suspend functionality, additional module handling may be required depending on your model:

- All T2 models require the apple-bce module handling.
- For models with Touch Bar, a specific module sequence (apple_bce -> hid_appletb_bl -> hid_appletb_kbd) is required to properly reinitialize the Touch Bar device after resume.
- If you use tiny-dfr for Touch Bar customization, the tiny-dfr service needs to be stopped before suspend and started after resume, and appletbdrm module is required.

The script below includes all cases with commented sections. Uncomment the relevant sections based on your model and requirements. The loading order of modules is important for proper device initialization after resume.

1. Create and edit this file: `/etc/elogind/system-sleep/apple-bce-handler`

```bash
#!/bin/bash
case $1/$2 in
pre/*)
# Required for all T2 models
rmmod -f apple_bce

# Uncomment the following if using tiny dfr for touchbar
#/etc/init.d/tiny-dfr stop
#modprobe -r appletbdrm

# Uncomment the following for models with touchbar, irrespective of whether using tiny-dfr
#modprobe -r hid_appletb_kbd
#modprobe -r hid_appletb_bl
;;

post/*)
# Required for all T2 models
sleep 4
modprobe apple_bce

# Uncomment the following for models with touchbar, irrespective of whether using tiny-dfr
#sleep 4
#modprobe hid_appletb_bl
#sleep 2
#modprobe hid_appletb_kbd

# Uncomment the following if using tiny dfr for touchbar
#sleep 2
#modprobe appletbdrm
#sleep 3
#/etc/init.d/tiny-dfr start
;;
esac
```

2. Make the script executable:

```bash
chmod +x /etc/elogind/system-sleep/apple-bce-handler
```

!!! note
Make sure you have CONFIG_MODULE_FORCE_UNLOAD=y in the kernel config.
107 changes: 107 additions & 0 deletions docs/guides/suspend.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# Suspend

Suspend is working on all T2 Macs since early 2026, but not on all of them out of the box.
On some hardware we need workarounds because of upstream driver/ACPI or Apple firmware issues.

## Thunderbolt / slow resume times

We can either have fast resume from suspend, or we can have Thunderbolt support. Not both.
Linux by default masquerades as macOS to make certain features accessible.

@AdityaGarg8 AdityaGarg8 Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I just find this paragraph way too informative and can imagine people saying "Yo I can't understand shit here, fix my suspend!" on the discord. Also, you need to link the guide to the yml to make it accessible.

@deqrocks deqrocks Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Disagreed

Thunderbolt is one of those.
On the other hand, masquerading as macOS makes resume from suspend extremely slow.
Depending on the number of cores your CPU has, it can take up to three minutes on a I9,
while it takes around 20 seconds on a I5 because `smpboot`-times rise exponentially per core.

To stop masquerading as macOS and to make the CPU cores wake within milliseconds,
you need to add the kernel arguments

```bash
acpi_osi=!Darwin acpi_osi='Windows 2012'
```

How to add kernel parameter is described in [postinstall](postinstall.md/#add-necessary-kernel-parameters).
But note this will break Thunderbolt support. This needs to be fixed in the Linux
mainline ACPI driver and is a trade-off we have to make for now.

## iGPU black screen on resume

If using the iGPU causes the screen to be black after waking up from suspend, then try one of these workarounds:

- Add `i915.enable_guc=3` to [your kernel parameters](postinstall.md/#add-necessary-kernel-parameters). If that has a problem, try setting the value to 2 instead of 3.
- Turn the screen off and on after the backlight turns on. For GNOME: type your password then press enter, press Command + L to lock (this should turn off the backlight), then press any key.

## MacBook Pro 15,1 black screen on resume

The MacBook Pro 15,1 suffers the issue to come up with a black screen on resume
because the SMU dies when the driver suspends the hardware. The cause for this is
known and being worked on. As a temporary workaround you can make the iGPU primary
as described in the [hybrid graphics guide](hybrid-graphics.md) and unload/reload the dGPU driver on
suspend using systemd.
Paste and run the following code block to create and enable this service:

```bash
sudo tee /etc/systemd/system/amdgpu-suspend.service >/dev/null <<'EOF'
[Unit]
Description=Unload and Reload amdgpu for Suspend and Resume
Before=sleep.target
StopWhenUnneeded=yes

[Service]
User=root
Type=oneshot
RemainAfterExit=yes

ExecStart=-/usr/bin/modprobe -r amdgpu

ExecStop=-/usr/bin/modprobe amdgpu

[Install]
WantedBy=sleep.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable amdgpu-suspend.service
```

## Broadcom 4377

Opposite to the Broadcom 4364 and 4365, which use dedicated chips and firmwares
for Bluetooth and Wifi, the 4377 uses a single chip and a single unified firmware.
The bluetooth part of the firmware is holding back the 4377 chip from transitioning
from `D0` to `D3cold`. While the 4364 and 4365 don't even need or use the Bluetooth firmware
on Linux, a 4377 user can't choose to not use the BT firmware. What you can do though,
is unloading the Linux drivers on suspend and reloading them on resume using a systemd service.

You will know that you are on affected hardware, when `journalctl -b --grep=4377` returns
something `brcmfmac` related.

If so, simply run the following terminal command:

```bash
sudo tee /etc/systemd/system/brcmfmac-suspend.service >/dev/null <<'EOF'
[Unit]
Description=Unload and Reload brcmfmac for Suspend and Resume
Before=sleep.target
StopWhenUnneeded=yes

[Service]
User=root
Type=oneshot
RemainAfterExit=yes

ExecStart=-/usr/bin/modprobe -r brcmfmac_wcc
ExecStart=-/usr/bin/modprobe -r brcmfmac
ExecStart=-/usr/bin/modprobe -r hci_bcm4377


ExecStop=-/usr/bin/modprobe hci_bcm4377
ExecStop=-/usr/bin/modprobe brcmfmac
ExecStop=-/usr/bin/modprobe brcmfmac_wcc

[Install]
WantedBy=sleep.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable brcmfmac-suspend.service
```
15 changes: 13 additions & 2 deletions docs/guides/wifi-bluetooth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,14 +133,25 @@ Once you have run the script on macOS, depending on the method you chose, the st

Replace `/path/to/firmware.tar` with the actual path of the tarball. For example, if `firmware.tar` is copied to the Downloads folder in Linux, command to be run would be `sudo tar -v -xC /lib/firmware/brcm -f $HOME/Downloads/firmware.tar`

Then reload the Wi-Fi and Bluetooth drivers by running:
Then reload the Wi-Fi and Bluetooth drivers. For the Broadcom 4377 chip:

@AdityaGarg8 AdityaGarg8 Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This addition is an unnecessary complication for people who hate reading guides. Let it remain as it is.

@deqrocks deqrocks Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Disagreed


```bash
sudo modprobe -r brcmfmac_wcc
sudo modprobe -r brcmfmac
sudo modprobe brcmfmac
sudo modprobe -r hci_bcm4377
sudo modprobe hci_bcm4377
sudo modprobe brcmfmac
sudo modprobe brcmfmac_wcc
```
For Broadcomn 4364 and 4365 chips:

```bash
sudo modprobe -r brcmfmac_wcc
sudo modprobe -r brcmfmac
sudo modprobe -r hci_uart
sudo modprobe hci_uart
sudo modprobe brcmfmac
sudo modprobe brcmfmac_wcc
```

=== ":fontawesome-brands-linux: Method 3"
Expand Down
16 changes: 8 additions & 8 deletions docs/state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@ While Linux is usable on all T2 models, some features are limited due to the lac
|Internal Drive / SSD|🟢 Working|🟢 Kernel 5.4||[Filesystem notes](#filesystem-notes)|
|Screen, iGPU|🟢 Working|🟡 Partial|||
|USB|🟢 Working|🟢 Yes|||
|Keyboard|🟢 Working|🔴 No||[apple-bce](https://github.com/t2linux/apple-bce-drv)|
|Trackpad|🟢 Working|🔴 No|Works, but isn't as great as on macOS (no force touch or palm rejection).|[apple-bce](https://github.com/t2linux/apple-bce-drv), [Trackpad tuning](https://wiki.t2linux.org/#trackpad-tuning)|
|Keyboard|🟢 Working|🔴 No|||
|Trackpad|🟢 Working|🔴 No||[Trackpad tuning](https://wiki.t2linux.org/#trackpad-tuning)|
|Wi-Fi|🟢 Working|🟢 Yes|Requires macOS firmware|[Setup guide](https://wiki.t2linux.org/guides/wifi-bluetooth/)|
|Bluetooth|🟡 Partially working|🟢 Yes|Requires macOS firmware only for devices with BCM4377 chip. Also, Bluetooth glitches on devices with BCM4377 Chip if connected to a 2.4 GHz Wi-Fi connection. Thus, in order to use Bluetooth either turn off your Wi-Fi or use a 5 GHz Wi-Fi connection.|[Setup guide](https://wiki.t2linux.org/guides/wifi-bluetooth/)|
|Camera|🟢 Working|🔴 No||[apple-bce](https://github.com/t2linux/apple-bce-drv)|
|Thunderbolt|🟢 Working|🟢 Yes|If it doesn't work, try adding `pcie_ports=native` in the kernel parameters via GRUB.||
|Touch Bar|🟢 Working|🟡 Partial|"Touch Bar Keyboard" mode works OOTB, where only the Function Keys or the Media/Brightness Control Keys are shown. Touch Bar drivers were upstreamed in kernel 6.15, but we still need apple-bce to make it work.|[apple-bce](https://github.com/t2linux/apple-bce-drv), [tiny-dfr](https://github.com/AsahiLinux/tiny-dfr)|
|Suspend|🟡 Partially working|🟢 Yes|A firmware upgrade attached to macOS Sonoma broke suspend. Some users were having difficulty with it even before Sonoma. The issue has something to do with the apple-bce driver, because suspend works when it's disabled.|[#53](https://github.com/t2linux/T2-Ubuntu-Kernel/issues/53)|
|Audio|🟡 Partially working|🔴 No|With proper configuration audio can work, however it is not stable in some older kernels and switching between speakers and when using the microphone. Microphone volume is low in some Macs.|[apple-bce](https://github.com/t2linux/apple-bce-drv)|
|Bluetooth|🟡 Partially working|🟢 Yes| 5 GHz Wi-Fi connection is recommended to prevent Bluetooth interferences.|[Setup guide](https://wiki.t2linux.org/guides/wifi-bluetooth/)|

@AdityaGarg8 AdityaGarg8 Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Only on BCM4377 devices

@deqrocks deqrocks Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Not correct.

@AdityaGarg8 AdityaGarg8 Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Do we have any proof of that?

|Camera|🟢 Working|🔴 No|||
|Thunderbolt|🟢 Working|🟢 Yes|Needs`pcie_ports=native` in kernel parameters||
|Touch Bar|🟢 Working|🟢 Yes|Touchbar works in native mode and can be customized using tiny-dfr or react-drm||

@AdityaGarg8 AdityaGarg8 Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

There are tonnes of tiny dfr like daemons now. Let's just endorse tiny-dfr since that's what we maintain.

@deqrocks deqrocks Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I see no reason to support a daemon that does not survive suspend. I find your critique here very biased and close minded. I cooperated on react-drm to make the touchbar convenient AND survive suspend.

|Suspend|🟢 Working|🟡 Prepared|Generally working but requires hardware-specific adjustments until further notice.|[guide](guides/suspend.md)|
|Audio|🟢 Working|🟡 Prepared| Microphone volume is low, what is factory intended state. Gain needs to be turned up in userland||
|Hybrid Graphics|🟡 Partially working|🟡 Partial|Toggling dGPU power doesn't work.|[Hybrid Graphics](https://wiki.t2linux.org/guides/hybrid-graphics/)|
|AMD GPUs|🟡 Partially working||Changing resolution, using DRI_PRIME and doing various other things can cause crashes, but `echo high \| sudo tee /sys/bus/pci/drivers/amdgpu/0000:??:??.?/power_dpm_force_performance_level` or adding `amdgpu.dpm=0` to the kernel commandline stops these crashes.||
|MacPro7,1|🟡 Partially working||Users have encountered PCIe Address Space issues, with auto remap breaking. A temporary solution may be possible by removing the Infinity Fabric Link (Bridge or Jumper) from the GPU(s).||
Expand Down
Loading