aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSathees Balya <sathees.balya@arm.com>2019-01-30 15:56:44 +0000
committerJohn Tsichritzis <john.tsichritzis@arm.com>2019-02-19 15:49:23 +0000
commite36950bd6994f0168db66626394398a6dec1ae1d (patch)
treeecfc3e767f5b1f29becbca0453b829dda737c2a0
parentfa233ac9d435905d2717a9880cfb3a1671e37134 (diff)
downloadtrusted-firmware-a-e36950bd6994f0168db66626394398a6dec1ae1d.tar.gz
docs: Document romlib design
Change-Id: I2b75be16f452a8ab7c2445ccd519fb057a135812 Co-authored-by: John Tsichritzis <john.tsichritzis@arm.com> Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>
-rwxr-xr-xdocs/diagrams/romlib_design.diabin0 -> 2985 bytes
-rwxr-xr-xdocs/diagrams/romlib_design.pngbin0 -> 17244 bytes
-rwxr-xr-xdocs/diagrams/romlib_wrapper.diabin0 -> 2543 bytes
-rwxr-xr-xdocs/diagrams/romlib_wrapper.pngbin0 -> 12085 bytes
-rw-r--r--docs/firmware-design.rst6
-rw-r--r--docs/romlib-design.rst125
6 files changed, 131 insertions, 0 deletions
diff --git a/docs/diagrams/romlib_design.dia b/docs/diagrams/romlib_design.dia
new file mode 100755
index 0000000000..d12eec07dd
--- /dev/null
+++ b/docs/diagrams/romlib_design.dia
Binary files differ
diff --git a/docs/diagrams/romlib_design.png b/docs/diagrams/romlib_design.png
new file mode 100755
index 0000000000..bfffcde7ba
--- /dev/null
+++ b/docs/diagrams/romlib_design.png
Binary files differ
diff --git a/docs/diagrams/romlib_wrapper.dia b/docs/diagrams/romlib_wrapper.dia
new file mode 100755
index 0000000000..30cfbd8010
--- /dev/null
+++ b/docs/diagrams/romlib_wrapper.dia
Binary files differ
diff --git a/docs/diagrams/romlib_wrapper.png b/docs/diagrams/romlib_wrapper.png
new file mode 100755
index 0000000000..ec3a44118b
--- /dev/null
+++ b/docs/diagrams/romlib_wrapper.png
Binary files differ
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst
index 617cbb8861..4f51ff1d31 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)
----------------------------
@@ -2662,5 +2667,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/romlib-design.rst b/docs/romlib-design.rst
new file mode 100644
index 0000000000..34a7980be0
--- /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.*