summaryrefslogtreecommitdiffstats
path: root/docs/resources/diagrams/plantuml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
commit102b0d2daa97dae68d3eed54d8fe37a9cc38a892 (patch)
treebcf648efac40ca6139842707f0eba5a4496a6dd2 /docs/resources/diagrams/plantuml
parentInitial commit. (diff)
downloadarm-trusted-firmware-upstream.tar.xz
arm-trusted-firmware-upstream.zip
Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/resources/diagrams/plantuml')
-rw-r--r--docs/resources/diagrams/plantuml/bl2-loading-sp.puml44
-rw-r--r--docs/resources/diagrams/plantuml/el3_spm_dfd.puml78
-rw-r--r--docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml78
-rw-r--r--docs/resources/diagrams/plantuml/fconf_bl2_populate.puml49
-rw-r--r--docs/resources/diagrams/plantuml/fip-secure-partitions.puml167
-rw-r--r--docs/resources/diagrams/plantuml/io_arm_class_diagram.puml109
-rw-r--r--docs/resources/diagrams/plantuml/io_dev_init_and_check.puml62
-rw-r--r--docs/resources/diagrams/plantuml/io_dev_registration.puml52
-rw-r--r--docs/resources/diagrams/plantuml/io_framework_usage_overview.puml59
-rw-r--r--docs/resources/diagrams/plantuml/sdei_explicit_dispatch.puml51
-rw-r--r--docs/resources/diagrams/plantuml/sdei_general.puml43
-rw-r--r--docs/resources/diagrams/plantuml/spm_dfd.puml82
-rw-r--r--docs/resources/diagrams/plantuml/tfa_dfd.puml66
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