Add v0.3 release documentation

Update the readme.md and change-log.md with release information.

Also, remove the "Detailed changes since last release" section of
the change-log.md since the same information can be found in the
GIT commit messages. Fixes ARM-software/tf-issues#22.

Change-Id: I968cc8aaf588aa5c34ba8f1c12a5b797a46e04f5

docs/change-log.md

-ARM Trusted Firmware
-====================
+ARM Trusted Firmware - version 0.3
+==================================
 
-Detailed changes since last release
------------------------------------
+New features
+------------
 
 *   Support for Foundation FVP Version 2.0 added.
     The documented UEFI configuration disables some devices that are unavailable
     in the Foundation FVP, including MMC and CLCD. The resultant UEFI binary can
-    be used on the AEMv8 and Cortex-A57-A53 FVPs, as well as the Foundation FVP.
+    be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation
+    FVP.
+
     NOTE: The software will not work on Version 1.0 of the Foundation FVP.
 
-*   Regression-checked against latest Base FVPs (Version 5.2).
+*   Enabled third party contributions. Added a new contributing.md containing
+    instructions for how to contribute and updated copyright text in all files
+    to acknowledge contributors.
 
-*   The supplied FDTs expose the Interrupt Translation Service (ITS) available
-    in GICv3.
+*   The PSCI CPU_SUSPEND API has been stabilised to the extent where it can be
+    used for entry into power down states with the following restrictions:
+    -   Entry into standby states is not supported.
+    -   The API is only supported on the AEMv8 and Cortex-A57-A53 Base FVPs.
 
-*   Fixed various GCC compiler warnings.
+*   The PSCI AFFINITY_INFO api has undergone limited testing on the Base FVPs to
+    allow experimental use.
 
-*   Unmask SError and Debug exceptions in the trusted firmware.
-    Also route external abort and SError interrupts to EL3.
+*   Required C library and runtime header files are now included locally in ARM
+    Trusted Firmware instead of depending on the toolchain standard include
+    paths. The local implementation has been cleaned up and reduced in scope.
 
-*   The amount of physical RAM available to Linux as specified in the FDTs for
-    Base FVPs have been increased from 2GB to 4GB. This resolves the issue of
-    failing to start user-space when using a RAM-disk file-system.
+*   Added I/O abstraction framework, primarily to allow generic code to load
+    images in a platform-independent way. The existing image loading code has
+    been reworked to use the new framework. Semi-hosting and NOR flash I/O
+    drivers are provided.
 
-*   Build products are now created in a separate build directory tree.
+*   Introduced Firmware Image Package (FIP) handling code and tools. A FIP
+    combines multiple firmware images with a Table of Contents (ToC) into a
+    single binary image. The new FIP driver is another type of I/O driver. The
+    Makefile builds a FIP by default and the FVP platform code expect to load a
+    FIP from NOR flash, although some support for image loading using semi-
+    hosting is retained.
 
-*   Analyze at link-time whether bootloader images will fit in memory and won't
-    overlap each other at run time. If it is not the case then image linking
-    will now fail.
+    NOTE: Building a FIP by default is a non-backwards-compatible change.
 
-*   Reduce the size of the bootloader images by cutting some sections out of
-    their disk images and allocating them at load time, whenever possible.
+    NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
+    DRAM instead of expecting this to be pre-loaded at known location. This is
+    also a non-backwards-compatible change.
 
-*   Properly initialise the C runtime environment. C code can now safely assume
-    that global variables are initialised to 0 and that initialised data holds
-    the correct value.
+    NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
+    it knows the new location to execute from and no longer needs to copy
+    particular code modules to DRAM itself.
 
-*   General changes on the memory layout: some sections have been moved, some of
-    them have been merged together, and some alignment constraints on sections
-    have changed.
+*   Reworked BL2 to BL3-1 handover interface. A new composite structure
+    (bl31_args) holds the superset of information that needs to be passed from
+    BL2 to BL3-1, including information on how handover execution control to
+    BL3-2 (if present) and BL3-3 (non-trusted firmware).
 
-*   Enable third party contributions. Add a new contributing.md containing
-    instructions for how to contribute and update copyright text in all files to
-    acknowledge contributors.
+*   Added library support for CPU context management, allowing the saving and
+    restoring of
+    -   Shared system registers between Secure-EL1 and EL1.
+    -   VFP registers.
+    -   Essential EL3 system registers.
 
-*   The wake up enable bit in the FVP power controller is cleared when a cpu is
-    physically powered up to prevent a spurious wake up from a subsequent cpu
-    off state.
+*   Added a framework for implementing EL3 runtime services. Reworked the PSCI
+    implementation to be one such runtime service.
 
-*   Definitions of some constants related to the PSCI api calls AFFINITY_INFO
-    and CPU_SUSPEND have been corrected.
+*   Reworked the exception handling logic, making use of both SP_EL0 and SP_EL3
+    stack pointers for determining the type of exception, managing general
+    purpose and system register context on exception entry/exit, and handling
+    SMCs. SMCs are directed to the correct EL3 runtime service.
 
-*   A bug which triggered an error condition in the code executed after a cpu
-    is powered on, if a non zero context id parameter was passed in the PSCI
-    CPU_ON and CPU_SUSPEND api calls has been corrected.
+*   Added support for a Test Secure-EL1 Payload (TSP) and a corresponding
+    Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD
+    implements Secure Monitor functionality such as world switching and
+    EL1 context management, and is responsible for communication with the TSP.
+    NOTE: The TSPD does not yet contain support for secure world interrupts.
+    NOTE: The TSP/TSPD is not built by default.
 
-*   A restriction in the FVP code which did not allow the non-secure entrypoint
-    to lie outside the DRAM has been removed.
 
-*   The PSCI CPU_SUSPEND api has been stabilised to an extent where it can be
-    used for entry into power down states with the following restrictions:
-    -   Entry into standby states is not supported.
-    -   The api is only supported on the AEMv8 Base FVP.
+Issues resolved since last release
+----------------------------------
 
-*   The PSCI AFFINITY_INFO api has undergone limited testing on the AEMv8 Base
-    FVP to allow experimental use.
+*   Support has been added for switching context between secure and normal
+    worlds in EL3.
 
-*   Locks corresponding to each affinity level are acquired and released in
-    the correct sequence in the PSCI implementation. Invocation of the PSCI
-    CPU_SUSPEND and CPU_OFF apis simultaneously across cpus & clusters should
-    not result in unexpected behaviour.
+*   PSCI API calls `AFFINITY_INFO` & `PSCI_VERSION` have now been tested (to
+    a limited extent).
 
-*   The API to return the memory layout structures for each bootloader stage has
-    undergone change. A pointer to these structures is returned instead of their
-    copy.
+*   The ARM Trusted Firmware build artifacts are now placed in the `./build`
+    directory and sub-directories instead of being placed in the root of the
+    project.
 
-*   Required C library and runtime header files are now included locally in ARM
-    Trusted Firmware instead of depending on the toolchain standard include
-    paths. The local implementation has been cleaned up and reduced in scope.
-    Implementations for `putchar()` and `strchr()` were added to the local C
-    library.
+*   The ARM Trusted Firmware is now free from build warnings. Build warnings
+    are now treated as errors.
 
-*   GCC compiler built-in function support has been disabled in order to improve
-    compiler independence.
+*   The ARM Trusted Firmware now provides C library support locally within the
+    project to maintain compatibility between toolchains/systems.
 
-*   The references to GitHub issues in the documentation now to point to a
-    separate issue tracking repository
-    https://github.com/ARM-software/tf-issues.
+*   The PSCI locking code has been reworked so it no longer takes locks in an
+    incorrect sequence.
 
-*   Cleared bits in the architectural trap feature register (CPTR_EL3) during
-    early boot to prevent traps when accessing certain registers, including
-    floating point registers. Also added `-mgeneral-regs-only` flag to GCC
-    settings to prevent generation of code using floating point registers.
+*   The RAM-disk method of loading a Linux file-system has been confirmed to
+    work with the ARM Trusted Firmware and Linux kernel version (based on
+    version 3.13) used in this release, for both Foundation and Base FVPs.
 
-*   The GICv3 distributor can have more ports than CPUs are available in the
-    system. The GICv3 re-distributors are probed to work out which
-    re-distributor should be used with which CPU.
 
-*   Add multi-platform support to the build system. The user may now specify
-    which platform to build using PLAT=<platform> as part of the make command
-    line.  Default behaviour is to make all platforms.  New platforms are
-    automatically detected by the make file when they are added to the plat
-    directory.
+Known issues
+------------
 
-*   An issue in the PSCI implementation has been fixed which could result in the
-    power down of an affinity instance at level X even though at least one
-    affinity instance at level X - 1 does not allow this.
+The following is a list of issues which are expected to be fixed in the future
+releases of the ARM Trusted Firmware.
+
+*   The TrustZone Address Space Controller (TZC-400) is not being programmed
+    yet. Use of model parameter `-C bp.secure_memory=1` is not supported.
+
+*   No support yet for secure world interrupt handling.
+
+*   GICv3 support is experimental. The Linux kernel patches to support this are
+    not widely available. There are known issues with GICv3 initialization in
+    the ARM Trusted Firmware.
+
+*   Dynamic image loading is not available yet. The current image loader
+    implementation (used to load BL2 and all subsequent images) has some
+    limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead
+    to loading errors, even if the images should theoretically fit in memory.
+
+*   The ARM Trusted Firmware uses too much on-chip Trusted SRAM. Currently the
+    Test Secure-EL1 Payload (BL3-2) executes in Trusted DRAM since there is not
+    enough SRAM. A number of RAM usage enhancements have been identified to
+    rectify this situation.
+
+*   CPU idle does not work on the advertised version of the Foundation FVP.
+    Some FVP fixes are required that are not available externally at the time
+    of writing.
+
+*   Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been
+    observed when using Linaro toolchain versions later than 13.11. Although
+    most of these have been fixed, some remain at the time of writing. These
+    mainly seem to relate to a subtle change in the way the compiler converts
+    between 64-bit and 32-bit values (e.g. during casting operations), which
+    reveals previously hidden bugs in client code.
+
+*   The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
+    14.01) does not report progress correctly in the console. It only seems to
+    produce error output, not standard output. It otherwise appears to function
+    correctly. Other filesystem versions on the same software stack do not
+    exhibit the problem.
+
+*   The Makefile structure doesn't make it easy to separate out parts of the
+    Trusted Firmware for re-use in platform ports, for example if only BL3-1 is
+    required in a platform port. Also, dependency checking in the Makefile is
+    flawed.
+
+*   The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
+    its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
 
 
 ARM Trusted Firmware - version 0.2
@@ -177,11 +223,6 @@ releases of the ARM Trusted Firmware.
     to the kernel.
 
 
-Detailed changes since last release
------------------------------------
-
-First source release - not applicable.
-
 - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._

readme.md

-ARM Trusted Firmware - version 0.2
+ARM Trusted Firmware - version 0.3
 ==================================
 
 ARM Trusted Firmware provides a reference implementation of secure world
-software for [ARMv8-A], including Exception Level 3 (EL3) software. This first
+software for [ARMv8-A], including Exception Level 3 (EL3) software. This
 release focuses on support for ARM's [Fixed Virtual Platforms (FVPs)] [FVP].
 
 The intent is to provide a reference implementation of various ARM interface
@@ -11,9 +11,9 @@ Board Boot Requirements (TBBR) and [Secure Monitor] [TEE-SMC] code. As far as
 possible the code is designed for reuse or porting to other ARMv8-A model and
 hardware platforms.
 
-This release is the first one as source code: an initial prototype
-release was available in binary form in the [Linaro AArch64 OpenEmbedded
-Engineering Build] [AArch64 LEB] to support the new FVP Base platform
+This release builds on the previous source code release, which has been
+available in source and binary form since the [Linaro AArch64 OpenEmbedded 13.11
+Engineering Build] [AArch64 LEB]. These support the Base FVP platform
 models from ARM.
 
 ARM will continue development in collaboration with interested parties to
@@ -32,14 +32,16 @@ source files.
 This Release
 ------------
 
-This software is an early implementation of the Trusted Firmware. Only
+This release is an incomplete implementation of the Trusted Firmware. Only
 limited functionality is provided at present and it has not been optimized or
 subjected to extended robustness or stress testing.
 
 ### Functionality
 
 *   Initial implementation of a subset of the Trusted Board Boot Requirements
-    Platform Design Document (PDD).
+    Platform Design Document (PDD). This includes packaging the various firmware
+    images into a Firmware Image Package (FIP) to be loaded from non-volatile
+    storage.
 
 *   Initializes the secure world (for example, exception vectors, control
     registers, GIC and interrupts for the platform), before transitioning into
@@ -52,10 +54,16 @@ subjected to extended robustness or stress testing.
     if available, otherwise EL1.
 
 *   Handles SMCs (Secure Monitor Calls) conforming to the [SMC Calling
-    Convention PDD] [SMCCC].
+    Convention PDD] [SMCCC] using an EL3 runtime services framework.
 
 *   Handles SMCs relating to the [Power State Coordination Interface PDD] [PSCI]
-    for the Secondary CPU Boot and CPU hotplug use-cases.
+    for the Secondary CPU Boot, CPU hotplug and CPU idle use-cases.
+
+*   A Test Secure-EL1 Payload and Dispatcher to demonstrate Secure Monitor
+    functionality such as world switching and EL1 context management. This
+    also demonstrates Secure-EL1 interaction with PSCI. Some of this
+    functionality is provided in library form for re-use by other Secure-EL1
+    Payload Dispatchers.
 
 For a full list of updated functionality and implementation details, please
 see the [User Guide]. The [Change Log] provides details of changes made
@@ -66,26 +74,27 @@ since the last release.
 This release of the Trusted Firmware has been tested on the following ARM
 [FVP]s (64-bit versions only):
 
-*   `FVP_Base_AEMv8A-AEMv8A` (Version 5.1, Build 0.8.5108).
-*   `FVP_Base_Cortex-A57x4-A53x4` (Version 5.1, Build 0.8.5108).
-*   `FVP_Base_Cortex-A57x1-A53x1` (Version 5.1, Build 0.8.5108).
-
-These models can be licensed from ARM: see [www.arm.com/fvp] [FVP].
+*   `Foundation_v8` (Version 2.0, Build 0.8.5206)
+*   `FVP_Base_AEMv8A-AEMv8A` (Version 5.4, Build 0.8.5405)
+*   `FVP_Base_Cortex-A57x4-A53x4` (Version 5.4, Build 0.8.5405)
+*   `FVP_Base_Cortex-A57x1-A53x1` (Version 5.4, Build 0.8.5405)
 
-For an updated list of supported platforms, please see the [Change Log].
+The Foundation FVP can be downloaded free of charge. The Base FVPs can be
+licensed from ARM: see [www.arm.com/fvp] [FVP].
 
 ### Still to Come
 
 *   Complete implementation of the [PSCI] specification.
 
-*   Secure memory, Secure monitor, Test Secure OS & Secure interrupts.
+*   Secure memory, Secure interrupts and support for other types of Secure-EL1
+    Payloads.
 
-*   Booting the firmware from a block device.
+*   Booting the firmware from a Virtio block device.
 
 *   Completing the currently experimental GICv3 support.
 
 For a full list of detailed issues in the current code, please see the [Change
-Log].
+Log] and the [GitHub issue tracker].
 
 
 Getting Started
@@ -97,6 +106,8 @@ Get the Trusted Firmware source code from
 See the [User Guide] for instructions on how to install, build and use
 the Trusted Firmware with the ARM [FVP]s.
 
+See the [Firmware Design] for information on how the ARM Trusted Firmware works.
+
 See the [Porting Guide] as well for information about how to use this
 software on another ARMv8-A platform.
 
@@ -107,8 +118,7 @@ project.
 ### Feedback and support
 
 ARM welcomes any feedback on the Trusted Firmware. Please send feedback using
-the [GitHub issue tracker](
-https://github.com/ARM-software/tf-issues/issues).
+the [GitHub issue tracker].
 
 ARM licensees may contact ARM directly via their partner managers.
 
@@ -123,6 +133,7 @@ _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
 [Acknowledgements]:         ./acknowledgements.md "Contributor acknowledgements"
 [Change Log]:               ./docs/change-log.md
 [User Guide]:               ./docs/user-guide.md
+[Firmware Design]:          ./docs/firmware-design.md
 [Porting Guide]:            ./docs/porting-guide.md
 
 [ARMv8-A]:               http://www.arm.com/products/processors/armv8-architecture.php "ARMv8-A Architecture"
@@ -130,4 +141,5 @@ _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
 [PSCI]:                  http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)"
 [SMCCC]:                 http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
 [TEE-SMC]:               http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php "Secure Monitor and TEEs"
-[AArch64 LEB]:   http://releases.linaro.org/13.09/openembedded/aarch64 "Linaro AArch64 OpenEmbedded ARM Fast Model 13.09 Release"
+[AArch64 LEB]:           http://releases.linaro.org/13.11/openembedded/aarch64 "Linaro AArch64 OpenEmbedded ARM Fast Model 13.11 Release"
+[GitHub issue tracker]:  https://github.com/ARM-software/tf-issues/issues