blob: a70ed17ff5223e12d9e698e775752c615e613095 [file] [log] [blame]
Sathees Balya17d8eed2019-01-30 15:56:44 +00001Library at ROM
2==============
3
Sathees Balya17d8eed2019-01-30 15:56:44 +00004This document provides an overview of the "library at ROM" implementation in
5Trusted Firmware-A (TF-A).
6
7Introduction
8~~~~~~~~~~~~
9
10The "library at ROM" feature allows platforms to build a library of functions to
11be placed in ROM. This reduces SRAM usage by utilising the available space in
12ROM. The "library at ROM" contains a jump table with the list of functions that
13are placed in ROM. The capabilities of the "library at ROM" are:
14
151. Functions can be from one or several libraries.
16
172. Functions can be patched after they have been programmed into ROM.
18
193. Platform-specific libraries can be placed in ROM.
20
214. Functions can be accessed by one or more BL images.
22
23Index file
24~~~~~~~~~~
25
Paul Beesley814f8c02019-03-13 15:49:27 +000026.. image:: ../resources/diagrams/romlib_design.png
Sathees Balya17d8eed2019-01-30 15:56:44 +000027 :width: 600
28
29Library at ROM is described by an index file with the list of functions to be
30placed in ROM. The index file is platform specific and its format is:
31
32::
33
34 lib function [patch]
35
36 lib -- Name of the library the function belongs to
37 function -- Name of the function to be placed in library at ROM
38 [patch] -- Option to patch the function
39
40It is also possible to insert reserved spaces in the list by using the keyword
41"reserved" rather than the "lib" and "function" names as shown below:
42
43::
44
45 reserved reserved
46
47The reserved spaces can be used to add more functions in the future without
48affecting the order and location of functions already existing in the jump
49table. Also, for additional flexibility and modularity, the index file can
50include other index files.
51
52For an index file example, refer to ``lib/romlib/jmptbl.i``.
53
54Wrapper functions
55~~~~~~~~~~~~~~~~~
56
Paul Beesley814f8c02019-03-13 15:49:27 +000057.. image:: ../resources/diagrams/romlib_wrapper.png
Sathees Balya17d8eed2019-01-30 15:56:44 +000058 :width: 600
59
60When invoking a function of the "library at ROM", the calling sequence is as
61follows:
62
63BL image --> wrapper function --> jump table entry --> library at ROM
64
65The index file is used to create a jump table which is placed in ROM. Then, the
66wrappers refer to the jump table to call the "library at ROM" functions. The
67wrappers essentially contain a branch instruction to the jump table entry
68corresponding to the original function. Finally, the original function in the BL
69image(s) is replaced with the wrapper function.
70
71The "library at ROM" contains a necessary init function that initialises the
72global variables defined by the functions inside "library at ROM".
73
74Scripts
75~~~~~~~
76
77There are several scripts that generate the necessary files for the "library at
78ROM" to work:
79
801. ``gentbl.sh`` - Generates the jump table by parsing the index file.
81
822. ``genvar.sh`` - Generates the jump table global variable (**not** the jump
John Tsichritzisaec19d32019-03-08 16:54:13 +000083 table itself) with the absolute address in ROM. This global variable is,
84 basically, a pointer to the jump table.
Sathees Balya17d8eed2019-01-30 15:56:44 +000085
863. ``genwrappers.sh`` - Generates a wrapper function for each entry in the index
John Tsichritzisaec19d32019-03-08 16:54:13 +000087 file except for the ones that contain the keyword ``patch``. The generated
88 wrapper file is called ``<lib>_<fn_name>.S``.
Sathees Balya17d8eed2019-01-30 15:56:44 +000089
90Patching of functions in library at ROM
91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93The ``genwrappers.sh`` script does not generate wrappers for the entries in the
94index file that contain the keyword ``patch``. Thus, it allows calling the
95function from the actual library by breaking the link to the "library at ROM"
96version of this function.
97
98The calling sequence for a patched function is as follows:
99
100BL image --> function
101
102Build library at ROM
103~~~~~~~~~~~~~~~~~~~~~
104
105The environment variable ``CROSS_COMPILE`` must be set as per the user guide.
John Tsichritzisaec19d32019-03-08 16:54:13 +0000106In the below example the usage of ROMLIB together with mbed TLS is demonstrated
107to showcase the benefits of library at ROM - it's not mandatory.
Sathees Balya17d8eed2019-01-30 15:56:44 +0000108
Paul Beesley493e3492019-03-13 15:11:04 +0000109.. code:: shell
Sathees Balya17d8eed2019-01-30 15:56:44 +0000110
111 make PLAT=fvp \
112 MBEDTLS_DIR=</path/to/mbedtls/> \
113 TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
114 ARM_ROTPK_LOCATION=devel_rsa \
115 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
116 BL33=</path/to/bl33.bin> \
117 USE_ROMLIB=1 \
118 all fip
119
John Tsichritzisaec19d32019-03-08 16:54:13 +0000120Known issue
121-----------
122When building library at ROM, a clean build is always required. This is
123necessary when changes are made to the index files, e.g. adding new functions,
124patching existing ones etc.
125
Sathees Balya17d8eed2019-01-30 15:56:44 +0000126--------------
127
128*Copyright (c) 2019, Arm Limited. All rights reserved.*