docs(spm): update ff-a boot protocol documentation

Updated following sections to document implementation of the FF-A boot
information protocol:
- Describing secure partitions.
- Secure Partition Packages.
- Passing boot data to the SP.
Also updated description of the manifest field 'gp-register-num'.

Signed-off-by: J-Alves <joao.alves@arm.com>
Change-Id: I5c856437b60cdf05566dd636a01207c9b9f42e61

3 files changed, 65 insertions, 11 deletions

diff --git a/docs/components/ffa-manifest-binding.rst b/docs/components/ffa-manifest-binding.rst
index 59996cc27..1d8ad0a17 100644
--- a/docs/components/ffa-manifest-binding.rst
+++ b/docs/components/ffa-manifest-binding.rst
@@ -137,14 +137,14 @@ Partition Properties
 
 - gp-register-num
    - value type: <u32>
-   - Presence of this field indicates that the partition expects the
-     ffa_init_info structure to be passed in via the specified general purpose
-     register.
-     The field specifies the general purpose register number but not its width.
+   - The field specifies the general purpose register number but not its width.
      The width is derived from the partition's execution state, as specified in
      the partition properties. For example, if the number value is 1 then the
      general-purpose register used will be x1 in AArch64 state and w1 in AArch32
      state.
+     Presence of this field indicates that the partition expects the address of
+     the FF-A boot information blob to be passed in the specified general purpose
+     register.
 
 - stream-endpoint-ids
    - value type: <prop-encoded-array>
diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst
index 2eaae7583..53a5151e2 100644
--- a/docs/components/secure-partition-manager.rst
+++ b/docs/components/secure-partition-manager.rst
@@ -358,6 +358,15 @@ Describing secure partitions
 A json-formatted description file is passed to the build flow specifying paths
 to the SP binary image and associated DTS partition manifest file. The latter
 is processed by the dtc compiler to generate a DTB fed into the SP package.
+Optionally, the partition's json description can contain offsets for both
+the image and partition manifest within the SP package. Both offsets need to be
+4KB aligned, because it is the translation granule supported by Hafnium SPMC.
+These fields can be leveraged to support SPs with S1 translation granules that
+differ from 4KB, and to configure the regions allocated within the SP package,
+as well as to comply with the requirements for the implementation of the boot
+information protocol (see `Passing boot data to the SP`_ for more details). In
+case the offsets are absent in their json node, they default to 0x1000 and
+0x4000 for the manifest offset and image offset respectively.
 This file also specifies the SP owner (as an optional field) identifying the
 signing domain in case of dual root CoT.
 The SP owner can either be the silicon or the platform provider. The
@@ -381,7 +390,19 @@ manifest.
             "image": "tee2.bin",
             "pm": "tee2.dts",
             "owner": "Plat"
-        }
+        },
+
+        "tee3" : {
+            "image": {
+                "file": "tee3.bin",
+                "offset":"0x2000"
+             },
+            "pm": {
+                "file": "tee3.dts",
+                "offset":"0x6000"
+             },
+            "owner": "Plat"
+        },
     }
 
 SPMC manifest
@@ -544,13 +565,46 @@ non-secure EL1&0 Stage-2 table if it exists.
 Passing boot data to the SP
 ---------------------------
 
-In `[1]`_ , the "Protocol for passing data" section defines a method for passing
-boot data to SPs (not currently implemented).
+In `[1]`_ , the section  "Boot information protocol" defines a method for passing
+data to the SPs at boot time. It specifies the format for the boot information
+descriptor and boot information header structures, which describe the data to be
+exchanged between SPMC and SP.
+The specification also defines the types of data that can be passed.
+The aggregate of both the boot info structures and the data itself is designated
+the boot information blob, and is passed to a Partition as a contiguous memory
+region.
+
+Currently, the SPM implementation supports the FDT type which is used to pass the
+partition's DTB manifest.
+
+The region for the boot information blob is allocated through the SP package.
+
+.. image:: ../resources/diagrams/partition-package.png
+
+To adjust the space allocated for the boot information blob, the json description
+of the SP (see section `Describing secure partitions`_) shall be updated to contain
+the manifest offset. If no offset is provided the manifest offset defaults to 0x1000,
+which is the page size in the Hafnium SPMC.
+
+The configuration of the boot protocol is done in the SPs manifest. As defined by
+the specification, the manifest field 'gp-register-num' configures the GP register
+which shall be used to pass the address to the partitions boot information blob when
+booting the partition.
+In addition, the Hafnium SPMC implementation requires the boot information arguments
+to be listed in a designated DT node:
+
+.. code:: shell
+
+  boot-info {
+      compatible = "arm,ffa-manifest-boot-info";
+      ffa_manifest;
+  };
 
-Provided that the whole secure partition package image (see
-`Secure Partition packages`_) is mapped to the SP secure EL1&0 Stage-2
-translation regime, an SP can access its own manifest DTB blob and extract its
-partition manifest properties.
+The whole secure partition package image (see `Secure Partition packages`_) is
+mapped to the SP secure EL1&0 Stage-2 translation regime. As such, the SP can
+retrieve the address for the boot information blob in the designated GP register,
+process the boot information header and descriptors, access its own manifest
+DTB blob and extract its partition manifest properties.
 
 SP Boot order
 -------------
diff --git a/docs/resources/diagrams/partition-package.png b/docs/resources/diagrams/partition-package.png
new file mode 100644
index 000000000..33674228d
--- /dev/null
+++ b/docs/resources/diagrams/partition-package.png