include/babeltrace/so-info.h

   1 #ifndef _BABELTRACE_SO_INFO_H
   2 #define _BABELTRACE_SO_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
  36 #define DEFAULT_DEBUG_DIR "/usr/lib/debug"
  37 #define DEBUG_SUBDIR ".debug/"
  38 #define BUILD_ID_SUBDIR ".build-id/"
  39 #define BUILD_ID_SUFFIX ".debug"
  40
  41 struct so_info {
  42         /* Base virtual memory address. */
  43         uint64_t low_addr;
  44         /* Upper bound of exec address space. */
  45         uint64_t high_addr;
  46         /* Size of exec address space. */
  47         uint64_t memsz;
  48         /* Paths to ELF and DWARF files. */
  49         char *elf_path;
  50         char *dwarf_path;
  51         /* libelf and libdw objects representing the files. */
  52         Elf *elf_file;
  53         Dwarf *dwarf_info;
  54         /* Optional build ID info. */
  55         uint8_t *build_id;
  56         size_t build_id_len;
  57         /* Optional debug link info. */
  58         char *dbg_link_filename;
  59         uint32_t dbg_link_crc;
  60         /* FDs to ELF and DWARF files. */
  61         int elf_fd;
  62         int dwarf_fd;
  63         /* Denotes whether the executable is position independent code. */
  64         bool is_pic:1;
  65         /* Denotes whether the SO only has ELF symbols and no DWARF info. */
  66         bool is_elf_only:1;
  67 };
  68
  69 struct source_location {
  70         uint64_t line_no;
  71         char *filename;
  72 };
  73
  74 /**
  75  * Initializes the so_info framework. Call this before calling
  76  * anything else.
  77  *
  78  * @returns             0 on success, -1 on failure
  79  */
  80 BT_HIDDEN
  81 int so_info_init(void);
  82
  83 /**
  84  * Instantiate a structure representing an ELF executable, possibly
  85  * with DWARF info, located at the given path.
  86  *
  87  * @param path          Path to the ELF file
  88  * @param low_addr      Base address of the executable
  89  * @param memsz In-memory size of the executable
  90  * @param is_pic        Whether the executable is position independent
  91  *                      code (PIC)
  92  * @returns             Pointer to the new so_info on success,
  93  *                      NULL on failure.
  94  */
  95 BT_HIDDEN
  96 struct so_info *so_info_create(const char *path, uint64_t low_addr,
  97                 uint64_t memsz, bool is_pic);
  98
  99 /**
 100  * Destroy the given so_info instance
 101  *
 102  * @param so    so_info instance to destroy
 103  */
 104 BT_HIDDEN
 105 void so_info_destroy(struct so_info *so);
 106
 107 /**
 108  * Sets the build ID information for a given so_info instance.
 109  *
 110  * @param so            The so_info instance for which to set
 111  *                      the build ID
 112  * @param build_id      Array of bytes containing the actual ID
 113  * @param build_id_len  Length in bytes of the build_id
 114  * @returns             0 on success, -1 on failure
 115  */
 116 BT_HIDDEN
 117 int so_info_set_build_id(struct so_info *so, uint8_t *build_id,
 118                 size_t build_id_len);
 119
 120 /**
 121  * Sets the debug link information for a given so_info instance.
 122  *
 123  * @param so            The so_info instance for which to set
 124  *                      the debug link
 125  * @param filename      Name of the separate debug info file
 126  * @param crc           Checksum for the debug info file
 127  * @returns             0 on success, -1 on failure
 128  */
 129 BT_HIDDEN
 130 int so_info_set_debug_link(struct so_info *so, char *filename, uint32_t crc);
 131
 132 /**
 133  * Returns whether or not the given SO info \p so contains the address
 134  * \p addr.
 135  *
 136  * @param so            so_info instance
 137  * @param addr          Address to lookup
 138  * @returns             1 if \p so contains \p addr, 0 if it does not,
 139  *                      -1 on failure
 140  */
 141 static inline
 142 int so_info_has_address(struct so_info *so, uint64_t addr)
 143 {
 144         if (!so) {
 145                 return -1;
 146         }
 147
 148         return addr >= so->low_addr && addr < so->high_addr;
 149 }
 150
 151 /**
 152  * Get the name of the function containing a given address within an
 153  * executable.
 154  *
 155  * If no DWARF info is available, the function falls back to ELF
 156  * symbols and the "function name" is in fact the name of the closest
 157  * symbol, followed by the offset between the symbol and the address.
 158  *
 159  * On success, if found, the out parameter `func_name` is set. The ownership
 160  * of `func_name` is passed to the caller. On failure, `func_name` remains
 161  * unchanged.
 162  *
 163  * @param so            so_info instance for the executable containing
 164  *                      the address
 165  * @param addr          Virtual memory address for which to find the
 166  *                      function name
 167  * @param func_name     Out parameter, the function name.
 168  * @returns             0 on success, -1 on failure
 169  */
 170 BT_HIDDEN
 171 int so_info_lookup_function_name(struct so_info *so, uint64_t addr,
 172                 char **func_name);
 173
 174 /**
 175  * Get the source location (file name and line number) for a given
 176  * address within an executable.
 177  *
 178  * If no DWARF info is available, the source location cannot be found
 179  * and the function will return unsuccesfully.
 180  *
 181  * On success, if found, the out parameter `src_loc` is set. The ownership
 182  * of `src_loc` is passed to the caller. On failure, `src_loc` remains
 183  * unchanged.
 184  *
 185  * @param so            so_info instance for the executable containing
 186  *                      the address
 187  * @param addr          Virtual memory address for which to find the
 188  *                      source location
 189  * @param src_loc       Out parameter, the source location
 190  * @returns             0 on success, -1 on failure
 191  */
 192 BT_HIDDEN
 193 int so_info_lookup_source_location(struct so_info *so, uint64_t addr,
 194                 struct source_location **src_loc);
 195
 196 /**
 197  * Destroy the given source_location instance
 198  *
 199  * @param src_loc       source_location instance to destroy
 200  */
 201 BT_HIDDEN
 202 void source_location_destroy(struct source_location *src_loc);
 203
 204 #endif  /* _BABELTRACE_SO_INFO_H */