diff options
Diffstat (limited to '')
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 |