The Gigaboot boot loader

The Gigaboot boot loader is a UEFI boot shim for Zircon that can load images via chaining from iPXE, from a UEFI-accessible filesystem, or from local disk partitions.


Arguments are taken from the kernel command line, or additionally from the EFI command line for Gigaboot itself.

  • bootloader.zircon-a: Sets the fallback filename to use for loading the Zircon-A image (default: zircon.bin).
  • bootloader.zircon-b: Sets the fallback filename to use for loading the Zircon-B image (default: zedboot.bin).
  • bootloader.zircon-r: Sets the fallback filename to use for loading the Zircon-R (recovery) image (default: none).
  • bootloader.fbres: Sets the framebuffer resolution (e.g. 1024x768; default: automatic).
  • bootloader.default: Sets the default boot choice in the boot menu; default is the first in the list. Possible values are network, local or zedboot.

Fastboot support

Gigaboot supports fastboot over UDP. You can enter fastboot mode by pressing f during boot, or by invoking dm reboot-bootloader from Fuchsia.

Protocol Information

Gigaboot implements the fastboot over UDP protocol described here.

Example usage:

# Replace the IP with your device's IP, which is printed to serial and the
# display on boot.
fastboot -s udp:fe80::aaaa:bbbb:cccc:dddd getvar all

# Depending on your host network setup, you may need to specify a particular
# network interface as well.
fastboot -s udp:fe80::aaaa:bbbb:cccc:dddd%enx123 getvar all

Supported Commands

rebootReboots the device into the current active partition, as determined by ABR.
reboot-recoveryReboots the device into R.
reboot-bootloaderReboots the device into Fastboot mode.
flash [partition] [image]Flashes the given image onto the given partition.
erase [partition]Erases a partition by writing 0xff to it.
getvar [varname]Gets the value of the given variable.
`set_active [ab]`

The partitions available for flashing/erasing are listed here.

Supported Variables

allA meta-variable that lists all variables stored in the bootloader.
max-download-sizeThe maximum image size that can be sent over
slot-countThe number of slots that can be set active on the device.
bootloader-min-versionsThe minimum required version of the bootloader.
current-slotThe slot currently marked active by ABR.
versionThe fastboot protocol version.

Chaining with iPXE

Here is an example iPXE script showing how to chain Gigaboot. In this example, the files are loaded from a web server running on; we chain from Gigaboot into Zedboot.


echo Chain loader

prompt --key 0x02 --timeout 3000 Chain Loader: Press Ctrl-B for the iPXE command line... && shell ||
kernel bootloader.default=local bootloader.zircon-a=zedboot.zbi || goto loop2

initrd || goto loop2

boot || goto loop2

Build notes

Since UEFI images are in PE32+ file format, we require that our binaries be position independent executables with no relocations. For the most part this does not require any extra effort on x86-64, but it does mean that you cannot statically initialize any variables that hold an address. (These addresses may be assigned at runtime however.)

External Dependencies

qemu-system-x86_64 is needed to test in emulation; gnu parted and mtools are needed to generate the disk.img for Qemu.

Useful Resources & Documentation

ACPI & UEFI Specifications:

Intel 64 and IA-32 Architecture Manuals:

Tianocore UEFI Open Source Community (Source for OVMF, EDK II Dev Environment, etc):