mirror of
https://github.com/ARM-software/arm-trusted-firmware.git
synced 2025-04-17 10:04:26 +00:00
83993177d9
Required work to make all documents sit at the correct levels within the document tree and any derived content like the table of contents and the categories in the sidebar. Change-Id: I4885fbe30864a87c8822ee67482b71fb46a8fbc6 Signed-off-by: Paul Beesley <paul.beesley@arm.com>
130 lines
4.4 KiB
ReStructuredText
130 lines
4.4 KiB
ReStructuredText
Library at ROM
|
|
==============
|
|
|
|
.. 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.
|
|
In the below example the usage of ROMLIB together with mbed TLS is demonstrated
|
|
to showcase the benefits of library at ROM - it's not mandatory.
|
|
|
|
::
|
|
|
|
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
|
|
|
|
Known issue
|
|
-----------
|
|
When building library at ROM, a clean build is always required. This is
|
|
necessary when changes are made to the index files, e.g. adding new functions,
|
|
patching existing ones etc.
|
|
|
|
--------------
|
|
|
|
*Copyright (c) 2019, Arm Limited. All rights reserved.*
|