Gitiles
Code Review Sign In
git01.mediatek.com / filogic / atf / a61c330650beb71a87abef0e22392719078ab065 / . / docs / tools / memory-layout-tool.rst
blob: 8874bd7c7acbe93b2d19add1e21c556e07cf3ca7 [file] [log] [blame]
Harrison Mutaie9bc4882023-02-23 10:33:58 +0000[diff] [blame]1TF-A Memory Layout Tool
2=======================
3
4TF-A's memory layout tool is a Python script for analyzing the virtual
5memory layout of TF-A builds.
6
7Prerequisites
8~~~~~~~~~~~~~
9
10#. Python (3.8 or later)
11#. `Poetry`_ Python package manager
12
13Getting Started
14~~~~~~~~~~~~~~~
15
16#. Install Poetry
17
18 .. code:: shell
19
20 curl -sSL https://install.python-poetry.org | python3 -
21
22#. Install the required packages
23
24 .. code:: shell
25
26 poetry install --with memory
27
28#. Verify that the tool runs in the installed virtual environment
29
30 .. code:: shell
31
32 poetry run memory --help
33
34Symbol Virtual Map
35~~~~~~~~~~~~~~~~~~
36
37The tool can be used to generate a visualisation of the symbol table. By
38default, it prints the symbols representing the start and end address of the
39main memory regions in an ELF file (i.e. text, bss, rodata) but can be modified
40to print any set of symbols.
41
42.. code:: shell
43
44 $ poetry run memory -s
45 build-path: build/fvp/release
46 Virtual Address Map:
47 +------------__BL1_RAM_END__------------+---------------------------------------+
48 +---------__COHERENT_RAM_END__----------+ |
49 +--------__COHERENT_RAM_START__---------+ |
50 0x0403b000 +----------__XLAT_TABLE_END__-----------+ |
51 0x04036000 +---------__XLAT_TABLE_START__----------+ |
52 +--------__BASE_XLAT_TABLE_END__--------+ |
53 0x04035600 +--------------__BSS_END__--------------+ |
54 +-------__BASE_XLAT_TABLE_START__-------+ |
55 +-----__PMF_PERCPU_TIMESTAMP_END__------+ |
56 +---------__PMF_TIMESTAMP_END__---------+ |
57 0x04035400 +--------__PMF_TIMESTAMP_START__--------+ |
58 +-------------__BSS_START__-------------+ |
59 0x04034a00 +------------__STACKS_END__-------------+ |
60 0x04034500 +-----------__STACKS_START__------------+ |
61 0x040344c5 +-----------__DATA_RAM_END__------------+ |
62 +-----------__BL1_RAM_START__-----------+ |
63 0x04034000 +----------__DATA_RAM_START__-----------+ |
64 | +---------__COHERENT_RAM_END__----------+
65 | +--------__COHERENT_RAM_START__---------+
66 0x0402e000 | +----------__XLAT_TABLE_END__-----------+
67 0x04029000 | +---------__XLAT_TABLE_START__----------+
68 | +--------__BASE_XLAT_TABLE_END__--------+
69 0x04028800 | +--------------__BSS_END__--------------+
70 | +-------__BASE_XLAT_TABLE_START__-------+
71 | +-----__PMF_PERCPU_TIMESTAMP_END__------+
72 | +---------__PMF_TIMESTAMP_END__---------+
73 0x04028580 | +--------__PMF_TIMESTAMP_START__--------+
74 0x04028000 | +-------------__BSS_START__-------------+
75 0x04027e40 | +------------__STACKS_END__-------------+
76 0x04027840 | +-----------__STACKS_START__------------+
77 0x04027000 | +------------__RODATA_END__-------------+
78 | +------------__CPU_OPS_END__------------+
79 | +-----------__CPU_OPS_START__-----------+
80 | +--------__FCONF_POPULATOR_END__--------+
81 | +--------------__GOT_END__--------------+
82 | +-------------__GOT_START__-------------+
83 | +---------__PMF_SVC_DESCS_END__---------+
84 0x04026c10 | +--------__PMF_SVC_DESCS_START__--------+
85 0x04026bf8 | +-------__FCONF_POPULATOR_START__-------+
86 | +-----------__RODATA_START__------------+
87 0x04026000 | +-------------__TEXT_END__--------------+
88 0x04021000 | +------------__TEXT_START__-------------+
89 0x000062b5 +------------__BL1_ROM_END__------------+ |
90 0x00005df0 +----------__DATA_ROM_START__-----------+ |
91 +------------__CPU_OPS_END__------------+ |
92 +--------------__GOT_END__--------------+ |
93 +-------------__GOT_START__-------------+ |
94 0x00005de8 +------------__RODATA_END__-------------+ |
95 +-----------__CPU_OPS_START__-----------+ |
96 +--------__FCONF_POPULATOR_END__--------+ |
97 +---------__PMF_SVC_DESCS_END__---------+ |
98 0x00005c98 +--------__PMF_SVC_DESCS_START__--------+ |
99 0x00005c80 +-------__FCONF_POPULATOR_START__-------+ |
100 +-----------__RODATA_START__------------+ |
101 0x00005000 +-------------__TEXT_END__--------------+ |
102 0x00000000 +------------__TEXT_START__-------------+---------------------------------------+
103
104Addresses are displayed in hexadecimal by default but can be printed in decimal
105instead with the ``-d`` option.
106
107Because of the length of many of the symbols, the tool defaults to a text width
108of 120 chars. This can be increased if needed with the ``-w`` option.
109
110For more detailed help instructions, run:
111
112.. code:: shell
113
114 poetry run memory --help
115
Harrison Mutai372b8802023-02-23 11:30:17 +0000[diff] [blame]116Memory Footprint
117~~~~~~~~~~~~~~~~
118
119The tool enables users to view static memory consumption. When the options
120``-f``, or ``--footprint`` are provided, the script analyses the ELF binaries in
121the build path to generate a table (per memory type), showing memory allocation
122and usage. This is the default output generated by the tool.
123
124.. code:: shell
125
126 $ poetry run memory -f
127 build-path: build/fvp/release
128 +----------------------------------------------------------------------------+
129 | Memory Usage (bytes) [RAM] |
130 +-----------+------------+------------+------------+------------+------------+
131 | Component | Start | Limit | Size | Free | Total |
132 +-----------+------------+------------+------------+------------+------------+
133 | BL1 | 4034000 | 4040000 | 7000 | 5000 | c000 |
134 | BL2 | 4021000 | 4034000 | d000 | 6000 | 13000 |
135 | BL2U | 4021000 | 4034000 | a000 | 9000 | 13000 |
136 | BL31 | 4003000 | 4040000 | 1e000 | 1f000 | 3d000 |
137 +-----------+------------+------------+------------+------------+------------+
138
139 +----------------------------------------------------------------------------+
140 | Memory Usage (bytes) [ROM] |
141 +-----------+------------+------------+------------+------------+------------+
142 | Component | Start | Limit | Size | Free | Total |
143 +-----------+------------+------------+------------+------------+------------+
144 | BL1 | 0 | 4000000 | 5df0 | 3ffa210 | 4000000 |
145 +-----------+------------+------------+------------+------------+------------+
146
147The script relies on symbols in the symbol table to determine the start, end,
148and limit addresses of each bootloader stage.
149
Harrison Mutai0c0afde2023-02-23 11:30:55 +0000[diff] [blame]150Memory Tree
151~~~~~~~~~~~
152
153A hierarchical view of the memory layout can be produced by passing the option
154``-t`` or ``--tree`` to the tool. This gives the start, end, and size of each
155module, their ELF segments as well as sections.
156
157.. code:: shell
158
159 $ poetry run memory -t
160 build-path: build/fvp/release
161 name start end size
162 bl1 0 400c000 400c000
163 ├── 00 0 5de0 5de0
164 │ ├── .text 0 5000 5000
165 │ └── .rodata 5000 5de0 de0
166 ├── 01 4034000 40344c5 4c5
167 │ └── .data 4034000 40344c5 4c5
168 ├── 02 4034500 4034a00 500
169 │ └── .stacks 4034500 4034a00 500
170 ├── 04 4034a00 4035600 c00
171 │ └── .bss 4034a00 4035600 c00
172 └── 03 4036000 403b000 5000
173 └── .xlat_table 4036000 403b000 5000
174 bl2 4021000 4034000 13000
175 ├── 00 4021000 4027000 6000
176 │ ├── .text 4021000 4026000 5000
177 │ └── .rodata 4026000 4027000 1000
178 └── 01 4027000 402e000 7000
179 ├── .data 4027000 4027809 809
180 ├── .stacks 4027840 4027e40 600
181 ├── .bss 4028000 4028800 800
182 └── .xlat_table 4029000 402e000 5000
183 bl2u 4021000 4034000 13000
184 ├── 00 4021000 4025000 4000
185 │ ├── .text 4021000 4024000 3000
186 │ └── .rodata 4024000 4025000 1000
187 └── 01 4025000 402b000 6000
188 ├── .data 4025000 4025065 65
189 ├── .stacks 4025080 4025480 400
190 ├── .bss 4025600 4025c00 600
191 └── .xlat_table 4026000 402b000 5000
192 bl31 4003000 4040000 3d000
193 ├── 02 ffe00000 ffe03000 3000
194 │ └── .el3_tzc_dram ffe00000 ffe03000 3000
195 ├── 00 4003000 4010000 d000
196 │ └── .text 4003000 4010000 d000
197 └── 01 4010000 4021000 11000
198 ├── .rodata 4010000 4012000 2000
199 ├── .data 4012000 401219d 19d
200 ├── .stacks 40121c0 40161c0 4000
201 ├── .bss 4016200 4018c00 2a00
202 ├── .xlat_table 4019000 4020000 7000
203 └── .coherent_ram 4020000 4021000 1000
204
205
206The granularity of this view can be modified with the ``--depth`` option. For
207instance, if you only require the tree up to the level showing segment data,
208you can specify the depth with:
209
210.. code::
211
212 $ poetry run memory -t --depth 2
213 build-path: build/fvp/release
214 name start end size
215 bl1 0 400c000 400c000
216 ├── 00 0 5df0 5df0
217 ├── 01 4034000 40344c5 4c5
218 ├── 02 4034500 4034a00 500
219 ├── 04 4034a00 4035600 c00
220 └── 03 4036000 403b000 5000
221 bl2 4021000 4034000 13000
222 ├── 00 4021000 4027000 6000
223 └── 01 4027000 402e000 7000
224 bl2u 4021000 4034000 13000
225 ├── 00 4021000 4025000 4000
226 └── 01 4025000 402b000 6000
227 bl31 4003000 4040000 3d000
228 ├── 02 ffe00000 ffe03000 3000
229 ├── 00 4003000 4010000 d000
230 └── 01 4010000 4021000 11000
231
Harrison Mutaie9bc4882023-02-23 10:33:58 +0000[diff] [blame]232--------------
233
234*Copyright (c) 2023, Arm Limited. All rights reserved.*
235
236.. _Poetry: https://python-poetry.org/docs/