Initial version of unit testing documentation
This commit includes the 'User guide' and 'Implementing tests' sections
for helping people building, running and writing unit tests. A more
detailed version of documentation is available under the 'Component
user manuals section'.
Change-Id: I67e93ac805d1f4e7727964f3d95a70436ae34733
Signed-off-by: Imre Kis <imre.kis@arm.com>
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index a3199d7..aec9b1d 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -1,10 +1,222 @@
-User Guide
+User guide
==========
-TODO: add text here
+This page describes how to get started with compiling and running unit tests on
+the host machine.
+
+Host machine requirements
+-------------------------
+
+The system has been successfully tested on the following platforms:
+
+- Ubuntu 19.04
+- Ubuntu 18.04
+- Arch Linux
+- MSYS2 MinGW64
+
+Tools
+-----
+
+The following applications are expected to be installed in the build machine:
+
+- CMake >=3.11
+
+- Python >=3.4
+
+- c-picker
+
+ - pyyaml
+
+ - clang (pip package if not included in libclang)
+
+ - libclang
+
+- git
+
+- Toolchain
+
+- Native build system
+
+Ubuntu 19.04
+^^^^^^^^^^^^
+
+On Ubuntu 19.04 use the following commands to install the required tools:
+
+::
+
+ sudo apt-get install cmake git python3 python3-pip libclang-dev build-essential
+ sudo pip3 install git+https://gerrit.oss.arm.com/iot-sw/shared/c-picker
+
+Ubuntu 18.04
+^^^^^^^^^^^^
+
+The official Ubuntu 18.04 package repository only contains CMake 3.10 which not
+satisfies the requirements for building unit tests. Fortunately there's an
+official CMake APT repository provided by Kitware: https://apt.kitware.com/ By
+adding this server to the repository list an up-to-date version of CMake can be
+installed on Ubuntu 18.04.
+
+::
+
+ wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc \
+ 2>/dev/null | sudo apt-key add -
+ sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
+
+ sudo apt-get install cmake git python3 python3-pip libclang-dev build-essential
+ sudo pip3 install git+https://gerrit.oss.arm.com/iot-sw/shared/c-picker
+
+Arch Linux
+^^^^^^^^^^
+
+On Arch Linux use the following commands to install the required tools:
+
+::
+
+ sudo pacman -Sy cmake git python python-pip python-yaml make gcc clang
+ sudo pip install git+https://gerrit.oss.arm.com/iot-sw/shared/c-picker
+
+MSYS2 MinGW64
+^^^^^^^^^^^^^
+
+::
+
+ pacman -Sy mingw-w64-x86_64-cmake git mingw-w64-x86_64-python3 \
+ mingw-w64-x86_64-python3-pip make mingw-w64-x86_64-gcc mingw-w64-x86_64-clang
+ pip install git+https://gerrit.oss.arm.com/iot-sw/shared/c-picker
+
+
+Getting unit test source code
+-----------------------------
+
+Download the unit test source code using the following command:
+
+::
+
+ git clone https://gerrit.oss.arm.com/trusted-firmware/tf-a-unit-tests.git
+
+
+Getting Trusted Firmware-A source code
+--------------------------------------
+
+Download the TF-A source code using the following command:
+
+::
+
+ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+
+
+Building unit tests
+-------------------
+
+Building unit tests start with running CMake which will check all the
+prerequisites and generate the native build system's input files. This example
+uses Unix Makefiles. Unit tests exercise the code directly by compiling it into
+the same binary as the test code. In this case the tests need to know where to
+find the TF-A source files and this is why the :cmake:variable:`TF_A_PATH` is
+specified.
+
+::
+
+ cd tf-a-unit-tests
+ mkdir build
+ cd build
+ cmake -DTF_A_PATH=../../trusted-firmware-a -G"Unix Makefiles" ..
+
+After running the previous steps the makefiles are generated into the build
+directory so make can build unit tests. During unit test development if only the
+source files have changed it's not necessary to re-run cmake it's only needed to
+run make as shown below.
+
+::
+
+ make -j
+
+For building single unit tests suites the test's name can be used as a makefile
+target. Let's assume there's a test suite called bl1_fwu.
+
+::
+
+ make bl1_fwu
+
+
+Running unit tests
+------------------
+
+CMake provides a built-in tool called ctest for running all the tests using a
+single command. It is also able to filter tests or run them in parallel for
+speeding up the tests process. Run all the tests using the following command:
+
+::
+
+ ctest
+
+Each unit test suite has its own executable. The easiest way of running single
+test suite is running it as a simple executable.
+
+::
+
+ ./bl1_fwu
+
+
+Debugging unit tests
+--------------------
+
+As it was mentioned in the previous section test suites are basically separate
+executables so they can be debugged as any other native applications on the host
+machine. In a Linux environment gdb or IDE's built-in debugger can be utilized
+for debugging.
+
+::
+
+ gdb ./bl1_fwu
+
+
+Measuring code coverage
+-----------------------
+
+Inspecting code coverage is a useful method for detecting parts of the code
+which is not exercised by tests. The build system includes an option for
+generating code coverage report of the unit tests. The coverage is processed by
+``lcov`` which needs to be installed for this feature. Also the coverage
+measurement in only available when GCC is used as a compiler.
+
+First of all the :cmake:variable:`COVERAGE` option has to be enabled by using
+the following command line when invoking CMake.
+
+::
+
+ cmake -DTF_A_PATH=../../trusted-firmware-a -DCOVERAGE=ON -G"Unix Makefiles" ..
+
+This makes CMake to build the binaries with coverage information included. The
+rest of the build process works the same way as before.
+
+Before collecting coverage info and generating reports the tests must be run as
+the coverage is a runtime measurement. See section `Running unit tests`_ for
+more information about running unit tests.
+
+The :cmake:variable:`COVERAGE` option adds two new build targets called
+``coverage`` and ``coverage_report``. They can be used simply by running the
+following commands if ``make`` is used as a build system.
+
+::
+
+ make coverage
+ make coverage_report
+
+The ``coverage`` target generates lcov info files for further processing. If
+there are coverage files available from different sources (i.e. coverages of
+other tests) they can be merged with the unit test coverage file and evaluated
+together. Currently two coverage info files are generated during the build. One
+of them contains the coverage of code under test (i.e. Trusted Firmware-A) and
+the other one has the coverage of the unit tests themselves.
+
+The ``coverage_report`` target generates a HTML report from the coverage info
+files. The coverage reports can be found in the build directory's subdirectories
+having ``-coverage`` suffix in their names. The report shows the directory
+structure of the code and each file can be inspected individually. Line,
+function and branch coverage is included.
+
--------------
-*Copyright (c) 2019, Arm Limited and Contributors. All rights reserved.*
-
-SPDX-License-Identifier: BSD-3-Clause
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*