19 files changed, 297 insertions, 109 deletions
diff --git a/docs/change-log.rst b/docs/change-log.rst
index 5941a8ba..71f24fd6 100644
--- a/docs/change-log.rst
+++ b/docs/change-log.rst
@@ -2425,9 +2425,10 @@ releases of TF-A.
 .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
 .. _PSCI Integration Guide: ./getting_started/psci-lib-integration-guide.rst
 .. _Developer Certificate of Origin: ../dco.txt
-.. _Contribution Guide: ./contributing.rst
+.. _Contribution Guide: ./process/contributing.rst
 .. _Authentication framework: ./design/auth-framework.rst
 .. _Firmware Update: ./design/firmware-update.rst
+.. _Firmware Design: ./design/firmware-design.rst
 .. _TF-A Reset Design: ./design/reset-design.rst
 .. _Power Domain Topology Design: ./design/psci-pd-tree.rst
 .. _TF-A wiki on GitHub: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst
index 9cbf1994..e450d375 100644
--- a/docs/components/arm-sip-service.rst
+++ b/docs/components/arm-sip-service.rst
@@ -92,5 +92,5 @@ respectively.
 *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
 
 .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
-.. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework
-.. _Firmware Design document: ./firmware-design.rst
+.. _Performance Measurement Framework: ../design/firmware-design.rst#user-content-performance-measurement-framework
+.. _Firmware Design document: ../design/firmware-design.rst
diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst
index 8f74eb65..0d017331 100644
--- a/docs/components/exception-handling.rst
+++ b/docs/components/exception-handling.rst
@@ -622,5 +622,5 @@ The |EHF| has the following limitations:
 
 *Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.*
 
-.. _Interrupt Framework Design: interrupt-framework-design.rst
+.. _Interrupt Framework Design: ../design/interrupt-framework-design.rst
 .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst
index 31f5917e..d6bb6ce8 100644
--- a/docs/components/firmware-update.rst
+++ b/docs/components/firmware-update.rst
@@ -394,10 +394,10 @@ This is only allowed if the image is not being executed.
 
 *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
 
-.. _Trusted Board Boot: ./trusted-board-boot.rst
+.. _Trusted Board Boot: ../design/trusted-board-boot.rst
 .. _Porting Guide: ../getting_started/porting-guide.rst
 .. _here: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
-.. _Authentication Framework Design: ./auth-framework.rst
+.. _Authentication Framework Design: ../design/auth-framework.rst
 .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
 
 .. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst
index 845a2955..6d0e1563 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -41,7 +41,7 @@ execute the registered handler [10]. The client terminates its execution with
 original EL2 execution [13]. Note that the SDEI interrupt remains active until
 the client handler completes, at which point EL3 does EOI [12].
 
-Other than events bound to interrupts (as depicted in the sequence above, SDEI
+Other than events bound to interrupts, as depicted in the sequence above, SDEI
 events can be explicitly dispatched in response to other exceptions, for
 example, upon receiving an *SError* or *Synchronous External Abort*. See
 `Explicit dispatch of events`_.
@@ -370,3 +370,4 @@ implemented in assembly, following a similar pattern as below:
 
 .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
 .. _SDEI porting requirements: ../getting_started/porting-guide.rst#sdei-porting-requirements
+.. _Software Delegated Exception Interface: `SDEI specification`_
diff --git a/docs/conf.py b/docs/conf.py
index 697b8711..64f12431 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -23,7 +23,7 @@ release = version # We don't need these to be distinct
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -54,6 +54,9 @@ pygments_style = 'sphinx'
 with open('global_substitutions.txt', 'r') as subs:
   rst_prolog = subs.read()
 
+# Minimum version of sphinx required
+needs_sphinx = '2.0'
+
 # -- Options for HTML output -------------------------------------------------
 
 # Don't show the "Built with Sphinx" footer
@@ -75,3 +78,8 @@ html_theme_options = {
     'prev_next_buttons_location': 'both', # Top and bottom of the page
     'style_external_links': True # Display an icon next to external links
 }
+
+# -- Options for autosectionlabel --------------------------------------------
+
+# Only generate automatic section labels for document titles
+autosectionlabel_maxdepth = 1
+\ No newline at end of file
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/design/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst
index e49c73e7..07983a90 100644
--- a/docs/design/cpu-specific-build-macros.rst
+++ b/docs/design/cpu-specific-build-macros.rst
@@ -143,6 +143,9 @@ For Cortex-A55, the following errata build flags are defined :
 -  ``ERRATA_A55_903758``: This applies errata 903758 workaround to Cortex-A55
    CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
 
+-  ``ERRATA_A55_1221012``: This applies errata 1221012 workaround to Cortex-A55
+   CPU. This needs to be enabled only for revision <= r1p0 of the CPU.
+
 For Cortex-A57, the following errata build flags are defined :
 
 -  ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index 21b82346..00e199a2 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -19,7 +19,7 @@ in either security state. The details of the interrupt management framework
 and its design can be found in TF-A Interrupt Management Design guide [4]_.
 
 TF-A also implements a library for setting up and managing the translation
-tables. The details of this library can be found in `Xlat_tables design`_.
+tables. The details of this library can be found in `Translation tables design`_.
 
 TF-A can be built to support either AArch64 or AArch32 execution state.
 
@@ -1333,7 +1333,7 @@ different CPUs during power down and reset handling. The platform can specify
 any CPU optimization it wants to enable for each CPU. It can also specify
 the CPU errata workarounds to be applied for each CPU type during reset
 handling by defining CPU errata compile time macros. Details on these macros
-can be found in the `cpu-specific-build-macros.rst`_ file.
+can be found in `CPU specific build macros`_.
 
 The CPU specific operations framework depends on the ``cpu_ops`` structure which
 needs to be exported for each type of CPU in the platform. It is defined in
@@ -2564,7 +2564,7 @@ Armv8.3-A
    to the context that is saved when doing a world switch.
 
    The TF-A itself has support for pointer authentication at runtime
-   that can be enabled by setting both options ``ENABLE_PAUTH`` and
+   that can be enabled by setting ``BRANCH_PROTECTION`` option to non-zero and
    ``CTX_INCLUDE_PAUTH_REGS`` to 1. This enables pointer authentication in BL1,
    BL2, BL31, and the TSP if it is used.
 
@@ -2577,6 +2577,12 @@ Armv8.3-A
    enabling PAuth is lower because the compiler will use the optimized
    PAuth instructions rather than the backwards-compatible ones.
 
+Armv8.5-A
+~~~~~~~~~
+
+-  Branch Target Identification feature is selected by ``BRANCH_PROTECTION``
+   option set to 1. This option defaults to 0 and this is an experimental feature.
+
 Armv7-A
 ~~~~~~~
 
@@ -2664,7 +2670,7 @@ References
 
 .. _Reset Design: ./reset-design.rst
 .. _Porting Guide: ../getting_started/porting-guide.rst
-.. _Firmware Update: ./firmware-update.rst
+.. _Firmware Update: ../components/firmware-update.rst
 .. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 .. _PSCI Library integration guide: ../getting_started/psci-lib-integration-guide.rst
@@ -2672,15 +2678,15 @@ References
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _here: ../getting_started/psci-lib-integration-guide.rst
-.. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst
+.. _CPU specific build macros: ./cpu-specific-build-macros.rst
 .. _CPUBM: ./cpu-specific-build-macros.rst
 .. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
 .. _User Guide: ../getting_started/user-guide.rst
 .. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 .. _TF-A Interrupt Management Design guide: ./interrupt-framework-design.rst
-.. _Xlat_tables design: xlat-tables-lib-v2-design.rst
-.. _Exception Handling Framework: exception-handling.rst
-.. _ROMLIB Design: romlib-design.rst
+.. _Translation tables design: ../components/xlat-tables-lib-v2-design.rst
+.. _Exception Handling Framework: ../components/exception-handling.rst
+.. _ROMLIB Design: ../components/romlib-design.rst
 .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
 
 .. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png
diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst
index 6f648f51..82be272b 100644
--- a/docs/design/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
@@ -227,7 +227,7 @@ for building and using the tool can be found in the `User Guide`_.
 
 *Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Firmware Update: firmware-update.rst
+.. _Firmware Update: ../components/firmware-update.rst
 .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt
 .. _User Guide: ../getting_started/user-guide.rst
 .. _Auth Framework: auth-framework.rst
diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 94ec9323..72865a51 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -2821,14 +2821,14 @@ amount of open resources per driver.
 .. _plat/common/aarch64/platform_mp_stack.S: ../plat/common/aarch64/platform_mp_stack.S
 .. _plat/common/aarch64/platform_up_stack.S: ../plat/common/aarch64/platform_up_stack.S
 .. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160
-.. _Power Domain Topology Design: psci-pd-tree.rst
+.. _Power Domain Topology Design: ../design/psci-pd-tree.rst
 .. _include/common/bl_common.h: ../include/common/bl_common.h
 .. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h
-.. _Firmware Design: firmware-design.rst
+.. _Firmware Design: ../design/firmware-design.rst
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _plat/arm/board/fvp/fvp_pm.c: ../plat/arm/board/fvp/fvp_pm.c
-.. _Platform compatibility policy: ./platform-compatibility-policy.rst
-.. _IMF Design Guide: interrupt-framework-design.rst
+.. _Platform compatibility policy: ../process/platform-compatibility-policy.rst
+.. _IMF Design Guide: ../design/interrupt-framework-design.rst
 .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
 .. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html
 .. _FreeBSD: https://www.freebsd.org
diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst
index f5ea0d78..25936d90 100644
--- a/docs/getting_started/psci-lib-integration-guide.rst
+++ b/docs/getting_started/psci-lib-integration-guide.rst
@@ -544,5 +544,5 @@ workarounds.
 .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
 .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Porting Guide: ../getting_started/porting-guide.rst
+.. _Porting Guide: ./porting-guide.rst
 .. _Firmware Design: ../design/firmware-design.rst
diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst
index 03212af1..6c17a1fb 100644
--- a/docs/getting_started/rt-svc-writers-guide.rst
+++ b/docs/getting_started/rt-svc-writers-guide.rst
@@ -300,7 +300,7 @@ provide this information....
 
 .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Firmware Design: ../designb_documents/firmware-design.rst
+.. _Firmware Design: ../design/firmware-design.rst
 .. _services: ../../services
 .. _lib/psci: ../../lib/psci
 .. _runtime_svc.h: ../../include/common/runtime_svc.h
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst
index 60654644..1a4df03d 100644
--- a/docs/getting_started/user-guide.rst
+++ b/docs/getting_started/user-guide.rst
@@ -315,6 +315,34 @@ Common build options
    file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
    this file name will be used to save the key.
 
+-  ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication
+   and ARMv8.5 Branch Target Identification support for TF-A BL images themselves.
+   If enabled, it is needed to use a compiler that supports the option
+   ``-mbranch-protection``. Selects the branch protection features to use:
+-  0: Default value turns off all types of branch protection
+-  1: Enables all types of branch protection features
+-  2: Return address signing to its standard level
+-  3: Extend the signing to include leaf functions
+
+   The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options
+   and resulting PAuth/BTI features.
+
+   +-------+--------------+-------+-----+
+   | Value |  GCC option  | PAuth | BTI |
+   +=======+==============+=======+=====+
+   |   0   |     none     |   N   |  N  |
+   +-------+--------------+-------+-----+
+   |   1   |   standard   |   Y   |  Y  |
+   +-------+--------------+-------+-----+
+   |   2   |   pac-ret    |   Y   |  N  |
+   +-------+--------------+-------+-----+
+   |   3   | pac-ret+leaf |   Y   |  N  |
+   +-------+--------------+-------+-----+
+
+   This option defaults to 0 and this is an experimental feature.
+   Note that Pointer Authentication is enabled for Non-secure world
+   irrespective of the value of this option if the CPU supports it.
+
 -  ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
    compilation of each build. It must be set to a C string (including quotes
    where applicable). Defaults to a string that contains the time and date of
@@ -354,17 +382,12 @@ Common build options
    registers to be included when saving and restoring the CPU context. Default
    is 0.
 
--  ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, allows
-   Pointer Authentication for **Secure world**. This will cause the
-   Armv8.3-PAuth registers to be included when saving and restoring the CPU
-   context as part of a world switch. Default value is 0. Pointer Authentication
-   is an experimental feature.
-
-   Note that, if the CPU supports it, Pointer Authentication is allowed for
-   Non-secure world irrespectively of the value of this flag. "Allowed" means
-   that accesses to PAuth-related registers or execution of PAuth-related
-   instructions will not be trapped to EL3. As such, usage or not of PAuth in
-   Non-secure world images, depends on those images themselves.
+-  ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables
+   Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth
+   registers to be included when saving and restoring the CPU context as
+   part of world switch. Default value is 0 and this is an experimental feature.
+   Note that Pointer Authentication is enabled for Non-secure world irrespective
+   of the value of this flag if the CPU supports it.
 
 -  ``DEBUG``: Chooses between a debug and release build. It can take either 0
    (release) or 1 (debug) as values. 0 is the default.
@@ -417,13 +440,6 @@ Common build options
    partitioning in EL3, however. Platform initialisation code should configure
    and use partitions in EL3 as required. This option defaults to ``0``.
 
--  ``ENABLE_PAUTH``: Boolean option to enable Armv8.3 Pointer Authentication
-   for **TF-A BL images themselves**. If enabled, the compiler must support the
-   ``-msign-return-address`` option. This flag defaults to 0. Pointer
-   Authentication is an experimental feature.
-
-   If this flag is enabled, ``CTX_INCLUDE_PAUTH_REGS`` must also be enabled.
-
 -  ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
    support within generic code in TF-A. This option is currently only supported
    in BL31. Default is 0.
@@ -2144,17 +2160,17 @@ wakeup interrupt from RTC.
 .. _Linux master tree: https://github.com/torvalds/linux/tree/master/
 .. _Dia: https://wiki.gnome.org/Apps/Dia/Download
 .. _here: psci-lib-integration-guide.rst
-.. _Trusted Board Boot: trusted-board-boot.rst
-.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
-.. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
-.. _Firmware Update: firmware-update.rst
-.. _Firmware Design: firmware-design.rst
+.. _Trusted Board Boot: ../design/trusted-board-boot.rst
+.. _TB_FW_CONFIG for FVP: ../../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
+.. _Secure-EL1 Payloads and Dispatchers: ../design/firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
+.. _Firmware Update: ../components/firmware-update.rst
+.. _Firmware Design: ../design/firmware-design.rst
 .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
 .. _mbed TLS Security Center: https://tls.mbed.org/security
 .. _Arm's website: `FVP models`_
 .. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
 .. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
-.. _Secure Partition Manager Design guide: secure-partition-manager-design.rst
-.. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst
-.. _`Library at ROM`: romlib-design.rst
+.. _Secure Partition Manager Design guide: ../components/secure-partition-manager-design.rst
+.. _`Trusted Firmware-A Coding Guidelines`: ../process/coding-guidelines.rst
+.. _Library at ROM: ../components/romlib-design.rst
diff --git a/docs/index.rst b/docs/index.rst
index 6f6cfdff..7ac0584c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -260,20 +260,13 @@ See the `Contributing Guidelines`_ for information on how to contribute to this
 project and the `Acknowledgments`_ file for a list of contributors to the
 project.
 
-IRC channel
-~~~~~~~~~~~
+Contact us
+~~~~~~~~~~
 
-Development discussion takes place on the #trusted-firmware-a channel
-on the Freenode IRC network. This is not an official support channel.
-If you have an issue to raise, please use the `issue tracker`_.
-
-Feedback and support
-~~~~~~~~~~~~~~~~~~~~
-
-Arm welcomes any feedback on TF-A. If you think you have found a security
+We welcome any feedback on TF-A. If you think you have found a security
 vulnerability, please report this using the process defined in the TF-A
-`Security Center`_. For all other feedback, please use the
-`issue tracker`_.
+`Security Center`_. For all other feedback, you can use either the
+`issue tracker`_ or our `mailing list`_.
 
 Arm licensees may contact Arm directly via their partner managers.
 
@@ -300,21 +293,12 @@ Arm licensees may contact Arm directly via their partner managers.
 .. _Trusty Secure OS: https://source.android.com/security/trusty
 .. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
 .. _issue tracker: https://issues.trustedfirmware.org
-.. _Security Center: ./docs/security-center.rst
+.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a
+.. _Security Center: ./process/security.rst
 .. _license: ./license.rst
-.. _Contributing Guidelines: ./contributing.rst
+.. _Contributing Guidelines: ./process/contributing.rst
 .. _Acknowledgments: ./acknowledgements.rst
-.. _Firmware Design: ./docs/firmware-design.rst
-.. _Change Log: ./docs/change-log.rst
-.. _User Guide: ./docs/user-guide.rst
-.. _Porting Guide: ./docs/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
-.. _Security Advisory TFV-2: ./docs/security_advisories/security-advisory-tfv-2.rst
-.. _Security Advisory TFV-3: ./docs/security_advisories/security-advisory-tfv-3.rst
-.. _Security Advisory TFV-4: ./docs/security_advisories/security-advisory-tfv-4.rst
-.. _Security Advisory TFV-5: ./docs/security_advisories/security-advisory-tfv-5.rst
-.. _Security Advisory TFV-6: ./docs/security_advisories/security-advisory-tfv-6.rst
-.. _Security Advisory TFV-7: ./docs/security_advisories/security-advisory-tfv-7.rst
-.. _Security Advisory TFV-8: ./docs/security_advisories/security-advisory-tfv-8.rst
+.. _Firmware Design: ./design/firmware-design.rst
+.. _Change Log: ./change-log.rst
+.. _User Guide: ./getting_started/user-guide.rst
+.. _Porting Guide: ./getting_started/porting-guide.rst
diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst
index 8f8143f8..66b282c9 100644
--- a/docs/process/contributing.rst
+++ b/docs/process/contributing.rst
@@ -13,9 +13,9 @@ Getting Started
       raise a separate `issue`_ for this and ensure that the changes that
       include Third Party IP are made on a separate topic branch.
 
--  Clone `arm-trusted-firmware-a`_ on your own machine as suggested on the
+-  Clone `Trusted Firmware-A`_ on your own machine as suggested on the
    `User Guide`_.
--  Create a local topic branch based on the `arm-trusted-firmware-a`_ ``master``
+-  Create a local topic branch based on the `Trusted Firmware-A`_ ``master``
    branch.
 
 Making Changes
@@ -130,17 +130,17 @@ Binary Components
 
 .. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
 .. _issue: https://developer.trustedfirmware.org/project/board/1/
-.. _arm-trusted-firmware-a: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
 .. _Git guidelines: http://git-scm.com/book/ch5-2.html
-.. _Coding Guidelines: ./docs/coding-guidelines.rst
-.. _User Guide: ./docs/user-guide.rst
-.. _Porting Guide: ./docs/porting-guide.rst
-.. _Firmware Design: ./docs/firmware-design.rst
-.. _license.rst: ./license.rst
-.. _Acknowledgements: ./acknowledgements.rst
-.. _Maintainers: ./maintainers.rst
-.. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp
-.. _Developer Certificate of Origin (DCO): ./dco.txt
+.. _Coding Guidelines: ./coding-guidelines.rst
+.. _User Guide: ../getting_started/user-guide.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
+.. _Firmware Design: ../design/firmware-design.rst
+.. _license.rst: ../license.rst
+.. _Acknowledgements: ../acknowledgements.rst
+.. _Maintainers: ../maintainers.rst
+.. _Running the software on FVP: ../getting_started/user-guide.rst#user-content-running-the-software-on-fvp
+.. _Developer Certificate of Origin (DCO): ../../dco.txt
 .. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
 .. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
 .. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
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/requirements.txt b/docs/requirements.txt
new file mode 100644
index 00000000..8f95774b
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=2.0.0
+sphinx-rtd-theme>=0.4.3
+\ No newline at end of file
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`_)
 ----------------------------