Debian Codegraph @

libdrgn/dwarf_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 * 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 */