Debian Codegraph @

libdrgn/program.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 * Program internals.
8 *
9 * See @ref ProgramInternals.
10 */
11
12 #ifndef DRGN_PROGRAM_H
13 #define DRGN_PROGRAM_H
14
15 #include <libelf.h>
16 #include <sys/types.h>
17 #ifdef WITH_LIBKDUMPFILE
18 #include <libkdumpfile/kdumpfile.h>
19 #endif
20
21 #include "debug_info.h"
22 #include "drgn_internal.h"
23 #include "handler.h"
24 #include "hash_table.h"
25 #include "language.h"
26 #include "memory_reader.h"
27 #include "platform.h"
28 #include "pp.h"
29 #include "qemu_machine_protocol.h"
30 #include "type.h"
31 #include "vector.h"
32
33 struct drgn_object_finder;
34 struct drgn_symbol;
35 struct drgn_symbol_finder;
36 struct drgn_type_finder;
37
38 /**
39 * @defgroup Internals Internals
40 *
41 * Internal implementation
42 *
43 * @{
44 *
45 * @defgroup ProgramInternals Programs
46 *
47 * Program internals.
48 *
49 * @{
50 */
51
52 struct drgn_thread {
53 struct drgn_program *prog;
54 uint32_t tid;
55 struct nstring prstatus;
56 struct drgn_object object;
57 };
58
59 DEFINE_VECTOR_TYPE(drgn_typep_vector, struct drgn_type *);
60 DEFINE_HASH_TABLE_TYPE(drgn_thread_set, struct drgn_thread);
61
62 #define SEARCH_MEMORY_UINT_SIZES X(16) X(32) X(64)
63
64 struct drgn_program {
65 /** @privatesection */
66
67 /*
68 * Memory/core dump.
69 */
70 struct drgn_memory_reader reader;
71 /* Elf core dump or /proc/pid/mem file segments. */
72 struct drgn_memory_file_segment *file_segments;
73 /* Elf core dump. Not valid for live programs or kdump files. */
74 Elf *core;
75 /* File descriptor for ELF core dump, kdump file, or /proc/pid/mem. */
76 int core_fd;
77 /* Path of core dump. */
78 char *core_path;
79 /* PID of live userspace program. */
80 pid_t pid;
81 #ifdef WITH_LIBKDUMPFILE
82 kdump_ctx_t *kdump_ctx;
83 #endif
84 struct drgn_qmp_conn qmp_conn;
85
86 /*
87 * Types.
88 */
89 /** Callbacks for finding types. */
90 struct drgn_handler_list type_finders;
91 /** Void type for each language. */
92 struct drgn_type void_types[DRGN_NUM_LANGUAGES];
93 /** Cache of primitive types. */
94 struct drgn_type *primitive_types[DRGN_PRIMITIVE_TYPE_NUM];
95 /** Cache of deduplicated types. */
96 struct drgn_dedupe_type_set dedupe_types;
97 /**
98 * List of created types that are not deduplicated: types with non-empty
99 * lists of members, parameters, template parameters, or enumerators.
100 *
101 * Members, parameters, and template parameters contain lazily-evaluated
102 * objects, so they cannot be easily deduplicated.
103 *
104 * Enumerators could be deduplicated, but it's probably not worth the
105 * effort to hash and compare them.
106 */
107 struct drgn_typep_vector created_types;
108 /** Cache for @ref drgn_program_find_member(). */
109 struct drgn_member_map members;
110 /**
111 * Set of types which have been already cached in @ref
112 * drgn_program::members.
113 */
114 struct drgn_type_set members_cached;
115
116 /*
117 * Debugging information.
118 */
119 struct drgn_handler_list object_finders;
120 struct drgn_debug_info dbinfo;
121 struct drgn_handler_list symbol_finders;
122
123 /*
124 * Program information.
125 */
126 /* Default language of the program. */
127 const struct drgn_language *lang;
128 struct drgn_platform platform;
129 /**
130 * Whether we have tried determining the default language from "main"
131 * since the last time that debug info was added.
132 */
133 bool tried_main_language;
134 bool has_platform;
135 enum drgn_program_flags flags;
136
137 /*
138 * Threads/stack traces.
139 */
140 /*
141 * Threads indexed by TID.
142 *
143 * For the Linux kernel, this is only used to index @c PRSTATUS notes.
144 * See @ref drgn_program_find_prstatus().
145 */
146 struct drgn_thread_set thread_set;
147 struct drgn_thread *main_thread;
148 struct drgn_thread *crashed_thread;
149 /*
150 * Cached offsetof(struct pt_regs, stackframe) for aarch64, or 0 if not
151 * yet cached.
152 */
153 uint64_t aarch64_stackframe_offset_cached;
154
155 /*
156 * AArch64 instruction pointer authentication code mask, parsed either
157 * from NT_ARM_PAC_MASK or VMCOREINFO.
158 */
159 uint64_t aarch64_insn_pac_mask;
160 bool core_dump_threads_cached;
161
162 union {
163 /*
164 * Userspace-specific.
165 */
166 struct {
167 /** Cached `pr_fname` from `NT_PRPSINFO` note. */
168 char *core_dump_fname_cached;
169 /** Cache of important parts of auxiliary vector. */
170 struct {
171 uint64_t at_phdr;
172 uint64_t at_phnum;
173 uint64_t at_sysinfo_ehdr;
174 } auxv;
175 bool auxv_cached;
176 };
177
178 /*
179 * Linux kernel-specific.
180 */
181 struct {
182 /*
183 * Important parts of the VMCOREINFO note of a Linux
184 * kernel core.
185 */
186 struct {
187 /** `uname -r` */
188 char osrelease[128];
189 /** Build ID. */
190 char build_id[128];
191 /** `PAGE_SIZE` of the kernel. */
192 uint64_t page_size;
193 /**
194 * The offset from the compiled address of the
195 * kernel image to its actual address in memory.
196 *
197 * This is non-zero if kernel address space
198 * layout randomization (KASLR) is enabled.
199 */
200 uint64_t kaslr_offset;
201 /** Kernel page table. */
202 uint64_t swapper_pg_dir;
203 /**
204 * Length of mem_section array (i.e.,
205 * `NR_SECTION_ROOTS`).
206 */
207 uint64_t mem_section_length;
208 /**
209 * `SECTION_SIZE_BITS` of the kernel. Initially
210 * 0 if not found in VMCOREINFO, but may be
211 * determined by other means and cached later.
212 */
213 int section_size_bits;
214 /**
215 * `MAX_PHYSMEM_BITS` of the kernel. Initially 0
216 * if not found in VMCOREINFO, but may be
217 * determined by other means and cached later.
218 */
219 int max_physmem_bits;
220 /** `VA_BITS` on AArch64. */
221 uint64_t va_bits;
222 /** `TCR_EL1_T1SZ` on AArch64. */
223 uint64_t tcr_el1_t1sz;
224 /** `kimage_voffset` on AArch64 */
225 uint64_t kimage_voffset;
226 /** `phys_base` on x86_64 */
227 uint64_t phys_base;
228 /**
229 * Whether 5-level paging was enabled on x86-64.
230 */
231 bool pgtable_l5_enabled;
232 /** Whether LPAE was enabled on Arm. */
233 bool arm_lpae;
234 /** Whether `CRASHTIME` was in the VMCOREINFO. */
235 bool have_crashtime;
236 /** Whether `phys_base` was in the VMCOREINFO. */
237 bool have_phys_base;
238 /** Length of build ID. */
239 unsigned int build_id_len;
240 /**
241 * `PAGE_SHIFT` of the kernel (derived from
242 * `PAGE_SIZE`).
243 */
244 int page_shift;
245
246 /** The original vmcoreinfo data, to expose as an object */
247 char *raw;
248 size_t raw_size;
249 } vmcoreinfo;
250 /**
251 * Value of `THREAD_SIZE` in the kernel, or 0 if not
252 * cached yet.
253 */
254 uint64_t thread_size_cached;
255 /**
256 * Value of `SECTIONS_PER_ROOT` in the kernel, or 0 if
257 * not cached yet.
258 */
259 uint64_t cached_sections_per_root;
260 /** Value of `ARCH_PFN_OFFSET` in the kernel. */
261 uint64_t arch_pfn_offset;
262 /*
263 * Difference between a virtual address in the direct
264 * mapping and the physical address it maps to.
265 */
266 uint64_t direct_mapping_offset;
267 /** Cached value of `MOD_TEXT` in the kernel. */
268 uint64_t mod_text;
269 /** Cached array of per-cpu __irq_regs values */
270 uint64_t *irq_regs_cached;
271 /**
272 * Whether @ref drgn_program::arch_pfn_offset has been
273 * cached.
274 */
275 bool arch_pfn_offset_cached;
276 /*
277 * Whether @ref drgn_program::direct_mapping_offset has
278 * been cached.
279 */
280 bool direct_mapping_offset_cached;
281 /**
282 * Whether @ref drgn_program::mod_text has been cached.
283 */
284 bool mod_text_cached;
285 /*
286 * Whether we are currently in address translation. Used
287 * to prevent address translation from recursing.
288 */
289 bool in_address_translation;
290 };
291 };
292 /*
293 * Linux kernel-specific, but simplifies init/deinit to have them
294 * outside of the union above.
295 */
296 /* Cached vmemmap. */
297 struct drgn_object vmemmap;
298 /* Page table iterator. */
299 struct pgtable_iterator *pgtable_it;
300
301 /*
302 * Logging.
303 */
304 drgn_log_fn *log_fn;
305 void *log_arg;
306 FILE *progress_file;
307 enum drgn_log_level log_level;
308 bool default_progress_file;
309 };
310
311 /** Initialize a @ref drgn_program. */
312 void drgn_program_init(struct drgn_program *prog,
313 const struct drgn_platform *platform);
314
315 /** Deinitialize a @ref drgn_program. */
316 void drgn_program_deinit(struct drgn_program *prog);
317
318 /**
319 * Return an error if the program's memory has already been initialized or its
320 * target has been set.
321 */
322 struct drgn_error *drgn_program_check_initialized(struct drgn_program *prog);
323
324 /**
325 * Set the @ref drgn_platform of a @ref drgn_program if it hasn't been set
326 * yet.
327 */
328 void drgn_program_set_platform(struct drgn_program *prog,
329 const struct drgn_platform *platform);
330
331 /**
332 * Implement @ref drgn_program_from_core_dump() on an initialized @ref
333 * drgn_program.
334 */
335 struct drgn_error *drgn_program_init_core_dump(struct drgn_program *prog,
336 const char *path);
337
338 /**
339 * Implement @ref drgn_program_from_core_dump_fd() on an initialized @ref
340 * drgn_program.
341 */
342 struct drgn_error *drgn_program_init_core_dump_fd(struct drgn_program *prog,
343 int fd);
344
345 /**
346 * Implement @ref drgn_program_from_kernel() on an initialized @ref
347 * drgn_program.
348 */
349 struct drgn_error *drgn_program_init_kernel(struct drgn_program *prog);
350
351 /**
352 * Implement @ref drgn_program_from_pid() on an initialized @ref drgn_program.
353 */
354 struct drgn_error *drgn_program_init_pid(struct drgn_program *prog, pid_t pid);
355
356 struct drgn_error *drgn_program_cache_auxv(struct drgn_program *prog);
357
358 /**
359 * Return whether a @ref drgn_program is a userspace process running on the
360 * local machine.
361 */
362 static inline bool
363 drgn_program_is_userspace_process(struct drgn_program *prog)
364 {
365 return (prog->flags & (DRGN_PROGRAM_IS_LINUX_KERNEL
366 | DRGN_PROGRAM_IS_LIVE
367 | DRGN_PROGRAM_IS_LOCAL))
368 == (DRGN_PROGRAM_IS_LIVE | DRGN_PROGRAM_IS_LOCAL);
369 }
370
371 /** Return whether a @ref drgn_program is a core dump of a userspace process. */
372 static inline bool
373 drgn_program_is_userspace_core(struct drgn_program *prog)
374 {
375 return (prog->flags &
376 (DRGN_PROGRAM_IS_LINUX_KERNEL | DRGN_PROGRAM_IS_LIVE)) == 0
377 && prog->core;
378 }
379
380 static inline struct drgn_error *
381 drgn_program_is_little_endian(struct drgn_program *prog, bool *ret)
382 {
383 if (!prog->has_platform) {
384 return drgn_error_create(DRGN_ERROR_INVALID_ARGUMENT,
385 "program byte order is not known");
386 }
387 *ret = drgn_platform_is_little_endian(&prog->platform);
388 return NULL;
389 }
390
391 /**
392 * Return whether a @ref drgn_program has a different endianness than the host
393 * system.
394 */
395 static inline struct drgn_error *
396 drgn_program_bswap(struct drgn_program *prog, bool *ret)
397 {
398 if (!prog->has_platform) {
399 return drgn_error_create(DRGN_ERROR_INVALID_ARGUMENT,
400 "program byte order is not known");
401 }
402 *ret = drgn_platform_bswap(&prog->platform);
403 return NULL;
404 }
405
406 static inline struct drgn_error *
407 drgn_program_is_64_bit(struct drgn_program *prog, bool *ret)
408 {
409 if (!prog->has_platform) {
410 return drgn_error_create(DRGN_ERROR_INVALID_ARGUMENT,
411 "program word size is not known");
412 }
413 *ret = drgn_platform_is_64_bit(&prog->platform);
414 return NULL;
415 }
416
417 static inline struct drgn_error *
418 drgn_program_address_mask(const struct drgn_program *prog, uint64_t *ret)
419 {
420 if (!prog->has_platform) {
421 return drgn_error_create(DRGN_ERROR_INVALID_ARGUMENT,
422 "program address size is not known");
423 }
424 *ret = drgn_platform_address_mask(&prog->platform);
425 return NULL;
426 }
427
428 static inline struct drgn_error *
429 drgn_program_untagged_addr(const struct drgn_program *prog, uint64_t *address)
430 {
431 if (!prog->has_platform) {
432 return drgn_error_create(DRGN_ERROR_INVALID_ARGUMENT,
433 "program address size is not known");
434 }
435 *address &= drgn_platform_address_mask(&prog->platform);
436 if (prog->platform.arch->untagged_addr)
437 *address = prog->platform.arch->untagged_addr(*address);
438 return NULL;
439 }
440
441 struct drgn_error *drgn_thread_dup_internal(const struct drgn_thread *thread,
442 struct drgn_thread *ret);
443
444 void drgn_thread_deinit(struct drgn_thread *thread);
445
446 /**
447 * Find the @c NT_PRSTATUS note with the given "PID".
448 *
449 * For userspace, the PID is the thread ID. For the kernel, it's complicated;
450 * see drgn_get_initial_registers_from_kernel_core_dump().
451 *
452 * @param[out] ret Returned note data. If not found, <tt>ret->str</tt> is set to
453 * @c NULL and <tt>ret->len</tt> is set to zero.
454 */
455 struct drgn_error *drgn_program_find_prstatus(struct drgn_program *prog,
456 uint32_t tid,
457 struct nstring *ret);
458
459 /**
460 * Cache the @c NT_PRSTATUS note provided by @p data in @p prog.
461 *
462 * @param[in] data The pointer to the note data.
463 * @param[in] size Size of data in note.
464 * @param[out] ret Thread ID from note.
465 */
466 struct drgn_error *drgn_program_cache_prstatus_entry(struct drgn_program *prog,
467 const char *data,
468 size_t size,
469 uint32_t *ret);
470
471 /*
472 * Like @ref drgn_program_find_symbol_by_address(), but returns @c NULL rather
473 * than a lookup error if the symbol was not found.
474 *
475 * @param[in] address Address to search for.
476 * @param [out] ret The symbol found by the lookup (if found)
477 * @return @c NULL unless an error (unrelated to a lookup error) was encountered
478 */
479 struct drgn_error *
480 drgn_program_find_symbol_by_address_internal(struct drgn_program *prog,
481 uint64_t address,
482 struct drgn_symbol **ret);
483
484 struct drgn_error *
485 drgn_program_register_type_finder_impl(struct drgn_program *prog,
486 struct drgn_type_finder *finder,
487 const char *name,
488 const struct drgn_type_finder_ops *ops,
489 void *arg, size_t enable_index);
490
491 struct drgn_error *
492 drgn_program_register_object_finder_impl(struct drgn_program *prog,
493 struct drgn_object_finder *finder,
494 const char *name,
495 const struct drgn_object_finder_ops *ops,
496 void *arg, size_t enable_index);
497
498 struct drgn_error *
499 drgn_program_register_symbol_finder_impl(struct drgn_program *prog,
500 struct drgn_symbol_finder *finder,
501 const char *name,
502 const struct drgn_symbol_finder_ops *ops,
503 void *arg, size_t enable_index);
504
505 /** Opaque state used for blocking operations. */
506 typedef struct drgn_blocking_state *drgn_blocking_state;
507
508 /**
509 * Call before a blocking (I/O or long-running) operation.
510 *
511 * Must be paired with @ref drgn_end_blocking().
512 *
513 * @return Opaque state to pass to @ref drgn_end_blocking().
514 */
515 drgn_blocking_state drgn_begin_blocking(void);
516
517 /**
518 * Call after a blocking (I/O or long-running) operation.
519 *
520 * @param[in] state Return value of @ref drgn_begin_blocking().
521 */
522 void drgn_end_blocking(drgn_blocking_state state);
523
524 /**
525 * Call periodically during a blocking operation to check for pending signals.
526 *
527 * @param[in,out] statep Pointer to return value of @ref drgn_begin_blocking().
528 */
529 struct drgn_error *
530 drgn_blocking_check_signals(drgn_blocking_state *statep);
531
532 static inline void
533 drgn_blocking_guard_cleanup(drgn_blocking_state *statep)
534 {
535 drgn_end_blocking(*statep);
536 }
537
538 /**
539 * Scope guard that wraps @ref drgn_begin_blocking() and @ref
540 * drgn_end_blocking().
541 */
542 #define drgn_blocking_guard(name) \
543 drgn_blocking_state name \
544 __attribute__((__cleanup__(drgn_blocking_guard_cleanup), __unused__)) = \
545 drgn_begin_blocking()
546
547 /**
548 * @}
549 * @}
550 */
551
552 #endif /* DRGN_PROGRAM_H */