Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

13 files changed, 940 insertions, 0 deletions

diff --git a/docs/resources/diagrams/plantuml/bl2-loading-sp.puml b/docs/resources/diagrams/plantuml/bl2-loading-sp.puml
new file mode 100644
index 0000000..3cf7c36
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/bl2-loading-sp.puml
@@ -0,0 +1,44 @@
+/'
+ ' Copyright (c) 2020, ARM Limited and Contributors. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+@startuml
+participant bl1
+participant FIP
+
+bl1 -> FIP : read(FW_CONFIG)
+create FW_CONFIG
+bl1 -> FW_CONFIG : load
+
+bl1 -> FIP : read(bl2)
+create bl2
+bl1 -> bl2 : load
+bl1 --> bl2 : hand off (FW_CONFIG)
+
+bl2 -> FW_CONFIG : read_node(SPKs)
+loop for each spkg subnode
+  bl2 -> FW_CONFIG : read(UUID)
+  bl2 -> FW_CONFIG : read(load_address)
+  bl2 -> FIP : read(spkg@UUID)
+  create SPKG
+  bl2 -> SPKG : load
+end loop
+
+bl2 -> FW_CONFIG : read_node(TOS_FW_CONFIG)
+create TOS_FW_CONFIG
+bl2 -> TOS_FW_CONFIG : load
+
+bl2 -> FIP : read(bl32/SPMC)
+create SPMC
+bl2 -> SPMC : load
+
+bl2 -> FIP : read(bl31)
+create bl31
+bl2 -> bl31 : load
+bl2 --> bl31 : hand off (TOS_FW_CONFIG)
+
+bl31 --> SPMC : hand off (TOS_FW_CONFIG)
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/el3_spm_dfd.puml b/docs/resources/diagrams/plantuml/el3_spm_dfd.puml
new file mode 100644
index 0000000..c716180
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/el3_spm_dfd.puml
@@ -0,0 +1,78 @@
+/'
+ ' Copyright (c) 2022, Arm Limited. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+/'
+TF-A EL3 SPMC Data Flow Diagram
+'/
+
+@startuml
+digraph tfa_el3_dfd {
+
+    # Allow arrows to end on cluster boundaries
+    compound=true
+    concentrate=false
+    newrank=true
+
+    # Default settings for edges and nodes
+    edge [minlen=2 color="#8c1b07"]
+    node [fillcolor="#ffb866" style=filled shape=box fixedsize=true width=1.6 height=0.7]
+
+    # Nodes outside of the trust boundary
+    nsec [label="NS Client"]
+    ddr  [label="External memory (DDR)"]
+
+    {rank="same" smmu, spmd}
+    # Trust boundary cluster
+    subgraph cluster_trusted {
+        graph [style=dashed color="#f22430"]
+        concentrate=false
+
+        # HW IPs cluster
+        subgraph cluster_ip {
+            label ="Hardware IPs";
+            graph [style=filled color="#000000" fillcolor="#ffd29e"]
+
+            rank="same"
+            gic [label="GIC" width=1.2 height=0.5]
+            smmu [label="SMMU" width=1.2 height=0.5]
+            uart [label="UART" width=1.2 height=0.5]
+            pe [label="PE" width=1.2 height=0.5]
+        }
+
+        # TF-A cluster
+        subgraph cluster_tfa {
+            label ="EL3 monitor";
+            graph [style=filled color="#000000" fillcolor="#faf9cd"]
+            {rank="same" spmc, bl31}
+            {rank="same" spmd, lsp}
+            spmc [label="SPMC" fillcolor="#ddffb3"]
+            bl31 [label="BL31" fillcolor="#ddffb3"];
+            spmd [label="SPMD" fillcolor="#ddffb3"]
+            lsp[label="LSP1" fillcolor="#ddffb3"]
+        }
+        bl2 [label="BL2" width=1.2 height=0.5]
+    }
+
+    # Secure Partitions cluster
+    subgraph cluster_sp {
+        label ="Secure Partitions";
+        graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+        sp1 [label="SP1" fillcolor="#ddffb3"]
+    }
+
+    sp1 -> spmc [dir="both" label="DF1"]
+    lsp -> spmc [dir="both" label="DF4"]
+    spmc -> spmd [dir="both" label="DF2"]
+    spmd -> nsec [dir="both" label="DF3"]
+    spmc -> smmu [lhead=cluster_spmc label="DF5"]
+    bl2 -> spmc [lhead=cluster_spmc label="DF6"]
+    bl2 -> sp1 [lhead=cluster_spmc label="DF6"]
+    sp1 -> ddr [dir="both"  label="DF7"]
+    spmc -> ddr [dir="both"  label="DF7"]
+}
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml b/docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml
new file mode 100644
index 0000000..e513ed4
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml
@@ -0,0 +1,78 @@
+@startuml
+
+box "BL1 common code"
+	participant bl1_main
+	participant bl_common
+end box
+
+box "arm platform code" #LightBlue
+	participant fvp_bl1_setup
+	participant arm_bl1_setup
+	participant arm_io_storage
+end box
+
+box "platform common code"
+	participant plat_bl1_common
+	participant fconf_dyn_cfg_getter
+	participant fconf
+end box
+
+bl1_main -> fvp_bl1_setup : bl1_platform_setup()
+fvp_bl1_setup -> arm_bl1_setup : arm_bl1_platform_setup()
+arm_bl1_setup -> arm_io_storage : plat_arm_io_setup()
+note over arm_io_storage : register and setup fip
+arm_bl1_setup -> fconf : set_fw_config_info(fw_config_base, max_size)
+note over fconf
+	set fw_config information
+	(address, size, image_id)
+	in global dtb_infos array.
+end note
+activate fconf
+	arm_bl1_setup -> fconf : fconf_load_config(FW_CONFIG_ID)
+	fconf -> fconf : FCONF_GET_PROPERTY(dyn_cfg, dtb, FW_CONFIG_ID)
+	fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(FW_CONFIG_ID)
+	fconf_dyn_cfg_getter -> fconf: fw_config_info
+	fconf -> bl_common : load_auth_image(FW_CONFIG_ID, &image_info)
+	activate bl_common
+	note over bl_common
+		load and auth image from fip
+		with info from plat_io_policy
+	end note
+	bl_common -> arm_io_storage
+	arm_io_storage -> fconf: FCONF_GET_PROPERTY(arm, arm_io_policies, FW_CONFIG_ID)
+	note over fconf: use statically defined policies in bl1
+	fconf <- bl_common : image_info
+	deactivate bl_common
+	note over fconf : get fw_config_dtb from image_info
+	arm_bl1_setup -> fconf: FCONF_GET_PROPERTY(dyn_cfg, dtb, FW_CONFIG_ID)
+	fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(FW_CONFIG_ID)
+	fconf_dyn_cfg_getter -> arm_bl1_setup: fw_config_info
+	arm_bl1_setup -> fconf_dyn_cfg_getter: populate_dtb_registry(uintptr_t dtb)
+	arm_bl1_setup -> fconf: fconf_load_config(TB_FW_CONFIG_ID)
+	fconf -> fconf : FCONF_GET_PROPERTY(dyn_cfg, dtb, TB_FW_CONFIG_ID)
+	fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(TB_FW_CONFIG_ID)
+	fconf_dyn_cfg_getter -> fconf: tb_fw_config_info
+	fconf -> bl_common : load_auth_image(TB_FW_CONFIG_ID, &image_info)
+	activate bl_common
+	note over bl_common
+		load and auth image from fip
+		with info from plat_io_policy
+	end note
+	bl_common -> arm_io_storage
+	arm_io_storage -> fconf: FCONF_GET_PROPERTY(arm, arm_io_policies, TB_FW_CONFIG_ID)
+	note over fconf: use statically defined policies in bl1
+	fconf <- bl_common : image_info
+	deactivate bl_common
+	note over fconf : get tb_fw_config_dtb from image_info
+	fconf -> arm_bl1_setup
+	arm_bl1_setup -> plat_bl1_common : bl1_plat_get_image_desc(BL2_IMAGE_ID)
+	arm_bl1_setup <- plat_bl1_common : BL2_IMAGE_DESC
+	note over arm_bl1_setup
+	set ep_info.args.arg0 of BL2_IMAGE_DESC
+	to FW_CONFIG base address
+	end note
+deactivate fconf
+
+== load & auth, prepare and jump to BL2 ==
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/fconf_bl2_populate.puml b/docs/resources/diagrams/plantuml/fconf_bl2_populate.puml
new file mode 100644
index 0000000..c536ee0
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/fconf_bl2_populate.puml
@@ -0,0 +1,49 @@
+@startuml
+
+box "BL2 common code"
+	participant bl2_entrypoint
+	participant bl2_main
+end box
+
+box "platform common code"
+	participant fconf
+	participant fconf_tbbr_getter
+participant fconf_dyn_cfg_getter
+end box
+
+box "arm platform code" #LightBlue
+	participant arm_bl2_setup
+	participant arm_io_storage
+	participant arm_fconf_io
+end box
+
+== bl2 setup ==
+bl2_entrypoint -> bl2_main : bl2_setup()
+bl2_main -> arm_bl2_setup : bl2_early_platform_setup2(\n\t arg0, arg1, arg2, arg3)
+note over arm_bl2_setup
+	arg0 = fw_config
+	arg1 = mem_layout
+end note
+arm_bl2_setup -> arm_bl2_setup : arm_bl2_early_platform_setup(\n\t fw_config, mem_layout)
+activate arm_bl2_setup
+	arm_bl2_setup -> fconf: fconf_populate("FW_CONFIG", fw_config)
+	activate fconf
+		fconf -> fconf_dyn_cfg_getter: populate_dtb_registry(uintptr_t dtb)
+		note over fconf_dyn_cfg_getter: read dtb_registry properties from dtb
+		fconf_dyn_cfg_getter -> arm_bl2_setup
+		arm_bl2_setup -> fconf: FCONF_GET_PROPERTY(dyn_cfg, dtb, TB_FW_CONFIG_ID)
+		fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(TB_FW_CONFIG_ID)
+		fconf_dyn_cfg_getter -> arm_bl2_setup: tb_fw_config_info
+		arm_bl2_setup -> fconf: fconf_populate("TB_FW_CONFIG", tb_fw_config)
+		fconf -> fconf_tbbr_getter: fconf_populate_tbbr_dyn_config(uintptr_t dtb)
+		note over fconf_tbbr_getter: read tbbr properties from dtb
+		fconf -> arm_fconf_io: fconf_populate_arm_io_policies(uintptr_t dtb)
+		note over arm_fconf_io: read arm io propeties from dtb
+	deactivate fconf
+	arm_bl2_setup -> arm_io_storage : plat_arm_io_setup()
+	note over arm_io_storage: use populated properties
+deactivate arm_bl2_setup
+
+== bl2 main ==
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/fip-secure-partitions.puml b/docs/resources/diagrams/plantuml/fip-secure-partitions.puml
new file mode 100644
index 0000000..9457e32
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/fip-secure-partitions.puml
@@ -0,0 +1,167 @@
+/'
+ ' Copyright (c) 2020, ARM Limited and Contributors. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+@startuml
+
+folder SP_vendor_1 {
+ artifact sp_binary_1
+ artifact sp_manifest_1 [
+ sp_manifest_1
+ ===
+ UUID = xxx
+ load_address = 0xaaa
+ owner = "Sip"
+ ...
+ ]
+}
+
+folder SP_vendor_2 {
+ artifact sp_binary_2
+ artifact sp_manifest_2 [
+ sp_manifest_2
+ ===
+ UUID = yyy
+ load_address = 0xbbb
+ owner = "Plat"
+ ]
+}
+
+artifact tb_fw_config.dts [
+ tb_fw_config.dts
+ ----
+ secure-partitions
+ ===
+ spkg_1 UUID
+ spkg_1 load_address
+ ---
+ spkg_2 UUID
+ spkg_2 load_address
+ ---
+ ...
+ ===
+ ...<rest of the nodes>
+]
+
+artifact config.json [
+ SP_LAYOUT.json
+ ===
+ path to sp_binary_1
+ path to sp_manifest_1
+ ---
+ path to sp_binary_2
+ path to sp_manifest_2
+ ---
+ ...
+]
+
+control sp_mk_generator
+
+artifact sp_gen [
+ sp_gen.mk
+ ===
+ FDT_SOURCE = ...
+ SPTOOL_ARGS = ...
+ FIP_ARGS = ...
+ CRT_ARGS = ...
+]
+
+control dtc
+control sptool
+
+artifact tb_fw_config.dtb
+
+artifact spkg_1 [
+ sp1.pkg
+ ===
+ <i>header</i>
+ ---
+ manifest
+ ---
+ binary
+]
+
+artifact spkg_2 [
+ sp2.pkg
+ ===
+ <i>header</i>
+ ---
+ manifest
+ ---
+ binary
+]
+
+artifact signed_tb_fw_config.dtb [
+ tb_fw_config.dtb (signed)
+]
+
+artifact signed_spkg_1 [
+ sp1.pkg (signed)
+ ===
+ <i>header</i>
+ ---
+ manifest
+ ---
+ binary
+ ---
+ <i>signature</I>
+]
+
+artifact signed_spkg_2 [
+ sp2.pkg (signed)
+ ===
+ <i>header</i>
+ ---
+ manifest
+ ---
+ binary
+ ---
+ <i>signature</I>
+]
+
+control crttool
+control fiptool
+
+artifact fip [
+ fip.bin
+ ===
+ tb_fw_config.dtb (signed)
+ ---
+ ...
+ ---
+ sp1.pkg  (signed & SiP owned)
+ ---
+ sp2.pkg  (signed & Platform owned)
+ ---
+ ...
+]
+
+config.json .up.> SP_vendor_1
+config.json .up.> SP_vendor_2
+config.json --> sp_mk_generator
+sp_mk_generator --> sp_gen
+sp_gen --> fiptool
+sp_gen --> cert_create
+sp_gen --> sptool
+
+sptool --> spkg_1
+sptool --> spkg_2
+
+spkg_1 --> cert_create
+spkg_2 --> cert_create
+cert_create --> signed_spkg_1
+cert_create --> signed_spkg_2
+
+tb_fw_config.dts --> dtc
+dtc --> tb_fw_config.dtb
+tb_fw_config.dtb --> cert_create
+cert_create --> signed_tb_fw_config.dtb
+
+signed_tb_fw_config.dtb --> fiptool
+signed_spkg_1 -down-> fiptool
+signed_spkg_2 -down-> fiptool
+fiptool -down-> fip
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/io_arm_class_diagram.puml b/docs/resources/diagrams/plantuml/io_arm_class_diagram.puml
new file mode 100644
index 0000000..53594c2
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/io_arm_class_diagram.puml
@@ -0,0 +1,109 @@
+@startuml
+
+package arm_io_storage {
+
+	class plat_io_policy {
+		dev_handle : uintptr_t*
+		image_spec : uintptr_t
+		{abstract} check() : fctptr
+	}
+
+	class FIP_IMAGE_ID {
+		memmap_dev_handle
+		fip_block_spec
+		open_memmap()
+	}
+
+	class BL2_IMAGE_ID{
+		fip_dev_handle
+		bl2_uuid_spec
+		open_fip()
+	}
+
+	class xxx_IMAGE_ID{
+		fip_dev_handle
+		xxx_uuid_spec
+		open_fip()
+	}
+
+	class arm_io_storage {
+		fip_dev_con : io_dev_connector_t*
+		fip_dev_handle : uintptr_t
+		memmap_dev_con : io_dev_connector_t*
+		memmap_dev_handle : uintptr_t
+
+		fip_block_spec : io_block_spec_t
+
+		policies : plat_io_policy[1..*]
+
+		-open_fip()
+		-open_memmap()
+
+		+arm_io_setup()
+		+plat_get_image_source()
+	}
+
+	FIP_IMAGE_ID -up-|> plat_io_policy
+	BL2_IMAGE_ID -up-|> plat_io_policy
+	xxx_IMAGE_ID -up-|> plat_io_policy
+
+	arm_io_storage *-"1..*" plat_io_policy
+}
+
+package IO {
+	class  io_storage {
+		io_dev_open()
+		io_dev_init()
+		io_dev_close()
+
+		.. synchronous operations ..
+		io_open()
+		io_seek()
+		io_size()
+		io_read()
+		io_write()
+		io_close()
+
+		io_register_device()
+	}
+
+	class io_fip {
+		register_io_dev_fip()
+		.. io_dev_funcs_t interface ..
+		fip_dev_funcs : io_dev_funcs_t
+	}
+
+	class io_memmap {
+		register_io_dev_memmap()
+		.. io_dev_funcs_t interface ..
+		memmap_dev_funcs : io_dev_funcs_t
+	}
+
+	interface io_driver {
+		io_entity_t
+		io_dev_info_t
+
+		.. io_dev_connector_t interface ..
+		dev_open()
+
+		.. io_dev_funcs_t interface ..
+			type()
+			open()
+			seek()
+			size()
+			read()
+			write()
+			close()
+			dev_init()
+			dev_close()
+
+		io_register_device()
+	}
+}
+arm_io_storage .. io_driver
+arm_io_storage .. io_fip
+arm_io_storage .. io_memmap
+arm_io_storage .. io_storage
+
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml b/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml
new file mode 100644
index 0000000..b7289a2
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml
@@ -0,0 +1,62 @@
+@startuml
+
+participant arm_io_storage
+participant io_storage
+
+ -> arm_io_storage : plat_get_image_source(image_id, &dev_handle, &image_spec)
+
+group init and check device (image_id)
+
+alt image_id = BL2_IMAGE_ID
+note over arm_io_storage
+	get BL2_IMAGE_ID policy:
+	- fip_dev_handle
+	- open_fip()
+end note
+opt policy->check()
+	arm_io_storage -> arm_io_storage : open_fip(spec)
+	activate arm_io_storage
+	arm_io_storage -> io_storage : io_dev_init(fip_dev_handle, FIP_IMAGE_ID)
+	ref over io_storage : dev_init() on fip device
+
+	arm_io_storage -> io_storage : io_open(fip_dev_handle, spec, &local_image_handle)
+	ref over io_storage : io_open() on fip device
+
+	arm_io_storage -> io_storage : io_close(local_image_handle)
+	ref over io_storage : io_close() on fip device
+
+	hnote over arm_io_storage
+		fip_dev_handle ready
+	end note
+end opt
+deactivate arm_io_storage
+
+else image_id = FIP_IMAGE_ID
+activate arm_io_storage
+note over arm_io_storage
+	get FIP_IMAGE_ID policy:
+	- memmap_dev_handle
+	- open_memmap()
+end note
+opt policy->check()
+	arm_io_storage -> arm_io_storage : open_memmap(spec)
+	activate arm_io_storage
+	arm_io_storage -> io_storage : io_dev_init(memmap_dev_handle, NULL)
+	ref over io_storage : dev_init() on memmap device
+
+	arm_io_storage -> io_storage : io_open(memmap_dev_handle, spec, &local_image_handle)
+	ref over io_storage : io_open() on memmap device
+
+	arm_io_storage -> io_storage : io_close(local_image_handle)
+	ref over io_storage : io_close() on memmap device
+
+	hnote over arm_io_storage
+		memmap_dev_handle ready
+	end note
+	deactivate arm_io_storage
+end  opt
+deactivate arm_io_storage
+end alt
+
+end group
+@enduml
diff --git a/docs/resources/diagrams/plantuml/io_dev_registration.puml b/docs/resources/diagrams/plantuml/io_dev_registration.puml
new file mode 100644
index 0000000..c6f330e
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/io_dev_registration.puml
@@ -0,0 +1,52 @@
+@startuml
+
+participant arm_io_storage
+participant io_storage
+participant io_fip
+participant io_memmap
+
+ -> arm_io_storage : arm_io_setup()
+
+group io dev registration
+
+arm_io_storage -> io_fip : register_io_dev_fip(&fip_dev_con)
+io_fip -> io_storage : io_register_device(&dev_info_pool[])
+note over io_storage
+	devices[dev_count] = (fip_)dev_info_pool
+	dev_count++
+end note
+
+arm_io_storage -> io_memmap : register_io_dev_memmap(&memmap_dev_con)
+io_memmap -> io_storage : io_register_device(&memmap_dev_info)
+note over io_storage
+	devices[dev_count] = memmap_dev_info
+	dev_count++
+end note
+
+arm_io_storage -> io_storage : io_dev_open(fip_dev_con, NULL, fip_dev_handle)
+ io_storage -> io_storage : dev_open(dev_con, dev_spec, handle)
+activate io_storage
+opt dev_open() on fip device
+	io_storage -> io_fip : fip_dev_open(dev_spec, dev_info)
+	note over io_fip
+		dev_info = one of the
+		"fip_dev_info" from
+		dev_info_pool[]
+	end note
+end opt
+deactivate io_storage
+
+
+arm_io_storage -> io_storage : io_dev_open(memmap_dev_con, NULL, memmap_dev_handle)
+io_storage -> io_storage : dev_open(dev_con, dev_spec, handle)
+activate io_storage
+opt dev_open() on memmap device
+	io_storage -> io_memmap : memmap_dev_open(dev_spec, dev_info)
+	note over io_memmap
+		dev_info = memmap_dev_info
+	end note
+end opt
+deactivate io_storage
+
+end group
+@enduml
diff --git a/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml b/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml
new file mode 100644
index 0000000..b21a0ae
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml
@@ -0,0 +1,59 @@
+@startuml
+
+participant bl_common
+participant arm_io_storage
+participant io_storage
+
+== Platform Setup ==
+
+bl1_main -> xxx_bl1_setup : bl1_platform_setup()
+xxx_bl1_setup -> arm_io_storage : plat_arm_io_setup()
+
+arm_io_storage -> arm_io_storage : arm_io_setup()
+ref over arm_io_storage, io_storage : io device registration
+
+== Get Image ==
+bl1_main -> xxx_bl1_setup : bl1_plat_get_next_image_id()
+bl1_main <-- xxx_bl1_setup : BL2_IMAGE_ID
+
+bl1_main -> bl1_main : bl1_load_bl2()
+activate bl1_main
+bl1_main -> plat_bl1_common : bl1_plat_get_image_desc(BL2_IMAGE_ID)
+bl1_main <-- plat_bl1_common : BL2_IMAGE_DESC
+
+bl1_main -> plat_bl1_common : bl1_plat_handle_pre_image_load(BL2_IMAGE_ID)
+
+bl1_main -> bl_common : load_auth_image(BL2_IMAGE_ID, image_info)
+activate bl_common
+bl_common -> bl_common : load_auth_image_internal(BL2_IMAGE_ID, image_info, is_parent_image)
+activate bl_common
+bl_common -> bl_common : load_image(BL2_IMAGE_ID, image_info)
+activate bl_common
+bl_common -> arm_io_storage : plat_get_image_source(BL2_IMAGE_ID, &dev_handle, &image_spec)
+ref over arm_io_storage, io_storage : init and check device (BL2_IMAGE_ID)
+bl_common <-- arm_io_storage : dev_handle
+
+bl_common -> io_storage : io_open(dev_handle, image_spec, &image_handle)
+ref over io_storage : io_open() on fip device
+bl_common <-- io_storage : image_handle
+bl_common -> io_storage : io_size(image_handle, &image_size)
+ref over io_storage : io_size() on fip device
+bl_common -> io_storage : io_read(image_handle, image_base, image_size, &bytes_read)
+ref over io_storage : io_read() on fip device
+bl_common -> io_storage : io_close(image_handle)
+ref over io_storage : io_close() on fip device
+bl_common -> io_storage : io_dev_close(dev_handle)
+ref over io_storage : io_dev_close() on fip device
+
+deactivate bl_common
+deactivate bl_common
+deactivate bl_common
+
+== Prepare Next Image ==
+bl1_main -> plat_bl1_common : bl1_plat_handle_post_image_load(BL2_IMAGE_ID)
+
+deactivate bl1_main
+
+== Jump to next Image ==
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.puml b/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.puml
new file mode 100644
index 0000000..90ff23c
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.puml
@@ -0,0 +1,51 @@
+/'
+ ' Copyright (c) 2017-2018, ARM Limited and Contributors. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+@startuml
+
+autonumber "<b>[#]</b>"
+participant "SDEI client" as EL2
+participant EL3
+participant SDEI
+participant "RAS Driver" as RAS
+
+activate EL2
+EL2->EL3: **SDEI_EVENT_REGISTER**(ev, handler, ...)
+EL3->EL2: success
+EL2->EL3: **SDEI_EVENT_ENABLE**(ev)
+EL3->EL2: success
+EL2->EL3: **SDEI_PE_UNMASK**()
+EL3->EL2: 1
+
+... <<Business as usual>> ...
+
+EL3<--]: **CRITICAL EVENT**
+activate EL3 #red
+note over EL3: Critical event triage
+EL3->RAS: dispatch to handle
+deactivate EL3
+activate RAS #salmon
+note over RAS: Critical event handling
+RAS-->SDEI: sdei_dispatch_event(ev)
+deactivate RAS
+activate SDEI #salmon
+note over SDEI: Prepare SDEI dispatch
+SDEI->EL2: dispatch
+activate EL2 #salmon
+note over EL2: SDEI handler
+EL2->SDEI: **SDEI_EVENT_COMPLETE()**
+deactivate EL2
+note over SDEI: Complete SDEI dispatch
+SDEI-->RAS: return
+deactivate SDEI
+activate RAS #salmon
+RAS->EL3: error handling done
+deactivate RAS
+EL3->EL2: resumes preempted execution
+
+... <<Normal execution resumes>> ...
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/sdei_general.puml b/docs/resources/diagrams/plantuml/sdei_general.puml
new file mode 100644
index 0000000..ab6929a
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/sdei_general.puml
@@ -0,0 +1,43 @@
+/'
+ ' Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+@startuml
+
+autonumber "<b>[#]</b>"
+participant "SDEI client" as EL2
+participant EL3
+participant "SDEI interrupt source" as SDEI
+
+activate EL2
+EL2->EL3: **SDEI_INTERRUPT_BIND**(irq)
+EL3->EL2: event number: ev
+EL2->EL3: **SDEI_EVENT_REGISTER**(ev, handler, ...)
+EL3->EL2: success
+EL2->EL3: **SDEI_EVENT_ENABLE**(ev)
+EL3->EL2: success
+EL2->EL3: **SDEI_PE_UNMASK**()
+EL3->EL2: 1
+
+... <<Business as usual>> ...
+
+SDEI-->EL3: SDEI interrupt
+activate SDEI #salmon
+activate EL3 #red
+note over EL3: Prepare SDEI dispatch
+EL3->EL2: dispatch
+activate EL2 #salmon
+note over EL2: SDEI handler
+EL2->EL3: **SDEI_EVENT_COMPLETE()**
+deactivate EL2
+note over EL3: Complete SDEI dispatch
+EL3-->SDEI: EOI
+deactivate SDEI
+EL3->EL2: resumes preempted execution
+deactivate EL3
+
+... <<Normal execution resumes>> ...
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/spm_dfd.puml b/docs/resources/diagrams/plantuml/spm_dfd.puml
new file mode 100644
index 0000000..ad4996e
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/spm_dfd.puml
@@ -0,0 +1,82 @@
+/'
+ ' Copyright (c) 2021, Arm Limited. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+/'
+TF-A SPMC Data Flow Diagram
+'/
+
+@startuml
+digraph tfa_dfd {
+
+    # Allow arrows to end on cluster boundaries
+    compound=true
+
+    # Default settings for edges and nodes
+    edge [minlen=2 color="#8c1b07"]
+    node [fillcolor="#ffb866" style=filled shape=box fixedsize=true width=1.6 height=0.7]
+
+    # Nodes outside of the trust boundary
+    nsec [label="NS Client"]
+    ddr  [label="External memory (DDR)"]
+
+    # Trust boundary cluster
+    subgraph cluster_trusted {
+        graph [style=dashed color="#f22430"]
+
+        # HW IPs cluster
+        subgraph cluster_ip {
+            label ="Hardware IPs";
+            graph [style=filled color="#000000" fillcolor="#ffd29e"]
+
+            rank="same"
+            gic [label="GIC" width=1.2 height=0.5]
+            smmu [label="SMMU" width=1.2 height=0.5]
+            uart [label="UART" width=1.2 height=0.5]
+	    pe [label="PE" width=1.2 height=0.5]
+        }
+
+        # TF-A cluster
+        subgraph cluster_tfa {
+            label ="EL3 monitor";
+            graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+            bl31 [label="BL31" fillcolor="#ddffb3"];
+            spmd [label="SPMD" fillcolor="#ddffb3" height=1]
+        }
+
+        # SPMC cluster
+        subgraph cluster_spmc {
+            label ="SPMC";
+            graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+            spmc [label="SPMC" fillcolor="#ddffb3" height=1]
+        }
+	bl2 [label="BL2" width=1.2 height=0.5]
+    }
+
+    # Secure Partitions cluster
+    subgraph cluster_sp {
+        label ="Secure Partitions";
+        graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+        sp1 [label="SP1" fillcolor="#ddffb3" height=1]
+        sp2 [label="SP2" fillcolor="#ddffb3" height=1]
+        spn [label="SP..." fillcolor="#ddffb3" height=1]
+    }
+
+    # Interactions between nodes
+    sp1 -> spmc [dir="both" label="DF1"]
+    spmc -> spmd [dir="both" label="DF2"]
+    spmd -> nsec [dir="both" label="DF3"]
+    sp1 -> sp2 [dir="both" label="DF4"]
+    spmc -> smmu [lhead=cluster_spmc label="DF5"]
+    bl2 -> spmc [lhead=cluster_spmc label="DF6"]
+    bl2 -> spn [lhead=cluster_spmc label="DF6"]
+    sp1 -> ddr [dir="both"  label="DF7"]
+    spmc -> ddr [dir="both"  label="DF7"]
+}
+
+@enduml
diff --git a/docs/resources/diagrams/plantuml/tfa_dfd.puml b/docs/resources/diagrams/plantuml/tfa_dfd.puml
new file mode 100644
index 0000000..0007911
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/tfa_dfd.puml
@@ -0,0 +1,66 @@
+/'
+ ' Copyright (c) 2021, Arm Limited. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+/'
+TF-A Data Flow Diagram
+'/
+
+@startuml
+digraph tfa_dfd {
+
+    # Arrange nodes from left to right
+    rankdir="LR"
+
+    # Allow arrows to end on cluster boundaries
+    compound=true
+
+    # Default settings for edges and nodes
+    edge [minlen=2 color="#8c1b07"]
+    node [fillcolor="#ffb866" style=filled shape=box fixedsize=true width=1.6 height=0.7]
+
+    # Nodes outside of the trust boundary
+    nsec [label="Non-secure\nClients"]
+    sec [label="Secure\nClients"]
+    dbg [label="Debug & Trace"]
+    logs [label="Logs\n(UART)"]
+    nvm [label="Non-volatile\nMemory"]
+
+    # Trust boundary cluster
+    subgraph cluster_trusted{
+        graph [style=dashed color="#f22430"]
+
+        # HW IPs cluster
+        subgraph cluster_ip{
+            label ="Hardware IPs";
+            graph [style=filled color="#000000" fillcolor="#ffd29e"]
+
+            rank="same"
+            gic [label="GIC" width=1.2 height=0.5]
+            tzc [label="TZ\nController" width=1.2 height=0.5]
+            etc [label="..." shape=none style=none height=0.5]
+        }
+
+        # TF-A cluster
+        subgraph cluster_tfa{
+            label ="TF-A";
+            graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+            bl1 [label="Boot ROM\n(BL1)" fillcolor="#ddffb3"];
+            bl2 [label="Trusted Boot\nFirmware\n(BL2)" fillcolor="#ddffb3" height=1]
+            bl31 [label="TF-A Runtime\n(BL31)" fillcolor="#ddffb3"]
+        }
+    }
+
+    # Interactions between nodes
+    nvm -> bl31 [lhead=cluster_tfa label="DF1"]
+    logs -> bl31 [dir="back" lhead=cluster_tfa label="DF2"]
+    dbg -> bl2 [dir="both" lhead=cluster_tfa label="DF3"]
+    sec -> bl2 [dir="both" lhead=cluster_tfa label="DF4"]
+    nsec -> bl1 [dir="both" lhead=cluster_tfa, label="DF5"]
+    bl2 ->  tzc [dir="both" ltail=cluster_tfa lhead=cluster_ip label="DF6" minlen=1]
+}
+
+@enduml