Trusted Firmware-A Tests, version 2.0
This is the first public version of the tests for the Trusted
Firmware-A project. Please see the documentation provided in the
source tree for more details.
Change-Id: I6f3452046a1351ac94a71b3525c30a4ca8db7867
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Co-authored-by: amobal01 <amol.balasokamble@arm.com>
Co-authored-by: Antonio Nino Diaz <antonio.ninodiaz@arm.com>
Co-authored-by: Asha R <asha.r@arm.com>
Co-authored-by: Chandni Cherukuri <chandni.cherukuri@arm.com>
Co-authored-by: David Cunado <david.cunado@arm.com>
Co-authored-by: Dimitris Papastamos <dimitris.papastamos@arm.com>
Co-authored-by: Douglas Raillard <douglas.raillard@arm.com>
Co-authored-by: dp-arm <dimitris.papastamos@arm.com>
Co-authored-by: Jeenu Viswambharan <jeenu.viswambharan@arm.com>
Co-authored-by: Jonathan Wright <jonathan.wright@arm.com>
Co-authored-by: Kévin Petit <kevin.petit@arm.com>
Co-authored-by: Roberto Vargas <roberto.vargas@arm.com>
Co-authored-by: Sathees Balya <sathees.balya@arm.com>
Co-authored-by: Shawon Roy <Shawon.Roy@arm.com>
Co-authored-by: Soby Mathew <soby.mathew@arm.com>
Co-authored-by: Thomas Abraham <thomas.abraham@arm.com>
Co-authored-by: Vikram Kanigiri <vikram.kanigiri@arm.com>
Co-authored-by: Yatharth Kochar <yatharth.kochar@arm.com>
diff --git a/docs/design.rst b/docs/design.rst
new file mode 100644
index 0000000..a59c1d7
--- /dev/null
+++ b/docs/design.rst
@@ -0,0 +1,266 @@
+Trusted Firmware-A Tests - Design
+=================================
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+This document provides some details about the internals of the TF-A Tests
+design. It is incomplete at the moment.
+
+Global overview of the TF-A tests behaviour
+-------------------------------------------
+
+The EL3 firmware is expected to hand over to the TF-A tests with all secondary
+cores powered down, i.e. only the primary core should enter the TF-A tests.
+
+The primary CPU initialises the platform and the TF-A tests internal data
+structures.
+
+Then the test session begins. The TF-A tests are executed one after the
+other. Tests results are saved in non-volatile memory as we go along.
+
+Once all tests have completed, a report is generated. The TF-A tests currently
+supports 2 report formats:
+
+- Raw output, i.e. text messages over serial console.
+
+- Junit output, i.e. XML file generated over semihosting. This is useful when a
+ post-processing tool needs to parse the test report, as it is more
+ machine-friendly than the raw output.
+
+The report format to use is chosen at build time. For more information,
+refer to the section `Summary of build options`_ in the User Guide.
+
+Global Code Structure
+---------------------
+
+The code is organised into the following categories (present as directories at
+the top level or under the ``tftf/`` directory):
+
+- **Drivers.**
+
+ Some examples follow, this list might not be exhaustive.
+
+ - Generic GIC driver.
+
+ ``arm_gic.h`` contains the public APIs that tests might use. Both GIC
+ architecture versions 2 and 3 are supported.
+
+ - PL011 UART driver.
+
+ - VExpress NOR flash driver.
+
+ Note that tests are not expected to use this driver in most
+ cases. Instead, they should use the ``tftf_nvm_read()`` and
+ ``tftf_nvm_write()`` wrapper APIs. See definitions in
+ ``tftf/framework/include/nvm.h``. See also the NVM validation test cases
+ (``tftf/tests/framework_validation_tests/test_validation_nvm.c``) for an
+ example of usage of these functions.
+
+ - SP805 watchdog.
+
+ Used solely to generate an interrupt that will reset the system on purpose
+ (used in ``tftf_plat_reset()``).
+
+ - SP804 timer.
+
+ This is used as the system timer on Juno. It is configured such that an
+ interrupt is generated when it reaches 0. It is programmed in one-shot
+ mode, i.e. it must be rearmed every time it reaches 0.
+
+- **Framework.**
+
+ Core features of the test framework.
+
+- **Library code.**
+
+ Some examples of APIs provided in ``include/lib/`` follow, this list might
+ not be exhaustive.
+
+ - ``aarch64/``
+
+ Architecture helper functions for e.g. system registers access, cache
+ maintenance operations, MMU configuration, ...
+
+ - ``events.h``
+
+ Events API. Used to create synchronisation points between CPUs in tests.
+
+ - ``irq.h``
+
+ IRQ handling support. Used to configure IRQs and register/unregister
+ handlers called upon reception of a specific IRQ.
+
+ - ``power_management.h``
+
+ Power management operations (CPU ON/OFF, CPU suspend, etc.).
+
+ - ``sgi.h``
+
+ Software Generated Interrupt support. Used as an inter-CPU communication
+ mechanism.
+
+ - ``spinlock.h``
+
+ Lightweight implementation of synchronisation locks. Used to prevent
+ concurrent accesses to shared data structures.
+
+ - ``timer.h``
+
+ Support for programming the timer. Any timer which is in the `always-on`
+ power domain can be used to exit CPUs from suspend state.
+
+ - ``tftf_lib.h``
+
+ Miscellaneous helper functions/macros: MP-safe ``printf()``, low-level
+ PSCI wrappers, insertion of delays, raw SMC interface, support for writing
+ a string in the test report, macros to skip tests on platforms that do not
+ meet topology requirements, etc.
+
+ - ``semihosting.h``
+
+ Semihosting support.
+
+ - ``io_storage.h``
+
+ Low-level IO operations. Tests are not expected to use these APIs
+ directly. They should use higher-level APIs like ``tftf_nvm_read()``
+ and ``tftf_nvm_write()``.
+
+ ``include/stdlib/`` provides standard C library functions (``memcpy()``,
+ ``printf()``, and so on).
+
+- **Platform specific.**
+
+ Note that ``include/plat/common/plat_topology.h`` provides the interfaces
+ that a platform must implement to support topology discovery (i.e. how many
+ CPUs and clusters there are).
+
+- **Tests.**
+
+The tests are divided into the following categories (present as directories in
+the ``tftf/tests/`` directory):
+
+- **Framework validation tests.**
+
+ Tests that exercise the core features of the framework. Verify that the test
+ framework itself works properly.
+
+- **Runtime services tests.**
+
+ Tests that exercise the runtime services offered by the EL3 Firmware to the
+ Normal World software. For example, this includes tests for the Standard
+ Service (to which PSCI belongs to), the Trusted OS service or the SiP
+ service.
+
+- **CPU extensions tests.**
+
+ Tests some CPU extensions features. For example, the AMU tests ensure that
+ the counters provided by the Activity Monitor Unit are behaving correctly.
+
+- **Firmware Update tests.**
+
+ Tests that exercise the `Firmware Update`_ feature of TF-A.
+
+- **Template tests.**
+
+ Sample test code showing how to write tests in practice. Serves as
+ documentation.
+
+- **Performance tests.**
+
+ Simple tests measuring the latency of an SMC call.
+
+- **Miscellaneous tests.**
+
+ Tests for RAS support, correct system setup, ...
+
+All assembler files have the ``.S`` extension. The linker source file has the
+extension ``.ld.S``. This is processed by GCC to create the linker script which
+has the extension ``.ld``.
+
+Detailed Code Structure
+-----------------------
+
+The cold boot entry point is ``tftf_entrypoint`` (see
+``tftf/framework/aarch64/entrypoint.S``). As explained in section `Global
+overview of the TF-A tests behaviour`_, only the primary CPU is expected to
+execute this code.
+
+Tests can power on other CPUs using the function ``tftf_cpu_on()``. This uses
+the PSCI ``CPU_ON`` API of the EL3 Firmware. When entering the Normal World,
+execution starts at the warm boot entry point, which is ``tftf_hotplug_entry()``
+(see ``tftf/framework/aarch64/entrypoint.S``).
+
+Information about the progression of the test session and tests results are
+written into Non-Volatile Memory as we go along. This consists of the following
+data (see struct ``tftf_state_t`` typedef in ``tftf/framework/include/nvm.h``):
+
+- ``test_to_run``
+
+ Reference to the test to run.
+
+- ``test_progress``
+
+ Progress in the execution of ``test_to_run``. This is used to implement the
+ following state machine:
+
+::
+
+ +-> TEST_READY (initial state of the test) <--------------+
+ | | |
+ | | Test framework prepares the test environment. |
+ | | |
+ | v |
+ | TEST_IN_PROGRESS |
+ | | |
+ | | Hand over to the test function. |
+ | | If the test wants to reboot the platform ---> TEST_REBOOTING |
+ | | | |
+ | | Test function returns into framework. | Reboot |
+ | | | |
+ | | +---------+
+ | v
+ | TEST_COMPLETE
+ | |
+ | | Do some framework management.
+ | | Move to next test.
+ +--------+
+
+- ``testcase_buffer``
+
+ A buffer that the test can use as a scratch area for whatever it is doing.
+
+- ``testcase_results``
+
+- ``result_buffer_size``
+
+- ``result_buffer``
+
+ Buffer holding the tests output. Tests output are concatenated.
+
+Interrupts management
+---------------------
+
+The TF-A tests expect SGIs #0 to #7 to be available for their own usage. In
+particular, this means that Trusted World software must configure them as
+non-secure interrupts.
+
+SGI #7 has a special status. It is the SGI that the timer management framework
+sends to all CPUs when the system timer fires off (see the definition of the
+constant ``IRQ_WAKE_SGI`` in the header file ``include/lib/irq.h``). Although
+test cases can use this specific SGI - e.g. they can register an IRQ handler for
+it and use it as an inter-CPU communication mechanism - they have to be aware of
+the underlying consequences. Some tests, like the PSCI ``CPU_SUSPEND`` tests,
+rely on this SGI to be enabled in order to wake up CPUs from their suspend
+state. If it is disabled, these tests will leave the system in an unresponsive
+state.
+
+--------------
+
+*Copyright (c) 2018, Arm Limited. All rights reserved.*
+
+.. _Summary of build options: user-guide.html#summary-of-build-options
+.. _Firmware Update: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst