[PATCH] doc: Add UEFI supplement document

Fri Jun 7 20:11:46 CEST 2024

On 29.05.24 15:36, Jiaxun Yang wrote:
> Add UEFI supplement document to define some behaviours
> on architectures not covered by the original specification.
>
> Signed-off-by: Jiaxun Yang <jiaxun.yang at flygoat.com>
> ---
> Hi all,
>
> This document is in response to discussion at [1]. It is produced
> based on my attempt to port U-Boot UEFI to MIPS and Xtensa. I also
> plan to try m68k.
>
> Please review
>
> Thanks
> [1]: https://lore.kernel.org/u-boot/CAC_iWjLbY6+FaUYQw2Zv5y5byCnXRHxfzvrFf1dMyJX+ANP9VQ@mail.gmail.com/
> ---
>   doc/develop/uefi/index.rst           |  1 +
>   doc/develop/uefi/uefi_supplement.rst | 73 ++++++++++++++++++++++++++++++++++++
>   2 files changed, 74 insertions(+)
>
> diff --git a/doc/develop/uefi/index.rst b/doc/develop/uefi/index.rst
> index e26b1fbe05c5..a274fff88754 100644
> --- a/doc/develop/uefi/index.rst
> +++ b/doc/develop/uefi/index.rst
> @@ -11,6 +11,7 @@ can be run an UEFI payload.
>      :maxdepth: 2
>
>      uefi.rst
> +   uefi_supplement.rst
>      u-boot_on_efi.rst
>      iscsi.rst
>      fwu_updates.rst
> diff --git a/doc/develop/uefi/uefi_supplement.rst b/doc/develop/uefi/uefi_supplement.rst
> new file mode 100644
> index 000000000000..cb20cd290912
> --- /dev/null
> +++ b/doc/develop/uefi/uefi_supplement.rst
> @@ -0,0 +1,73 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (c) 2024 Jiaxun Yang <jiaxun.yang at flygoat.com>
> +
> +U-Boot Supplement to UEFI Specifications
> +========================================
> +
> +Motivation
> +----------
> +
> +The UEFI specifications are designed to be platform-independent, enabling the
> +implementation of UEFI-like API support across various architectures. However,
> +some platform-dependent aspects and constraints remain. This document provides
> +a supplement to the UEFI specifications for U-Boot, clarifying these platform
> +dependent details for architectures not covered by the original specifications.

This does not explain why we should bother about any non-UEFI
architecture. It does not list relevant architectures and does not
provide any evidence that this more than an academic endeavor.

All git repositories you mentioned in you MIPS series have not seen any
update in the last four years.

If any company were sincerely interested in using UEFI on such
architectures, wouldn't they contribute to the specification like has
been done for LoongArch and RISC-V?

It does not make sense to define UEFI for non-UEFI architectures in
U-Boot. Isn't there any existing documentation for UEFI on MIPS?

> +
> +Architectural Conventions
> +-------------------------
> +
> +The UEFI specifications cover IA32, X64, ARM, AARCH64, RISC-V, LoongArch, and

There is only one UEFI specification.

%s/specifications cover/specification covers/

> +Itanium architectures. This document extends the UEFI specifications to include
> +all architectures supported by U-Boot.
> +
> +The following conventions are used for these architectures:
> +
> +- For architectures with multiple ABIs, we adhere to the calling conventions
> +  used by the Linux kernel for the same architecture.
> +
> +- Optional CPU registers (floating-point, SIMD) are excluded from calling
> +  conventions. However, the UEFI payload should be able to utilize them if
> +  available.
> +
> +- Control is handed over to the UEFI payload at the privilege level used
> +  by the Linux kernel for the same architecture.

This does not provide enough detail. The Linux kernel can run at
different privilege levels on the same architecture, e.g. in S-mode or
M-mode on RISC-V.

> +
> +- Identity mapping (i.e., VA == PA mapping) is preferred for UEFI. However,
> +  this may not be possible for some architectures. In such cases, if the
> +  processor supports a default linear translation, it should be used.
> +
> +- Endianness: UEFI specifications enforce little-endian architectures.
> +  However, U-Boot supports both little-endian and big-endian architectures.
> +  For big-endian architectures, UEFI data structures should be stored in
> +  native endianness, with exceptions explicitly specified.

Why do you bother about big-endian systems? MIPS supports low-endian.
Linux distros like Debian have dropped big-endian MIPS support.

If found https://www.ventoy.net/en/doc_mips64el.html (MIPS64EL UEFI) but
nothing describing big-endian usage of UEFI.

> +
> +UEFI Images
> +-----------
> +
> +The UEFI specifications define the PE/COFF image format for UEFI applications.
> +U-Boot extends this format as follows:

The UEFI specification does not define the PE/COFF image format. It
prescribes its usage.

> +
> +- **PE32+ Machine Type**: UEFI specifications define machine types for supported
> +  architectures. For machines not covered by UEFI specifications, we use the
> +  machine type defined by the Microsoft PE/COFF specification if possible.
> +  Otherwise, we use the ``IMAGE_FILE_MACHINE_UNKNOWN`` (0) machine type.
> +  U-Boot should always accept ``IMAGE_FILE_MACHINE_UNKNOWN`` as a valid
> +  machine type.

We should not accept IMAGE_FILE_MACHINE_UNKNOWN on an architecture that
has a machine type defined in the PE-COFF specification.

Which MIPS machine type are you missing?

> +
> +- **Header Endianness**: PE/COFF header data fields are always stored as
> +  little-endian, regardless of the target architecture's endianness.
> +
> +- **DOS Stub**: To accommodate various boot image formats, we relax the requirement
> +  for a DOS stub in the UEFI image. U-Boot should accept UEFI images without a DOS
> +  stub and MZ signature. However, U-Boot still expects the PE/COFF header at the
> +  file offset specified at offset 0x3C.

Why would anybody create such an invalid file and expect it to be
interpreted as EFI?

Shouldn't you fix the software creating such invalid files?

This topic is related to the question of which specification has been
used to create UEFI implementations like
https://github.com/kontais/EFI-MIPS.

> +
> +I/O Device Access
> +-----------------
> +
> +UEFI specifications define the EFI_DEVICE_IO_PROTOCOL and EFI_PCI_IO_PROTOCOL
> +for accessing I/O devices. U-Boot extends these specifications as follows:

These protocols are not used in U-Boot, yet.

Best regards

Heinrich

> +
> +- All I/O access is performed using the CPU's native endianness.
> +  For big-endian architectures, U-Boot should convert data to/from little-endian
> +  before/after accessing I/O devices.
>
> ---
> base-commit: 46ff00bea5dd2dd247d5e2fdadbf5dcf8653cd9a
> change-id: 20240529-efi-spec-0ea657985272
>
> Best regards,