UEFI App Bare Bones

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

Difficulty level
Medium

In this tutorial, developers will create a hard drive or ISO image containing a bare bones UEFI application for the x86-64 platform.

It is recommended to have read and fully understood the Bare Bones tutorial first. The UEFI page provides some background to the UEFI boot process and should also be consulted first.

This tutorial uses the header files and GUID definitions from the GNU-EFI project, but does not use the gnu-efi build system, but rather the MinGW-w64 or LLVM/Clang toolchain.

Prerequisites

Developers will need a GCC Cross-Compiler or Clang targeting the x86_64-w64-mingw32 target (for PE output), and the gnu-efi package (for UEFI headers). Most Linux distros provide cross-compilers for this target, so it's usually not necessary to build it yourself. This example does not link against GNU-EFI or follow its build process; only the headers are used.

To build the EFI filesystem image, developers can use MTools or mkgpt to create a hard disk image. To build a CD image, xorriso (in mkisofs emulation mode) will be needed. To run under an emulator, it is best to use qemu-system-x86_64 coupled with the x64 OVMF firmware.

Under an apt-based system (e.g. Debian/Ubuntu), developers can run:

sudo apt-get install qemu ovmf gnu-efi binutils-mingw-w64 gcc-mingw-w64 xorriso mtools

To install mkgpt you can run these commands:

git clone https://github.com/jncronin/mkgpt.git
cd mkgpt
automake --add-missing
autoreconf
./configure
make
sudo make install

Testing the emulator

Now is a good time to check the emulator is working successfully with the OVMF firmware.

qemu-system-x86_64 -L OVMF_dir/ -pflash OVMF.fd

should launch qemu and launch a UEFI shell prompt.

Preparing the files

hello.c

Next, create a file with the following:

#include <efi.h>
#include <efilib.h>

EFI_STATUS efi_main(EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable)
{
    EFI_STATUS Status;
    EFI_INPUT_KEY Key;

    /* Store the system table for future use in other functions */
    ST = SystemTable;

    /* Say hi */
    Status = ST->ConOut->OutputString(ST->ConOut, L"Hello World\r\n"); // EFI Applications use Unicode and CRLF, a la Windows
    if (EFI_ERROR(Status))
        return Status;

    /* Now wait for a keystroke before continuing, otherwise your
       message will flash off the screen before you see it.

       First, we need to empty the console input buffer to flush
       out any keystrokes entered before this point */
    Status = ST->ConIn->Reset(ST->ConIn, FALSE);
    if (EFI_ERROR(Status))
        return Status;

    /* Now wait until a key becomes available.  This is a simple
       polling implementation.  You could try and use the WaitForKey
       event instead if you like */
    while ((Status = ST->ConIn->ReadKeyStroke(ST->ConIn, &Key)) == EFI_NOT_READY) ;

    return Status;
}

gnu-efi/lib/data.c

Developers will also need bring in the data.c file from the gnu-efi distribution, as this contains many predefined GUIDs for the various UEFI services. To avoid bloat and unnecessary dependencies on the rest of gnu-efi, it will need to be edited to remove the references to 'LibStubStriCmp', 'LibStubMetaiMatch', and 'LibStubStrLwrUpr' (simply set all the members of the LibStubUnicodeInterface structure be NULL).

gnu-efi/lib/lib.h

data.c includes this file. It must be copied as-is to the source directory.

Building

To build, use the cross-compiler:

# compile: (flags before -o become CFLAGS in the Makefile)
x86_64-w64-mingw32-gcc -ffreestanding -Ipath/to/gnu-efi/inc -Ipath/to/gnu-efi/inc/x86_64 -Ipath/to/gnu-efi/inc/protocol -c -o hello.o hello.c
x86_64-w64-mingw32-gcc -ffreestanding -Ipath/to/gnu-efi/inc -Ipath/to/gnu-efi/inc/x86_64 -Ipath/to/gnu-efi/inc/protocol -c -o data.o path/to/gnu-efi/lib/data.c
# link: (flags before -o become LDFLAGS in the Makefile)
x86_64-w64-mingw32-gcc -nostdlib -Wl,-dll -shared -Wl,--subsystem,10 -e efi_main -o BOOTX64.EFI hello.o data.o

Note here that '--subsystem 10' specifies an EFI application for ld.

Under LLVM/clang

The build sequence under LLVM/clang is essentially the same, although there is the advantage of having all targets installed by default:

CFLAGS='-target x86_64-unknown-windows 
        -ffreestanding 
        -fshort-wchar 
        -mno-red-zone 
        -Ipath/to/gnu-efi/inc -Ipath/to/gnu-efi/inc/x86_64 -Ipath/to/gnu-efi/inc/protocol'
LDFLAGS='-target x86_64-unknown-windows 
        -nostdlib 
        -Wl,-entry:efi_main 
        -Wl,-subsystem:efi_application 
        -fuse-ld=lld-link'
clang $CFLAGS -c -o hello.o hello.c
clang $CFLAGS -c -o data.o path/to/gnu-efi/lib/data.c
clang $LDFLAGS -o BOOTX64.EFI hello.o data.o

Passing '--target x86_64-unknown-windows' to clang tells it to compile for x86_64 "Windows". This is quite not the same as 64-bit UEFI PE yet, but as before the "freestanding" part makes it a good kernel image. An example of this toolchain is found in the c-efi project.

Note the '-mno-red-zone' part used here as well -- it is a bad idea to use a red zone for kernel code if interrupts are to be implemented. It should be done with GCC as well, but read Libgcc without red zone for the extra work needed to be done.

Creating the FAT image

Main article: Bootable Disk

Next, create a FAT filesystem image.

dd if=/dev/zero of=fat.img bs=1k count=1440
mformat -i fat.img -f 1440 ::
mmd -i fat.img ::/EFI
mmd -i fat.img ::/EFI/BOOT
mcopy -i fat.img BOOTX64.EFI ::/EFI/BOOT

Running as a USB stick image

The FAT image can either be written directly to a USB stick and used in in a UEFI machine, or it can be run directly in QEMU:

qemu-system-x86_64 -L OVMF_dir/ -pflash OVMF.fd -usb -usbdevice disk::fat.img

Creating and running the HD image

The HD image is a disk image in the GPT format, with the FAT image specially identified as a 'EFI System Partition'.

mkgpt -o hdimage.bin --image-size 4096 --part fat.img --type system
qemu-system-x86_64 -L OVMF_dir/ -pflash OVMF.fd -hda hdimage.bin

Creating and running the CD image

The ISO image is a standard ISO9660 image which contains the FAT image as a file. A special El Torito option (-e) then points EFI aware systems to this image to be loaded. The CD image can either be burned to a CD and ran in a UEFI machine, or run directly in QEMU:

mkdir iso
cp fat.img iso
xorriso -as mkisofs -R -f -e fat.img -no-emul-boot -o cdimage.iso iso
qemu-system-x86_64 -L OVMF_dir/ -pflash OVMF.fd -cdrom cdimage.iso

What to do next?

Developers may want to try using some more of the EFI boot services, e.g., to read more files from the FAT image, manage memory, set up graphical frame buffer etc. (see the UEFI Specifications page for further documentation of this).

There is also a finished app bare bone which supports both Linux and Windows (Visual Studio), see uefi-simple.

Common problems

Some UEFI hardware implementations require that the FAT image is in the FAT32 format (rather than FAT12 or FAT16). OVMF does not have this limitation, so developers will not see such a problem in QEMU. However, the minimum size of a FAT32 filesystem is around 32 MiB, so developers will need to generate a much larger image and pass the '-F' option to mformat.

See also

• UEFI
• UEFI ISO Bare Bones
• GNU-EFI
• POSIX-UEFI