Multiboot1 Bare Bones

Difficulty level
Beginner

Kernel Designs
Models
Monolithic Kernel Microkernel Exokernel Nano/Picokernel Cache Kernel Virtualizing Kernel Megalithic Kernel
Other Concepts
Modular Kernel Higher Half Kernel 64-bit Kernel Hybrid Kernel

In this tutorial we will compile a simple C kernel and boot it.

WAIT! Have you read Getting Started, Beginner Mistakes, and some of the related OS theory?

Preface

This tutorial assumes you have a compiler / assembler / linker toolchain capable of handling ELF files. On a Windows machine, you are strongly encouraged to set up a GCC Cross-Compiler, as it removes all the various toolchain-specific issues you might have ("PE operation on a non-PE file", "unsupported file format", and a number of others). While technically a Linux machine already has an ELF-capable toolchain, you are still encouraged to build a cross-compiler, as it is the first step to do, and it keeps you from relying on things you shouldn't (header files, for example).

The code in this tutorial assumes you are using GRUB to boot the system. GRUB (a Multiboot compliant boot loader) puts the system in to the correct state for your kernel to start executing. This includes enabling the A20 line (to give you access to all available memory addresses) and putting the system in to 32-bit Protected Mode, giving you access to a theoretical 4GiB of memory.

Overview

Even when using GRUB, some setup is required before entering an int main() type function. The most basic setup to get an ELF format kernel to be booted by GRUB consists of three files:

• loader.s - assembler "glue" between bootloader and kernel
• kernel.c - your actual kernel routines
• linker.ld - for linking the above files

The second part of this tutorial briefly describes how to boot the compiled kernel.

loader.s

loader.s takes over over control from the Multiboot bootloader, and jumps into the kernel proper.

NASM

global loader           ; making entry point visible to linker
extern kmain            ; kmain is defined elsewhere

; setting up the Multiboot header - see GRUB docs for details
MODULEALIGN equ  1<<0                   ; align loaded modules on page boundaries
MEMINFO     equ  1<<1                   ; provide memory map
FLAGS       equ  MODULEALIGN | MEMINFO  ; this is the Multiboot 'flag' field
MAGIC       equ    0x1BADB002           ; 'magic number' lets bootloader find the header
CHECKSUM    equ -(MAGIC + FLAGS)        ; checksum required

section .text
align 4
MultiBootHeader:
   dd MAGIC
   dd FLAGS
   dd CHECKSUM

; reserve initial kernel stack space
STACKSIZE equ 0x4000                  ; that's 16k.

loader:
   mov esp, stack+STACKSIZE           ; set up the stack
   push eax                           ; pass Multiboot magic number
   push ebx                           ; pass Multiboot info structure

   call  kmain                       ; call kernel proper

   cli
hang:
   hlt                                ; halt machine should kernel return
   jmp   hang

section .bss
align 32
stack:
   resb STACKSIZE                     ; reserve 16k stack on a quadword boundary

Assemble using:

nasm -f elf -o loader.o loader.s

GAS

.global loader                 # making entry point visible to linker

# setting up the Multiboot header - see GRUB docs for details
.set ALIGN,    1<<0             # align loaded modules on page boundaries
.set MEMINFO,  1<<1             # provide memory map
.set FLAGS,    ALIGN | MEMINFO  # this is the Multiboot 'flag' field
.set MAGIC,    0x1BADB002       # 'magic number' lets bootloader find the header
.set CHECKSUM, -(MAGIC + FLAGS) # checksum required

.align 4
.long MAGIC
.long FLAGS
.long CHECKSUM

# reserve initial kernel stack space
.set STACKSIZE, 0x4000          # that is, 16k.
.comm stack, STACKSIZE, 32      # reserve 16k stack on a quadword boundary

loader:
   mov   $(stack + STACKSIZE), %esp # set up the stack
   push  %eax                       # Multiboot magic number
   push  %ebx                       # Multiboot data structure

   call  kmain            # call kernel proper

   cli
hang:
   hlt                    # halt machine should kernel return
   jmp   hang

Assemble using:

as -o loader.o loader.s

kernel.c

This is not exactly your average int main() (which is one of the reasons why you should not call it like that). Most notably, you do not have any library stuff available. As soon as you write so much as #include <, you have probably made the first mistake. Welcome to kernel land.

void kmain( void* mbd, unsigned int magic )
{
   if ( magic != 0x2BADB002 )
   {
      /* Something went not according to specs. Print an error */
      /* message and halt, but do *not* rely on the multiboot */
      /* data structure. */
   }

   /* You could either use multiboot.h */
   /* (http://www.gnu.org/software/grub/manual/multiboot/multiboot.html#multiboot_002eh) */
   /* or do your offsets yourself. The following is merely an example. */ 
   char * boot_loader_name = (char *)mbd + 64;

   /* Print a letter to screen to see everything is working: */
   unsigned char *videoram = (unsigned char *) 0xb8000;
   videoram[0] = 65; /* character 'A' */
   videoram[1] = 0x07; /* forground, background color. */

   /* Write your kernel here. */
}

Compile using:

gcc -o kernel.o -c kernel.c -Wall -Wextra -Werror -nostdlib -nostartfiles -nodefaultlibs

Note: the flags -Wall -Wextra -Werror are not exactly required, but using them will certainly help you later on. They might seem to be a pest, but remember: The compiler is your friend! Note #2: The code as given will fail to compile with the -Werror flag. You may wish to remove it temporarily

linker.ld

ENTRY (loader)

SECTIONS{
    . = 0x00100000;

    .text :{
        *(.text)
    }

    .rodata ALIGN (0x1000) : {
        *(.rodata)
    }

    .data ALIGN (0x1000) : {
        *(.data)
    }

    .bss : {
        sbss = .;
        *(COMMON)
        *(.bss)
        ebss = .;
    }
}

Link using:

ld -T linker.ld -o kernel.bin loader.o kernel.o

The file kernel.bin is now your kernel (all other files are no longer needed).

In the next section of this tutorial, we will actually boot this kernel!

Booting the kernel

In a few minutes, you will see your kernel in action.

Preparing a virtual computer (Bochs/QEMU) and grub

Main articles: Bochs, GRUB

In short: bochs is a virtual computer (so you won't damage your real computer), and grub is a boot loader. Another option is to use QEMU, an alternative virtual computer.

For bochs, prepare a configuration file named bochsrc.txt in your working directory. It should contain

boot: floppy
floppya: 1_44="floppy.img", status=inserted

which means that we will boot from a virtual floppy (actually a file). We will create this floppy file below.

For QEMU you just need to make sure it is installed, you can do this via your package manager (eg: apt,yum). For example, under ubuntu:

sudo apt-get install qemu

From the GRUB project download the binaries. For a first success, only the files stage1 and stage2 are needed. They are in a package named grub-0.97-pc386.

Also create a file named pad with exactly 750 bytes (content does not matter; more precisely, the 750 is the result of 102400 - len(stage1)- len(stage2)). eg: 102400 - (512 + 101138) = 750

To create this pad file under linux type:

dd if=/dev/zero of=pad bs=1 count=750

Creating the floppy image

Create the floppy image as follows:

cat  stage1 stage2 pad kernel.bin > floppy.img # linux, netbsd, ...
copy /b stage1+stage2+pad+kernel.bin   floppy.img # Windows, DOS

As a result, the kernel begins exactly in block #200 (remember, a block equals 512 bytes). Without padding, the kernel would start in the middle of a block, making it impossible to boot.

Note: bochs may complain about the size of the floppy image. If this happens, it means bochs wants a floppy image file that is 1474560 bytes long (or any other accepted size, but 1.44MB is the canonical size for a floppy). Simply create another pad file of the appropriate size to use in your cat statement. For example:

cat stage1 stage2 pad kernel.bin pad2 > floppy.img

with the resulting floppy.img being 1474560 bytes.

Starting the virtual computer (Bochs/QEMU)

This step is equivalent to turning on a computer with a bootable floppy inserted.

Important: first check the size of your kernel.bin in blocks. This is the length in bytes, divided by 512 and rounded up to the next integer. You will need this number. Let us assume that the kernel size is 18 blocks.

ToDo: Quote from Solar: The whole Bochs section is a bit fishy, as it makes assumptions on the sizes of stage1, stage2, and kernel.bin, but doesn't elaborate on how to determine them, so I guess it's easy to fall into the trap of merely copying the values without checking them.

If you are using bochs, Type bochs. If you are using QEMU, Type qemu -fda floppy.img

It will display a "monitor" with some messages from GRUB, ending in a command promt. Type:

kernel 200+18
boot

The first command means that the kernel starts at block #200 (see above) and its size is 18 blocks. This just loads the kernel into the memory, but does not start it. The boot command really starts the kernel.

Questions

Why the multiboot header? Wouldn't a pure ELF file be loadable by GRUB anyway?

GRUB is capable of loading a variety of formats. However, in this tutorial we are creating a Multiboot compliant kernel that could be loaded by any other compliant bootloader. To achieve this, the multiboot header is mandatory.

Is the AOUT kludge required for my kernel ?

The AOUT kludge is not necessary for kernels in ELF format: a multiboot-compliant loader will recognize an ELF executable as such and use the program header to load things in their proper place. You can provide an AOUT kludge with your ELF kernel, in which case the headers of the ELF file are ignored. With any other format, such as AOUT, COFF or PE kernels, the AOUT kludge it is required, however.

Can the multiboot header be anywhere in the kernel file, or does it have to be in a specific offset?

The multiboot header must be in the first 8kb of the kernel file for GRUB to find it. You can ensure that this is the case by putting the header in its own source code file and passing that as the first object file to LD.

Will GRUB wipe the BSS section before loading the kernel?

Yes. For ELF kernels, the .bss section is automatically identified and cleared (despite the Multiboot specification being a bit vague about it). For other formats, if you ask it politely to do so, that is if you use the 'address override' information from the multiboot header (flag #16) and give a non-zero value to the bss_end_addr field. Note that using "address override" with an ELF kernel will disable the default behavior and do what is described by the "address override" header instead.

What is the state of registers / memory / etc. when GRUB calls my kernel?

GRUB is an implementation of the Multiboot specification. Anything not specified there is "undefined behavior", which should ring a bell (not only) with C/C++ programmers... Better check the Machine State section of multiboot documentation, and assume nothing else.

I get unresolved references because of missing / superfluous underscores in the object files !?

As an immediate resolve, you can use -fno-leading-underscores or -fleading-underscores to get the object file variant you need; in the long run, you might want to set up a GCC Cross-Compiler with the correct default behavior.

I get Error: junk at end of line, first unrecognized character is ',' ...

Chances are the GNU as you use is not targeted at ELF - it chokes on the .comm stack, STACKSIZE, 32 line, as three arguments to .comm are only supported for ELF targets. Try setting up a GCC Cross-Compiler.

I still get Error 13: Invalid or unsupported executable format from GRUB ...

Chances are the multiboot header is missing from the final executable.

If you are using some other format than ELF (such as PE), you should specify the AOUT kludge in the multiboot header. The mbchk program (coming with GRUB) and "objdump -h" should give you more hints about what is going on.

It may also happen if you use an ELF object file instead of an executable (e.g. you have an ELF file with unresolved symbols or unfixable relocations). Try to link your ELF file to a binary executable to get more accurate error messages.