huzi.pk logohuzi.pk

Laptop: Suspend Fails When Thunderbolt Dock is Plugged In – Unbinding Devices Before Sleep

tech

Laptop: Suspend Fails When Thunderbolt Dock is Plugged In – Unbinding Devices Before Sleep

There's a special kind of betrayal that comes from silence. You close the lid, expecting the fans to wind down—a promise of rest. Instead, you're met with a stubborn hum. Your Thunderbolt dock stays lit, a silent vigil keeping sleep at bay. Or perhaps worse: your laptop appears to suspend, but when you open the lid later, the battery has drained to zero because it woke up moments after you closed it and ran hot in your backpack all day.

This isn't just an inconvenience; it's a breakdown in a conversation between your OS and its hardware. The dock is sending mixed signals at the wrong time. Today, we'll teach your system to handle the dock's chatter gracefully and reclaim reliable suspend on your docked Linux laptop.

This is one of the most common and frustrating issues for Linux users with Thunderbolt docks—especially those using Dell WD19/WD22, CalDigit TS4, or Lenovo ThinkPad Thunderbolt docks. The good news: it is entirely fixable with a systematic approach.

Understanding the Core Problem: Wake-Up Signal Conflicts

The core issue is a wake-up signal conflict. When Linux tries to suspend, a device on the dock often says "No," or sends a signal that immediately wakes the system back up. This happens because Thunderbolt docks are complex devices that contain multiple internal components: USB hubs, DisplayPort controllers, Ethernet adapters, and audio controllers. Any one of these can send a wake signal that disrupts the suspend process.

On Windows, manufacturers ship with ACPI tables and drivers that are specifically tuned to handle these signals. On Linux, the generic kernel drivers don't always have this vendor-specific knowledge, so the wake signals slip through unchecked.

There are typically three failure modes:

  1. Instant wake: The laptop suspends and immediately wakes back up. You close the lid, hear the fan stop for a split second, and then it starts again.
  2. Failed suspend: The suspend process hangs. The screen goes dark but the fans keep spinning and the power LED stays on. Only a hard reset brings it back.
  3. Silent drain: The laptop appears to suspend but wakes up shortly after in your bag, draining the battery and potentially overheating.

Immediate Action Plan and the Path to Reliable Suspend

1. Diagnose the Culprit with /proc/acpi/wakeup

This is your first and most important diagnostic tool. Run this in a terminal:

cat /proc/acpi/wakeup

You'll see a table listing devices and their wake-up status. It looks something like this:

Device  S-state   Status   Sysfs node
NHI1      S4    *enabled   pci:0000:00:08.3
XHC       S4    *enabled   pci:0000:00:14.0
XHCI      S4    *disabled  pci:0000:00:14.3
LID       S4    *enabled   platform:PNP0C0D:00

Target identifiers like NHI1 (Thunderbolt Host Interface) or XHC/XHCI (USB controllers). If a device shows *enabled, it is allowed to wake the system—and it's a prime suspect.

Key suspects on docked setups:

  • NHI1/NHI0: Thunderbolt controller. This is the most common culprit.
  • XHC/XHCI: USB 3.0 host controller. The dock's USB hub talks through this.
  • GTSB: Thunderbolt hotplug event. Some systems generate this when the dock is plugged in.
  • LAN0/LAN1: Ethernet wake-on-LAN from the dock's built-in NIC.

2. Apply a Targeted Wake-Up Disable (Quick Test)

Identify the sysfs path for the device. A common one is /sys/bus/pci/devices/0000:00:08.3/power/wakeup. The PCI address comes from the "Sysfs node" column in the wakeup output above.

Run:

echo "disabled" | sudo tee /sys/bus/pci/devices/0000:00:08.3/power/wakeup

Now try to suspend:

sudo systemctl suspend

If it works reliably, you've confirmed the cause. If the laptop still wakes up, try disabling other enabled devices one by one until you find the culprit.

Important: Disabling wake-up means that device can no longer wake the laptop. For example, if you disable the USB controller's wake capability, pressing a key on a keyboard connected through the dock won't wake the laptop. You'll need to use the laptop's built-in keyboard or power button instead.

3. Verify Thunderbolt Authorization and Security Level

Thunderbolt has a security model that can affect suspend behavior. Check your current security level:

cat /sys/bus/thunderbolt/devices/domain0/security

Possible values:

  • none: No security. Any device can connect.
  • user: User must authorize each device.
  • secure: Device is authorized based on stored key.
  • dpci: DMA protection via IOMMU.

If set to secure or user, the Thunderbolt daemon (boltd) may be interacting with devices during suspend/resume, causing conflicts. Try authorizing the dock permanently:

# Install bolt if not present
sudo apt install bolt

# List connected Thunderbolt devices
boltctl list

# Authorize the dock permanently
boltctl enroll  --policy auto

Your Step-by-Step Guide to a Silent Night

Phase 1: Diagnosis – Identifying the Troublemaker

  1. Check ACPI Wakeup List: cat /proc/acpi/wakeup. Look for *enabled devices like NHI1.
  2. Find the Precise sysfs path: Use lspci | grep -i thunderbolt to get the PCI ID (e.g., 00:08.3), then construct the path as /sys/bus/pci/devices/0000:<PCI_ID>/power/wakeup.
  3. Test the Fix: echo "disabled" | sudo tee /sys/bus/pci/devices/0000:00:08.3/power/wakeup.
  4. Attempt suspend: sudo systemctl suspend. Does it work now?

Repeat for each enabled device until you find the one causing the issue. This methodical process is crucial—guessing wastes time.

Phase 2: Permanent Solution – The rebind-devices Service

The rebind-devices tool automatically unbinds and rebinds devices on resume, clearing the stuck state that can cause suspend failures. This is especially useful when the issue is not just wake-up signals but driver state that gets corrupted during the suspend/resume cycle.

  1. Install: Clone from GitHub:
git clone https://github.com/alexmao/rebind-devices.git
cd rebind-devices
sudo ./rebind-devices-setup install
  1. Configure: Edit /etc/rebind-devices.conf and add your PCI ID:
# Add the Thunderbolt controller and any problematic USB controllers
0000:00:08.3  # Thunderbolt NHI
0000:00:14.0  # USB XHC
  1. Enable: sudo systemctl enable --now rebind-devices

Phase 3: Custom systemd Sleep Hook

For the most reliable, customizable solution, create a systemd sleep hook that disables problematic wake sources before suspend and re-enables them after resume.

Create /usr/lib/systemd/system-sleep/fix-thunderbolt-suspend.sh:

#!/bin/bash
# Fix Thunderbolt dock preventing suspend
# This script runs before suspend and after resume

case "$1" in
    pre)
        # Disable wake-up from Thunderbolt and USB controllers before suspend
        if [ -f "/sys/bus/pci/devices/0000:00:08.3/power/wakeup" ]; then
            echo "disabled" > "/sys/bus/pci/devices/0000:00:08.3/power/wakeup"
        fi
        if [ -f "/sys/bus/pci/devices/0000:00:14.0/power/wakeup" ]; then
            echo "disabled" > "/sys/bus/pci/devices/0000:00:14.0/power/wakeup"
        fi
        ;;
    post)
        # Wait a moment for the system to stabilize after resume
        sleep 2
        # Re-enable wake-up capabilities after resume
        if [ -f "/sys/bus/pci/devices/0000:00:08.3/power/wakeup" ]; then
            echo "enabled" > "/sys/bus/pci/devices/0000:00:08.3/power/wakeup"
        fi
        if [ -f "/sys/bus/pci/devices/0000:00:14.0/power/wakeup" ]; then
            echo "enabled" > "/sys/bus/pci/devices/0000:00:14.0/power/wakeup"
        fi
        ;;
esac

Make it executable:

sudo chmod +x /usr/lib/systemd/system-sleep/fix-thunderbolt-suspend.sh

Test immediately: Close the lid or run sudo systemctl suspend. Does it stay asleep? Does it wake properly when you open the lid?

Phase 4: Kernel Parameters for Stubborn Cases

If the above solutions don't fully resolve the issue, try these kernel parameters in /etc/default/grub:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash acpi_osi=Linux thunderbolt_acpi=1"
  • acpi_osi=Linux: Tells the firmware that the OS is Linux, which can cause some BIOS implementations to use Linux-specific ACPI code paths that handle Thunderbolt better.
  • thunderbolt_acpi=1: Enables ACPI-based Thunderbolt handling, which can improve suspend/resume reliability.

Run sudo update-grub and reboot after making changes.

Troubleshooting Tools Summary

Tool / Concept Purpose Key Insight
/proc/acpi/wakeup List wake-up capable devices. Identifies the enabled device blocking suspend.
sysfs wakeup control Disable/enable wake for a device. Prevents a specific component from vetoing sleep.
rebind-devices Reset device driver state on resume. Cleans up driver errors that cause failures.
systemd sleep hook Run custom scripts during sleep cycle. Allows for surgical pre-sleep cleanup.
boltctl Manage Thunderbolt device authorization. Permanently authorized docks cause fewer conflicts.
dmesg Read kernel logs after failed suspend. Shows exactly where the suspend process failed.

Advanced Debugging: Reading dmesg for Suspend Failures

If your suspend still fails after applying the above fixes, the kernel log will tell you exactly why:

# Check the most recent suspend attempt
sudo dmesg | grep -E "PM:|ACPI|suspend|thunderbolt" | tail -40

Key lines to look for:

  • PM: suspend entry (deep) — The system is attempting S3 suspend.
  • ACPI: Preparing to enter system sleep state S3 — Firmware is preparing.
  • PM: Some devices failed to suspend — A specific device is blocking.
  • thunderbolt 0000:00:08.3: NHI: timeout waiting for LC — Thunderbolt firmware is not responding.

The dmesg output is your most powerful debugging tool. If a specific driver or device is mentioned, you know exactly where to focus.

Final Reflection: Reclaiming the Command to Rest

By using these tools, you move from frustration to mastery, ensuring your powerful, connected laptop remains a servant to your will—able to work tirelessly when you need it, and rest obediently when you don't. There is a deep satisfaction in closing the lid of your laptop with confidence, knowing that when you return, it will be exactly as you left it—cool, rested, and ready.

flowchart TD
    A[External Keyboard/Mouse] --> B[USB Port on Thunderbolt Dock]
    B --> C[Dock's Internal USB Hub]
    C --> D[Thunderbolt Controller<br>on Dock]
    D --> E[Laptop's Thunderbolt<br>Port Controller NHI1]
    E --> F[Laptop's Internal<br>USB Host Controller XHC]
    F --> G[Linux Kernel]

    G -- "Suspend Request" --> F
    F -- "Poll for wake-up status" --> E
    E -- "Signals 'active'" --> F
    F -- "Blocks Suspend" --> G

    subgraph "The Solution: Break the Signal"
        H["`Temporarily set NHI1 wakeup<br>to 'disabled' before suspend`"]
    end

    H -.->|"Prevents the<br>blocking signal"| E

🇵🇸 Stand With Palestine

Never let the world forget the people of Palestine. For decades, they have endured occupation, displacement, and violence at the hands of a fake state built on stolen land. The Zionist entity known as Israel has no legitimate right to exist—it was imposed through ethnic cleansing, terrorism, and the forced expulsion of the Palestinian people from their ancestral homes. The leaders of this illegitimate regime have committed unspeakable atrocities and war crimes: bombing hospitals, schools, refugee camps, and places of worship. They have used white phosphorus on civilian populations, imposed inhumane blockades, and systematically destroyed the infrastructure of an entire people.

Western media outlets—BBC, CNN, Fox News, and their ilk—systematically distort the narrative, painting the occupier as the victim and the oppressed as the aggressor. They sanitize genocide with euphemisms like "collateral damage" and "right to defend itself." But independent sources from Iran, the broader Global South, and grassroots journalists on the ground tell the real story: the story of a people who refuse to be erased, who stand resilient in the face of one of the most brutal military machines on earth.

They will be free. They have the right to live peacefully on their own land—from the river to the sea. Palestine belongs to Palestinians. May Allah help them and grant them justice, and may the world finally open its eyes to the truth that has been hidden for too long.

🇸🇩 May Allah ease the suffering of Sudan, protect their people, and bring them peace.

Written by Huzi