1Library at ROM 2============== 3 4This 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 26.. image:: ../resources/diagrams/romlib_design.png 27 :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 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 57.. image:: ../resources/diagrams/romlib_wrapper.png 58 :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 74Script 75~~~~~~ 76 77There is a ``romlib_generate.py`` Python script that generates the necessary 78files for the "library at ROM" to work. It implements multiple functions: 79 801. ``romlib_generate.py gentbl [args]`` - Generates the jump table by parsing 81 the index file. 82 832. ``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. 86 873. ``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 101 102Patching of functions in library at ROM 103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 104 105The ``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. 109 110The calling sequence for a patched function is as follows: 111 112BL image --> function 113 114Memory impact 115~~~~~~~~~~~~~ 116 117Using library at ROM will modify the memory layout of the BL images: 118- The ROM library needs a page aligned RAM section to hold the RW data. This 119 section is defined by the ROMLIB_RW_BASE and ROMLIB_RW_END macros. 120 On Arm platforms a section of 1 page (0x1000) is allocated at the top of SRAM. 121 This will have for effect to shift down all the BL images by 1 page. 122- Depending on the functions moved to the ROM library, the size of the BL images 123 will be reduced. 124 For example: moving MbedTLS function into the ROM library reduces BL1 and 125 BL2, but not BL31. 126- This change in BL images size can be taken into consideration to optimize the 127 memory layout when defining the BLx_BASE macros. 128 129Build library at ROM 130~~~~~~~~~~~~~~~~~~~~~ 131 132The environment variable ``CROSS_COMPILE`` must be set as per the user guide. 133In the below example the usage of ROMLIB together with mbed TLS is demonstrated 134to showcase the benefits of library at ROM - it's not mandatory. 135 136.. code:: shell 137 138 make PLAT=fvp \ 139 MBEDTLS_DIR=</path/to/mbedtls/> \ 140 TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ 141 ARM_ROTPK_LOCATION=devel_rsa \ 142 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 143 BL33=</path/to/bl33.bin> \ 144 USE_ROMLIB=1 \ 145 all fip 146 147-------------- 148 149*Copyright (c) 2019, Arm Limited. All rights reserved.* 150
