Debian Codegraph @

libdrgn/debug_info.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * Debugging information handling.
8 *
9 * See @ref DebugInfo.
10 */
11
12 #ifndef DRGN_DEBUG_INFO_H
13 #define DRGN_DEBUG_INFO_H
14
15 #if WITH_DEBUGINFOD
16 #include <elfutils/debuginfod.h>
17 #endif
18 #include <elfutils/libdw.h>
19 #include <libelf.h>
20
21 #include "binary_search_tree.h"
22 #include "cfi.h"
23 #include "debug_info_options.h"
24 #include "drgn_internal.h"
25 #include "dwarf_info.h"
26 #include "elf_symtab.h"
27 #include "hash_table.h"
28 #include "object.h"
29 #include "orc_info.h"
30 #include "string_builder.h"
31 #include "symbol.h"
32 #include "type.h"
33 #include "vector.h"
34
35 struct drgn_elf_file;
36
37 /**
38 * @ingroup Internals
39 *
40 * @defgroup DebugInfo Debugging information
41 *
42 * Caching of debugging information.
43 *
44 * @ref drgn_debug_info caches debugging information (currently DWARF and ORC).
45 * It translates the debugging information to types and objects.
46 *
47 * @{
48 */
49
50 #if WITH_DEBUGINFOD
51 #if ENABLE_DLOPEN_DEBUGINFOD
52 bool drgn_have_debuginfod(void);
53 #else
54 static inline bool drgn_have_debuginfod(void)
55 {
56 return true;
57 }
58 #endif
59 #else
60 static inline bool drgn_have_debuginfod(void)
61 {
62 return false;
63 }
64 #endif
65
66 DEFINE_HASH_TABLE_TYPE(drgn_elf_file_dwarf_table, struct drgn_elf_file *);
67 DEFINE_HASH_TABLE_TYPE(drgn_module_table, struct drgn_module *);
68 DEFINE_BINARY_SEARCH_TREE_TYPE(drgn_module_address_tree,
69 struct drgn_module_address_range);
70
71 struct drgn_debug_info_finder {
72 struct drgn_handler handler;
73 struct drgn_debug_info_finder_ops ops;
74 void *arg;
75 };
76
77 /** Cache of debugging information. */
78 struct drgn_debug_info {
79 /** Program owning this cache. */
80 struct drgn_program *prog;
81
82 struct drgn_type_finder type_finder;
83 struct drgn_object_finder object_finder;
84 struct drgn_symbol_finder symbol_finder;
85
86 /** Main module. @c NULL if not created yet. */
87 struct drgn_module *main_module;
88 /**
89 * Table of all modules indexed by name.
90 *
91 * Modules with the same name (which should be rare) are on a
92 * singly-linked list (@ref drgn_module::next_same_name).
93 */
94 struct drgn_module_table modules;
95 /**
96 * Counter used to detect when @ref modules is modified during iteration
97 * of a @ref drgn_created_module_iterator.
98 */
99 uint64_t modules_generation;
100 /** Tree of modules sorted by start address. */
101 struct drgn_module_address_tree modules_by_address;
102 /**
103 * Singly-linked list of modules that need to have their DWARF
104 * information indexed.
105 */
106 struct drgn_module *modules_pending_indexing;
107 /** DWARF debugging information. */
108 struct drgn_dwarf_info dwarf;
109
110 struct drgn_handler_list debug_info_finders;
111 struct drgn_debug_info_finder standard_debug_info_finder;
112 struct drgn_debug_info_options options;
113 /**
114 * Counter used to detect when loading debugging information is
115 * attempted.
116 *
117 * @sa drgn_module::load_debug_info_generation
118 */
119 uint64_t load_debug_info_generation;
120 /**
121 * Counter used to detect when the wanted supplementary file for a
122 * module has changed.
123 *
124 * @sa drgn_module_wanted_supplementary_file::generation
125 */
126 uint64_t supplementary_file_generation;
127
128 #if WITH_DEBUGINFOD
129 struct drgn_debug_info_finder debuginfod_debug_info_finder;
130 /** debuginfod-client session. */
131 debuginfod_client *debuginfod_client;
132 const char *debuginfod_current_name;
133 const char *debuginfod_current_type;
134 unsigned int debuginfod_spinner_position;
135 bool debuginfod_have_url;
136 bool logged_debuginfod_progress;
137 #endif
138 bool logged_no_debuginfod;
139
140 /**
141 * Cache of entries in /proc/$pid/map_files used for finding loaded
142 * files. Populated the first time we need it or opportunistically when
143 * we parse /proc/$pid/maps. Rebuilt whenever we try to open an entry
144 * that no longer exists.
145 */
146 struct drgn_map_files_segment *map_files_segments;
147 /** Number of segments in @ref map_files_segments. */
148 size_t num_map_files_segments;
149 };
150
151 /** Initialize a @ref drgn_debug_info. */
152 void drgn_debug_info_init(struct drgn_debug_info *dbinfo,
153 struct drgn_program *prog);
154
155 /** Deinitialize a @ref drgn_debug_info. */
156 void drgn_debug_info_deinit(struct drgn_debug_info *dbinfo);
157
158 typedef void drgn_module_iterator_destroy_fn(struct drgn_module_iterator *);
159 typedef struct drgn_error *
160 drgn_module_iterator_next_fn(struct drgn_module_iterator *,
161 struct drgn_module **, bool *);
162
163 struct drgn_module_iterator {
164 struct drgn_program *prog;
165 drgn_module_iterator_destroy_fn *destroy;
166 drgn_module_iterator_next_fn *next;
167 bool for_load_debug_info;
168 };
169
170 static inline void
171 drgn_module_iterator_init(struct drgn_module_iterator *it,
172 struct drgn_program *prog,
173 drgn_module_iterator_destroy_fn *destroy,
174 drgn_module_iterator_next_fn *next)
175 {
176 it->prog = prog;
177 it->destroy = destroy;
178 it->next = next;
179 it->for_load_debug_info = false;
180 }
181
182 /** Bitmask of files in a @ref drgn_module. */
183 enum drgn_module_file_mask {
184 DRGN_MODULE_FILE_MASK_LOADED = 1 << 0,
185 DRGN_MODULE_FILE_MASK_DEBUG = 1 << 1,
186 } __attribute__((__packed__));
187
188 DEFINE_HASH_MAP_TYPE(drgn_module_section_address_map, char *, uint64_t);
189
190 struct drgn_module_address_range {
191 /** Node in @ref drgn_debug_info::modules_by_address. */
192 struct binary_tree_node node;
193 /** Address range. */
194 uint64_t start, end;
195 /** Module owning this range. */
196 struct drgn_module *module;
197 };
198
199 struct drgn_module {
200 struct drgn_program *prog;
201 enum drgn_module_kind kind;
202
203 /** Module name. */
204 char *name;
205 /** Kind-specific info. */
206 uint64_t info;
207
208 /** Next module with the same name in @ref drgn_debug_info::modules. */
209 struct drgn_module *next_same_name;
210
211 /**
212 * Raw binary build ID. @c NULL if the module does not have a build ID.
213 */
214 void *build_id;
215 /**
216 * Length of @ref drgn_module::build_id in bytes. Zero if the module
217 * does not have a build ID.
218 */
219 size_t build_id_len;
220 /**
221 * Build ID as a null-terminated hexadecimal string. @c NULL if the
222 * module does not have a build ID.
223 *
224 * Used for logging and finding debugging information.
225 *
226 * This is allocated together with @ref drgn_module::build_id.
227 */
228 char *build_id_str;
229 /** Load address ranges. @c NULL if not known yet. */
230 struct drgn_module_address_range *address_ranges;
231 /** Number of ranges in @ref address_ranges. */
232 size_t num_address_ranges;
233 /**
234 * Placeholder assigned to @ref address_ranges in two cases:
235 *
236 * 1. If @ref num_address_ranges is 1. This lets us avoid allocating the
237 * address ranges separately. This is a minor optimization for the
238 * common case, but more importantly,
239 * `drgn_module_maybe_use_elf_file()` can't handle @ref
240 * drgn_module_set_address_range() failing.
241 * 2. If the address range is known to be empty. This allows us to
242 * distinguish between that and the unknown case.
243 */
244 struct drgn_module_address_range single_address_range;
245
246 struct drgn_elf_file *loaded_file;
247 struct drgn_elf_file *debug_file;
248 struct drgn_elf_file *supplementary_debug_file;
249 struct drgn_elf_file *gnu_debugdata_file;
250 /** Table mapping libdw handle to corresponding @ref drgn_elf_file. */
251 struct drgn_elf_file_dwarf_table split_dwarf_files;
252 uint64_t loaded_file_bias;
253 uint64_t debug_file_bias;
254 enum drgn_module_file_status loaded_file_status;
255 enum drgn_module_file_status debug_file_status;
256 enum drgn_supplementary_file_kind supplementary_debug_file_kind;
257
258 /** DWARF debugging information. */
259 struct drgn_module_dwarf_info dwarf;
260 /** ORC unwinder information. */
261 struct drgn_module_orc_info orc;
262 /** ELF symbol table. */
263 struct drgn_elf_symbol_table elf_symtab;
264 /** Symbol table from the gnu_debugdata_file */
265 struct drgn_elf_symbol_table gnu_debugdata_symtab;
266
267 /** Whether .debug_frame has been parsed. */
268 bool parsed_debug_frame;
269 /** Whether .eh_frame has been parsed. */
270 bool parsed_eh_frame;
271 /** Whether ORC unwinder data has been parsed. */
272 bool parsed_orc;
273 /** Which files need to be checked for an ELF symbol table. */
274 enum drgn_module_file_mask elf_symtab_pending_files;
275 /**
276 * Whether a full symbol table has been found (as opposed to a dynamic
277 * symbol table, which only contains a subset of symbols).
278 */
279 bool have_full_symtab;
280
281 /** Mapping from section name to address. */
282 struct drgn_module_section_address_map section_addresses;
283 /**
284 * Counter used to detect when @ref section_addresses is modified during
285 * iteration of a @ref drgn_module_section_address_iterator.
286 */
287 uint64_t section_addresses_generation;
288
289 /**
290 * Counter used to detect when loading debugging information is
291 * attempted.
292 *
293 * @sa drgn_debug_info::load_debug_info_generation
294 */
295 uint64_t load_debug_info_generation;
296 struct drgn_module_wanted_supplementary_file *wanted_supplementary_debug_file;
297 /** Node in @ref drgn_debug_info::modules_pending_indexing. */
298 struct drgn_module *pending_indexing_next;
299 /** Object the module was created from */
300 struct drgn_object object;
301 };
302
303 /**
304 * Delete a partially-initialized module. This can only be called before the
305 * module is returned from public API.
306 */
307 void drgn_module_delete(struct drgn_module *module);
308
309 static inline void drgn_module_deletep(struct drgn_module **modulep)
310 {
311 if (*modulep)
312 drgn_module_delete(*modulep);
313 }
314
315 // Binary index file generated by depmod(8).
316 struct depmod_index {
317 char *path;
318 void *addr;
319 size_t len;
320 };
321
322 DEFINE_VECTOR_TYPE(char_p_vector, char *);
323
324 DEFINE_HASH_MAP_TYPE(drgn_kmod_walk_module_map, const char *,
325 struct char_p_vector);
326
327 DEFINE_VECTOR_TYPE(drgn_kmod_walk_stack,
328 struct drgn_kmod_walk_stack_entry);
329
330 struct drgn_kmod_walk_inode {
331 dev_t dev;
332 ino_t ino;
333 };
334
335 DEFINE_HASH_SET_TYPE(drgn_kmod_walk_inode_set, struct drgn_kmod_walk_inode);
336
337 struct drgn_kmod_walk_state {
338 struct drgn_kmod_walk_module_map modules;
339 struct drgn_kmod_walk_stack stack;
340 struct string_builder path;
341 struct drgn_kmod_walk_inode_set visited_dirs;
342 const char * const *next_kernel_dir;
343 const char * const *next_debug_dir;
344 };
345
346 // State kept by standard debug info finder for all modules it's working on.
347 // Currently it's only used to cache locations of Linux kernel loadable modules.
348 struct drgn_standard_debug_info_find_state {
349 struct drgn_module * const *modules;
350 size_t num_modules;
351 struct depmod_index modules_dep;
352 struct drgn_kmod_walk_state kmod_walk;
353 };
354
355 void
356 drgn_standard_debug_info_find_state_deinit(struct drgn_standard_debug_info_find_state *state);
357
358 // Always takes ownership of fd. Attempts to resolve the real path of path.
359 struct drgn_error *
360 drgn_module_try_standard_file(struct drgn_module *module,
361 const struct drgn_debug_info_options *options,
362 const char *path, int fd, bool check_build_id,
363 const uint32_t *expected_crc);
364
365 static inline bool drgn_module_wants_file(struct drgn_module *module)
366 {
367 return drgn_module_wants_loaded_file(module)
368 || drgn_module_wants_debug_file(module);
369 }
370
371 /**
372 * Get the language of the program's `main` function or `NULL` if it could not
373 * be found.
374 */
375 const struct drgn_language *
376 drgn_debug_info_main_language(struct drgn_debug_info *dbinfo);
377
378 /** @ref drgn_type_finder_ops::find() that uses debugging information. */
379 struct drgn_error *drgn_debug_info_find_type(uint64_t kinds, const char *name,
380 size_t name_len,
381 const char *filename, void *arg,
382 struct drgn_qualified_type *ret);
383
384 /** @ref drgn_object_finder_ops::find() that uses debugging information. */
385 struct drgn_error *
386 drgn_debug_info_find_object(const char *name, size_t name_len,
387 const char *filename,
388 enum drgn_find_object_flags flags, void *arg,
389 struct drgn_object *ret);
390
391 struct drgn_elf_file *drgn_module_find_dwarf_file(struct drgn_module *module,
392 Dwarf *dwarf);
393
394 struct drgn_error *
395 drgn_module_create_split_dwarf_file(struct drgn_module *module,
396 const char *name, Dwarf *dwarf,
397 struct drgn_elf_file **ret);
398
399 /**
400 * Get the Call Frame Information in a @ref drgn_module at a given program
401 * counter.
402 *
403 * @param[in] module Module containing @p pc.
404 * @param[in] pc Program counter.
405 * @param[out] file_ret Returned file containing CFI.
406 * @param[in,out] row_ret Returned CFI row.
407 * @param[out] interrupted_ret Whether the found frame interrupted its caller.
408 * @param[out] ret_addr_regno_ret Returned return address register number.
409 * @return @c NULL on success, non-@c NULL on error. In particular, &@ref
410 * drgn_not_found if CFI wasn't found.
411 */
412 struct drgn_error *
413 drgn_module_find_cfi(struct drgn_program *prog, struct drgn_module *module,
414 uint64_t pc, struct drgn_elf_file **file_ret,
415 struct drgn_cfi_row **row_ret, bool *interrupted_ret,
416 drgn_register_number *ret_addr_regno_ret);
417
418 struct drgn_error *open_elf_file(const char *path, int *fd_ret, Elf **elf_ret);
419
420 struct drgn_error *find_elf_file(char **path_ret, int *fd_ret, Elf **elf_ret,
421 const char * const *path_formats, ...);
422
423 struct drgn_error *elf_address_range(Elf *elf, uint64_t bias,
424 uint64_t *start_ret, uint64_t *end_ret);
425
426 /** @} */
427
428 #endif /* DRGN_DEBUG_INFO_H */