| 1 |
// Copyright (c) Meta Platforms, Inc. and affiliates. |
| 2 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 3 |
|
| 4 |
/** |
| 5 |
* @file |
| 6 |
* |
| 7 |
* DWARF and .eh_frame support. |
| 8 |
* |
| 9 |
* See @ref DebugInfo. |
| 10 |
*/ |
| 11 |
|
| 12 |
#ifndef DRGN_DEBUG_INFO_DWARF_H |
| 13 |
#define DRGN_DEBUG_INFO_DWARF_H |
| 14 |
|
| 15 |
/** |
| 16 |
* @ingroup DebugInfo |
| 17 |
* |
| 18 |
* @{ |
| 19 |
*/ |
| 20 |
|
| 21 |
#include <elfutils/libdw.h> |
| 22 |
|
| 23 |
#include "cfi.h" |
| 24 |
#include "drgn_internal.h" |
| 25 |
#include "hash_table.h" |
| 26 |
#include "vector.h" |
| 27 |
|
| 28 |
struct drgn_debug_info; |
| 29 |
struct drgn_elf_file; |
| 30 |
struct drgn_module; |
| 31 |
struct drgn_register_state; |
| 32 |
|
| 33 |
/** DWARF Frame Description Entry. */ |
| 34 |
struct drgn_dwarf_fde { |
| 35 |
uint64_t initial_location; |
| 36 |
uint64_t address_range; |
| 37 |
/* CIE for this FDE as an index into drgn_dwarf_cfi::cies. */ |
| 38 |
size_t cie; |
| 39 |
const char *instructions; |
| 40 |
size_t instructions_size; |
| 41 |
}; |
| 42 |
|
| 43 |
/** DWARF Call Frame Information. */ |
| 44 |
struct drgn_dwarf_cfi { |
| 45 |
/** Array of DWARF Common Information Entries. */ |
| 46 |
struct drgn_dwarf_cie *cies; |
| 47 |
/** |
| 48 |
* Array of DWARF Frame Description Entries sorted by initial_location. |
| 49 |
*/ |
| 50 |
struct drgn_dwarf_fde *fdes; |
| 51 |
/** Number of elements in @ref drgn_dwarf_cfi::fdes. */ |
| 52 |
size_t num_fdes; |
| 53 |
}; |
| 54 |
|
| 55 |
/** DWARF debugging information for a @ref drgn_module. */ |
| 56 |
struct drgn_module_dwarf_info { |
| 57 |
/** Call Frame Information from .debug_frame. */ |
| 58 |
struct drgn_dwarf_cfi debug_frame; |
| 59 |
/** Call Frame Information from .eh_frame. */ |
| 60 |
struct drgn_dwarf_cfi eh_frame; |
| 61 |
/** Base for `DW_EH_PE_pcrel`. */ |
| 62 |
uint64_t pcrel_base; |
| 63 |
/** Base for `DW_EH_PE_textrel`. */ |
| 64 |
uint64_t textrel_base; |
| 65 |
/** Base for `DW_EH_PE_datarel`. */ |
| 66 |
uint64_t datarel_base; |
| 67 |
}; |
| 68 |
|
| 69 |
void drgn_module_dwarf_info_deinit(struct drgn_module *module); |
| 70 |
|
| 71 |
DEFINE_VECTOR_TYPE(drgn_dwarf_index_die_vector, uintptr_t, |
| 72 |
vector_inline_minimal, uint32_t); |
| 73 |
DEFINE_HASH_MAP_TYPE(drgn_dwarf_index_die_map, struct nstring, |
| 74 |
struct drgn_dwarf_index_die_vector); |
| 75 |
|
| 76 |
DEFINE_HASH_TABLE_TYPE(drgn_namespace_table, |
| 77 |
struct drgn_namespace_dwarf_index *); |
| 78 |
|
| 79 |
/* DWARF tags that act as namespaces. */ |
| 80 |
#define DRGN_DWARF_INDEX_NAMESPACE_TAGS \ |
| 81 |
X(structure_type) \ |
| 82 |
X(class_type) \ |
| 83 |
X(union_type) \ |
| 84 |
X(namespace) |
| 85 |
|
| 86 |
/* DWARF tags that we index. */ |
| 87 |
#define DRGN_DWARF_INDEX_TAGS \ |
| 88 |
/* \ |
| 89 |
* These must be first for a few places where we only care about \ |
| 90 |
* namespace-like tags (e.g., drgn_namespace_dwarf_index::dies_indexed).\ |
| 91 |
*/ \ |
| 92 |
DRGN_DWARF_INDEX_NAMESPACE_TAGS \ |
| 93 |
X(enumeration_type) \ |
| 94 |
X(typedef) \ |
| 95 |
X(enumerator) \ |
| 96 |
X(subprogram) \ |
| 97 |
X(variable) \ |
| 98 |
X(base_type) |
| 99 |
|
| 100 |
enum drgn_dwarf_index_tag { |
| 101 |
#define X(name) DRGN_DWARF_INDEX_##name, |
| 102 |
DRGN_DWARF_INDEX_TAGS |
| 103 |
#undef X |
| 104 |
}; |
| 105 |
|
| 106 |
#define X(_) + 1 |
| 107 |
enum { DRGN_DWARF_INDEX_NUM_NAMESPACE_TAGS = DRGN_DWARF_INDEX_NAMESPACE_TAGS }; |
| 108 |
enum { DRGN_DWARF_INDEX_NUM_TAGS = DRGN_DWARF_INDEX_TAGS }; |
| 109 |
#undef X |
| 110 |
_Static_assert(DRGN_DWARF_INDEX_base_type == DRGN_DWARF_INDEX_NUM_TAGS - 1, |
| 111 |
"base_type must be last"); |
| 112 |
enum { DRGN_DWARF_INDEX_MAP_SIZE = DRGN_DWARF_INDEX_NUM_TAGS - 1 }; |
| 113 |
|
| 114 |
/** |
| 115 |
* DWARF information for a namespace or nested definitions in a class, struct, |
| 116 |
* or union. |
| 117 |
*/ |
| 118 |
struct drgn_namespace_dwarf_index { |
| 119 |
/** Debugging information cache that owns this index. */ |
| 120 |
struct drgn_debug_info *dbinfo; |
| 121 |
/** (Null-terminated) name of this namespace. */ |
| 122 |
const char *name; |
| 123 |
/** Length of @ref name. */ |
| 124 |
size_t name_len; |
| 125 |
/** Parent namespace, or @c NULL if it is the global namespace. */ |
| 126 |
struct drgn_namespace_dwarf_index *parent; |
| 127 |
/** Children namespaces indexed by name. */ |
| 128 |
struct drgn_namespace_table children; |
| 129 |
/** |
| 130 |
* Mapping for each @ref drgn_dwarf_index_tag from name to a list of |
| 131 |
* matching DIE addresses. |
| 132 |
* |
| 133 |
* This has a few quirks: |
| 134 |
* |
| 135 |
* - `base_type` DIEs are in @ref drgn_dwarf_info::base_types, not here. |
| 136 |
* - `enumerator` entries store the addresses of the parent |
| 137 |
* `enumeration_type` DIEs instead. |
| 138 |
* - `namespace` entries also include the addresses of `class_type`, |
| 139 |
* `structure_type`, and `union_type` DIEs that have children and |
| 140 |
* `DW_AT_declaration`. This is because class, struct, and union |
| 141 |
* declaration DIEs can contain nested definitions, so we want to |
| 142 |
* index the children of those declarations, but we don't want to |
| 143 |
* encounter the declarations when looking for the actual type. |
| 144 |
* - Otherwise, this does not include DIEs with `DW_AT_declaration`. |
| 145 |
*/ |
| 146 |
struct drgn_dwarf_index_die_map map[DRGN_DWARF_INDEX_MAP_SIZE]; |
| 147 |
/** |
| 148 |
* Number of CUs that were indexed the last time that this namespace was |
| 149 |
* indexed. |
| 150 |
*/ |
| 151 |
size_t cus_indexed; |
| 152 |
/** |
| 153 |
* Number of DIEs for each namespace-like tag in the parent's index that |
| 154 |
* were indexed the last time that this namespace was indexed. |
| 155 |
*/ |
| 156 |
uint32_t dies_indexed[DRGN_DWARF_INDEX_NUM_NAMESPACE_TAGS]; |
| 157 |
/** Saved error from a previous index. */ |
| 158 |
struct drgn_error *saved_err; |
| 159 |
}; |
| 160 |
|
| 161 |
/** Cached type in a @ref drgn_debug_info. */ |
| 162 |
struct drgn_dwarf_type { |
| 163 |
struct drgn_type *type; |
| 164 |
enum drgn_qualifiers qualifiers; |
| 165 |
/** |
| 166 |
* Whether this is an incomplete array type or a typedef of one. |
| 167 |
* |
| 168 |
* This is used to work around a GCC bug; see @ref |
| 169 |
* drgn_type_from_dwarf_internal(). |
| 170 |
*/ |
| 171 |
bool is_incomplete_array; |
| 172 |
}; |
| 173 |
|
| 174 |
DEFINE_HASH_MAP_TYPE(drgn_dwarf_base_type_map, struct nstring, uintptr_t); |
| 175 |
DEFINE_HASH_MAP_TYPE(drgn_dwarf_specification_map, uintptr_t, uintptr_t); |
| 176 |
DEFINE_VECTOR_TYPE(drgn_dwarf_index_cu_vector, struct drgn_dwarf_index_cu); |
| 177 |
DEFINE_HASH_MAP_TYPE(drgn_dwarf_type_map, const void *, struct drgn_dwarf_type); |
| 178 |
|
| 179 |
/** DWARF debugging information for a program/@ref drgn_debug_info. */ |
| 180 |
struct drgn_dwarf_info { |
| 181 |
/** Global namespace index. */ |
| 182 |
struct drgn_namespace_dwarf_index global; |
| 183 |
/** |
| 184 |
* Mapping from name to `DW_TAG_base_type` DIE address with that name. |
| 185 |
* |
| 186 |
* Unlike user-defined types and variables, there can only be one base |
| 187 |
* type with a given name in the entire program, so we don't store them |
| 188 |
* in a @ref drgn_dwarf_index_die_map. |
| 189 |
*/ |
| 190 |
struct drgn_dwarf_base_type_map base_types; |
| 191 |
/** |
| 192 |
* Map from the address of a DIE to the address of a top-level DIE with |
| 193 |
* a `DW_AT_specification` or `DW_AT_abstract_origin` attribute that |
| 194 |
* refers to it. |
| 195 |
*/ |
| 196 |
struct drgn_dwarf_specification_map specifications; |
| 197 |
/** Indexed compilation units. */ |
| 198 |
struct drgn_dwarf_index_cu_vector index_cus; |
| 199 |
/** |
| 200 |
* Lookup table for indexed compilation units sorted on buffer address. |
| 201 |
* |
| 202 |
* Size is equal to that of @ref index_cus. |
| 203 |
*/ |
| 204 |
struct drgn_dwarf_index_cu_lookup *index_cu_lookup; |
| 205 |
|
| 206 |
/** |
| 207 |
* Cache of parsed types. |
| 208 |
* |
| 209 |
* The key is the address of the DIE (@c Dwarf_Die::addr). The value is |
| 210 |
* a @ref drgn_dwarf_type. |
| 211 |
*/ |
| 212 |
struct drgn_dwarf_type_map types; |
| 213 |
/** |
| 214 |
* Cache of parsed types which appear to be incomplete array types but |
| 215 |
* can't be. |
| 216 |
* |
| 217 |
* See @ref drgn_type_from_dwarf_internal(). |
| 218 |
*/ |
| 219 |
struct drgn_dwarf_type_map cant_be_incomplete_array_types; |
| 220 |
}; |
| 221 |
|
| 222 |
void drgn_dwarf_info_init(struct drgn_debug_info *dbinfo); |
| 223 |
void drgn_dwarf_info_deinit(struct drgn_debug_info *dbinfo); |
| 224 |
|
| 225 |
struct drgn_error *drgn_dwarf_info_update_index(struct drgn_debug_info *dbinfo); |
| 226 |
|
| 227 |
/** |
| 228 |
* Find the DWARF DIEs in a @ref drgn_module for the scope containing a given |
| 229 |
* program counter. |
| 230 |
* |
| 231 |
* @param[in] module Module containing @p pc. |
| 232 |
* @param[in] pc Program counter. |
| 233 |
* @param[out] bias_ret Returned difference between addresses in the loaded |
| 234 |
* module and addresses in the returned DIEs. |
| 235 |
* @param[out] dies_ret Returned DIEs. `(*dies_ret)[*length_ret - 1]` is the |
| 236 |
* innermost DIE containing @p pc, `(*dies_ret)[*length_ret - 2]` is its parent |
| 237 |
* (which may not contain @p pc itself), `(*dies_ret)[*length_ret - 3]` is its |
| 238 |
* grandparent, etc. Must be freed with @c free(). |
| 239 |
* @param[out] length_ret Returned length of @p dies_ret. |
| 240 |
*/ |
| 241 |
struct drgn_error *drgn_module_find_dwarf_scopes(struct drgn_module *module, |
| 242 |
uint64_t pc, |
| 243 |
uint64_t *bias_ret, |
| 244 |
Dwarf_Die **dies_ret, |
| 245 |
size_t *length_ret) |
| 246 |
__attribute__((__nonnull__(1, 3, 4, 5))); |
| 247 |
|
| 248 |
/** |
| 249 |
* Find the ancestors of a DWARF DIE. |
| 250 |
* |
| 251 |
* This finds the parent, grandparent, etc., of a DWARF DIE in the tree of DIEs. |
| 252 |
* |
| 253 |
* @param[in] module Module containing @p die. |
| 254 |
* @param[in] die DIE to find. |
| 255 |
* @param[out] dies_ret Returned DIEs. `(*dies_ret)[*length_ret]` is the DIE, |
| 256 |
* `(*dies_ret)[*length_ret - 1]` is its parent, `(*dies_ret)[*length_ret - 2]` |
| 257 |
* is its grandparent, etc., and `(*dies_ret)[0]` is the top-level unit DIE. |
| 258 |
* @param[out] length_ret Returned number of ancestors in @p dies_ret. |
| 259 |
*/ |
| 260 |
struct drgn_error *drgn_find_die_ancestors(Dwarf_Die *die, Dwarf_Die **dies_ret, |
| 261 |
size_t *length_ret) |
| 262 |
__attribute__((__nonnull__(2, 3))); |
| 263 |
|
| 264 |
/** |
| 265 |
* Get an array of names of `DW_TAG_variable` and `DW_TAG_formal_parameter` DIEs |
| 266 |
* in local scopes. |
| 267 |
* |
| 268 |
* @param[out] names_ret Returned array of names. On success, must be freed with |
| 269 |
* @c free(). The individual strings should not be freed. |
| 270 |
* @param[out] count_ret Returned number of names in @p names_ret. |
| 271 |
*/ |
| 272 |
struct drgn_error *drgn_dwarf_scopes_names(Dwarf_Die *scopes, |
| 273 |
size_t num_scopes, |
| 274 |
const char ***names_ret, |
| 275 |
size_t *count_ret); |
| 276 |
|
| 277 |
/** |
| 278 |
* Find an object DIE in an array of DWARF scopes. |
| 279 |
* |
| 280 |
* @param[in] scopes Array of scopes, from outermost to innermost. |
| 281 |
* @param[in] num_scopes Number of scopes in @p scopes. |
| 282 |
* @param[out] die_ret Returned object DIE. |
| 283 |
* @param[out] type_ret If @p die_ret is a `DW_TAG_enumerator` DIE, its parent. |
| 284 |
* Otherwise, undefined. |
| 285 |
*/ |
| 286 |
struct drgn_error *drgn_find_in_dwarf_scopes(Dwarf_Die *scopes, |
| 287 |
size_t num_scopes, |
| 288 |
const char *name, |
| 289 |
Dwarf_Die *die_ret, |
| 290 |
Dwarf_Die *type_ret); |
| 291 |
|
| 292 |
/** |
| 293 |
* Create a @ref drgn_object from a `Dwarf_Die`. |
| 294 |
* |
| 295 |
* @param[in] die Object DIE (e.g., `DW_TAG_subprogram`, `DW_TAG_variable`, |
| 296 |
* `DW_TAG_formal_parameter`, `DW_TAG_enumerator`, |
| 297 |
* `DW_TAG_template_value_parameter`). |
| 298 |
* @param[in] type_die DIE of object's type. If @c NULL, use the `DW_AT_type` |
| 299 |
* attribute of @p die. If @p die is a `DW_TAG_enumerator` DIE, this should be |
| 300 |
* its parent. |
| 301 |
* @param[in] function_die DIE of current function. @c NULL if not in function |
| 302 |
* context. |
| 303 |
* @param[in] regs Registers of current stack frame. @c NULL if not in stack |
| 304 |
* frame context. |
| 305 |
* @param[out] ret Returned object. |
| 306 |
*/ |
| 307 |
struct drgn_error * |
| 308 |
drgn_object_from_dwarf(struct drgn_debug_info *dbinfo, |
| 309 |
struct drgn_elf_file *file, Dwarf_Die *die, |
| 310 |
Dwarf_Die *type_die, Dwarf_Die *function_die, |
| 311 |
const struct drgn_register_state *regs, |
| 312 |
struct drgn_object *ret); |
| 313 |
|
| 314 |
struct drgn_error *drgn_module_parse_debug_frame(struct drgn_module *module); |
| 315 |
|
| 316 |
struct drgn_error * |
| 317 |
drgn_module_find_dwarf_cfi(struct drgn_module *module, uint64_t pc, |
| 318 |
struct drgn_cfi_row **row_ret, bool *interrupted_ret, |
| 319 |
drgn_register_number *ret_addr_regno_ret); |
| 320 |
|
| 321 |
struct drgn_error *drgn_module_parse_eh_frame(struct drgn_module *module); |
| 322 |
|
| 323 |
struct drgn_error * |
| 324 |
drgn_module_find_eh_cfi(struct drgn_module *module, uint64_t pc, |
| 325 |
struct drgn_cfi_row **row_ret, bool *interrupted_ret, |
| 326 |
drgn_register_number *ret_addr_regno_ret); |
| 327 |
|
| 328 |
struct drgn_error * |
| 329 |
drgn_eval_cfi_dwarf_expression(struct drgn_program *prog, |
| 330 |
struct drgn_elf_file *file, |
| 331 |
const struct drgn_cfi_rule *rule, |
| 332 |
const struct drgn_register_state *regs, |
| 333 |
void *buf, size_t size); |
| 334 |
|
| 335 |
/** @} */ |
| 336 |
|
| 337 |
#endif /* DRGN_DEBUG_INFO_DWARF_H */ |