1Project Structure
2=================
3
4This page describes the directory and repository structure for the trusted services project.
5
6Top-Level Project Organization
7------------------------------
8The project is organized under the following top-level directories::
9
10    project
11        |-- docs
12        |-- deployments
13        |-- environments
14        |-- platforms
15        |-- components
16        |-- external
17        |-- protocols
18        |-- tools
19
20Top-level directories are used to organize project files as follows:
21
22docs
23''''
24
25The home for project documentation source.
26
27deployments
28'''''''''''
29
30A deployment represents the build instance of a service (or in fact any unit of functionality) for a particular
31environment.  For each deployment, there is a single deployable output, usually a binary executable.  The
32deployment is concerned with configuring and building a particular set of components to run in a particular
33environment.  For each supported deployment, there is a leaf sub-directory that lives under a parent.  The
34parent directory identifies what's being deployed while the leaf sub-directory identifies where it is being
35deployed.  The following example illustrates how the 'what' and 'where' are combined to form fully defined
36deployments::
37
38    deployment-name = <descriptive-name>/<environment>
39
40    deployments
41        |-- protected-storage/opteesp
42        |-- crypto/opteesp
43        |-- crypto/sp
44        |-- ts-demo/arm-linux
45        |-- component-test/linux-pc
46        |-- libts/linux-pc
47
48The trusted services project uses CMake to configure and generate build files.  A CMakeLists.txt file exists
49for each deployment to define the set of components, any deployment specific configuration and anything
50environment specific.  Each deployment leaf directory also holds a source file that defines the main entry
51point to allow a particular set of components to be initialized before entering the application that implements
52the core functionality of software being deployed.
53
54The directory structure for deployments supports inheritance from the deployment parent to promote reuse of
55common definitions and initialization code.  For example, deployments of the secure-storage service for
56different environments are likely to have similarities in terms of the set of components used and in subsystem
57initialization code.  To avoid duplication between deployments, common cmake and source files may be located
58under the deployment parent.  This is illustrated in the following::
59
60    deployments
61        |-- secure-storage
62                |-- common.cmake            <-- Common cmake file
63                |-- service_init.c          <-- Common initialization code
64                |-- opteesp
65                |       |-- CMakeLists.txt      <-- Includes ../common.cmake to inherit common definitions
66                |       |-- opteesp_service_init.c
67                |-- sp
68                        |-- CMakeLists.txt      <-- Includes ../common.cmake to inherit common definitions
69                        |-- opteesp_service_init.c
70
71environments
72''''''''''''
73
74An environment represents the execution context in which a built image runs.  There are different environments
75represented in the project structure, one for each supported isolated execution context.  Files related to a
76particular environment live under a sub-directory whose name describes the environment.  For example:
77
78    - *opteesp*         An S-EL0 secure partition hosted by OP-TEE
79    - *sp*              SPMC agnostic S-EL0 secure partition
80    - *arm-linux*       Linux user-space, cross compiled for Arm.
81    - *linux-pc*        Native PC POSIX environment
82
83Files related to an environment will tend to live outside of the project tree and will need to be imported
84in some way.  How this is handled will depend on the environment.  An environment will generally provide the
85following:
86
87    - Environment specific libraries that have been externally built.
88    - Public header files for libraries.
89    - An install method that takes a deployment image and installs it in the environment.
90    - Compiler configuration
91
92A deployment will include an environment specific build file (see above) that defines the list of environment
93specific components used for a deployment into a particular environment.
94
95opteesp
96"""""""
97
98The opteesp environment uses a very similar SP format to the OP-TEE Trusted Applications. It is an ELF file with an OP-TEE
99specific header structure at its beginning. The SP image is relocatable and it is handled by the ELF loader (ldelf) component
100of OP-TEE. Naturally this environment only works with OP-TEE in the role of the SPMC.
101
102sp
103""
104
105Deployments that use the sp environment can produce SPMC agnostic SP images. This environment generates SP images as flat
106binaries that can be loaded without an ELF loader. The initialization of the stack and the handling of relocation must be done
107in the startup code of the SP. Setting the memory access rights of different sections of the SP image can be either done
108thought load relative memory regions in the manifest or by using the ``FFA_MEM_PERM_SET`` interface of the FF-A v1.1
109specification in the boot phase of the SP.
110
111Trusted Services first builds ELF files for the sp environment deployments and then it generates the memory region nodes of the
112manifest based on the sections of the ELF file. The sections of the ELF is then copied into the flat binary image. The
113environment provides the startup file so all the necessary initialization steps are done before the ``sp_main`` call.
114
115platforms
116'''''''''
117
118For some deployments, an environment may not provide access to all hardware backed services needed by an
119application.  Files under the platforms directory are concerned with configuring and building platform specific
120code that extends the capabilities of an environment.  Details of how this works are described in the:
121:ref:`Service Deployment Model`
122
123components
124''''''''''
125
126Source code lives under the components directory, organized as reusable groups of source files.  A component
127is the unit of reuse for code that may be combined with other components to realize the functionality needed
128for a deployment.  Creating a new deployment should be just a case of selecting the right set of components
129to provide the required functionality for the target environment.  Some components may depend on other
130components and others may only make sense in a particular environment.
131
132The components sub-tree has an organization that reflects the layered model where service components are
133kept separate from RPC components and so on.  There is also a separation between client components and service
134provider components.  The following illustrates this::
135
136    components
137        |-- service
138        |   |-- common
139        |   |       |-- test
140        |   |-- secure-storage
141        |   |       |-- frontend
142        |   |       |-- backend
143        |   |       |-- factory
144        |   |       |-- test
145        |   |-- crypto
146        |   |       |-- client
147        |   |               |- component.cmake
148        |   |       |-- provider
149        |-- rpc
150        |   |-- common
151        |   |-- ffarpc
152        |   |       |-- caller
153        |   |       |-- endpoint
154
155Each leaf directory under the components parent includes a cmake file called component.cmake.  This is used to
156define all files that make up the component and any special defines that are needed to build it.  A deployment
157CMakeLists.txt just needs to reference the required set of components.  No details of the component internals
158are reflected in the deployment CMakeLists.txt file.
159
160Test components
161'''''''''''''''
162
163Test code is treated in exactly the same as any other source code and is organized into components to achieve
164the same reuse goals.  To create a deployment intended for testing, you select an appropriate set of components
165where some happen to be test components.  By convention, test components live in sub-directories called test.
166Test directories are located at the point in the components sub-tree that reflects the scope of tests.  In the
167above example, two test sub-directories are illustrated.  The locations of the test component directories imply
168the following about the scope of the tests::
169
170    components
171        |-- service
172        |   |-- common
173        |   |       |-- test        <-- Tests for the common service component
174        |   |-- secure-storage
175        |   |       |-- frontend
176        |   |       |-- backend
177        |   |       |-- factory
178        |   |       |-- test        <-- Service level tests for the secure-storage service
179
180If it is necessary to componentize tests further, sub-directories under the test directory may be used, say
181for different classes of test. e.g::
182
183    components
184        |-- service
185            |-- common
186                    |-- test
187                        |-- unit
188                        |-- fuzz
189
190external
191''''''''
192
193Code that originates from other open source projects that needs to be built as part of trusted service
194deployments is represented by directories beneath the external top-level directory.  External components
195are generally fetched from the source repo during the CMake build process.  During the build for a particular
196deployment, a deployment specific configuration may be applied to an external component.   A CMake file under
197each external component directory is responsible for fetching and building the external component::
198
199    external
200        |-- CppUTest
201        |       |-- CppUTest.cmake
202        |       |-- cpputest-cmake-fix.patch
203        |-- mbed-crypto
204        |-- nanopb
205
206protocols
207'''''''''
208
209The protocols directory holds protocol definition files to allow clients to use trusted services.  Ideally,
210the service access protocol should be formally defined using an interface description language (IDL) that
211provides a programming language neutral definition of the service interface.  The protocols directory
212structure accommodates protocol definitions using different definition methods.  Where a service access
213protocol has been defined using an IDL with language compilation support, code may be generated from the
214interface description to allow RPC request and response parameters to be serialized and deserialized in a
215compatible way between service clients and providers.  The protocols sub-tree is organized as follows::
216
217    protocols
218        |-- service
219        |       |-- common
220        |       |-- crypto
221        |       |       |-- packed-c        <-- C structure based definitions
222        |       |       |-- protobuf        <-- Protocol Buffers definitions
223        |       |-- secure-storage
224        |               |-- packed-c
225
226tools
227'''''
228
229The project directory structure includes a tools directory for holding general purpose tools components
230to support activities such as build and test.
231
232--------------
233
234*Copyright (c) 2020-2023, Arm Limited and Contributors. All rights reserved.*
235
236SPDX-License-Identifier: BSD-3-Clause
237