IDF Size

IDF Size is a tool for analyzing statically-allocated memory in ESP-IDF project. The main functionality is provided by the esp-idf-size Python package, while idf.py offers a more user-friendly and higher-level interface through the size, size-components, and size-files sub-commands. These sub-commands allow you to specify various options, such as the report's output format. For more details, please use the --help option. ESP-IDF also includes a handy idf_size.py wrapper to invoke the esp-idf-size Python module. For more information, use the command idf_size.py --help.

Size Summary idf.py size

This output provides a summary of the statically-allocated memory for different memory types in the firmware binary:

$ idf.py size
                             Memory Type Usage Summary
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Memory Type/Section    Used [bytes]  Used [%]  Remain [bytes]  Total [bytes] ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ Flash Code                    80666      2.41         3261638        3342304 │
│    .text                      80666      2.41                                │
│ IRAM                          51835     39.55           79237         131072 │
│    .text                      50807     38.76                                │
│    .vectors                    1027      0.78                                │
│ Flash Data                    38224      0.91         4156048        4194272 │
│    .rodata                    37968      0.91                                │
│    .appdesc                     256      0.01                                │
│ DRAM                          11236      6.22          169500         180736 │
│    .data                       8988      4.97                                │
│    .bss                        2248      1.24                                │
│ RTC SLOW                         24      0.29            8168           8192 │
│    .rtc_slow_reserved            24      0.29                                │
└───────────────────────┴──────────────┴──────────┴────────────────┴───────────────┘
Total image size: 179712 bytes (.bin may be padded larger)

Espressif chips include various Memory Types, which are detailed in the Technical Reference Manual (TRM). These memory types are listed in the Memory Type column, along with the ELF Sections that are loaded into each type. The Used columns display the memory usage for each specific memory type or section. The Remain column indicates the remaining available memory for the specified memory type. The Total column shows the total available memory for that memory type, based on the memory region sizes defined in the linker script that map into the memory type.

Note

The Total memory available for each memory type, like IRAM, is determined by the memory region sizes specified in the link map file, which is generated by the linker script, with the MEMORY command, during the build process. The esp-idf-size tool includes YAML files for each target, detailing memory type ranges based on the TRM. The memory ranges from the link map file are mapped to these memory type ranges. This process calculates the total memory available for different memory types. Note that the total available size may differ from what is stated in the TRM, as some memory portions may be reserved for purposes such as the bootloader or cache, depending on the configuration. The remaining memory is calculated by subtracting the sizes of output Sections loaded to the specific memory type from the Total size.

Note

Certain memory types might map to the same hardware memory. On some targets, IRAM and DRAM could be mapped to the same hardware memory but at different virtual addresses, accessible through data and instruction buses. These memory types are referred to as DIRAM in the Memory Type column.

Below is a description of the most interesting memory types and output sections. Please note that all output sections with a non-zero size are included in the summary. Their names are determined by the output section names specified in the linker script.

  • DRAM: Total amount of DRAM allocated at compile time. Remain indicates the amount of DRAM left to be used as heap memory at runtime. Note that due to meta data overhead, implementation constraints, and startup heap allocations, the actual size of the DRAM heap is smaller.

    • .data: Amount of DRAM allocated at compile time for the .data (i.e., all statically allocated variables that are initialized to non-zero values). .data also consumes space in the binary image to store the non-zero initialization values.

    • .bss: Amount of DRAM allocated at compile time for .bss (i.e., all statically allocated variables that are initialized to zero). .bss does not consume extra space in flash.

  • IRAM: Total amount of IRAM allocated at compile time. Remain indicates the amount of IRAM left to be used as heap memory at runtime. Note that due to meta data overhead, implementation constraints, and startup heap allocations, the actual size of the IRAM heap is smaller.

    • .text: Amount of IRAM used for .text (i.e., all code that is executed from IRAM). .text also consumes space in the binary image as the code is initially stored there and is then copied over to IRAM on startup.

  • Flash Code: Code executed from flash.

    • .text: Amount of flash used for .text (i.e., all code that is executed via the flash cache, see IROM).

  • Flash Data: Data stored in flash.

    • .rodata: Amount of flash used for .rodata (i.e., read-only data that is loaded via the flash cache, see DROM).

  • Total image size is the estimated total size of the binary file.

Component Usage Summary idf.py size-components

The summary output from idf.py size lacks sufficient detail to identify the primary cause of excessive binary size. For a more detailed analysis, use idf.py size-components, which indicates the contribution of each static library archive to the final binary size.

$ idf.py size-components
                                                                 Per-archive contributions to ELF file
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Archive File             Total Size  DRAM  .bss  .data   IRAM  .text  .vectors  Flash Code  .text  Flash Data  .rodata  .appdesc  RTC SLOW  .rtc_slow_reserved ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ libnet80211.a                116712  9454  8393   1061   5310   5310         0       89698  89698       12250    12250         0         0                   0 │
│ libmbedcrypto.a              105863   141    81     60      0      0         0       71251  71251       34471    34471         0         0                   0 │
│ liblwip.a                     85394  2470  2458     12      0      0         0       79486  79486        3438     3438         0         0                   0 │
│ libpp.a                       66484  3915  1444   2471  20004  20004         0       37714  37714        4851     4851         0         0                   0 │
│ libc.a                        59525   576   316    260      0      0         0       55513  55513        3436     3436         0         0                   0 │
│ libesp_app_format.a           53209    10    10      0      0      0         0         417    417       52782    52526       256         0                   0 │
│ libwpa_supplicant.a           45251  1241  1233      8      0      0         0       42315  42315        1695     1695         0         0                   0 │
│ libphy.a                      44360  1229   637    592   8922   8922         0       34209  34209           0        0         0         0                   0 │
│ libfreertos.a                 21108  3841   741   3100  15594  15594         0         467    467        1206     1206         0         0                   0 │
│ libesp_hw_support.a           15147   256    96    160   5654   5654         0        8264   8264         949      949         0        24                  24 │
│ libnvs_flash.a                14522    24    24      0      0      0         0       14250  14250         248      248         0         0                   0 │
│ libesp_system.a               13304   793   313    480   4267   4267         0        7575   7575         669      669         0         0                   0 │
│ libhal.a                      13078  4000     8   3992   5810   5810         0        3143   3143         125      125         0         0                   0 │
│ libheap.a                     12009    12     8      4   7298   7298         0        3109   3109        1590     1590         0         0                   0 │
│ libspi_flash.a                11613  1348    24   1324   8932   8932         0         865    865         468      468         0         0                   0 │
│ libesp_driver_uart.a           7255   228    32    196      0      0         0        6434   6434         593      593         0         0                   0 │
│ libesp_netif.a                 5954    33    29      4      0      0         0        5758   5758         163      163         0         0                   0 │
│ libvfs.a                       4180   236    44    192      0      0         0        3757   3757         187      187         0         0                   0 │
│ libesp_mm.a                    4003   160   124     36   1002   1002         0        2627   2627         214      214         0         0                   0 │
│ libesp_wifi.a                  3919   527    47    480    357    357         0        2993   2993          42       42         0         0                   0 │
│ libesp_timer.a                 3471    56    24     32   1621   1621         0        1659   1659         135      135         0         0                   0 │
│ libxtensa.a                    3412  1044     0   1044   2213   1789       424         119    119          36       36         0         0                   0 │
│ libnewlib.a                    3352   360   200    160   1535   1535         0        1346   1346         111      111         0         0                   0 │
│ libesp_event.a                 3137     4     4      0      0      0         0        2992   2992         141      141         0         0                   0 │
│ libesp_phy.a                   2400    53    36     17    235    235         0        1868   1868         244      244         0         0                   0 │
│ libbootloader_support.a        1939     0     0      0   1805   1805         0          94     94          40       40         0         0                   0 │
│ libesp_partition.a             1865     8     8      0      0      0         0        1689   1689         168      168         0         0                   0 │
│ libesp_common.a                1793     0     0      0      0      0         0          51     51        1742     1742         0         0                   0 │
│ liblog.a                       1706   280   272      8    276    276         0        1102   1102          48       48         0         0                   0 │
│ libefuse.a                     1672    64     4     60      0      0         0        1427   1427         181      181         0         0                   0 │
│ libsoc.a                       1540     0     0      0     37     37         0          39     39        1464     1464         0         0                   0 │
│ libstdc++.a                    1502    21    17      4      0      0         0        1282   1282         199      199         0         0                   0 │
│ libesp_ringbuf.a               1121     0     0      0   1024   1024         0           0      0          97       97         0         0                   0 │
│ libmain.a                      1027     8     8      0      0      0         0         964    964          55       55         0         0                   0 │
│ libpthread.a                    678    20    12      8      0      0         0         604    604          54       54         0         0                   0 │
│ libesp_vfs_console.a            599    12    12      0      0      0         0         415    415         172      172         0         0                   0 │
│ libxt_hal.a                     475     0     0      0    443    443         0           0      0          32       32         0         0                   0 │
│ librtc.a                        456     0     0      0    456    456         0           0      0           0        0         0         0                   0 │
│ libcore.a                       331    33    33      0      0      0         0         255    255          43       43         0         0                   0 │
│ libesp_coex.a                   277     0     0      0    118    118         0         159    159           0        0         0         0                   0 │
│ libapp_update.a                 186     4     4      0      0      0         0         152    152          30       30         0         0                   0 │
│ libesp_rom.a                    102     0     0      0    102    102         0           0      0           0        0         0         0                   0 │
│ libgcc.a                         89     0     0      0      0      0         0          89     89           0        0         0         0                   0 │
│ libcxx.a                         52     0     0      0      0      0         0          52     52           0        0         0         0                   0 │
│ libnvs_sec_provider.a             5     0     0      0      0      0         0           5      5           0        0         0         0                   0 │
│ (exe)                             3     0     0      0      3      0         3           0      0           0        0         0         0                   0 │
└─────────────────────────┴────────────┴──────┴──────┴───────┴───────┴───────┴──────────┴────────────┴───────┴────────────┴─────────┴──────────┴──────────┴────────────────────┘

Generally, one static library archive is built per component, although some are binary libraries included by a particular component, for example, libnet80211.a is included by esp_wifi component. There are also toolchain libraries such as libc.a and libgcc.a listed here, these provide Standard C/C++ Library and toolchain built-in functionality.

If the project is simple and only has a main component, then all of the project's code will be shown under libmain.a. If the project includes its own components (see Build System), then they will each be shown on a separate line.

The table is sorted in descending order of the total contribution of the static archive to the binary size. The columns indicate memory types and output sections as detailed in the Size Summary.

Note

The (exe) archive is a special archive that contains object files directly linked into the final binary, meaning they are not part of any archive file.

Note

The size of the .rodata section in the Flash Data memory type may appear very large for a single archive. This occurs due to linker relaxations. The linker may attempt to combine object file sections with MERGE and STRINGS flags from all archives into one to perform tail string optimization. Consequently, one archive may end up with a very large .rodata section, containing string literals from other archives. This is evident in the .rodata section of the libesp_app_format.a archive. The specific compiler behavior here can be turned off by enabling CONFIG_COMPILER_NO_MERGE_CONSTANTS option (only for GCC toolchain), please read help for more details.

Source File Usage Summary idf.py size-files

For even more details, run idf.py size-files to get a summary of the contribution each object file has made to the final binary size. Each object file corresponds to a single source file.

$ idf.py size-files
                                                                            Per-file contributions to ELF file
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Object File                          Total Size  DRAM  .bss  .data  IRAM  .text  .vectors  Flash Code  .text  Flash Data  .rodata  .appdesc  RTC SLOW  .rtc_slow_reserved ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ esp_app_desc.c.obj                        72313    10    10      0     0      0         0         417    417       71886    71630       256         0                   0 │
│ x509_crt_bundle.S.obj                     67810     0     0      0     0      0         0           0      0       67810    67810         0         0                   0 │
│ ecp_curves.c.obj                          36415     0     0      0     0      0         0        6875   6875       29540    29540         0         0                   0 │
│ phy_chip_v7.o                             19384   783   533    250  2186   2186         0       16415  16415           0        0         0         0                   0 │
│ wl_cnx.o                                  18567  3891  3889      2   277    277         0       13343  13343        1056     1056         0         0                   0 │
│ ieee80211_output.o                        15498    27    25      2  2083   2083         0       12840  12840         548      548         0         0                   0 │
│ pp.o                                      14722  1207    53   1154  7286   7286         0        5590   5590         639      639         0         0                   0 │
│ libc_a-vfprintf.o                         14084     0     0      0     0      0         0       13508  13508         576      576         0         0                   0 │
│ phy_chip_v7_cal.o                         13997   229    54    175  4039   4039         0        9729   9729           0        0         0         0                   0 │
│ pm.o                                      13958   532   488     44  3630   3630         0        8823   8823         973      973         0         0                   0 │
│ libc_a-svfprintf.o                        13753     0     0      0     0      0         0       13177  13177         576      576         0         0                   0 │
│ ieee80211_sta.o                           13711    50    38     12  1443   1443         0       11181  11181        1037     1037         0         0                   0 │
│ ieee80211_ioctl.o                         13479   120   116      4   271    271         0       11127  11127        1961     1961         0         0                   0 │
│ ieee80211_scan.o                          12037   327   309     18     0      0         0       11119  11119         591      591         0         0                   0 │
│ ieee80211_hostap.o                        11970    42    41      1     0      0         0       10898  10898        1030     1030         0         0                   0 │
│ nd6.c.obj                                 11815   940   932      8     0      0         0       10764  10764         111      111         0         0                   0 │
│ phy_chip_v7_ana.o                         11039   217    50    167  2697   2697         0        8125   8125           0        0         0         0                   0 │
│ ieee80211_ht.o                            11033     5     4      1  1179   1179         0        8466   8466        1383     1383         0         0                   0 │
│ sae.c.obj                                 11003     0     0      0     0      0         0       10971  10971          32       32         0         0                   0 │
│ tasks.c.obj                               10753   712   696     16  9416   9416         0           0      0         625      625         0         0                   0 │
│ libc_a-svfiprintf.o                       10446     0     0      0     0      0         0        9398   9398        1048     1048         0         0                   0 │
│ libc_a-vfiprintf.o                        10092     0     0      0     0      0         0        9516   9516         576      576         0         0                   0 │
│ wpa.c.obj                                  9688   872   872      0     0      0         0        8816   8816           0        0         0         0                   0 │
│ tcp_in.c.obj                               8904    52    52      0     0      0         0        8698   8698         154      154         0         0                   0 [... additional lines removed ...]

The table is sorted in descending order of the total contribution of the object files to the binary size. The columns indicate memory types and output sections as detailed in the Size Summary.

For example, we can see that the file x509_crt_bundle.S.o contributed 67,810 bytes to the total firmware size, all as .rodata in flash. Therefore we can guess that this application is using the ESP x509 Certificate Bundle feature and not using this feature would save at last this many bytes from the firmware size.

Some of the object files are linked from binary libraries and therefore you will not find a corresponding source file. To locate which component a source file belongs to, it is generally possible to search in the ESP-IDF source tree or look in the Linker Map File for the full path.

Comparing Two Binaries

When making changes that impact binary size, you can use the IDF Size tool to analyze the precise differences in size. The --diff option can be used with all previously mentioned sub-commands, allowing you to specify a path to a project build for comparison with the current project.

For example to compare two hello_world project builds, follow these steps. First, create two copies of the hello_world project directory. Name the first project directory hello_world_Og. This project will use the default CONFIG_COMPILER_OPTIMIZATION compiler optimization setting Debug (-Og) and will serve as the REFERENCE project. Name the second project directory hello_world_Os. This project will use the Optimize for size (-Os) setting, which can be enabled using idf.py menuconfig. This will be the CURRENT project. Build both projects. Then, from within the hello_world_Os project directory, run the following command:

$ idf.py size --diff ../hello_world_Og

 CURRENT   project file: "hello_world_Os/build/hello_world.map"
 REFERENCE project file: "hello_world_Og/build/hello_world.map"
 Difference is counted as CURRENT - REFERENCE, i.e. a positive number means that CURRENT is larger.
                                Memory Type Usage Summary
 ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
  Memory Type/Section  Used [bytes]      Used [%]  Remain [bytes]   Total [bytes]  ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
  Flash Code           74498  -6168   2.23  -0.18  3267806  +6168  3342304      0      .text             74498  -6168   2.23  -0.18                                   IRAM                 45539  -6296  34.74   -4.8    85533  +6296   131072      0      .text             44511  -6296  33.96   -4.8                                   Flash Data           35784  -2440   0.85  -0.06  4158488  +2440  4194272      0      .rodata           35528  -2440   0.85  -0.06                                   DRAM                 10844   -392    6.0  -0.22   169892   +392   180736      0      .data              8612   -376   4.76  -0.21                                      .bss               2232    -16   1.23  -0.01                                  └─────────────────────┴──────────────┴──────────────┴────────────────┴────────────────┘
 Total image size: 164432 -15280 bytes (.bin may be padded larger)

In addition to the previously mentioned Size Summary example, each column now also shows the size differences. Each difference is shown as CURRENT - REFERENCE, meaning the current project sizes minus the sizes in the project specified with the --diff option. In this example, the final binary image of the hello_world_Os project is 15,280 bytes smaller than that of the hello_world_Og project. Additionally, the hello_world_Os project uses 6,168 bytes less in Flash Code memory, leaving 6,168 bytes more available in Flash Code, with no difference in the total available memory.

You can also use the diff mode to generate a table showing the differences at the component level (static library archive):

$ idf.py size-components --diff ../hello_world_Og

Additionally, at the level of each individual source file:

$ idf.py size-files --diff ../hello_world_Og

Showing Size When Linker Fails

If too much static memory is allocated, the linker will fail with an error such as DRAM segment data does not fit, region `iram0_0_seg' overflowed by 44 bytes, or similar.

In these cases, idf.py size will also fail. However, you can run idf_size.py, which is a convenient wrapper that allows you to call esp-idf-size directly from within the ESP-IDF environment and see the partial static memory usage. The idf_size.py script requires a link map file as an argument, which is located in the project's build directory as <projectname>.map.

$ idf_size.py <projectname>.map
warning:  DRAM overflow detected!: output section or its part .dram0.bss(addr: 1073422848, size: 2240) does not fit into any memory region and will be assigned to the preceding dram0_0_seg memory region
warning:  DRAM overflow detected!: output section or its part .dram0.data(addr: 1073414144, size: 8704) does not fit into any memory region and will be assigned to the preceding dram0_0_seg memory region
                            Memory Type Usage Summary
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Memory Type/Section  Used [bytes]  Used [%]  Remain [bytes]  Total [bytes] ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ Flash Code                  79759      2.39         3262545        3342304 │
│    .text                    79759      2.39                                │
│ IRAM                        51106     38.99           79966         131072 │
│    .text                    50079     38.21                                │
│    .vectors                  1027      0.78                                │
│ Flash Data                  38576      0.92         4155696        4194272 │
│    .rodata                  38320      0.91                                │
│    .appdesc                   256      0.01                                │
│ DRAM                        10944         0          -10944              0 │
│    .data_overflow            8704         0                                │
│    .bss_overflow             2240         0                                │
└─────────────────────┴──────────────┴──────────┴────────────────┴───────────────┘
Total image size: 178145 bytes (.bin may be padded larger)

Sections that do not fit into the memory region will have the suffix _overflow.


Was this page helpful?