doc: Migrate a subset of the GitHub wiki content

With the TF wiki being migrated from GitHub to trustedfirmware.org,
some documents will be moved into the docs/ directory within the
repository rather than remaining as external content. The
appropriate action has been decided on a per-document basis.

Change-Id: Id0f615f3418369256f30d2e34e354a115389d105
Signed-off-by: Joel Hutton <Joel.Hutton@Arm.com>
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

14 files changed, 1585 insertions, 0 deletions

diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst
new file mode 100644
index 00000000..3b144461
--- /dev/null
+++ b/docs/frequently-asked-questions.rst
@@ -0,0 +1,88 @@
+How do I update a Pull Request?
+-------------------------------
+
+Often it is necessary to update a Pull Request (PR) before it is merged.  When
+you push to the source topic branch of an open PR, the PR is automatically
+updated with the new commits.
+
+If you need to modify existing commits in the PR (for example following review
+comments), then use the ``--force`` option when pushing. Any comments that apply
+to previous versions of the PR are retained in the PR. Sometimes it may be
+confusing whether comments apply to the current or a previous version of the PR,
+especially if there are several rounds of rework. In this case, you may be asked
+to close the PR and create a new one with the latest commits. The new PR should
+have a version appended to the name (e.g. "My topic v2") and you should create a
+link to the old PR so that reviewers can easily find previous versions.
+
+When the PR is finally merged, you will be given the option of deleting your
+topic branch. It is recommended you delete this (and any previous topic branch
+versions) to avoid polluting your fork with obsolete branches.
+
+How long will my Pull Request take to merge?
+--------------------------------------------
+
+This can vary a lot, depending on:
+
+* How important the Pull Request (PR) is considered by the TF maintainers. Where
+  possible, you should indicate the required timescales for merging the PR and
+  the impact of any delay.
+
+* The quality of the PR. PRs are likely to be merged quicker if they follow the
+  coding guidelines, have already had some code review, and have been
+  appropriately tested. Note that PRs from Arm engineers go through an internal
+  review process before appearing on GitHub, therefore may appear to be merged
+  more quickly.
+
+* The impact of the PR. For example, a PR that changes a key generic API is
+  likely to receive much greater scrutiny than a local change to a specific
+  platform port.
+
+* How much opportunity for external review is required. For example, the TF
+  maintainers may not wait for external review comments to merge trivial
+  bug-fixes but may wait up to a week to merge major changes, or ones requiring
+  feedback from specific parties.
+
+* How many other topics need to be integrated and the risk of conflict between
+  the topics.
+
+* Is there a code freeze in place in preparation for the release. Please refer
+  the `release information`_ for more details.
+
+* The workload of the TF maintainers.
+
+Feel free to add a comment to your PR to get an estimate of when it will
+be merged.
+
+How long will it take for my merged Pull Request to go from ``integration`` to ``master``?
+------------------------------------------------------------------------------------------
+
+This depends on how many concurrent Pull Requests (PRs) are being processed at
+the same time. In simple cases where all potential regressions have already been
+tested, the delay will be less than 1 day.  If the TF maintainers are trying to
+merge several things over the course of a few days, it might take up to a week.
+Typically, it will be 1-2 days.
+
+The worst case is if the TF maintainers are trying to make a release while also
+receiving PRs that will not be merged into the release. In this case, the PRs
+will be merged onto ``integration``, which will temporarily diverge from the
+release branch. The ``integration`` branch will be rebased onto ``master`` after
+the release, and then ``master`` will be fast-forwarded to ``integration`` 1-2
+days later. This whole process could take up 4 weeks. Please refer the `release
+information`_ for code freeze dates. The TF maintainers will inform the PR owner
+if this is going to happen.
+
+It is OK to create a PR based on commits that are only available in
+``integration`` or another PR, rather than ``master``. There is a risk that the
+dependency commits will change (for example due to PR rework or integration
+problems). If this happens, the dependent PR will need reworking.
+
+What are these strange comments in my Pull Request?
+---------------------------------------------------
+
+For example, comments like "Can one of the admins verify this patch?" or "test
+this please". These are associated with Arm's Continuous Integration
+infrastructure and can be safely ignored. Those who are curious can see the
+documentation for `this Jenkins plugin`_ for more details.
+
+.. _release information: release-information
+.. _this Jenkins plugin: https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin
diff --git a/docs/image-terminology.rst b/docs/image-terminology.rst
new file mode 100644
index 00000000..1c642977
--- /dev/null
+++ b/docs/image-terminology.rst
@@ -0,0 +1,171 @@
+Trusted Firmware images
+-----------------------
+
+This page contains the current name, abbreviated name and purpose of the various
+images referred to in the Trusted Firmware project.
+
+Some general notes:
+
+- Some of the names and abbreviated names have changed to accomodate new
+  requirements. The changed names are as backward compatible as possible to
+  minimize confusion. Where applicable, the previous names are indicated. Some
+  code, documentation and build artefacts may still refer to the previous names;
+  these will inevitably take time to catch up.
+
+- The main name change is to prefix each image with the processor it corresponds
+  to (for example ``AP_``, ``SCP_``, ...). In situations where there is no
+  ambiguity (for example, within AP specific code/documentation), it is
+  permitted to omit the processor prefix (for example, just BL1 instead of
+  ``AP_BL1``).
+
+- Previously, the format for 3rd level images had 2 forms; ``BL3`` was either
+  suffixed with a dash ("-") followed by a number (for example, ``BL3-1``) or a
+  subscript number, depending on whether rich text formatting was available.
+  This was confusing and often the dash gets omitted in practice. Therefore the
+  new form is to just omit the dash and not use subscript formatting.
+
+- The names no longer contain dash ("-") characters at all. In some places (for
+  example, function names) it's not possible to use this character. All dashes
+  are either removed or replaced by underscores ("_").
+
+- The abbreviation BL stands for BootLoader. This is a historical anomaly.
+  Clearly, many of these images are not BootLoaders, they are simply firmware
+  images. However, the BL abbreviation is now widely used and is retained for
+  backwards compatibility.
+
+- The image names are not case sensitive. For example, ``bl1`` is
+  interchangeable with ``BL1``, although mixed case should be avoided.
+
+AP Boot ROM: ``AP_BL1``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically, this is the first code to execute on the AP and cannot be modified.
+Its primary purpose is to perform the minimum intialization necessary to load
+and authenticate an updateable AP firmware image into an executable RAM
+location, then hand-off control to that image.
+
+AP RAM Firmware: ``AP_BL2``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the 2nd stage AP firmware. It is currently also known as the "Trusted
+Boot Firmware". Its primary purpose is to perform any additional initialization
+required to load and authenticate all 3rd level firmware images into their
+executable RAM locations, then hand-off control to the EL3 Runtime Firmware.
+
+EL3 Runtime Firmware: ``AP_BL31``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Also known as "SoC AP firmware" or "EL3 monitor firmware". Its primary purpose
+is to handle transitions between the normal and secure world.
+
+Secure-EL1 Payload (SP): ``AP_BL32``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically this is a TEE or Trusted OS, providing runtime secure services to the
+normal world. However, it may refer to a more abstract Secure-EL1 Payload (SP).
+Note that this abbreviation should only be used in systems where there is a
+single or primary image executing at Secure-EL1. In systems where there are
+potentially multiple SPs and there is no concept of a primary SP, this
+abbreviation should be avoided; use the recommended **Other AP 3rd level
+images** abbreviation instead.
+
+AP Normal World Firmware: ``AP_BL33``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For example, UEFI or uboot. Its primary purpose is to boot a normal world OS.
+
+Other AP 3rd level images: ``AP_BL3_XXX``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The abbreviated names of the existing 3rd level images imply a load/execution
+ordering (for example, ``AP_BL31 -> AP_BL32 -> AP_BL33``).  Some systems may
+have additional images and/or a different load/execution ordering. The
+abbreviated names of the existing images are retained for backward compatibility
+but new 3rd level images should be suffixed with an underscore followed by text
+identifier, not a number.
+
+In systems where 3rd level images are provided by different vendors, the
+abbreviated name should identify the vendor as well as the image
+function. For example, ``AP_BL3_ARM_RAS``.
+
+SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically, this is the first code to execute on the SCP and cannot be modified.
+Its primary purpose is to perform the minimum intialization necessary to load
+and authenticate an updateable SCP firmware image into an executable RAM
+location, then hand-off control to that image. This may be performed in
+conjunction with other processor firmware (for example, ``AP_BL1`` and
+``AP_BL2``).
+
+This image was previously abbreviated as ``BL0`` but in some systems, the SCP
+may directly load/authenticate its own firmware. In these systems, it doesn't
+make sense to interleave the image terminology for AP and SCP; both AP and SCP
+Boot ROMs are ``BL1`` from their own point of view.
+
+SCP RAM Firmware: ``SCP_BL2`` (previously ``BL3-0``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the 2nd stage SCP firmware. It is currently also known as the "SCP
+runtime firmware" but it could potentially be an intermediate firmware if the
+SCP needs to load/authenticate multiple 3rd level images in future.
+
+This image was previously abbreviated as BL3-0 but from the SCP's point of view,
+this has always been the 2nd stage firmware. The previous name is too
+AP-centric.
+
+Firmware update images
+----------------------
+
+The terminology for these images has not been widely adopted yet but they have
+to be considered in a production Trusted Board Boot solution.
+
+AP Firmware Update Boot ROM: ``AP_NS_BL1U``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically, this is the first normal world code to execute on the AP during a
+firmware update operation, and cannot be modified. Its primary purpose is to
+load subequent firmware update images from an external interface and communicate
+with ``AP_BL1`` to authenticate those images.
+
+During firmware update, there are (potentially) multiple transitions between the
+secure and normal world. The "level" of the BL image is relative to the world
+it's in so it makes sense to encode "NS" in the normal world images. The absence
+of "NS" implies a secure world image.
+
+AP Firmware Update Config: ``AP_BL2U``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This image does the minimum necessary AP secure world configuration required to
+complete the firmware update operation. It is potentially a subset of ``AP_BL2``
+functionality.
+
+SCP Firmware Update Config: ``SCP_BL2U`` (previously ``BL2-U0``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This image does the minimum necessary SCP secure world configuration required to
+complete the firmware update operation. It is potentially a subset of
+``SCP_BL2`` functionality.
+
+AP Firmware Updater: ``AP_NS_BL2U`` (previously ``BL3-U``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the 2nd stage AP normal world firmware updater. Its primary purpose is
+to load a new set of firmware images from an external interface and write them
+into non-volatile storage.
+
+Other processor firmware images
+-------------------------------
+
+Some systems may have additional processors to the AP and SCP. For example, a
+Management Control Processor (MCP). Images for these processors should follow
+the same terminology, with the processor abbreviation prefix, followed by
+underscore and the level of the firmware image.
+
+For example,
+
+MCP Boot ROM: ``MCP_BL1``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MCP RAM Firmware: ``MCP_BL2``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/psci-performance-juno.rst b/docs/psci-performance-juno.rst
new file mode 100644
index 00000000..a28f732b
--- /dev/null
+++ b/docs/psci-performance-juno.rst
@@ -0,0 +1,285 @@
+This document summarises the findings of performance measurements of key
+operations in the ARM Trusted Firmware (TF) Power State Coordination Interface
+(PSCI) implementation, using the in-built Performance Measurement Framework
+(PMF) and runtime instrumentation timestamps.
+
+Method
+------
+
+We used the `Juno R1 platform`_ for these tests, which has 4 x Cortex-A53 and 2
+x Cortex-A57 clusters running at the following frequencies:
+
++-----------------+--------------------+
+| Domain          | Frequency (MHz)    |
++=================+====================+
+| Cortex-A57      | 900 (nominal)      |
++-----------------+--------------------+
+| Cortex-A53      | 650 (underdrive)   |
++-----------------+--------------------+
+| AXI subsystem   | 533                |
++-----------------+--------------------+
+
+Juno supports CPU, cluster and system power down states, corresponding to power
+levels 0, 1 and 2 respectively. It does not support any retention states.
+
+We used the upstream `TF master as of 31/01/2017`_, building the platform using
+the ``ENABLE_RUNTIME_INSTRUMENTATION`` option:
+
+::
+
+    make PLAT=juno ENABLE_RUNTIME_INSTRUMENTATION=1 \
+        SCP_BL2=<path/to/scp-fw.bin>                \
+        BL33=<path/to/test-fw.bin>                  \
+        all fip
+
+When using the debug build of TF, there was no noticeable difference in the
+results.
+
+The tests are based on an ARM-internal test framework. The release build of this
+framework was used because the results in the debug build became skewed; the
+console output prevented some of the tests from executing in parallel.
+
+The tests consist of both parallel and sequential tests, which are broadly
+described as follows:
+
+- **Parallel Tests** This type of test powers on all the non-lead CPUs and
+  brings them and the lead CPU to a common synchronization point.  The lead CPU
+  then initiates the test on all CPUs in parallel.
+
+- **Sequential Tests** This type of test powers on each non-lead CPU in
+  sequence. The lead CPU initiates the test on a non-lead CPU then waits for the
+  test to complete before proceeding to the next non-lead CPU. The lead CPU then
+  executes the test on itself.
+
+In the results below, CPUs 0-3 refer to CPUs in the little cluster (A53) and
+CPUs 4-5 refer to CPUs in the big cluster (A57). In all cases CPU 4 is the lead
+CPU.
+
+``PSCI_ENTRY`` refers to the time taken from entering the TF PSCI implementation
+to the point the hardware enters the low power state (WFI). Referring to the TF
+runtime instrumentation points, this corresponds to:
+``(RT_INSTR_ENTER_HW_LOW_PWR - RT_INSTR_ENTER_PSCI)``.
+
+``PSCI_EXIT`` refers to the time taken from the point the hardware exits the low
+power state to exiting the TF PSCI implementation. This corresponds to:
+``(RT_INSTR_EXIT_PSCI - RT_INSTR_EXIT_HW_LOW_PWR)``.
+
+``CFLUSH_OVERHEAD`` refers to the part of ``PSCI_ENTRY`` taken to flush the
+caches. This corresponds to: ``(RT_INSTR_EXIT_CFLUSH - RT_INSTR_ENTER_CFLUSH)``.
+
+Note there is very little variance observed in the values given (~1us), although
+the values for each CPU are sometimes interchanged, depending on the order in
+which locks are acquired. Also, there is very little variance observed between
+executing the tests sequentially in a single boot or rebooting between tests.
+
+Given that runtime instrumentation using PMF is invasive, there is a small
+(unquantified) overhead on the results. PMF uses the generic counter for
+timestamps, which runs at 50MHz on Juno.
+
+Results and Commentary
+----------------------
+
+``CPU_SUSPEND`` to deepest power level on all CPUs in parallel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++-------+---------------------+--------------------+--------------------------+
+| CPU   | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) |
++=======+=====================+====================+==========================+
+| 0     | 27                  | 20                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 1     | 114                 | 86                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 2     | 202                 | 58                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 3     | 375                 | 29                 | 94                       |
++-------+---------------------+--------------------+--------------------------+
+| 4     | 20                  | 22                 | 6                        |
++-------+---------------------+--------------------+--------------------------+
+| 5     | 290                 | 18                 | 206                      |
++-------+---------------------+--------------------+--------------------------+
+
+A large variance in ``PSCI_ENTRY`` and ``PSCI_EXIT`` times across CPUs is
+observed due to TF PSCI lock contention. In the worst case, CPU 3 has to wait
+for the 3 other CPUs in the cluster (0-2) to complete ``PSCI_ENTRY`` and release
+the lock before proceeding.
+
+The ``CFLUSH_OVERHEAD`` times for CPUs 3 and 5 are higher because they are the
+last CPUs in their respective clusters to power down, therefore both the L1 and
+L2 caches are flushed.
+
+The ``CFLUSH_OVERHEAD`` time for CPU 5 is a lot larger than that for CPU 3
+because the L2 cache size for the big cluster is lot larger (2MB) compared to
+the little cluster (1MB).
+
+``CPU_SUSPEND`` to power level 0 on all CPUs in parallel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++-------+---------------------+--------------------+--------------------------+
+| CPU   | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) |
++=======+=====================+====================+==========================+
+| 0     | 116                 | 14                 | 8                        |
++-------+---------------------+--------------------+--------------------------+
+| 1     | 204                 | 14                 | 8                        |
++-------+---------------------+--------------------+--------------------------+
+| 2     | 287                 | 13                 | 8                        |
++-------+---------------------+--------------------+--------------------------+
+| 3     | 376                 | 13                 | 9                        |
++-------+---------------------+--------------------+--------------------------+
+| 4     | 29                  | 15                 | 7                        |
++-------+---------------------+--------------------+--------------------------+
+| 5     | 21                  | 15                 | 8                        |
++-------+---------------------+--------------------+--------------------------+
+
+There is no lock contention in TF generic code at power level 0 but the large
+variance in ``PSCI_ENTRY`` times across CPUs is due to lock contention in Juno
+platform code. The platform lock is used to mediate access to a single SCP
+communication channel. This is compounded by the SCP firmware waiting for each
+AP CPU to enter WFI before making the channel available to other CPUs, which
+effectively serializes the SCP power down commands from all CPUs.
+
+On platforms with a more efficient CPU power down mechanism, it should be
+possible to make the ``PSCI_ENTRY`` times smaller and consistent.
+
+The ``PSCI_EXIT`` times are consistent across all CPUs because TF does not
+require locks at power level 0.
+
+The ``CFLUSH_OVERHEAD`` times for all CPUs are small and consistent since only
+the cache associated with power level 0 is flushed (L1).
+
+``CPU_SUSPEND`` to deepest power level on all CPUs in sequence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++-------+---------------------+--------------------+--------------------------+
+| CPU   | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) |
++=======+=====================+====================+==========================+
+| 0     | 114                 | 20                 | 94                       |
++-------+---------------------+--------------------+--------------------------+
+| 1     | 114                 | 20                 | 94                       |
++-------+---------------------+--------------------+--------------------------+
+| 2     | 114                 | 20                 | 94                       |
++-------+---------------------+--------------------+--------------------------+
+| 3     | 114                 | 20                 | 94                       |
++-------+---------------------+--------------------+--------------------------+
+| 4     | 195                 | 22                 | 180                      |
++-------+---------------------+--------------------+--------------------------+
+| 5     | 21                  | 17                 | 6                        |
++-------+---------------------+--------------------+--------------------------+
+
+The ``CLUSH_OVERHEAD`` times for lead CPU 4 and all CPUs in the non-lead cluster
+are large because all other CPUs in the cluster are powered down during the
+test. The ``CPU_SUSPEND`` call powers down to the cluster level, requiring a
+flush of both L1 and L2 caches.
+
+The ``CFLUSH_OVERHEAD`` time for CPU 4 is a lot larger than those for the little
+CPUs because the L2 cache size for the big cluster is lot larger (2MB) compared
+to the little cluster (1MB).
+
+The ``PSCI_ENTRY`` and ``CFLUSH_OVERHEAD`` times for CPU 5 are low because lead
+CPU 4 continues to run while CPU 5 is suspended. Hence CPU 5 only powers down to
+level 0, which only requires L1 cache flush.
+
+``CPU_SUSPEND`` to power level 0 on all CPUs in sequence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++-------+---------------------+--------------------+--------------------------+
+| CPU   | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) |
++=======+=====================+====================+==========================+
+| 0     | 22                  | 14                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 1     | 22                  | 14                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 2     | 21                  | 14                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 3     | 22                  | 14                 | 5                        |
++-------+---------------------+--------------------+--------------------------+
+| 4     | 17                  | 14                 | 6                        |
++-------+---------------------+--------------------+--------------------------+
+| 5     | 18                  | 15                 | 6                        |
++-------+---------------------+--------------------+--------------------------+
+
+Here the times are small and consistent since there is no contention and it is
+only necessary to flush the cache to power level 0 (L1). This is the best case
+scenario.
+
+The ``PSCI_ENTRY`` times for CPUs in the big cluster are slightly smaller than
+for the CPUs in little cluster due to greater CPU performance.
+
+The ``PSCI_EXIT`` times are generally lower than in the last test because the
+cluster remains powered on throughout the test and there is less code to execute
+on power on (for example, no need to enter CCI coherency)
+
+``CPU_OFF`` on all non-lead CPUs in sequence then ``CPU_SUSPEND`` on lead CPU to deepest power level
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The test sequence here is as follows:
+
+1. Call ``CPU_ON`` and ``CPU_OFF`` on each non-lead CPU in sequence.
+
+2. Program wake up timer and suspend the lead CPU to the deepest power level.
+
+3. Call ``CPU_ON`` on non-lead CPU to get the timestamps from each CPU.
+
++-------+---------------------+--------------------+--------------------------+
+| CPU   | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) |
++=======+=====================+====================+==========================+
+| 0     | 110                 | 28                 | 93                       |
++-------+---------------------+--------------------+--------------------------+
+| 1     | 110                 | 28                 | 93                       |
++-------+---------------------+--------------------+--------------------------+
+| 2     | 110                 | 28                 | 93                       |
++-------+---------------------+--------------------+--------------------------+
+| 3     | 111                 | 28                 | 93                       |
++-------+---------------------+--------------------+--------------------------+
+| 4     | 195                 | 22                 | 181                      |
++-------+---------------------+--------------------+--------------------------+
+| 5     | 20                  | 23                 | 6                        |
++-------+---------------------+--------------------+--------------------------+
+
+The ``CFLUSH_OVERHEAD`` times for all little CPUs are large because all other
+CPUs in that cluster are powerered down during the test. The ``CPU_OFF`` call
+powers down to the cluster level, requiring a flush of both L1 and L2 caches.
+
+The ``PSCI_ENTRY`` and ``CFLUSH_OVERHEAD`` times for CPU 5 are small because
+lead CPU 4 is running and CPU 5 only powers down to level 0, which only requires
+an L1 cache flush.
+
+The ``CFLUSH_OVERHEAD`` time for CPU 4 is a lot larger than those for the little
+CPUs because the L2 cache size for the big cluster is lot larger (2MB) compared
+to the little cluster (1MB).
+
+The ``PSCI_EXIT`` times for CPUs in the big cluster are slightly smaller than
+for CPUs in the little cluster due to greater CPU performance.  These times
+generally are greater than the ``PSCI_EXIT`` times in the ``CPU_SUSPEND`` tests
+because there is more code to execute in the "on finisher" compared to the
+"suspend finisher" (for example, GIC redistributor register programming).
+
+``PSCI_VERSION`` on all CPUs in parallel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since very little code is associated with ``PSCI_VERSION``, this test
+approximates the round trip latency for handling a fast SMC at EL3 in TF.
+
++-------+-------------------+
+| CPU   | TOTAL TIME (ns)   |
++=======+===================+
+| 0     | 3020              |
++-------+-------------------+
+| 1     | 2940              |
++-------+-------------------+
+| 2     | 2980              |
++-------+-------------------+
+| 3     | 3060              |
++-------+-------------------+
+| 4     | 520               |
++-------+-------------------+
+| 5     | 720               |
++-------+-------------------+
+
+The times for the big CPUs are less than the little CPUs due to greater CPU
+performance.
+
+We suspect the time for lead CPU 4 is shorter than CPU 5 due to subtle cache
+effects, given that these measurements are at the nano-second level.
+
+.. _Juno R1 platform: https://www.arm.com/files/pdf/Juno_r1_ARM_Dev_datasheet.pdf
+.. _TF master as of 31/01/2017: https://github.com/ARM-software/arm-trusted-firmware/tree/c38b36d
diff --git a/docs/release-information.rst b/docs/release-information.rst
new file mode 100644
index 00000000..af3cbbe3
--- /dev/null
+++ b/docs/release-information.rst
@@ -0,0 +1,89 @@
+TF-A Release Information
+========================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+--------------
+
+Project Release Cadence
+-----------------------
+
+The project currently aims to do a release once every 6 months which will be
+tagged on the master branch. There will be a code freeze (stop merging
+non-essential PRs) up to 4 weeks prior to the target release date. The release
+candidates will start appearing after this and only bug fixes or updates
+required for the release will be merged. The maintainers are free to use their
+judgement on what PRs are essential for the release. A release branch may be
+created after code freeze if there are significant PRs that need merging onto
+the integration branch during the merge window.
+
+The release testing will be performed on release candidates and depending on
+issues found, additional release candidates may be created to fix the issues.
+
+::
+
+                            |<----------6 months---------->|
+            |<---4 weeks--->|              |<---4 weeks--->|
+       +-----------------------------------------------------------> time
+            |               |              |               |
+         code freeze       ver w.x       code freeze     ver y.z
+
+
+Upcoming Releases
+~~~~~~~~~~~~~~~~~
+
+These are the estimated dates for the upcoming release. These may change
+depending on project requirement and partner feedback.
+
++-----------------+---------------------------+------------------------------+
+| Release Version |  Target Date              | Expected Code Freeze         |
++=================+===========================+==============================+
+| v2.0            | 1st week of Oct '18       | 1st week of Sep '18          |
++-----------------+---------------------------+------------------------------+
+| v2.1            | 5th week of Mar '19       | 1st week of Mar '19          |
++-----------------+---------------------------+------------------------------+
+
+Removal of Deprecated Interfaces
+--------------------------------
+
+As mentioned in the `Platform compatibility policy`_, this is a live document
+cataloging all the deprecated interfaces in TF-A project and the Release version
+after which it will be removed.
+
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| Interface                      | Deprecation | Removed | Comments                                                |
+|                                | Date        | after   |                                                         |
+|                                |             | Release |                                                         |
++================================+=============+=========+=========================================================+
+| Legacy Console API             | Jan '18     | v2.1    | Deprecated in favour of ``MULTI_CONSOLE_API``           |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| Weak default                   | Oct '18     | v2.1    | The default implementations are defined in              |
+| ``plat_crash_console_*``       |             |         | `crash_console_helpers.S`_. The platforms have to       |
+| APIs                           |             |         | define ``plat_crash_console_*``.                        |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| ``finish_console_register``    | Oct '18     | v2.1    | The old version of the macro is deprecated. See commit  |
+| macro in                       |             |         | cc5859c_ for more details.                              |
+| ``MULTI_CONSOLE_API``          |             |         |                                                         |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| Types ``tzc_action_t`` and     | Oct '18     | v2.1    | Using logical operations such as OR in enumerations     |
+| ``tzc_region_attributes_t``    |             |         | goes against the MISRA guidelines.                      |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| Macro ``EL_IMPLEMENTED()``     | Oct '18     | v2.1    | Deprecated in favour of ``el_implemented()``.           |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| ``get_afflvl_shift()``,        | Dec '18     | v2.1    | Removed.                                                |
+| ``mpidr_mask_lower_afflvls()``,|             |         |                                                         |
+| and ``eret()``.                |             |         |                                                         |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+| Extra include paths in the     | Jan '18     | v2.1    | Now it is needed to use the full path of the common     |
+| Makefile in ``INCLUDES``.      |             |         | header files. More information in commit 09d40e0e0828_. |
++--------------------------------+-------------+---------+---------------------------------------------------------+
+
+*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.*
+
+.. _Platform compatibility policy: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/platform-compatibility-policy.rst
+.. _crash_console_helpers.S: https://github.com/ARM-software/arm-trusted-firmware/blob/master/plat/common/aarch64/crash_console_helpers.S
+.. _cc5859c: https://github.com/ARM-software/arm-trusted-firmware/commit/cc5859ca19ff546c35eb0331000dae090b6eabcf
+.. _09d40e0e0828: https://github.com/ARM-software/arm-trusted-firmware/commit/09d40e0e08283a249e7dce0e106c07c5141f9b7e
diff --git a/docs/security-center.rst b/docs/security-center.rst
new file mode 100644
index 00000000..825b1102
--- /dev/null
+++ b/docs/security-center.rst
@@ -0,0 +1,100 @@
+Security Disclosures
+--------------------
+
+We disclose all security vulnerabilities we find or are advised about that are
+relevant for ARM Trusted Firmware (TF). We encourage responsible disclosure of
+vulnerabilities and inform users as best we can about all possible issues.
+
+We disclose TF vulnerabilities as Security Advisories. These are listed at the
+bottom of this page and announced as issues in the `GitHub issue tracker`_ with
+the "security-advisory" tag. You can receive notification emails for these by
+watching that project.
+
+Found a Security Issue?
+-----------------------
+
+Although we try to keep TF secure, we can only do so with the help of the
+community of developers and security researchers.
+
+If you think you have found a security vulnerability, please *do not* report it
+in the `GitHub issue tracker`_. Instead send an email to
+trusted-firmware-security@arm.com
+
+Please include:
+
+* Trusted Firmware version (or commit) affected
+
+* A description of the concern or vulnerability
+
+* Details on how to replicate the vulnerability, including:
+
+  - Configuration details
+
+  - Proof of concept exploit code
+
+  - Any additional software or tools required
+
+We recommend using `this PGP/GPG key`_ for encrypting the information. This key
+is also available at http://keyserver.pgp.com and LDAP port 389 of the same
+server. The fingerprint for this key is:
+
+::
+
+    1309 2C19 22B4 8E87 F17B FE5C 3AB7 EFCB 45A0 DFD0
+
+If you would like replies to be encrypted, please provide your public key.
+
+Please give us the time to respond to you and fix the vulnerability before going
+public. We do our best to respond and fix any issues quickly. We also need to
+ensure providers of products that use TF have a chance to consider the
+implications of the vulnerability and its remedy.
+
+Afterwards, we encourage you to write-up your findings about the TF source code.
+
+Attribution
+-----------
+
+We will name and thank you in the ``change-log.rst`` distributed with the source
+code and in any published security advisory.
+
+Security Advisories
+-------------------
+
++-----------+------------------------------------------------------------------+
+| ID        | Title                                                            |
++===========+==================================================================+
+| `TFV-1`_  | Malformed Firmware Update SMC can result in copy of unexpectedly |
+|           | large data into secure memory                                    |
++-----------+------------------------------------------------------------------+
+| `TFV-2`_  | Enabled secure self-hosted invasive debug interface can allow    |
+|           | normal world to panic secure world                               |
++-----------+------------------------------------------------------------------+
+| `TFV-3`_  | RO memory is always executable at AArch64 Secure EL1             |
++-----------+------------------------------------------------------------------+
+| `TFV-4`_  | Malformed Firmware Update SMC can result in copy or              |
+|           | authentication of unexpected data in secure memory in AArch32    |
+|           | state                                                            |
++-----------+------------------------------------------------------------------+
+| `TFV-5`_  | Not initializing or saving/restoring PMCR_EL0 can leak secure    |
+|           | world timing information                                         |
++-----------+------------------------------------------------------------------+
+| `TFV-6`_  | Arm Trusted Firmware exposure to speculative processor           |
+|           | vulnerabilities using cache timing side-channels                 |
++-----------+------------------------------------------------------------------+
+| `TFV-7`_  | Trusted Firmware-A exposure to cache speculation vulnerability   |
+|           | Variant 4                                                        |
++-----------+------------------------------------------------------------------+
+| `TFV-8`_  | Not saving x0 to x3 registers can leak information from one      |
+|           | Normal World SMC client to another                               |
++-----------+------------------------------------------------------------------+
+
+.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
+.. _this PGP/GPG key: Trusted-Firmware-Security.asc
+.. _TFV-1: ARM-Trusted-Firmware-Security-Advisory-TFV-1
+.. _TFV-2: ARM-Trusted-Firmware-Security-Advisory-TFV-2
+.. _TFV-3: ARM-Trusted-Firmware-Security-Advisory-TFV-3
+.. _TFV-4: ARM-Trusted-Firmware-Security-Advisory-TFV-4
+.. _TFV-5: ARM-Trusted-Firmware-Security-Advisory-TFV-5
+.. _TFV-6: Arm-Trusted-Firmware-Security-Advisory-TFV-6
+.. _TFV-7: Trusted-Firmware-A-Security-Advisory-TFV-7
+.. _TFV-8: Trusted-Firmware-A-Security-Advisory-TFV-8
diff --git a/docs/security-reporting.asc b/docs/security-reporting.asc
new file mode 100644
index 00000000..8c41f7bf
--- /dev/null
+++ b/docs/security-reporting.asc
@@ -0,0 +1,45 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: PGP Desktop 10.2.0 (Build 2317)
+
+mQENBFey/QMBCACyxJaLsMYU794ZfzLdY172tHXRJfP0X3b34HU35G7kYl1zNiYc
+/NoygtQdtDv/aW1B2A/YTNhGge+gX4BWAREd5CYDbdPEoMWC395/qbnmMmez7YNY
+PEJ9Iq9e5AayAWwZTL1zgKwdvE+WTwWok/nMbsifJSEdhdrOIHNqRcZgplUUyZ2R
+sDqFtSbACO3xj4Psk8KJ23Ax7UZgULouZOJaHOnyq8F9V/U7zWvX4Odf96XaC1Em
+cUTsG0kQfa7Y4Hqqjzowq366I4k2o2LAtuLPWNCvq5jjEceLs2+qV4cNLgyL2dzO
+wtUL6EdkrGfkxsPHpsVKXig4wjeX9ehCSqRlABEBAAG0PVRydXN0ZWQgRmlybXdh
+cmUgU2VjdXJpdHkgPHRydXN0ZWQtZmlybXdhcmUtc2VjdXJpdHlAYXJtLmNvbT6J
+AYwEEAECAHYFAley/SEwFIAAAAAAIAAHcHJlZmVycmVkLWVtYWlsLWVuY29kaW5n
+QHBncC5jb21wZ3BtaW1lCAsJCAcDAgEKAhkBGRhsZGFwOi8va2V5c2VydmVyLnBn
+cC5jb20FGwMAAAAFFgADAgEFHgEAAAAGFQgJCgMCAAoJEDq378tFoN/QFJsH/0ly
+H91LYYzKIQrbolQw7Rp47lgzH88uN1rInYpW2GaTbjwPffAhYJ4VsN8RaiFskD9m
+DjMg4vY8p0jPTCUX1Acq20Wq0Ybv3HcrtjUp4ie0+rLUi3043yJyKFMWkJC2Kr+p
+SobnxSrAie4HDFUgSaPoh9Qf1zXEzOavdgcziMiyS5iVUf6NXYZ9z82OTZ6TdPKS
+u+L5zOHTdrV3+hD54w00Xa+EIE7u4v0to6Uwm977508hyGuvpOVq+u7+S3qJQvnY
++JheStbgLsm6CyoRjyrlTE01ujAD6hI6Ef9yMgEljOBEy4phKAJ67SCRLEOiCp5U
+YHFCULwhzIyg2y3WmZSJASIEEAECAAwFAlezAnwFAwASdQAACgkQlxC4m8pXrXzd
+GAf/T8YEICI9qQt2vnCtCbBvVaTc2sAphVZ51kZVDqCDPB7znDtJYRBpi/9IPELt
+mYwIElMx2mqmahVaeUghmbzmcLZe8QHUi8GanO1mh+ook6uyjRojSIq6VUVV5uUf
+tuscfhpilOvUclqMqYEIgXfl08YwS40Kmmj0qokwad0co0zGQ8GEhlgMi2yvJfiG
+fPS0Xcn1J0980E/VgJQCAKwZvukrbb32WVwuhgepqs/4/62PZNxglcErioFt6P0A
+ik4t9Hr0uErqCeEKiYtmEw5e9ioRdX7CV+tJgIk907Tpv6E0iDFRJHmJBvmsz82O
+stOazS3wZ5Xck7asTqkvoyo9Z7kBDQRXsv0DAQgAsmL1UUIWyoNmYJWixSPDmclP
+0ul3T1FCOsIlWTeVeshnHByYdgZOfce78ETCUoq8G7qvYm4GRrEDpqVbxqTxJioP
+4Li05WDdNCKzSoqWd8ADA48gYnnJEu2NhA7ZkEC6u3+Mdbmd3M0J6nsAWeE0BV1p
+F5zI600sJuoH2QNWB7Kv5N3GCFE4IgCIH8MwDo4Y4FTZtygx4GjEtSExiOIz+bpX
+2+GkFCQGpIyLHLP4FmQmrsNzsIdEyFuG0IdoVuQ2PtNLiw+Wkm7CXWgRmFx/dtPN
+eVnOFWdbTtjBWVv/Z6zbANos2knfc75KR4FCQ6pWRvVeJuMuMopUDkfFDMtR8QAR
+AQABiQJBBBgBAgErBQJXsv0EBRsMAAAAwF0gBBkBCAAGBQJXsv0DAAoJENaB8ph8
+s9hu/nsH/Rx696ZR+1vZi5qCTUwo6s0Qa15x4OuyJEM85VgMLVY7/MZpp1Y8If6u
+A5BynQpy4QIPxIRsRx6twduW9/gb8UVhpMRPyuJ+5sSv0/KeUqkPbKSUGro2zGlR
+sjqPrchi6uafWZqOR/y/DNkEvkgZZaP+f9xs2qWKuoF08yTioo76QoroA4DVuVAT
+MkDFe9d3natAmfmjO4kvxuthg3y7R+sdXrCHpYYJZdbiR6gyj7e8whlSLwHQT3lz
+7QBL/CvVvL/dmhu5pk8fsksbehepMQTkCJ6GGEamOPEhwh7IvlzhEt97U4uzjuMd
+BPjqOCes+4QTmn/+lMTySG0kXxnHOEUACgkQOrfvy0Wg39D8Jgf/Uf3epkMOJ9xm
+N1l5vW8tQQ6RR055YQxQ9P6JMyCQGEJmGOcvrasCho69wMQDy4AYVtJaZd25LH/3
+LX/lcyDOP4C9VYXM+IxlcaRmjBKqWx9UzQeeioIkfmjMpJFU846ZP1dacge0lPx8
+p6ocPbM0rkv0xuF/dwkDQd4BPSmv4/3/UM8FRoYo8Q7SHkDR98wJ8FCm6k9wRtWC
+K/jzmBswY2TewAHom3jLzTM0FZ/n5Sini3EGAI2EvnQrxWRpeE7ZOkHKqLHEOaHl
+zeST4U/cUgxhwgnhbGJ7zmrFsHpYnnZYM3mIKfQ3/EhksZ68TF9IB1tfUiQTij4r
+9jWa0ybRdQ==
+=nZZb
+-----END PGP PUBLIC KEY BLOCK-----
diff --git a/docs/security_advisories/security-advisory-tfv-1.rst b/docs/security_advisories/security-advisory-tfv-1.rst
new file mode 100644
index 00000000..23b1c989
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-1.rst
@@ -0,0 +1,158 @@
++----------------+-------------------------------------------------------------+
+| Title          | Malformed Firmware Update SMC can result in copy of         |
+|                | unexpectedly large data into secure memory                  |
++================+=============================================================+
+| CVE ID         | CVE-2016-10319                                              |
++----------------+-------------------------------------------------------------+
+| Date           | 18 Oct 2016                                                 |
++----------------+-------------------------------------------------------------+
+| Versions       | v1.2 and v1.3 (since commit `48bfb88`_)                     |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | Platforms that use AArch64 BL1 plus untrusted normal world  |
+| Affected       | firmware update code executing before BL31                  |
++----------------+-------------------------------------------------------------+
+| Impact         | Copy of unexpectedly large data into the free secure memory |
+|                | reported by BL1 platform code                               |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #783`_                                        |
++----------------+-------------------------------------------------------------+
+| Credit         | IOActive                                                    |
++----------------+-------------------------------------------------------------+
+
+Generic Trusted Firmware (TF) BL1 code contains an SMC interface that is briefly
+available after cold reset to support the Firmware Update (FWU) feature (also
+known as recovery mode). This allows most FWU functionality to be implemented in
+the normal world, while retaining the essential image authentication
+functionality in BL1. When cold boot reaches the EL3 Runtime Software (for
+example, BL31 on AArch64 systems), the FWU SMC interface is replaced by the EL3
+Runtime SMC interface. Platforms may choose how much of this FWU functionality
+to use, if any.
+
+The BL1 FWU SMC handling code, currently only supported on AArch64, contains
+several vulnerabilities that may be exploited when *all* the following
+conditions apply:
+
+1. Platform code uses TF BL1 with the ``TRUSTED_BOARD_BOOT`` build option
+   enabled.
+
+2. Platform code arranges for untrusted normal world FWU code to be executed in
+   the cold boot path, before BL31 starts. Untrusted in this sense means code
+   that is not in ROM or has not been authenticated or has otherwise been
+   executed by an attacker.
+
+3. Platform code copies the insecure pattern described below from the ARM
+   platform version of ``bl1_plat_mem_check()``.
+
+The vulnerabilities consist of potential integer overflows in the input
+validation checks while handling the ``FWU_SMC_IMAGE_COPY`` SMC. The SMC
+implementation is designed to copy an image into secure memory for subsequent
+authentication, but the vulnerabilities may allow an attacker to copy
+unexpectedly large data into secure memory. Note that a separate vulnerability
+is required to leverage these vulnerabilities; for example a way to get the
+system to change its behaviour based on the unexpected secure memory contents.
+
+Two of the vulnerabilities are in the function ``bl1_fwu_image_copy()`` in
+``bl1/bl1_fwu.c``. These are listed below, referring to the v1.3 tagged version
+of the code:
+
+- Line 155:
+
+  .. code:: c
+
+    /*
+     * If last block is more than expected then
+     * clip the block to the required image size.
+     */
+    if (image_desc->copied_size + block_size >
+         image_desc->image_info.image_size) {
+        block_size = image_desc->image_info.image_size -
+            image_desc->copied_size;
+        WARN("BL1-FWU: Copy argument block_size > remaining image size."
+            " Clipping block_size\n");
+    }
+
+    /* Make sure the image src/size is mapped. */
+    if (bl1_plat_mem_check(image_src, block_size, flags)) {
+        WARN("BL1-FWU: Copy arguments source/size not mapped\n");
+        return -ENOMEM;
+    }
+
+    INFO("BL1-FWU: Continuing image copy in blocks\n");
+
+    /* Copy image for given block size. */
+    base_addr += image_desc->copied_size;
+    image_desc->copied_size += block_size;
+    memcpy((void *)base_addr, (const void *)image_src, block_size);
+    ...
+
+  This code fragment is executed when the image copy operation is performed in
+  blocks over multiple SMCs. ``block_size`` is an SMC argument and therefore
+  potentially controllable by an attacker. A very large value may result in an
+  integer overflow in the 1st ``if`` statement, which would bypass the check,
+  allowing an unclipped ``block_size`` to be passed into
+  ``bl1_plat_mem_check()``. If ``bl1_plat_mem_check()`` also passes, this may
+  result in an unexpectedly large copy of data into secure memory.
+
+- Line 206:
+
+  .. code:: c
+
+    /* Make sure the image src/size is mapped. */
+    if (bl1_plat_mem_check(image_src, block_size, flags)) {
+        WARN("BL1-FWU: Copy arguments source/size not mapped\n");
+        return -ENOMEM;
+    }
+
+    /* Find out how much free trusted ram remains after BL1 load */
+    mem_layout = bl1_plat_sec_mem_layout();
+    if ((image_desc->image_info.image_base < mem_layout->free_base) ||
+         (image_desc->image_info.image_base + image_size >
+          mem_layout->free_base + mem_layout->free_size)) {
+        WARN("BL1-FWU: Memory not available to copy\n");
+        return -ENOMEM;
+    }
+
+    /* Update the image size. */
+    image_desc->image_info.image_size = image_size;
+
+    /* Copy image for given size. */
+    memcpy((void *)base_addr, (const void *)image_src, block_size);
+    ...
+
+  This code fragment is executed during the 1st invocation of the image copy
+  operation. Both ``block_size`` and ``image_size`` are SMC arguments. A very
+  large value of ``image_size`` may result in an integer overflow in the 2nd
+  ``if`` statement, which would bypass the check, allowing execution to proceed.
+  If ``bl1_plat_mem_check()`` also passes, this may result in an unexpectedly
+  large copy of data into secure memory.
+
+If the platform's implementation of ``bl1_plat_mem_check()`` is correct then it
+may help prevent the above 2 vulnerabilities from being exploited. However, the
+ARM platform version of this function contains a similar vulnerability:
+
+- Line 88 of ``plat/arm/common/arm_bl1_fwu.c`` in function of
+  ``bl1_plat_mem_check()``:
+
+  .. code:: c
+
+    while (mmap[index].mem_size) {
+        if ((mem_base >= mmap[index].mem_base) &&
+            ((mem_base + mem_size)
+            <= (mmap[index].mem_base +
+            mmap[index].mem_size)))
+            return 0;
+
+        index++;
+    }
+    ...
+
+  This function checks that the passed memory region is within one of the
+  regions mapped in by ARM platforms. Here, ``mem_size`` may be the
+  ``block_size`` passed from ``bl1_fwu_image_copy()``. A very large value of
+  ``mem_size`` may result in an integer overflow and the function to incorrectly
+  return success. Platforms that copy this insecure pattern will have the same
+  vulnerability.
+
+.. _48bfb88: https://github.com/ARM-software/arm-trusted-firmware/commit/48bfb88
+.. _Pull Request #783: https://github.com/ARM-software/arm-trusted-firmware/pull/783
diff --git a/docs/security_advisories/security-advisory-tfv-2.rst b/docs/security_advisories/security-advisory-tfv-2.rst
new file mode 100644
index 00000000..1c3a28f1
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-2.rst
@@ -0,0 +1,57 @@
++----------------+-------------------------------------------------------------+
+| Title          | Enabled secure self-hosted invasive debug interface can     |
+|                | allow normal world to panic secure world                    |
++================+=============================================================+
+| CVE ID         | CVE-2017-7564                                               |
++----------------+-------------------------------------------------------------+
+| Date           | 02 Feb 2017                                                 |
++----------------+-------------------------------------------------------------+
+| Versions       | All versions up to v1.3                                     |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | All                                                         |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Impact         | Denial of Service (secure world panic)                      |
++----------------+-------------------------------------------------------------+
+| Fix Version    | 15 Feb 2017 `Pull Request #841`_                            |
++----------------+-------------------------------------------------------------+
+| Credit         | ARM                                                         |
++----------------+-------------------------------------------------------------+
+
+The ``MDCR_EL3.SDD`` bit controls AArch64 secure self-hosted invasive debug
+enablement. By default, the BL1 and BL31 images of the current version of ARM
+Trusted Firmware (TF) unconditionally assign this bit to ``0`` in the early
+entrypoint code, which enables debug exceptions from the secure world. This can
+be seen in the implementation of the ``el3_arch_init_common`` `AArch64 macro`_ .
+Given that TF does not currently contain support for this feature (for example,
+by saving and restoring the appropriate debug registers), this may allow a
+normal world attacker to induce a panic in the secure world.
+
+The ``MDCR_EL3.SDD`` bit should be assigned to ``1`` to disable debug exceptions
+from the secure world.
+
+Earlier versions of TF (prior to `commit 495f3d3`_) did not assign this bit.
+Since the bit has an architecturally ``UNKNOWN`` reset value, earlier versions
+may or may not have the same problem, depending on the platform.
+
+A similar issue applies to the ``MDCR_EL3.SPD32`` bits, which control AArch32
+secure self-hosted invasive debug enablement. TF assigns these bits to ``00``
+meaning that debug exceptions from Secure EL1 are enabled by the authentication
+interface. Therefore this issue only exists for AArch32 Secure EL1 code when
+secure privileged invasive debug is enabled by the authentication interface, at
+which point the device is vulnerable to other, more serious attacks anyway.
+
+However, given that TF contains no support for handling debug exceptions, the
+``MDCR_EL3.SPD32`` bits should be assigned to ``10`` to disable debug exceptions
+from AArch32 Secure EL1.
+
+Finally, this also issue applies to AArch32 platforms that use the TF SP_MIN
+image or integrate the `AArch32 equivalent`_ of the ``el3_arch_init_common``
+macro. Here the affected bits are ``SDCR.SPD``, which should also be assigned to
+``10`` instead of ``00``
+
+.. _commit 495f3d3: https://github.com/ARM-software/arm-trusted-firmware/commit/495f3d3
+.. _AArch64 macro: https://github.com/ARM-software/arm-trusted-firmware/blob/bcc2bf0/include/common/aarch64/el3_common_macros.S#L85
+.. _AArch32 equivalent: https://github.com/ARM-software/arm-trusted-firmware/blob/bcc2bf0/include/common/aarch32/el3_common_macros.S#L41
+.. _Pull Request #841: https://github.com/ARM-software/arm-trusted-firmware/pull/841
diff --git a/docs/security_advisories/security-advisory-tfv-3.rst b/docs/security_advisories/security-advisory-tfv-3.rst
new file mode 100644
index 00000000..42415730
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-3.rst
@@ -0,0 +1,82 @@
++----------------+-------------------------------------------------------------+
+| Title          | RO memory is always executable at AArch64 Secure EL1        |
++================+=============================================================+
+| CVE ID         | CVE-2017-7563                                               |
++----------------+-------------------------------------------------------------+
+| Date           | 06 Apr 2017                                                 |
++----------------+-------------------------------------------------------------+
+| Versions       | v1.3 (since `Pull Request #662`_)                           |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | AArch64 BL2, TSP or other users of xlat_tables library      |
+| Affected       | executing at AArch64 Secure EL1                             |
++----------------+-------------------------------------------------------------+
+| Impact         | Unexpected Privilege Escalation                             |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #924`_                                        |
++----------------+-------------------------------------------------------------+
+| Credit         | ARM                                                         |
++----------------+-------------------------------------------------------------+
+
+The translation table library in ARM Trusted Firmware (TF) (under
+``lib/xlat_tables`` and ``lib/xlat_tables_v2``) provides APIs to help program
+translation tables in the MMU. The xlat\_tables client specifies its required
+memory mappings in the form of ``mmap_region`` structures.  Each ``mmap_region``
+has memory attributes represented by the ``mmap_attr_t`` enumeration type. This
+contains flags to control data access permissions (``MT_RO``/``MT_RW``) and
+instruction execution permissions (``MT_EXECUTE``/``MT_EXECUTE_NEVER``). Thus a
+mapping specifying both ``MT_RO`` and ``MT_EXECUTE_NEVER`` should result in a
+Read-Only (RO), non-executable memory region.
+
+This feature does not work correctly for AArch64 images executing at Secure EL1.
+Any memory region mapped as RO will always be executable, regardless of whether
+the client specified ``MT_EXECUTE`` or ``MT_EXECUTE_NEVER``.
+
+The vulnerability is known to affect the BL2 and Test Secure Payload (TSP)
+images on platforms that enable the ``SEPARATE_CODE_AND_RODATA`` build option,
+which includes all ARM standard platforms, and the upstream Xilinx and NVidia
+platforms. The RO data section for these images on these platforms is
+unexpectedly executable instead of non-executable. Other platforms or
+``xlat_tables`` clients may also be affected.
+
+The vulnerability primarily manifests itself after `Pull Request #662`_.  Before
+that, ``xlat_tables`` clients could not specify instruction execution
+permissions separately to data access permissions. All RO normal memory regions
+were implicitly executable. Before `Pull Request #662`_.  the vulnerability
+would only manifest itself for device memory mapped as RO; use of this mapping
+is considered rare, although the upstream QEMU platform uses this mapping when
+the ``DEVICE2_BASE`` build option is used.
+
+Note that one or more separate vulnerabilities are also required to exploit this
+vulnerability.
+
+The vulnerability is due to incorrect handling of the execute-never bits in the
+translation tables. The EL3 translation regime uses a single ``XN`` bit to
+determine whether a region is executable. The Secure EL1&0 translation regime
+handles 2 Virtual Address (VA) ranges and so uses 2 bits, ``UXN`` and ``PXN``.
+The ``xlat_tables`` library only handles the ``XN`` bit, which maps to ``UXN``
+in the Secure EL1&0 regime. As a result, this programs the Secure EL0 execution
+permissions but always leaves the memory as executable at Secure EL1.
+
+The vulnerability is mitigated by the following factors:
+
+- The xlat\_tables library ensures that all Read-Write (RW) memory regions are
+  non-executable by setting the ``SCTLR_ELx.WXN`` bit. This overrides any value
+  of the ``XN``, ``UXN`` or ``PXN`` bits in the translation tables. See the
+  ``enable_mmu()`` function:
+
+  .. code:: c
+
+      sctlr = read_sctlr_el##_el();               \
+      sctlr |= SCTLR_WXN_BIT | SCTLR_M_BIT;       \
+
+- AArch32 configurations are unaffected. Here the ``XN`` bit controls execution
+  privileges of the currently executing translation regime, which is the desired
+  behaviour.
+
+- ARM TF EL3 code (for example BL1 and BL31) ensures that all non-secure memory
+  mapped into the secure world is non-executable by setting the ``SCR_EL3.SIF``
+  bit. See the ``el3_arch_init_common`` macro in ``el3_common_macros.S``.
+
+.. _Pull Request #662: https://github.com/ARM-software/arm-trusted-firmware/pull/662
+.. _Pull Request #924: https://github.com/ARM-software/arm-trusted-firmware/pull/924
diff --git a/docs/security_advisories/security-advisory-tfv-4.rst b/docs/security_advisories/security-advisory-tfv-4.rst
new file mode 100644
index 00000000..9f304c63
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-4.rst
@@ -0,0 +1,120 @@
++----------------+-------------------------------------------------------------+
+| Title          | Malformed Firmware Update SMC can result in copy or         |
+|                | authentication of unexpected data in secure memory in       |
+|                | AArch32 state                                               |
++================+=============================================================+
+| CVE ID         | CVE-2017-9607                                               |
++----------------+-------------------------------------------------------------+
+| Date           | 20 Jun 2017                                                 |
++----------------+-------------------------------------------------------------+
+| Versions       | None (only between 22 May 2017 and 14 June 2017)            |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | Platforms that use AArch32 BL1 plus untrusted normal world  |
+| Affected       | firmware update code executing before BL31                  |
++----------------+-------------------------------------------------------------+
+| Impact         | Copy or authentication of unexpected data in the secure     |
+|                | memory                                                      |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #979`_ (merged on 14 June 2017)               |
++----------------+-------------------------------------------------------------+
+| Credit         | ARM                                                         |
++----------------+-------------------------------------------------------------+
+
+The ``include/lib/utils_def.h`` header file provides the
+``check_uptr_overflow()`` macro, which aims at detecting arithmetic overflows
+that may occur when computing the sum of a base pointer and an offset. This
+macro evaluates to 1 if the sum of the given base pointer and offset would
+result in a value large enough to wrap around, which may lead to unpredictable
+behaviour.
+
+The macro code is at line 52, referring to the version of the code as of `commit
+c396b73`_:
+
+.. code:: c
+
+    /*
+     * Evaluates to 1 if (ptr + inc) overflows, 0 otherwise.
+     * Both arguments must be unsigned pointer values (i.e. uintptr_t).
+     */
+    #define check_uptr_overflow(ptr, inc)       \
+        (((ptr) > UINTPTR_MAX - (inc)) ? 1 : 0)
+
+This macro does not work correctly for AArch32 images. It fails to detect
+overflows when the sum of its two parameters fall into the ``[2^32, 2^64 - 1]``
+range. Therefore, any AArch32 code relying on this macro to detect such integer
+overflows is actually not protected.
+
+The buggy code has been present in ARM Trusted Firmware (TF) since `Pull Request
+#678`_ was merged (on 18 August 2016). However, the upstream code was not
+vulnerable until `Pull Request #939`_ was merged (on 22 May 2017), which
+introduced AArch32 support for the Trusted Board Boot (TBB) feature. Before
+then, the ``check_uptr_overflow()`` macro was not used in AArch32 code.
+
+The vulnerability resides in the BL1 FWU SMC handling code and it may be
+exploited when *all* the following conditions apply:
+
+- Platform code uses TF BL1 with the ``TRUSTED_BOARD_BOOT`` build option.
+
+- Platform code uses the Firmware Update (FWU) code provided in
+  ``bl1/bl1_fwu.c``, which is part of the TBB support.
+
+- TF BL1 is compiled with the ``ARCH=aarch32`` build option.
+
+In this context, the AArch32 BL1 image might fail to detect potential integer
+overflows in the input validation checks while handling the
+``FWU_SMC_IMAGE_COPY`` and ``FWU_SMC_IMAGE_AUTH`` SMCs.
+
+The ``FWU_SMC_IMAGE_COPY`` SMC handler is designed to copy an image into secure
+memory for subsequent authentication. This is implemented by the
+``bl1_fwu_image_copy()`` function, which has the following function prototype:
+
+.. code:: c
+
+     static int bl1_fwu_image_copy(unsigned int image_id,
+                        uintptr_t image_src,
+                        unsigned int block_size,
+                        unsigned int image_size,
+                        unsigned int flags)
+
+``image_src`` is an SMC argument and therefore potentially controllable by an
+attacker. A very large 32-bit value, for example ``2^32 -1``, may result in the
+sum of ``image_src`` and ``block_size`` overflowing a 32-bit type, which
+``check_uptr_overflow()`` will fail to detect.  Depending on its implementation,
+the platform-specific function ``bl1_plat_mem_check()`` might get defeated by
+these unsanitized values and allow the following memory copy operation, that
+would wrap around.  This may allow an attacker to copy unexpected data into
+secure memory if the memory is mapped in BL1's address space, or cause a fatal
+exception if it's not.
+
+The ``FWU_SMC_IMAGE_AUTH`` SMC handler is designed to authenticate an image
+resident in secure memory. This is implemented by the ``bl1_fwu_image_auth()``
+function, which has the following function prototype:
+
+.. code:: c
+
+    static int bl1_fwu_image_auth(unsigned int image_id,
+                        uintptr_t image_src,
+                        unsigned int image_size,
+                        unsigned int flags)
+
+Similarly, if an attacker has control over the ``image_src`` or ``image_size``
+arguments through the SMC interface and injects high values whose sum overflows,
+they might defeat the ``bl1_plat_mem_check()`` function and make the
+authentication module read data outside of what's normally allowed by the
+platform code or crash the platform.
+
+Note that in both cases, a separate vulnerability is required to leverage this
+vulnerability; for example a way to get the system to change its behaviour based
+on the unexpected secure memory accesses.  Moreover, the normal world FWU code
+would need to be compromised in order to send a malformed FWU SMC that triggers
+an integer overflow.
+
+The vulnerability is known to affect all ARM standard platforms when enabling
+the ``TRUSTED_BOARD_BOOT`` and ``ARCH=aarch32`` build options.  Other platforms
+may also be affected if they fulfil the above conditions.
+
+.. _commit c396b73: https://github.com/ARM-software/arm-trusted-firmware/commit/c396b73
+.. _Pull Request #678: https://github.com/ARM-software/arm-trusted-firmware/pull/678
+.. _Pull Request #939: https://github.com/ARM-software/arm-trusted-firmware/pull/939
+.. _Pull Request #979: https://github.com/ARM-software/arm-trusted-firmware/pull/979
diff --git a/docs/security_advisories/security-advisory-tfv-5.rst b/docs/security_advisories/security-advisory-tfv-5.rst
new file mode 100644
index 00000000..65256452
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-5.rst
@@ -0,0 +1,42 @@
++----------------+-------------------------------------------------------------+
+| Title          | Not initializing or saving/restoring ``PMCR_EL0`` can leak  |
+|                | secure world timing information                             |
++================+=============================================================+
+| CVE ID         | CVE-2017-15031                                              |
++----------------+-------------------------------------------------------------+
+| Date           | 02 Oct 2017                                                 |
++----------------+-------------------------------------------------------------+
+| Versions       | All, up to and including v1.4                               |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | All                                                         |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Impact         | Leakage of sensitive secure world timing information        |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #1127`_ (merged on 18 October 2017)           |
++----------------+-------------------------------------------------------------+
+| Credit         | Arm                                                         |
++----------------+-------------------------------------------------------------+
+
+The ``PMCR_EL0`` (Performance Monitors Control Register) provides details of the
+Performance Monitors implementation, including the number of counters
+implemented, and configures and controls the counters. If the ``PMCR_EL0.DP``
+bit is set to zero, the cycle counter (when enabled) counts during secure world
+execution, even when prohibited by the debug signals.
+
+Since Arm TF does not save and restore ``PMCR_EL0`` when switching between the
+normal and secure worlds, normal world code can set ``PMCR_EL0.DP`` to zero to
+cause leakage of secure world timing information. This register should be added
+to the list of saved/restored registers.
+
+Furthermore, ``PMCR_EL0.DP`` has an architecturally ``UNKNOWN`` reset value.
+Since Arm TF does not initialize this register, it's possible that on at least
+some implementations, ``PMCR_EL0.DP`` is set to zero by default. This and other
+bits with an architecturally UNKNOWN reset value should be initialized to
+sensible default values in the secure context.
+
+The same issue exists for the equivalent AArch32 register, ``PMCR``, except that
+here ``PMCR_EL0.DP`` architecturally resets to zero.
+
+.. _Pull Request #1127: https://github.com/ARM-software/arm-trusted-firmware/pull/1127
diff --git a/docs/security_advisories/security-advisory-tfv-6.rst b/docs/security_advisories/security-advisory-tfv-6.rst
new file mode 100644
index 00000000..7b556d8e
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-6.rst
@@ -0,0 +1,145 @@
++----------------+-------------------------------------------------------------+
+| Title          | Arm Trusted Firmware exposure to speculative processor      |
+|                | vulnerabilities using cache timing side-channels            |
++================+=============================================================+
+| CVE ID         | `CVE-2017-5753`_ / `CVE-2017-5715`_ / `CVE-2017-5754`_      |
++----------------+-------------------------------------------------------------+
+| Date           | 03 Jan 2018 (Updated 11 Jan, 18 Jan, 26 Jan, 30 Jan and 07  |
+|                | June 2018)                                                  |
++----------------+-------------------------------------------------------------+
+| Versions       | All, up to and including v1.4                               |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | All                                                         |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Impact         | Leakage of secure world data to normal world                |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #1214`_, `Pull Request #1228`_,               |
+|                | `Pull Request #1240`_ and `Pull Request #1405`_             |
++----------------+-------------------------------------------------------------+
+| Credit         | Google / Arm                                                |
++----------------+-------------------------------------------------------------+
+
+This security advisory describes the current understanding of the Arm Trusted
+Firmware (TF) exposure to the speculative processor vulnerabilities identified
+by `Google Project Zero`_.  To understand the background and wider impact of
+these vulnerabilities on Arm systems, please refer to the `Arm Processor
+Security Update`_.
+
+Variant 1 (`CVE-2017-5753`_)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the time of writing, no vulnerable patterns have been observed in upstream TF
+code, therefore no workarounds have been applied or are planned.
+
+Variant 2 (`CVE-2017-5715`_)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Where possible on vulnerable CPUs, Arm recommends invalidating the branch
+predictor as early as possible on entry into the secure world, before any branch
+instruction is executed. There are a number of implementation defined ways to
+achieve this.
+
+For Cortex-A57 and Cortex-A72 CPUs, the Pull Requests (PRs) in this advisory
+invalidate the branch predictor when entering EL3 by disabling and re-enabling
+the MMU.
+
+For Cortex-A73 and Cortex-A75 CPUs, the PRs in this advisory invalidate the
+branch predictor when entering EL3 by temporarily dropping into AArch32
+Secure-EL1 and executing the ``BPIALL`` instruction. This workaround is
+signifiantly more complex than the "MMU disable/enable" workaround. The latter
+is not effective at invalidating the branch predictor on Cortex-A73/Cortex-A75.
+
+Note that if other privileged software, for example a Rich OS kernel, implements
+its own branch predictor invalidation during context switch by issuing an SMC
+(to execute firmware branch predictor invalidation), then there is a dependency
+on the PRs in this advisory being deployed in order for those workarounds to
+work. If that other privileged software is able to workaround the vulnerability
+locally (for example by implementing "MMU disable/enable" itself), there is no
+such dependency.
+
+`Pull Request #1240`_ and `Pull Request #1405`_ optimise the earlier fixes by
+implementing a specified `CVE-2017-5715`_ workaround SMC
+(``SMCCC_ARCH_WORKAROUND_1``) for use by normal world privileged software. This
+is more efficient than calling an arbitrary SMC (for example ``PSCI_VERSION``).
+Details of ``SMCCC_ARCH_WORKAROUND_1`` can be found in the `CVE-2017-5715
+mitigation specification`_.  The specification and implementation also enable
+the normal world to discover the presence of this firmware service.
+
+On Juno R1 we measured the round trip latency for both the ``PSCI_VERSION`` and
+``SMCCC_ARCH_WORKAROUND_1`` SMCs on Cortex-A57, using both the "MMU
+disable/enable" and "BPIALL at AArch32 Secure-EL1" workarounds described above.
+This includes the time spent in test code conforming to the SMC Calling
+Convention (SMCCC) from AArch64. For the ``SMCCC_ARCH_WORKAROUND_1`` cases, the
+test code uses SMCCC v1.1, which reduces the number of general purpose registers
+it needs to save/restore. Although the ``BPIALL`` instruction is not effective
+at invalidating the branch predictor on Cortex-A57, the drop into Secure-EL1
+with MMU disabled that this workaround entails effectively does invalidate the
+branch predictor. Hence this is a reasonable comparison.
+
+The results were as follows:
+
++------------------------------------------------------------------+-----------+
+| Test                                                             | Time (ns) |
++==================================================================+===========+
+| ``PSCI_VERSION`` baseline (without PRs in this advisory)         | 515       |
++------------------------------------------------------------------+-----------+
+| ``PSCI_VERSION`` baseline (with PRs in this advisory)            | 527       |
++------------------------------------------------------------------+-----------+
+| ``PSCI_VERSION`` with "MMU disable/enable"                       | 930       |
++------------------------------------------------------------------+-----------+
+| ``SMCCC_ARCH_WORKAROUND_1`` with "MMU disable/enable"            | 386       |
++------------------------------------------------------------------+-----------+
+| ``PSCI_VERSION`` with "BPIALL at AArch32 Secure-EL1"             | 1276      |
++------------------------------------------------------------------+-----------+
+| ``SMCCC_ARCH_WORKAROUND_1`` with "BPIALL at AArch32 Secure-EL1"  | 770       |
++------------------------------------------------------------------+-----------+
+
+Due to the high severity and wide applicability of this issue, the above
+workarounds are enabled by default (on vulnerable CPUs only), despite some
+performance and code size overhead. Platforms can choose to disable them at
+compile time if they do not require them. `Pull Request #1240`_ disables the
+workarounds for unaffected upstream platforms.
+
+For vulnerable AArch32-only CPUs (for example Cortex-A8, Cortex-A9 and
+Cortex-A17), the ``BPIALL`` instruction should be used as early as possible on
+entry into the secure world. For Cortex-A8, also set ``ACTLR[6]`` to 1 during
+early processor initialization. Note that the ``BPIALL`` instruction is not
+effective at invalidating the branch predictor on Cortex-A15. For that CPU, set
+``ACTLR[0]`` to 1 during early processor initialization, and invalidate the
+branch predictor by performing an ``ICIALLU`` instruction.
+
+On AArch32 EL3 systems, the monitor and secure-SVC code is typically tightly
+integrated, for example as part of a Trusted OS. Therefore any Variant 2
+workaround should be provided by vendors of that software and is outside the
+scope of TF. However, an example implementation in the minimal AArch32 Secure
+Payload, ``SP_MIN`` is provided in `Pull Request #1228`_.
+
+Other Arm CPUs are not vulnerable to this or other variants. This includes
+Cortex-A76, Cortex-A53, Cortex-A55, Cortex-A32, Cortex-A7 and Cortex-A5.
+
+For more information about non-Arm CPUs, please contact the CPU vendor.
+
+Variant 3 (`CVE-2017-5754`_)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This variant is only exploitable between Exception Levels within the same
+translation regime, for example between EL0 and EL1, therefore this variant
+cannot be used to access secure memory from the non-secure world, and is not
+applicable for TF. However, Secure Payloads (for example, Trusted OS) should
+provide mitigations on vulnerable CPUs to protect themselves from exploited
+Secure-EL0 applications.
+
+The only Arm CPU vulnerable to this variant is Cortex-A75.
+
+.. _Google Project Zero: https://googleprojectzero.blogspot.co.uk/2018/01/reading-privileged-memory-with-side.html
+.. _Arm Processor Security Update: http://www.arm.com/security-update
+.. _CVE-2017-5753: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5753
+.. _CVE-2017-5715: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715
+.. _CVE-2017-5754: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5754
+.. _Pull Request #1214: https://github.com/ARM-software/arm-trusted-firmware/pull/1214
+.. _Pull Request #1228: https://github.com/ARM-software/arm-trusted-firmware/pull/1228
+.. _Pull Request #1240: https://github.com/ARM-software/arm-trusted-firmware/pull/1240
+.. _Pull Request #1405: https://github.com/ARM-software/arm-trusted-firmware/pull/1405
+.. _CVE-2017-5715 mitigation specification: https://developer.arm.com/cache-speculation-vulnerability-firmware-specification
diff --git a/docs/security_advisories/security-advisory-tfv-7.rst b/docs/security_advisories/security-advisory-tfv-7.rst
new file mode 100644
index 00000000..572268aa
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-7.rst
@@ -0,0 +1,104 @@
++----------------+-------------------------------------------------------------+
+| Title          | Trusted Firmware-A exposure to cache speculation            |
+|                | vulnerability Variant 4                                     |
++================+=============================================================+
+| CVE ID         | `CVE-2018-3639`_                                            |
++----------------+-------------------------------------------------------------+
+| Date           | 21 May 2018 (Updated 7 June 2018)                           |
++----------------+-------------------------------------------------------------+
+| Versions       | All, up to and including v1.5                               |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | All                                                         |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Impact         | Leakage of secure world data to normal world                |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #1392`_, `Pull Request #1397`_                |
++----------------+-------------------------------------------------------------+
+| Credit         | Google                                                      |
++----------------+-------------------------------------------------------------+
+
+This security advisory describes the current understanding of the Trusted
+Firmware-A (TF-A) exposure to Variant 4 of the cache speculation vulnerabilities
+identified by `Google Project Zero`_.  To understand the background and wider
+impact of these vulnerabilities on Arm systems, please refer to the `Arm
+Processor Security Update`_.
+
+At the time of writing, the TF-A project is not aware of a Variant 4 exploit
+that could be used against TF-A. It is likely to be very difficult to achieve an
+exploit against current standard configurations of TF-A, due to the limited
+interfaces into the secure world with attacker-controlled inputs. However, this
+is becoming increasingly difficult to guarantee with the introduction of complex
+new firmware interfaces, for example the `Software Delegated Exception Interface
+(SDEI)`_.  Also, the TF-A project does not have visibility of all
+vendor-supplied interfaces. Therefore, the TF-A project takes a conservative
+approach by mitigating Variant 4 in hardware wherever possible during secure
+world execution. The mitigation is enabled by setting an implementation defined
+control bit to prevent the re-ordering of stores and loads.
+
+For each affected CPU type, TF-A implements one of the two following mitigation
+approaches in `Pull Request #1392`_ and `Pull Request #1397`_.  Both approaches
+have a system performance impact, which varies for each CPU type and use-case.
+The mitigation code is enabled by default, but can be disabled at compile time
+for platforms that are unaffected or where the risk is deemed low enough.
+
+Arm CPUs not mentioned below are unaffected.
+
+Static mitigation
+~~~~~~~~~~~~~~~~~
+
+For affected CPUs, this approach enables the mitigation during EL3
+initialization, following every PE reset. No mechanism is provided to disable
+the mitigation at runtime.
+
+This approach permanently mitigates the entire software stack and no additional
+mitigation code is required in other software components.
+
+TF-A implements this approach for the following affected CPUs:
+
+- Cortex-A57 and Cortex-A72, by setting bit 55 (Disable load pass store) of
+  ``CPUACTLR_EL1`` (``S3_1_C15_C2_0``).
+
+- Cortex-A73, by setting bit 3 of ``S3_0_C15_C0_0`` (not documented in the
+  Technical Reference Manual (TRM)).
+
+- Cortex-A75, by setting bit 35 (reserved in TRM) of ``CPUACTLR_EL1``
+  (``S3_0_C15_C1_0``).
+
+Dynamic mitigation
+~~~~~~~~~~~~~~~~~~
+
+For affected CPUs, this approach also enables the mitigation during EL3
+initialization, following every PE reset. In addition, this approach implements
+``SMCCC_ARCH_WORKAROUND_2`` in the Arm architectural range to allow callers at
+lower exception levels to temporarily disable the mitigation in their execution
+context, where the risk is deemed low enough. This approach enables mitigation
+on entry to EL3, and restores the mitigation state of the lower exception level
+on exit from EL3. For more information on this approach, see `Firmware
+interfaces for mitigating cache speculation vulnerabilities`_.
+
+This approach may be complemented by additional mitigation code in other
+software components, for example code that calls ``SMCCC_ARCH_WORKAROUND_2``.
+However, even without any mitigation code in other software components, this
+approach will effectively permanently mitigate the entire software stack, since
+the default mitigation state for firmware-managed execution contexts is enabled.
+
+Since the expectation in this approach is that more software executes with the
+mitigation disabled, this may result in better system performance than the
+static approach for some systems or use-cases.  However, for other systems or
+use-cases, this performance saving may be outweighed by the additional overhead
+of ``SMCCC_ARCH_WORKAROUND_2`` calls and TF-A exception handling.
+
+TF-A implements this approach for the following affected CPU:
+
+- Cortex-A76, by setting and clearing bit 16 (reserved in TRM) of
+  ``CPUACTLR2_EL1`` (``S3_0_C15_C1_1``).
+
+.. _Google Project Zero: https://bugs.chromium.org/p/project-zero/issues/detail?id=1528
+.. _Arm Processor Security Update: http://www.arm.com/security-update
+.. _CVE-2018-3639: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639
+.. _Software Delegated Exception Interface (SDEI): http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
+.. _Firmware interfaces for mitigating cache speculation vulnerabilities: https://developer.arm.com/cache-speculation-vulnerability-firmware-specification
+.. _Pull Request #1392: https://github.com/ARM-software/arm-trusted-firmware/pull/1392
+.. _Pull Request #1397: https://github.com/ARM-software/arm-trusted-firmware/pull/1397
diff --git a/docs/security_advisories/security-advisory-tfv-8.rst b/docs/security_advisories/security-advisory-tfv-8.rst
new file mode 100644
index 00000000..d04c575a
--- /dev/null
+++ b/docs/security_advisories/security-advisory-tfv-8.rst
@@ -0,0 +1,99 @@
++----------------+-------------------------------------------------------------+
+| Title          | Not saving x0 to x3 registers can leak information from one |
+|                | Normal World SMC client to another                          |
++================+=============================================================+
+| CVE ID         | CVE-2018-19440                                              |
++----------------+-------------------------------------------------------------+
+| Date           | 27 Nov 2018                                                 |
++----------------+-------------------------------------------------------------+
+| Versions       | All                                                         |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Configurations | Multiple normal world SMC clients calling into AArch64 BL31 |
+| Affected       |                                                             |
++----------------+-------------------------------------------------------------+
+| Impact         | Leakage of SMC return values from one normal world SMC      |
+|                | client to another                                           |
++----------------+-------------------------------------------------------------+
+| Fix Version    | `Pull Request #1710`_                                       |
++----------------+-------------------------------------------------------------+
+| Credit         | Secmation                                                   |
++----------------+-------------------------------------------------------------+
+
+When taking an exception to EL3, BL31 saves the CPU context. The aim is to
+restore it before returning into the lower exception level software that called
+into the firmware. However, for an SMC exception, the general purpose registers
+``x0`` to ``x3`` are not part of the CPU context saved on the stack.
+
+As per the `SMC Calling Convention`_, up to 4 values may be returned to the
+caller in registers ``x0`` to ``x3``. In TF-A, these return values are written
+into the CPU context, typically using one of the ``SMC_RETx()`` macros provided
+in the ``include/lib/aarch64/smccc_helpers.h`` header file.
+
+Before returning to the caller, the ``restore_gp_registers()`` function is
+called. It restores the values of all general purpose registers taken from the
+CPU context stored on the stack. This includes registers ``x0`` to ``x3``, as
+can be seen in the ``lib/el3_runtime/aarch64/context.S`` file at line 339
+(referring to the version of the code as of `commit c385955`_):
+
+.. code:: c
+
+    /*
+     * This function restores all general purpose registers except x30 from the
+     * CPU context. x30 register must be explicitly restored by the caller.
+     */
+    func restore_gp_registers
+        ldp x0, x1, [sp, #CTX_GPREGS_OFFSET + CTX_GPREG_X0]
+        ldp x2, x3, [sp, #CTX_GPREGS_OFFSET + CTX_GPREG_X2]
+
+In the case of an SMC handler that does not use all 4 return values, the
+remaining ones are left unchanged in the CPU context. As a result,
+``restore_gp_registers()`` restores the stale values saved by a previous SMC
+request (or asynchronous exception to EL3) that used these return values.
+
+In the presence of multiple normal world SMC clients, this behaviour might leak
+some of the return values from one client to another. For example, if a victim
+client first sends an SMC that returns 4 values, a malicious client may then
+send a second SMC expecting no return values (for example, a
+``SDEI_EVENT_COMPLETE`` SMC) to get the 4 return values of the victim client.
+
+In general, the responsibility for mitigating threats due to the presence of
+multiple normal world SMC clients lies with EL2 software.  When present, EL2
+software must trap SMC calls from EL1 software to ensure secure behaviour.
+
+For this reason, TF-A does not save ``x0`` to ``x3`` in the CPU context on an
+SMC synchronous exception. It has behaved this way since the first version.
+
+We can confirm that at least upstream KVM-based systems mitigate this threat,
+and are therefore unaffected by this issue. Other EL2 software should be audited
+to assess the impact of this threat.
+
+EL2 software might find mitigating this threat somewhat onerous, because for all
+SMCs it would need to be aware of which return registers contain valid data, so
+it can sanitise any unused return registers. On the other hand, mitigating this
+in EL3 is relatively easy and cheap. Therefore, TF-A will now ensure that no
+information is leaked through registers ``x0`` to ``x3``, by preserving the
+register state over the call.
+
+Note that AArch32 TF-A is not affected by this issue. The SMC handling code in
+``SP_MIN`` already saves all general purpose registers - including ``r0`` to
+``r3``, as can be seen in the ``include/lib/aarch32/smccc_macros.S`` file at
+line 19 (referring to the version of the code as of `commit c385955`_):
+
+.. code:: c
+
+    /*
+     * Macro to save the General purpose registers (r0 - r12), the banked
+     * spsr, lr, sp registers and the `scr` register to the SMC context on entry
+     * due a SMC call. The `lr` of the current mode (monitor) is expected to be
+     * already saved. The `sp` must point to the `smc_ctx_t` to save to.
+     * Additionally, also save the 'pmcr' register as this is updated whilst
+     * executing in the secure world.
+     */
+        .macro smccc_save_gp_mode_regs
+        /* Save r0 - r12 in the SMC context */
+        stm sp, {r0-r12}
+
+.. _commit c385955: https://github.com/ARM-software/arm-trusted-firmware/commit/c385955
+.. _SMC Calling Convention: http://arminfo.emea.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+.. _Pull Request #1710: https://github.com/ARM-software/arm-trusted-firmware/pull/1710