On 2/1/21 8:56 PM, Grant Likely wrote:
On 29/01/2021 20:17, Heinrich Schuchardt wrote:
On 1/29/21 8:21 PM, Grant Likely wrote:
EBBR only requires a subset of UEFI. Provide a replacement for the UEFI section that lists base requirements.
Fixes: #60 Fixes: #61 Fixes: #64
This is my first complete draft itemizing the specific UEFI requirements for EBBR. Please review and comment.
Cheers, g.
Dear Grant,
thanks for putting this into the spec.
Thanks for the feedback Heinrich. Comments below...
--- a/source/chapter2-uefi.rst +++ b/source/chapter2-uefi.rst @@ -14,8 +14,157 @@ This document uses version 2.8 Errata A of the UEFI specification [UEFI]_. UEFI Compliance ===============
-EBBR compliant platforms shall conform to the requirements in [UEFI]_ § 2.6, -except where explicit exemptions are provided by this document. +EBBR compliant platform shall conform to a subset of the [UEFI]_ spec as listed +in this section. +Normally, UEFI compliance would require full compliance with all items listed +in section 2.6 of the UEFI spec. +However, the EBBR target market has a reduced set of requirements, +and so some UEFI features are omitted as unnecessary.
+Required Elements +-----------------
+This section replaces the list of required elements in [UEFI]_ § 2.6.1. +All of the following UEFI elements are required for EBBR compliance.
+.. list-table:: UEFI Required Elements + :widths: 50 50 + :header-rows: 1
+ * - Element + - Requirement + * - `EFI_SYSTEM_TABLE` + - The system table is required to provide required to access UEFI Boot Services, + UEFI Runtime Services, consoles, and other firmware, vendor and platform + information. + * - `EFI_BOOT_SERVICES` + - All functions defined as boot services must exist. + Methods for unsupported or unimplemented behavour must return an appropriate error code.
%s/behavour/behavior/g
+ * - `EFI_RUNTIME_SERVICES` + - All functions defined as runtime services must exist. + Methods for unsupported or unimplemented behavour must return an appropriate error code.
ditto
done
+ * - `EFI_LOADED_IMAGE_PROTOCOL` + - Must be installed for each loaded image + * - `EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL` + - Must be installed for each loaded image + * - `EFI_DEVICE_PATH_PROTOCOL` + - Interface to provide location of a device
What is the requirement? The protocol must be installed on all handles related to devices?
I don't know. What do you recommend be specified here?
An EFI_DEVICE_PATH_PROTOCOL must be installed onto all device handles provided by the firmware.
+ * - `EFI_DEVICE_PATH_UTILITIES_PROTOCOL` + - Interface for creating and manipulating UEFI device paths
+.. list-table:: Notible Omissions from UEFI section 2.6.1
%s/Omissions/omissions/ ?
fixed
+ :header-rows: 1
+ * - Element + - Note + * - EFI_DECOMPRESS_PROTOCOL + - Native EFI Decompression is rarely used and therefore not required.
%s/Decompression/decompression/ ?
fixed
+Required Platform Specific Elements +-----------------------------------
+This section replaces the list of required elements in [UEFI]_ § 2.6.2. +All of the following UEFI elements are required for EBBR compliance.
+.. list-table:: UEFI Platform-Specific Required Elements + :widths: 50 50 + :header-rows: 1
+ * - Element + - Description + * - Console devices + - The platform must have at least one console device + * - `EFI_SIMPLE_TEXT_INPUT_PROTOCOL` + - Needed for console input + * - `EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL` + - Needed for console input + * - `EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL` + - Needed for console output + * - `EFI_DEVICE_PATH_TO_TEXT_PROTOCOL` + - Needed for console output + * - `EFI_HII_STRING_PROTOCOL` + - Required by EFI shell and for compliance testing + * - `EFI_HII_DATABASE_PROTOCOL` + - Required by EFI shell and for compliance testing + * - `EFI_UNICODE_COLLATION2_PROTOCOL` + - Required by EFI shell and for compliance testing + * - `EFI_BLOCK_IO_PROTOCOL` + - Required for block device access + * - `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL` + - Required if booting from block device is supported + * - `EFI_RNG_PROTOCOL` + - Required if platform has a hardware entropy source + * - Network booting + - If the platform supports network booting via TFTP, + then `EFI_SIMPLE_NETWORK_PROTOCOL` and + `EFI_PXE_BASE_CODE_PROTOCOL` must be implemented.
TFTP booting means loading the first EFI binary via TFTP. The EFI_PXE_BASE_CODE_PROTOCOL does not help to do this. This requirement needs some clarification.
Okay, so should I then drop EFI_PXE_BASE_CODE_PROTOCOL and required something else? Can you suggest some language?
* -`EFI_SIMPLE_NETWORK_PROTOCOL` - Required for network booting if a network device is available.
+The following table is a list of notable deviations from UEFI section 2.6.2. +Many of these deviations are because the EBBR use cases do not require +interface specific UEFI protocols, and so they have been made optional.
+.. list-table:: Notible Deviations from UEFI section 2.6.2 + :widths: 50 50 + :header-rows: 1
+ * - Element + - Description of deviation + * - `EFI_HII_CONFIG_ACCESS_PROTOCOL` + - UEFI requires this for console devices, but it is rarely necessary in practice. + Therefore this protocol is not requried.
%s/requried/required/
+ * - `EFI_HII_CONFIG_ROUTING_PROTOCOL` + - UEFI requires this for console devices, but it is rarely necessary in practice. + Therefore this protocol is not requried.
ditto
+ * - Graphical console + - Platforms with a graphical device are not required to expose it as a graphical console. + * - EFI_DISK_IO_PROTOCOL + - Rarely used interface that isn't requried for EBBR use cases
* - EFI_PXE_BASE_CODE_PROTOCOL - Booting via the Preboot Execution Environment (PXE) is insecure. Loading via PXE is typically executed before launching the first UEFI application.
Best regards
Heinrich
ditto
fixed
+ * - Network protocols + - A full implementation of the UEFI general purpose networking ABIs is not required, + including `EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL`, `EFI_MANAGED_NETWORK_PROTOCOL`, + `EFI_*_SERVICE_BINDING_PROTOCOL`, or any of the IPv4 or IPv6 protocols. + * - Byte stream device support (UART) + - UEFI protocols not required + * - PCI bus support + - UEFI protocols not required + * - USB bus support + - UEFI protocols not required + * - NVMe pass through support + - UEFI protocols not required + * - SCSI pass through support + - UEFI protocols not required + * - SCSI pass through support + - UEFI protocols not required + * - `EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL` + - Not required + * - Option ROM support + - EBBR implementations are not required to support option ROM loading
I am missing a justification for ignoring option ROMs in the suggested text.
Can't we write that option ROMs are currently not available for non-x86 architectures.
All this is saying is that option ROM loading isn't required by the platform. A platform is still able to implement it if needed, but my read on the ecosystem is that supporting generic add-in boards is not a high priority. Rather native OS drivers and integration are relied on to support specific PCIe devices.
"But wait," I hear you say, "What about GPUs?". I simply don't think GPU add in board support is a significant enough use case for option ROMs to be required by EBBR. Change my mind. :-)
I've added the reasoning to the text as discussed in our meeting today. New version out shortly.
+Required Global Variables +-------------------------
+EBBR compliant platforms are required to implement the following Global +Variables as found in [UEFI]_ § 3.3.
+.. list-table:: Required UEFI Variables + :widths: 25 75 + :header-rows: 1
+ * - Variable Name + - Description + * - `Boot####` + - A boot load option. #### is a numerical hex value + * - `BootCurrent` + - The boot option that was selected for the current boot + * - `BootNext` + - The boot option that will be used for the next boot only + * - `BootOrder` + - An ordered list of boot options. + Firmware will attempt each Boot#### entry in this order
These variables except BootCurrent are not "implemented" by the platform but set by the user. The firmware provides a "boot manager".
How about: s/required to implement/required to support/
+ * - `OsIndications` + - Method for OS to request features from firmware
This variable is set by the OS and interpreted by the firmware.
Otherwise the patch looks good to me.
In a future patch we should add advice for configuration tables like the EFI System Resource Table and the Image Execution Information Table.
Yes. ESRT should be added at the same time as UpdateCapsule. I haven't looked into IEIT yet.
Best regards
Heinrich
+ * - `OsIndicationsSupported` + - Variable for firmware to indicate which features can be enabled
Block device partitioning ------------------------- @@ -148,7 +297,7 @@ are required to be implemented during boot services and runtime services. .. table:: EFI_RUNTIME_SERVICES Implementation Requirements
============================== ============= ================ - EFI_RUNTIME_SERVICES function Boot Services Runtime Services + EFI_RUNTIME_SERVICES function Before EBS() After EBS() ============================== ============= ================ EFI_GET_TIME Optional Optional EFI_SET_TIME Optional Optional