Skip to content

Commit

Permalink
Add v0.3 release documentation
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@danh-arm
danh-arm committed Feb 28, 2014
1 parent 57de6d7 commit b238849
Show file tree
Hide file tree
Showing 2 changed files with 161 additions and 108 deletions.
205 changes: 123 additions & 82 deletions docs/change-log.md
View file
Original file line number Diff line number Diff line change
@@ -1,112 +1,158 @@
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
Expand Down Expand Up @@ -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._
64 changes: 38 additions & 26 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -123,11 +133,13 @@ _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"
[FVP]: http://www.arm.com/fvp "ARM's Fixed Virtual Platforms"
[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"
[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"
[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

0 comments on commit b238849

Please sign in to comment.