1 files changed, 106 insertions, 0 deletions
diff --git a/documentation/globalplatform_api.md b/documentation/globalplatform_api.md
new file mode 100644
index 0000000..f8ed8d7
--- /dev/null
+++ b/documentation/globalplatform_api.md
@@ -0,0 +1,106 @@
+GlobalPlatform API and OP-TEE
+=============================
+
+Contents :
+
+1. Introduction
+2. TEE Client API
+3. TEE Internal API
+
+# 1. Introduction
+[GlobalPlatform](http://www.globalplatform.org) works across industries to
+identify, develop and publish specifications which facilitate the secure and
+interoperable deployment and management of multiple embedded applications on
+secure chip technology. OP-TEE has support for GlobalPlatform [TEE Client API
+Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp) and
+[TEE Internal API Specification
+v1.0](http://www.globalplatform.org/specificationsdevice.asp).
+
+# 2. TEE Client API
+The TEE Client API describes and defines how a client running in a rich
+operating environment (REE) should communicate with the TEE. To identify a
+Trusted Application (TA) to be used, the client provides an
+[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier). All TA's
+exposes one or several functions. Those functions corresponds to a so called
+`commandID` which also is sent by the client. 
+
+### TEE Contexts
+The TEE Context is used for creating a logical connection between the client and
+the TEE. The context must be initialized before the TEE Session can be
+created. When the client has completed a jobs running in secure world, it should
+finalize the context and thereby also releasing resources.
+
+### TEE Sessions
+Sessions are used to create logical connections between a client and a specific
+Trusted Application. When the session has been established the client have a
+opened up the communication channel towards the specified Trusted Application
+identified by the `UUID`. At this stage the client and the Trusted Application
+can start to exchange data.
+
+
+### TEE Client API example / usage
+Below you will find the main functions as defined by GlobalPlatform and which
+are used in the communication between the client and the TEE.
+
+#### TEE Functions
+``` c
+TEEC_Result TEEC_InitializeContext(
+	const char*
+	name,
+	TEEC_Context* context)
+
+void TEEC_FinalizeContext(
+	TEEC_Context* context)
+
+TEEC_Result TEEC_OpenSession (
+	TEEC_Context* context,
+	TEEC_Session* session,
+	const TEEC_UUID* destination,
+	uint32_t connectionMethod,
+	const void* connectionData,
+	TEEC_Operation* operation,
+	uint32_t* returnOrigin)
+
+void TEEC_CloseSession (
+	TEEC_Session* session)
+
+TEEC_Result TEEC_InvokeCommand(
+	TEEC_Session* session,
+	uint32_t commandID,
+	TEEC_Operation* operation,
+	uint32_t* returnOrigin)
+```
+
+In principle the commands are called in this order:
+
+	TEEC_InitializeContext(...)
+	TEEC_OpenSession(...)
+	TEEC_InvokeCommand(...)
+	TEEC_CloseSession(...)
+	TEEC_FinalizeContext(...)
+
+It is not uncommon that `TEEC_InvokeCommand` is called several times in row
+when the session has been established.
+
+For a complete example, please see chapter **5.2 Example 1: Using the TEE
+Client API** in the GlobalPlatform [TEE Client API
+Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp).
+
+
+# 3. TEE Internal API
+The Internal API is the API that is exposed to the Trusted Applications running
+in the secure world. The TEE Internal API consists of four major parts:
+
+1. **Trusted Storage API for Data and Keys**
+2. **Cryptographic Operations API**
+3. **Time API**
+4. **Arithmetical API**
+
+### Examples / usage
+Calling the Internal API is done in the same way as described above using Client API.
+The best place to find information how this should be done is in the
+[TEE Internal API Specification
+v1.0](http://www.globalplatform.org/specificationsdevice.asp) which contains a
+lot of examples of how to call the various APIs.
+
+