docs/components/romlib-design.rst

4 This document provides an overview of the "library at ROM" implementation in
11 be placed in ROM. This reduces SRAM usage by utilising the available space in
12 ROM. The "library at ROM" contains a jump table with the list of functions that
13 are placed in ROM. The capabilities of the "library at ROM" are:
29 Library at ROM is described by an index file with the list of functions to be
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
40 It 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:
47 The reserved spaces can be used to add more functions in the future without
48 affecting the order and location of functions already existing in the jump
49 table. Also, for additional flexibility and modularity, the index file can
60 When invoking a function of the "library at ROM", the calling sequence is as
65 The index file is used to create a jump table which is placed in ROM. Then, the
66 wrappers refer to the jump table to call the "library at ROM" functions. The
67 wrappers essentially contain a branch instruction to the jump table entry
68 corresponding to the original function. Finally, the original function in the BL
69 image(s) is replaced with the wrapper function.
71 The "library at ROM" contains a necessary init function that initialises the
72 global variables defined by the functions inside "library at ROM".
74 Wrapper functions are specified at the link stage of compilation and cannot
75 interpose uppon functions within the same translation unit. For example, if
77 the romlib jump table includes an entry for ``fn_b``, ``fn_a`` will include
78 a reference to ``fn_b``'s original program text instead of the wrapper. Thus
79 the jumptable author must take care to include public entry points into
80 translation units to avoid paying the program text cost twice, once in the
86 There is a ``romlib_generator.py`` Python script that generates the necessary
87 files for the "library at ROM" to work. It implements multiple functions:
89 1. ``romlib_generator.py gentbl [args]`` - Generates the jump table by parsing
90    the index file.
92 2. ``romlib_generator.py genvar [args]`` - Generates the jump table global
93    variable (**not** the jump table itself) with the absolute address in ROM.
94    This global variable is, basically, a pointer to the jump table.
97    each entry in the index file except for the ones that contain the keyword
100 4. ``romlib_generator.py pre [args]`` - Preprocesses the index file which means
101    it resolves all the include commands in the file recursively. It can also
102    generate a dependency file of the included index files which can be directly
114 The ``romlib_generator.py genwrappers`` does not generate wrappers for the
115 entries in the index file that contain the keyword ``patch``. Thus, it allows
116 calling the function from the actual library by breaking the link to the
126 Using library at ROM will modify the memory layout of the BL images:
128 - The ROM library needs a page aligned RAM section to hold the RW data. This
129   section is defined by the ROMLIB_RW_BASE and ROMLIB_RW_END macros.
130   On Arm platforms a section of 1 page (0x1000) is allocated at the top of SRAM.
131   This will have for effect to shift down all the BL images by 1 page.
133 - Depending on the functions moved to the ROM library, the size of the BL images
135   For example: moving MbedTLS function into the ROM library reduces BL1 and
138 - This change in BL images size can be taken into consideration to optimize the
139   memory layout when defining the BLx_BASE macros.
148 In the below example the usage of ROMLIB together with mbed TLS is demonstrated
149 to showcase the benefits of library at ROM - it's not mandatory.