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

2 files changed, 296 insertions, 10 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
 
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 519be3d..6506624 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -1,7 +1,56 @@
-### Building the test framework
+EL3 Firmware Test Framework User Guide
+======================================
 
-2 platforms are supported at the moment:
-   * FVP models
+Contents :
+
+1.  Introduction
+2.  Host machine requirements
+3.  Tools
+4.  Building the Test Framework
+
+- - - - - - - - - - - - - - - - - -
+
+1.  Introduction
+----------------
+
+This document describes how to build the EL3 Firmware Test Framework for
+the Juno ARM development platform and ARM Fixed Virtual Platform (FVP)
+models.
+
+
+2.  Host machine requirements
+-----------------------------
+
+The minimum recommended machine specification for building the software and
+running the FVP models is a dual-core processor running at 2GHz with 12GB of
+RAM. For best performance, use a machine with a quad-core processor running at
+2.6GHz with 16GB of RAM.
+
+The software has been tested on Ubuntu 12.04.04 (64-bit). Packages used
+for building the software were installed from that distribution unless
+otherwise specified.
+
+
+3.  Tools
+---------
+
+The following tools are required to use the EL3 Firmware Test Framework:
+
+*   Baremetal GNU GCC tools. Verified packages can be downloaded from [Linaro]
+    [Linaro Toolchain]. The rest of this document assumes that the
+    `gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz` tools are used.
+
+        wget http://releases.linaro.org/14.07/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz
+        tar -xf gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz
+
+*   (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.19.
+
+
+4.  Building the Test framework
+---------------------------------
+
+Two platforms are supported at the moment:
+   * FVP models: Foundation, Base AEM, Base Cortex
    * Juno board
 
 To build the software for one of these two platforms, follow these steps:
@@ -9,7 +58,7 @@ To build the software for one of these two platforms, follow these steps:
 1.   Specify the cross-compiler prefix, the targeted platform and build:
 
          CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
-         make PLAT=<platform>
+         make PLAT=<platform> all
 
      ... where `<platform>` is either `fvp` or `juno`.
 
@@ -17,18 +66,56 @@ To build the software for one of these two platforms, follow these steps:
      debug version instead,
 
          CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
-         make PLAT=<platform> DEBUG=1
+         make PLAT=<platform> DEBUG=1 all
 
      To make the build verbose, use:
 
          CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
-         make PLAT=<platform> V=1
+         make PLAT=<platform> V=1 all
 
 2.   The build process creates products in a `build` directory tree.
      The resulting binary is in `build/<platform>/<build_type>/tftf.bin`
      where `<build_type>` is either `debug` or `release`.
      The resulting ELF file is in `build/<platform>/<build_type>/tftf/tftf.elf`
 
+### Summary of build options
+
+The Test Framework build system supports the following build options. Unless
+mentioned otherwise, these options are expected to be specified at the build
+command line and are not to be modified in any component makefiles. Note that
+the build system doesn't track dependency for build options. Therefore, if any
+of the build options are changed from a previous build, a clean build must be
+performed.
+
+*   `CROSS_COMPILE`: Prefix to toolchain binaries. Please refer to examples in
+    this document for usage.
+
+*   `DEBUG`: Choose between a debug and release build. It can take either 0
+    (release) or 1 (debug) as values. 0 is the default.
+
+*   `PLAT`: Choose a platform to build the Test Framework for. The chosen
+    platform name must be the name of one of the directories under the `plat/`
+    directory other than `common`.
+
+*   `TEST_REPORT_FORMAT`: Format of the test report. It can take either 'raw'
+    (text output on the console) or 'junit' (XML Junit format). The default is
+    'raw'.
+
+*   `V`: Verbose build. If assigned anything other than 0, the build commands
+    are printed. Default is 0.
+
+- - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
+
+
+[ARM FVP website]:         http://www.arm.com/fvp
+[Linaro Toolchain]:        http://releases.linaro.org/14.07/components/toolchain/binaries/
+[DS-5]:                    http://www.arm.com/products/tools/software-tools/ds-5/index.php
+
+
+---------------------------------------------------------
+Old documentation
 
 ### Overview of TFTF behaviour