[PATCH] doc: Add UEFI supplement document

[Jiaxun Yang]

在2024年6月7日六月 下午7:11，Heinrich Schuchardt写道：
[...]
>
> 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.

Hi Heinrich,

As per discussion made at [1] it can be next generation of U-Boot's
API facing to bare-metal software.

I admit it's more or less an academic endeavour to me, but isn't
U-Boot a great place for such thing? Do we have to be bound by
commercial interest?

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

Everything is working well, so nobody is willing to touch them.

>
> 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?

Some architectures are dead in commercial point of view (m68k, xtensa)
etc, so I think nobody is going to represent them in commercial world.
Loongson tried to push UEFI spec for MIPS to UEFI forum a couple of years
ago but was trapped by a good deal of commercial stuff. Now they
lost interest on it.

>
> 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?

Yes, from Loongson, in Chinese.
But I'd like to make a cross-arch document to help with other ports.

>
>> +
>> +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.

I think it's only the case of RISC-V and AArch64 to have multiple privilege
levels. MIPS, m68k, xtensa, power, nios2 all have only one level for kernel.
But I'm happy to add some architecture specific wording here.

>
>> +
>> +- 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.

Yes there is no such usage so far, but Big Endian is still widely used
in network devices (cavium octeon, even aarch64_be from ZXIC etc) and I don't want
to left it over.

>
>> +
>> +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?

Not for MIPS, but we don't have onr for m68k and xtensa.

>
>> +
>> +- **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?

There is no such usage so far, but I noticed that for m68k "MZ" is not a valid
stub opcode, it might be a problem for EFISTUB kernel. Thus I came up with this
idea.

But it can be worked out if we define another booting header format for m68k.

What's your opinion?

>
> 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.

Yes, I had a glance on the specification and noticed that issue, so I
write it here in case we are going to support them in future.

>
> 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,

[1]: https://lore.kernel.org/u-boot/CAC_iWjLbY6+FaUYQw2Zv5y5byCnXRHxfzvrFf1dMyJX+ANP9VQ@mail.gmail.com/
Thanks
-- 
- Jiaxun