4.12.1.Introduction

The “library at ROM” feature allows platforms to build a library of functions tobe placed in ROM. This reduces SRAM usage by utilising the available space inROM. The “library at ROM” contains a jump table with the list of functions thatare 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.

4.12.2.Index file

Library at ROM is described by an index file with the list of functions to beplaced in ROM. The index file is platform specific and its format is:

libfunction[patch]lib--Nameofthelibrarythefunctionbelongstofunction--NameofthefunctiontobeplacedinlibraryatROM[patch]--Optiontopatchthefunction

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 withoutaffecting the order and location of functions already existing in the jumptable. Also, for additional flexibility and modularity, the index file caninclude other index files.

For an index file example, refer tolib/romlib/jmptbl.i.

4.12.3.Wrapper functions

When invoking a function of the “library at ROM”, the calling sequence is asfollows:

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, thewrappers refer to the jump table to call the “library at ROM” functions. Thewrappers essentially contain a branch instruction to the jump table entrycorresponding to the original function. Finally, the original function in the BLimage(s) is replaced with the wrapper function.

The “library at ROM” contains a necessary init function that initialises theglobal variables defined by the functions inside “library at ROM”.

Wrapper functions are specified at the link stage of compilation and cannotinterpose uppon functions within the same translation unit. For example, iffunctionfn_a callsfn_b within translation unitfunctions.c andthe romlib jump table includes an entry forfn_b,fn_a will includea reference tofn_b’s original program text instead of the wrapper. Thusthe jumptable author must take care to include public entry points intotranslation units to avoid paying the program text cost twice, once in theoriginal executable and once in romlib.

4.12.4.Script

There is aromlib_generator.py Python script that generates the necessaryfiles for the “library at ROM” to work. It implements multiple functions:

1. romlib_generator.pygentbl[args] - Generates the jump table by parsingthe index file.

2. romlib_generator.pygenvar[args] - Generates the jump table globalvariable (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.pygenwrappers[args] - Generates a wrapper function foreach entry in the index file except for the ones that contain the keywordpatch. The generated wrapper file is calledwrappers.s.

4. romlib_generator.pypre[args] - Preprocesses the index file which meansit resolves all the include commands in the file recursively. It can alsogenerate a dependency file of the included index files which can be directlyused in makefiles.

Eachromlib_generator.py function has its own manual which is accessible byruningromlib_generator.py[function]--help.

romlib_generator.py requires Python 3 environment.

4.12.5.Patching of functions in library at ROM

Theromlib_generator.pygenwrappers does not generate wrappers for theentries in the index file that contain the keywordpatch. Thus, it allowscalling 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

4.12.6.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. Thissection 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 imageswill be reduced.For example: moving MbedTLS function into the ROM library reduces BL1 andBL2, but not BL31.

• This change in BL images size can be taken into consideration to optimize thememory layout when defining the BLx_BASE macros.

4.12.7.Build library at ROM

The environment variableCROSS_COMPILE must be set appropriately. Refer toPerforming an Initial Build for more information about setting thisvariable.

In the below example the usage of ROMLIB together with mbed TLS is demonstratedto showcase the benefits of library at ROM - it’s not mandatory.

makePLAT=fvp\MBEDTLS_DIR=</path/to/mbedtls/>\TRUSTED_BOARD_BOOT=1GENERATE_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\allfip

Copyright (c) 2019, Arm Limited. All rights reserved.