Debian Codegraph @

libdrgn/symbol.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // Copyright (c) 2024, Oracle and/or its affiliates.
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4
5 #ifndef DRGN_SYMBOL_H
6 #define DRGN_SYMBOL_H
7
8 #include <gelf.h>
9
10 #include "cleanup.h"
11 #include "drgn_internal.h"
12 #include "handler.h"
13 #include "hash_table.h"
14 #include "string_builder.h"
15 #include "vector.h"
16
17 struct drgn_symbol {
18 const char *name;
19 uint64_t address;
20 uint64_t size;
21 enum drgn_symbol_binding binding;
22 enum drgn_symbol_kind kind;
23 enum drgn_lifetime name_lifetime;
24 enum drgn_lifetime lifetime;
25 };
26
27 struct drgn_symbol_finder {
28 struct drgn_handler handler;
29 struct drgn_symbol_finder_ops ops;
30 void *arg;
31 };
32
33 DEFINE_VECTOR_TYPE(symbolp_vector, struct drgn_symbol *);
34
35 struct drgn_symbol_result_builder {
36 bool one;
37 union {
38 struct symbolp_vector vector;
39 struct drgn_symbol *single;
40 };
41 };
42
43 #define _cleanup_symbol_ _cleanup_(drgn_symbol_cleanup)
44 static inline void drgn_symbol_cleanup(struct drgn_symbol **p)
45 {
46 drgn_symbol_destroy(*p);
47 }
48
49 /** Destroy the contents of the result builder */
50 void drgn_symbol_result_builder_abort(struct drgn_symbol_result_builder *builder);
51
52 /** Initialize result builder */
53 void drgn_symbol_result_builder_init(struct drgn_symbol_result_builder *builder,
54 bool one);
55
56 /**
57 * Convert an ELF symbol to a @ref drgn_symbol and add it to a result builder.
58 *
59 * @return @c true on success, @c false on failure to allocate memory.
60 */
61 bool
62 drgn_symbol_result_builder_add_from_elf(struct drgn_symbol_result_builder *builder,
63 const char *name, uint64_t address,
64 const GElf_Sym *elf_sym);
65
66 /** Return single result */
67 struct drgn_symbol *
68 drgn_symbol_result_builder_single(struct drgn_symbol_result_builder *builder);
69
70 /** Return array result */
71 void drgn_symbol_result_builder_array(struct drgn_symbol_result_builder *builder,
72 struct drgn_symbol ***syms_ret, size_t *count_ret);
73
74 struct drgn_error *
75 drgn_symbol_copy(struct drgn_symbol *dst, struct drgn_symbol *src);
76
77 DEFINE_HASH_MAP(drgn_symbol_name_table, const char *,
78 struct { uint32_t start; uint32_t end; },
79 c_string_key_hash_pair, c_string_key_eq);
80
81 /**
82 * An index of symbols, supporting efficient lookup by name or address
83 *
84 * While the dynamic symbol finding callback is a very flexible API, many use
85 * cases can be served best by simply providing drgn with a known symbol table
86 * to index. Drgn can efficiently implement the name and address lookup
87 * functions once, and provide a symbol finder implementation, so that clients
88 * need not redo this boilerplate.
89 *
90 * In the interest of simplicity, the index is immutable once created. This
91 * allows us to use simple data structures. If the symbol table needs frequent
92 * updates, then registering a custom symbol finder should be preferred.
93 */
94 struct drgn_symbol_index {
95 /** Array of symbols, in sorted order by address */
96 struct drgn_symbol *symbols;
97
98 /** Array of max_addr, to aid address lookup */
99 uint64_t *max_addrs;
100
101 /** Number of symbols */
102 uint32_t num_syms;
103
104 /** The buffer containing all symbol names */
105 char *strings;
106
107 /** Array of symbol indices, sorted by name. Used by the htab. */
108 uint32_t *name_sort;
109
110 /** Map of symbol names to index */
111 struct drgn_symbol_name_table htab;
112 };
113
114 /**
115 * Create a symbol index from an array of symbols
116 *
117 * This takes ownership of the symbol array and the individual symbols. The @a
118 * buffer argument allows us to provide a single backing buffer for all strings
119 * (in which case the lifetimes of each symbol name should be static). On error
120 * @a symbols and @a buffer are already freed, since the builder took ownership
121 * of them.
122 */
123 struct drgn_error *
124 drgn_symbol_index_init(struct drgn_symbol *symbols, uint32_t count,
125 char *buffer, struct drgn_symbol_index *ret);
126
127 /** Deinitialize the symbol index. Safe to call multiple times. */
128 void drgn_symbol_index_deinit(struct drgn_symbol_index *index);
129
130 DEFINE_VECTOR_TYPE(symbol_vector, struct drgn_symbol);
131
132 struct drgn_symbol_index_builder {
133 struct string_builder names;
134 struct symbol_vector symbols;
135 };
136
137 /**
138 * Create a symbol builder which will efficiently pack string names next
139 * to each other in memory, rather than allocating many small strings.
140 */
141 void
142 drgn_symbol_index_builder_init(struct drgn_symbol_index_builder *builder);
143
144 /**
145 * For destroying a builder on error conditions. It is safe to call this
146 * multiple times, including after drgn_symbol_index_init_from_builder().
147 */
148 void
149 drgn_symbol_index_builder_deinit(struct drgn_symbol_index_builder *builder);
150
151 /**
152 * Add symbol to the builder: the builder does not take ownership of @a ptr,
153 * instead making a copy.
154 */
155 bool
156 drgn_symbol_index_builder_add(struct drgn_symbol_index_builder *builder,
157 const struct drgn_symbol *ptr);
158
159 /**
160 * Convert the builder to a symbol index, destroying the builder.
161 * On error, the builder and symbol index are both deinitialized, requiring no
162 * further cleanup.
163 */
164 struct drgn_error *
165 drgn_symbol_index_init_from_builder(struct drgn_symbol_index *index,
166 struct drgn_symbol_index_builder *builder);
167
168 /**
169 * The actual implementation of the Symbol Finder API.
170 */
171 struct drgn_error *
172 drgn_symbol_index_find(const char *name, uint64_t address,
173 enum drgn_find_symbol_flags flags, void *arg,
174 struct drgn_symbol_result_builder *builder);
175
176 #endif /* DRGN_SYMBOL_H */