Fix various small issues in the documentation

Change some hard-to-convert constructs to cleaner ones.
Fix a broken link.

Change-Id: Ida70aa1da0af7a107b0e05eb20b8d46669a0380b
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>

10 files changed, 276 insertions, 214 deletions

diff --git a/contributing.md b/contributing.md
index 65d2ca87..d1be2810 100644
--- a/contributing.md
+++ b/contributing.md
@@ -64,8 +64,7 @@ Making Changes
         changes (and nothing else) in the last commit of the series. Otherwise,
         include the documentation changes within the single commit.
 *   Please test your changes. As a minimum, ensure UEFI boots to the shell on
-    the Foundation FVP. See the "[Running the software]" section of the
-    [User Guide] for more information.
+    the Foundation FVP. See [Running the software on FVP] for more information.
 
 
 Submitting Changes
@@ -105,7 +104,7 @@ _Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved._
 
 
 [User Guide]:                           ./docs/user-guide.md
-[Running the software]:                 ./docs/user-guide.md#6--running-the-software
+[Running the software on FVP]:          ./docs/user-guide.md#8--running-the-software-on-fvp
 [Porting Guide]:                        ./docs/porting-guide.md
 [Firmware Design]:                      ./docs/firmware-design.md
 [Acknowledgements]:                     ./acknowledgements.md "Contributor acknowledgements"
diff --git a/docs/arm-sip-service.md b/docs/arm-sip-service.md
index 7ebb724e..1d15b85e 100644
--- a/docs/arm-sip-service.md
+++ b/docs/arm-sip-service.md
@@ -87,5 +87,7 @@ respectively.
 
 - - - - - - - - - - - - - - - - - - - - - - - - - -
 
+_Copyright (c) 2017, ARM Limited and Contributors. All rights reserved._
+
 [Firmware Design]: ./firmware-design.md
 [SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 9ae97170..0d4578a5 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -31,17 +31,16 @@ to the stage where it hands-off control to firmware running in the normal
 world in DRAM. This is the cold boot path.
 
 The ARM Trusted Firmware also implements the Power State Coordination Interface
-([PSCI]) PDD [2] as a runtime service. PSCI is the interface from normal world
-software to firmware implementing power management use-cases (for example,
-secondary CPU boot, hotplug and idle). Normal world software can access ARM
-Trusted Firmware runtime services via the ARM SMC (Secure Monitor Call)
-instruction. The SMC instruction must be used as mandated by the [SMC Calling
-Convention PDD][SMCCC] [3].
+PDD [2] as a runtime service. PSCI is the interface from normal world software
+to firmware implementing power management use-cases (for example, secondary CPU
+boot, hotplug and idle). Normal world software can access ARM Trusted Firmware
+runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC
+instruction must be used as mandated by the SMC Calling Convention [3].
 
 The ARM Trusted Firmware implements a framework for configuring and managing
 interrupts generated in either security state. The details of the interrupt
-management framework and its design can be found in [ARM Trusted
-Firmware Interrupt Management Design guide][INTRG] [4].
+management framework and its design can be found in ARM Trusted Firmware
+Interrupt Management Design guide [4].
 
 The ARM Trusted Firmware can be built to support either AArch64 or AArch32
 execution state.
@@ -390,8 +389,8 @@ BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state
 initialization is complete. Hence, BL2 populates a platform-specific area of
 memory with the entrypoint and Saved Program Status Register (`SPSR`) of the
 normal world software image. The entrypoint is the load address of the BL33
-image. The `SPSR` is determined as specified in Section 5.13 of the [PSCI PDD]
-[PSCI]. This information is passed to the EL3 Runtime Software.
+image. The `SPSR` is determined as specified in Section 5.13 of the 
+[PSCI PDD][PSCI]. This information is passed to the EL3 Runtime Software.
 
 #### AArch64 BL31 (EL3 Runtime Software) execution
 
@@ -2303,9 +2302,9 @@ kernel at boot time. These can be found in the `fdts` directory.
 1.  Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
     under NDA through your ARM account representative.
 
-2.  [Power State Coordination Interface PDD (ARM DEN 0022B.b)][PSCI].
+2.  [Power State Coordination Interface PDD][PSCI]
 
-3.  [SMC Calling Convention PDD (ARM DEN 0028A)][SMCCC].
+3.  [SMC Calling Convention PDD][SMCCC]
 
 4.  [ARM Trusted Firmware Interrupt Management Design guide][INTRG].
 
@@ -2314,8 +2313,8 @@ kernel at boot time. These can be found in the `fdts` directory.
 _Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
 
 [ARM ARM]:          http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html "ARMv8-A Reference Manual (ARM DDI0487A.E)"
-[PSCI]:             http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
-[SMCCC]:            http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
+[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 (ARM DEN 0022D)"
+[SMCCC]:            http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf "SMC Calling Convention PDD (ARM DEN 0028B)"
 [UUID]:             https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
 [User Guide]:       ./user-guide.md
 [Porting Guide]:    ./porting-guide.md
diff --git a/docs/plat/hikey.md b/docs/plat/hikey.md
index a5e592bb..5e62a5bc 100644
--- a/docs/plat/hikey.md
+++ b/docs/plat/hikey.md
@@ -1,9 +1,9 @@
 
 Description
 ====================
-  HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey.
+HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey.
 
-  More information are listed in [link](https://github.com/96boards/documentation/blob/master/ConsumerEdition/HiKey/Quickstart/README.md).
+More information are listed in [link](https://github.com/96boards/documentation/blob/master/ConsumerEdition/HiKey/Quickstart/README.md).
 
 
 How to build
@@ -12,112 +12,136 @@ How to build
 1. Code Locations
 -----------------
 
-   * ARM Trusted Firmware:
-   [link](https://github.com/ARM-software/arm-trusted-firmware)
+  * ARM Trusted Firmware:
+    [link](https://github.com/ARM-software/arm-trusted-firmware)
 
-   * edk2:
-   [link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5)
+  * edk2:
+    [link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5)
 
-   * OpenPlatformPkg:
-   [link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4)
+  * OpenPlatformPkg:
+    [link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4)
 
-   * l-loader:
-   [link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2)
+  * l-loader:
+    [link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2)
 
-   * uefi-tools:
-   [link](https://github.com/96boards-hikey/uefi-tools/tree/testing/hikey960_v1)
+  * uefi-tools:
+    [link](https://github.com/96boards-hikey/uefi-tools/tree/testing/hikey960_v1)
 
-   * atf-fastboot:
-   [link](https://github.com/96boards-hikey/atf-fastboot/tree/master)
+  * atf-fastboot:
+    [link](https://github.com/96boards-hikey/atf-fastboot/tree/master)
 
 
 2. Build Procedure
 ------------------
 
-   * Fetch all the above repositories into local host.
-     Make all the repositories in the same ${BUILD_PATH}.
-
-   * Create the symbol link to OpenPlatformPkg in edk2.
-     <br>`$cd ${BUILD_PATH}/edk2`</br>
-     <br>`$ln -sf ../OpenPlatformPkg`</br>
-
-   * Prepare AARCH64 && AARCH32 toolchain. Prepare python.
-
-   * If your hikey hardware is built by CircuitCo, update _uefi-tools/platform.config_ first. _(optional)_
-     <br>__Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
-     console on hikey.__</br>
-     <br>`BUILDFLAGS=-DSERIAL_BASE=0xF8015000`</br>
-     <br>If your hikey hardware is built by LeMarker, nothing to do.</br>
-
-   * Build it as debug mode. Create your own build script file or you could refer to __build_uefi.sh__ in l-loader git repository.
-     <br>`BUILD_OPTION=DEBUG`</br>
-     <br>`export AARCH64_TOOLCHAIN=GCC5`</br>
-     <br>`export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools`<br>
-     <br>`export EDK2_DIR=${BUILD_PATH}/edk2`</br>
-     <br>`EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}`</br>
-     <br>`# Build fastboot for ARM Trust Firmware. It's used for recovery mode.`</br>
-     <br>`cd ${BUILD_PATH}/atf-fastboot`</br>
-     <br>`CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1`</br>
-     <br>`# Convert DEBUG/RELEASE to debug/release`</br>
-     <br>`FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]')`</br>
-     <br>`cd ${EDK2_DIR}`</br>
-     <br>`# Build UEFI & ARM Trust Firmware`</br>
-     <br>`${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey`</br>
-     <br>`# Generate l-loader.bin`</br>
-     <br>`cd ${BUILD_PATH}/l-loader`</br>
-     <br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin`</br>
-     <br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin`</br>
-     <br>`ln -sf ${BUILD_PATH}/atf-fastboot/build/hikey/${FASTBOOT_BUILD_OPTION}/bl1.bin fastboot.bin`</br>
-     <br>`python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd`</br>
-     <br>`arm-linux-gnueabihf-gcc -c -o start.o start.S`</br>
-     <br>`arm-linux-gnueabihf-ld -Bstatic -Tl-loader.lds -Ttext 0xf9800800 start.o -o loader`</br>
-     <br>`arm-linux-gnueabihf-objcopy -O binary loader temp`</br>
-     <br>`python gen_loader_hikey.py -o l-loader.bin --img_loader=temp --img_bl1=bl1.bin --img_ns_bl1u=fastboot.bin`</br>
-
-   * Generate partition table for aosp. The eMMC capacity is either 4GB or 8GB. Just change "aosp-4g" to "linux-4g" for debian.
-     <br>`$PTABLE=aosp-4g SECTOR_SIZE=512 bash -x generate_ptable.sh`</br>
+  * Fetch all the above repositories into local host.
+    Make all the repositories in the same ${BUILD_PATH}.
+
+  * Create the symbol link to OpenPlatformPkg in edk2.
+    ```shell
+    $cd ${BUILD_PATH}/edk2
+    $ln -sf ../OpenPlatformPkg
+    ```
+
+  * Prepare AARCH64 && AARCH32 toolchain. Prepare python.
+
+  * If your hikey hardware is built by CircuitCo, update _uefi-tools/platform.config_ first. _(optional)_
+    __Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
+    console on hikey.__
+    ```shell
+    BUILDFLAGS=-DSERIAL_BASE=0xF8015000
+    ```
+    If your hikey hardware is built by LeMarker, nothing to do.
+
+  * Build it as debug mode. Create your own build script file or you could refer to __build_uefi.sh__ in l-loader git repository.
+    ```shell
+    BUILD_OPTION=DEBUG
+    export AARCH64_TOOLCHAIN=GCC5
+    export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools
+    export EDK2_DIR=${BUILD_PATH}/edk2
+    EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
+    # Build fastboot for ARM Trust Firmware. It's used for recovery mode.
+    cd ${BUILD_PATH}/atf-fastboot
+    CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1
+    # Convert DEBUG/RELEASE to debug/release
+    FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]')
+    cd ${EDK2_DIR}
+    # Build UEFI & ARM Trust Firmware
+    ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey
+    # Generate l-loader.bin
+    cd ${BUILD_PATH}/l-loader
+    ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin
+    ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin
+    ln -sf ${BUILD_PATH}/atf-fastboot/build/hikey/${FASTBOOT_BUILD_OPTION}/bl1.bin fastboot.bin
+    python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd
+    arm-linux-gnueabihf-gcc -c -o start.o start.S
+    arm-linux-gnueabihf-ld -Bstatic -Tl-loader.lds -Ttext 0xf9800800 start.o -o loader
+    arm-linux-gnueabihf-objcopy -O binary loader temp
+    python gen_loader_hikey.py -o l-loader.bin --img_loader=temp --img_bl1=bl1.bin --img_ns_bl1u=fastboot.bin
+    ```
+
+  * Generate partition table for aosp. The eMMC capacity is either 4GB or 8GB. Just change "aosp-4g" to "linux-4g" for debian.
+    ```shell
+    $PTABLE=aosp-4g SECTOR_SIZE=512 bash -x generate_ptable.sh
+    ```
 
 
 3. Setup Console
 ----------------
 
-   * Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. __If you don't need Boot Manager GUI, just ignore this section.__
-     <br>`$sudo apt-get install ser2net`</br>
+  * Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. __If you don't need Boot Manager GUI, just ignore this section.__
+    ```shell
+    $sudo apt-get install ser2net
+    ```
 
-   * Configure ser2net.
-     <br>`$sudo vi /etc/ser2net.conf`</br>
-     <br>Append one line for serial-over-USB in below.</br>
-     <br>_#ser2net.conf_</br>
-     <br>`2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner`</br>
+  * Configure ser2net.
+    ```shell
+    $sudo vi /etc/ser2net.conf
+    ```
 
-   * Open the console.
-     <br>`$telnet localhost 2004`</br>
-     <br>And you could open the console remotely, too.</br>
+    Append one line for serial-over-USB in below.
+    _#ser2net.conf_
+    ```shell
+    2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner
+    ```
+
+  * Open the console.
+    ```shell
+    $telnet localhost 2004
+    ```
+
+    And you could open the console remotely, too.
 
 
 4. Flush images in recovery mode
 -----------------------------
 
-   * Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey.
+  * Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey.
 
-   * Remove the modemmanager package. This package may cause the idt tool failure.
-     <br>`$sudo apt-get purge modemmanager`</br>
+  * Remove the modemmanager package. This package may cause the idt tool failure.
+    ```shell
+    $sudo apt-get purge modemmanager
+    ```
 
-   * Run the command to download l-loader.bin into HiKey.
-     <br>`$sudo python hisi-idt.py -d /dev/ttyUSB1 --img1 l-loader.bin`</br>
+  * Run the command to download l-loader.bin into HiKey.
+    ```shell
+    $sudo python hisi-idt.py -d /dev/ttyUSB1 --img1 l-loader.bin
+    ```
 
-   * Update images. All aosp or debian images could be fetched from [link](https://builds.96boards.org/).
-     <br>`$sudo fastboot flash ptable prm_ptable.img`</br>
-     <br>`$sudo fastboot flash fastboot fip.bin`</br>
-     <br>`$sudo fastboot flash boot boot.img`</br>
-     <br>`$sudo fastboot flash cache cache.img`</br>
-     <br>`$sudo fastboot flash system system.img`</br>
-     <br>`$sudo fastboot flash userdata userdata.img`</br>
+  * Update images. All aosp or debian images could be fetched from [link](https://builds.96boards.org/).
+    ```shell
+    $sudo fastboot flash ptable prm_ptable.img
+    $sudo fastboot flash fastboot fip.bin
+    $sudo fastboot flash boot boot.img
+    $sudo fastboot flash cache cache.img
+    $sudo fastboot flash system system.img
+    $sudo  fastboot flash userdata userdata.img
+    ```
 
 
 5. Boot UEFI in normal mode
 -----------------------------
 
-   * Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey.
+  * Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey.
 
-   * Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md)
+  * Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md)
diff --git a/docs/plat/hikey960.md b/docs/plat/hikey960.md
index 786a54b9..8442a189 100644
--- a/docs/plat/hikey960.md
+++ b/docs/plat/hikey960.md
@@ -1,9 +1,9 @@
 
 Description
 ====================
-  HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960.
+HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960.
 
-  More information are listed in [link](http://www.96boards.org/documentation/ConsumerEdition/HiKey960/README.md).
+More information are listed in [link](http://www.96boards.org/documentation/ConsumerEdition/HiKey960/README.md).
 
 
 How to build
@@ -12,123 +12,148 @@ How to build
 1. Code Locations
 -----------------
 
-   * ARM Trusted Firmware:
-   [link](https://github.com/ARM-software/arm-trusted-firmware)
+  * ARM Trusted Firmware:
+    [link](https://github.com/ARM-software/arm-trusted-firmware)
 
-   * edk2:
-   [link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5)
+  * edk2:
+    [link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5)
 
-   * OpenPlatformPkg:
-   [link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4)
+  * OpenPlatformPkg:
+    [link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4)
 
-   * l-loader:
-   [link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2)
+  * l-loader:
+    [link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2)
 
-   * uefi-tools:
-   [link](https://github.com/96boards-hikey/uefi-tools/tree/hikey960_v1)
+  * uefi-tools:
+    [link](https://github.com/96boards-hikey/uefi-tools/tree/hikey960_v1)
 
 
 2. Build Procedure
 ------------------
 
-   * Fetch all the above 5 repositories into local host.
-     Make all the repositories in the same ${BUILD_PATH}.
-
-   * Create the symbol link to OpenPlatformPkg in edk2.
-     <br>`$cd ${BUILD_PATH}/edk2`</br>
-     <br>`$ln -sf ../OpenPlatformPkg`</br>
-
-   * Prepare AARCH64 toolchain.
-
-   * If your hikey960 hardware is v1, update _uefi-tools/platform.config_ first. _(optional)_
-     <br>__Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
-     console on hikey960 v1.__</br>
-     <br>`BUILDFLAGS=-DSERIAL_BASE=0xFDF05000`</br>
-     <br>If your hikey960 hardware is v2 or newer, nothing to do.</br>
-
-   * Build it as debug mode. Create script file for build.
-     <br>`BUILD_OPTION=DEBUG`</br>
-     <br>`export AARCH64_TOOLCHAIN=GCC48`</br>
-     <br>`export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools`<br>
-     <br>`export EDK2_DIR=${BUILD_PATH}/edk2`</br>
-     <br>`EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}`</br>
-     <br>`cd ${EDK2_DIR}`</br>
-     <br>`# Build UEFI & ARM Trust Firmware`</br>
-     <br>`${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey960`</br>
-     <br>`# Generate l-loader.bin`</br>
-     <br>`cd ${BUILD_PATH}/l-loader`</br>
-     <br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin`</br>
-     <br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin`</br>
-     <br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/BL33_AP_UEFI.fd`</br>
-     <br>`python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd`</br>
-
-   * Generate partition table.
-     <br>_Make sure that you're using the sgdisk in the l-loader directory._</br>
-     <br>`$PTABLE=aosp-32g SECTOR_SIZE=4096 SGDISK=./sgdisk bash -x generate_ptable.sh`</br>
+  * Fetch all the above 5 repositories into local host.
+    Make all the repositories in the same ${BUILD_PATH}.
+
+  * Create the symbol link to OpenPlatformPkg in edk2.
+    ```shell
+    $cd ${BUILD_PATH}/edk2
+    $ln -sf ../OpenPlatformPkg
+    ```
+
+  * Prepare AARCH64 toolchain.
+
+  * If your hikey960 hardware is v1, update _uefi-tools/platform.config_ first. _(optional)_
+    __Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
+    console on hikey960 v1.__
+    ```shell
+    BUILDFLAGS=-DSERIAL_BASE=0xFDF05000
+    ```
+    If your hikey960 hardware is v2 or newer, nothing to do.
+
+  * Build it as debug mode. Create script file for build.
+    ```shell
+    BUILD_OPTION=DEBUG
+    export AARCH64_TOOLCHAIN=GCC48
+    export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools
+    export EDK2_DIR=${BUILD_PATH}/edk2
+    EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
+    cd ${EDK2_DIR}
+    # Build UEFI & ARM Trust Firmware
+    ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey960
+    # Generate l-loader.bin
+    cd ${BUILD_PATH}/l-loader
+    ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin
+    ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin
+    ln -sf ${EDK2_OUTPUT_DIR}/FV/BL33_AP_UEFI.fd
+    python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd
+    ```
+
+  * Generate partition table.
+    _Make sure that you're using the sgdisk in the l-loader directory._
+    ```shell
+    $PTABLE=aosp-32g SECTOR_SIZE=4096 SGDISK=./sgdisk bash -x generate_ptable.sh
+    ```
 
 
 3. Setup Console
 ----------------
 
-   * Install ser2net. Use telnet as the console since UEFI will output window
-     that fails to display in minicom.
-     <br>`$sudo apt-get install ser2net`</br>
+  * Install ser2net. Use telnet as the console since UEFI will output window
+    that fails to display in minicom.
+    ```shell
+    $sudo apt-get install ser2net
+    ```
 
-   * Configure ser2net.
-     <br>`$sudo vi /etc/ser2net.conf`</br>
-     <br>Append one line for serial-over-USB in below.</br>
-     <br>_#ser2net.conf_</br>
-     <br>`2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner`</br>
+  * Configure ser2net.
+    ```shell
+    $sudo vi /etc/ser2net.conf
+    ```
+    Append one line for serial-over-USB in _#ser2net.conf_
+    ```
+    2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner
+    ```
 
-   * Open the console.
-     <br>`$telnet localhost 2004`</br>
-     <br>And you could open the console remotely, too.</br>
+  * Open the console.
+    ```shell
+    $telnet localhost 2004
+    ```
+    And you could open the console remotely, too.
 
 
 4. Boot UEFI in recovery mode
 -----------------------------
 
-   * Fetch that are used in recovery mode. The code location is in below.
-     [link](https://github.com/96boards-hikey/tools-images-hikey960)
-
-   * Generate l-loader.bin.
-     <br>`$cd tools-images-hikey960`</br>
-     <br>`$ln -sf ${BUILD_PATH}/l-loader/l-loader.bin`</br>
-
-   * Prepare config file.
-     <br>_$vi config_</br>
-     <br>_# The content of config file_</br>
-     <br>`./sec_user_xloader.img 0x00020000`</br>
-     <br>`./sec_uce_boot.img 0x6A908000`</br>
-     <br>`./l-loader.bin 0x1AC00000`</br>
-
-   * Remove the modemmanager package. This package may causes hikey_idt tool failure.
-     <br>`$sudo apt-get purge modemmanager`</br>
-
-   * Run the command to download l-loader.bin into HiKey960.
-     <br>`$sudo ./hikey_idt -c config -p /dev/ttyUSB1`</br>
-
-   * UEFI running in recovery mode.
-     <br>When prompt '.' is displayed on console, press hotkey 'f' in keyboard. Then Android fastboot app is running.</br>
-     <br>The timeout of prompt '.' is 10 seconds.</br>
-
-   * Update images.
-     <br>`$sudo fastboot flash ptable prm_ptable.img`</br>
-     <br>`$sudo fastboot flash xloader sec_xloader.img`</br>
-     <br>`$sudo fastboot flash fastboot l-loader.bin`</br>
-     <br>`$sudo fastboot flash fip fip.bin`</br>
-     <br>`$sudo fastboot flash boot boot.img`</br>
-     <br>`$sudo fastboot flash cache cache.img`</br>
-     <br>`$sudo fastboot flash system system.img`</br>
-     <br>`$sudo fastboot flash userdata userdata.img`</br>
-
-   * Notice: UEFI could also boot kernel in recovery mode, but BL31 isn't loaded in
-     recovery mode.
+  * Fetch that are used in recovery mode. The code location is in below.
+    [link](https://github.com/96boards-hikey/tools-images-hikey960)
+
+  * Generate l-loader.bin.
+    ```shell
+    $cd tools-images-hikey960
+    $ln -sf ${BUILD_PATH}/l-loader/l-loader.bin
+    ```
+
+  * Prepare config file.
+    ```shell
+    $vi config
+    # The content of config file
+    ./sec_user_xloader.img 0x00020000
+    ./sec_uce_boot.img 0x6A908000
+    ./l-loader.bin 0x1AC00000
+    ```
+
+  * Remove the modemmanager package. This package may causes hikey_idt tool failure.
+    ```shell
+    $sudo apt-get purge modemmanager
+    ```
+
+  * Run the command to download l-loader.bin into HiKey960.
+    ```shell
+    $sudo ./hikey_idt -c config -p /dev/ttyUSB1
+    ```
+
+  * UEFI running in recovery mode.
+    When prompt '.' is displayed on console, press hotkey 'f' in keyboard. Then Android fastboot app is running.
+    The timeout of prompt '.' is 10 seconds.
+
+  * Update images.
+    ```shell
+    $sudo fastboot flash ptable prm_ptable.img
+    $sudo fastboot flash xloader sec_xloader.img
+    $sudo fastboot flash fastboot l-loader.bin
+    $sudo fastboot flash fip fip.bin
+    $sudo fastboot flash boot boot.img
+    $sudo fastboot flash cache cache.img
+    $sudo fastboot flash system system.img
+    $sudo fastboot flash userdata userdata.img
+    ```
+
+  * Notice: UEFI could also boot kernel in recovery mode, but BL31 isn't loaded in
+  recovery mode.
 
 
 5. Boot UEFI in normal mode
 -----------------------------
 
-   * Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960.
+  * Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960.
 
-   * Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md)
+  * Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md)
diff --git a/docs/plat/nvidia-tegra.md b/docs/plat/nvidia-tegra.md
index b45fec6e..3cb16827 100644
--- a/docs/plat/nvidia-tegra.md
+++ b/docs/plat/nvidia-tegra.md
@@ -56,10 +56,12 @@ without changing any makefiles.
 
 Preparing the BL31 image to run on Tegra SoCs
 ===================================================
-'CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
-TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31'
+```shell
+CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
+TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31
+```
 
-Platforms wanting to use different TZDRAM_BASE, can add 'TZDRAM_BASE=<value>'
+Platforms wanting to use different TZDRAM_BASE, can add `TZDRAM_BASE=<value>`
 to the build command line.
 
 The Tegra platform code expects a pointer to the following platform specific
diff --git a/docs/psci-lib-integration-guide.md b/docs/psci-lib-integration-guide.md
index d81b3286..ab0276b0 100644
--- a/docs/psci-lib-integration-guide.md
+++ b/docs/psci-lib-integration-guide.md
@@ -2,7 +2,6 @@ PSCI Library Integration guide for ARMv8-A AArch32 systems
 ==========================================================
 
 Contents
---------
 
 1. [Introduction](#1-introduction)
 2. [Generic call sequence for PSCI Library interface (AArch32)](#2-generic-call-sequence-for-psci-library-interface-aarch32)
@@ -31,8 +30,8 @@ with EL3 Runtime Software in this document is targeted towards AArch32 systems.
 2. Generic call sequence for PSCI Library interface (AArch32)
 -------------------------------------------------------------
 
-The generic call sequence of PSCI Library interfaces
-[(see section 4)](#4-psci-library-interface) during cold boot in AArch32
+The generic call sequence of PSCI Library interfaces (see
+[section 4](#4-psci-library-interface)) during cold boot in AArch32
 system is described below:
 
 1.  After cold reset, the EL3 Runtime Software performs its cold boot
diff --git a/docs/psci-pd-tree.md b/docs/psci-pd-tree.md
index c253905c..a847f06b 100644
--- a/docs/psci-pd-tree.md
+++ b/docs/psci-pd-tree.md
@@ -1,3 +1,12 @@
+PSCI Library Integration guide for ARMv8-A AArch32 systems
+==========================================================
+
+Contents
+--------
+
+1. [Requirements](#requirements)
+2. [Design](#design)
+
 ------------
 Requirements
 ------------
@@ -293,3 +302,7 @@ Each core can find its node in the `psci_cpu_pd_nodes` array using the
 provides an MPIDR. The `plat_core_pos_by_mpidr()` function is used to validate
 the MPIDR before using it to find the corresponding core node. The non-core power
 domain nodes do not need to be identified.
+
+- - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2017, ARM Limited and Contributors. All rights reserved._
diff --git a/docs/spd/optee-dispatcher.md b/docs/spd/optee-dispatcher.md
index c154f6b3..1971d9a6 100644
--- a/docs/spd/optee-dispatcher.md
+++ b/docs/spd/optee-dispatcher.md
@@ -3,11 +3,11 @@ OP-TEE Dispatcher
 
 [OP-TEE OS] is a Trusted OS running as Secure EL1.
 
-To build and execute [OP-TEE OS] follow the instructions at
-[ARM Trusted Firmware with OP-TEE] [OP-TEE OS]
+To build and execute OP-TEE follow the instructions at
+[OP-TEE build.git][OP-TEE OS]
 
 - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
+_Copyright (c) 2014-2017, ARM Limited and Contributors. All rights reserved._
 
-[OP-TEE OS]:  http://github.com/OP-TEE/optee_os/tree/master/documentation/arm_trusted_firmware.md
+[OP-TEE OS]:  https://github.com/OP-TEE/build
diff --git a/docs/user-guide.md b/docs/user-guide.md
index ea2874d8..678bb424 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -140,10 +140,10 @@ Download the Trusted Firmware source code from Github:
         make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
 
 
-   Notes:
+    Notes:
 
     *   If `PLAT` is not specified, `fvp` is assumed by default. See the
-        "Summary of build options" for more information on available build
+        [Summary of build options](#summary-of-build-options) for more information on available build
         options.
 
     *   (AArch32 only) Currently only `PLAT=fvp` is supported.
@@ -157,15 +157,15 @@ Download the Trusted Firmware source code from Github:
         EL3 Runtime Software can be found [here][PSCI Lib Integration].
 
     *   (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
-        image, is not compiled in by default. Refer to the "Building the Test
-        Secure Payload" section below.
+        image, is not compiled in by default. Refer to the [Building the Test
+        Secure Payload](#building-the-test-secure-payload) section below.
 
     *   By default this produces a release version of the build. To produce a
         debug version instead, refer to the "Debugging options" section below.
 
     *   The build process creates products in a `build` directory tree, building
         the objects and binaries for each boot loader stage in separate
-        sub-directories.  The following boot loader binary files are created
+        sub-directories. The following boot loader binary files are created
         from the corresponding ELF files:
 
         *   `build/<platform>/<build-type>/bl1.bin`
@@ -213,7 +213,7 @@ performed.
 
 *   `ARM_ARCH_MAJOR`: The major version of ARM Architecture to target when
     compiling ARM Trusted Firmware. Its value must be numeric, and defaults to
-    8. See also, _ARMv8 Architecture Extensions_ in [Firmware Design].
+    8 . See also, _ARMv8 Architecture Extensions_ in [Firmware Design].
 
 *   `ARM_ARCH_MINOR`: The minor version of ARM Architecture to target when
     compiling ARM Trusted Firmware. Its value must be a numeric, and defaults
@@ -575,9 +575,9 @@ performed.
     optimise memory usage need to set this flag to 1 and must override the
     related macros.
 
-*   `ARM_CONFIG_CNTACR`: boolean option to unlock access to the CNTBase<N>
-    frame registers by setting the CNTCTLBase.CNTACR<N> register bits. The
-    frame number <N> is defined by `PLAT_ARM_NSTIMER_FRAME_ID`, which should
+*   `ARM_CONFIG_CNTACR`: boolean option to unlock access to the `CNTBase<N>`
+    frame registers by setting the `CNTCTLBase.CNTACR<N>` register bits. The
+    frame number `<N>` is defined by `PLAT_ARM_NSTIMER_FRAME_ID`, which should
     match the frame used by the Non-Secure image (normally the Linux kernel).
     Default is true (access to the frame is allowed).
 
@@ -730,7 +730,7 @@ commands can be used:
 The TSP is coupled with a companion runtime service in the BL31 firmware,
 called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
 must be recompiled as well. For more information on SPs and SPDs, see the
-"Secure-EL1 Payloads and Dispatchers" section in the [Firmware Design].
+[Secure-EL1 Payloads and Dispatchers](firmware-design.rst#secure-el1-payloads-and-dispatchers) section in the [Firmware Design].
 
 First clean the Trusted Firmware build directory to get rid of any previous
 BL31 binary. Then to build the TSP image use:
@@ -848,8 +848,7 @@ remove operations will automatically overwrite it.
 The unpack operation will fail if the images already exist at the
 destination.  In that case, use -f or --force to continue.
 
-More information about FIP can be found in the [Firmware Design document]
-[Firmware Design].
+More information about FIP can be found in the [Firmware Design] document.
 
 #### Migrating from fip_create to fiptool