Update documentation

The following modifications have been made to the User Guide:

 - List `libxml-libxml-perl` as a required package to build the TFTF
 - Add instructions to build a FIP containing the TFTF image
 - Add instructions to run the Test Framework
 - Provide a global overview of the Test Framework's behaviour

The following modifications have been made to the Design Document:

 - Move part of the old documentation to this document
 - Add a note about the special status of SGI #IRQ_WAKE_SGI
 - List the main limitations of the test framework

Also provide a new document explaining briefly how to develop tests.

Change-Id: Iece24d733a29c4b416d3f6cf55b4916d9ee9d2e0

1 files changed, 100 insertions, 3 deletions

diff --git a/docs/design.md b/docs/design.md
index 37cf3ba..9f789e1 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -3,10 +3,15 @@ EL3 Firmware Test framework Design
 
 Contents :
 
-1.  Code structure
+1.  Global code structure
+2.  Detailed code structure
+3.  Interrupts management
+4.  Limitations of the Test Framework
 
-1.  Code Structure
--------------------
+- - - - - - - - - - - - - - - - - -
+
+1.  Global Code Structure
+-------------------------
 
 The code is organised into the following categories (present as directories at
 the top level):
@@ -34,3 +39,95 @@ the `tests/` directory):
 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
+
+Tests results are written into NVM as we go along. The following data is saved
+(see struct `TEST_NVM` in `framework/include/nvm.h`):
+
+    * current_testcase
+
+      Contains the function pointer of the current test. It is set up just
+      before starting the execution of the test and reset after the test has
+      completed. This is used to detect when the previous test session crashed:
+      if current_testcase is not empty when the platform is brought up
+      then it means that a test crashed/timed out during last run.
+
+    * next_testcase
+
+      Contains the function pointer of the next test to run. It is used
+      to allow a test session to be interrupted and resumed later:
+      if next_testcase is not empty when the platform is brought up
+      then it means that the last test session is not over and TFTF will
+      try to resume test execution where it has been left.
+
+    * 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.
+
+*   The system timer must be programmed only by the primary CPU.
+    The system timer IRQ is configured to target the primary CPU only. Other
+    CPUs won't receive this interrupt. The function `tftf_systimer_fire_in()`,
+    used to program the system timer to fire in a given amount of time, should
+    only be called by the primary CPU. Other CPUs can request to receive a
+    notification when the system timer fires off using the function
+    `tftf_register_sgi_wake_interrupt()`.
+
+    In the future, it will be possible to migrate the timer management framework
+    to any CPU.