Add details of UEFI interaction with /memory and /reserved-memory

Output from discussion on EBBR issue:
ARM-software/ebbr#52

When using the UEFI ABI for booting, the DT memory map is ignored and
instead UEFI GetMemoryMap() is used to find system memory. Also, regions
described in /reserved-memory need to also be added to the UEFI memory
map to protect against overlapping allocations. The patch adds language
to cover both of those cases.

Signed-off-by: Grant Likely <[email protected]>
Cc: Heinrich Schuchardt <[email protected]>
Cc: Ard Biesheuvel <[email protected]>
Reviewed-by: Etienne Carriere <[email protected]>

source/chapter3-devicenodes.rst

@@ -160,6 +160,12 @@ If the VLE storage attribute is supported, with VLE=0.
 .. note:: All other standard properties
    (:numref:`sect-standard-properties`) are allowed but are optional.
 
+``/memory`` node and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When booting via [UEFI]_, the system memory map is obtained via the
+GetMemoryMap() UEFI boot time service as defined in [UEFI]_ § 7.2,
+and if present, the OS must ignore any ``/memory`` nodes.
 
 ``/memory`` Examples
 ~~~~~~~~~~~~~~~~~~~~
@@ -205,8 +211,8 @@ address and length for the ``reg`` property of the memory node.
 -------------------------
 
 Reserved memory is specified as a node under the ``/reserved-memory`` node.
-The operating system shall exclude reserved memory from normal usage
-one can create child nodes describing particular reserved (excluded from
+The operating system shall exclude reserved memory from normal usage.
+One can create child nodes describing particular reserved (excluded from
 normal use) memory regions.
 Such memory regions are usually designed for the special usage by various
 device drivers.
@@ -341,13 +347,30 @@ nodes by adding a ``memory-region`` property to the device node.
    Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
    =======================================================================================================
 
+.. _sect-reserved-memory-uefi:
+
+``/reserved-memory`` and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When booting via [UEFI]_, static ``/reserved-memory`` regions must
+also be listed in the system memory map obtained via the GetMemoryMap()
+UEFI boot time service as defined in [UEFI]_ § 7.2.
+The reserved memory regions need to be included in the UEFI memory map to
+protect against allocations by UEFI applications.
+
+Reserved regions with the ``no-map`` property must be listed in the memory
+map with type ``EfiReservedMemoryType``.
+All other reserved regions must be listed with type ``EfiBootServicesData``.
+
+Dynamic reserved memory regions must not be listed in the [UEFI]_ memory map
+because they are allocated by the OS after exiting firmware boot services.
+
 ``/reserved-memory`` Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This example defines 3 contiguous regions are defined for Linux kernel:
-one default of all device drivers (named ``linux,cma@72000000`` and 64MiB in size),
+one default of all device drivers (named ``linux,cma`` and 64MiB in size),
 one dedicated to the framebuffer device (named ``framebuffer@78000000``, 8MiB), and
-one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB).
+one for multimedia processing (named ``multimedia@77000000``, 64MiB).
 
 .. code-block:: dts
 

source/chapter5-flattened-format.rst

@@ -234,6 +234,16 @@ reservation block as a whole, shall be located at an 8-byte aligned
 offset from the beginning of the devicetree blob (see
 :numref:`sect-fdt-alignment`).
 
+Memory Reservation Block and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As with the ``/reserved-memory`` node (:numref:`sect-reserved-memory-uefi`),
+when booting via [UEFI]_ entries in the Memory Reservation Block must also be
+listed in the system memory map obtained via the GetMemoryMap() to protect against
+allocations by UEFI applications.
+The memory reservation block entries should be listed with type
+``EfiReservedMemoryType``.
+
 .. _sect-fdt-structure-block:
 
 Structure Block

source/references.rst

@@ -23,3 +23,7 @@
 .. [EPAPR] *Power.org Standard for Embedded Power Architecture
    Platform Requirements*, power.org, 2011,
    https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/
+
+.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A
+   <https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_,
+   February 2020, `UEFI Forum <http://www.uefi.org>`_