Haiku KDL: Capture Kernel-Hang Evidence Before Rebooting

Kernel Debugging Land (KDL) is Haiku’s interactive kernel debugger environment. It is distinct from the graphical Debugger application used for userland crashes and distinct from a shell prompt. KDL is useful when the kernel has panicked or the machine appears to have stopped making progress, but it is not a general repair console. Its primary value is diagnostic: capture the first failure, current execution context, relevant stacks and system state, then preserve that evidence before rebooting.

The biggest operational risk is entering KDL without a plan, typing speculative commands, and then restarting before recording the result. A kernel hang may involve broken keyboard input, a driver that holds the display, or a system that has stopped scheduling. KDL availability and commands vary by architecture and build. Use the official command guide for the running revision and do not assume every command exists in every release.

Decide whether KDL is the right tool

If one application crashes but the desktop and other applications continue, use the userland Debugger and preserve its report/core. If a server such as app_server or media_server fails while the kernel still runs, collect its crash report and system logs. KDL is for kernel-level failures: a panic, hard system hang, suspected kernel/driver fault, or explicit entry into the debugger.

The system may enter KDL automatically after a fatal kernel error. On supported keyboard/architecture combinations, the official user guide documents an Alt+SysReq+D sequence for entering KDL; SysReq is often mapped to Print Screen, but keyboard firmware, USB controllers, and hardware can prevent the combination from working. Do not promise that a keyboard shortcut will recover a frozen machine.

If the display is unusable or keyboard input does not work, serial or on-screen debug output configured through the boot loader may be the only practical evidence path. Configure diagnostic output before reproducing the issue. That preparation is safer than trying to enable logging after a total freeze.

Capture the first screen before issuing commands

Record the complete initial KDL screen, including the reason for entry, panic text, CPU or thread context when shown, fault address, and any stack already printed. Take a photograph if the system is on physical hardware. On a virtual machine, save the complete console output or a screenshot. Preserve exact characters; a single module name or address can identify the fault path.

Note the Haiku revision/build, architecture, hardware, connected peripherals, loaded third-party drivers, recent updates, boot options, and the exact action that triggered the failure. Record whether the failure is deterministic and how long it takes. Do not change several variables before capturing a baseline.

KDL commands can help inspect teams, threads, stacks, semaphores, areas, ports, modules, and memory. The official guide documents commands such as teams, threads, and sc/bt for stack traces, but the command set is build-specific. Check the KDL guide before relying on a command or piping syntax. A useful sequence is to identify the current thread and affected subsystem, collect relevant stack traces, then capture logs. Do not dump unrelated memory or run expensive scans on a machine already in a fragile state.

Use bounded inspection to answer one question

For a suspected deadlock, determine whether the blocked thread waits on a lock, semaphore, port, or I/O path, and which other thread could make progress. A stack trace can show where a thread is blocked; it does not by itself prove ownership or root cause. Compare several relevant threads and note repeated wait chains. Do not declare a lock cycle from one truncated stack.

For a panic, preserve the first failure context. Later errors may be consequences. Capture the current stack, faulting address, thread/team, and loaded module context, then stop. Avoid trying to “fix” memory or alter kernel state from KDL; a modified system may continue in a corrupted state and destroy evidence.

If the official debugger supports redirection or output capture in the current build, use only documented forms. The user guide describes piping some command output to a file, but whether filesystem writes work depends on the current failure state. Serial output or a photo is a safer fallback. Never assume a command output file was successfully flushed just because the command returned.

Continue and reboot are decisions, not repairs

KDL provides ways to continue execution or reboot on supported systems. continue is useful only when the system can safely resume and the action is part of controlled diagnosis; it does not repair a broken kernel invariant. A panicked kernel may immediately fail again or corrupt data if resumed. Reboot discards volatile context, so capture evidence first unless there is an immediate hardware or safety concern.

Before rebooting a wedged system, consider whether writes may still be in flight. If the machine is already panicked, filesystem integrity cannot be guaranteed. After restart, run appropriate filesystem checks only when evidence or symptoms justify it; do not launch repair tools reflexively while the disk may still be mounted or active.

Prepare persistent logs before reproducing

Haiku’s boot loader has options for previous-session syslog and on-screen debug output. Configure these before the next reproduction when normal logs do not survive a crash. The official bug-reporting guidance explains tradeoffs: on-screen output is timing-sensitive and useful only for specific investigations; serial output can preserve text that a frozen display cannot. Record which option was enabled because instrumentation can change timing.

Keep one baseline without optional tracing when possible, then one trace-enabled reproduction. Compare the two rather than assuming the trace is neutral. Do not publish complete logs without reviewing them for private paths, email addresses, credentials, or user data.

Build a useful kernel bug report

A strong report includes exact steps, expected and actual result, frequency, revision, architecture, hardware/peripherals, recent changes, boot options, complete KDL text or image, and any relevant previous-session syslog. Separate observation from hypothesis: “the stack stopped in driver X” is evidence; “driver X is definitely the cause” is an inference unless reproduced by isolation.

If the failure started after an update, preserve the old and new package/build identifiers and change only one component at a time. If a third-party module is involved, record its package/version and whether disabling it in Safe Mode prevents the failure. Do not upload a whole disk image or private crash dump unless maintainers request it through a suitable channel.

For a userland crash, use the userland Debugger instead. Its report and core-file workflow is designed for application address spaces; a KDL stack is not a substitute. Keep that distinction clear in a ticket so maintainers receive the right artifact.

Verification checklist

Before reproduction, confirm that previous-session logging or serial capture is configured and that you know how to retrieve it. At failure time, preserve the first KDL screen, identify whether the system entered automatically or by request, collect only documented and relevant thread/stack information, and note any command that fails. After reboot, copy logs before normal use overwrites them and verify that the saved file is non-empty.

KDL is most effective when used like a forensic snapshot, not an interactive repair environment. Distinguish kernel failures from application/server faults, preserve first-failure data, use commands documented for the current build, and state clearly what could not be captured. This produces useful evidence while reducing the chance that debugging activity obscures the original failure.

Related:

Sources: