build_info.h

#pragma once

//! @file
//!
//! Copyright (c) Memfault, Inc.
//! See License.txt for details
//!
//! @brief
//! The Memfault SDK can automatically track information about the build it was compiled into, such
//! as a unique "build id" for your firmware project binary.
//!
//! There are two ways a unique "build id" can be generated and tracked by the SDK. The modes
//! are controlled by setting the MEMFAULT_USE_GNU_BUILD_ID CFLAG to either 0 or 1, where:
//!
//! Memfault Generated Build ID (MEMFAULT_USE_GNU_BUILD_ID=0)
//!
//!  This is the _default_ option and works with any compiler (GCC, IAR, ARM MDK, etc). For this
//!  configuration, a unique "build id" can be patched into the ELF file generated by your build
//!  by running the following as a post-compilation step:
//!    python $MEMFAULT_FIRMWARE_SDK/scripts/fw_build_id.py <path to elf file (ends in .axf, .elf, .out)>
//!
//!  Running this script is not required but if it if not run Memfault will be unable to to track a
//!  unique "build id" for your binary.
//!
//! GNU Build ID  (MEMFAULT_USE_GNU_BUILD_ID=1)
//!
//!  This mode makes use of the GNU Build ID generated by the GNU linker (https://mflt.io/gnu-build-id).
//!  If you are compiling with GCC, we _recommend_ using this mode. To do this, you will need to make
//!  the following two changes:
//!
//!   1. Pass the "--build-id" argument to GNU LD.
//!      ("-Wl,--build-id" when invoking the linker via GCC)
//!
//!   2. Add the -DMEMFAULT_USE_GNU_BUILD_ID=1 CFLAG to your CC invocation
//!
//!   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))
//!     } > FLASH

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define MEMFAULT_BUILD_ID_LEN 20

typedef struct {
  // A unique build identifier for the current binary
  uint8_t build_id[MEMFAULT_BUILD_ID_LEN];
} sMemfaultBuildInfo;

//! Returns build info tracked by the Memfault SDK
//!
//! @param[out] info When available, populated with information about the current build
//!
//! @return true if a unique id was found and populated in info or false otherwise
bool memfault_build_info_read(sMemfaultBuildInfo *info);


//! Copies the build id as a hex string into the buffer provided
//!
//! @param[out] out_buf The buffer to copy the build id into
//!
//! @param buf_len The length of the buffer. This routine will copy up to buf_len - 1 bytes of the
//! build id. For example, to copy only the first 5 hex characters of a build id, the buffer only
//! needs to be 6 bytes long.
bool memfault_build_id_get_string(char *out_buf, size_t buf_len);

//! Dump version info tracked by Memfault to the console using an MEMFAULT_LOG_INFO()
//!
//! You will see something like one of the following printed
//! depending on the configuration in use:
//!   No Build ID available
//!   Memfault Build ID: 000102030405060708090a0b0c0d0e0f10111213
//!   GNU Build ID: 58faeeb01696afbfb4f790c63b77c80f89972989
void memfault_build_info_dump(void);

#ifdef __cplusplus
}
#endif