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