| Message ID | 1380799481-5470-2-git-send-email-leif.lindholm@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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. >
Hi Leif, On Thu, Oct 03, 2013 at 12:24:39PM +0100, 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: > +- 'linux,efi-system-table': > + Physical address of the system table. (required) > + 64-bit value since an ARMv7 plattform may support LPAE, and to facilitate s/plattform/platform/ > + code sharing with arm64. Top 32 bits will be ignored, since UEFI specification > + mandates a 1:1 mapping of all RAM. You could use something like #size-cells to describe how big this is going to be. Is this Linux-specific -- it looks like something provided by EFI rather than the kernel itself. > +- '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. > + 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(). This is a little scary. If the format is so complicated, should it really be embedded? How big is this likely to be? Given that this is in a format defined externally, this isn't really Linux-specific. Maybe we need an "efi" pseudo-vendor prefix. > +- 'linux,efi-mmap-desc-size': > + Size of each descriptor in the memory map. (override default) What units is this in? How many u32 cells does this take up (one presumably)? > +- 'linux,efi-mmap-desc-ver': > + Memory descriptor format version. (override default) Type, format, valid values and their meaning? Thanks, Mark. > + > +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. > -- > 1.7.10.4 > > `> _______________________________________________ > linux-arm-kernel mailing list > linux-arm-kernel@lists.infradead.org > http://lists.infradead.org/mailman/listinfo/linux-arm-kernel >
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
On Thu, Oct 03, 2013 at 06:10:54PM +0100, Mark Rutland wrote: > > +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: > > +- 'linux,efi-system-table': > > + Physical address of the system table. (required) > > + 64-bit value since an ARMv7 plattform may support LPAE, and to facilitate > > s/plattform/platform/ Indeed, thanks. > > + code sharing with arm64. Top 32 bits will be ignored, since UEFI specification > > + mandates a 1:1 mapping of all RAM. > > You could use something like #size-cells to describe how big this is > going to be. Is this Linux-specific -- it looks like something provided > by EFI rather than the kernel itself. Provided by the bootloader, which may be the kernel's UEFI stub, or something else (like GRUB). Extracted from UEFI by stub (or other loader) which executes as a UEFI application. > > +- '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. > > + 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(). > > This is a little scary. If the format is so complicated, should it > really be embedded? How big is this likely to be? With current format, and it has yet to be extended beyond v1, it is 40 bytes per entry. Number of entries will vary depending on how many regions are allocated in UEFI (1 entry per region). I have heard of some x86 systems with 128 or more regions, but my devboards have more like 16, and my desktop ~60. Having it embedded in the DT means the data passed by the bootloader to the kernel is automatically kept together (for kexec or such). Not vital, but nice. > Given that this is in a format defined externally, this isn't really > Linux-specific. Maybe we need an "efi" pseudo-vendor prefix. A discussion for the other thread. > > +- 'linux,efi-mmap-desc-size': > > + Size of each descriptor in the memory map. (override default) > > What units is this in? How many u32 cells does this take up (one > presumably)? Value as returned by UEFI GetMemoryMap() boot service call. Yes, one for ARM. > > +- 'linux,efi-mmap-desc-ver': > > + Memory descriptor format version. (override default) > > Type, format, valid values and their meaning? Meaning defined by UEFI specification, currently providing the only valid value as 1. 32-bit uint. / Leif
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@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html >
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: +- '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. + 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) +- 'linux,efi-mmap-desc-ver': + Memory descriptor format version. (override default) + +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.