Sathees Balya | 17d8eed | 2019-01-30 15:56:44 +0000 | [diff] [blame] | 1 | Library at ROM |
| 2 | ============== |
| 3 | |
Sathees Balya | 17d8eed | 2019-01-30 15:56:44 +0000 | [diff] [blame] | 4 | .. contents:: |
| 5 | |
| 6 | This document provides an overview of the "library at ROM" implementation in |
| 7 | Trusted Firmware-A (TF-A). |
| 8 | |
| 9 | Introduction |
| 10 | ~~~~~~~~~~~~ |
| 11 | |
| 12 | The "library at ROM" feature allows platforms to build a library of functions to |
| 13 | be placed in ROM. This reduces SRAM usage by utilising the available space in |
| 14 | ROM. The "library at ROM" contains a jump table with the list of functions that |
| 15 | are placed in ROM. The capabilities of the "library at ROM" are: |
| 16 | |
| 17 | 1. Functions can be from one or several libraries. |
| 18 | |
| 19 | 2. Functions can be patched after they have been programmed into ROM. |
| 20 | |
| 21 | 3. Platform-specific libraries can be placed in ROM. |
| 22 | |
| 23 | 4. Functions can be accessed by one or more BL images. |
| 24 | |
| 25 | Index file |
| 26 | ~~~~~~~~~~ |
| 27 | |
| 28 | .. image:: diagrams/romlib_design.png |
| 29 | :width: 600 |
| 30 | |
| 31 | Library at ROM is described by an index file with the list of functions to be |
| 32 | placed 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 | |
| 42 | It 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 | |
| 49 | The reserved spaces can be used to add more functions in the future without |
| 50 | affecting the order and location of functions already existing in the jump |
| 51 | table. Also, for additional flexibility and modularity, the index file can |
| 52 | include other index files. |
| 53 | |
| 54 | For an index file example, refer to ``lib/romlib/jmptbl.i``. |
| 55 | |
| 56 | Wrapper functions |
| 57 | ~~~~~~~~~~~~~~~~~ |
| 58 | |
| 59 | .. image:: diagrams/romlib_wrapper.png |
| 60 | :width: 600 |
| 61 | |
| 62 | When invoking a function of the "library at ROM", the calling sequence is as |
| 63 | follows: |
| 64 | |
| 65 | BL image --> wrapper function --> jump table entry --> library at ROM |
| 66 | |
| 67 | The index file is used to create a jump table which is placed in ROM. Then, the |
| 68 | wrappers refer to the jump table to call the "library at ROM" functions. The |
| 69 | wrappers essentially contain a branch instruction to the jump table entry |
| 70 | corresponding to the original function. Finally, the original function in the BL |
| 71 | image(s) is replaced with the wrapper function. |
| 72 | |
| 73 | The "library at ROM" contains a necessary init function that initialises the |
| 74 | global variables defined by the functions inside "library at ROM". |
| 75 | |
| 76 | Scripts |
| 77 | ~~~~~~~ |
| 78 | |
| 79 | There are several scripts that generate the necessary files for the "library at |
| 80 | ROM" to work: |
| 81 | |
| 82 | 1. ``gentbl.sh`` - Generates the jump table by parsing the index file. |
| 83 | |
| 84 | 2. ``genvar.sh`` - Generates the jump table global variable (**not** the jump |
John Tsichritzis | aec19d3 | 2019-03-08 16:54:13 +0000 | [diff] [blame] | 85 | table itself) with the absolute address in ROM. This global variable is, |
| 86 | basically, a pointer to the jump table. |
Sathees Balya | 17d8eed | 2019-01-30 15:56:44 +0000 | [diff] [blame] | 87 | |
| 88 | 3. ``genwrappers.sh`` - Generates a wrapper function for each entry in the index |
John Tsichritzis | aec19d3 | 2019-03-08 16:54:13 +0000 | [diff] [blame] | 89 | file except for the ones that contain the keyword ``patch``. The generated |
| 90 | wrapper file is called ``<lib>_<fn_name>.S``. |
Sathees Balya | 17d8eed | 2019-01-30 15:56:44 +0000 | [diff] [blame] | 91 | |
| 92 | Patching of functions in library at ROM |
| 93 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 94 | |
| 95 | The ``genwrappers.sh`` script does not generate wrappers for the entries in the |
| 96 | index file that contain the keyword ``patch``. Thus, it allows calling the |
| 97 | function from the actual library by breaking the link to the "library at ROM" |
| 98 | version of this function. |
| 99 | |
| 100 | The calling sequence for a patched function is as follows: |
| 101 | |
| 102 | BL image --> function |
| 103 | |
| 104 | Build library at ROM |
| 105 | ~~~~~~~~~~~~~~~~~~~~~ |
| 106 | |
| 107 | The environment variable ``CROSS_COMPILE`` must be set as per the user guide. |
John Tsichritzis | aec19d3 | 2019-03-08 16:54:13 +0000 | [diff] [blame] | 108 | In the below example the usage of ROMLIB together with mbed TLS is demonstrated |
| 109 | to showcase the benefits of library at ROM - it's not mandatory. |
Sathees Balya | 17d8eed | 2019-01-30 15:56:44 +0000 | [diff] [blame] | 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 | |
John Tsichritzis | aec19d3 | 2019-03-08 16:54:13 +0000 | [diff] [blame] | 122 | Known issue |
| 123 | ----------- |
| 124 | When building library at ROM, a clean build is always required. This is |
| 125 | necessary when changes are made to the index files, e.g. adding new functions, |
| 126 | patching existing ones etc. |
| 127 | |
Sathees Balya | 17d8eed | 2019-01-30 15:56:44 +0000 | [diff] [blame] | 128 | -------------- |
| 129 | |
| 130 | *Copyright (c) 2019, Arm Limited. All rights reserved.* |