diff options
Diffstat (limited to 'docs/tools/memory-layout-tool.rst')
| -rw-r--r-- | docs/tools/memory-layout-tool.rst | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/docs/tools/memory-layout-tool.rst b/docs/tools/memory-layout-tool.rst new file mode 100644 index 0000000..8874bd7 --- /dev/null +++ b/docs/tools/memory-layout-tool.rst @@ -0,0 +1,236 @@ +TF-A Memory Layout Tool +======================= + +TF-A's memory layout tool is a Python script for analyzing the virtual +memory layout of TF-A builds. + +Prerequisites +~~~~~~~~~~~~~ + +#. Python (3.8 or later) +#. `Poetry`_ Python package manager + +Getting Started +~~~~~~~~~~~~~~~ + +#. Install Poetry + + .. code:: shell + + curl -sSL https://install.python-poetry.org | python3 - + +#. Install the required packages + + .. code:: shell + + poetry install --with memory + +#. Verify that the tool runs in the installed virtual environment + + .. code:: shell + + poetry run memory --help + +Symbol Virtual Map +~~~~~~~~~~~~~~~~~~ + +The tool can be used to generate a visualisation of the symbol table. By +default, it prints the symbols representing the start and end address of the +main memory regions in an ELF file (i.e. text, bss, rodata) but can be modified +to print any set of symbols. + +.. code:: shell + + $ poetry run memory -s + build-path: build/fvp/release + Virtual Address Map: + +------------__BL1_RAM_END__------------+---------------------------------------+ + +---------__COHERENT_RAM_END__----------+ | + +--------__COHERENT_RAM_START__---------+ | + 0x0403b000 +----------__XLAT_TABLE_END__-----------+ | + 0x04036000 +---------__XLAT_TABLE_START__----------+ | + +--------__BASE_XLAT_TABLE_END__--------+ | + 0x04035600 +--------------__BSS_END__--------------+ | + +-------__BASE_XLAT_TABLE_START__-------+ | + +-----__PMF_PERCPU_TIMESTAMP_END__------+ | + +---------__PMF_TIMESTAMP_END__---------+ | + 0x04035400 +--------__PMF_TIMESTAMP_START__--------+ | + +-------------__BSS_START__-------------+ | + 0x04034a00 +------------__STACKS_END__-------------+ | + 0x04034500 +-----------__STACKS_START__------------+ | + 0x040344c5 +-----------__DATA_RAM_END__------------+ | + +-----------__BL1_RAM_START__-----------+ | + 0x04034000 +----------__DATA_RAM_START__-----------+ | + | +---------__COHERENT_RAM_END__----------+ + | +--------__COHERENT_RAM_START__---------+ + 0x0402e000 | +----------__XLAT_TABLE_END__-----------+ + 0x04029000 | +---------__XLAT_TABLE_START__----------+ + | +--------__BASE_XLAT_TABLE_END__--------+ + 0x04028800 | +--------------__BSS_END__--------------+ + | +-------__BASE_XLAT_TABLE_START__-------+ + | +-----__PMF_PERCPU_TIMESTAMP_END__------+ + | +---------__PMF_TIMESTAMP_END__---------+ + 0x04028580 | +--------__PMF_TIMESTAMP_START__--------+ + 0x04028000 | +-------------__BSS_START__-------------+ + 0x04027e40 | +------------__STACKS_END__-------------+ + 0x04027840 | +-----------__STACKS_START__------------+ + 0x04027000 | +------------__RODATA_END__-------------+ + | +------------__CPU_OPS_END__------------+ + | +-----------__CPU_OPS_START__-----------+ + | +--------__FCONF_POPULATOR_END__--------+ + | +--------------__GOT_END__--------------+ + | +-------------__GOT_START__-------------+ + | +---------__PMF_SVC_DESCS_END__---------+ + 0x04026c10 | +--------__PMF_SVC_DESCS_START__--------+ + 0x04026bf8 | +-------__FCONF_POPULATOR_START__-------+ + | +-----------__RODATA_START__------------+ + 0x04026000 | +-------------__TEXT_END__--------------+ + 0x04021000 | +------------__TEXT_START__-------------+ + 0x000062b5 +------------__BL1_ROM_END__------------+ | + 0x00005df0 +----------__DATA_ROM_START__-----------+ | + +------------__CPU_OPS_END__------------+ | + +--------------__GOT_END__--------------+ | + +-------------__GOT_START__-------------+ | + 0x00005de8 +------------__RODATA_END__-------------+ | + +-----------__CPU_OPS_START__-----------+ | + +--------__FCONF_POPULATOR_END__--------+ | + +---------__PMF_SVC_DESCS_END__---------+ | + 0x00005c98 +--------__PMF_SVC_DESCS_START__--------+ | + 0x00005c80 +-------__FCONF_POPULATOR_START__-------+ | + +-----------__RODATA_START__------------+ | + 0x00005000 +-------------__TEXT_END__--------------+ | + 0x00000000 +------------__TEXT_START__-------------+---------------------------------------+ + +Addresses are displayed in hexadecimal by default but can be printed in decimal +instead with the ``-d`` option. + +Because of the length of many of the symbols, the tool defaults to a text width +of 120 chars. This can be increased if needed with the ``-w`` option. + +For more detailed help instructions, run: + +.. code:: shell + + poetry run memory --help + +Memory Footprint +~~~~~~~~~~~~~~~~ + +The tool enables users to view static memory consumption. When the options +``-f``, or ``--footprint`` are provided, the script analyses the ELF binaries in +the build path to generate a table (per memory type), showing memory allocation +and usage. This is the default output generated by the tool. + +.. code:: shell + + $ poetry run memory -f + build-path: build/fvp/release + +----------------------------------------------------------------------------+ + | Memory Usage (bytes) [RAM] | + +-----------+------------+------------+------------+------------+------------+ + | Component | Start | Limit | Size | Free | Total | + +-----------+------------+------------+------------+------------+------------+ + | BL1 | 4034000 | 4040000 | 7000 | 5000 | c000 | + | BL2 | 4021000 | 4034000 | d000 | 6000 | 13000 | + | BL2U | 4021000 | 4034000 | a000 | 9000 | 13000 | + | BL31 | 4003000 | 4040000 | 1e000 | 1f000 | 3d000 | + +-----------+------------+------------+------------+------------+------------+ + + +----------------------------------------------------------------------------+ + | Memory Usage (bytes) [ROM] | + +-----------+------------+------------+------------+------------+------------+ + | Component | Start | Limit | Size | Free | Total | + +-----------+------------+------------+------------+------------+------------+ + | BL1 | 0 | 4000000 | 5df0 | 3ffa210 | 4000000 | + +-----------+------------+------------+------------+------------+------------+ + +The script relies on symbols in the symbol table to determine the start, end, +and limit addresses of each bootloader stage. + +Memory Tree +~~~~~~~~~~~ + +A hierarchical view of the memory layout can be produced by passing the option +``-t`` or ``--tree`` to the tool. This gives the start, end, and size of each +module, their ELF segments as well as sections. + +.. code:: shell + + $ poetry run memory -t + build-path: build/fvp/release + name start end size + bl1 0 400c000 400c000 + ├── 00 0 5de0 5de0 + │ ├── .text 0 5000 5000 + │ └── .rodata 5000 5de0 de0 + ├── 01 4034000 40344c5 4c5 + │ └── .data 4034000 40344c5 4c5 + ├── 02 4034500 4034a00 500 + │ └── .stacks 4034500 4034a00 500 + ├── 04 4034a00 4035600 c00 + │ └── .bss 4034a00 4035600 c00 + └── 03 4036000 403b000 5000 + └── .xlat_table 4036000 403b000 5000 + bl2 4021000 4034000 13000 + ├── 00 4021000 4027000 6000 + │ ├── .text 4021000 4026000 5000 + │ └── .rodata 4026000 4027000 1000 + └── 01 4027000 402e000 7000 + ├── .data 4027000 4027809 809 + ├── .stacks 4027840 4027e40 600 + ├── .bss 4028000 4028800 800 + └── .xlat_table 4029000 402e000 5000 + bl2u 4021000 4034000 13000 + ├── 00 4021000 4025000 4000 + │ ├── .text 4021000 4024000 3000 + │ └── .rodata 4024000 4025000 1000 + └── 01 4025000 402b000 6000 + ├── .data 4025000 4025065 65 + ├── .stacks 4025080 4025480 400 + ├── .bss 4025600 4025c00 600 + └── .xlat_table 4026000 402b000 5000 + bl31 4003000 4040000 3d000 + ├── 02 ffe00000 ffe03000 3000 + │ └── .el3_tzc_dram ffe00000 ffe03000 3000 + ├── 00 4003000 4010000 d000 + │ └── .text 4003000 4010000 d000 + └── 01 4010000 4021000 11000 + ├── .rodata 4010000 4012000 2000 + ├── .data 4012000 401219d 19d + ├── .stacks 40121c0 40161c0 4000 + ├── .bss 4016200 4018c00 2a00 + ├── .xlat_table 4019000 4020000 7000 + └── .coherent_ram 4020000 4021000 1000 + + +The granularity of this view can be modified with the ``--depth`` option. For +instance, if you only require the tree up to the level showing segment data, +you can specify the depth with: + +.. code:: + + $ poetry run memory -t --depth 2 + build-path: build/fvp/release + name start end size + bl1 0 400c000 400c000 + ├── 00 0 5df0 5df0 + ├── 01 4034000 40344c5 4c5 + ├── 02 4034500 4034a00 500 + ├── 04 4034a00 4035600 c00 + └── 03 4036000 403b000 5000 + bl2 4021000 4034000 13000 + ├── 00 4021000 4027000 6000 + └── 01 4027000 402e000 7000 + bl2u 4021000 4034000 13000 + ├── 00 4021000 4025000 4000 + └── 01 4025000 402b000 6000 + bl31 4003000 4040000 3d000 + ├── 02 ffe00000 ffe03000 3000 + ├── 00 4003000 4010000 d000 + └── 01 4010000 4021000 11000 + +-------------- + +*Copyright (c) 2023, Arm Limited. All rights reserved.* + +.. _Poetry: https://python-poetry.org/docs/ |