Runnable examples
Let's create and run some minuscule bare metal hello world programs that run without an OS on:
We will also try them out on the QEMU emulator as much as possible, as that is safer and more convenient for development. The QEMU tests have been on an Ubuntu 18.04 host with the pre-packaged QEMU 2.11.1.
The code of all x86 examples below and more is present on this GitHub repo.
How to run the examples on x86 real hardware
Remember that running examples on real hardware can be dangerous, e.g. you could wipe your disk or brick the hardware by mistake: only do this on old machines that don't contain critical data! Or even better, use cheap semi-disposable devboards such as the Raspberry Pi, see the ARM example below.
For a typical x86 laptop, you have to do something like:
Burn the image to an USB stick (will destroy your data!):
sudo dd if=main.img of=/dev/sdX
plug the USB on a computer
turn it on
tell it to boot from the USB.
This means making the firmware pick USB before hard disk.
If that is not the default behavior of your machine, keep hitting Enter, F12, ESC or other such weird keys after power-on until you get a boot menu where you can select to boot from the USB.
It is often possible to configure the search order in those menus.
For example, on my T430 I see the following.
After turning on, this is when I have to press Enter to enter the boot menu:
Then, here I have to press F12 to select the USB as the boot device:
From there, I can select the USB as the boot device like this:
Alternatively, to change the boot order and choose the USB to have higher precedence so I don't have to manually select it every time, I would hit F1 on the "Startup Interrupt Menu" screen, and then navigate to:
Boot sector
On x86, the simplest and lowest level thing you can do is to create a Master Boot Sector (MBR), which is a type of boot sector, and then install it to a disk.
Here we create one with a single printf call:
printf '364%509s125252' > main.img
sudo apt-get install qemu-system-x86
qemu-system-x86_64 -hda main.img
Outcome:
Note that even without doing anything, a few characters are already printed on the screen. Those are printed by the firmware, and serve to identify the system.
And on the T430 we just get a blank screen with a blinking cursor:
main.img contains the following:
364 in octal == 0xf4 in hex: the encoding for a hlt instruction, which tells the CPU to stop working.
Therefore our program will not do anything: only start and stop.
We use octal because x hex numbers are not specified by POSIX.
We could obtain this encoding easily with:
echo hlt > a.S
as -o a.o a.S
objdump -S a.o
which outputs:
a.o: file format elf64-x86-64
Disassembly of section .text:
0000000000000000 <.text>:
0: f4 hlt
but it is also documented in the Intel manual of course.
%509s produce 509 spaces. Needed to fill in the file until byte 510.
125252 in octal == 0x55 followed by 0xaa.
These are 2 required magic bytes which must be bytes 511 and 512.
The BIOS goes through all our disks looking for bootable ones, and it only considers bootable those that have those two magic bytes.
If not present, the hardware will not treat this as a bootable disk.
If you are not a printf master, you can confirm the contents of main.img with:
hd main.img
which shows the expected:
00000000 f4 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 |. |
00000010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 | |
*
000001f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 55 aa | U.|
00000200
where 20 is a space in ASCII.
The BIOS firmware reads those 512 bytes from the disk, puts them into memory, and sets the PC to the first byte to start executing them.
Hello world boot sector
Now that we have made a minimal program, let's move to a hello world.
The obvious question is: how to do IO? A few options:
ask the firmware, e.g. BIOS or UEFI, to do it for us
VGA: special memory region that gets printed to the screen if written to. Can be used in Protected Mode.
write a driver and talk directly to the display hardware. This is the "proper" way to do it: more powerful, but more complex.
serial port. This is a very simple standardized protocol that sends and receives characters from a host terminal.
On desktops, it looks like this:
Source.
It is unfortunately not exposed on most modern laptops, but is the common way to go for development boards, see the ARM examples below.
This is really a shame, since such interfaces are really useful to debug the Linux kernel for example.
use debug features of chips. ARM calls theirs semihosting for example. On real hardware, it requires some extra hardware and software support, but on emulators it can be a free convenient option. Example.
Here we will do a BIOS example as it is simpler on x86. But note that it is not the most robust method.
main.S
.code16
mov $msg, %si
mov $0x0e, %ah
loop:
lodsb
or %al, %al
jz halt
int $0x10
jmp loop
halt:
hlt
msg:
.asciz "hello world"
GitHub upstream.
link.ld
SECTIONS
{
/* The BIOS loads the code from the disk to this location.
* We must tell that to the linker so that it can properly
* calculate the addresses of symbols we might jump to.
*/
. = 0x7c00;
.text :
{
__start = .;
*(.text)
/* Place the magic boot bytes at the end of the first 512 sector. */
. = 0x1FE;
SHORT(0xAA55)
}
}
Assemble and link with:
as -g -o main.o main.S
ld --oformat binary -o main.img -T link.ld main.o
qemu-system-x86_64 -hda main.img
Outcome:
And on the T430:
Tested on: Lenovo Thinkpad T430, UEFI BIOS 1.16. Disk generated on an Ubuntu 18.04 host.
Besides the standard userland assembly instructions, we have:
.code16: tells GAS to output 16-bit code
cli: disable software interrupts. Those could make the processor start running again after the hlt
int $0x10: does a BIOS call. This is what prints the characters one by one.
The important link flags are:
--oformat binary: output raw binary assembly code, don't wrap it inside an ELF file as is the case for regular userland executables.
To better understand the linker script part, familiarize yourself with the relocation step of linking: What do linkers do?
Cooler x86 bare metal programs
Here are a few more complex bare metal setups that I've achieved:
Use C instead of assembly
Summary: use GRUB multiboot, which will solve a lot of annoying problems you never thought about. See the section below.
The main difficulty on x86 is that the BIOS only loads 512 bytes from the disk to memory, and you are likely to blow up those 512 bytes when using C!
To solve that, we can use a two-stage bootloader. This makes further BIOS calls, which load more bytes from the disk into memory. Here is a minimal stage 2 assembly example from scratch using the int 0x13 BIOS calls:
Alternatively:
- if you only need it to work in QEMU but not real hardware, use the
-kernel option, which loads an entire ELF file into memory. <a href="https://github.com
