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.
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.
+ * - `EFI_RUNTIME_SERVICES`
+ - All functions defined as runtime services must exist.
+ Methods for unsupported or unimplemented behavour must return an appropriate error code.
+ * - `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
+ * - `EFI_DEVICE_PATH_UTILITIES_PROTOCOL`
+ - Interface for creating and manipulating UEFI device paths
+
+.. list-table:: Notible Omissions from UEFI section 2.6.1
+ :header-rows: 1
+
+ * - Element
+ - Note
+ * - EFI_DECOMPRESS_PROTOCOL
+ - Native EFI Decompression is rarely used and therefore not required.
+
+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.
+
+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.
+ * - `EFI_HII_CONFIG_ROUTING_PROTOCOL`
+ - UEFI requires this for console devices, but it is rarely necessary in practice.
+ Therefore this protocol is not requried.
+ * - 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
+ * - 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
+
+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
+ * - `OsIndications`
+ - Method for OS to request features from firmware
+ * - `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
--
2.20.1
Hi all,
Next EBBR biweekly is on Monday at 16:00 GMT. Dial-in details are below.
Below is the agenda I have so far. I've carried over the items that we
did not have time to discuss last week.
Agenda:
- Initrd passing
- Revised UEFI requirements (patch on mailing list)
- UpdateCapsule()
- other business
Please email if you want to add anything to the agenda
Cheers,
g.
----
Topic: EBBR Biweekly
Time: 1 Feb 2021, 16:00-17:00 GMT
Join Zoom Meeting
https://armltd.zoom.us/j/92081365511?pwd=SFZpRitXUEp3Zy9GM0h3UUZ1b1pnUT09
Meeting ID: 920 8136 5511
Passcode: 490324
One tap mobile
+14086380968,,92081365511#,,,,*490324# US (San Jose)
+16465189805,,92081365511#,,,,*490324# US (New York)
Dial by your location
+1 408 638 0968 US (San Jose)
+1 646 518 9805 US (New York)
+1 346 248 7799 US (Houston)
Meeting ID: 920 8136 5511
Passcode: 490324
Find your local number: https://armltd.zoom.us/u/aelJgr9ZAW
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
All,
I hope we have finally settled on a standing meeting time for the DT Evo
call. We will have the call every other Monday alternating with EBBR in
the same time slot. If I have done the TZ math correctly this is 16:00
UTC, and 11 AM US Eastern, 8AM US Pacific.
I have sent a google calendar invite to all those listed on the previous
call. If you would like to be added to that please email me directly at
bill.mills(a)linaro.org
Topic: Devicetree Evolution
Time: Jan 25, 2021 11:00 AM Eastern Time (US and Canada)
Every 2 weeks on Mon
(Alternates with EBBR meeting in same time slot)
Join Zoom Meeting
https://linaro-org.zoom.us/j/96170428801?pwd=elBJNFdVMFJub0UzanFUcVQxTHBqdz…
Meeting ID: 961 7042 8801
Passcode: 8250
One tap mobile
+13017158592,,96170428801# US (Washington D.C)
+16465588656,,96170428801# US (New York)
Dial by your location
+1 301 715 8592 US (Washington D.C)
888 788 0099 US Toll-free
877 853 5247 US Toll-free
+44 203 481 5237 United Kingdom
0 800 031 5717 United Kingdom Toll-free
Meeting ID: 961 7042 8801
Find your local number: https://linaro-org.zoom.us/u/acQEZ30MEP
--
Bill Mills
Principal Technical Consultant, Linaro
+1-240-643-0836
TZ: US Eastern
Work Schedule: Tues/Wed/Thur
Hi
I assume this needs to be analyzed from System Device Tree perspective:
https://trustedfirmware-a.readthedocs.io/en/latest/components/psa-ffa-manif…
And this is to be included in the DT Technical Report.
Cheers
FF
--
François-Frédéric Ozog | *Director Linaro Edge & Fog Computing Group*
T: +33.67221.6485
francois.ozog(a)linaro.org | Skype: ffozog
Hi everyone.
I have to do this, but I have another unexpected conflict for the EBBR biweekly on the 14th.
Rather than cancelling outright, does anyone else want to chair the meeting? The major planned orientatio item on the agenda was to talk about EBBR testing, with Heinrich sharing what he is currently doing.
If I don't hear anything by about 1pm GMT tomorrow then I'll just cancel. Our next meeting will be in January as I believe most of us will already be on Christmas holiday on the 21st
g.
Get Outlook for Android<https://aka.ms/ghei36>
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
EFI_UPDATE_CAPSULE is the industry standard method for applying firmware
updates. Make it a requirement in EBBR so that fwupd, Windows Update,
and any other generic firmware update service can support EBBR platforms.
This is made required because the ability to update firmware is a
critical part of building secure platforms.
Fixes: #69
Signed-off-by: Grant Likely <grant.likely(a)arm.com>
---
source/chapter2-uefi.rst | 32 +++++++++++++++++++++++++++++++-
1 file changed, 31 insertions(+), 1 deletion(-)
diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst
index 7b5eb24..b1182a8 100644
--- a/source/chapter2-uefi.rst
+++ b/source/chapter2-uefi.rst
@@ -167,7 +167,10 @@ are required to be implemented during boot services and runtime services.
EFI_SET_VARIABLE Required Optional
EFI_GET_NEXT_HIGH_MONO_COUNT N/A Optional
EFI_RESET_SYSTEM Required Optional
- EFI_UPDATE_CAPSULE Optional Optional
+ EFI_UPDATE_CAPSULE Required Optional
+ for in-band
+ firmware
+ update
EFI_QUERY_CAPSULE_CAPABILITIES Optional Optional
EFI_QUERY_VARIABLE_INFO Optional Optional
============================== ============= ================
@@ -243,6 +246,25 @@ Even when SetVariable() is not supported during runtime services, firmware
should cache variable names and values in EfiRuntimeServicesData memory so
that GetVariable() and GetNextVeriableName() can behave as specified.
+Firmware Update
+---------------
+
+Being able to update firmware to address security issues is a key feature of secure platforms.
+EBBR platforms are required to implement either an in-band or an out-of-band firmware update mechanism.
+
+If firmware update is performed in-band (firmware on the application processor updates itself),
+then the firmware shall implement EFI_UPDATE_CAPSULE and accept updates in the
+"Firmware Management Protocol Data Capsule Structure" format as described in [UEFI]_ § 23.3,
+"Delivering Capsules Containing Updates to Firmware Management Protocol. [#FMPNote]_
+Firmware is also required to provide an EFI System Resource Table (ESRT). [UEFI]_ § 23.4
+Every firmware image that is updated in-band must be described in the ESRT.
+
+If firmware update is performed out-of-band (e.g., by an independent Board Management Controller,
+or firmware is provided by a hypervisor), then the platform is not required to implement EFI_UPDATE_CAPSULE.
+
+EFI_UPDATE_CAPSULE is only required before ExitBootServices() is called.
+
+
.. [#OPTEESupplicant] It is worth noting that OP-TEE has a similar problem
regarding secure storage.
OP-TEE's chosen solution is to rely on an OS supplicant agent to perform
@@ -253,3 +275,11 @@ that GetVariable() and GetNextVeriableName() can behave as specified.
during runtime services.
https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
+
+.. [#FMPNote] The `EFI_UPDATE_CAPSULE` implementation is expected to be suitable
+ for use by generic firmware update services like fwupd and Windows Update.
+ Both fwupd and Windows Update read the ESRT table to determine what firmware
+ can be updated, and use an EFI helper application to call `EFI_UPDATE_CAPSULE`
+ before ExitBootServices() is called.
+
+ https://fwupd.org/
--
2.20.1
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
Hi,
I thought perhaps it might be worth starting a thread on this, as
despite Grant and Heinrich kinding spending a bit of time talking
about this, I am still very much in the dark about how 'embedded' and
distro/other boot flows are going to come together with EBBR. Of
course this would be easier f2f.
Case 1:
Firmware loads the kernel to a particular address, selects DT and
boots it. The kernel may require EFI boot services, or may not, but in
the general case the firmware provides them.
Case 2:
Firmware loads EFI app and provides EFI boot services to it. How the
system actually boots is under control of the app.
I feel that a lot of the confusion about verified boot, DT selections,
boot menus, etc. is coming from the introduction of an EFI app which
has no specification (it can be grub, shim or something else, as I
understand it). Certainly this is very flexible and future-proof, but
it is also arbitrarily complex, unpredictable and hard to secure.
I am wondering if we can come up with a way to deterministically
specify how a system will boot and how to make it boot a different way
(i.e. with a different kernel, initrd, DT).
Heinrich mentioned EFI variables as a way of selecting
kernel/initrd/DT. Then the problem becomes just a case of being able
to change those variables from Linux userspace. Is that right?
We are talking about having a 'secure' part of EBBR, which allows for
secure boot. Should we have a 'defined boot' part of EBBR, that
defines how the kernel/DT/initrd are selected, based on EFI variables?
Unfortunately I just don't know enough about all the different boot
flows used by the different distros. It seems like crazy town. Does
anyone have some pointers so I can do some study?
Regards,
SImon
All,
On the Devicetree evolution call Wednesday I promised to finish my
comparison of u-boot DT vs kernel DT.
The script is not perfect but the results are still interesting.
For each dts and dtsi file in the tip of the u-boot tree, it tries to
correlate it to the kernel tip.
It compares git SHA1 signatures or falls back to filenames.
The results were surprising to me but perhaps they should not have been.
I have checked in the script[1] and the full results here [2]
The full file lists (with some diff stats) are in the root dir.
Example [3]
I also looked at the line count of the u-boot override files.
Even though we don't expect these to correlate, we do expect reasonable
usage to result in small files. Big files are an indication of possible
abuse of the system. (I don't think the idea was to have wholesale new
versions of the DTS as an override.)
I plan to redo the script in python. It will be much easier to be more
precise and to look deeper. (For example figure out how old the u-boot
version is in number of change sets and number of days. Or if no
content sync now were they ever synced?)
Here is the scripts output: (from summary.txt)
Devicetree sync status for u-boot v2021.01-rc5-7-gb8c725e736
Compared to kernel v5.11-rc2-156-g71c061d24438
14% (255) are completely synced
253 arm
2 riscv
0 mips
0 powerpc
0 x86
0 68k
0 microblaze
0 sh
0 arc
23% (416) content has appeared in the kernel but is not up to date
411 arm
0 riscv
1 mips
0 powerpc
1 x86
0 68k
0 microblaze
0 sh
1 arc
33% (584) filename appears in kernel but content never has
467 arm
1 riscv
12 mips
91 powerpc
0 x86
0 68k
0 microblaze
0 sh
8 arc
28% (510) neither filename nor content appears in kernel
305 arm
4 riscv
48 mips
35 powerpc
44 x86
0 68k
1 microblaze
1 sh
6 arc
n/a (510) U-Boot specific, no correlation expected
7 sandbox
358 override
211 test
histogram of override size (in raw lines)
10 61
20 53
30 38
40 33
50 23
60 14
70 12
80 7
90 5
100 4
110 4
120 5
130 6
140 4
150 0
160 2
170 0
180 0
190 4
200 0
210 2
220 2
230 1
240 2
250 1
260 1
270 1
280 0
290 0
300 0
310 0
320 1
[1]
https://github.com/wmamills/devicetree-source/blob/master/scripts/correlate…
[2] https://github.com/wmamills/devicetree-source
[3]
https://github.com/wmamills/devicetree-source/blob/master/dts-somewhere.txt
--
Bill Mills
Principal Technical Consultant, Linaro
+1-240-643-0836
TZ: US Eastern
Work Schedule: Tues/Wed/Thur
Hello,
Thanks to all that have participated in the doodle poll. We don't yet
have all key stakeholders so please add your info if you have not.
As expected there is no perfect time but the current leader is
Wednesdays at 4PM UK, 11 AM US Eastern.
I have scheduled a meeting for tomorrow as this first one.
Possible topics for tomorrow include:
* More Conformance testing of DT source
* Keeping multiple DT projects in sync (w/o moving the DT source)
* DT overlay source in the kernel source tree (for bootloader applied
overlays)
If we stay with Wednesdays the meeting after this one would be Jan 27.
(Wednesdays require working around Linaro TSC calls)
Thanks,
Bill
***
Bill Mills is inviting you to a scheduled Zoom meeting.
Topic: DT Evolution
Time: Jan 6, 2021 04:00 PM London
Join Zoom Meeting
https://linaro-org.zoom.us/j/94413146152?pwd=NEs1Ym1xbnRBS0U4ZWNsaXFzbm1Ndz…
Meeting ID: 944 1314 6152
Passcode: 8250
One tap mobile
+13017158592,,94413146152# US (Washington D.C)
+13126266799,,94413146152# US (Chicago)
Dial by your location
+1 301 715 8592 US (Washington D.C)
+1 312 626 6799 US (Chicago)
+1 646 558 8656 US (New York)
+1 669 900 9128 US (San Jose)
+1 253 215 8782 US (Tacoma)
+1 346 248 7799 US (Houston)
877 853 5247 US Toll-free
888 788 0099 US Toll-free
Meeting ID: 944 1314 6152
Find your local number: https://linaro-org.zoom.us/u/aesZr3aPDG
--
Bill Mills
Principal Technical Consultant, Linaro
+1-240-643-0836
TZ: US Eastern
Work Schedule: Tues/Wed/Thur
Hi,
As I am thinking about conformance testing for SystemReady and Trusted
Substrate, I'd like to get your feedback on the following.
There are 7 values in the reg entry of interrupt-controller@210000 from the
below DT. This corresponds to 3 valid {address,size} plus a single
{address}.
The spec does not state anything on incomplete {address,size} pairs... I
understand that #size-cell can be zero, indicating that the reg will
contain only {address} "tuples" and not {address,size} tuples. But that
should be for all reg tuples, not just one.
In this case, I assume the driver will get what it wants, but from a
certification perspective:
- I would reject this DT.
- I would document proper tuple forming in the spec (no incomplete pairs)
Last, I would also add some "notes" in the spec about where to get the
"#*-cells" for the reg property of a device. If you think "hardware" it is
obvious that the information must be retrieved from the immediate parent
and "inheritance" does not make sense. But as I Googled the topic, I have
seen a number of discussions and wrong patches around that. So I would add
a non normative text (properly identified as such) to describe that in the
spec.
Thank you for your help
Cheers
FF
config-space@f0000000 {
#address-cells = <0x01>;
#size-cells = <0x01>;
compatible = "simple-bus";
ranges = <0x00 0x00 0xf0000000 0x1000000>;
interrupt-controller@210000 {
compatible = "arm,gic-400";
#interrupt-cells = <0x03>;
#address-cells = <0x01>;
#size-cells = <0x01>;
ranges;
interrupt-controller;
interrupts = <0x01 0x09 0xf04>;
reg = <0x210000 0x10000 0x220000 0x20000 0x240000 0 0x20000>;
phandle = <0x01>;
v2m@280000 {
compatible = "arm,gic-v2m-frame";
msi-controller;
reg = <0x280000 0x1000>;
arm,msi-base-spi = <0xa0>;
arm,msi-num-spis = <0x20>;
phandle = <0x03>;
};
--
François-Frédéric Ozog | *Director Linaro Edge & Fog Computing Group*
T: +33.67221.6485
francois.ozog(a)linaro.org | Skype: ffozog
