Debian Codegraph @

libdrgn/cfi.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 * Call frame information
8 *
9 * See @ref CallFrameInformation.
10 */
11
12 #ifndef DRGN_CFI_H
13 #define DRGN_CFI_H
14
15 #include <stdbool.h>
16 #include <stdint.h>
17 #include <stdlib.h>
18
19 /**
20 * @ingroup Internals
21 *
22 * @defgroup CallFrameInformation Call frame information
23 *
24 * Call frame information for stack unwinding.
25 *
26 * This defines a generic representation for Call Frame Information (CFI), which
27 * describes how to determine the Canonical Frame Address (CFA) and previous
28 * register values while unwinding a stack trace.
29 *
30 * @{
31 */
32
33 /**
34 * Numeric identifier for a register.
35 *
36 * These are only unique within an architecture, and they are not necessarily
37 * the same as the register numbers used by DWARF.
38 */
39 typedef uint16_t drgn_register_number;
40
41 /** Maximum valid register number. */
42 #define DRGN_MAX_REGISTER_NUMBER ((drgn_register_number)-3)
43 /** Placeholder number for unknown register. */
44 #define DRGN_REGISTER_NUMBER_UNKNOWN ((drgn_register_number)-1)
45
46 /** Kinds of CFI rules. */
47 enum drgn_cfi_rule_kind {
48 /** Register value in the caller is not known. */
49 DRGN_CFI_RULE_UNDEFINED,
50 /**
51 * Register value in the caller is stored at the CFA in the current
52 * frame plus an offset: `*(cfa + offset)`.
53 */
54 DRGN_CFI_RULE_AT_CFA_PLUS_OFFSET,
55 /**
56 * Register value in the caller is the CFA in the current frame plus an
57 * offset: `cfa + offset`.
58 */
59 DRGN_CFI_RULE_CFA_PLUS_OFFSET,
60 /**
61 * Register value in the caller is stored at the value of a register in
62 * the current frame plus an offset: `*(reg + offset)`.
63 */
64 DRGN_CFI_RULE_AT_REGISTER_PLUS_OFFSET,
65 /**
66 * Register value in the caller is an offset plus the value stored at
67 * the value of a register in the current frame: `(*reg) + offset`.
68 */
69 DRGN_CFI_RULE_AT_REGISTER_ADD_OFFSET,
70 /**
71 * Register value in the caller is the value of a register in the
72 * current frame plus an offset: `reg + offset`.
73 *
74 * Note that this can also be used to represent DWARF's "same value"
75 * rule by using the same register with an offset of 0.
76 */
77 DRGN_CFI_RULE_REGISTER_PLUS_OFFSET,
78 /**
79 * Register value in the caller is stored at the address given by a
80 * DWARF expression.
81 */
82 DRGN_CFI_RULE_AT_DWARF_EXPRESSION,
83 /** Register value in the caller is given by a DWARF expression. */
84 DRGN_CFI_RULE_DWARF_EXPRESSION,
85 /** Register value in the caller has a constant value. */
86 DRGN_CFI_RULE_CONSTANT,
87 } __attribute__((__packed__));
88
89 /** Rule for determining a single register value or CFA. */
90 struct drgn_cfi_rule {
91 /** Rule kind. */
92 enum drgn_cfi_rule_kind kind;
93 /**
94 * Whether to push the CFA before evaluating the DWARF
95 * expression for @ref DRGN_CFI_RULE_AT_DWARF_EXPRESSION or @ref
96 * DRGN_CFI_RULE_DWARF_EXPRESSION.
97 */
98 bool push_cfa;
99 /** Register number for @ref DRGN_CFI_RULE_REGISTER_PLUS_OFFSET. */
100 drgn_register_number regno;
101 union {
102 /**
103 * Offset for @ref DRGN_CFI_RULE_AT_CFA_PLUS_OFFSET, @ref
104 * DRGN_CFI_RULE_CFA_PLUS_OFFSET, @ref
105 * DRGN_CFI_RULE_AT_REGISTER_PLUS_OFFSET, @ref
106 * DRGN_CFI_RULE_AT_REGISTER_ADD_OFFSET, and @ref
107 * DRGN_CFI_RULE_REGISTER_PLUS_OFFSET.
108 */
109 int64_t offset;
110 /** Constant for @ref DRGN_CFI_RULE_CONSTANT. */
111 uint64_t constant;
112 /**
113 * DWARF expression for @ref DRGN_CFI_RULE_AT_DWARF_EXPRESSION
114 * and @ref DRGN_CFI_RULE_DWARF_EXPRESSION.
115 */
116 struct {
117 /** Pointer to expression data. */
118 const char *expr;
119 /** Size of @ref drgn_cfi_rule::expr. */
120 size_t expr_size;
121 };
122 };
123 };
124
125 /**
126 * "Row" of call frame information, i.e., how to get the CFA and the previous
127 * value of each register at a single location in the program.
128 *
129 * A row may be allocated statically or on the heap. Static rows are created
130 * with @ref DRGN_CFI_ROW(). The first time a static row would be modified (with
131 * @ref drgn_cfi_row_copy(), @ref drgn_cfi_row_set_cfa(), or @ref
132 * drgn_cfi_row_set_register()), it is first copied to the heap. Subsequent
133 * modifications reuse the heap allocation, growing it if necessary. The
134 * allocation must be freed with @ref drgn_cfi_row_destroy().
135 */
136 struct drgn_cfi_row {
137 /**
138 * Number of rules allocated, including the CFA rule.
139 *
140 * If the row is statically allocated, then this is zero, even if
141 * `num_regs` is non-zero. Otherwise, it is at least `num_regs + 1`.
142 */
143 uint16_t allocated_rules;
144 /** Number of initialized elements in `reg_rules`. */
145 uint16_t num_regs;
146 /** Canonical Frame Address rule. */
147 struct drgn_cfi_rule cfa_rule;
148 /** Register rules. */
149 struct drgn_cfi_rule reg_rules[];
150 };
151
152 /**
153 * Initializer for a static @ref drgn_cfi_row given initializers for @ref
154 * drgn_cfi_row::reg_rules.
155 */
156 #define DRGN_CFI_ROW(...) { \
157 .num_regs = (sizeof((struct drgn_cfi_rule []){ __VA_ARGS__ }) \
158 / sizeof(struct drgn_cfi_rule)), \
159 .reg_rules = { __VA_ARGS__ }, \
160 }
161
162 /**
163 * Initializer for a rule in @ref drgn_cfi_row::reg_rules specifying that the
164 * register with the given number has the same value in the caller.
165 */
166 #define DRGN_CFI_SAME_VALUE_INIT(number) \
167 [(number)] = { \
168 .kind = DRGN_CFI_RULE_REGISTER_PLUS_OFFSET, \
169 .regno = (number), \
170 }
171
172 extern const struct drgn_cfi_row drgn_empty_cfi_row_impl;
173 /**
174 * Static @ref drgn_cfi_row with all rules set to @ref DRGN_CFI_RULE_UNDEFINED.
175 */
176 #define drgn_empty_cfi_row ((struct drgn_cfi_row *)&drgn_empty_cfi_row_impl)
177
178 /** Free a @ref drgn_cfi_row. */
179 static inline void drgn_cfi_row_destroy(struct drgn_cfi_row *row)
180 {
181 if (row->allocated_rules > 0)
182 free(row);
183 }
184
185 /** Copy the rules from one @ref drgn_cfi_row to another. */
186 bool drgn_cfi_row_copy(struct drgn_cfi_row **dst,
187 const struct drgn_cfi_row *src);
188
189 /**
190 * Get the rule for the Canonical Frame Address in a @ref drgn_cfi_row.
191 *
192 * @param[out] ret Returned rule.
193 */
194 static inline void drgn_cfi_row_get_cfa(const struct drgn_cfi_row *row,
195 struct drgn_cfi_rule *ret)
196 {
197 *ret = row->cfa_rule;
198 }
199
200 /**
201 * Set the rule for the Canonical Frame Address in a @ref drgn_cfi_row.
202 *
203 * @param[in] rule Rule to set to.
204 * @return @c true on success, @c false on failure to allocate memory.
205 */
206 bool drgn_cfi_row_set_cfa(struct drgn_cfi_row **row,
207 const struct drgn_cfi_rule *rule);
208
209 /**
210 * Get the rule for a register in a @ref drgn_cfi_row.
211 *
212 * @param[in] regno Register number.
213 */
214 void drgn_cfi_row_get_register(const struct drgn_cfi_row *row,
215 drgn_register_number regno,
216 struct drgn_cfi_rule *ret);
217
218 /**
219 * Set the rule for a register in a @ref drgn_cfi_row.
220 *
221 * @param[in] regno Register number.
222 * @param[in] rule Rule to set to.
223 * @return @c true on success, @c false on failure to allocate memory.
224 */
225 bool drgn_cfi_row_set_register(struct drgn_cfi_row **row,
226 drgn_register_number regno,
227 const struct drgn_cfi_rule *rule);
228
229 /** @} */
230
231 #endif /* DRGN_CFI_H */