Skip to content
Haiku OSDeep Dive Published Updated 7 min readViews unavailable

Haiku Suspend and Resume: Driver Hooks Are Not a Sleep Guarantee

Audit Haiku's declared driver suspend/resume callbacks, the kernel call path, and the limits of battery or CPU power features before promising system sleep.

A callback in a driver interface is not proof that the operating system calls it. Haiku’s device-driver API declares suspend() and resume() hooks, which can make system sleep appear closer to completion than it is. In the upstream source snapshot examined here, the device-manager documentation explicitly says those hooks are never called because power management is not implemented; a pinned-source search also finds the declarations but no device-manager invocation. Do not infer a working suspend-to-RAM or hibernation path from the function pointers alone.

This is a source-status and support-boundary guide, not a claim that Haiku has no power-related behavior. Battery telemetry, CPU frequency or idle handling, display blanking, and full-machine suspend are separate mechanisms. One working path does not establish another. The implementation references below are pinned to Haiku commit 388ca6823493ae937134949782be1eac9f5343b9 (the upstream master revision inspected on 2026-10-13); recheck later revisions before relying on this conclusion for a future release.

What the driver API declares

The public device-manager header defines driver_module_info, including these two function-pointer fields:

status_t (*suspend)(void *driverCookie, int32 state);
status_t (*resume)(void *driverCookie);

The names describe per-driver operations: prepare a driver’s device for a requested state and resume it afterward. They do not by themselves specify who initiates a system transition, how a state value maps to ACPI S-states, which devices must quiesce first, how wake sources are selected, or how the kernel handles a driver that returns an error. Those contracts require a caller and a system-wide transition policy.

The distinction is visible in the same upstream tree. Haiku’s device-driver architecture document lists the callbacks and then states that they are currently never called because Haiku has no power management implemented. The matching driver-module header confirms that the declarations exist. Read together, the sources distinguish an API shape from an operational feature.

At that pinned revision, the device-manager implementation handles driver registration, child-device discovery, and device removal, but the kernel device-manager path contains no call through the driver’s suspend or resume fields. A text search can return resume_thread() in the I/O scheduler; that resumes a kernel thread and is not a call to a hardware driver’s resume() callback. Search results must be interpreted by type and call site, not by substring.

Keep separate power features separate

Several things can look like “power management” in a desktop UI or a laptop specification while proving nothing about system suspend:

Observation What it can establish What it does not establish
Battery icon shows charge state A battery value reached the status application at some point. That the value is fresh, or that devices can be quiesced and restored across sleep.
CPU speed or idle behavior changes A processor-related policy may be active on that hardware and build. That RAM remains powered while the rest of the machine enters S3, or that resume works.
Display turns off The display path changed state; this may be screen blanking rather than machine sleep. That the CPU, storage, USB, network, and other devices entered a system sleep state.
Lid-close action or third-party menu appears A UI or add-on exposes an action with that label. That the kernel invokes the declared driver callbacks or can recover the complete machine.

Haiku’s battery telemetry path is a different topic: it traces ACPI battery methods through a driver to PowerStatus. A valid battery reading does not show that the kernel coordinates suspend/resume. Likewise, device discovery and readiness through select() or poll(), covered by Haiku Device Driver Readiness: select(), poll(), and Waiter Lifetimes, does not establish a power-transition lifecycle.

For support reports, describe observable behavior precisely. “The screen blanked while audio continued” is different from “the machine entered a system sleep state and resumed.” Record whether fans, network traffic, timers, audio, and disk activity continue, but do not use any single symptom as proof of the internal ACPI state. If the platform has no supported sleep workflow, prefer a normal shutdown before transporting a laptop or closing its lid for an extended period; save work and verify a backup rather than betting on undocumented behavior.

Reproduce the source-level check

If a future Haiku release or downstream fork changes its behavior, inspect the exact source revision rather than copying an old forum post. In a Haiku source checkout, record the revision and compare the public declaration, documentation, and caller path:

git rev-parse HEAD

# The API declaration and the documentation's explicit status statement.
git grep -n -E 'suspend|resume' HEAD -- \
  headers/os/drivers/device_manager.h \
  docs/develop/kernel/device_manager_introduction.rst

# Look specifically for calls through driver callback fields in the kernel.
if git grep -n -E -e '->(suspend|resume)' HEAD -- \
  src/system/kernel/device_manager; then
    : # Matching call sites need inspection.
else
    grep_status=$?
    if [ "$grep_status" -ne 1 ]; then
        printf 'git grep failed with status %d\n' "$grep_status" >&2
        exit "$grep_status"
    fi
fi

The last command’s empty result is meaningful only for the inspected tree and paths; it is not a formal proof that no experimental code exists anywhere in every fork. Inspect surrounding code and the target release’s changes. A result for resume_thread() is a scheduler operation, not the callback, and a pointer declaration is not a call. If the source has moved, search for the driver-module structure’s call sites and trace the initiating system transition from the UI or service down to the kernel.

Do not try to “test” an unimplemented path by calling a private ioctl, invoking a guessed command, or writing to a device node. An invented interface can hang, corrupt work, or simply do nothing; it creates no useful evidence. On a supported Haiku build, use only a documented user-facing sleep control if one exists for that build and hardware. The pinned sources here do not identify such a control or promise it works, so this article deliberately provides no supposed pm-suspend command or configuration key.

What a real implementation would have to prove

Per-device callbacks are only one part of a system-wide transition. An implementation would also need an owner for transition requests; a defined state vocabulary; coordination for user processes and filesystems; dependency-aware ordering for buses and child devices; callback timeout and error policy; wake-source configuration; and a restoration path that brings display, input, storage, network, and timers back consistently. It would need to handle partial failure without leaving some devices asleep and others active. These are engineering requirements inferred from the callback boundary and the device tree, not claims about features already present in Haiku.

This is why a driver author should not add a suspend() function and advertise laptop sleep as complete. The callback would need a real caller, a stable state contract, ordering relative to parent and child devices, and tests on hardware where losing power or failing to wake cannot destroy the only copy of a user’s data. Device-specific resume also needs to restore enough state for normal I/O, not merely return B_OK.

For downstream implementers, treat early experiments as development-only. Keep another machine or serial/debug path available, back up test data, test on disposable volumes, and record the exact kernel and driver revisions. Exercise repeated transitions, wake sources, unplug/replug behavior, timeout paths, and rollback after one driver refuses to quiesce. A one-time dark screen followed by a reboot is not a successful suspend/resume test.

A practical support decision

When a user asks whether a Haiku laptop supports sleep, check the exact release notes and source revision for an implemented, documented system-level workflow. Do not answer “yes” from the presence of battery status, CPU scaling, a driver’s callback declaration, or a third-party menu label. If the only evidence is the driver_module_info fields, explain that these define hooks but the inspected device manager does not call them and the upstream documentation explicitly says the power-management path is not implemented at that snapshot.

That answer is narrower, and more useful, than a blanket statement about every form of power conservation. Haiku can expose battery data and may support other power-related behavior without providing a reliable suspend or hibernate contract. Pin the source revision, distinguish hardware-specific observations from OS guarantees, and update the conclusion only when the implementation and documentation show a complete transition path.

Related:

Sources:

Comments