docs: rebuild KB in OKF v0.1 with live-verified facts
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
This commit is contained in:
Frank
@@ -0,0 +1,301 @@
|
||||
---
|
||||
type: reference
|
||||
title: Linux Power Management
|
||||
description: Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
tags:
|
||||
- power-management
|
||||
- sleep
|
||||
- nvidia
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
Comprehensive guide to sleep/wake configuration and diagnostics on Linux systems. Covers systemd sleep, kernel states, NVIDIA GPU power management, and diagnostic tools.
|
||||
|
||||
---
|
||||
|
||||
## Systemd Sleep Configuration
|
||||
|
||||
### logind.conf (`/etc/systemd/logind.conf`)
|
||||
|
||||
Controls login manager behavior around sleep:
|
||||
|
||||
```ini
|
||||
[Login]
|
||||
HandlePowerKey=poweroff
|
||||
HandleSleepKey=suspend
|
||||
HandleHibernateKey=hibernate
|
||||
HandleLidSwitch=suspend
|
||||
HandleLidSwitchDocked=ignore
|
||||
HoldoffTimeoutSec=5s
|
||||
IdleAction=hibernate
|
||||
IdleActionSec=30min
|
||||
```
|
||||
|
||||
**Key setting**: `HoldoffTimeoutSec` — increase if sleep triggers are too aggressive.
|
||||
|
||||
### sleep.conf (`/etc/systemd/sleep.conf`)
|
||||
|
||||
Controls the actual sleep behavior:
|
||||
|
||||
```ini
|
||||
[Sleep]
|
||||
AllowSuspend=yes
|
||||
AllowHibernation=yes
|
||||
AllowHybridSleep=yes
|
||||
HibernateMode=platform+shutdown
|
||||
HibernateDelaySec=1800
|
||||
```
|
||||
|
||||
**HibernateMode options**:
|
||||
- `platform` — ACPI platform sleep (faster, firmware-dependent)
|
||||
- `shutdown` — classic shutdown-to-disk (slower, more compatible)
|
||||
- `shutdown+platform` — try platform first, fall back to shutdown
|
||||
|
||||
### Suspend-Then-Hibernate Flow
|
||||
|
||||
```
|
||||
Suspend (RAM) --timeout--> Hibernate (disk)
|
||||
|
|
||||
+-- wake event --> Resume
|
||||
```
|
||||
|
||||
### Custom Sleep Hooks
|
||||
|
||||
Create `/etc/systemd/system-sleep/` scripts for pre/post sleep actions:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /etc/systemd/system-sleep/hook
|
||||
case "$1" in
|
||||
pre) echo "Suspending..." ;;
|
||||
post) echo "Resumed!" ;;
|
||||
esac
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Kernel Sleep States
|
||||
|
||||
### ACPI Sleep States
|
||||
|
||||
| State | Name | Power | Wake Time | Description |
|
||||
|-------|------|-------|-----------|-------------|
|
||||
| S0 | Working | Full | Instant | System is running |
|
||||
| S1 | Sleep (halted) | ~10-20W | <1s | CPU halted, RAM refresh |
|
||||
| S2 | Sleep | ~5-10W | ~1s | CPU cache flushed |
|
||||
| **S3** | **Sleeping Standby** | **~1-5W** | **~1-2s** | **RAM retained, most power off** |
|
||||
| S4 | Hibernate | 0W | ~10-30s | RAM written to disk |
|
||||
| **S5** | **Soft Off** | **0W** | **~5-10s** | **Powered off but can wake** |
|
||||
|
||||
### Modern ACPI Sleep States (s2idle)
|
||||
|
||||
Modern laptops often **only support s2idle** (S0 idle):
|
||||
|
||||
```bash
|
||||
$ cat /sys/power/mem_sleep
|
||||
[s2idle] deep
|
||||
```
|
||||
|
||||
| Mode | Name | Power | Characteristics |
|
||||
|------|------|-------|----------------|
|
||||
| **s2idle** | "Suspend to Idle" | 3-8W | Shallow, firmware-managed, fast wake, higher drain |
|
||||
| **deep** | S3 | 1-3W | Deeper sleep, slower wake, better battery |
|
||||
|
||||
### Setting Default Sleep State
|
||||
|
||||
Add to kernel command line (GRUB or systemd-boot):
|
||||
|
||||
```
|
||||
mem_sleep_default=deep # Prefer S3 deep sleep
|
||||
mem_sleep_default=s2idle # Force s2idle
|
||||
```
|
||||
|
||||
**For GRUB:** Edit `/etc/default/grub`, add to `GRUB_CMDLINE_LINUX_DEFAULT`:
|
||||
```
|
||||
GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NVIDIA GPU Power Management
|
||||
|
||||
### Enable NVIDIA Suspend Support
|
||||
|
||||
```bash
|
||||
sudo systemctl enable nvidia-suspend.service
|
||||
sudo systemctl enable nvidia-suspend-then-hibernate.service
|
||||
sudo systemctl enable nvidia-hibernate.service
|
||||
```
|
||||
|
||||
### NVIDIA Module Parameters
|
||||
|
||||
Edit `/etc/modprobe.d/nvidia.conf`:
|
||||
|
||||
```
|
||||
options nvidia NVreg_PreserveVideoMemoryAllocations=1
|
||||
options nvidia NVreg_EnableS0ixPowerManagement=1
|
||||
```
|
||||
|
||||
### Check NVIDIA GPU State
|
||||
|
||||
```bash
|
||||
# Is the NVIDIA GPU active?
|
||||
lspci -vnn | grep -A 12 -i "vga"
|
||||
|
||||
# Force NVIDIA GPU to D3hot (fully off) before suspend
|
||||
sudo tee /sys/bus/pci/devices/0000:01:00.0/power/control <<< auto
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Tools
|
||||
|
||||
### journalctl
|
||||
|
||||
```bash
|
||||
# All sleep-related events in the last boot
|
||||
journalctl -b -0 | grep -iE 'suspend|resume|sleep|wake|acpi'
|
||||
|
||||
# Real-time monitoring during a suspend attempt
|
||||
journalctl -f &
|
||||
systemctl suspend
|
||||
# Wait for failure, then Ctrl+C
|
||||
```
|
||||
|
||||
### powertop
|
||||
|
||||
```bash
|
||||
sudo powertop # Interactive view
|
||||
sudo powertop --calibrate # One-time setup
|
||||
sudo powertop --auto-tune # Apply recommendations
|
||||
sudo powertop --html=/tmp/report.html --csv=/tmp/report.csv
|
||||
```
|
||||
|
||||
### tlp — Advanced Power Management
|
||||
|
||||
```bash
|
||||
sudo pacman -S tlp tlp-rdw # Arch
|
||||
sudo apt install tlp # Debian/Ubuntu
|
||||
sudo systemctl enable --now tlp
|
||||
sudo tlp-stat
|
||||
```
|
||||
|
||||
### dmesg
|
||||
|
||||
```bash
|
||||
dmesg | grep -iE 'suspend|resume|acpi|pm_'
|
||||
dmesg -wH # Watch mode, human-readable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Wake Source Management
|
||||
|
||||
### Checking Wake Sources
|
||||
|
||||
```bash
|
||||
# What can wake the system?
|
||||
cat /proc/acpi/wakeup | grep enabled
|
||||
|
||||
# What woke the system last time?
|
||||
journalctl -b -1 | grep -iE 'PM: wakeup|wakeup source|acpi: wakeup'
|
||||
```
|
||||
|
||||
### Toggling Wake Sources
|
||||
|
||||
```bash
|
||||
# Toggle a device's wake capability
|
||||
echo XHCI | sudo tee /proc/acpi/wakeup
|
||||
echo RP01 | sudo tee /proc/acpi/wakeup
|
||||
```
|
||||
|
||||
### Persistent Wake Source Configuration
|
||||
|
||||
Create a systemd service:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/config-wake-sources.service
|
||||
[Unit]
|
||||
Description=Configure ACPI wake sources
|
||||
Before=sleep.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/bin/bash -c 'echo XHCI > /proc/acpi/wakeup'
|
||||
RemainAfterExit=yes
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Kernel Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `mem_sleep_default=deep` | Prefer S3 deep sleep |
|
||||
| `pcie_aspm=force` | Force ASPM (aggressive power saving) |
|
||||
| `pcie_aspm.policy=performance` | Disable ASPM (fixes some issues) |
|
||||
| `acpi_osi=!` | Hide OS identity from ACPI |
|
||||
| `usbcore.autosuspend=-1` | Disable USB autosuspend |
|
||||
|
||||
---
|
||||
|
||||
## Testing Sleep Modes
|
||||
|
||||
```bash
|
||||
# Suspend to RAM
|
||||
systemctl suspend
|
||||
|
||||
# Hibernate to disk
|
||||
systemctl hibernate
|
||||
|
||||
# Suspend then hibernate
|
||||
systemctl suspend-then-hibernate
|
||||
|
||||
# Freeze (CPUs idle, RAM on)
|
||||
systemctl freeze
|
||||
```
|
||||
|
||||
### Automated Stress Test
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
for i in $(seq 1 10); do
|
||||
echo "=== Cycle $i ==="
|
||||
date
|
||||
echo mem | sudo tee /sys/power/state 2>/dev/null || systemctl suspend
|
||||
echo "Resume $i: SUCCESS"
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Action Items
|
||||
|
||||
```bash
|
||||
# 1. Enable NVIDIA suspend support
|
||||
sudo systemctl enable nvidia-suspend.service
|
||||
sudo systemctl enable nvidia-suspend-then-hibernate.service
|
||||
|
||||
# 2. Add NVIDIA power management module parameter
|
||||
echo 'options nvidia NVreg_PreserveVideoMemoryAllocations=1' | sudo tee /etc/modprobe.d/nvidia-preserve.conf
|
||||
|
||||
# 3. Reboot
|
||||
sudo reboot
|
||||
|
||||
# 4. Test suspend
|
||||
systemctl suspend
|
||||
|
||||
# 5. After resume, check for errors
|
||||
dmesg | tail -30
|
||||
journalctl -b -0 | grep -iE 'error|fail|nvidia' | tail -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- The [AGENTS.md Format](../core/agents-md-format.md) defines the system-level instruction contract that governs how agent sessions configure these systems.
|
||||
Reference in New Issue
Block a user