1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
Library at ROM
==============
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:: ../resources/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
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:: ../resources/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".
Script
~~~~~~
There is a ``romlib_generate.py`` Python script that generates the necessary
files for the "library at ROM" to work. It implements multiple functions:
1. ``romlib_generate.py gentbl [args]`` - Generates the jump table by parsing
the index file.
2. ``romlib_generator.py genvar [args]`` - 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. ``romlib_generator.py genwrappers [args]`` - 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 ``<fn_name>.s``.
4. ``romlib_generator.py pre [args]`` - Preprocesses the index file which means
it resolves all the include commands in the file recursively. It can also
generate a dependency file of the included index files which can be directly
used in makefiles.
Each ``romlib_generate.py`` function has its own manual which is accessible by
runing ``romlib_generator.py [function] --help``.
``romlib_generate.py`` requires Python 3 environment.
Patching of functions in library at ROM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``romlib_generator.py genwrappers`` 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
Memory impact
~~~~~~~~~~~~~
Using library at ROM will modify the memory layout of the BL images:
- The ROM library needs a page aligned RAM section to hold the RW data. This
section is defined by the ROMLIB_RW_BASE and ROMLIB_RW_END macros.
On Arm platforms a section of 1 page (0x1000) is allocated at the top of SRAM.
This will have for effect to shift down all the BL images by 1 page.
- Depending on the functions moved to the ROM library, the size of the BL images
will be reduced.
For example: moving MbedTLS function into the ROM library reduces BL1 and
BL2, but not BL31.
- This change in BL images size can be taken into consideration to optimize the
memory layout when defining the BLx_BASE macros.
Build library at ROM
~~~~~~~~~~~~~~~~~~~~~
The environment variable ``CROSS_COMPILE`` must be set appropriately. Refer to
:ref:`Performing an Initial Build` for more information about setting this
variable.
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.
.. code:: shell
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.*
|
