Haiku's Boot Process: From Boot Loader to Desktop

Haiku boot is a sequence of contracts: firmware finds boot code, the Haiku loader finds a boot volume and prepares the kernel, the kernel initializes memory and devices, the packaged system hierarchy becomes available, and launch_daemon starts user-space services. A failure before the kernel begins and a failure while Tracker starts can both look like “it does not boot,” but they require entirely different evidence.

Haiku’s official boot-process specification and user guide expose unusually useful recovery controls. The loader can select a volume or older package state, disable specific components, choose fail-safe graphics, and preserve debugging output. Those options work best when treated as controlled experiments rather than a random checklist.

Firmware and boot paths

On legacy x86 BIOS systems, firmware loads only a small initial block of boot code. Haiku’s BIOS loader is therefore divided into stages 1, 1.5, and 2. Stage 1 fits the firmware’s constrained entry mechanism, stage 1.5 bridges disk and execution requirements, and stage 2 contains the richer file-system, module-loading, hardware setup, and menu logic needed to start the kernel.

UEFI follows a different firmware contract and loads an EFI application from the system partition. The paths are not interchangeable, even though they eventually prepare the same Haiku kernel interface. A machine reaching the Haiku boot menu has already passed firmware discovery and enough loader execution to draw and accept input; a machine never reaching it may have an installation, firmware-mode, partition, or boot-manager problem.

The loader must identify the boot device despite firmware naming disks differently from the running kernel. The boot-process specification describes collecting configuration and boot-device information and passing a dedicated structure to the kernel. It also prepares CPU and memory details and loads components needed to access the boot volume.

Haiku does not use a Linux-style initramfs. Its loader understands BFS sufficiently to find the kernel and required modules, and the specification says it can extract needed files from packages. That capability is why an arbitrary foreign boot loader cannot simply load one kernel file without satisfying Haiku’s expected handoff and supporting modules.

The official user guide documents how to enter Boot Loader Options: hold Shift before Haiku starts on classic BIOS systems; on UEFI systems use Space. The menu can select a boot volume or saved system state, set safe-mode options, enable debugging output, and force screen resolution.

Safe mode is not one opaque switch. Options include disabling user add-ons, using fail-safe video, disabling DMA or specific interrupt/power features, limiting CPU cores or memory, and selecting individual system components to ignore. The exact list is architecture and build dependent, so the menu’s own description and current user guide are the authority.

Change one option at a time when possible. If fail-safe video changes a black screen into a usable desktop, the result implicates the graphics-driver/mode path more strongly than storage. If disabling user add-ons works, inspect software installed in the user hierarchy. If selecting an older package state works, compare package transactions rather than reinstalling the boot loader.

Debug options can show messages instead of the boot logo, forward syslog to serial, and preserve logs for recovery. Photographing the last icon is weaker than capturing textual output with the last successful subsystem and error. Enable evidence collection before repeating a crash that may overwrite earlier context.

Loader-to-kernel handoff

Before transferring control, the loader relocates the kernel and passes boot arguments describing memory, modules, boot device, and chosen settings. Boot modules include enough bus and storage support for the kernel to continue accessing its root volume. The loader and kernel must agree on this private handoff; mixing a loader from an unrelated BeOS or Haiku revision is not a supported repair technique.

Once execution enters the kernel, architecture code establishes processor state and core kernel subsystems. Memory management, interrupts, timers, scheduler, module infrastructure, device manager, file systems, and additional CPUs are initialized in dependency order. The boot screen’s icons roughly correspond to phases such as modules, rootfs/devfs, device manager, boot disk, CPU-specific modules, final subsystem initialization, and userland launch.

A hang here should be located relative to the last completed phase. A kernel debugger prompt is different from an automatic reboot; a freeze during device exploration is different from a panic mounting the boot disk. Preserve the exact panic text, stack, hardware identifiers, and selected safe-mode settings.

Module design helps isolation but does not make every failure harmless. A storage driver required for the boot disk cannot simply fail and let the system continue. A bad optional add-on may be bypassed. The loader’s ability to disable components exists to distinguish those cases and regain a repair environment.

BFS, packages, and the visible system

The boot volume supplies the writable file-system foundation, while packagefs presents activated packages as the system directory hierarchy. Package-management documentation describes an activated-packages state and historical state directories retained across transactions. The boot loader can choose an older state, which is a powerful recovery path after a package installation makes the latest system unbootable.

Packagefs activation is not the same as copying every package file into /boot/system. It exposes package contents in a unified, largely read-only hierarchy and cooperates with the package daemon for later activation changes. During early boot, the selected consistent state determines which kernel add-ons, libraries, servers, and applications are available.

“Disable user add-ons” and full safe mode address different layers. User add-ons live under the user configuration hierarchy; safe mode can also suppress servers, daemons, and the UserBootscript. A component installed in the system hierarchy may require the loader’s component-disable menu or booting an older package state because /boot/system is package-managed rather than edited like an ordinary directory.

Journaling and package states aid recovery but are not backups. A damaged disk, missing package file, or corrupted BFS structure can prevent even an older activation list from loading. Preserve important data and verify storage health before repeatedly writing to a failing volume.

launch_daemon and the desktop boundary

After the kernel has a working system environment, user-space startup begins. Current Haiku uses launch_daemon and launch configurations to start and supervise services. System servers such as the registrar, input and application servers establish facilities used by ordinary desktop programs. Tracker and Deskbar then provide the visible desktop and menu/task interface.

Reaching a graphical background without Tracker or Deskbar means firmware, loader, kernel, boot storage, and at least part of userland succeeded. A missing desktop component is not evidence to rewrite the partition boot sector. Inspect launch logs, server crashes, user settings, and package availability.

The user boot script and login/session-specific startup happen late compared with kernel initialization. Full safe mode suppressing these components can distinguish a per-user startup problem from a system service failure. Test a clean user configuration only after preserving the original settings for comparison.

Services communicate and depend on one another, so the first visible crash may be downstream. Capture which service failed first, its error status, and any missing library or add-on. Repeatedly killing and restarting the final desktop process can hide a registrar or app_server failure that prevents it from functioning.

A stage-based recovery method

First classify the last known stage: firmware sees the device; Haiku menu appears; kernel icons advance; textual boot reaches a mount; launch begins; or desktop components appear. Record BIOS versus UEFI, selected volume, Haiku revision, and recent hardware/package changes.

If the menu never appears, verify firmware mode, boot entry, EFI system partition or legacy active partition, and installation target. If the menu appears but the kernel does not start, show debug output and test the correct volume/state. If storage mounting fails, focus on controller driver, disk health, partition, BFS, and packages—not the display server.

For a blank screen after kernel progress, try only fail-safe video and compare. For a regression after installing software, disable user add-ons, then select the previous package state. For a multiprocessor or interrupt-related hang, test the corresponding safe option and report the exact hardware and the one option that changes behavior.

Once recovery succeeds, do not leave the diagnosis at “safe mode works.” Re-enable options individually, remove or update the identified component, and confirm two normal cold boots. Save the failing and successful logs. The boot loader’s granularity turns a broad symptom into evidence only when experiments remain controlled.

Related:

Sources: