// Copyright (c) Meta Platforms, Inc. and affiliates. // SPDX-License-Identifier: LGPL-2.1-or-later /** * @file * * Debugging information handling. * * See @ref DebugInfo. */ #ifndef DRGN_DEBUG_INFO_H #define DRGN_DEBUG_INFO_H #if WITH_DEBUGINFOD #include #endif #include #include #include "binary_search_tree.h" #include "cfi.h" #include "debug_info_options.h" #include "drgn_internal.h" #include "dwarf_info.h" #include "elf_symtab.h" #include "hash_table.h" #include "object.h" #include "orc_info.h" #include "string_builder.h" #include "symbol.h" #include "type.h" #include "vector.h" struct drgn_elf_file; /** * @ingroup Internals * * @defgroup DebugInfo Debugging information * * Caching of debugging information. * * @ref drgn_debug_info caches debugging information (currently DWARF and ORC). * It translates the debugging information to types and objects. * * @{ */ #if WITH_DEBUGINFOD #if ENABLE_DLOPEN_DEBUGINFOD bool drgn_have_debuginfod(void); #else static inline bool drgn_have_debuginfod(void) { return true; } #endif #else static inline bool drgn_have_debuginfod(void) { return false; } #endif DEFINE_HASH_TABLE_TYPE(drgn_elf_file_dwarf_table, struct drgn_elf_file *); DEFINE_HASH_TABLE_TYPE(drgn_module_table, struct drgn_module *); DEFINE_BINARY_SEARCH_TREE_TYPE(drgn_module_address_tree, struct drgn_module_address_range); struct drgn_debug_info_finder { struct drgn_handler handler; struct drgn_debug_info_finder_ops ops; void *arg; }; /** Cache of debugging information. */ struct drgn_debug_info { /** Program owning this cache. */ struct drgn_program *prog; struct drgn_type_finder type_finder; struct drgn_object_finder object_finder; struct drgn_symbol_finder symbol_finder; /** Main module. @c NULL if not created yet. */ struct drgn_module *main_module; /** * Table of all modules indexed by name. * * Modules with the same name (which should be rare) are on a * singly-linked list (@ref drgn_module::next_same_name). */ struct drgn_module_table modules; /** * Counter used to detect when @ref modules is modified during iteration * of a @ref drgn_created_module_iterator. */ uint64_t modules_generation; /** Tree of modules sorted by start address. */ struct drgn_module_address_tree modules_by_address; /** * Singly-linked list of modules that need to have their DWARF * information indexed. */ struct drgn_module *modules_pending_indexing; /** DWARF debugging information. */ struct drgn_dwarf_info dwarf; struct drgn_handler_list debug_info_finders; struct drgn_debug_info_finder standard_debug_info_finder; struct drgn_debug_info_options options; /** * Counter used to detect when loading debugging information is * attempted. * * @sa drgn_module::load_debug_info_generation */ uint64_t load_debug_info_generation; /** * Counter used to detect when the wanted supplementary file for a * module has changed. * * @sa drgn_module_wanted_supplementary_file::generation */ uint64_t supplementary_file_generation; #if WITH_DEBUGINFOD struct drgn_debug_info_finder debuginfod_debug_info_finder; /** debuginfod-client session. */ debuginfod_client *debuginfod_client; const char *debuginfod_current_name; const char *debuginfod_current_type; unsigned int debuginfod_spinner_position; bool debuginfod_have_url; bool logged_debuginfod_progress; #endif bool logged_no_debuginfod; /** * Cache of entries in /proc/$pid/map_files used for finding loaded * files. Populated the first time we need it or opportunistically when * we parse /proc/$pid/maps. Rebuilt whenever we try to open an entry * that no longer exists. */ struct drgn_map_files_segment *map_files_segments; /** Number of segments in @ref map_files_segments. */ size_t num_map_files_segments; }; /** Initialize a @ref drgn_debug_info. */ void drgn_debug_info_init(struct drgn_debug_info *dbinfo, struct drgn_program *prog); /** Deinitialize a @ref drgn_debug_info. */ void drgn_debug_info_deinit(struct drgn_debug_info *dbinfo); typedef void drgn_module_iterator_destroy_fn(struct drgn_module_iterator *); typedef struct drgn_error * drgn_module_iterator_next_fn(struct drgn_module_iterator *, struct drgn_module **, bool *); struct drgn_module_iterator { struct drgn_program *prog; drgn_module_iterator_destroy_fn *destroy; drgn_module_iterator_next_fn *next; bool for_load_debug_info; }; static inline void drgn_module_iterator_init(struct drgn_module_iterator *it, struct drgn_program *prog, drgn_module_iterator_destroy_fn *destroy, drgn_module_iterator_next_fn *next) { it->prog = prog; it->destroy = destroy; it->next = next; it->for_load_debug_info = false; } /** Bitmask of files in a @ref drgn_module. */ enum drgn_module_file_mask { DRGN_MODULE_FILE_MASK_LOADED = 1 << 0, DRGN_MODULE_FILE_MASK_DEBUG = 1 << 1, } __attribute__((__packed__)); DEFINE_HASH_MAP_TYPE(drgn_module_section_address_map, char *, uint64_t); struct drgn_module_address_range { /** Node in @ref drgn_debug_info::modules_by_address. */ struct binary_tree_node node; /** Address range. */ uint64_t start, end; /** Module owning this range. */ struct drgn_module *module; }; struct drgn_module { struct drgn_program *prog; enum drgn_module_kind kind; /** Module name. */ char *name; /** Kind-specific info. */ uint64_t info; /** Next module with the same name in @ref drgn_debug_info::modules. */ struct drgn_module *next_same_name; /** * Raw binary build ID. @c NULL if the module does not have a build ID. */ void *build_id; /** * Length of @ref drgn_module::build_id in bytes. Zero if the module * does not have a build ID. */ size_t build_id_len; /** * Build ID as a null-terminated hexadecimal string. @c NULL if the * module does not have a build ID. * * Used for logging and finding debugging information. * * This is allocated together with @ref drgn_module::build_id. */ char *build_id_str; /** Load address ranges. @c NULL if not known yet. */ struct drgn_module_address_range *address_ranges; /** Number of ranges in @ref address_ranges. */ size_t num_address_ranges; /** * Placeholder assigned to @ref address_ranges in two cases: * * 1. If @ref num_address_ranges is 1. This lets us avoid allocating the * address ranges separately. This is a minor optimization for the * common case, but more importantly, * `drgn_module_maybe_use_elf_file()` can't handle @ref * drgn_module_set_address_range() failing. * 2. If the address range is known to be empty. This allows us to * distinguish between that and the unknown case. */ struct drgn_module_address_range single_address_range; struct drgn_elf_file *loaded_file; struct drgn_elf_file *debug_file; struct drgn_elf_file *supplementary_debug_file; struct drgn_elf_file *gnu_debugdata_file; /** Table mapping libdw handle to corresponding @ref drgn_elf_file. */ struct drgn_elf_file_dwarf_table split_dwarf_files; uint64_t loaded_file_bias; uint64_t debug_file_bias; enum drgn_module_file_status loaded_file_status; enum drgn_module_file_status debug_file_status; enum drgn_supplementary_file_kind supplementary_debug_file_kind; /** DWARF debugging information. */ struct drgn_module_dwarf_info dwarf; /** ORC unwinder information. */ struct drgn_module_orc_info orc; /** ELF symbol table. */ struct drgn_elf_symbol_table elf_symtab; /** Symbol table from the gnu_debugdata_file */ struct drgn_elf_symbol_table gnu_debugdata_symtab; /** Whether .debug_frame has been parsed. */ bool parsed_debug_frame; /** Whether .eh_frame has been parsed. */ bool parsed_eh_frame; /** Whether ORC unwinder data has been parsed. */ bool parsed_orc; /** Which files need to be checked for an ELF symbol table. */ enum drgn_module_file_mask elf_symtab_pending_files; /** * Whether a full symbol table has been found (as opposed to a dynamic * symbol table, which only contains a subset of symbols). */ bool have_full_symtab; /** Mapping from section name to address. */ struct drgn_module_section_address_map section_addresses; /** * Counter used to detect when @ref section_addresses is modified during * iteration of a @ref drgn_module_section_address_iterator. */ uint64_t section_addresses_generation; /** * Counter used to detect when loading debugging information is * attempted. * * @sa drgn_debug_info::load_debug_info_generation */ uint64_t load_debug_info_generation; struct drgn_module_wanted_supplementary_file *wanted_supplementary_debug_file; /** Node in @ref drgn_debug_info::modules_pending_indexing. */ struct drgn_module *pending_indexing_next; /** Object the module was created from */ struct drgn_object object; }; /** * Delete a partially-initialized module. This can only be called before the * module is returned from public API. */ void drgn_module_delete(struct drgn_module *module); static inline void drgn_module_deletep(struct drgn_module **modulep) { if (*modulep) drgn_module_delete(*modulep); } // Binary index file generated by depmod(8). struct depmod_index { char *path; void *addr; size_t len; }; DEFINE_VECTOR_TYPE(char_p_vector, char *); DEFINE_HASH_MAP_TYPE(drgn_kmod_walk_module_map, const char *, struct char_p_vector); DEFINE_VECTOR_TYPE(drgn_kmod_walk_stack, struct drgn_kmod_walk_stack_entry); struct drgn_kmod_walk_inode { dev_t dev; ino_t ino; }; DEFINE_HASH_SET_TYPE(drgn_kmod_walk_inode_set, struct drgn_kmod_walk_inode); struct drgn_kmod_walk_state { struct drgn_kmod_walk_module_map modules; struct drgn_kmod_walk_stack stack; struct string_builder path; struct drgn_kmod_walk_inode_set visited_dirs; const char * const *next_kernel_dir; const char * const *next_debug_dir; }; // State kept by standard debug info finder for all modules it's working on. // Currently it's only used to cache locations of Linux kernel loadable modules. struct drgn_standard_debug_info_find_state { struct drgn_module * const *modules; size_t num_modules; struct depmod_index modules_dep; struct drgn_kmod_walk_state kmod_walk; }; void drgn_standard_debug_info_find_state_deinit(struct drgn_standard_debug_info_find_state *state); // Always takes ownership of fd. Attempts to resolve the real path of path. struct drgn_error * drgn_module_try_standard_file(struct drgn_module *module, const struct drgn_debug_info_options *options, const char *path, int fd, bool check_build_id, const uint32_t *expected_crc); static inline bool drgn_module_wants_file(struct drgn_module *module) { return drgn_module_wants_loaded_file(module) || drgn_module_wants_debug_file(module); } /** * Get the language of the program's `main` function or `NULL` if it could not * be found. */ const struct drgn_language * drgn_debug_info_main_language(struct drgn_debug_info *dbinfo); /** @ref drgn_type_finder_ops::find() that uses debugging information. */ struct drgn_error *drgn_debug_info_find_type(uint64_t kinds, const char *name, size_t name_len, const char *filename, void *arg, struct drgn_qualified_type *ret); /** @ref drgn_object_finder_ops::find() that uses debugging information. */ struct drgn_error * drgn_debug_info_find_object(const char *name, size_t name_len, const char *filename, enum drgn_find_object_flags flags, void *arg, struct drgn_object *ret); struct drgn_elf_file *drgn_module_find_dwarf_file(struct drgn_module *module, Dwarf *dwarf); struct drgn_error * drgn_module_create_split_dwarf_file(struct drgn_module *module, const char *name, Dwarf *dwarf, struct drgn_elf_file **ret); /** * Get the Call Frame Information in a @ref drgn_module at a given program * counter. * * @param[in] module Module containing @p pc. * @param[in] pc Program counter. * @param[out] file_ret Returned file containing CFI. * @param[in,out] row_ret Returned CFI row. * @param[out] interrupted_ret Whether the found frame interrupted its caller. * @param[out] ret_addr_regno_ret Returned return address register number. * @return @c NULL on success, non-@c NULL on error. In particular, &@ref * drgn_not_found if CFI wasn't found. */ struct drgn_error * drgn_module_find_cfi(struct drgn_program *prog, struct drgn_module *module, uint64_t pc, struct drgn_elf_file **file_ret, struct drgn_cfi_row **row_ret, bool *interrupted_ret, drgn_register_number *ret_addr_regno_ret); struct drgn_error *open_elf_file(const char *path, int *fd_ret, Elf **elf_ret); struct drgn_error *find_elf_file(char **path_ret, int *fd_ret, Elf **elf_ret, const char * const *path_formats, ...); struct drgn_error *elf_address_range(Elf *elf, uint64_t bias, uint64_t *start_ret, uint64_t *end_ret); /** @} */ #endif /* DRGN_DEBUG_INFO_H */