Programming for EFI:
Creating a "Hello, World" Program

by Roderick W. Smith, rodsmith@rodsbooks.com

Originally written: 5/3/2013

I'm a technical writer and consultant specializing in Linux technologies. This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!

Donate $1.00	Donate $2.50	Donate $5.00	Donate $10.00	Donate another value

Note: This page is a sub-page of my Programming for EFI document. If a Web search has brought you here, you may want to start at the introductory page.

The traditional first program for a new compiler or environment is "Hello, World." I therefore present such a program for EFI, including the program itself, a Makefile for the program, and instructions on how to compile and run it.

A "Hello, World" program for EFI demonstrates some of the unique features of EFI programming. To begin, consider the program itself:

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

EFI_STATUS
EFIAPI
efi_main (EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable) {
   InitializeLib(ImageHandle, SystemTable);
   Print(L"Hello, world!\n");

   return EFI_SUCCESS;
}

If you want to try compiling the program itself, cut-and-paste the preceding lines into a file called main.c; the Makefile presented shortly assumes this name. Many of this program's features are similar to those of a similar program for Linux, Windows, or other OSes and environments; however, there are some significant differences, too:

• The program begins with two #include directives, which load EFI header files from the GNU-EFI package. You should not normally include regular C header files, such as stdlib.h, because most of these header files define data types and functions that are used by the C library. This library is not available in EFI, though, and because of differences in compilation options, you can't easily compile it into an EFI program. Instead, you must rely exclusively on your development package's library. Also note that if you use TianoCore's EDK II rather than GNU-EFI, you'll need to include different (and usually more) header files than shown here.
• Instead of using an entry point function called main(), EFI programs written with GNU-EFI use an entry point called efi_main(). This function takes two arguments, as shown in the sample program, which point to the program's image and to the EFI system table, respectively. (The EFI system table is the key to accessing most EFI features, as described on the Using EFI Services page.) If you use the TianoCore EDK II toolkit, you can give the program's entry point another name, but you must specify the entry point when linking the program.
• The efi_main() function returns a value of type EFI_STATUS. Possible return values are summarized in the Phoenix EFI documentation, among other places. The sample program always returns EFI_SUCCESS, but a more complex program might return another value.
• The definition of EFIAPI varies between platforms. It tells the compiler to use EFI's calling conventions for the specified function. Unfortunately for Linux programmers, EFI uses Microsoft's application binary interface (ABI), rather than the System V (SysV) ABI used by Linux, and therefore used by GCC by default. Functions called from outside your own program, such as efi_main() and functions you pass to the EFI (as drivers are likely to do, and as you might do if you want to patch the EFI's service tables) must be so identified. If you use the TianoCore toolkit, it uses the Microsoft ABI internally, but GNU-EFI uses the SysV ABI internally.
• The call to InitializeLib() sets up some critical global variables that are created by GNU-EFI and used to access the firmware's features. Most importantly, the ST variable identifies the system table, the BS variable refers to boot services, and RT refers to runtime services. If you use the TianoCore EDK II, this call doesn't exist, and the variables in question are generally referred to as gST, gBS, and gRT, respectively.
• The EFI Print() call takes the place of the printf() function with which you're probably familiar. You can use the two in a very similar fashion, but this example program illustrates one exception: Strings in EFI use a 16-bit encoding, so you must precede string constants with the character L to denote a 16-bit representation. When using string variables, they must normally be defined as a CHAR16* type in order to display properly with Print() or to be passed to most EFI functions. More advanced programs can use common conversion specifiers with Print(), such as %s for strings and %d for decimal numbers.

More complex programs will of course expose additional differences between a C program written for most OSes and one written for EFI. Most of these differences relate to library differences between EFI and other environments.

If you were building a "Hello, World" program for Linux in a Linux environment, you could compile it without a Makefile. Building the program in Linux for EFI, though, is essentially a cross-compilation operation. As such, it necessitates using unusual compilation and linker options, as well as a post-linking operation to convert the program into a form that the EFI will accept. Although you could type all the relevant commands by hand, a Makefile helps a lot. Such a file to build the preceding program file looks like this:

ARCH            = $(shell uname -m | sed s,i[3456789]86,ia32,)

OBJS            = main.o
TARGET          = hello.efi

EFIINC          = /usr/include/efi
EFIINCS         = -I$(EFIINC) -I$(EFIINC)/$(ARCH) -I$(EFIINC)/protocol
LIB             = /usr/lib64
EFILIB          = /usr/lib64/gnuefi
EFI_CRT_OBJS    = $(EFILIB)/crt0-efi-$(ARCH).o
EFI_LDS         = $(EFILIB)/elf_$(ARCH)_efi.lds

CFLAGS          = $(EFIINCS) -fno-stack-protector -fpic \
		  -fshort-wchar -mno-red-zone -Wall 
ifeq ($(ARCH),x86_64)
  CFLAGS += -DEFI_FUNCTION_WRAPPER
endif

LDFLAGS         = -nostdlib -znocombreloc -T $(EFI_LDS) -shared \
		  -Bsymbolic -L $(EFILIB) -L $(LIB) $(EFI_CRT_OBJS) 

all: $(TARGET)

hello.so: $(OBJS)
	ld $(LDFLAGS) $(OBJS) -o $@ -lefi -lgnuefi

%.efi: %.so
	objcopy -j .text -j .sdata -j .data -j .dynamic \
		-j .dynsym  -j .rel -j .rela -j .reloc \
		--target=efi-app-$(ARCH) $^ $@

If you cut-and-paste this code into a text editor, be sure to convert stretches of eight characters to tabs! Also, be aware that you may need to adjust the EFIINC, LIB, and EFILIB variables to point to the relevant portions of your GNU-EFI installation directory. EFIINC should, of course, point to your GNU-EFI include files; LIB should point to the directory that holds the libefi.a and libgnuefi.a files; and EFILIB should point to the directory that holds the crt0-efi-x86_64.o and elf_x86_64_efi.lds files (or equivalents for another architecture). The Makefile shown here works on a Fedora 18 installation. On Ubuntu 13.04, both LIB and EFILIB must be set to /usr/lib; and on Gentoo, they must both be set to /usr/lib64.

The CFLAGS line sets a number of options that are important for getting a working EFI binary. Although some of these could be omitted or changed for the simple "Hello, World" demonstration, they can be important for larger programs:

• -fno-stack-protector—Stack protection isn't supported by EFI, so there's no point in building a binary with this feature active.
• -fpic—EFI requires that code be position-independent, hence the use of this option.
• -fshort-wchar—GCC defines the wchar_t type to be 32 bits by default, but EFI requires it to be 16 bits for 16-bit strings to work correctly.
• -fmno-red-zone—On x86-64 systems, the red zone is an area that follows the stack pointer that can be used for temporary variables. The EFI may modify this area, though, so it's not safe to use, and you must compile EFI binaries with this option.
• -Wall—When developing EFI applications, you might want to pay extra attention to compiler warnings, and this switch (which causes warnings to be treated as errors) can help.
• -DEFI_FUNCTION_WRAPPER—This option is required on the x86-64 platform, but is not defined on the 32-bit x86 platform. It relates to the calling conventions for EFI functions, described on the Using EFI Services page.

Linker flags are defined in LDFLAGS, of course. They have the following effects:

• -nostdlib—An EFI application should not be linked against standard libraries, and this argument accomplishes this goal.
• -nocombreloc—This argument causes the linker to not combine relocation sections.
• -T $(EFI_LDS)—To create an EFI binary, a non-standard linker script must be used, and this option tells ld where to find it.
• -shared—Even with GNU-EFI's new linker script, ld can't create the final executable. Instead, it creates a shared library, which is subsequently turned into the final binary.
• -Bsymbolic—This option causes references to global symbols to be bound to the definitions within the shared library.

When ld finishes its work, the result is a file called hello.so, which is technically a shared library. To create an EFI executable, the Makefile calls the objcopy program, which copies the code needed from the library to create an EFI application.

If you use TianoCore EDK II, many of these options will be different. One extremely important difference is the inclusion of the -DEFIAPI=__attribute__((ms_abi)) GCC flag, which causes the binary to be built using Microsoft's ABI. The linking process is also different; the TianoCore EDK II includes its own program, called GenFw, that builds the final binary instead of objcopy. TianoCore is designed around a build process that doesn't use make, so you must either use TianoCore's own build process or design a Makefile to mimic it. I don't describe either approach here, so you should consult TianoCore's documentation for the first option. If you want to use TianoCore with make, check rEFInd, which uses this approach, as a model.

Compiling the program is simple: Type make. The result should be generation of intermediate files and the final hello.efi program file of about 46KiB on a 64-bit system. If you encounter errors, you'll have to fix them yourself. Be sure that your Makefile uses tabs where necessary, and check the locations of the header and library files, as already described. Note that the build process described here results in a program file for the architecture you're using. If you build on a 64-bit system, the binary won't work on a 32-bit computer, and vice-versa.

The best way to run the program is likely to be from an EFI shell. You can download a binary from the TianoCore site, for both 64-bit (x86-64) and 32-bit (x86) platforms. Rename these files as shellx64.efi or shellia32.efi, respectively, and place them in the root directory of your EFI System Partition (ESP). Some ESPs and boot managers, such as rEFInd and gummiboot, recognize this name and location as special, and will enable you to launch a shell when one exists there. Other boot managers, such as GRUB, may require explicit configuration to launch an EFI shell. Treat the shell like an OS's boot loader. For instance, in GRUB 2 you might create an entry in /etc/grub.d/40_custom like the following:

menuentry "EFI shell" {
        insmod part_gpt
        insmod chain
        set root='(hd0,gpt1)'
        chainloader /shellx64.efi
}

Note: If your computer boots with Secure Boot active, you should disable Secure Boot for your initial tests, since launching your own applications on such a computer complicates matters.

Details will vary depending on your installation, though. Once you've made these changes, use update-grub or grub-mkconfig to re-create your grub.cfg file with the new entry to launch the EFI shell.

When you launch your EFI shell, you should type fs0: to change to the first filesystem, which is normally the ESP. You can then type hello.efi to launch the program. You should see its output, as in:

Shell> fs0:

fs0:\> hello.efi
Hello, world!

fs0:\> exit

If the program hangs or otherwise misbehaves, you may need to review the code and build process. Unfortunately, debugging EFI applications can be tedious, because the usual debugging tools don't work with them. I find that using a virtual machine can help. VirtualBox, for instance, supports EFI, so it's possible to install Linux under EFI on VirtualBox and use it for testing EFI applications compiled in the host environment. This procedure at least obviates the need to re-start your editor or IDE after every test of your program. Ubuntu and Linux Mint work well in this role because they both boot very quickly, which can speed things up if you need to make a small but quick change to be tested immediately.

Go on to "Using EFI Services"

Return to the "Programming for EFI" main page

copyright © 2013 by Roderick W. Smith

If you have problems with or comments about this Web page, please e-mail me at rodsmith@rodsbooks.com. Thanks.

Return to my main Web page.