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