[PATCH] doc: Add UEFI supplement document

[Jiaxun Yang]

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.
+
+Architectural Conventions
+-------------------------
+
+The UEFI specifications cover IA32, X64, ARM, AARCH64, RISC-V, LoongArch, and
+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.
+
+- 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.
+
+UEFI Images
+-----------
+
+The UEFI specifications define the PE/COFF image format for UEFI applications.
+U-Boot extends this format as follows:
+
+- **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.
+
+- **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.
+
+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:
+
+- 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,
-- 
Jiaxun Yang <jiaxun.yang at flygoat.com>