trivial: move some footnotes closer to their referrer

Some of our footnotes contents are written as close as possible to the
places referencing them, while some others are written at the end of their
chapters.
Settle on one approach (as close as possible) and harmonize all our
footnotes.

Also, add an advice for writers in the README.

Signed-off-by: Vincent Stehlé <vincent.stehle@arm.com>

README.rst

@@ -153,6 +153,8 @@ tag. Generally this means each ``.rst`` file should include the line
 .. _Sphinx: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
 In general, try to keep the text width to at most 80 columns.
+Try to write footnotes contents as close a possible to the places referencing
+them.
 
 Sphinx Extensions
 -----------------

source/chapter2-uefi.rst

@@ -210,6 +210,8 @@ When the firmware implements in-band firmware update with `UpdateCapsule()` it
 must support the following Variables to report the status of capsule "on disk"
 processing after restart as found in :UEFI:`8.5.6`. [#FWUpNote]_
 
+.. [#FWUpNote] See section :ref:`section-fw-update`.
+
 .. list-table:: UEFI Variables required for capsule update "on disk"
    :widths: 50 50
    :header-rows: 1
@@ -224,8 +226,6 @@ processing after restart as found in :UEFI:`8.5.6`. [#FWUpNote]_
    * - `CapsuleLast`
      - Variable for platform to publish the last `CapsuleNNNN` created.
 
-.. [#FWUpNote] See section :ref:`section-fw-update`.
-
 Block device partitioning
 -------------------------
 
@@ -364,6 +364,9 @@ The DTB Nodes and Properties must be compliant with the requirements listed in
 [DTSPEC]_ § 3 & 4 and with the requirements listed in the following table, which
 take precedence. [#DTSchNote]_
 
+.. [#DTSchNote] The validity of the DTB and its conformance to [DTSPEC]_ can be
+   verified automatically with the tools and schemas in [DTSCHEMA]_.
+
 .. list-table:: DTB Nodes and Properties requirements
    :widths: 50 50
    :header-rows: 1
@@ -379,9 +382,6 @@ take precedence. [#DTSchNote]_
 The DTB must be contained in memory of type `EfiACPIReclaimMemory`.
 [#ACPIMemNote]_
 
-.. [#DTSchNote] The validity of the DTB and its conformance to [DTSPEC]_ can be
-   verified automatically with the tools and schemas in [DTSCHEMA]_.
-
 .. [#ACPIMemNote] `EfiACPIReclaimMemory` was chosen to match the recommendation
    for ACPI tables which fulfill the same task as the DTB.
 
@@ -567,6 +567,17 @@ collide with transactions initiated by the OS.
 Neither U-Boot nor Tianocore have a generic solution for accessing or updating
 variables stored on shared media. [#OPTEESupplicant]_
 
+.. [#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
+   storage operations on behalf of OP-TEE.
+   The same solution may be applicable to solving the UEFI non-volatile
+   variable problem, but it requires additional OS support to work.
+   Regardless, EBBR compliance does not require `SetVariable()` support
+   during runtime services.
+
+   https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
+
 If a platform does not implement modifying non-volatile variables with
 `SetVariable()` after `ExitBootServices()`,
 then firmware shall return `EFI_UNSUPPORTED` for any call to `SetVariable()`,
@@ -580,17 +591,6 @@ Even when `SetVariable()` is not supported during runtime services, firmware
 should cache variable names and values in `EfiRuntimeServicesData` memory so
 that `GetVariable()` and `GetNextVariableName()` can behave as specified.
 
-.. [#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
-   storage operations on behalf of OP-TEE.
-   The same solution may be applicable to solving the UEFI non-volatile
-   variable problem, but it requires additional OS support to work.
-   Regardless, EBBR compliance does not require `SetVariable()` support
-   during runtime services.
-
-   https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
-
 .. _section-fw-update:
 
 Firmware Update
@@ -610,29 +610,29 @@ service and accept updates in the "Firmware Management Protocol Data Capsule
 Structure" format as described in :UEFI:`23.3`. [#FMPNote]_
 `UpdateCapsule()` is only required before `ExitBootServices()` is called.
 
+.. [#FMPNote] The `UpdateCapsule()` runtime service 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 `UpdateCapsule()`
+   before `ExitBootServices()` is called.
+
+   https://fwupd.org/
+
 Firmware is also required to provide an EFI System Resource Table (ESRT) as
 described in :UEFI:`23.4`.
 Every firmware image that can be updated in-band must be described in the ESRT.
 
 Firmware must support the delivery of capsules via file on mass storage device
 ("on disk") as described in :UEFI:`8.5.5`. [#VarNote]_
 
+.. [#VarNote] Some Variables are required to support capsule "on disk".
+   See section :ref:`section-required-vars-for-on-disk`.
+
 .. note::
    It is recommended that firmware implementing the `UpdateCapsule()` runtime
    service and an ESRT also implement the `EFI_FIRMWARE_MANAGEMENT_PROTOCOL`
    described in :UEFI:`23.1`. [#FMProtoNote]_
 
-.. [#FMPNote] The `UpdateCapsule()` runtime service 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 `UpdateCapsule()`
-   before `ExitBootServices()` is called.
-
-   https://fwupd.org/
-
-.. [#VarNote] Some Variables are required to support capsule "on disk".
-   See section :ref:`section-required-vars-for-on-disk`.
-
 .. [#FMProtoNote] At the time of writing, both Tianocore/EDK2 and U-Boot are
    using the `EFI_FIRMWARE_MANAGEMENT_PROTOCOL` internally to support their
    implementation of the `UpdateCapsule()` runtime service and of the ESRT,

source/chapter4-firmware-media.rst

@@ -13,18 +13,6 @@ or a dedicated logical unit (LU) within a device
 (e.g. eMMC boot partition, [#eMMCBootPartition]_
 or UFS boot LU [#LogicalUnitNote]_).
 
-However, many embedded systems have size, cost, or implementation
-constraints that make separate firmware storage unfeasible.
-On such systems, firmware and the OS reside in the same storage device.
-Care must be taken to ensure firmware kept in normal storage does not
-conflict with normal usage of the media by an OS.
-
-* Firmware must be stored on the media in a way that does not conflict
-  with normal partitioning and usage by the operating system.
-* Normal operation of the OS must not interfere with firmware files.
-* Firmware needs a method to modify variable storage at runtime while the
-  OS controls access to the device. [#LUVariables]_
-
 .. [#eMMCBootPartition] Watch out for the ambiguity of the word 'partition'.
    In most of this document, a 'partition' is a contiguous region of a block
    device as described by a GPT or MBR partition table,
@@ -38,6 +26,18 @@ conflict with normal usage of the media by an OS.
    A platform that uses one LU for firmware, and another LU for OS partitions
    and the ESP is considered to be using dedicated firmware storage.
 
+However, many embedded systems have size, cost, or implementation
+constraints that make separate firmware storage unfeasible.
+On such systems, firmware and the OS reside in the same storage device.
+Care must be taken to ensure firmware kept in normal storage does not
+conflict with normal usage of the media by an OS.
+
+* Firmware must be stored on the media in a way that does not conflict
+  with normal partitioning and usage by the operating system.
+* Normal operation of the OS must not interfere with firmware files.
+* Firmware needs a method to modify variable storage at runtime while the
+  OS controls access to the device. [#LUVariables]_
+
 .. [#LUVariables] Runtime access to firmware data may still be an issue when
    firmware is stored in a dedicated LU, simply because the OS remains in
    control of the storage device command stream. If firmware doesn't have