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