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/developer/arch-overview.rst b/docs/developer/arch-overview.rst
new file mode 100644
index 0000000..d2f8c4d
--- /dev/null
+++ b/docs/developer/arch-overview.rst
@@ -0,0 +1,79 @@
+Architecture Overview
+=====================
+
+The Trusted Services project provides a framework for developing applications that can be built and deployed in
+different secure processing environments and on different hardware platforms. The structure and conventions adopted
+are designed to maximize opportunities for component reuse. The project adopts a portability model based on the
+*ports and adapters* architectural pattern, which promotes loose coupling between an application
+and its environment. The model allows applications to be deployed in a diverse range of environments from full
+featured trusted OSs, such as OP-TEE, to bare metal secure partitions.
+
+For a more in-depth description of how the ports and adapters pattern is applied, see:
+:ref:`Portability Model`
+
+Service Model
+-------------
+
+Trusted services conform to a client/server model where service specific operations are invoked using an RPC mechanism.
+The realization of the RPC layer and any underlying messaging layer may vary between deployments but the service layer
+should be identical for every deployment of a particular service. The following diagram illustrates the common layered
+model and where standardization on layer interfaces and protocols will be aimed for.
+
+.. image:: image/TrustedServicesLayers.svg
+
+The layered service model is reflected in the project source tree where software components are organized by layer and role.
+Because components that perform the same role are inter-changeable, there is much flexibility to meet the needs of
+different deployments. For example:
+
+ - An instance of the secure storage service could be accessed by different types of client, each presenting
+ different upper edge APIs to suite the needs of different applications. Some different secure storage clients
+ could be:
+
+ - A filesystem driver that presents a filesystem mount for user-space access to stored objects.
+ - A client that presents the PSA Protected Storage API.
+
+ - Different types of secure storage provider are possible, each accessed using a common protocol. Some different
+ secure storage providers could be:
+
+ - A secure storage provider that uses an external RPMB serial flash device for storage.
+ - A secure storage provider that encrypts objects before passing them to a normal world agent to access
+ file-backed storage.
+
+ - Different RPC layers may be used to access services deployed in different secure processing environments.
+
+Service Deployments
+-------------------
+
+The ability to deploy trusted services over a range of secure processing environments allows a consistent view of
+services to be presented to clients, independent of the back-end implementation. For a particular service deployment, a
+concrete set of build-time and run-time dependencies and configurations must be defined. Representing each deployment
+in the project structure allows multiple deployments to be supported, each reusing a subset of shared components.
+The following diagram illustrates the dependencies and configurations that must be defined for a fully specified
+deployment.
+
+.. uml:: uml/ServiceDeployment.puml
+
+Currently supported deployments are listed here:
+:ref:`Deployments`
+
+Service Access Protocols
+------------------------
+
+As mentioned in the section on layering, trusted services are accessed by clients via an RPC layer. Independent of the
+mechanics of the RPC layer, a service access protocol is defined by:
+
+ - A supported set of operations, each qualified by an opcode.
+ - A set of request and response message parameter definitions, one for each operation.
+
+The main documentation page for service access protocols is here: :ref:`Service Access Protocols`.
+
+The trusted service framework can accommodate the use of arbitrary serializations for message parameters. So far,
+message protocols using Google Protocol Buffers and packed C structures have been defined.
+
+.. image:: image/ServiceAccessProto.svg
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause