Merge changes from topic "jts/docs" into integration

* changes:
  Docs fixes
  Update security documentation

4 files changed, 193 insertions, 26 deletions

diff --git a/docs/contents.rst b/docs/contents.rst
new file mode 100644
index 00000000..4909dabe
--- /dev/null
+++ b/docs/contents.rst
@@ -0,0 +1,165 @@
+Trusted Firmware-A Documentation Contents
+=========================================
+
+This document serves as a list of the documentation that is included with the
+Trusted Firmware-A source.
+
+Introduction
+------------
+
+`About Trusted Firmware-A`_
+
+Getting Started
+---------------
+
+`Frequently-Asked Questions (FAQ)`_
+
+`Image Terminology`_
+
+`Porting Guide`_
+
+`User Guide`_
+
+Contributing
+------------
+
+`Coding Style and Guidelines`_
+
+`Contributor Acknowledgements`_
+
+`Contributor's Guide`_
+
+`License`_
+
+`Maintainers`_
+
+Processes and Policies
+----------------------
+
+`Platform Compatibility Policy`_
+
+`Release Processes`_
+
+Secure Payload Dispatch
+-----------------------
+
+`OP-TEE Dispatcher`_
+
+`Trusted Little Kernel (TLK) Dispatcher`_
+
+`Trusty Dispatcher`_
+
+System Design and Components
+----------------------------
+
+`Arm CPU Specific Build Macros`_
+
+`Arm SiP Services`_
+
+`Authentication Framework & Chain of Trust`_
+
+`CPU Reset`_
+
+`EL3 Runtime Service Writer’s Guide`_
+
+`Exception Handling Framework`_
+
+`Firmware Design Overview`_
+
+`Firmware Update (FWU)`_
+
+`Interrupt Management Framework`_
+
+`Library at ROM`_
+
+`Platform Interrupt Controller API`_
+
+`PSCI Library Integration Guide for Armv8-A AArch32 systems`_
+
+`PSCI Power Domain Tree design`_
+
+`Reliability, Availability, and Serviceability (RAS) Extensions`_
+
+`Secure Partition Manager`_
+
+`Software Delegated Exception Interface`_
+
+`Translation (XLAT) Tables Library`_
+
+`Trusted Board Boot Design Guide`_
+
+Performance and Testing
+-----------------------
+
+`PSCI Performance Measurements on Arm Juno Development Platform`_
+
+Security and Advisories
+-----------------------
+
+`Security Processes`_
+
+`TFV-1`_
+
+`TFV-2`_
+
+`TFV-3`_
+
+`TFV-4`_
+
+`TFV-5`_
+
+`TFV-6`_
+
+`TFV-7`_
+
+`TFV-8`_
+
+Other Documents
+---------------
+
+`Change Log`_
+
+.. _About Trusted Firmware-A: ../readme.rst
+.. _Frequently-Asked Questions (FAQ): ./process/faq.rst
+.. _Image Terminology: ./getting_started/image-terminology.rst
+.. _Porting Guide: ./getting_started/porting-guide.rst
+.. _User Guide: ./getting_started/user-guide.rst
+.. _Coding Style and Guidelines: ./process/coding-guidelines.rst
+.. _Contributor Acknowledgements: ./acknowledgements.rst
+.. _`Contributor's Guide`: ./process/contributing.rst
+.. _License: ../license.rst
+.. _Maintainers: ./maintainers.rst
+.. _Platform Compatibility Policy: ./process/platform-compatibility-policy.rst
+.. _Release Processes: ./process/release-information.rst
+.. _Arm SiP Services: ./components/arm-sip-service.rst
+.. _Exception Handling Framework: ./components/exception-handling.rst
+.. _Firmware Update (FWU): ./components/firmware-update.rst
+.. _Interrupt Management Framework: ./design/interrupt-framework-design.rst
+.. _Library at ROM: ./components/romlib-design.rst
+.. _Platform Interrupt Controller API: ./components/platform-interrupt-controller-API.rst
+.. _`Reliability, Availability, and Serviceability (RAS) Extensions`: ./components/ras.rst
+.. _Secure Partition Manager: ./components/secure-partition-manager-design.rst
+.. _Software Delegated Exception Interface: ./components/sdei.rst
+.. _Translation (XLAT) Tables Library: ./components/xlat-tables-lib-v2-design.rst
+.. _OP-TEE Dispatcher: ./components/spd/optee-dispatcher.rst
+.. _Trusted Little Kernel (TLK) Dispatcher: ./components/spd/tlk-dispatcher.rst
+.. _Trusty Dispatcher: ./components/spd/trusty-dispatcher.rst
+.. _Arm CPU Specific Build Macros: ./design/cpu-specific-build-macros.rst
+.. _`Authentication Framework & Chain of Trust`: ./design/auth-framework.rst
+.. _CPU Reset: ./design/reset-design.rst
+.. _`EL3 Runtime Service Writer’s Guide`: ./getting_started/rt-svc-writers-guide.rst
+.. _Firmware Design Overview: ./design/firmware-design.rst
+.. _PSCI Library Integration Guide for Armv8-A AArch32 systems: ./getting_started/psci-lib-integration-guide.rst
+.. _PSCI Power Domain Tree design: ./design/psci-pd-tree.rst
+.. _Trusted Board Boot Design Guide: ./design/trusted-board-boot.rst
+.. _PSCI Performance Measurements on Arm Juno Development Platform: ./perf/psci-performance-juno.rst
+.. _Security Processes: ./process/security.rst
+.. _Change Log: ./change-log.rst
+.. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst
+.. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst
+.. _TFV-3: ./security_advisories/security-advisory-tfv-3.rst
+.. _TFV-4: ./security_advisories/security-advisory-tfv-4.rst
+.. _TFV-5: ./security_advisories/security-advisory-tfv-5.rst
+.. _TFV-6: ./security_advisories/security-advisory-tfv-6.rst
+.. _TFV-7: ./security_advisories/security-advisory-tfv-7.rst
+.. _TFV-8: ./security_advisories/security-advisory-tfv-8.rst
diff --git a/docs/process/security.rst b/docs/process/security.rst
index b4831c82..d1c997ba 100644
--- a/docs/process/security.rst
+++ b/docs/process/security.rst
@@ -4,28 +4,29 @@ Security Handling
 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
+We disclose all security vulnerabilities we find, or are advised about, that are
+relevant to Trusted Firmware-A. 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.
+We disclose TF-A vulnerabilities as Security Advisories, all of which are listed
+at the bottom of this page. Any new ones will, additionally, be announced as
+issues in the project's `issue tracker`_ with the ``security-advisory`` tag. You
+can receive notification emails for these by watching the "Trusted Firmware-A"
+project at https://developer.trustedfirmware.org/.
 
 Found a Security Issue?
 -----------------------
 
-Although we try to keep TF secure, we can only do so with the help of the
+Although we try to keep TF-A 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
+If you think you have found a security vulnerability, please **do not** report it
+in the `issue tracker`_. Instead send an email to
 trusted-firmware-security@arm.com
 
 Please include:
 
-* Trusted Firmware version (or commit) affected
+* Trusted Firmware-A version (or commit) affected
 
 * A description of the concern or vulnerability
 
@@ -49,10 +50,11 @@ 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
+ensure providers of products that use TF-A 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.
+Afterwards, we encourage you to write-up your findings about the TF-A source
+code.
 
 Attribution
 -----------
@@ -81,7 +83,7 @@ Security Advisories
 | `TFV-5`_  | Not initializing or saving/restoring PMCR_EL0 can leak secure    |
 |           | world timing information                                         |
 +-----------+------------------------------------------------------------------+
-| `TFV-6`_  | Arm Trusted Firmware exposure to speculative processor           |
+| `TFV-6`_  | Trusted Firmware-A exposure to speculative processor             |
 |           | vulnerabilities using cache timing side-channels                 |
 +-----------+------------------------------------------------------------------+
 | `TFV-7`_  | Trusted Firmware-A exposure to cache speculation vulnerability   |
@@ -91,7 +93,7 @@ Security Advisories
 |           | Normal World SMC client to another                               |
 +-----------+------------------------------------------------------------------+
 
-.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
+.. _issue tracker: https://developer.trustedfirmware.org/project/board/1/
 .. _this PGP/GPG key: security-reporting.asc
 .. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst
 .. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst
diff --git a/docs/security_advisories/security-advisory-tfv-6.rst b/docs/security_advisories/security-advisory-tfv-6.rst
index f968262c..495eddda 100644
--- a/docs/security_advisories/security-advisory-tfv-6.rst
+++ b/docs/security_advisories/security-advisory-tfv-6.rst
@@ -2,7 +2,7 @@ Advisory TFV-6 (CVE-2017-5753, CVE-2017-5715, CVE-2017-5754)
 ============================================================
 
 +----------------+-------------------------------------------------------------+
-| Title          | Arm Trusted Firmware exposure to speculative processor      |
+| Title          | Trusted Firmware-A exposure to speculative processor        |
 |                | vulnerabilities using cache timing side-channels            |
 +================+=============================================================+
 | CVE ID         | `CVE-2017-5753`_ / `CVE-2017-5715`_ / `CVE-2017-5754`_      |
@@ -24,11 +24,11 @@ Advisory TFV-6 (CVE-2017-5753, CVE-2017-5715, CVE-2017-5754)
 | 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`_.
+This security advisory describes the current understanding of the Trusted
+Firmware-A 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`_)
 ----------------------------
diff --git a/readme.rst b/readme.rst
index 2737d5c6..02aa392e 100644
--- a/readme.rst
+++ b/readme.rst
@@ -335,14 +335,14 @@ Security advisories
 .. _Trusty Secure OS: https://source.android.com/security/trusty
 .. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
 .. _issue tracker: https://developer.trustedfirmware.org/project/board/1/
-.. _Security Center: ./docs/security-center.rst
+.. _Security Center: ./docs/process/security.rst
 .. _license: ./license.rst
-.. _Contributing Guidelines: ./contributing.rst
-.. _Acknowledgments: ./acknowledgements.rst
-.. _Firmware Design: ./docs/firmware-design.rst
+.. _Contributing Guidelines: ./docs/process/contributing.rst
+.. _Acknowledgments: ./docs/acknowledgements.rst
+.. _Firmware Design: ./docs/design/firmware-design.rst
 .. _Change Log: ./docs/change-log.rst
-.. _User Guide: ./docs/user-guide.rst
-.. _Porting Guide: ./docs/porting-guide.rst
+.. _User Guide: ./docs/getting-started/user-guide.rst
+.. _Porting Guide: ./docs/getting-started/porting-guide.rst
 .. _FreeBSD: http://www.freebsd.org
 .. _SCC: http://www.simple-cc.org/
 .. _Security Advisory TFV-1: ./docs/security_advisories/security-advisory-tfv-1.rst