docs/design.rst - TF-A/tf-a-tests.git - Gitiles

 Framework Design
 ================

 This document provides some details about the internals of the TF-A Tests
 design. It is incomplete at the moment.

 .. _design_high_level_behaviour:

 High-Level 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 printed over the serial console.

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

    Firstly, there is ``include/libc/`` which provides standard C library
    functions like ``memcpy()``, ``printf()`` and so on.
    Additionally, various other APIs are provided under ``include/lib/``. The
    below list gives some examples but 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.

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

 -  **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
 :ref:`design_high_level_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.

 Interrupt 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-2019, Arm Limited. All rights reserved.*

 .. _Firmware update: https://trustedfirmware-a.readthedocs.io/en/latest/components/firmware-update.html
	Framework Design
	================

	This document provides some details about the internals of the TF-A Tests
	design. It is incomplete at the moment.

	.. _design_high_level_behaviour:

	High-Level 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 printed over the serial console.

	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.

	Firstly, there is ``include/libc/`` which provides standard C library
	functions like ``memcpy()``, ``printf()`` and so on.
	Additionally, various other APIs are provided under ``include/lib/``. The
	below list gives some examples but 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.

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

	- 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
	:ref:`design_high_level_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.

	Interrupt 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-2019, Arm Limited. All rights reserved.

	.. _Firmware update: https://trustedfirmware-a.readthedocs.io/en/latest/components/firmware-update.html