1Service Deployment Model
2========================
3
4A goal of the Trusted Services project is to provide a toolbox of reusable service components
5that can be deployed across a wide range of platforms. The project structure promotes reuse by
6grouping related source files into subdirectories that represent reusable components. Components
7may be configured and combined in different ways to meet the needs of platform integrators who
8aim to create firmware with the right features and tradeoffs for their products.
9
10Within the TS project structure, build files that combine and configure components to create
11deployable firmware images reside under the deployments top-level directory. Beneath the
12deployments parent are sub-directories concerned with building and deploying different
13applications. Applications can generally be classified as one of the following:
14
15  - Service providers (e.g. psa-crypto)
16  - Test suites (e.g. ts-service-test)
17  - Libraries (e.g. libts)
18  - Development support applications (e.g. fwu-tool)
19
20This page is mainly concerned with describing the conventions used to enable service providers
21to be deployed in different environments, on different platforms and with different capabilities.
22The conventions aim to minimize build definition duplication between alternative deployments
23while offering sufficient flexibility to customize capabilities and support different platforms.
24
25Ports and Adapters Architecture
26-------------------------------
27
28An application is decoupled from any particular environment via a set of interfaces that reflect
29the needs of the application. This model conforms to the ports and adapters architectural
30pattern that aims to avoid tight coupling between application components and any particular
31environment. This pattern, also known as the hexagonal architecture, is often illustrated as a
32hexagonal cell with the application on the inside and the platform on the outside.
33
34The following diagram illustrates how ports and adapters is applied in the trusted services
35project to provide a model for service provider deployment.
36
37.. image:: image/TSportabilityModel.svg
38
39This deployment model has the following characteristics:
40
41  - The application is decoupled from the environment by a set of virtual interfaces (ports)
42    that reflect the needs of the application.
43  - Ports are realized by a set of adapters. An adapter may:
44
45      * Use a service/device provided by the platform or environment.
46      * Communicate with another service provider.
47      * Provide a self-contained implementation.
48  - The set of adapters that the application depends on represents the infrastructure that is
49    needed to support the application.
50  - Different infrastructure realizations may be needed for different deployments of the same
51    service provider.
52
53Service Deployment Structure
54----------------------------
55
56By convention, the directory structure for service provider deployments reflects the layers in
57the ports and adapters architecture. The following dependency diagram illustrates the set of
58relationships that exist for a fully defined deployment:
59
60.. uml:: uml/ServiceDeploymentDependencies.puml
61
62To avoid undesirable build definition duplication when adding new deployments of an application,
63the directory structure used to organize files related to different deployments should reflect
64the above model. The following table lists reusable build components that may be used across
65different deployment definitions:
66
67.. list-table::
68  :widths: 10 20 20
69  :header-rows: 1
70
71  * - Build Component
72    - Defines
73    - Reuse Scope
74  * - Deployment
75    - | Represents an application. Examples: a service provider, demo application, test application,
76      | some tool.
77    - | -
78  * - Infrastructure
79    - | A specific set of SW components that realize the ports that the application depends on.
80      | An infrastructure definition may depend on:
81
82        * Drivers that conform to a driver model.
83    - | Any deployment that uses the same infrastructure to support the application.
84      | This will depend on how specific the infrastructure is.  An infrastructure
85      | definition may allow for some level of configurability to enable a deployment
86      | to impose a particular build configuration. Where an infrastructure includes
87      | adapters that use a well supported driver model (such as UEFI), the scope
88      | for reuse is large.
89  * - Environment
90    - | The set of environment specific components that are common across all
91      | deployments of an application for a particular environment.
92    - | All deployments of the application into a specific environment. There is
93      | scope to improve reuse of environment specific components across multiple
94      | deployments.
95  * - Configuration
96    - | Build configuration variables together with a particular application, infrastructure
97      | and environment. Represents a specific build of the application.
98    - | None.
99  * - Platform
100    - | A specific set of hardware drivers and target platform specific settings.
101      | A platform definition may depend on:
102
103            * Hardware driver ports defined by various components.
104            * Hardware specific resources.
105            * Target specific resource selection.
106    - | None.
107
108Deployment Directory Structure
109------------------------------
110Using the block-storage deployment as an example, the deployment directory structure reflects
111the service deployment model as follows::
112
113  deployments
114      |- block-storage
115              |- block-storage.cmake     - Common application build definition
116              |- env                     - Environment specific build definitions
117              |- infra                   - Alternative infrastructures
118              |- config                  - Configurations for block-storage deployments
119
120Configuration Definitions
121^^^^^^^^^^^^^^^^^^^^^^^^^
122To build a particular configuration of the block-storage service provider (in this case, one
123that uses flash storage emulated with semihosting on the AEM FVP platform), use::
124
125  cd deployments/block-storage/config/semihosted-opteesp
126  cmake -B build
127  cmake --build build
128
129The CMakeLists.txt file for the n1sdp-flash deployment of the block-storage service provider
130includes:
131
132  - Set TS_PLATFORM to n1sdp platform name
133  - Set any build configuration parameter overrides
134  - Include ``${DEPLOYMENT_ROOT}/env/opteesp.cmake``
135  - Include ``${DEPLOYMENT_ROOT}/infra/edk2-flash.cmake``
136  - Include ``${DEPLOYMENT_ROOT}/block-storage.cmake``
137
138Each alternative deployment of the block-storage service provider is represented by a
139subdirectory under ``${DEPLOYMENT_ROOT}/config``. The number of directories under config is
140likely to grow to accommodate platform variability and different tradeoffs for how the infrastructure
141for an application will be realized.
142
143To support test and to provide a starting point for new config definitions, a default config should
144exist for each supported environment.
145
146Infrastructure Definitions
147^^^^^^^^^^^^^^^^^^^^^^^^^^
148An infrastructure defines a set of adapter components that realize the ports that the application
149depends on. For block-storage deployments, some possible infrastructures are:
150
151.. list-table::
152  :header-rows: 1
153  :widths: 10, 40
154
155  * - Infra Name
156    - Description
157  * - ref-ram
158    - Provides volatile storage using the reference partition configuration. Intended for test.
159  * - edk2-flash
160    - Provides persistent storage using a flash driver that conforms to the EDK2 driver model.
161  * - tfa-flash
162    - Provides persistent storage using a flash driver that conforms to the TF-A driver model.
163  * - rpmb
164    - Provides persistent storage using an RPMB partition, accessed via a Nwd agent.
165
166Platform Support
167----------------
168The Trusted Services project is not intended to be a home for platform specific code such as
169device drivers. Ideally, device drivers and other platform specific code should be reused
170from external upstream repos such as edk2-platforms. The ports and adapters pattern allows
171alternative driver models to be accommodated so different upstream projects with different
172driver models may be used without the need to modify driver code. Where driver reuse from
173an external project is not possible, the platform directory structure can accommodate driver
174components that reside within the TS project.
175
176The ability to accommodate third-party device drivers that conform to different driver models
177is important for enabling TS components to be used across different segments. The EDK2
178project for example can provide a rich source of drivers that conform to the UEFI model.
179UEFI is not however adopted in all product segments.
180
181All files related to supporting different platforms reside beneath the platform top-level
182directory.
183
184Platform Providers
185^^^^^^^^^^^^^^^^^^
186Within the TS project, a platform provider is responsible for adding and maintaining the
187glue that enables platform specific code to be used from a particular source. The platform
188code will either be:
189
190  - Fetched from an upstream repo (preferred)
191  - Added to the TS project.
192
193Each platform provider is represented by a subdirectory beneath ``platform/providers``. For
194Arm provided platforms, the structure will look something like this::
195
196  platform
197      |-- providers
198              |--arm
199                  |-- Corstone1000
200                  |-- fvp
201                      |-- fvp_base_aemva
202                      |-- fvp_base_revc-2xaemv8a
203                                  |-- platform.cmake
204
205Under each platform leaf directory is a file called ``platform.cmake``. This file implements
206the common configuration and build interface that will be used during the deployment build
207process. How this interface is realized is entirely down to the platform provider. An
208implementation will do things like setting configuration variables for SoC, board and driver
209selection. Any additional files needed to support platform configuration and build may be
210included within the platform provider's sub-tree.
211
212For product developers who want to define and maintain their own private platforms, it should
213be possible to override the default ``platform/providers`` directory path to allow an
214alternative sub-tree to be used.  A product developer is free to organize a private sub-tree
215in any way that suites their needs.
216
217Although the TS project structure doesn't mandate it, platform specific firmware is likely
218to live outside of the TS project. The ability to reuse existing drivers and driver frameworks
219is important for promoting adoption across hardware from different vendors.  Board and silicon
220vendors may reuse existing CI and project infrastructure for platform components that they
221maintain.
222
223Platform support that depends on EDK2 platform components is represented by the edk2 platform
224provider. Files related to the EDK2 platform provider are organized as follows::
225
226  platform
227    |- providers
228          |- edk2
229              |- edk2-platforms.cmake            - Fetches the upstream edk2-platforms repo
230              |- platform                        - Directory for platform definitions, organized by contributor
231                    |- arm
232                        |- n1sdp
233                              |- platform.cmake
234
235Some special platforms are provided by the TS project itself. These are represented beneath
236the ts provider. Current TS platforms are:
237
238.. list-table::
239  :header-rows: 1
240  :widths: 10, 90
241
242  * - TS Platform
243    - Purpose
244  * - ``ts/vanilla``
245    - | A platform that never provides any drivers. The ``ts/vanilla`` platform should be used when an environment provides its own
246      | device framework and no additional drivers need to be provided by the platform. An attempt to build a deployment with
247      | platform dependencies on the vanilla platform will result in a build-time error. The vanilla platform is selected by
248      | default at build-time if no explicit platform has been specified.
249  * - ``ts/mock``
250    - | A platform that provides a complete set of drivers that may be selected when building any deployment. The platform uses
251      | mock drivers that don't offer functionality suitable for production builds. The mock platform is useful for CI build
252      | testing of deployments with platform dependencies. You should always expect a deployment with platform dependencies to
253      | build when ``TS_PLATFORM=ts/mock``.
254
255Diver Models
256^^^^^^^^^^^^
257Alternative driver models are represented by subdirectories beneath ``platform/driver_model``.
258Driver code imported from an external project, such as edk2-platforms, will also depend on
259interface and other header files related to the driver model.  For drivers reused from
260edk2-platforms, the driver interface header files will define interface structures defined
261by the UEFI specification. The following example illustrates two driver models, one for
262UEFI drivers from the EDK2 project and another for bare-metal drivers that conform to TS
263defined interfaces::
264
265  platform
266    |- driver_model
267            |- edk2
268            |- baremetal
269
270Header files under the driver_model/edk2 directory will either explicitly provide definitions for
271the EDK2 driver model or include definitions from an external component. To maintain compatibility
272with driver code imported from edk2-platforms, sub-directories beneath platform/driver_model/edk2
273should conform to the EDK2 directory structure and naming conventions. The following illustrates
274how UEFI driver model files are organized::
275
276  platform
277    |- driver_model
278            |- edk2
279                |- interface
280                        |- Protocol
281                        |      |- BlockIo.h
282                        |      |- DiskIo.h
283                        |      |- FirmwareVolumeBlock.h
284                        |
285                        |- Library
286                        |      |- IoLib.h
287                        |      |- DebugLib.h
288
289Drivers
290^^^^^^^
291The platforms/drivers directory provides a home for CMake files that enable driver code to be built
292as part of the the deployment build process. Source files will either have been fetched from an
293upstream repo or will live under the ``platform/drivers`` parent.
294
295--------------
296
297*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.*
298
299SPDX-License-Identifier: BSD-3-Clause
300