1Haiku boot process specification 2================================ 3 4Creation Date: November 23, 2002 5Version: 2.0 (Jan 22, 2021) 6Status: documenting the current state of things 7Author(s): Axel Dörfler, Adrien Destugues 8 9 10Overview 11-------- 12 13Unlike other systems, Haiku comes with its own user-friendly bootloader. 14The main task of the bootloader is to load and start the kernel. We 15don't have a concept of an initramfs as Linux does, instead our 16bootloader is able to find the kernel and modules in a BFS partition, 17and even extract them from packages as needed. It also provides an early 18boot menu that can be used to change settings, boot older versions of 19Haiku that were snapshotted by the package system, and write boot logs 20to USB mass storage. 21 22Booting from BIOS 23----------------- 24 25Haiku BIOS boot loader process is split into 3 different stages. Since 26the second stage is bound tightly to both other stages (which are 27independent from each other), it is referred to as stage 1.5, whereas 28the other stages are referred to as stage 1 and 2. This architecture is 29used because the BIOS booting process only loads a very small piece of 30code from disk for booting, insufficient for the needs outlined above. 31 32The following will explain all stages in detail. 33 34Stage 1 35~~~~~~~ 36 37The first stage is responsible for loading the real boot loader from a 38BFS disk. It will be loaded by the Master Boot Record (MBR) and executed 39in the x86 real mode. It is only used if the system will be booted 40directly from a BFS partition, it won't be used at all if it is booted 41from a floppy disk or CD-ROM (in this case, stage 1.5 is in charge 42immediately). 43 44| It resides in the first 1024 bytes of a BFS disk which usually refers 45 to the first two sectors of the partition in question. Since the BFS 46 superblock is located at byte offset 512, and about 170 bytes large, 47 this section is already reserved, and thus cannot be used by the 48 loader itself. 49| The MBR only loads the first sector of a partition into memory, so it 50 has to load the superblock (and the rest of its implementation) by 51 itself. 52 53| The loader must be able to load the real boot loader from a certain 54 path, and execute it. In BeOS this boot loader would be in 55 "/boot/beos/system/zbeos", in Haiku this is haiku_loader.bios_ia32 56 found in the haiku_loader package. 57| Theoretically, it is enough to load the first few blocks from the 58 loader, and let the next stage then load the whole thing (which it has 59 to do anyway if it has been written on a floppy). This would be one 60 possible optimization if the 850 bytes of space are filled too early, 61 but would require that "zbeos" is written in one sequential block 62 (which should be always the case anyway). 63 64haiku_loader.bios_ia32 65~~~~~~~~~~~~~~~~~~~~~~ 66 67Contains both the stage 1.5 boot loader, and the compressed stage 2 68loader. It's not an ELF executable file; i.e. it can be directly written 69to a floppy disk which would cause the BIOS to load the first 512 bytes 70of that file and execute it. 71 72Therefore, it will start with the stage 1.5 boot loader which will be 73loaded either by the BIOS when it directly resides on the disk (for 74example when loaded from a floppy disk), or the stage 1 boot loader, 75although this one could have a different entry point than the BIOS. 76 77Stage 1.5 78~~~~~~~~~ 79 80Will have to load the rest of haiku_loader into memory (if not already 81done by the stage 1 loader in case it has been loaded from a BFS disk), 82set up the global descriptor table, switch to x86 protected mode, 83uncompress stage 2, and execute it. 84 85This part is very similar to the stage 1 boot loader from NewOS. 86 87Stage 2 88~~~~~~~ 89 90This is the most complex part of the boot loader. In short, it has to 91load any modules and devices the kernel needs to access the boot device, 92set up the system, load the kernel, and execute it. 93 94The kernel, and the modules and drivers needed are loaded from the boot 95disk - therefore the loader has to be able to access BFS disks. It also 96has to be able to load and parse the settings of these drivers (and the 97kernel) from the boot disk, some of them are already important for the 98boot loader itself (like "don't call the BIOS"). Since this stage is 99already executed in protected mode, it has to use the virtual-86 mode to 100call the BIOS and access any disk. 101 102Before loading those files from the boot disk, it should look for 103additional files located on a specific disk location after the "zbeos" 104file (on floppy disk or CD-ROM). This way, it could access disks that 105cannot be accessed by the BIOS itself. 106 107Setting up the system for the kernel also means initalizing PCI devices 108needed during the boot process before the kernel is up. It must be able 109to do so since the BIOS might not have set up those devices correctly or 110at all. 111 112It also must calculate a check sum for the boot device which the kernel 113can then use to identify the boot volume and partition with - there is 114no other reliable way to map BIOS disk IDs to the /dev/disk/... tree the 115system itself is using. 116 117After having loaded and relocated the kernel, it executes it by passing 118a special structure which tells the kernel things like the boot device 119check sum, which modules are already loaded and where they are. 120 121The stage 2 boot loader also includes user interaction. If the user 122presses a special key during the boot process (like the space key, or 123some others as well), a menu will be presented where the user can select 124the boot device (if several, the loader has to scan for options), safe 125mode options, VESA mode, etc. 126 127This menu may also come up if an error occured during the execution of 128the stage 2 loader. 129 130Open Firmware 131------------- 132 133On Open Firmware based systems, there is no need for a stage 1.5 because 134the firmware does not give us as many constraints. Instead, the stage 2 135is loaded directly by the firmware. This requires converting the 136haiku_loader executable to the appropriate executable format (a.out on 137sparc, pef on powerpc). The conversion is done using custom tools 138because binutils does not support these formats anymore. 139 140There is no notion of real and protected mode on non-x86 architectures, 141and the bootloader is able to easily call Open Firmware methods to 142perform most tasks (disk access, network booting, setting up the 143framebuffer) in a largely hardware-independent way. 144 145U-Boot 146------ 147 148U-Boot is able to load the stage2 loader directly from an ELF file. 149However, it does not provide any other features. It is not possible for 150the bootloader to call into U-Boot APIs for disk access, displaying 151messages on screen etc (while possible in theory, these features are 152often disabled in U-Boot). This means haiku_loader would need to parse 153the FDT (describing the available hardware) and bundle its own drivers 154for using the hardware. This approach is not easy to set up, and it is 155recommended to instead use the UEFI support in U-Boot where possible. 156 157EFI 158--- 159 160On EFI systems, there is no need for a stage1 loader as there is for 161BIOS. Instead, our stage2 loader (haiku_loader) can be executed directly 162from the EFI firmware. 163 164The EFI firmware only knows how to run executables in the PE format (as 165used by Windows) because Microsoft was involved in specifying it. On 166x86_64, we can use binutils to output a PE file directly. But on other 167platforms, this is not supported by binutils. So, what we do is generate 168a "fake" PE header and wrap our elf file inside it. The bootloader then 169parses the embedded ELF header and relocates itself, so the other parts 170of the code can be run. 171 172After this initial loading phase, the process is very similar to the 173Open Firmware one. EFI provides us with all the tools we need to do disk 174access and both text mode and framebuffer output. 175