Add "Loading and preparing TA for execution" section
Adds an overview of how TAs are initialized by ldelf. At the end of the
section there's also an overview of the steps involved when a client opens
a session to a new TA.
Reviewed-by: Jerome Forissier <jerome@forissier.org>
Reviewed-by: Joakim Bech <joakim.bech@linaro.org>
Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>
diff --git a/architecture/trusted_applications.rst b/architecture/trusted_applications.rst
index 44be1d2..e77c924 100644
--- a/architecture/trusted_applications.rst
+++ b/architecture/trusted_applications.rst
@@ -132,9 +132,14 @@
#define SHDR_GET_SIG(x) (SHDR_GET_HASH(x) + (x)->hash_size)
-The field ``image_type`` tells the type of TA, if it's ``SHDR_TA`` (0),
+The field ``img_type`` tells the type of TA, if it's ``SHDR_TA`` (0),
it's a legacy TA. If it's ``SHDR_BOOTSTRAP_TA`` (1) it's a bootstrap TA.
+The field ``algo`` tells the algorithm used. The script used to sign TAs
+currently uses ``TEE_ALG_RSASSA_PKCS1_V1_5_SHA256`` (0x70004830). This
+means RSA with PKCS#1v1.5 padding and SHA-256 hash function. OP-TEE accepts
+any of the ``TEE_ALG_RSASSA_PKCS1_*`` algorithms.
+
For bootstrap TAs ``struct shdr`` is followed by a subheader, ``struct
shdr_bootstrap_ta`` which is defined as:
@@ -211,6 +216,40 @@
$ xtest --install-ta
+Loading and preparing TA for execution
+**************************************
+
+User mode TAs are loaded into final memory in the same way using the user
+mode ELF loader ``ldelf``. The different TA locations has a common
+interface towards ``ldelf`` which makes the user mode operations identical
+regarless of how the TA is stored.
+
+The TA is loaded into secure memory in :ref:`prepare_ta`.
+
+.. _prepare_ta:
+
+.. figure:: ../images/trusted_applications/prepare_ta.png
+ :figclass: align-center
+
+ Preparing TA for execution
+
+After ``ldelf`` has returned with a TA prepared for execution it still
+remains in memory to serve the TA if dlopen() and friends are used.
+``ldelf`` is also used to dump stack trace and detailed memory mappings if
+a TA is terminated via an abort.
+
+A high level view of the entire flow from the client application in Linux
+user space where a session is opened to a TA is given in
+:ref:`open_session`.
+
+.. _open_session:
+
+.. figure:: ../images/trusted_applications/open_session.png
+ :figclass: align-center
+
+ Open session to a TA
+
+
.. _ta_properties:
TA Properties
diff --git a/images/trusted_applications/open_session.msc b/images/trusted_applications/open_session.msc
new file mode 100644
index 0000000..d73e8b8
--- /dev/null
+++ b/images/trusted_applications/open_session.msc
@@ -0,0 +1,38 @@
+# Generate with:
+# mscgen -T png -o images/trusted_applications/open_session.png \
+# images/trusted_applications/open_session.msc
+
+msc {
+ hscale = "2", wordwraparcs = on;
+
+ a [label = "client"],
+ b [label = "tee-supplicant"],
+ c [label = "kernel"],
+ d [label = "OP-TEE core"],
+ e [label = "ldelf"],
+ f [label = "TA"];
+
+ ||| ;
+ --- [ label = " Open a session to a TA "];
+ a=>c [ label = "TEEC_InitializeContext() /\nopen(/dev/teeX" ];
+ c>>a;
+ a=>c [ label = "TEEC_OpenSession() /\nioctl(TEE_IOC_OPEN_SESSION)" ];
+ c=>d [ label = "MSG_CMD_OPEN_SESSION" ];
+ d=>e [ label = "_ldelf_start" ];
+ e=>d [ label = "PTA_SYSTEM_OPEN_TA_BINARY" ];
+ d=>c [ label = "RPC_CMD_LOAD_TA" ];
+ c=>b [ label = "RPC_CMD_LOAD_TA" ];
+ b>>c;
+ c>>d;
+ d>>e;
+ e=>d [label = "PTA_SYSTEM_MAP_TA_BINARY" ];
+ d>>e;
+ e=>d [label = "PTA_SYSTEM_CLOSE_TA_BINARY" ];
+ d>>e;
+ e>>d [label = "return from _ldelf_start" ];
+ d=>f [label = "UTEE_ENTRY_FUNC_OPEN_SESSION" ];
+ f>>d;
+ d>>c [label = "return from MSG_CMD_OPEN_SESSION"];
+ c>>a [label = "return from TEEC_OpenSession()"];
+}
+
diff --git a/images/trusted_applications/open_session.png b/images/trusted_applications/open_session.png
new file mode 100644
index 0000000..70c297e
--- /dev/null
+++ b/images/trusted_applications/open_session.png
Binary files differ
diff --git a/images/trusted_applications/prepare_ta.msc b/images/trusted_applications/prepare_ta.msc
new file mode 100644
index 0000000..c520688
--- /dev/null
+++ b/images/trusted_applications/prepare_ta.msc
@@ -0,0 +1,42 @@
+# Generate with:
+# mscgen -T png -o images/trusted_applications/prepare_ta.png \
+# images/trusted_applications/prepare_ta.msc
+
+msc {
+ hscale = "2", wordwraparcs = on;
+
+ a [ label = "OP-TEE Core" ],
+ b [ label = "ldelf" ];
+
+ ||| ;
+ --- [ label = " Preparing TA from init_with_ldelf() "];
+ a=>b [ label = "_ldelf_start" ];
+ --- [ label = " Load main ELF "];
+ b=>a [ label = "PTA_SYSTEM_OPEN_TA_BINARY" ];
+ a=>a [ label = "Lookup user TA ELF in storages" ];
+ a>>b [ label = "return storage ELF handle" ];
+ b=>a [ label = "PTA_SYSTEM_MAP_TA_BINARY -- map ELF headers" ];
+ a>>b;
+ b=>b [ label = "parse ELF" ];
+ b=>a [ label = "PTA_SYSTEM_MAP_TA_BINARY -- map sections" ];
+ a>>b;
+ b=>a [ label = "PTA_SYSTEM_CLOSE_TA_BINARY" ];
+ b=>a [ label = "PTA_SYSTEM_MAP_ZI -- map zero initialized memory" ];
+ a>>b;
+ b=>a [ label = "PTA_SYSTEM_MAP_ZI -- map stack" ];
+ a>>b;
+ --- [ label = " Load dynamically linked library, repeat until done "];
+ a=>a [ label = "Lookup user TA ELF library in storages" ];
+ a>>b [ label = "return storage ELF handle" ];
+ b=>a [ label = "PTA_SYSTEM_MAP_TA_BINARY -- map ELF headers" ];
+ a>>b;
+ b=>b [ label = "parse ELF" ];
+ b=>a [ label = "PTA_SYSTEM_MAP_TA_BINARY -- map sections" ];
+ a>>b;
+ b=>a [ label = "PTA_SYSTEM_CLOSE_TA_BINARY" ];
+ b=>a [ label = "PTA_SYSTEM_MAP_ZI -- map zero initialized memory" ];
+ a>>b;
+ --- [ label = " TA and its library are loaded "];
+ b>>a [ label = "return to init_with_ldelf()" ];
+}
+
diff --git a/images/trusted_applications/prepare_ta.png b/images/trusted_applications/prepare_ta.png
new file mode 100644
index 0000000..bcbe896
--- /dev/null
+++ b/images/trusted_applications/prepare_ta.png
Binary files differ
