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/service-locator.rst b/docs/developer/service-locator.rst
new file mode 100644
index 0000000..8064913
--- /dev/null
+++ b/docs/developer/service-locator.rst
@@ -0,0 +1,169 @@
+Service Locator
+===============
+
+The service locator model provides clients of trusted services with a common interface for locating service instances and
+establishing RPC sessions with service endpoints. By using the service locator, application code is decoupled from the details
+of where services are deployed. Use of the service locator is entirely optional for client applications. Different deployments
+of *libts* provide implementations of the service locator API that are suitable for different environments. The trusted
+services project uses *libts* to decouple test code from the services under test. This enables tests to be reused for testing
+on different platforms with different distributions of services. The same flexibility may be exploited when writing
+applications that use trusted services.
+
+Service Locator Model
+---------------------
+
+The following class diagram illustrates the service locator model:
+
+.. uml:: uml/ServiceLocatorClassDiagram.puml
+
+The model takes inspiration from microservices architectures where there is a similar need to decouple clients from service
+location. In the model, classes have the following roles:
+
+Class service_locator
+'''''''''''''''''''''
+
+The service_locator is responsible for locating service provider instances and returning a service_context object to allow a
+client to establish RPC sessions with the located service endpoint. A service instance is requested by a client using a service
+name. The service name uniquely identifies a service instance, independent of where the service provider is located. The
+service_locator is a singleton and forms the common interface for locating trusted services.
+
+Class service_context
+'''''''''''''''''''''
+
+A service_context object represents a located service and enables a service client to establish RPC sessions with the service.
+A concrete service_context will provide open and close methods that manage RPC session setup and teardown.
+
+Class rpc_caller
+''''''''''''''''
+
+An rpc_caller provides methods for making remote calls associated with a service endpoint. An rpc_caller object represents an
+instance of an RPC session.
+
+Locating Service Instances
+--------------------------
+
+The location of service instances is likely to vary between deployments. Many factors influence where a service instance is
+deployed and the method needed to locate it. e.g.:
+
+ - The type of processing environment in which a service instance is deployed. e.g. service could be deployed in a secure
+ partition, as a TA or in a secure enclave.
+ - Whether a service instance is co-located with other services instances in the same processing environment or whether a
+ separate environment instance is used per service instance.
+ - For Linux user-space clients, the kernel driver model used for messaging influences how a service is located and the type
+ of messaging interface used for RPC requests.
+
+Because of the wide variability in service deployment options, the Trusted Services framework supports the following:
+
+ - *Location independent service names* - a naming convention for identifying service instances, wherever they are located.
+ By using a location independent service name, a client is decoupled from the actual location of a service instance
+ (similar to a DNS names). A concrete service locator is responsible for resolving the location independent service name.
+ - *Service location strategies* - to accommodate the likely variability, an extensible framework for alternative service
+ location strategies is provided.
+
+Service Names
+'''''''''''''
+
+Location Independent Service Names
+``````````````````````````````````
+
+Because of the potential variability in where service instances are deployed, a naming convention that allows a service instance
+to be identified, independent of its location, is useful. By using a location independent service name, coupling between a
+client application and any particular service deployment can be avoided. Use of the Service Locator API and location
+independent service names allows client applications to be portable across different platforms.
+
+The service instance naming convention uses a URN type string to uniquely identify a particular instance of a class of service.
+To provide extensibility, a naming authority is included in the name. This allows anyone with a domain name to define their own
+unique service names. Core service names are defined under the *trustedfirmware.org* authority. The general structure of a
+service name is as follows::
+
+ urn:sn:<authority>:<service>.<version>:<instance>
+
+ The 'urn' prefix should be dropped when service names are used in context.
+ The version field is optional.
+
+The naming convention includes a version number, separated from the <service> field by a '.' character. Beyond the '.', any
+version numbering scheme may be used. This will potentially be useful for delegating version compatibility decisions to a
+service locator. It is preferable for a client to specify a service name that includes a version number as this will
+potentially allow a service locator to:
+
+ - Locate a compatible service instance. For example, a service provider may expose multiple RPC call endpoints to handle
+ different protocol versions. A service locator may resolve the name to the compatible RPC endpoint, based on the version
+ string requested by the client.
+ - Fail gracefully if no compatible version is found.
+
+Some example service names::
+
+ sn:trustedfirmware.org:crypto.1.0.4:0
+ sn:trustedfirmware.org:secure-storage.1.3.11:1
+ sn:trustedfirmware.org:tpm.2.0:0
+
+Location Specific Service Names
+```````````````````````````````
+
+To enable a client to be able to specify location specific service names, it should also be possible to use names that express a
+location specific identifier such as a partition UUID. While use of location specific services names creates a coupling between
+the client and details of the service deployment, their use may be important in the following cases:
+
+ - Where there is no well-known mapping between a location independent service name and a location specific identifier.
+ - Where the client needs to be specific e.g. for tests that target a specific service deployment.
+
+Location specific service names use the same structure as location independent services names but with a technology specific
+authority field. The following is an example of a service name that identifies a service instance that is deployed in a secure
+partition::
+
+ sn:ffa:d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0:0
+
+ The instance field qualified a particular SP instance from the discovered set.
+
+Service Location Strategies
+'''''''''''''''''''''''''''
+
+The method used by the service locator to resolve a service name to a service instance will depend on the environment in which a
+client is running and where service instances are located. Services will need to be located by any client of a trusted service.
+There are typically two classes of trusted service client:
+
+ - A user-space application.
+ - Another trusted service, running in a secure processing environment.
+
+Different methods for locating service instances in different environments are illustrated in the following examples:
+
+Locating a Service from Linux User-space
+````````````````````````````````````````
+
+Depending on the kernel driver model used, the example methods for locating service instances from Linux user-space are:
+
+ 1. Service instances are represented by device nodes e.g. /dev/tpm0. The service locator will simply map the <service>
+ portion of the services name to the base device name and the <instance> to the device node instance.
+ 2. A service instance is hosted by a TEE as a TA. The TEE will provide a discovery mechanism that will allow a TA type and
+ instance to be identified. The service locator will need to map the service name to the TEE specific naming scheme.
+ 3. A special device that provides messaging provides a method for discovery. e.g. an FF-A driver supports partition
+ discovery.
+ 4. A device is used for remote messaging to a separate microcontroller. There is a well-known protocol for endpoint
+ discovery using the messaging layer.
+
+Locating a Service from another Trusted Service
+```````````````````````````````````````````````
+
+Where a trusted service uses another trusted service, it is likely that both service instances will be running in the same
+security domain e.g. both running in secure partitions within the secure world. Where a single service instance is deployed per
+secure partition, the client service will use the following strategy to locate the service provider:
+
+ 1. The service name is mapped to the well known UUID for the class of SP that hosts the service provider.
+ 2. FF-A partition discovery is used to find all SPs that match the requested UUID.
+ 3. The service instance portion of the service name is used to match the partition ID when selecting the target SP from the
+ list of discovered SPs.
+
+Extending the Service Locator Model
+```````````````````````````````````
+
+To accommodate the need to support alternative location strategies, the Service Locator model can be extended to use a set of
+concrete strategy objects to implement different methods of locating a service instance. The set of strategies used will be
+different for different client environments. The following class diagram illustrates how the model can be extended.
+
+.. uml:: uml/ServiceLocationStrategyClassDiagram.puml
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause