Re: [PATCH v2 1/3] Documentation: arm: add UEFI support documentation

Re: [PATCH v2 1/3] Documentation: arm: add UEFI support documentation

[Rob Herring]

Adding devicetree list since you are defining bindings...

On 10/03/2013 06:24 AM, Leif Lindholm wrote:
> This patch provides documentation of the [U]EFI runtime services and
> configuration features.
> 
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
> Acked-by: Rob Landley <rob@landley.net>
> ---
>  Documentation/arm/00-INDEX |    3 +++
>  Documentation/arm/uefi.txt |   47 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 50 insertions(+)
>  create mode 100644 Documentation/arm/uefi.txt
> 
> diff --git a/Documentation/arm/00-INDEX b/Documentation/arm/00-INDEX
> index 4978456..87e01d1 100644
> --- a/Documentation/arm/00-INDEX
> +++ b/Documentation/arm/00-INDEX
> @@ -36,3 +36,6 @@ nwfpe/
>  	- NWFPE floating point emulator documentation
>  swp_emulation
>  	- SWP/SWPB emulation handler/logging description
> +
> +uefi.txt
> +	- [U]EFI configuration and runtime services documentation
> diff --git a/Documentation/arm/uefi.txt b/Documentation/arm/uefi.txt
> new file mode 100644
> index 0000000..e6e4d41
> --- /dev/null
> +++ b/Documentation/arm/uefi.txt
> @@ -0,0 +1,47 @@
> +UEFI, the Unified Extensible Firmware Interface is a speifcication
> +governing the behaviours of compatible firmware interfaces. It is
> +maintained by the UEFI Forum - http://www.uefi.org/.
> +
> +Since UEFI is an evolution of its predecessor 'EFI', the terms EFI and
> +UEFI are used somewhat interchangeably in this document and associated
> +source code.
> +
> +The implementation depends on receiving the UEFI runtime memory map and a
> +pointer to the System Table in a Flattened Device Tree - so is only available
> +with CONFIG_OF.
> +
> +It parses the FDT /chosen node for the following parameters:

DT bindings should be documented in Documentation/devicetree/bindings.

I also wonder if this would be more appropriately placed in a /firmware
node.

> +- 'linux,efi-system-table':
> +  Physical address of the system table. (required)
> +  64-bit value since an ARMv7 plattform may support LPAE, and to facilitate
> +  code sharing with arm64. Top 32 bits will be ignored, since UEFI specification
> +  mandates a 1:1 mapping of all RAM.
> +- 'linux,efi-mmap':
> +  The EFI memory map as an embedded property. (required)
> +  An array of type EFI_MEMORY_DESCRIPTOR as described by the UEFI
> +  specification, current version described in Linux by efi_memory_desc_t.

Is that too complex to describe here?

> +  The memory map is represented in little-endian, not DT, byte order.
> +  This map needs to contain at least the regions to be preserved for runtime
> +  services, but would normally just be the map retreieved by calling UEFI
> +  GetMemoryMap() immediately before ExitBootServices().
> +- 'linux,efi-mmap-desc-size':
> +  Size of each descriptor in the memory map. (override default)

32-bit value?

> +- 'linux,efi-mmap-desc-ver':
> +  Memory descriptor format version. (override default)

String? Number?

Are these all generated by UEFI at runtime or could they be statically
set in a platform's DTB?

How would other OS's get this information? Is this really linux specific?

Rob

> +
> +It also depends on early_memremap() to parse the UEFI configuration tables.
> +
> +For actually enabling [U]EFI support, enable:
> +- CONFIG_EFI=y
> +- CONFIG_EFI_VARS=y or m
> +
> +After the kernel has mapped the required regions into its address space,
> +a SetVirtualAddressMap() call is made into UEFI in order to update
> +relocations. This call must be performed with all the code in a 1:1
> +mapping. This implementation achieves this by temporarily disabling the
> +MMU for the duration of this call. This can only be done safely:
> +- before secondary CPUs are brought online.
> +- after early_initcalls have completed, since it uses setup_mm_for_reboot().
> +
> +For verbose debug messages, specify 'uefi_debug' on the kernel command
> +line.
> 

Re: [PATCH v2 1/3] Documentation: arm: add UEFI support documentation

[Leif Lindholm]

On Thu, Oct 03, 2013 at 11:11:18AM -0500, Rob Herring wrote:
> Adding devicetree list since you are defining bindings...
> 
> > +with CONFIG_OF.
> > +
> > +It parses the FDT /chosen node for the following parameters:
> 
> DT bindings should be documented in Documentation/devicetree/bindings.
> 
> I also wonder if this would be more appropriately placed in a /firmware
> node.

This is information passed to the kernel by the bootloader - not
system descriptiont - so I don't quite see why it needs different
treatment from initrd and bootargs.

Feedback on v1 was:
https://lkml.org/lkml/2013/6/26/378
and
https://lkml.org/lkml/2013/6/27/420

I don't really mind either way, but the current layout is now used
across 3 sets of kernel patches, so we need to reach some sort of
consensus. Interested parties so far: me, you, Grant, Arnd, Mark.

> > +- 'linux,efi-mmap':
> > +  The EFI memory map as an embedded property. (required)
> > +  An array of type EFI_MEMORY_DESCRIPTOR as described by the UEFI
> > +  specification, current version described in Linux by efi_memory_desc_t.
> 
> Is that too complex to describe here?
 
No, just felt a bit redundant, and also not architecture-specific.

> > +  The memory map is represented in little-endian, not DT, byte order.
> > +  This map needs to contain at least the regions to be preserved for runtime
> > +  services, but would normally just be the map retreieved by calling UEFI
> > +  GetMemoryMap() immediately before ExitBootServices().
> > +- 'linux,efi-mmap-desc-size':
> > +  Size of each descriptor in the memory map. (override default)
> 
> 32-bit value?

Value as returned by the above mentioned GetMemoryMap().
Defined in UEFI specification (and <linux/efi.h>) as 32-bit (native
int). But yes, I can be explicit.

> > +- 'linux,efi-mmap-desc-ver':
> > +  Memory descriptor format version. (override default)
> 
> String? Number?
 
Value as returned by the above mentioned GetMemoryMap().
Defined in the UEFI specification as 32-bit (uint32), not
architecture specific. And I can add that too.

> Are these all generated by UEFI at runtime or could they be statically
> set in a platform's DTB?

Generated at runtime.
This is not the platform memory map, this is the UEFI memory map,
which tells us which regions we need to preserve for runtime
services, ACPI and such.

> How would other OS's get this information? Is this really linux specific?

The way it is passed through DT is. Other operating systems might keep
boot services running for longer, and make calls into UEFI later, so
not needing to cache the data. Since boot services means the timer
interrupt is active, the ARM Linux boot protocol effectively prohibits
this.

Many of these questions are about generic UEFI mechanisms.
If they need to be documented outside the UEFI specification,
Documentation/arm is not the right place for it.

If you want, I could give a basic Documentation/uefi.txt a shot.

/
    Leif

Re: [PATCH v2 1/3] Documentation: arm: add UEFI support documentation

[Mark Rutland]

Hi Leif,

On Thu, Oct 03, 2013 at 06:18:02PM +0100, Leif Lindholm wrote:
> On Thu, Oct 03, 2013 at 11:11:18AM -0500, Rob Herring wrote:
> > Adding devicetree list since you are defining bindings...
> > 
> > > +with CONFIG_OF.
> > > +
> > > +It parses the FDT /chosen node for the following parameters:
> > 
> > DT bindings should be documented in Documentation/devicetree/bindings.
> > 
> > I also wonder if this would be more appropriately placed in a /firmware
> > node.
> 
> This is information passed to the kernel by the bootloader - not
> system descriptiont - so I don't quite see why it needs different
> treatment from initrd and bootargs.

That's somewhat debatable -- the description isn't a configuration
option (as bootargs and initrd are) so much as a description of the
firmware.

> 
> Feedback on v1 was:
> https://lkml.org/lkml/2013/6/26/378
> and
> https://lkml.org/lkml/2013/6/27/420
> 
> I don't really mind either way, but the current layout is now used
> across 3 sets of kernel patches, so we need to reach some sort of
> consensus. Interested parties so far: me, you, Grant, Arnd, Mark.
> 
> > > +- 'linux,efi-mmap':
> > > +  The EFI memory map as an embedded property. (required)
> > > +  An array of type EFI_MEMORY_DESCRIPTOR as described by the UEFI
> > > +  specification, current version described in Linux by efi_memory_desc_t.
> > 
> > Is that too complex to describe here?
>  
> No, just felt a bit redundant, and also not architecture-specific.

I'd point to the EFI spec and leave it at that. The particular encoding
is defined by EFI and is beyond the scope of this document (endianness
issues aside).

If this were a device with a single window of registers we'd just
describe the whole window and not the format of each individual register
or bit within them. I see no reason to do differently here.

As the efi-mmap is built by EFI, and is in a format defined by EFI, I'd
also drop the "linux" vendor prefix -- Linux has had no hand in defining
this property. It may make sense to have "efi" as a vendor prefix, but
perhaps others won't like that?

> 
> > > +  The memory map is represented in little-endian, not DT, byte order.
> > > +  This map needs to contain at least the regions to be preserved for runtime
> > > +  services, but would normally just be the map retreieved by calling UEFI
> > > +  GetMemoryMap() immediately before ExitBootServices().
> > > +- 'linux,efi-mmap-desc-size':
> > > +  Size of each descriptor in the memory map. (override default)
> > 
> > 32-bit value?
> 
> Value as returned by the above mentioned GetMemoryMap().
> Defined in UEFI specification (and <linux/efi.h>) as 32-bit (native
> int). But yes, I can be explicit.

Please do. Something like:

- efi-mmap-desc-size:
  A single (u32) cell describing the size of each descriptor in the
  memory map, if not the EFI default size of $EFI_MMAP_DESC_SIZE. See
  $EFI_DOCUMENTATION for more information.
  
> 
> > > +- 'linux,efi-mmap-desc-ver':
> > > +  Memory descriptor format version. (override default)
> > 
> > String? Number?
>  
> Value as returned by the above mentioned GetMemoryMap().
> Defined in the UEFI specification as 32-bit (uint32), not
> architecture specific. And I can add that too.

How about something like:

- efi-mmap-desc-version:
  A single (u32) cell describing the memory descriptor format version, 
  if not 1 (the current EFI version). See $EFI_DOCUMENTATION for more
  information.

> 
> > Are these all generated by UEFI at runtime or could they be statically
> > set in a platform's DTB?
> 
> Generated at runtime.
> This is not the platform memory map, this is the UEFI memory map,
> which tells us which regions we need to preserve for runtime
> services, ACPI and such.
> 
> > How would other OS's get this information? Is this really linux specific?
> 
> The way it is passed through DT is. Other operating systems might keep
> boot services running for longer, and make calls into UEFI later, so
> not needing to cache the data. Since boot services means the timer
> interrupt is active, the ARM Linux boot protocol effectively prohibits
> this.

I suspect other OSs that may use DT are likely to have similar
requirements, or could at least cope with this mechanism.

I think before we can take any code in this area we need to define the
boot protocol (i.e. do we use DT to describe EFI & ACPI, what gets
described where) for EFI and/or ACPI. We have enough of a mess as it is,
and we need to carefully control anything we add to the fray. We should
discuss this at the upcoming LinuxCon, ELC, and Linaro Connect.

Thanks,
Mark.

>
> Many of these questions are about generic UEFI mechanisms.
> If they need to be documented outside the UEFI specification,
> Documentation/arm is not the right place for it.
> 
> If you want, I could give a basic Documentation/uefi.txt a shot.
> 
> /
>     Leif
> --
> To unsubscribe from this list: send the line "unsubscribe devicetree" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>