[PATCH] doc: Add UEFI supplement document
Add UEFI supplement document to define some behaviours on architectures not covered by the original specification.
Signed-off-by: Jiaxun Yang jiaxun.yang@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+... --- 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@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,
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@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+...
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@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,
在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+... Thanks
participants (2)
-
Heinrich Schuchardt -
Jiaxun Yang