DOC: update documentation.
Add documentation covering:
- developer information about architecture
- project structure and building
- project overview and service descriptions
- the portability model for supporting hardware
Signed-off-by: Julian Hall <julian.hall@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@gmail.com>
Change-Id: I8bf9c01a66350719d82a7ca2bc1c78a8ab17978d
diff --git a/docs/uml/colors.puml b/docs/uml/colors.puml
new file mode 100644
index 0000000..7b1238c
--- /dev/null
+++ b/docs/uml/colors.puml
@@ -0,0 +1,30 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+' Colors shared between various graphs
+
+!define COLOR_ARM_BLUE #0091BD
+!define COLOR_LT_BLUE b3edff
+
+' The higher the number at the end of the name the darker the color is.
+!define COLOR_BLUE1 #DCEEF3
+!define COLOR_BLUE2 #B9DDE7
+!define COLOR_BLUE3 #96CDDB
+!define COLOR_GREEN1 #EBF1E0
+!define COLOR_GREEN2 #DEF2B8
+!define COLOR_GREY1 #D9D9D9
+!define COLOR_GREY2 #F2F2F2
+!define COLOR_RED1 #FF9C9C
+!define COLOR_RED2 #FFD6D6
+
+!define COLOR_PSA_NW COLOR_GREY1
+!define COLOR_PSA_S_APP_ROT COLOR_GREEN1
+!define COLOR_PSA_S_PSA_ROT COLOR_BLUE2
+!define COLOR_PSA_S_ROT_PERIPHERAL COLOR_BLUE1
+!define COLOR_PSA_NS_PE COLOR_NW
+!define COLOR_PSA_FW_API COLOR_RED2
+!define COLOR_PSA_ROT_SERVICE_API COLOR_RED1
diff --git a/docs/uml/libsp_functions.puml b/docs/uml/libsp_functions.puml
new file mode 100644
index 0000000..b46cc01
--- /dev/null
+++ b/docs/uml/libsp_functions.puml
@@ -0,0 +1,118 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+class ffa_internal_api {
+ .. SVC call ..
+ + ffa_svc()
+}
+
+package "FF-A layer" {
+ class ffa_api {
+ .. Setup and discovery interfaces ..
+ + ffa_version()
+ + ffa_features()
+ + ffa_rx_release()
+ + ffa_rxtx_map()
+ + ffa_rxtx_unmap()
+ + ffa_partition_info_get()
+ + ffa_id_get()
+
+ .. CPU cycle management interfaces ..
+ + ffa_msg_wait()
+
+ .. Messaging interfaces ..
+ + ffa_msg_send_direct_req()
+ + ffa_msg_send_direct_resp()
+
+ .. Memory management interfaces ..
+ + ffa_mem_donate()
+ + ffa_mem_donate_rxtx()
+ + ffa_mem_lend()
+ + ffa_mem_lend_rxtx()
+ + ffa_mem_share()
+ + ffa_mem_share_rxtx()
+ + ffa_mem_retrieve_req()
+ + ffa_mem_retrieve_req_rxtx()
+ + ffa_mem_relinquish()
+ + ffa_mem_reclaim()
+
+ .. Interrupt handler definition ..
+ + ffa_interrupt_handler()
+ }
+
+ class ffa_memory_descriptors {
+ .. Transaction buffer handling ..
+ + ffa_init_mem_transaction_buffer()
+
+ .. Transaction descriptor ..
+ + ffa_init_mem_transaction_desc()
+ + ffa_get_mem_transaction_desc()
+
+ .. Memory access descriptor ..
+ + ffa_reserve_mem_access_desc()
+ + ffa_add_mem_access_desc()
+ + ffa_get_mem_access_desc_count()
+ + ffa_get_mem_access_desc()
+
+ .. Memory region ..
+ + ffa_add_memory_region()
+ + ffa_get_memory_region()
+ }
+}
+
+package "SP layer" {
+ class sp_rxtx {
+ .. RXTX buffer handling ..
+ + sp_rxtx_buffer_map()
+ + sp_rxtx_buffer_unmap()
+ + sp_rxtx_buffer_alignment_boundary_get()
+ + sp_rxtx_buffer_rx_get()
+ + sp_rxtx_buffer_tx_get()
+ }
+
+ class sp_memory_management {
+ .. Donate ..
+ + sp_memory_donate()
+ + sp_memory_donate_dynamic()
+ + sp_memory_donate_dynamic_is_supported()
+
+ .. Lend ..
+ + sp_memory_lend()
+ + sp_memory_lend_dynamic()
+ + sp_memory_lend_dynamic_is_supported()
+
+ .. Share ..
+ + sp_memory_share()
+ + sp_memory_share_dynamic()
+ + sp_memory_share_dynamic_is_supported()
+
+ .. Retrieve ..
+ + sp_memory_retrieve()
+ + sp_memory_retrieve_dynamic()
+ + sp_memory_retrieve_dynamic_is_supported()
+
+ .. Relinquish ..
+ + sp_memory_relinquish()
+
+ .. Reclaim ..
+ + sp_memory_reclaim()
+ }
+}
+
+
+ffa_api -left-> ffa_internal_api
+
+ffa_api -[hidden]-> ffa_memory_descriptors
+
+sp_rxtx -left-> ffa_api
+sp_memory_management --> ffa_api
+sp_memory_management -left-> ffa_memory_descriptors
+sp_memory_management -up-> sp_rxtx
+
+@enduml
diff --git a/docs/uml/style-component.puml b/docs/uml/style-component.puml
new file mode 100644
index 0000000..9400e93
--- /dev/null
+++ b/docs/uml/style-component.puml
@@ -0,0 +1,28 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+!include colors.puml
+
+'Comonent diagram definitions
+!define NS_COMPONENT component COLOR_GREY2
+!define NS_IFC interface COLOR_GREY2
+!define S_COMPONENT component COLOR_BLUE1
+!define S_IFC interface COLOR_BLUE1
+
+skinparam component {
+ ArrowColor black
+ BorderColor black
+}
+
+skinparam interface {
+ BorderColor black
+}
+
+skinparam BackgroundColor COLOR_ARM_BLUE
+
+@enduml