blob: d34b3cc58fe9feccadd9423858b259c45ef4e69f [file] [log] [blame]
Sathees Balyae36950b2019-01-30 15:56:44 +00001Library at ROM
2==============
3
Sathees Balyae36950b2019-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 Beesleya2c320a2019-03-13 15:49:27 +000026.. image:: ../resources/diagrams/romlib_design.png
Sathees Balyae36950b2019-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
Imre Kisd8210dc2019-07-09 18:30:58 +020045 reserved
Sathees Balyae36950b2019-01-30 15:56:44 +000046
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 Beesleya2c320a2019-03-13 15:49:27 +000057.. image:: ../resources/diagrams/romlib_wrapper.png
Sathees Balyae36950b2019-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
Imre Kisd8210dc2019-07-09 18:30:58 +020074Script
75~~~~~~
Sathees Balyae36950b2019-01-30 15:56:44 +000076
Imre Kisd8210dc2019-07-09 18:30:58 +020077There is a ``romlib_generate.py`` Python script that generates the necessary
78files for the "library at ROM" to work. It implements multiple functions:
Sathees Balyae36950b2019-01-30 15:56:44 +000079
Imre Kisd8210dc2019-07-09 18:30:58 +0200801. ``romlib_generate.py gentbl [args]`` - Generates the jump table by parsing
81 the index file.
Sathees Balyae36950b2019-01-30 15:56:44 +000082
Imre Kisd8210dc2019-07-09 18:30:58 +0200832. ``romlib_generator.py genvar [args]`` - Generates the jump table global
84 variable (**not** the jump table itself) with the absolute address in ROM.
85 This global variable is, basically, a pointer to the jump table.
Sathees Balyae36950b2019-01-30 15:56:44 +000086
Imre Kisd8210dc2019-07-09 18:30:58 +0200873. ``romlib_generator.py genwrappers [args]`` - Generates a wrapper function for
88 each entry in the index file except for the ones that contain the keyword
89 ``patch``. The generated wrapper file is called ``<fn_name>.s``.
90
914. ``romlib_generator.py pre [args]`` - Preprocesses the index file which means
92 it resolves all the include commands in the file recursively. It can also
93 generate a dependency file of the included index files which can be directly
94 used in makefiles.
95
96Each ``romlib_generate.py`` function has its own manual which is accessible by
97runing ``romlib_generator.py [function] --help``.
98
99``romlib_generate.py`` requires Python 3 environment.
100
Sathees Balyae36950b2019-01-30 15:56:44 +0000101
102Patching of functions in library at ROM
103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
Imre Kisd8210dc2019-07-09 18:30:58 +0200105The ``romlib_generator.py genwrappers`` does not generate wrappers for the
106entries in the index file that contain the keyword ``patch``. Thus, it allows
107calling the function from the actual library by breaking the link to the
108"library at ROM" version of this function.
Sathees Balyae36950b2019-01-30 15:56:44 +0000109
110The calling sequence for a patched function is as follows:
111
112BL image --> function
113
Louis Mayencourt4685b642019-10-11 15:27:01 +0100114Memory impact
115~~~~~~~~~~~~~
116
117Using library at ROM will modify the memory layout of the BL images:
Paul Beesley43f35ef2019-05-29 13:59:40 +0100118
Louis Mayencourt4685b642019-10-11 15:27:01 +0100119- The ROM library needs a page aligned RAM section to hold the RW data. This
Paul Beesley43f35ef2019-05-29 13:59:40 +0100120 section is defined by the ROMLIB_RW_BASE and ROMLIB_RW_END macros.
121 On Arm platforms a section of 1 page (0x1000) is allocated at the top of SRAM.
122 This will have for effect to shift down all the BL images by 1 page.
123
Louis Mayencourt4685b642019-10-11 15:27:01 +0100124- Depending on the functions moved to the ROM library, the size of the BL images
Paul Beesley43f35ef2019-05-29 13:59:40 +0100125 will be reduced.
126 For example: moving MbedTLS function into the ROM library reduces BL1 and
127 BL2, but not BL31.
128
Louis Mayencourt4685b642019-10-11 15:27:01 +0100129- This change in BL images size can be taken into consideration to optimize the
Paul Beesley43f35ef2019-05-29 13:59:40 +0100130 memory layout when defining the BLx_BASE macros.
Louis Mayencourt4685b642019-10-11 15:27:01 +0100131
Sathees Balyae36950b2019-01-30 15:56:44 +0000132Build library at ROM
133~~~~~~~~~~~~~~~~~~~~~
134
Paul Beesley43f35ef2019-05-29 13:59:40 +0100135The environment variable ``CROSS_COMPILE`` must be set appropriately. Refer to
136:ref:`Performing an Initial Build` for more information about setting this
137variable.
138
John Tsichritzisae2e01b2019-03-08 16:54:13 +0000139In the below example the usage of ROMLIB together with mbed TLS is demonstrated
140to showcase the benefits of library at ROM - it's not mandatory.
Sathees Balyae36950b2019-01-30 15:56:44 +0000141
Paul Beesley29c02522019-03-13 15:11:04 +0000142.. code:: shell
Sathees Balyae36950b2019-01-30 15:56:44 +0000143
144 make PLAT=fvp \
145 MBEDTLS_DIR=</path/to/mbedtls/> \
146 TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
147 ARM_ROTPK_LOCATION=devel_rsa \
148 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
149 BL33=</path/to/bl33.bin> \
150 USE_ROMLIB=1 \
151 all fip
152
Sathees Balyae36950b2019-01-30 15:56:44 +0000153--------------
154
155*Copyright (c) 2019, Arm Limited. All rights reserved.*