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/build-instructions.rst b/docs/developer/build-instructions.rst
new file mode 100644
index 0000000..5fe6c63
--- /dev/null
+++ b/docs/developer/build-instructions.rst
@@ -0,0 +1,140 @@
+Build Instructions
+==================
+All trusted service builds use CMake to create native build files for building and installing service binaries
+and other build products. Details about the tools needed for building are specified here:
+:ref:`Software Requirements`.
+
+All top-level build files are located beneath the 'deployments' parent directory under a sub-directory
+for each deployment. For more information about the project directory structure, see:
+:ref:`Project Structure`.
+
+Build Flow
+----------
+All deployment builds follow a common flow that results in the creation of executable binaries or libraries
+and the installation of files into an output directory. Deploying the contents of the output directory into
+the target environment is handled in an environment specific way and is not part of the common build
+flow. The build flow conforms to the conventional CMake process where building takes place in to following
+two stages:
+
+ 1. Native build files, such as makefiles, are generated from CMake configuration files.
+ 2. Native build tools, such as make, are used to build and install items, ready for deployment.
+
+The following activity diagram illustrates the common deployment build flow. The green activity states
+lie outside of the common build flow. Environment specific instructions are provided for deploying into
+different environments:
+
+.. uml:: uml/BuildFlow.puml
+
+Building and Installing
+-----------------------
+When building from a clean environment where no generated build files exist, it is necessary to run
+the CMake command, specifying the source directory, the build directory and optionally, the install
+directory where build output is installed.
+
+To illustrate the steps involved, we will build the 'component-test' executable to run in the
+'linux-pc' environment. The built executable is a standalone program that uses the CppUTest
+framework to run a set of component level tests on components from within the project. For this
+example, it is assumed that we are building under Linux and 'make' is used as the native build tool.
+
+The described steps may be used for any of the deployments under the top-level *deployments* directory.
+
+Starting from the project root directory, change directory to the relevant deployment directory::
+
+ cd deployments/component-test/linux-pc
+
+Build file generation is performed using the CMake command. If no CMAKE_INSTALL_PREFIX path is
+specified, build output will be installed in the default location (*build/install*). To generate
+build files that install to the default location, use::
+
+ cmake -S . -B build
+
+To generate build files that install to an alternative location, use::
+
+ cmake -S . -B build -DCMAKE_INSTALL_PREFIX=<install_dir>
+
+Having successfully generated build files, the native build tool may be run to build and install
+files using::
+
+ cd build
+ make install
+
+In the above example, all build output is written to a sub-directory called 'build'. You
+are free to choose any location for build output.
+
+Dependencies on external components and in-tree built objects, such as libraries,
+are handled automatically by the build system during the *generating* phase. External components
+are fetched from the relevant source repository and built as part of the build context for the
+deployment binary being built. This allows deployment specific configuration and compiler options
+to be applied to the external component without impacting other builds. Dependencies on in-tree
+built libraries are handled in a similar manner.
+
+For information on running tests, see:
+:ref:`Running Tests`.
+
+For more information on deployments, see:
+:ref:`Deployments`.
+
+Installed build output files
+----------------------------
+On successfully completing the *building* phase of the build flow, a set of build output files are
+installed to the directory specified by CMAKE_INSTALL_PREFIX. The set of installed files will
+depend on the type of build and the environment in which the files will be deployed. The following
+table summarizes what files are installed for different typed of build during the *installing* phase
+of the build flow:
+
+.. list-table:: Example build output files
+ :header-rows: 1
+
+ * - Deployment type
+ - Environment
+ - Files installed
+ * - Binary executable
+ - linux-pc, arm-linux
+ - | *bin/* - program binary
+ * - Shared library
+ - linux-pc, arm-linux
+ - | *include/* - public header files
+ | *lib/* - shared library
+ | *lib/cmake/* - cmake target import file
+ * - SP image
+ - opteesp
+ - | *bin/* - stripped elf file for SP
+ | *lib/make* - OP-TEE helper makefile
+ * - SP collection
+ - opteesp
+ - | *bin/* - set of stripped elf files
+ | *lib/make/* - set of OP-TEE helper makefiles
+
+
+Deploying installed files
+-------------------------
+Having built and installed build output files to a known directory, further steps may be needed to
+deploy the files into the target processing environment. The nature of these steps will be different
+for different environments.
+
+To avoid overly complicating the common Trusted Services build system, details of how installed files
+are deployed into the target execution environment are handled separately and may rely on environment
+specific tools.
+
+Some example deployment methods are:
+
+ * A filesystem share exists between a build machine and the target machine. Files installed into the shared directory are
+ directly accessible by the target.
+ * Installed files are incorporated into a third-party build process e.g. OP-TEE.
+
+The following guides provide instructions on deploying to different environments:
+
+* :ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE`
+* :ref:`Deploying Programs on FVP`
+
+Batch Building
+--------------
+To support batching building of a set of deployments, a tool called b-test is included. For
+more information, see
+:doc:`b-test page <./b-test>`
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause