Update documentation

Update the porting guide:
 * structure of the document
 * list platform #defines and functions to port

Update the user guide:
 * structure of the document
 * modify the build instructions to work around bug GENFW-385

Change-Id: Ia9bd7857ff2048a257ce26730be018beef01deb6

1 files changed, 203 insertions, 4 deletions

diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index 7582764..91af786 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -1,8 +1,207 @@
-*** tftf/tftf_platform.c
+EL3 Firmware Test framework Porting Guide
+=========================================
 
-    All functions in tftf/tftf_platform.c are weak definitions and most of
-    them do nothing. It is up to the platform to provide its own implementation
-    of those functions.
+Contents
+--------
+
+1.  Introduction
+2.  Platform requirements
+3.  Mandatory modifications
+4.  Optional modifications
+5.  Storage abstraction layer
+
+- - - - - - - - - - - - - - - - - -
+
+1.  Introduction
+----------------
+
+Porting the EL3 Firmware Test Framework to a new platform involves making some
+mandatory and optional modifications for both the cold and warm boot paths.
+Modifications consist of:
+
+*   Implementing a platform-specific function or variable,
+*   Setting up the execution context in a certain way, or
+*   Defining certain constants (for example #defines).
+
+The platform-specific functions and variables are all declared in
+[include/plat/common/platform.h]. The framework provides a default
+implementation of variables and functions to fulfill the optional requirements.
+These implementations are all weakly defined; they are provided to ease the
+porting effort. Each platform port can override them with its own implementation
+if the default implementation is inadequate.
+
+
+2.  Platform requirements
+-------------------------
+
+The Test Framework relies on the following features to be present on the
+platform and accessible from Normal World.
+
+*   Watchdog
+*   Non-Volatile Memory
+*   System Timer
+
+This also means that a platform port of the Test Framework must include software
+drivers for those features.
+
+
+3.  Mandatory modifications
+---------------------------
+
+### File : platform_def.h [mandatory]
+
+Each platform must ensure that a header file of this name is in the system
+include path with the following constants defined. This may require updating the
+list of `PLAT_INCLUDES` in the `platform.mk` file. In the ARM FVP port, this
+file is found in [plat/fvp/include/platform_def.h].
+
+*   **#define : PLATFORM_LINKER_FORMAT**
+
+    Defines the linker format used by the platform, for example
+    `elf64-littleaarch64` used by the FVP.
+
+*   **#define : PLATFORM_LINKER_ARCH**
+
+    Defines the processor architecture for the linker by the platform, for
+    example `aarch64` used by the FVP.
+
+*   **#define : PLATFORM_STACK_SIZE**
+
+    Defines the stack memory available to each CPU. This constant is used by
+    [plat/common/aarch64/platform_mp_stack.S].
+
+*   **#define : PLATFORM_CACHE_LINE_SIZE**
+
+    Defines the size (in bytes) of the largest cache line across all the cache
+    levels in the platform.
+
+*   **#define : PLATFORM_CLUSTER_COUNT**
+
+    Defines the total number of clusters implemented by the platform in the
+    system.
+
+*   **#define : PLATFORM_CORE_COUNT**
+
+    Defines the total number of CPUs implemented by the platform across all
+    clusters in the system.
+
+*   **#define : PLATFORM_MAX_CPUS_PER_CLUSTER**
+
+    Defines the maximum number of CPUs that can be implemented within a cluster
+    on the platform.
+
+*   **#define : PLATFORM_NUM_AFFS**
+
+    Defines the total number of nodes in the affinity hierarchy at all affinity
+    levels used by the platform.
+
+*   **#define : TFTF_BASE**
+
+    Defines the base address of the TFTF binary in DRAM. Used by the linker
+    script to link the image at the right address. Must be aligned on a
+    page-size boundary.
+
+If the platform port uses the IO storage framework, the following constants
+must also be defined:
+
+*   **#define : MAX_IO_DEVICES**
+
+    Defines the maximum number of registered IO devices. Attempting to register
+    more devices than this value using `io_register_device()` will fail with
+    `IO_RESOURCES_EXHAUSTED`.
+
+*   **#define : MAX_IO_HANDLES**
+
+    Defines the maximum number of open IO handles. Attempting to open more IO
+    entities than this value using `io_open()` will fail with
+    `IO_RESOURCES_EXHAUSTED`.
+
+### Function : tftf_plat_arch_setup() [mandatory]
+
+    Argument : void
+    Return   : void
+
+This function performs any platform-specific and architectural setup that the
+platform requires.
+
+In both the ARM FVP and Juno ports, this function configures and enables the
+MMU.
+
+### Function : tftf_early_platform_setup() [mandatory]
+
+    Argument : void
+    Return   : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU. It is used to perform platform-specific actions very early
+in the boot.
+
+In both the ARM FVP and Juno ports, this function configures the console.
+
+### Function : tftf_platform_setup() [mandatory]
+
+    Argument : void
+    Return   : void
+
+This function executes with the MMU and data caches enabled. It is responsible
+for performing any remaining platform-specific setup that can occur after the
+MMU and data cache have been enabled.
+
+This function is also responsible for initializing the storage abstraction layer
+used to access non-volatile memory for permanent storage of test results. It
+also initialises the GIC and detects the platform topology using
+platform-specific means.
+
+
+4.  Optional modifications
+--------------------------
+
+The following are helper functions implemented by the Test Framework that
+perform common platform-specific tasks. A platform may choose to override these
+definitions.
+
+### Function : platform_get_stack()
+
+    Argument : unsigned long
+    Return   : unsigned long
+
+This function returns the base address of the memory stack that has been
+allocated for the CPU specified by MPIDR. The size of the stack allocated to
+each CPU is specified by the platform defined constant `PLATFORM_STACK_SIZE`.
+
+Common implementation of this function is provided in
+[plat/common/aarch64/platform_mp_stack.S].
+
+### Function : tftf_platform_end()
+
+    Argument : void
+    Return   : void
+
+This function performs any operation required by the platform to properly finish
+the test session.
+
+In the FVP port, this function terminates the model by sending an EOT
+(End Of Transmission) character on the UART.
+
+
+5.  Storage abstraction layer
+-----------------------------
+
+In order to improve platform independence and portability a storage abstraction
+layer is used to store test results to non-volatile platform storage.
+
+Each platform should register devices and their drivers via the Storage layer.
+These drivers then need to be initialized in `tftf_platform_setup()` function.
+
+It is mandatory to implement at least one storage driver. For the FVP and Juno
+platforms the NOR Flash driver is provided as the default means to store test
+results to storage. The storage layer is described in the header file
+`<FIXME>/io_storage.h`. The implementation of the common library is in
+`<FIXME>/io_storage.c` and the driver files are located in `drivers/io/`.
+
+
+------------------------------------------------------
+Old documentation
 
 *** (Optional) plat/<platform>/tests_platform/tests_to_skip.txt