Merge changes from topic "od/spm-doc-update" into integration

* changes:
  docs(spm): refresh FF-A SPM design doc
  docs(spm): update FF-A manifest binding

docs/components/ffa-manifest-binding.rst

@@ -4,11 +4,8 @@ FF-A manifest binding to device tree
 This document defines the nodes and properties used to define a partition,
 according to the FF-A specification.
 
-Version 1.0
------------
-
 Partition Properties
-^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 - compatible [mandatory]
    - value type: <string>
@@ -184,13 +181,14 @@ Memory Regions
       - 0x1: Read
       - 0x2: Write
       - 0x4: Execute
+      - 0x8: Security state
 
 - base-address
    - value type: <u64>
    - Base address of the region. The address must be aligned to the translation
      granule size.
      The address given may be a Physical Address (PA), Virtual Address (VA), or
-     Intermediate Physical Address (IPA). Refer to the FFA specification for
+     Intermediate Physical Address (IPA). Refer to the FF-A specification for
      more information on the restrictions around the address type.
      If the base address is omitted then the partition manager must map a memory
      region of the specified size into the partition's translation regime and
@@ -208,14 +206,10 @@ Device Regions
    - value type: <string>
    - Name of the device region e.g. for debugging purposes.
 
-- reg [mandatory]
+- pages-count [mandatory]
-   - value type: <prop-encoded-array>
+   - value type: <u32>
-   - A (address, num-pages) pair describing the device, where:
+   - Count of pages of memory region as a multiple of the translation granule
-
+     size
-      - address: The physical base address <u64> value of the device MMIO
-        region.
-      - num-pages: The <u32> number of pages of the region. The total size of
-        the region is this value multiplied by the translation granule size.
 
 - attributes [mandatory]
    - value type: <u32>
@@ -224,6 +218,15 @@ Device Regions
      - 0x1: Read
      - 0x2: Write
      - 0x4: Execute
+     - 0x8: Security state
+
+- base-address [mandatory]
+   - value type: <u64>
+   - Base address of the region. The address must be aligned to the translation
+     granule size.
+     The address given may be a Physical Address (PA), Virtual Address (VA), or
+     Intermediate Physical Address (IPA). Refer to the FF-A specification for
+     more information on the restrictions around the address type.
 
 - smmu-id
    - value type: <u32>
@@ -243,14 +246,32 @@ Device Regions
    - A list of (id, attributes) pair describing the device interrupts, where:
 
       - id: The <u32> interrupt IDs.
-      - attributes: A <u32> value,
+      - attributes: A <u32> value, containing attributes for each interrupt ID:
-        containing the attributes for each interrupt ID:
 
-         - Interrupt type: SPI, PPI, SGI
+        +----------------------+----------+
-         - Interrupt configuration: Edge triggered, Level triggered
+        |Field                 | Bit(s)   |
-         - Interrupt security state: Secure, Non-secure
+        +----------------------+----------+
-         - Interrupt priority value
+        | Priority	       | 7:0      |
-         - Target execution context/vCPU for each SPI
+        +----------------------+----------+
+        | Security state       | 8        |
+        +----------------------+----------+
+        | Config(Edge/Level)   | 9        |
+        +----------------------+----------+
+        | Type(SPI/PPI/SGI)    | 11:10    |
+        +----------------------+----------+
+
+        Security state:
+          - Secure:       1
+          - Non-secure:   0
+
+        Configuration:
+          - Edge triggered:       0
+          - Level triggered:      1
+
+        Type:
+          - SPI:  0b10
+          - PPI:  0b01
+          - SGI:  0b00
 
 - exclusive-access
    - value type: <empty>
@@ -259,4 +280,4 @@ Device Regions
 
 --------------
 
-*Copyright (c) 2019-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2019-2022, Arm Limited and Contributors. All rights reserved.*

docs/components/index.rst

@@ -21,7 +21,6 @@ Components
    sdei
    secure-partition-manager
    secure-partition-manager-mm
-   ffa-manifest-binding
    xlat-tables-lib-v2-design
    cot-binding
    realm-management-extension

docs/components/secure-partition-manager.rst

@@ -3,6 +3,9 @@ Secure Partition Manager
 
 .. contents::
 
+.. toctree::
+  ffa-manifest-binding
+
 Acronyms
 ========
 
@@ -23,6 +26,8 @@ Acronyms
 +--------+--------------------------------------+
 | IPA    | Intermediate Physical Address        |
 +--------+--------------------------------------+
+| JOP    | Jump-Oriented Programming            |
++--------+--------------------------------------+
 | NWd    | Normal World                         |
 +--------+--------------------------------------+
 | ODM    | Original Design Manufacturer         |
@@ -37,6 +42,8 @@ Acronyms
 +--------+--------------------------------------+
 | PVM    | Primary VM                           |
 +--------+--------------------------------------+
+| ROP    | Return-Oriented Programming          |
++--------+--------------------------------------+
 | SMMU   | System Memory Management Unit        |
 +--------+--------------------------------------+
 | SP     | Secure Partition                     |
@@ -63,24 +70,25 @@ Acronyms
 Foreword
 ========
 
-Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
+Three implementations of a Secure Partition Manager co-exist in the TF-A
+codebase:
 
-- SPM based on the FF-A specification `[1]`_.
+#. S-EL2 SPMC based on the FF-A specification `[1]`_, enabling virtualization in
-- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_.
+   the secure world, managing multiple S-EL1 or S-EL0 partitions.
+#. EL3 SPMC based on the FF-A specification, managing a single S-EL1 partition
+   without virtualization in the secure world.
+#. EL3 SPM based on the MM specification, legacy implementation managing a
+   single S-EL0 partition `[2]`_.
 
-Both implementations differ in their architectures and only one can be selected
+These implementations differ in their respective SW architecture and only one
-at build time.
+can be selected at build time. This document:
 
-This document:
+- describes the implementation from bullet 1. when the SPMC resides at S-EL2.
-
-- describes the FF-A implementation where the Secure Partition Manager
-  resides at EL3 and S-EL2 (or EL3 and S-EL1).
 - is not an architecture specification and it might provide assumptions
   on sections mandated as implementation-defined in the specification.
-- covers the implications to TF-A used as a bootloader, and Hafnium
+- covers the implications to TF-A used as a bootloader, and Hafnium used as a
-  used as a reference code base for an S-EL2 secure firmware on
+  reference code base for an S-EL2/SPMC secure firmware on platforms
-  platforms implementing the FEAT_SEL2 (formerly Armv8.4 Secure EL2)
+  implementing the FEAT_SEL2 architecture extension.
-  architecture extension.
 
 Terminology
 -----------
@@ -98,20 +106,23 @@ Terminology
 Support for legacy platforms
 ----------------------------
 
-In the implementation, the SPM is split into SPMD and SPMC components.
+The SPM is split into a dispatcher and a core component (respectively SPMD and
-The SPMD is located at EL3 and mainly relays FF-A messages from
+SPMC) residing at different exception levels. To permit the FF-A specification
-NWd (Hypervisor or OS kernel) to SPMC located either at S-EL1 or S-EL2.
+adoption and a smooth migration, the SPMD supports an SPMC residing either at
+S-EL1 or S-EL2:
 
-Hence TF-A supports both cases where the SPMC is located either at:
+- The SPMD is located at EL3 and mainly relays the FF-A protocol from NWd
+  (Hypervisor or OS kernel) to the SPMC.
+- The same SPMD component is used for both S-EL1 and S-EL2 SPMC configurations.
+- The SPMC exception level is a build time choice.
 
-- S-EL1 supporting platforms not implementing the FEAT_SEL2 architecture
+TF-A supports both cases:
+
+- S-EL1 SPMC for platforms not supporting the FEAT_SEL2 architecture
   extension. The SPMD relays the FF-A protocol from EL3 to S-EL1.
-- or S-EL2 supporting platforms implementing the FEAT_SEL2 architecture
+- S-EL2 SPMC for platforms implementing the FEAT_SEL2 architecture
   extension. The SPMD relays the FF-A protocol from EL3 to S-EL2.
 
-The same TF-A SPMD component is used to support both configurations.
-The SPMC exception level is a build time choice.
-
 Sample reference stack
 ======================
 
@@ -137,7 +148,7 @@ SPMC located at S-EL1, S-EL2 or EL3:
   SPD=spmd is chosen.
 - **SPMC_AT_EL3**: this option adjusts the SPMC exception level to being
   at EL3.
-- If neither **SPMD_SPM_AT_SEL2** or **SPMC_AT_EL3** are enabled the SPMC
+- If neither ``SPMD_SPM_AT_SEL2`` or ``SPMC_AT_EL3`` are enabled the SPMC
   exception level is set to S-EL1.
 - **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
   restoring) the EL2 system register context before entering (resp.
@@ -148,7 +159,7 @@ SPMC located at S-EL1, S-EL2 or EL3:
   providing paths to SP binary images and manifests in DTS format
   (see `Describing secure partitions`_). It
   is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
-  secure partitions are to be loaded on behalf of the SPMC.
+  secure partitions are to be loaded by BL2 on behalf of the SPMC.
 
 +---------------+----------------------+------------------+-------------+
 |               | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 | SPMC_AT_EL3 |
@@ -168,9 +179,8 @@ Notes:
 
 - Only Arm's FVP platform is supported to use with the TF-A reference software
   stack.
-- The reference software stack uses FEAT_PAuth (formerly Armv8.3-PAuth) and
+- When ``SPMD_SPM_AT_SEL2=1``, the reference software stack assumes enablement
-  FEAT_BTI (formerly Armv8.5-BTI) architecture extensions by default at EL3
+  of FEAT_PAuth, FEAT_BTI and FEAT_MTE architecture extensions.
-  and S-EL2.
 - The ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
   barely saving/restoring EL2 registers from an Arm arch perspective. As such
   it is decoupled from the ``SPD=spmd`` option.
@@ -178,10 +188,10 @@ Notes:
   the Hafnium binary path (built for the secure world) or the path to a TEE
   binary implementing FF-A interfaces.
 - BL33 option can specify the TFTF binary or a normal world loader
-  such as U-Boot or the UEFI framework.
+  such as U-Boot or the UEFI framework payload.
 
-Sample TF-A build command line when SPMC is located at S-EL1
+Sample TF-A build command line when the SPMC is located at S-EL1
-(e.g. when the FEAT_EL2 architecture extension is not implemented):
+(e.g. when the FEAT_SEL2 architecture extension is not implemented):
 
 .. code:: shell
 
@@ -194,9 +204,8 @@ Sample TF-A build command line when SPMC is located at S-EL1
     PLAT=fvp \
     all fip
 
-Sample TF-A build command line for a FEAT_SEL2 enabled system where the SPMC is
+Sample TF-A build command line when FEAT_SEL2 architecture extension is
-located at S-EL2:
+implemented and the SPMC is located at S-EL2:
-
 .. code:: shell
 
     make \
@@ -207,13 +216,14 @@ located at S-EL2:
     ARM_ARCH_MINOR=5 \
     BRANCH_PROTECTION=1 \
     CTX_INCLUDE_PAUTH_REGS=1 \
+    CTX_INCLUDE_MTE_REGS=1 \
     BL32=<path-to-hafnium-binary> \
     BL33=<path-to-bl33-binary> \
     SP_LAYOUT_FILE=sp_layout.json \
     all fip
 
-Same as above with enabling secure boot in addition:
+Sample TF-A build command line when FEAT_SEL2 architecture extension is
-
+implemented, the SPMC is located at S-EL2, and enabling secure boot:
 .. code:: shell
 
     make \
@@ -224,6 +234,7 @@ Same as above with enabling secure boot in addition:
     ARM_ARCH_MINOR=5 \
     BRANCH_PROTECTION=1 \
     CTX_INCLUDE_PAUTH_REGS=1 \
+    CTX_INCLUDE_MTE_REGS=1 \
     BL32=<path-to-hafnium-binary> \
     BL33=<path-to-bl33-binary> \
     SP_LAYOUT_FILE=sp_layout.json \
@@ -235,7 +246,7 @@ Same as above with enabling secure boot in addition:
     GENERATE_COT=1 \
     all fip
 
-Sample TF-A build command line when SPMC is located at EL3:
+Sample TF-A build command line when the SPMC is located at EL3:
 
 .. code:: shell
 
@@ -270,29 +281,33 @@ The FVP command line needs the following options to exercise the S-EL2 SPMC:
 | - cluster0.has_branch_target_exception=1          | Implements FEAT_BTI.               |
 | - cluster1.has_branch_target_exception=1          |                                    |
 +---------------------------------------------------+------------------------------------+
-| - cluster0.restriction_on_speculative_execution=2 | Required by the EL2 context        |
+| - cluster0.has_pointer_authentication=2           | Implements FEAT_PAuth              |
-| - cluster1.restriction_on_speculative_execution=2 | save/restore routine.              |
+| - cluster1.has_pointer_authentication=2           |                                    |
++---------------------------------------------------+------------------------------------+
+| - cluster0.memory_tagging_support_level=2         | Implements FEAT_MTE2               |
+| - cluster1.memory_tagging_support_level=2         |                                    |
+| - bp.dram_metadata.is_enabled=1                   |                                    |
 +---------------------------------------------------+------------------------------------+
 
 Sample FVP command line invocation:
 
 .. code:: shell
 
-    <path-to-fvp-model>/FVP_Base_RevC-2xAEMv8A -C pctl.startup=0.0.0.0
+    <path-to-fvp-model>/FVP_Base_RevC-2xAEMvA -C pctl.startup=0.0.0.0 \
     -C cluster0.NUM_CORES=4 -C cluster1.NUM_CORES=4 -C bp.secure_memory=1 \
     -C bp.secureflashloader.fname=trusted-firmware-a/build/fvp/debug/bl1.bin \
     -C bp.flashloader0.fname=trusted-firmware-a/build/fvp/debug/fip.bin \
     -C bp.pl011_uart0.out_file=fvp-uart0.log -C bp.pl011_uart1.out_file=fvp-uart1.log \
     -C bp.pl011_uart2.out_file=fvp-uart2.log \
-    -C cluster0.has_arm_v8-5=1 -C cluster1.has_arm_v8-5=1 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 \
+    -C cluster0.has_arm_v8-5=1 -C cluster1.has_arm_v8-5=1 \
-    -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 \
+    -C cluster0.has_pointer_authentication=2 -C cluster1.has_pointer_authentication=2 \
-    -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 \
+    -C cluster0.has_branch_target_exception=1 -C cluster1.has_branch_target_exception=1 \
-    -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 \
+    -C cluster0.memory_tagging_support_level=2 -C cluster1.memory_tagging_support_level=2 \
-    -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 \
+    -C bp.dram_metadata.is_enabled=1 \
-    -C cluster0.has_branch_target_exception=1 \
+    -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B \
-    -C cluster1.has_branch_target_exception=1 \
+    -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 \
-    -C cluster0.restriction_on_speculative_execution=2 \
+    -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 \
-    -C cluster1.restriction_on_speculative_execution=2
+    -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0
 
 Boot process
 ============
@@ -424,7 +439,7 @@ two different cases:
     attribute {
         spmc_id = <0x8000>;
         maj_ver = <0x1>;
-        min_ver = <0x0>;
+        min_ver = <0x1>;
         exec_state = <0x0>;
         load_address = <0x0 0x6000000>;
         entrypoint = <0x0 0x6000000>;
@@ -443,13 +458,13 @@ two different cases:
   SPMD (currently matches ``BL32_BASE``) to enter the SPMC.
 
 Other nodes in the manifest are consumed by Hafnium in the secure world.
-A sample can be found at [7]:
+A sample can be found at `[7]`_:
 
 - The *hypervisor* node describes SPs. *is_ffa_partition* boolean attribute
   indicates a FF-A compliant SP. The *load_address* field specifies the load
-  address at which TF-A loaded the SP package.
+  address at which BL2 loaded the SP package.
 - *cpus* node provide the platform topology and allows MPIDR to VMPIDR mapping.
-  Note the primary core is declared first, then secondary core are declared
+  Note the primary core is declared first, then secondary cores are declared
   in reverse order.
 - The *memory* node provides platform information on the ranges of memory
   available to the SPMC.
@@ -481,7 +496,7 @@ below:
 
 Note this boot flow is an implementation sample on Arm's FVP platform.
 Platforms not using TF-A's *Firmware CONFiguration* framework would adjust to a
-different implementation.
+different boot flow. The flow restricts to a maximum of 8 secure partitions.
 
 Secure boot
 ~~~~~~~~~~~
@@ -496,6 +511,8 @@ the use of two root keys namely S-ROTPK and NS-ROTPK:
 - SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK.
 - BL33 may be signed by the OEM using NS-ROTPK.
 - An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK).
+- A maximum of 4 partitions can be signed with the S-ROTPK key and 4 partitions
+  signed with the NS-ROTPK key.
 
 Also refer to `Describing secure partitions`_ and `TF-A build options`_ sections.
 
@@ -512,20 +529,23 @@ In the Hafnium reference implementation specific code parts are only relevant to
 the secure world. Such portions are isolated in architecture specific files
 and/or enclosed by a ``SECURE_WORLD`` macro.
 
-Secure partitions CPU scheduling
+Secure partitions scheduling
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The FF-A v1.0 specification `[1]`_ provides two ways to relinquinsh CPU time to
+The FF-A specification `[1]`_ provides two ways to relinquinsh CPU time to
 secure partitions. For this a VM (Hypervisor or OS kernel), or SP invokes one of:
 
 - the FFA_MSG_SEND_DIRECT_REQ interface.
 - the FFA_RUN interface.
 
+Additionally a secure interrupt can pre-empt the normal world execution and give
+CPU cycles by transitioning to EL3 and S-EL2.
+
 Platform topology
 ~~~~~~~~~~~~~~~~~
 
 The *execution-ctx-count* SP manifest field can take the value of one or the
-total number of PEs. The FF-A v1.0 specification `[1]`_  recommends the
+total number of PEs. The FF-A specification `[1]`_  recommends the
 following SP types:
 
 - Pinned MP SPs: an execution context matches a physical PE. MP SPs must
@@ -711,29 +731,30 @@ called and informed by the FF-A driver, and it should allocate CPU cycles to the
 receiver.
 
 There are two types of notifications supported:
+
 - Global, which are targeted to a FF-A endpoint and can be handled within any of
-its execution contexts, as determined by the scheduler of the system.
+  its execution contexts, as determined by the scheduler of the system.
 - Per-vCPU, which are targeted to a FF-A endpoint and to be handled within a
-a specific execution context, as determined by the sender.
+  a specific execution context, as determined by the sender.
 
 The type of a notification is set when invoking FFA_NOTIFICATION_BIND to give
 permissions to the sender.
 
 Notification signaling resorts to two interrupts:
-- Schedule Receiver Interrupt: Non-secure physical interrupt to be handled by
+
-the FF-A 'transport' driver within the receiver scheduler. At initialization
+- Schedule Receiver Interrupt: non-secure physical interrupt to be handled by
-the SPMC (as suggested by the spec) configures a secure SGI, as non-secure, and
+  the FF-A driver within the receiver scheduler. At initialization the SPMC
-triggers it when there are pending notifications, and the respective receivers
+  donates a SGI ID chosen from the secure SGI IDs range and configures it as
-need CPU cycles to handle them.
+  non-secure. The SPMC triggers this SGI on the currently running core when
-- Notifications Pending Interrupt: Virtual Interrupt to be handled by the
+  there are pending notifications, and the respective receivers need CPU cycles
-receiver of the notification. Set when there are pending notifications. For
+  to handle them.
-per-vCPU the NPI is pended at the handling of FFA_NOTIFICATION_SET interface.
+- Notifications Pending Interrupt: virtual interrupt to be handled by the
+  receiver of the notification. Set when there are pending notifications for the
+  given secure partition. The NPI is pended when the NWd relinquishes CPU cycles
+  to an SP.
 
 The notifications receipt support is enabled in the partition FF-A manifest.
 
-The subsequent section provides more details about the each one of the
-FF-A interfaces for notifications support.
-
 Mandatory interfaces
 --------------------
 
@@ -755,9 +776,12 @@ The following interfaces are exposed to SPs:
 -  ``FFA_MEM_RETRIEVE_REQ``
 -  ``FFA_MEM_RETRIEVE_RESP``
 -  ``FFA_MEM_RELINQUISH``
+-  ``FFA_MEM_FRAG_RX``
+-  ``FFA_MEM_FRAG_TX``
 -  ``FFA_MEM_RECLAIM``
+-  ``FFA_RUN``
 
-As part of the support of FF-A v1.1, the following interfaces were added:
+As part of the FF-A v1.1 support, the following interfaces were added:
 
  - ``FFA_NOTIFICATION_BITMAP_CREATE``
  - ``FFA_NOTIFICATION_BITMAP_DESTROY``
@@ -768,6 +792,8 @@ As part of the support of FF-A v1.1, the following interfaces were added:
  - ``FFA_NOTIFICATION_INFO_GET``
  - ``FFA_SPM_ID_GET``
  - ``FFA_SECONDARY_EP_REGISTER``
+ - ``FFA_MEM_PERM_GET``
+ - ``FFA_MEM_PERM_SET``
 
 FFA_VERSION
 ~~~~~~~~~~~
@@ -895,24 +921,21 @@ notifications.
 FFA_NOTIFICATION_SET/FFA_NOTIFICATION_GET
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If the notifications set are per-vCPU, the NPI interrupt is set as pending
+FFA_NOTIFICATION_GET retrieves all pending global notifications and
-for a given receiver partition.
+per-vCPU notifications targeted to the current vCPU.
 
-The FFA_NOTIFICATION_GET will retrieve all pending global notifications and all
+Hafnium maintains a global count of pending notifications which gets incremented
-pending per-vCPU notifications targeted to the current vCPU.
+and decremented when handling FFA_NOTIFICATION_SET and FFA_NOTIFICATION_GET
-
+respectively. A delayed SRI is triggered if the counter is non-zero when the
-Hafnium keeps the global counting of the pending notifications, which is
+SPMC returns to normal world.
-incremented and decremented at the handling of FFA_NOTIFICATION_SET and
-FFA_NOTIFICATION_GET, respectively. If the counter reaches zero, prior to SPMC
-triggering the SRI, it won't be triggered.
 
 FFA_NOTIFICATION_INFO_GET
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Hafnium keeps the global counting of pending notifications whose info has been
+Hafnium maintains a global count of pending notifications whose information
-retrieved by this interface. The counting is incremented and decremented at the
+has been retrieved by this interface. The count is incremented and decremented
-handling of FFA_NOTIFICATION_INFO_GET and FFA_NOTIFICATION_GET, respectively.
+when handling FFA_NOTIFICATION_INFO_GET and FFA_NOTIFICATION_GET respectively.
-It also tracks the notifications whose info has been retrieved individually,
+It also tracks notifications whose information has been retrieved individually,
 such that it avoids duplicating returned information for subsequent calls to
 FFA_NOTIFICATION_INFO_GET. For each notification, this state information is
 reset when receiver called FFA_NOTIFICATION_GET to retrieve them.
@@ -920,18 +943,18 @@ reset when receiver called FFA_NOTIFICATION_GET to retrieve them.
 FFA_SPM_ID_GET
 ~~~~~~~~~~~~~~
 
-Returns the FF-A ID allocated to the SPM component (which includes SPMC + SPMD).
+Returns the FF-A ID allocated to an SPM component which can be one of SPMD
-At initialization, the SPMC queries the SPMD for the SPM ID, using this
+or SPMC.
-same interface, and saves it.
 
-The call emitted at NS and secure physical FF-A instances returns the SPM ID
+At initialization, the SPMC queries the SPMD for the SPMC ID, using the
-specified in the SPMC manifest.
+FFA_ID_GET interface, and records it. The SPMC can also query the SPMD ID using
+the FFA_SPM_ID_GET interface at the secure physical FF-A instance.
 
-Secure partitions call this interface at the virtual instance, to which the SPMC
+Secure partitions call this interface at the virtual FF-A instance, to which
-shall return the priorly retrieved SPM ID.
+the SPMC returns the priorly retrieved SPMC ID.
 
-The Hypervisor or OS kernel can issue an FFA_SPM_ID_GET call handled by the
+The Hypervisor or OS kernel can issue the FFA_SPM_ID_GET call handled by the
-SPMD, which returns the SPM ID.
+SPMD, which returns the SPMC ID.
 
 FFA_SECONDARY_EP_REGISTER
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -939,7 +962,7 @@ FFA_SECONDARY_EP_REGISTER
 When the SPMC boots, all secure partitions are initialized on their primary
 Execution Context.
 
-The interface FFA_SECONDARY_EP_REGISTER is to be used by a secure partitions
+The FFA_SECONDARY_EP_REGISTER interface is to be used by a secure partition
 from its first execution context, to provide the entry point address for
 secondary execution contexts.
 
@@ -956,26 +979,35 @@ permits SPMD to SPMC communication and either way.
 - SPMC to SPMD direct request/response uses SMC conduit.
 - SPMD to SPMC direct request/response uses ERET conduit.
 
+This is used in particular to convey power management messages.
+
 PE MMU configuration
 --------------------
 
-With secure virtualization enabled, two IPA spaces are output from the secure
+With secure virtualization enabled (``HCR_EL2.VM = 1``) and for S-EL1
-EL1&0 Stage-1 translation (secure and non-secure). The EL1&0 Stage-2 translation
+partitions, two IPA spaces (secure and non-secure) are output from the
-hardware is fed by:
+secure EL1&0 Stage-1 translation.
+The EL1&0 Stage-2 translation hardware is fed by:
 
-- A single secure IPA space when the SP EL1&0 Stage-1 MMU is disabled.
+- A secure IPA when the SP EL1&0 Stage-1 MMU is disabled.
-- Two IPA spaces (secure and non-secure) when the SP EL1&0 Stage-1 MMU is
+- One of secure or non-secure IPA when the secure EL1&0 Stage-1 MMU is enabled.
-  enabled.
 
 ``VTCR_EL2`` and ``VSTCR_EL2`` provide configuration bits for controlling the
-NS/S IPA translations.
+NS/S IPA translations. The following controls are set up:
-``VSTCR_EL2.SW`` = 0, ``VSTCR_EL2.SA`` = 0,``VTCR_EL2.NSW`` = 0, ``VTCR_EL2.NSA`` = 1:
+``VSTCR_EL2.SW = 0`` , ``VSTCR_EL2.SA = 0``, ``VTCR_EL2.NSW = 0``,
+``VTCR_EL2.NSA = 1``:
 
 - Stage-2 translations for the NS IPA space access the NS PA space.
 - Stage-2 translation table walks for the NS IPA space are to the secure PA space.
 
-Secure and non-secure IPA regions use the same set of Stage-2 page tables within
+Secure and non-secure IPA regions (rooted to by ``VTTBR_EL2`` and ``VSTTBR_EL2``)
-a SP.
+use the same set of Stage-2 page tables within a SP.
+
+The ``VTCR_EL2/VSTCR_EL2/VTTBR_EL2/VSTTBR_EL2`` virtual address space
+configuration is made part of a vCPU context.
+
+For S-EL0 partitions with VHE enabled, a single secure EL2&0 Stage-1 translation
+regime is used for both Hafnium and the partition.
 
 Interrupt management
 --------------------
@@ -1172,16 +1204,46 @@ When using the SPMD as a Secure Payload Dispatcher:
   (svc_off) hooks are registered.
 - The behavior for the cpu on event is described in `Secondary cores boot-up`_.
   The SPMC is entered through its secondary physical core entry point.
-- The cpu off event occurs when the NWd calls PSCI_CPU_OFF. The method by which
+- The cpu off event occurs when the NWd calls PSCI_CPU_OFF. The PM event is
-  the PM event is conveyed to the SPMC is implementation-defined in context of
+  signaled to the SPMC through a power management framework message.
-  FF-A v1.0 (`SPMC-SPMD direct requests/responses`_). It consists in a SPMD-to-SPMC
+  It consists in a SPMD-to-SPMC direct request/response (`SPMC-SPMD direct
-  direct request/response conveying the PM event details and SPMC response.
+  requests/responses`_) conveying the event details and SPMC response.
   The SPMD performs a synchronous entry into the SPMC. The SPMC is entered and
   updates its internal state to reflect the physical core is being turned off.
   In the current implementation no SP is resumed as a consequence. This behavior
   ensures a minimal support for CPU hotplug e.g. when initiated by the NWd linux
   userspace.
 
+Arm architecture extensions for security hardening
+==================================================
+
+Hafnium supports the following architecture extensions for security hardening:
+
+- Pointer authentication (FEAT_PAuth): the extension permits detection of forged
+  pointers used by ROP type of attacks through the signing of the pointer
+  value. Hafnium is built with the compiler branch protection option to permit
+  generation of a pointer authentication code for return addresses (pointer
+  authentication for instructions). The APIA key is used while Hafnium runs.
+  A random key is generated at boot time and restored upon entry into Hafnium
+  at run-time. APIA and other keys (APIB, APDA, APDB, APGA) are saved/restored
+  in vCPU contexts permitting to enable pointer authentication in VMs/SPs.
+- Branch Target Identification (FEAT_BTI): the extension permits detection of
+  unexpected indirect branches used by JOP type of attacks. Hafnium is built
+  with the compiler branch protection option, inserting land pads at function
+  prologues that are reached by indirect branch instructions (BR/BLR).
+  Hafnium code pages are marked as guarded in the EL2 Stage-1 MMU descriptors
+  such that an indirect branch must always target a landpad. A fault is
+  triggered otherwise. VMs/SPs can (independently) mark their code pages as
+  guarded in the EL1&0 Stage-1 translation regime.
+- Memory Tagging Extension (FEAT_MTE): the option permits detection of out of
+  bound memory array accesses or re-use of an already freed memory region.
+  Hafnium enables the compiler option permitting to leverage MTE stack tagging
+  applied to core stacks. Core stacks are marked as normal tagged memory in the
+  EL2 Stage-1 translation regime. A synchronous data abort is generated upon tag
+  check failure on load/stores. A random seed is generated at boot time and
+  restored upon entry into Hafnium. MTE system registers are saved/restored in
+  vCPU contexts permitting MTE usage from VMs/SPs.
+
 SMMUv3 support in Hafnium
 =========================
 
@@ -1291,7 +1353,7 @@ streams.
 -  No support for independent peripheral devices.
 
 S-EL0 Partition support
-=========================
+=======================
 The SPMC (Hafnium) has limited capability to run S-EL0 FF-A partitions using
 FEAT_VHE (mandatory with ARMv8.1 in non-secure state, and in secure world
 with ARMv8.4 and FEAT_SEL2).