******************
Boot Flow Overview
******************

To ease the support and developement of CoreOS on multiple plateform,
we use the same boot flow mechanisums on all our supported machine.

Glossary
========

In this document, the following terms have specific meanings:

.. glossary::

    Firmware
      Program that implement the boot and runtime services as defined by the
      :ext+uefi:ref:`UEFI specifications <maincontent>`.

    Application
      Program written according to the UEFI specification that can be started 
      by the firmware. See :ext:ref:`UEFI Applications <uefi-applications>`.
    
    Bootloader
      Application that allow to start other application based on user selection,
      configuration or autodetection.
    
    Operating system
      Application that include at least the Linux Kernel and the initial RAM
      disk.


Generic Boot Flow
=================

.. graphviz:: bootflow-generic.dot

CoreOS use a standardized workflow: the firmware can start either an
optional bootloader or an operating system as an UEFI application.

Firmware
========

CoreOS support two different use case:

Using a CoreOS provided firmware
--------------------------------

The most common use case is to use a firmware image provided by CoreOS as part
of the board support package.

Currently, the CoreOS provided firmware functionality is provided by `u-boot`

Using CoreOS on third party machine
-----------------------------------

As the interface between the firmware and the rest of the system is clearly
defined, we also support to run CoreOS on top of any standard UEFI complient
system. 

As an example, this is the case when using a CoreOS image inside a virtual
machine.

Firmware requirements
---------------------

.. warning::

  CoreOS support at the moment only hardware that contains a block storage
  device (SD Card, eMMC, ...) formatted with GPT. MBR disk or MTD device are
  not supported.

ARM32 / AArch32 based machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The firmware for ARM32 should implement a subset of the UEFI specification, as
defined by the EBBR Specification. As this architecure is used on old hardware,
it's ok to use the part of the specification that are marked as deprecated or
legacy.

We require the firmware to provide a DeviceTree based system description and not
an ACPI based table (as allowed by the specification).

We also require the firmware to implement the UEFI Secure Boot functionality.

ARM64 / AArch64 based machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The firmware for ARM64 should implement a subset of the UEFI specification, as
defined by the EBBR Specification.

We require the firmware to provide a DeviceTree based system description and not
an ACPI based table (as allowed by the specification). The DeviceTree provided
by the firmware can be very minimal as it can be replaced at boot time
by a device-tree contained inside the Operating System Image.

We also require the firmware to implement the UEFI Secure Boot functionality.


AMD64 / x86_64 based machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The firmware for AMD64 should implement the UEFI specification.

Bootloader
==========

CoreOS only support `efibootguard` as bootloader. The usage of the bootloader
is mandated.


Operating system
================

The operating system image is an UEFI application that contain the kernel. It's
a Unified Kernel Image generated by tools from the EFIBootGuard project.