# Symbol Files & Build Ids

## Introduction​

In order to process uploaded data, such as coredumps, Memfault needs to be able to find the Symbol File (ELF) that corresponds to the software that produced the uploaded data. Without an exact match, Memfault will not be able to decode the uploaded data.

To that end, the SDK adds metadata to the uploaded data to identify the software that produced the data. Likewise, any Symbol File that is uploaded to Memfault, must have that same identifying metadata.

## Identifier Types​

There are 3 types of identifiers:

Memfault Build IdGNU Build IdSoftware Type & Version
Examplea1e688...a1e688...wifi-fw/1.0.0
Automatically generated hash
Manually chosen
Compiler requirementGNU/gcc
ID embedded inside ELF
ID passed manually upon Symbol File upload
Requires running Python script to post-process ELF
Minimum SDK version0.20.00.20.0

We recommend using either the Memfault Build Id or GNU Build Id option. The Build Ids are automatically generated based on the contents of the ELF file.

Software Type & Version identifiers are manually assigned and therefore error-prone.

tip

When uploading a Symbol File (ELF) that has a Build Id embedded, it is possible to add a Software Type & Version based identifier, in addition to the embedded Build Id. This will link the Symbol File with the Software Version. That way, you can later look up and download the Symbol File by Software Version through the Software Versions UI in Memfault.

Note that for the purpose of finding a Symbol File to match uploaded data, the Build Id always takes precedence over Software Type & Version.

note

In order to use Build Ids for identification of Symbol Files & uploaded data, SDK version 0.20.0 or newer is required.

Memfault has two ways to add a Build ID to a target. Select the appropriate one below based on your toolchain setup.

GNU Build ID (Requires Use of GNU GCC Compiler)
1. Add -Wl,--build-id to flags passed to linker via GCC
2. Add #define MEMFAULT_USE_GNU_BUILD_ID 1 to third_party/memfault/memfault_platform_config.h
3. Add the following snippet to your projects linker script (.ld file) where "FLASH" below will match the name of the MEMORY section read-only data and text is placed in.
    .note.gnu.build-id :    {        __start_gnu_build_id_start = .;        KEEP(*(.note.gnu.build-id))    } > <YOUR_FLASH_SECTION>
info

Be sure to update \<YOUR_FLASH_SECTION\> to match the name of the section .text is placed in!

The .note.gnu.build-id output section name is used to locate the build id when the symbol file is uploaded. The __start_gnu_build_id_start identifier is used at compile time by the SDK for populating the build id.

IAR EWARM Python Script Run on ELF in Post-Build Action
1. install python (eg python3.9 from the Microsoft app store)

2. install the pyelftools python package by:

1. open git bash or cmd.exe
2. python3.9.exe -m pip install pyelftools==0.27
3. then add the appropriate post-build action, for example:

# double check the path to the fw_build_id.py scriptpython3.9.exe $PROJ_DIR$/third-party/memfault-firmware-sdk/scripts/fw_build_id.py $TARGET_PATH$

Python Script Run on ELF (Compiler Agnostic)

Update your build system to invoke the scripts/fw_build_id.py script on your ELF as part of a post-build step.

For example, using CMake, this can be achieved by adding a custom command to the target:

add_custom_command(TARGET ${YOUR_EXECUTABLE_NAME} POST_BUILD COMMAND python${MEMFAULT_SDK_ROOT}/scripts/fw_build_id.py ${YOUR_EXECUTABLE_NAME}) info The script depends on pyelftools so make sure you have run pip install pyelftools or added to your requirements.txt ## Uploading Symbol Files using Memfault CLI​ Please follow the instructions to install the Memfault CLI tool first. ### Uploading Symbol File with Build Id​ Because the Build Id is embedded inside the ELF file, the Build Id is automatically recognized and extracted and does not need to be passed as an argument to the memfault tool: memfault --org-token$ORG_TOKEN --org acme-inc --project smart-sink \  upload-mcu-symbols \  build/symbols.elf
note

Using link-time optimization (-flto) can cause the symbol upload to fail:

ERROR: main-with-lto.elf: Build Id missing. Specify --software-version and--software-type options or add a Build Id (see https://mflt.io/symbol-file-build-ids)Usage: memfault upload-mcu-symbols [OPTIONS] PATHError: Upload failed!

-flto can inline the contents of the build id variable, removing the symbol from the executable. To work around this, add this flag to the linker args:

-Wl,--require-defined=g_memfault_build_id

To associate a Software Type & Software Version with a Symbol File, the --software-type and --software-version arguments need to be passed to the memfault tool.
Optionally, a --revision (Git commit hash, SVN revision, etc) can be passed as well to store the version control revision in the newly created Software Version.
memfault --org-token \$ORG_TOKEN --org acme-inc --project smart-sink \  upload-mcu-symbols \  --software-type stm32-fw \  --software-version 1.0.0-alpha \  --revision 89335ffade90ff7697e2ce5238bd4c68978b6d6e \  build/symbols.elf`