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

   1 #ifndef _BABELTRACE_BIN_INFO_H
   2 #define _BABELTRACE_BIN_INFO_H
   3
   4 /*
   5  * Babeltrace - Executable and Shared Object Debug Info Reader
   6  *
   7  * Copyright 2015 Antoine Busque <abusque@efficios.com>
   8  *
   9  * Author: Antoine Busque <abusque@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  */
  29
  30 #include <stdint.h>
  31 #include <stdbool.h>
  32 #include <gelf.h>
  33 #include <elfutils/libdw.h>
  34 #include <babeltrace/babeltrace-internal.h>
  35 #include <babeltrace/fd-cache-internal.h>
  36
  37 #define DEFAULT_DEBUG_DIR "/usr/lib/debug"
  38 #define DEBUG_SUBDIR ".debug/"
  39 #define BUILD_ID_SUBDIR ".build-id/"
  40 #define BUILD_ID_SUFFIX ".debug"
  41
  42 struct bin_info {
  43         /* Base virtual memory address. */
  44         uint64_t low_addr;
  45         /* Upper bound of exec address space. */
  46         uint64_t high_addr;
  47         /* Size of exec address space. */
  48         uint64_t memsz;
  49         /* Paths to ELF and DWARF files. */
  50         gchar *elf_path;
  51         gchar *dwarf_path;
  52         /* libelf and libdw objects representing the files. */
  53         Elf *elf_file;
  54         Dwarf *dwarf_info;
  55         /* Optional build ID info. */
  56         uint8_t *build_id;
  57         size_t build_id_len;
  58
  59         /* Optional debug link info. */
  60         gchar *dbg_link_filename;
  61         uint32_t dbg_link_crc;
  62         /* fd cache handles to ELF and DWARF files. */
  63         struct bt_fd_cache_handle *elf_handle;
  64         struct bt_fd_cache_handle *dwarf_handle;
  65         /* Configuration. */
  66         gchar *debug_info_dir;
  67         /* Denotes whether the executable is position independent code. */
  68         bool is_pic:1;
  69         /*
  70          * Endianness of the binary file. (may differ from system endianness).
  71          * Two possible values are ELFDATA2MSB and ELFDATA2LSB.
  72          */
  73         uint8_t endianness;
  74         /* Denotes whether the build id in the trace matches to one on disk. */
  75         bool file_build_id_matches:1;
  76         /*
  77          * Denotes whether the executable only has ELF symbols and no
  78          * DWARF info.
  79          */
  80         bool is_elf_only:1;
  81         /* Weak ref. Owned by the iterator. */
  82         struct bt_fd_cache *fd_cache;
  83 };
  84
  85 struct source_location {
  86         uint64_t line_no;
  87         gchar *filename;
  88 };
  89
  90 /**
  91  * Initializes the bin_info framework. Call this before calling
  92  * anything else.
  93  *
  94  * @returns             0 on success, -1 on failure
  95  */
  96 BT_HIDDEN
  97 int bin_info_init(void);
  98
  99 /**
 100  * Instantiate a structure representing an ELF executable, possibly
 101  * with DWARF info, located at the given path.
 102  *
 103  * @param path          Path to the ELF file
 104  * @param low_addr      Base address of the executable
 105  * @param memsz In-memory size of the executable
 106  * @param is_pic        Whether the executable is position independent
 107  *                      code (PIC)
 108  * @param debug_info_dir Directory containing debug info or NULL.
 109  * @param target_prefix  Path to the root file system of the target
 110  *                       or NULL.
 111  * @returns             Pointer to the new bin_info on success,
 112  *                      NULL on failure.
 113  */
 114 BT_HIDDEN
 115 struct bin_info *bin_info_create(struct bt_fd_cache *fdc, const char *path,
 116                 uint64_t low_addr, uint64_t memsz, bool is_pic,
 117                 const char *debug_info_dir, const char *target_prefix);
 118
 119 /**
 120  * Destroy the given bin_info instance
 121  *
 122  * @param bin   bin_info instance to destroy
 123  */
 124 BT_HIDDEN
 125 void bin_info_destroy(struct bin_info *bin);
 126
 127 /**
 128  * Sets the build ID information for a given bin_info instance.
 129  *
 130  * @param bin           The bin_info instance for which to set
 131  *                      the build ID
 132  * @param build_id      Array of bytes containing the actual ID
 133  * @param build_id_len  Length in bytes of the build_id
 134  * @returns             0 on success, -1 on failure
 135  */
 136 BT_HIDDEN
 137 int bin_info_set_build_id(struct bin_info *bin, uint8_t *build_id,
 138                 size_t build_id_len);
 139
 140 /**
 141  * Sets the debug link information for a given bin_info instance.
 142  *
 143  * @param bin           The bin_info instance for which to set
 144  *                      the debug link
 145  * @param filename      Name of the separate debug info file
 146  * @param crc           Checksum for the debug info file
 147  * @returns             0 on success, -1 on failure
 148  */
 149 BT_HIDDEN
 150 int bin_info_set_debug_link(struct bin_info *bin, const char *filename,
 151                 uint32_t crc);
 152
 153 /**
 154  * Returns whether or not the given bin info \p bin contains the
 155  * address \p addr.
 156  *
 157  * @param bin           bin_info instance
 158  * @param addr          Address to lookup
 159  * @returns             1 if \p bin contains \p addr, 0 if it does not,
 160  *                      -1 on failure
 161  */
 162 static inline
 163 int bin_info_has_address(struct bin_info *bin, uint64_t addr)
 164 {
 165         if (!bin) {
 166                 return -1;
 167         }
 168
 169         return addr >= bin->low_addr && addr < bin->high_addr;
 170 }
 171
 172 /**
 173  * Get the name of the function containing a given address within an
 174  * executable.
 175  *
 176  * If no DWARF info is available, the function falls back to ELF
 177  * symbols and the "function name" is in fact the name of the closest
 178  * symbol, followed by the offset between the symbol and the address.
 179  *
 180  * On success, if found, the out parameter `func_name` is set. The ownership
 181  * of `func_name` is passed to the caller. On failure, `func_name` remains
 182  * unchanged.
 183  *
 184  * @param bin           bin_info instance for the executable containing
 185  *                      the address
 186  * @param addr          Virtual memory address for which to find the
 187  *                      function name
 188  * @param func_name     Out parameter, the function name.
 189  * @returns             0 on success, -1 on failure
 190  */
 191 BT_HIDDEN
 192 int bin_info_lookup_function_name(struct bin_info *bin, uint64_t addr,
 193                 char **func_name);
 194
 195 /**
 196  * Get the source location (file name and line number) for a given
 197  * address within an executable.
 198  *
 199  * If no DWARF info is available, the source location cannot be found
 200  * and the function will return unsuccessfully.
 201  *
 202  * On success, if found, the out parameter `src_loc` is set. The ownership
 203  * of `src_loc` is passed to the caller. On failure, `src_loc` remains
 204  * unchanged.
 205  *
 206  * @param bin           bin_info instance for the executable containing
 207  *                      the address
 208  * @param addr          Virtual memory address for which to find the
 209  *                      source location
 210  * @param src_loc       Out parameter, the source location
 211  * @returns             0 on success, -1 on failure
 212  */
 213 BT_HIDDEN
 214 int bin_info_lookup_source_location(struct bin_info *bin, uint64_t addr,
 215                 struct source_location **src_loc);
 216 /**
 217  * Get a string representing the location within the binary of a given
 218  * address.
 219  *
 220  * In the  case of a PIC binary, the location is relative (+0x1234).
 221  * For a non-PIC binary, the location is absolute (@0x1234)
 222  *
 223  * On success, the out parameter `bin_loc` is set. The ownership is
 224  * passed to the caller. On failure, `bin_loc` remains unchanged.
 225  *
 226  * @param bin           bin_info instance for the executable containing
 227  *                      the address
 228  * @param addr          Virtual memory address for which to find the
 229  *                      binary location
 230  * @param bin_loc       Out parameter, the binary location
 231  * @returns             0 on success, -1 on failure
 232  */
 233 BT_HIDDEN
 234 int bin_info_get_bin_loc(struct bin_info *bin, uint64_t addr, char **bin_loc);
 235
 236 /**
 237  * Destroy the given source_location instance
 238  *
 239  * @param src_loc       source_location instance to destroy
 240  */
 241 BT_HIDDEN
 242 void source_location_destroy(struct source_location *src_loc);
 243
 244 #endif  /* _BABELTRACE_BIN_INFO_H */