src/plugins/lttng-utils/debug-info/bin-info.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright 2015 Antoine Busque <abusque@efficios.com>
   5  *
   6  * Babeltrace - Executable and Shared Object Debug Info Reader
   7  */
   8
   9 #ifndef _BABELTRACE_BIN_INFO_H
  10 #define _BABELTRACE_BIN_INFO_H
  11
  12 #include <babeltrace2/babeltrace.h>
  13 #include <stdint.h>
  14 #include <stdbool.h>
  15 #include <gelf.h>
  16 #include <elfutils/libdw.h>
  17 #include "common/macros.h"
  18 #include "fd-cache/fd-cache.h"
  19
  20 #define DEFAULT_DEBUG_DIR "/usr/lib/debug"
  21 #define DEBUG_SUBDIR ".debug"
  22 #define BUILD_ID_SUBDIR ".build-id"
  23 #define BUILD_ID_SUFFIX ".debug"
  24 #define BUILD_ID_PREFIX_DIR_LEN 2
  25
  26 struct bin_info {
  27         bt_logging_level log_level;
  28
  29         /* Used for logging; can be `NULL` */
  30         bt_self_component *self_comp;
  31
  32         /* Base virtual memory address. */
  33         uint64_t low_addr;
  34         /* Upper bound of exec address space. */
  35         uint64_t high_addr;
  36         /* Size of exec address space. */
  37         uint64_t memsz;
  38         /* Paths to ELF and DWARF files. */
  39         gchar *elf_path;
  40         gchar *dwarf_path;
  41         /* libelf and libdw objects representing the files. */
  42         Elf *elf_file;
  43         Dwarf *dwarf_info;
  44         /* Optional build ID info. */
  45         uint8_t *build_id;
  46         size_t build_id_len;
  47
  48         /* Optional debug link info. */
  49         gchar *dbg_link_filename;
  50         uint32_t dbg_link_crc;
  51         /* fd cache handles to ELF and DWARF files. */
  52         struct bt_fd_cache_handle *elf_handle;
  53         struct bt_fd_cache_handle *dwarf_handle;
  54         /* Configuration. */
  55         gchar *debug_info_dir;
  56         /* Denotes whether the executable is position independent code. */
  57         bool is_pic:1;
  58         /* Denotes whether the build id in the trace matches to one on disk. */
  59         bool file_build_id_matches:1;
  60         /*
  61          * Denotes whether the executable only has ELF symbols and no
  62          * DWARF info.
  63          */
  64         bool is_elf_only:1;
  65         /* Weak ref. Owned by the iterator. */
  66         struct bt_fd_cache *fd_cache;
  67 };
  68
  69 struct source_location {
  70         uint64_t line_no;
  71         gchar *filename;
  72 };
  73
  74 /**
  75  * Initializes the bin_info framework. Call this before calling
  76  * anything else.
  77  *
  78  * @returns             0 on success, -1 on failure
  79  */
  80 BT_HIDDEN
  81 int bin_info_init(bt_logging_level log_level,
  82                 bt_self_component *self_comp);
  83
  84 /**
  85  * Instantiate a structure representing an ELF executable, possibly
  86  * with DWARF info, located at the given path.
  87  *
  88  * @param path          Path to the ELF file
  89  * @param low_addr      Base address of the executable
  90  * @param memsz In-memory size of the executable
  91  * @param is_pic        Whether the executable is position independent
  92  *                      code (PIC)
  93  * @param debug_info_dir Directory containing debug info or NULL.
  94  * @param target_prefix  Path to the root file system of the target
  95  *                       or NULL.
  96  * @returns             Pointer to the new bin_info on success,
  97  *                      NULL on failure.
  98  */
  99 BT_HIDDEN
 100 struct bin_info *bin_info_create(struct bt_fd_cache *fdc, const char *path,
 101                 uint64_t low_addr, uint64_t memsz, bool is_pic,
 102                 const char *debug_info_dir, const char *target_prefix,
 103                 bt_logging_level log_level, bt_self_component *self_comp);
 104
 105 /**
 106  * Destroy the given bin_info instance
 107  *
 108  * @param bin   bin_info instance to destroy
 109  */
 110 BT_HIDDEN
 111 void bin_info_destroy(struct bin_info *bin);
 112
 113 /**
 114  * Sets the build ID information for a given bin_info instance.
 115  *
 116  * @param bin           The bin_info instance for which to set
 117  *                      the build ID
 118  * @param build_id      Array of bytes containing the actual ID
 119  * @param build_id_len  Length in bytes of the build_id
 120  * @returns             0 on success, -1 on failure
 121  */
 122 BT_HIDDEN
 123 int bin_info_set_build_id(struct bin_info *bin, uint8_t *build_id,
 124                 size_t build_id_len);
 125
 126 /**
 127  * Sets the debug link information for a given bin_info instance.
 128  *
 129  * @param bin           The bin_info instance for which to set
 130  *                      the debug link
 131  * @param filename      Name of the separate debug info file
 132  * @param crc           Checksum for the debug info file
 133  * @returns             0 on success, -1 on failure
 134  */
 135 BT_HIDDEN
 136 int bin_info_set_debug_link(struct bin_info *bin, const char *filename,
 137                 uint32_t crc);
 138
 139 /**
 140  * Returns whether or not the given bin info \p bin contains the
 141  * address \p addr.
 142  *
 143  * @param bin           bin_info instance
 144  * @param addr          Address to lookup
 145  * @returns             1 if \p bin contains \p addr, 0 if it does not,
 146  *                      -1 on failure
 147  */
 148 static inline
 149 int bin_info_has_address(struct bin_info *bin, uint64_t addr)
 150 {
 151         if (!bin) {
 152                 return -1;
 153         }
 154
 155         return addr >= bin->low_addr && addr < bin->high_addr;
 156 }
 157
 158 /**
 159  * Get the name of the function containing a given address within an
 160  * executable.
 161  *
 162  * If no DWARF info is available, the function falls back to ELF
 163  * symbols and the "function name" is in fact the name of the closest
 164  * symbol, followed by the offset between the symbol and the address.
 165  *
 166  * On success, if found, the out parameter `func_name` is set. The ownership
 167  * of `func_name` is passed to the caller. On failure, `func_name` remains
 168  * unchanged.
 169  *
 170  * @param bin           bin_info instance for the executable containing
 171  *                      the address
 172  * @param addr          Virtual memory address for which to find the
 173  *                      function name
 174  * @param func_name     Out parameter, the function name.
 175  * @returns             0 on success, -1 on failure
 176  */
 177 BT_HIDDEN
 178 int bin_info_lookup_function_name(struct bin_info *bin, uint64_t addr,
 179                 char **func_name);
 180
 181 /**
 182  * Get the source location (file name and line number) for a given
 183  * address within an executable.
 184  *
 185  * If no DWARF info is available, the source location cannot be found
 186  * and the function will return unsuccessfully.
 187  *
 188  * On success, if found, the out parameter `src_loc` is set. The ownership
 189  * of `src_loc` is passed to the caller. On failure, `src_loc` remains
 190  * unchanged.
 191  *
 192  * @param bin           bin_info instance for the executable containing
 193  *                      the address
 194  * @param addr          Virtual memory address for which to find the
 195  *                      source location
 196  * @param src_loc       Out parameter, the source location
 197  * @returns             0 on success, -1 on failure
 198  */
 199 BT_HIDDEN
 200 int bin_info_lookup_source_location(struct bin_info *bin, uint64_t addr,
 201                 struct source_location **src_loc);
 202 /**
 203  * Get a string representing the location within the binary of a given
 204  * address.
 205  *
 206  * In the  case of a PIC binary, the location is relative (+0x1234).
 207  * For a non-PIC binary, the location is absolute (@0x1234)
 208  *
 209  * On success, the out parameter `bin_loc` is set. The ownership is
 210  * passed to the caller. On failure, `bin_loc` remains unchanged.
 211  *
 212  * @param bin           bin_info instance for the executable containing
 213  *                      the address
 214  * @param addr          Virtual memory address for which to find the
 215  *                      binary location
 216  * @param bin_loc       Out parameter, the binary location
 217  * @returns             0 on success, -1 on failure
 218  */
 219 BT_HIDDEN
 220 int bin_info_get_bin_loc(struct bin_info *bin, uint64_t addr, char **bin_loc);
 221
 222 /**
 223  * Destroy the given source_location instance
 224  *
 225  * @param src_loc       source_location instance to destroy
 226  */
 227 BT_HIDDEN
 228 void source_location_destroy(struct source_location *src_loc);
 229
 230 #endif  /* _BABELTRACE_BIN_INFO_H */