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