Merge pull request #205 from danh-arm/dh/1.0-docs

Documentation for version 1.0

Makefile

@@ -31,8 +31,8 @@
 #
 # Trusted Firmware Version
 #
-VERSION_MAJOR		:= 0
+VERSION_MAJOR		:= 1
-VERSION_MINOR		:= 4
+VERSION_MINOR		:= 0
 
 #
 # Default values for build configurations

docs/change-log.md

@@ -1,3 +1,183 @@
+ARM Trusted Firmware - version 1.0
+==================================
+
+New features
+------------
+
+*   It is now possible to map higher physical addresses using non-flat virtual
+    to physical address mappings in the MMU setup.
+
+*   Wider use is now made of the per-CPU data cache in BL3-1 to store:
+
+    *   Pointers to the non-secure and secure security state contexts.
+
+    *   A pointer to the CPU-specific operations.
+
+    *   A pointer to PSCI specific information (for example the current power
+        state).
+
+    *   A crash reporting buffer.
+
+*   The following RAM usage improvements result in a BL3-1 RAM usage reduction
+    from 96KB to 56KB (for FVP with TSPD), and a total RAM usage reduction
+    across all images from 208KB to 88KB, compared to the previous release.
+
+    *   Removed the separate `early_exception` vectors from BL3-1 (2KB code size
+        saving).
+
+    *   Removed NSRAM from the FVP memory map, allowing the removal of one
+        (4KB) translation table.
+
+    *   Eliminated the internal `psci_suspend_context` array, saving 2KB.
+
+    *   Correctly dimensioned the PSCI `aff_map_node` array, saving 1.5KB in the
+        FVP port.
+
+    *   Removed calling CPU mpidr from the bakery lock API, saving 160 bytes.
+
+    *   Removed current CPU mpidr from PSCI common code, saving 160 bytes.
+
+    *   Inlined the mmio accessor functions, saving 360 bytes.
+
+    *   Fully reclaimed all BL1 RW memory and BL2 memory on the FVP port by
+        overlaying the BL3-1/BL3-2 NOBITS sections on top of these at runtime.
+
+    *   Made storing the FP register context optional, saving 0.5KB per context
+        (8KB on the FVP port, with TSPD enabled and running on 8 CPUs).
+
+    *   Implemented a leaner `tf_printf()` function, allowing the stack to be
+        greatly reduced.
+
+    *   Removed coherent stacks from the codebase. Stacks allocated in normal
+        memory are now used before and after the MMU is enabled. This saves 768
+        bytes per CPU in BL3-1.
+
+    *   Reworked the crash reporting in BL3-1 to use less stack.
+
+    *   Optimized the EL3 register state stored in the `cpu_context` structure
+        so that registers that do not change during normal execution are
+        re-initialized each time during cold/warm boot, rather than restored
+        from memory. This saves about 1.2KB.
+
+    *   As a result of some of the above, reduced the runtime stack size in all
+        BL images. For BL3-1, this saves 1KB per CPU.
+
+*   PSCI SMC handler improvements to correctly handle calls from secure states
+    and from AArch32.
+
+*   CPU contexts are now initialized from the `entry_point_info`. BL3-1 fully
+    determines the exception level to use for the non-trusted firmware (BL3-3)
+    based on the SPSR value provided by the BL2 platform code (or otherwise
+    provided to BL3-1). This allows platform code to directly run non-trusted
+    firmware payloads at either EL2 or EL1 without requiring an EL2 stub or OS
+    loader.
+
+*   Code refactoring improvements:
+
+    *   Refactored `fvp_config` into a common platform header.
+
+    *   Refactored the fvp gic code to be a generic driver that no longer has an
+        explicit dependency on platform code.
+
+    *   Refactored the CCI-400 driver to not have dependency on platform code.
+
+    *   Simplified the IO driver so it's no longer necessary to call `io_init()`
+        and moved all the IO storage framework code to one place.
+
+    *   Simplified the interface the the TZC-400 driver.
+
+    *   Clarified the platform porting interface to the TSP.
+
+    *   Reworked the TSPD setup code to support the alternate BL3-2
+        intialization flow where BL3-1 generic code hands control to BL3-2,
+        rather than expecting the TSPD to hand control directly to BL3-2.
+
+    *   Considerable rework to PSCI generic code to support CPU specific
+        operations.
+
+*   Improved console log output, by:
+
+    *   Adding the concept of debug log levels.
+
+    *   Rationalizing the existing debug messages and adding new ones.
+
+    *   Printing out the version of each BL stage at runtime.
+
+    *   Adding support for printing console output from assembler code,
+        including when a crash occurs before the C runtime is initialized.
+
+*   Moved up to the latest versions of the FVPs, toolchain, EDK2, kernel, Linaro
+    file system and DS-5.
+
+*   On the FVP port, made the use of the Trusted DRAM region optional at build
+    time (off by default). Normal platforms will not have such a "ready-to-use"
+    DRAM area so it is not a good example to use it.
+
+*   Added support for PSCI `SYSTEM_OFF` and `SYSTEM_RESET` APIs.
+
+*   Added support for CPU specific reset sequences, power down sequences and
+    register dumping during crash reporting. The CPU specific reset sequences
+    include support for errata workarounds.
+
+*   Merged the Juno port into the master branch. Added support for CPU hotplug
+    and CPU idle. Updated the user guide to describe how to build and run on the
+    Juno platform.
+
+
+Issues resolved since last release
+----------------------------------
+
+*   Removed the concept of top/bottom image loading. The image loader now
+    automatically detects the position of the image inside the current memory
+    layout and updates the layout to minimize fragementation. This resolves the
+    image loader limitations of previously releases. There are currently no
+    plans to support dynamic image loading.
+
+*   CPU idle now works on the publicized version of the Foundation FVP.
+
+*   All known issues relating to the compiler version used have now been
+    resolved. This TF version uses Linaro toolchain 14.07 (based on GCC 4.9).
+
+
+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.
+
+*   While this version greatly reduces the on-chip RAM requirements, there are
+    further RAM usage enhancements that could be made.
+
+*   The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
+    its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
+
+*   The Juno-specific firmware design documentation is incomplete.
+
+*   Some recent enhancements to the FVP port have not yet been translated into
+    the Juno port. These will be tracked via the tf-issues project.
+
+*   The Linux kernel version referred to in the user guide has DVFS and HMP
+    support disabled due to some known instabilities at the time of this
+    release. A future kernel version will re-enable these features.
+
+*   DS-5 v5.19 does not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in
+    CADI server mode. This is because the `<SimName>` reported by the FVP in
+    this version has changed. For example, for the Cortex-A57x4-A53x4 Base FVP,
+    the `<SimName>` reported by the FVP is `FVP_Base_Cortex_A57x4_A53x4`, while
+    DS-5 expects it to be `FVP_Base_A57x4_A53x4`.
+
+    The temporary fix to this problem is to change the name of the FVP in
+    `sw/debugger/configdb/Boards/ARM FVP/Base_A57x4_A53x4/cadi_config.xml`.
+    Change the following line:
+
+        <SimName>System Generator:FVP_Base_A57x4_A53x4</SimName>
+    to
+        <SimName>System Generator:FVP_Base_Cortex-A57x4_A53x4</SimName>
+
+    A similar change can be made to the other Cortex-A57-A53 Base FVP variants.
+
+
 ARM Trusted Firmware - version 0.4
 ==================================
 

readme.md

@@ -1,9 +1,11 @@
-ARM Trusted Firmware - version 0.4
+ARM Trusted Firmware - version 1.0
 ==================================
 
 ARM Trusted Firmware provides a reference implementation of secure world
 software for [ARMv8-A], including Exception Level 3 (EL3) software. This
-release focuses on support for ARM's [Fixed Virtual Platforms (FVPs)] [FVP].
+release provides initial support for the [Juno ARM Development Platform] [Juno],
+complementing the existing support for the Base and Foundation
+[Fixed Virtual Platforms (FVPs)] [FVP] from ARM.
 
 The intent is to provide a reference implementation of various ARM interface
 standards, such as the Power State Coordination Interface ([PSCI]), Trusted
@@ -11,9 +13,6 @@ 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 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 technology.
@@ -48,14 +47,15 @@ contain new features, optimizations and quality improvements.
 *   Supports both GICv2 and GICv3 initialization for use by normal world
     software.
 
-*   Starts the normal world at the highest available Exception Level: EL2
+*   Starts the normal world at the Exception Level and Register Width provided
-    if available, otherwise EL1.
+    by the platform port. Typically this is AArch64 EL2 if available.
 
 *   Handles SMCs (Secure Monitor Calls) conforming to the [SMC Calling
     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, CPU hotplug and CPU idle use-cases.
+    for the Secondary CPU Boot, CPU Hotplug, CPU Idle and System Shutdown/Reset
+    use-cases.
 
 *   A Test Secure-EL1 Payload and Dispatcher to demonstrate Secure Monitor
     functionality such as world switching, EL1 context management and interrupt
@@ -70,28 +70,34 @@ contain new features, optimizations and quality improvements.
 *   Isolation of memory accessible by the secure world from the normal world
     through programming of a TrustZone controller.
 
+*   Support for CPU specific reset sequences, power down sequences and register
+    dumping during crash reporting. The CPU specific reset sequences include
+    support for errata workarounds.
+
 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
 
-This release of the Trusted Firmware has been tested on the following ARM
+This release of the Trusted Firmware has been tested on Revision B of the
-[FVP]s (64-bit versions only):
+[Juno ARM Development Platform] [Juno] with Version r0p0-00rel7 of the
+[ARM SCP Firmware] [SCP download].
 
-*   `Foundation_v8` (Version 2.0, Build 0.8.5206)
+The Trusted Firmware has also been tested on the 64-bit Linux versions of the
-*   `FVP_Base_AEMv8A-AEMv8A` (Version 5.6, Build 0.8.5602)
+following ARM [FVP]s:
-*   `FVP_Base_Cortex-A57x4-A53x4` (Version 5.6, Build 0.8.5602)
+
-*   `FVP_Base_Cortex-A57x1-A53x1` (Version 5.6, Build 0.8.5602)
+*   `Foundation_v8` (Version 2.1, Build 9.0.24)
-*   `FVP_Base_Cortex-A57x2-A53x4` (Version 5.6, Build 0.8.5602)
+*   `FVP_Base_AEMv8A-AEMv8A` (Version 5.8, Build 0.8.5802)
+*   `FVP_Base_Cortex-A57x4-A53x4` (Version 5.8, Build 0.8.5802)
+*   `FVP_Base_Cortex-A57x1-A53x1` (Version 5.8, Build 0.8.5802)
+*   `FVP_Base_Cortex-A57x2-A53x4` (Version 5.8, Build 0.8.5802)
 
 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
 
-*   Support for ARMv8-A development board as a reference platform.
-
 *   Complete Trusted Boot implementation.
 
 *   Complete implementation of the [PSCI] specification.
@@ -100,6 +106,8 @@ licensed from ARM: see [www.arm.com/fvp] [FVP].
 
 *   Completing the currently experimental GICv3 support.
 
+*   Support for new System IP devices.
+
 For a full list of detailed issues in the current code, please see the [Change
 Log] and the [GitHub issue tracker].
 
@@ -145,6 +153,8 @@ _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
 
 [ARMv8-A]:               http://www.arm.com/products/processors/armv8-architecture.php "ARMv8-A Architecture"
 [FVP]:                   http://www.arm.com/fvp "ARM's Fixed Virtual Platforms"
+[Juno]:                  http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php "Juno ARM Development Platform"
+[SCP download]:          https://silver.arm.com/download/download.tm?pv=1764630
 [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"