Re: [PATCH] Override UEFI section 2.6 requirements

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.

source/chapter2-uefi.rst | 155 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 152 insertions(+), 3 deletions(-)

diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst index aab1c2c..5864a17 100644 --- 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

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

• • • `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/ ?

• :header-rows: 1
• • • Element

• - Note
  

• • • EFI_DECOMPRESS_PROTOCOL

• - Native EFI Decompression is rarely used and therefore not required.
  

%s/Decompression/decompression/ ?

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

+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
  

ditto

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

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

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

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