arm/arm64 UEFI boot protocol

arm/arm64 UEFI boot protocol

[Leif Lindholm]

Hi all,

We currently have a few sets of patches floating around, for UEFI
runtime services, UEFI stub and GRUB support for Linux/UEFI on
arm/arm64.

The last version of Documentation/arm/uefi.txt I sent out raised a few
questions with regards to the boot protocol between UEFI and Linux, and
there is also upcoming support for ACPI which could use a few
clarifications in this area.

So, rather than sending out complete sets of patches for all these until
consensus is reached, below is my proposed suggestion for a
Documentation/arm/uefi.txt, to be shared for arm and arm64. If noone has
strong objections to this, we can quickly send updated (and hopefully
final-ish) versions of these sets.

/
    Leif

---

UEFI, the Unified Extensible Firmware Interface is a specification
governing the behaviours of compatible firmware interfaces.
It is maintained by the UEFI Forum - http://www.uefi.org/.
Support for the AArch32 (arm) architecture was added in version 2.3 of
the specification, and support for AAaarch64 (arm64) was added in
version 2.4.

UEFI is an evolution of its predecessor 'EFI', so the terms EFI and
EFI are used somewhat interchangeably in this document and associated
source code. As a rule, anything new uses 'UEFI', whereas 'EFI' refers
to legacy code or specifications.  

UEFI support in Linux                                                           
=====================                                                           
Booting on a platform with firmware compliant with the UEFI
specification makes it possible for the kernel to support additional
features:
- UEFI Runtime Services
- Retrieving various configuration information through the standardised
  interface of UEFI configuration tables. (ACPI, SMBIOS, ...)

For actually enabling [U]EFI support, enable:
- CONFIG_EFI=y
- CONFIG_EFI_VARS=y or m

UEFI stub
=========
The "stub" is a feature that turns the Image/zImage/bzImage into a valid
UEFI PE/COFF executable, including a loader application that makes it
possible to load the kernel directly from the UEFI shell, boot menu, or
one of the lightweight bootloaders like Gummiboot or rEFInd. 
The kernel image built with stub support remains a valid kernel image
for booting in the legacy fashion.

UEFI kernel support on ARM
==========================
The implementation depends on receiving information about the UEFI
environment in a Flattened Device Tree (FDT) - so is only available with
CONFIG_OF.

UEFI support also depends on early_memremap().

UEFI kernel support on the ARM architectures (arm and arm64) is only
available when boot is performed through the stub.

When booting in UEFI mode, the kernel ignores any memory nodes in the
DT, and instead reads the UEFI memory map. To prevent confusion, the
stub deletes any memory nodes from a provided DT.

The stub populates the FDT /chosen node with, and the kernel scans for
the following parameters:
________________________________________________________________________________
Name                      | Size   | Description
================================================================================
linux,uefi-system-table   | 64-bit | Physical address of the UEFI System Table.
--------------------------------------------------------------------------------
linux,uefi-mmap           | 64-bit | Physical address of the UEFI memory map,
                          |        | populated by the UEFI GetMemoryMap() call.
--------------------------------------------------------------------------------
linux,uefi-mmap-size      | 32-bit | Size in bytes of the UEFI memory map
                          |        | pointed to in previous entry.
--------------------------------------------------------------------------------
linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI
                          |        | memory map.
--------------------------------------------------------------------------------
linux,uefi-stub-kern-ver  | string | Copy of linux_banner from build.
--------------------------------------------------------------------------------

For verbose debug messages, specify 'uefi_debug' on the kernel command line.

Re: arm/arm64 UEFI boot protocol

[Will Deacon]

Hi Leif,

On Mon, Nov 11, 2013 at 05:43:21PM +0000, Leif Lindholm wrote:
> We currently have a few sets of patches floating around, for UEFI
> runtime services, UEFI stub and GRUB support for Linux/UEFI on
> arm/arm64.
> 
> The last version of Documentation/arm/uefi.txt I sent out raised a few
> questions with regards to the boot protocol between UEFI and Linux, and
> there is also upcoming support for ACPI which could use a few
> clarifications in this area.
> 
> So, rather than sending out complete sets of patches for all these until
> consensus is reached, below is my proposed suggestion for a
> Documentation/arm/uefi.txt, to be shared for arm and arm64. If noone has
> strong objections to this, we can quickly send updated (and hopefully
> final-ish) versions of these sets.

In the absence of code, I'll play English teacher then :)

> UEFI, the Unified Extensible Firmware Interface is a specification

Interface, is

> governing the behaviours of compatible firmware interfaces.
> It is maintained by the UEFI Forum - http://www.uefi.org/.
> Support for the AArch32 (arm) architecture was added in version 2.3 of
> the specification, and support for AAaarch64 (arm64) was added in
> version 2.4.

AArch64

> UEFI is an evolution of its predecessor 'EFI', so the terms EFI and
> EFI are used somewhat interchangeably in this document and associated

UEFI

> source code. As a rule, anything new uses 'UEFI', whereas 'EFI' refers
> to legacy code or specifications.  
> 
> UEFI support in Linux                                                           
> =====================                                                           
> Booting on a platform with firmware compliant with the UEFI
> specification makes it possible for the kernel to support additional
> features:
> - UEFI Runtime Services
> - Retrieving various configuration information through the standardised
>   interface of UEFI configuration tables. (ACPI, SMBIOS, ...)
> 
> For actually enabling [U]EFI support, enable:
> - CONFIG_EFI=y
> - CONFIG_EFI_VARS=y or m
> 
> UEFI stub
> =========
> The "stub" is a feature that turns the Image/zImage/bzImage into a valid

We don't support bzImage for arm or arm64.

> UEFI PE/COFF executable, including a loader application that makes it
> possible to load the kernel directly from the UEFI shell, boot menu, or
> one of the lightweight bootloaders like Gummiboot or rEFInd. 
> The kernel image built with stub support remains a valid kernel image
> for booting in the legacy fashion.

By legacy, you mean non-UEFI rather than EFI? I consider UEFI as a choice
rather than the future ;p

> UEFI kernel support on ARM
> ==========================

Wait, isn't this all under Documentation/arm/? You could probably combine
some of these sections together, since the scope is really tied to ARM here.

> The implementation depends on receiving information about the UEFI
> environment in a Flattened Device Tree (FDT) - so is only available with
> CONFIG_OF.

You could mention this in your earlier list of dependencies.

> UEFI support also depends on early_memremap().

Why is that worthy of note? Can a user even turn that off?

> UEFI kernel support on the ARM architectures (arm and arm64) is only
> available when boot is performed through the stub.
> 
> When booting in UEFI mode, the kernel ignores any memory nodes in the
> DT, and instead reads the UEFI memory map. To prevent confusion, the
> stub deletes any memory nodes from a provided DT.
> 
> The stub populates the FDT /chosen node with, and the kernel scans for
> the following parameters:

Sentence doesn't read very well. Maybe stick some brackets around (and the
kernel scans for)?

> ______________________________________________________________________________
> Name                      | Size   | Description
> ================================================================================
> linux,uefi-system-table   | 64-bit | Physical address of the UEFI System Table.
> --------------------------------------------------------------------------------
> linux,uefi-mmap           | 64-bit | Physical address of the UEFI memory map,
>                           |        | populated by the UEFI GetMemoryMap() call.
> --------------------------------------------------------------------------------
> linux,uefi-mmap-size      | 32-bit | Size in bytes of the UEFI memory map
>                           |        | pointed to in previous entry.
> --------------------------------------------------------------------------------
> linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI
>                           |        | memory map.

Do we actually need to define these sizes here, or can they be dealt with
using the usual #address-cells property? Also, I think you should describe
the binding in a separate document somewhere under Documentation/devicetree,
then cross-reference it from here.

> --------------------------------------------------------------------------------
> linux,uefi-stub-kern-ver  | string | Copy of linux_banner from build.
> --------------------------------------------------------------------------------

Are you sure you want to refer to kernel symbols here? If somebody renames
that variable, they're not going to fix this file.

Will

Re: arm/arm64 UEFI boot protocol

[Leif Lindholm]

On Tue, Nov 12, 2013 at 04:42:41PM +0000, Will Deacon wrote:
> > So, rather than sending out complete sets of patches for all these until
> > consensus is reached, below is my proposed suggestion for a
> > Documentation/arm/uefi.txt, to be shared for arm and arm64. If noone has
> > strong objections to this, we can quickly send updated (and hopefully
> > final-ish) versions of these sets.
> 
> In the absence of code, I'll play English teacher then :)

Yey - a reply!

> > UEFI, the Unified Extensible Firmware Interface is a specification
> 
> Interface, is

ok
 
> > governing the behaviours of compatible firmware interfaces.
> > It is maintained by the UEFI Forum - http://www.uefi.org/.
> > Support for the AArch32 (arm) architecture was added in version 2.3 of
> > the specification, and support for AAaarch64 (arm64) was added in
> > version 2.4.
> 
> AArch64
 
ok

> > UEFI is an evolution of its predecessor 'EFI', so the terms EFI and
> > EFI are used somewhat interchangeably in this document and associated
> 
> UEFI
 
ok

> > UEFI stub
> > =========
> > The "stub" is a feature that turns the Image/zImage/bzImage into a valid
> 
> We don't support bzImage for arm or arm64.
 
Well, it works the same on x86, and the feature is called the same.
Once we get the basic support in, I'm planning to write a
Documentation/uefi.txt and move all of the non architecture-specific to.

> > UEFI PE/COFF executable, including a loader application that makes it
> > possible to load the kernel directly from the UEFI shell, boot menu, or
> > one of the lightweight bootloaders like Gummiboot or rEFInd. 
> > The kernel image built with stub support remains a valid kernel image
> > for booting in the legacy fashion.
> 
> By legacy, you mean non-UEFI rather than EFI? I consider UEFI as a choice
> rather than the future ;p

So, "historical"? "Traditional"? Or just "non-UEFI"?
 
> > UEFI kernel support on ARM
> > ==========================
> 
> Wait, isn't this all under Documentation/arm/? You could probably combine
> some of these sections together, since the scope is really tied to ARM here.
 
Same reason as above, but I could squash for now.

> > The implementation depends on receiving information about the UEFI
> > environment in a Flattened Device Tree (FDT) - so is only available with
> > CONFIG_OF.
> 
> You could mention this in your earlier list of dependencies.
 
Ditto.

> > UEFI support also depends on early_memremap().
> 
> Why is that worthy of note? Can a user even turn that off?
 
Not really.

> > The stub populates the FDT /chosen node with, and the kernel scans for
> > the following parameters:
> 
> Sentence doesn't read very well. Maybe stick some brackets around (and the
> kernel scans for)?
 
ok

> > ______________________________________________________________________________
> > Name                      | Size   | Description
> > ================================================================================
> > linux,uefi-system-table   | 64-bit | Physical address of the UEFI System Table.
> > --------------------------------------------------------------------------------
> > linux,uefi-mmap           | 64-bit | Physical address of the UEFI memory map,
> >                           |        | populated by the UEFI GetMemoryMap() call.
> > --------------------------------------------------------------------------------
> > linux,uefi-mmap-size      | 32-bit | Size in bytes of the UEFI memory map
> >                           |        | pointed to in previous entry.
> > --------------------------------------------------------------------------------
> > linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI
> >                           |        | memory map.
> 
> Do we actually need to define these sizes here, or can they be dealt with
> using the usual #address-cells property? Also, I think you should describe
> the binding in a separate document somewhere under Documentation/devicetree,
> then cross-reference it from here.
 
This is not a generic ABI, so I don't think it belongs in there (it will
never be in a .dtb, and the only way it can be generated by something
that isn't the stub is by lying).
But I don't really care either way - as long as some general agreement
can be had.

> > --------------------------------------------------------------------------------
> > linux,uefi-stub-kern-ver  | string | Copy of linux_banner from build.
> > --------------------------------------------------------------------------------
> 
> Are you sure you want to refer to kernel symbols here? If somebody renames
> that variable, they're not going to fix this file.

There is a comment above the definition of linux_banner that says:
/* FIXED STRINGS! Don't touch! */

Sounded reliable enough to me :)

/
    Leif

Re: arm/arm64 UEFI boot protocol

[Grant Likely]

On Wed, Nov 13, 2013 at 3:00 AM, Leif Lindholm <leif.lindholm-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
> On Tue, Nov 12, 2013 at 04:42:41PM +0000, Will Deacon wrote:
>> > ______________________________________________________________________________
>> > Name                      | Size   | Description
>> > ================================================================================
>> > linux,uefi-system-table   | 64-bit | Physical address of the UEFI System Table.
>> > --------------------------------------------------------------------------------
>> > linux,uefi-mmap           | 64-bit | Physical address of the UEFI memory map,
>> >                           |        | populated by the UEFI GetMemoryMap() call.
>> > --------------------------------------------------------------------------------
>> > linux,uefi-mmap-size      | 32-bit | Size in bytes of the UEFI memory map
>> >                           |        | pointed to in previous entry.
>> > --------------------------------------------------------------------------------
>> > linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI
>> >                           |        | memory map.
>>
>> Do we actually need to define these sizes here, or can they be dealt with
>> using the usual #address-cells property? Also, I think you should describe
>> the binding in a separate document somewhere under Documentation/devicetree,
>> then cross-reference it from here.
>
> This is not a generic ABI, so I don't think it belongs in there (it will
> never be in a .dtb, and the only way it can be generated by something
> that isn't the stub is by lying).
> But I don't really care either way - as long as some general agreement
> can be had.

There is precedence with inserting the initrd location into the kernel
with similar properties. I think the binding does the right thing
here.

In the interest of bike shedding, I would name the properties
"linux,uefi-mmap-start" and "linux,uefi-mmap-size", but otherwise it
is fine by me. Should you have a property for the descriptor version
as returned by GetMemoryMap()?

>
>> > --------------------------------------------------------------------------------
>> > linux,uefi-stub-kern-ver  | string | Copy of linux_banner from build.
>> > --------------------------------------------------------------------------------
>>
>> Are you sure you want to refer to kernel symbols here? If somebody renames
>> that variable, they're not going to fix this file.
>
> There is a comment above the definition of linux_banner that says:
> /* FIXED STRINGS! Don't touch! */
>
> Sounded reliable enough to me :)

I think this is just fine.

g.

Re: arm/arm64 UEFI boot protocol

[Leif Lindholm]

On Wed, Nov 13, 2013 at 07:14:28AM +0900, Grant Likely wrote:
> In the interest of bike shedding, I would name the properties
> "linux,uefi-mmap-start" and "linux,uefi-mmap-size", but otherwise it
> is fine by me.

That makes sense to me, and makes for a prettier table :)

> Should you have a property for the descriptor version
> as returned by GetMemoryMap()?
 
Yes, I should, really. I did in an earlier version, but dropped it on
realising that this value has not changed since the inception of EFI.
But it needs to be passed back to SetVirtualAddressMap(), so it should
be kept. Mark never dropped it from his.

So, "linux,uefi-mmap-desc-ver"?

/
    Leif