Merge pull request #122 from 'danh-arm:dh/v0.4-docs'
diff --git a/docs/change-log.md b/docs/change-log.md
index c1b20ca..c7ad084 100644
--- a/docs/change-log.md
+++ b/docs/change-log.md
@@ -1,3 +1,136 @@
+ARM Trusted Firmware - version 0.4
+==================================
+
+New features
+------------
+
+* Makefile improvements:
+
+ * Improved dependency checking when building.
+
+ * Removed `dump` target (build now always produces dump files).
+
+ * Enabled platform ports to optionally make use of parts of the Trusted
+ Firmware (e.g. BL3-1 only), rather than being forced to use all parts.
+ Also made the `fip` target optional.
+
+ * Specified the full path to source files and removed use of the `vpath`
+ keyword.
+
+* Provided translation table library code for potential re-use by platforms
+ other than the FVPs.
+
+* Moved architectural timer setup to platform-specific code.
+
+* Added standby state support to PSCI cpu_suspend implementation.
+
+* SRAM usage improvements:
+
+ * Started using the `-ffunction-sections`, `-fdata-sections` and
+ `--gc-sections` compiler/linker options to remove unused code and data
+ from the images. Previously, all common functions were being built into
+ all binary images, whether or not they were actually used.
+
+ * Placed all assembler functions in their own section to allow more unused
+ functions to be removed from images.
+
+ * Updated BL1 and BL2 to use a single coherent stack each, rather than one
+ per CPU.
+
+ * Changed variables that were unnecessarily declared and initialized as
+ non-const (i.e. in the .data section) so they are either uninitialized
+ (zero init) or const.
+
+* Moved the Test Secure-EL1 Payload (BL3-2) to execute in Trusted SRAM by
+ default. The option for it to run in Trusted DRAM remains.
+
+* Implemented a TrustZone Address Space Controller (TZC-400) driver. A
+ default configuration is provided for the Base FVPs. This means the model
+ parameter `-C bp.secure_memory=1` is now supported.
+
+* Started saving the PSCI cpu_suspend 'power_state' parameter prior to
+ suspending a CPU. This allows platforms that implement multiple power-down
+ states at the same affinity level to identify a specific state.
+
+* Refactored the entire codebase to reduce the amount of nesting in header
+ files and to make the use of system/user includes more consistent. Also
+ split platform.h to separate out the platform porting declarations from the
+ required platform porting definitions and the definitions/declarations
+ specific to the platform port.
+
+* Optimized the data cache clean/invalidate operations.
+
+* Improved the BL3-1 unhandled exception handling and reporting. Unhandled
+ exceptions now result in a dump of registers to the console.
+
+* Major rework to the handover interface between BL stages, in particular the
+ interface to BL3-1. The interface now conforms to a specification and is
+ more future proof.
+
+* Added support for optionally making the BL3-1 entrypoint a reset handler
+ (instead of BL1). This allows platforms with an alternative image loading
+ architecture to re-use BL3-1 with fewer modifications to generic code.
+
+* Reserved some DDR DRAM for secure use on FVP platforms to avoid future
+ compatibility problems with non-secure software.
+
+* Added support for secure interrupts targeting the Secure-EL1 Payload (SP)
+ (using GICv2 routing only). Demonstrated this working by adding an interrupt
+ target and supporting test code to the TSP. Also demonstrated non-secure
+ interrupt handling during TSP processing.
+
+
+Issues resolved since last release
+----------------------------------
+
+* Now support use of the model parameter `-C bp.secure_memory=1` in the Base
+ FVPs (see **New features**).
+
+* Support for secure world interrupt handling now available (see **New
+ features**).
+
+* Made enough SRAM savings (see **New features**) to enable the Test Secure-EL1
+ Payload (BL3-2) to execute in Trusted SRAM by default.
+
+* The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
+ 14.04) now correctly reports progress in the console.
+
+* Improved the Makefile structure to make it easier to separate out parts of
+ the Trusted Firmware for re-use in platform ports. Also, improved target
+ dependency checking.
+
+
+Known issues
+------------
+
+* 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 still uses too much on-chip Trusted 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. This can be worked around by disabling CPU idle in the Linux
+ kernel.
+
+* 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 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.3
==================================
diff --git a/readme.md b/readme.md
index 756cf14..357a969 100644
--- a/readme.md
+++ b/readme.md
@@ -1,4 +1,4 @@
-ARM Trusted Firmware - version 0.3
+ARM Trusted Firmware - version 0.4
==================================
ARM Trusted Firmware provides a reference implementation of secure world
@@ -11,14 +11,12 @@
possible the code is designed for reuse or porting to other ARMv8-A model and
hardware platforms.
-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.
+This release builds on previous source code releases, supporting the Base and
+Foundation FVP platform models from ARM.
ARM will continue development in collaboration with interested parties to
provide a full reference implementation of PSCI, TBBR and Secure Monitor code
-to the benefit of all developers working with ARMv8-A TrustZone software.
+to the benefit of all developers working with ARMv8-A TrustZone technology.
License
@@ -32,9 +30,9 @@
This Release
------------
-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.
+This release is a limited functionality implementation of the Trusted Firmware.
+It provides a suitable starting point for productization. Future versions will
+contain new features, optimizations and quality improvements.
### Functionality
@@ -60,14 +58,21 @@
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.
+ functionality such as world switching, EL1 context management and interrupt
+ routing. 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
-since the last release.
+* Support for alternative Trusted Boot Firmware. Some platforms have their own
+ Trusted Boot implementation and only require the Secure Monitor
+ functionality provided by ARM Trusted Firmware.
+
+* Isolation of memory accessible by the secure world from the normal world
+ through programming of a TrustZone controller.
+
+For a full description of functionality and implementation details, please
+see the [Firmware Design] and supporting documentation. The [Change Log]
+provides details of changes made since the last release.
### Platforms
@@ -75,21 +80,23 @@
[FVP]s (64-bit versions only):
* `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)
+* `FVP_Base_AEMv8A-AEMv8A` (Version 5.6, Build 0.8.5602)
+* `FVP_Base_Cortex-A57x4-A53x4` (Version 5.6, Build 0.8.5602)
+* `FVP_Base_Cortex-A57x1-A53x1` (Version 5.6, Build 0.8.5602)
+* `FVP_Base_Cortex-A57x2-A53x4` (Version 5.6, Build 0.8.5602)
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.
+* Support for ARMv8-A development board as a reference platform.
-* Secure memory, Secure interrupts and support for other types of Secure-EL1
- Payloads.
+* Complete Trusted Boot implementation.
-* Booting the firmware from a Virtio block device.
+* Complete implementation of the [PSCI] specification.
+
+* Support for alternative types of Secure-EL1 Payloads.
* Completing the currently experimental GICv3 support.
@@ -112,7 +119,7 @@
software on another ARMv8-A platform.
See the [Contributing Guidelines] for information on how to contribute to this
-project and the [Acknowledgements] file for a list of contributors to the
+project and the [Acknowledgments] file for a list of contributors to the
project.
### Feedback and support
@@ -130,7 +137,7 @@
[License]: ./license.md "BSD license for ARM Trusted Firmware"
[Contributing Guidelines]: ./contributing.md "Guidelines for contributors"
-[Acknowledgements]: ./acknowledgements.md "Contributor acknowledgements"
+[Acknowledgments]: ./acknowledgements.md "Contributor acknowledgments"
[Change Log]: ./docs/change-log.md
[User Guide]: ./docs/user-guide.md
[Firmware Design]: ./docs/firmware-design.md
@@ -141,5 +148,4 @@
[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.11/openembedded/aarch64 "Linaro AArch64 OpenEmbedded ARM Fast Model 13.11 Release"
[GitHub issue tracker]: https://github.com/ARM-software/tf-issues/issues