EL3 Firmware Test framework Design
==================================

Contents :

1.  Global code structure
2.  Detailed code structure
3.  Interrupts management
4.  Limitations of the Test Framework

- - - - - - - - - - - - - - - - - -

1.  Global Code Structure
-------------------------

The code is organised into the following categories (present as directories at
the top level):

*   **Drivers.**
*   **Framework.** Core features of the test framework.
*   **Library code.** Comprise of functionality offered by the framework to the
    tests.
*   **Platform specific.** Choice of architecture-specific code depends upon
    the platform.
*   **Tests.**

The tests are divided into the following categories (present as directories in
the `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. This includes tests
    against the Standard Service (to which PSCI belongs to) and the Trusted OS
    service for now.
*   **Tutorial tests.** Sample test code showing how to write tests in practice.
    Serves as documentation of the tests API.

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`.


2.  Detailed Code Structure
---------------------------

The EL3 firmware is expected to hand over to the Test Framework with all
secondary cores powered down, i.e. only the primary core should enter the TFTF.
The cold boot entry point is `tftf_entrypoint` (see `framework/aarch64/
entrypoint.S`).

Tests can power on other CPUs using the function `tftf_cpu_on()`. This uses
the PSCI CPU_ON API to the EL3 Firmware. When entering the Normal World,
execution starts at the warm boot entry point, which is `tftf_hotplug_entry()`
(see `framework/aarch64/entrypoint.S`).

TODO: talk about lead CPU

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 `TEST_NVM` in `framework/include/nvm.h`):

    * test_to_run

      Reference to the test to run.

    * test_progress

      Progress in the execution of test_to_run.

    * 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.


3.  Interrupts management
-------------------------

The test framework expects SGIs #0 to #7 to be available for its use. 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
disabled, these tests will leave the system in an unresponsive state.


4.  Limitations of the Test Framework
-------------------------------------

This section lists the main limitations the test framework suffers from at the
moment and how they will be addressed in the future.

*   The lead CPU is not configurable, it is always the primary CPU.
    In the future, it will be possible to specify the lead CPU for each test
    through the `tests/tests.xml` file.

*   If for any reason a test hangs, execution will be stuck forever.
    In the future, we will add watchdog support, which will allow the framework
    to detect when a test time-outs and take corrective actions (e.g. platform
    reset) to get out of this situation and continue the test session.