8 files changed, 221 insertions, 6 deletions
diff --git a/docs/diagrams/romlib_design.dia b/docs/diagrams/romlib_design.dia
new file mode 100755
index 000000000..d12eec07d
--- /dev/null
+++ b/docs/diagrams/romlib_design.dia
diff --git a/docs/diagrams/romlib_design.png b/docs/diagrams/romlib_design.png
new file mode 100755
index 000000000..bfffcde7b
--- /dev/null
+++ b/docs/diagrams/romlib_design.png
diff --git a/docs/diagrams/romlib_wrapper.dia b/docs/diagrams/romlib_wrapper.dia
new file mode 100755
index 000000000..30cfbd801
--- /dev/null
+++ b/docs/diagrams/romlib_wrapper.dia
diff --git a/docs/diagrams/romlib_wrapper.png b/docs/diagrams/romlib_wrapper.png
new file mode 100755
index 000000000..ec3a44118
--- /dev/null
+++ b/docs/diagrams/romlib_wrapper.png
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst
index 617cbb886..299654fc2 100644
--- a/docs/firmware-design.rst
+++ b/docs/firmware-design.rst
@@ -1866,6 +1866,11 @@ BL image during boot.
                |   MHU    |
     0x04000000 +----------+
 
+Library at ROM
+---------------
+
+Please refer to the `ROMLIB Design`_ document.
+
 Firmware Image Package (FIP)
 ----------------------------
 
@@ -2544,10 +2549,8 @@ This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
 Armv8.2-A
 ~~~~~~~~~
 
-This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and
-``ARM_ARCH_MINOR`` >= 2.
-
--  The Common not Private (CnP) bit is enabled to indicate that multiple
+-  The presence of ARMv8.2-TTCNP is detected at runtime. When it is present, the
+   Common not Private (TTBRn_ELx.CnP) bit is enabled to indicate that multiple
    Processing Elements in the same Inner Shareable domain use the same
    translation table entries for a given stage of translation for a particular
    translation regime.
@@ -2642,7 +2645,7 @@ References
 
 --------------
 
-*Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. _Reset Design: ./reset-design.rst
 .. _Porting Guide: ./porting-guide.rst
@@ -2662,5 +2665,6 @@ References
 .. _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
 
 .. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true
diff --git a/docs/plat/fvp_ve.rst b/docs/plat/fvp_ve.rst
new file mode 100644
index 000000000..c6d67c090
--- /dev/null
+++ b/docs/plat/fvp_ve.rst
@@ -0,0 +1,81 @@
+Description
+===========
+
+Versatile Express (VE) family development platform provides an
+ultra fast environment for prototyping arm-v7 System-on-Chip designs.
+VE Fixed Virtual Platforms (FVP) are simulations of Versatile Express boards.
+The platform in arm-trusted-firmware has been verified with Arm Cortex-A5
+and Cortex-A7 VE FVP's. This platform is tested on and only expected to work
+with single core models.
+
+Boot Sequence
+=============
+
+BL1 --> BL2 --> BL32(sp_min) --> BL33(u-boot) --> Linux kernel
+
+How to build
+============
+
+Code Locations
+---------------
+-  `U-boot <https://git.linaro.org/landing-teams/working/arm/u-boot.git>`__
+
+-  `arm-trusted-firmware <https://github.com/ARM-software/arm-trusted-firmware>`__
+
+Build Procedure
+---------------
+
+-  Obtain arm toolchain. The software stack has been verified with linaro 6.2
+   `arm-linux-gnueabihf <https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/>`__.
+   Set the CROSS_COMPILE environment variable to point to the toolchain folder.
+
+-  Fetch and build u-boot.
+   Make the .config file using the command:
+
+   .. code:: shell
+
+      make ARCH=arm vexpress_aemv8a_aarch32_config
+
+   Make the u-boot binary for Cortex-A5 using the command:
+
+   .. code:: shell
+
+     make ARCH=arm SUPPORT_ARCH_TIMER=no
+
+   Make the u-boot binary for Cortex-A7 using the command:
+
+   .. code:: shell
+
+     make ARCH=arm
+
+
+-  Build TF-A:
+
+   The make command for Cortex-A5 is:
+
+   .. code:: shell
+
+       make PLAT=fvp_ve ARCH=aarch32 ARM_ARCH_MAJOR=7 ARM_CORTEX_A5=yes \
+       AARCH32_SP=sp_min FVP_HW_CONFIG_DTS=fdts/fvp-ve-Cortex-A5x1.dts \
+       ARM_XLAT_TABLES_LIB_V1=1 BL33=<path_to_u-boot.bin> all fip
+
+   The make command for Cortex-A7 is:
+
+   .. code:: shell
+
+      make PLAT=fvp_ve ARCH=aarch32 ARM_ARCH_MAJOR=7 ARM_CORTEX_A7=yes \
+      AARCH32_SP=sp_min FVP_HW_CONFIG_DTS=fdts/fvp-ve-Cortex-A7x1.dts  \
+      BL33=<path_to_u-boot.bin> all fip
+
+Run Procedure
+-------------
+
+The following model parameters should be used to boot Linux using the build of
+arm-trusted-firmware-a made using the above make commands:
+
+  .. code:: shell
+
+    ./<path_to_model> <path_to_bl1.elf> \
+          -C motherboard.flashloader1.fname=<path_to_fip.bin> \
+          --data cluster.cpu0=<path_to_zImage>@0x80080000  \
+          --data cluster.cpu0=<path_to_ramdisk>@0x84000000
diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst
index f8379b4eb..bfae9ccc8 100644
--- a/docs/plat/stm32mp1.rst
+++ b/docs/plat/stm32mp1.rst
@@ -4,6 +4,8 @@ Trusted Firmware-A for STM32MP1
 STM32MP1 is a microprocessor designed by STMicroelectronics
 based on a dual Arm Cortex-A7.
 It is an Armv7-A platform, using dedicated code from TF-A.
+The STM32MP1 chip also embeds a Cortex-M4.
+More information can be found on `STM32MP1 Series`_ page.
 
 
 Design
@@ -78,7 +80,7 @@ To build:
     make CROSS_COMPILE=arm-linux-gnueabihf- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 AARCH32_SP=sp_min
     cd <u-boot_directory>
     make stm32mp15_basic_defconfig
-    make DEVICE_TREE=stm32mp157c_ev1 all
+    make DEVICE_TREE=stm32mp157c-ev1 all
     ./tools/mkimage -T stm32image -a 0xC0100000 -e 0xC0100000 -d u-boot.bin u-boot.stm32
 
 The following build options are supported:
@@ -96,3 +98,6 @@ It should contain at least those partitions:
 - ssbl: to copy the u-boot.stm32 binary
 
 Usually, two copies of fsbl are used (fsbl1 and fsbl2) instead of one partition fsbl.
+
+
+.. _STM32MP1 Series: https://www.st.com/en/microcontrollers-microprocessors/stm32mp1-series.html
diff --git a/docs/romlib-design.rst b/docs/romlib-design.rst
new file mode 100644
index 000000000..34a7980be
--- /dev/null
+++ b/docs/romlib-design.rst
@@ -0,0 +1,125 @@
+Library at ROM
+==============
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+This document provides an overview of the "library at ROM" implementation in
+Trusted Firmware-A (TF-A).
+
+Introduction
+~~~~~~~~~~~~
+
+The "library at ROM" feature allows platforms to build a library of functions to
+be placed in ROM. This reduces SRAM usage by utilising the available space in
+ROM. The "library at ROM" contains a jump table with the list of functions that
+are placed in ROM. The capabilities of the "library at ROM" are:
+
+1. Functions can be from one or several libraries.
+
+2. Functions can be patched after they have been programmed into ROM.
+
+3. Platform-specific libraries can be placed in ROM.
+
+4. Functions can be accessed by one or more BL images.
+
+Index file
+~~~~~~~~~~
+
+.. image:: diagrams/romlib_design.png
+    :width: 600
+
+Library at ROM is described by an index file with the list of functions to be
+placed in ROM. The index file is platform specific and its format is:
+
+::
+
+    lib function    [patch]
+
+    lib      -- Name of the library the function belongs to
+    function -- Name of the function to be placed in library at ROM
+    [patch]  -- Option to patch the function
+
+It is also possible to insert reserved spaces in the list by using the keyword
+"reserved" rather than the "lib" and "function" names as shown below:
+
+::
+
+    reserved    reserved
+
+The reserved spaces can be used to add more functions in the future without
+affecting the order and location of functions already existing in the jump
+table. Also, for additional flexibility and modularity, the index file can
+include other index files.
+
+For an index file example, refer to ``lib/romlib/jmptbl.i``.
+
+Wrapper functions
+~~~~~~~~~~~~~~~~~
+
+.. image:: diagrams/romlib_wrapper.png
+    :width: 600
+
+When invoking a function of the "library at ROM", the calling sequence is as
+follows:
+
+BL image --> wrapper function --> jump table entry --> library at ROM
+
+The index file is used to create a jump table which is placed in ROM. Then, the
+wrappers refer to the jump table to call the "library at ROM" functions. The
+wrappers essentially contain a branch instruction to the jump table entry
+corresponding to the original function. Finally, the original function in the BL
+image(s) is replaced with the wrapper function.
+
+The "library at ROM" contains a necessary init function that initialises the
+global variables defined by the functions inside "library at ROM".
+
+Scripts
+~~~~~~~
+
+There are several scripts that generate the necessary files for the "library at
+ROM" to work:
+
+1. ``gentbl.sh`` - Generates the jump table by parsing the index file.
+
+2. ``genvar.sh`` - Generates the jump table global variable (**not** the jump
+table itself) with the absolute address in ROM. This global variable is,
+basically, a pointer to the jump table.
+
+3. ``genwrappers.sh`` - Generates a wrapper function for each entry in the index
+file except for the ones that contain the keyword ``patch``. The generated
+wrapper file is called ``<lib>_<fn_name>.S``.
+
+Patching of functions in library at ROM
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``genwrappers.sh`` script does not generate wrappers for the entries in the
+index file that contain the keyword ``patch``. Thus, it allows calling the
+function from the actual library by breaking the link to the  "library at ROM"
+version of this function.
+
+The calling sequence for a patched function is as follows:
+
+BL image --> function
+
+Build library at ROM
+~~~~~~~~~~~~~~~~~~~~~
+
+The environment variable ``CROSS_COMPILE`` must be set as per the user guide.
+
+::
+
+    make PLAT=fvp                                                   \
+    MBEDTLS_DIR=</path/to/mbedtls/>                                 \
+    TRUSTED_BOARD_BOOT=1 GENERATE_COT=1                             \
+    ARM_ROTPK_LOCATION=devel_rsa                                    \
+    ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
+    BL33=</path/to/bl33.bin>                                        \
+    USE_ROMLIB=1                                                    \
+    all fip
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*