Debian Codegraph @

libdrgn/register_state.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 * Register state.
8 *
9 * See @ref RegisterState.
10 */
11
12 #ifndef DRGN_REGISTER_STATE_H
13 #define DRGN_REGISTER_STATE_H
14
15 #include <assert.h>
16 #include <stdlib.h>
17 #include <string.h>
18
19 #include "cfi.h"
20 #include "drgn_internal.h"
21 #include "platform.h"
22 #include "program.h"
23 #include "serialize.h"
24 #include "util.h"
25
26 /**
27 * @ingroup Internals
28 *
29 * @defgroup RegisterState Register state
30 *
31 * Buffer of processor register values.
32 *
33 * This defines @ref drgn_register_state for storing the values of processor
34 * registers.
35 *
36 * Several macros defined here take a register identifier as defined in an
37 * architecture definition file. These are intended for use in the corresponding
38 * architecture support file. These macros also have function equivalents (with
39 * names ending in `_impl`) that take the register number, offset, and size
40 * instead.
41 *
42 * @{
43 */
44
45 /**
46 * State of processor registers (e.g., in a stack frame), including the program
47 * counter and Canonical Frame Address (some of which may not be known).
48 */
49 struct drgn_register_state {
50 /**
51 * Cached @ref drgn_module that contains the program counter.
52 *
53 * This is `NULL` if the program counter is not known or if the
54 * containing module could not be found.
55 */
56 struct drgn_module *module;
57 /** Total size of registers allocated in @ref drgn_register_state::buf. */
58 uint32_t regs_size;
59 /** Number of registers allocated in @ref drgn_register_state::buf. */
60 uint16_t num_regs;
61 /** Whether this frame was interrupted (e.g., by a signal). */
62 bool interrupted;
63 /** Program counter. Access with @ref drgn_register_state_get_pc(). */
64 uint64_t _pc;
65 /**
66 * Canonical Frame Address. Access with @ref
67 * drgn_register_state_get_cfa().
68 */
69 uint64_t _cfa;
70 /**
71 * Buffer of register values followed by bitset indicating which
72 * register values are known.
73 *
74 * The layout of the register values is architecture-specific and
75 * defined by @ref DRGN_ARCH_REGISTER_LAYOUT.
76 *
77 * Bit 0 of the bitset is whether the PC is known, bit 1 is whether the
78 * CFA is known, and the remaining @ref drgn_register_state::num_regs
79 * bits are whether each register is known.
80 *
81 * Registers beyond @ref drgn_register_state::regs_size ""/@ref
82 * drgn_register_state::num_regs are not allocated here and are assumed
83 * to be unknown.
84 */
85 unsigned char buf[];
86 };
87
88 /**
89 * Return the internal register number of a register.
90 *
91 * @param[in] id Register identifier.
92 */
93 #define DRGN_REGISTER_NUMBER(id) DRGN_REGISTER_NUMBER__##id
94
95 /**
96 * Return the offset of a register in the register buffer.
97 *
98 * @param[in] id Register identifier.
99 */
100 #define DRGN_REGISTER_OFFSET(id) offsetof(struct drgn_arch_register_layout, id)
101
102 /**
103 * Return the size of a register in bytes.
104 *
105 * @param[in] id Register identifier.
106 */
107 #define DRGN_REGISTER_SIZE(id) sizeof(((struct drgn_arch_register_layout *)0)->id)
108
109 /**
110 * Return one past the last byte of a register in the register buffer.
111 *
112 * @param[in] id Register identifier.
113 */
114 #define DRGN_REGISTER_END(id) (DRGN_REGISTER_OFFSET(id) + DRGN_REGISTER_SIZE(id))
115
116 struct drgn_register_state *drgn_register_state_create_impl(uint32_t regs_size,
117 uint16_t num_regs,
118 bool interrupted);
119
120 /**
121 * Create a @ref drgn_register_state large enough to store up to and including a
122 * given register.
123 *
124 * @param[in] last_reg Identifier of last register to allocate.
125 * @param[in] interrupted @ref drgn_register_state::interrupted
126 * @return New register state on success, @c NULL on failure to allocate memory.
127 */
128 #define drgn_register_state_create(last_reg, interrupted) \
129 drgn_register_state_create_impl(DRGN_REGISTER_END(last_reg), \
130 DRGN_REGISTER_NUMBER(last_reg) + 1, \
131 interrupted)
132
133 /**
134 * Create a copy of a @ref drgn_register_state.
135 *
136 * @return New register state on success, @c NULL on failure to allocate memory.
137 */
138 struct drgn_register_state *
139 drgn_register_state_dup(const struct drgn_register_state *regs);
140
141 /** Free a @ref drgn_register_state. */
142 static inline void
143 drgn_register_state_destroy(struct drgn_register_state *regs)
144 {
145 free(regs);
146 }
147
148 /**
149 * Get whether the value of a register is known in a @ref drgn_register_state.
150 *
151 * @param[in] regno Register number to check. May be @c
152 * DRGN_REGISTER_NUMBER_UNKNOWN, in which case this always returns @c false.
153 */
154 bool drgn_register_state_has_register(const struct drgn_register_state *regs,
155 drgn_register_number regno)
156 __attribute__((__pure__));
157
158 /**
159 * Mark a register as known in a @ref drgn_register_state.
160 *
161 * @param[in] regno Register number to mark as known. Must be less than @ref
162 * drgn_register_state::num_regs.
163 */
164 void drgn_register_state_set_has_register(struct drgn_register_state *regs,
165 drgn_register_number regno);
166
167 /**
168 * Mark a range of adjacent registers as known in a @ref drgn_register_state.
169 *
170 * @param[in] first_regno First register number to mark as known (inclusive).
171 * Must be less than or equal to @p last_regno.
172 * @param[in] last_regno Last register number to mark as known (inclusive). Must
173 * be less than @ref drgn_register_state::num_regs.
174 */
175 void
176 drgn_register_state_set_has_register_range(struct drgn_register_state *regs,
177 drgn_register_number first_regno,
178 drgn_register_number last_regno);
179
180 /**
181 * Mark a register as unknown in a @ref drgn_register_state.
182 *
183 * @param[in] regno Register number to mark as unknown.
184 */
185 void drgn_register_state_unset_has_register(struct drgn_register_state *regs,
186 drgn_register_number regno);
187
188 /** A `uint64_t` which may or may not be present. */
189 struct optional_uint64 {
190 uint64_t value;
191 bool has_value;
192 };
193
194 /** Get the value of the program counter in a @ref drgn_register_state. */
195 struct optional_uint64
196 drgn_register_state_get_pc(const struct drgn_register_state *regs)
197 __attribute__((__pure__));
198
199 /**
200 * Set the value of the program counter in a @ref drgn_register_state and mark
201 * it as known.
202 */
203 void drgn_register_state_set_pc(struct drgn_program *prog,
204 struct drgn_register_state *regs, uint64_t pc);
205
206 static inline void
207 drgn_register_state_set_pc_from_register_impl(struct drgn_program *prog,
208 struct drgn_register_state *regs,
209 drgn_register_number regno,
210 size_t reg_offset,
211 size_t reg_size)
212 {
213 assert(drgn_register_state_has_register(regs, regno));
214 uint64_t pc;
215 copy_lsbytes(&pc, sizeof(pc), HOST_LITTLE_ENDIAN,
216 &regs->buf[reg_offset], reg_size,
217 drgn_platform_is_little_endian(&prog->platform));
218 drgn_register_state_set_pc(prog, regs, pc);
219 }
220
221 /**
222 * Set the value of the program counter in a @ref drgn_register_state from the
223 * value of a register and mark it as known.
224 *
225 * @param[in] reg Identifier of register to set from. Value must be known.
226 */
227 #define drgn_register_state_set_pc_from_register(prog, regs, reg) \
228 drgn_register_state_set_pc_from_register_impl(prog, regs, \
229 DRGN_REGISTER_NUMBER(reg),\
230 DRGN_REGISTER_OFFSET(reg),\
231 DRGN_REGISTER_SIZE(reg))
232
233 /**
234 * Get the value of the Canonical Frame Address in a @ref drgn_register_state.
235 */
236 struct optional_uint64
237 drgn_register_state_get_cfa(const struct drgn_register_state *regs)
238 __attribute__((__pure__));
239
240 /**
241 * Set the value of the Canonical Frame Address in a @ref drgn_register_state
242 * and mark it as known.
243 */
244 void drgn_register_state_set_cfa(struct drgn_program *prog,
245 struct drgn_register_state *regs,
246 uint64_t cfa);
247
248 struct optional_uint64
249 drgn_register_state_get_u64_impl(struct drgn_program *prog,
250 struct drgn_register_state *regs,
251 drgn_register_number regno,
252 size_t reg_offset, size_t reg_size)
253 __attribute__((__pure__));
254
255 /**
256 * Get the least significant 64 bits of a register in a @ref
257 * drgn_register_state.
258 *
259 * @param[in] reg Identifier of register to get.
260 */
261 #define drgn_register_state_get_u64(prog, regs, reg) \
262 drgn_register_state_get_u64_impl(prog, regs, \
263 DRGN_REGISTER_NUMBER(reg), \
264 DRGN_REGISTER_OFFSET(reg), \
265 DRGN_REGISTER_SIZE(reg))
266
267
268 static inline void
269 drgn_register_state_set_from_buffer_impl(struct drgn_register_state *regs,
270 drgn_register_number regno,
271 size_t reg_offset, size_t reg_size,
272 const void *buf)
273 {
274 memcpy(&regs->buf[reg_offset], buf, reg_size);
275 drgn_register_state_set_has_register(regs, regno);
276 }
277
278 /**
279 * Set the value of a register in a @ref drgn_register_state from a buffer and
280 * mark it as known.
281 *
282 * The buffer must be at least as large as the register.
283 *
284 * @param[in] reg Identifier of register to set. Number must be less than @ref
285 * drgn_register_state::num_regs.
286 */
287 #define drgn_register_state_set_from_buffer(regs, reg, buf) \
288 drgn_register_state_set_from_buffer_impl(regs, \
289 DRGN_REGISTER_NUMBER(reg), \
290 DRGN_REGISTER_OFFSET(reg), \
291 DRGN_REGISTER_SIZE(reg), \
292 buf)
293
294 static inline void
295 drgn_register_state_set_range_from_buffer_impl(struct drgn_register_state *regs,
296 drgn_register_number first_regno,
297 drgn_register_number last_regno,
298 size_t first_reg_offset,
299 size_t last_reg_end,
300 const void *buf)
301 {
302 memcpy(&regs->buf[first_reg_offset], buf,
303 last_reg_end - first_reg_offset);
304 drgn_register_state_set_has_register_range(regs, first_regno, last_regno);
305 }
306
307 /**
308 * Set the values of a range of adjacent registers in a @ref drgn_register_state
309 * from a buffer and mark them as known.
310 *
311 * @param[in] first_reg Identifier of first register to set (inclusive). Number
312 * must be less than or equal to number of @p last_reg.
313 * @param[in] last_reg Identifier of last register to set (inclusive). Number
314 * must be less than @ref drgn_register_state::num_regs.
315 */
316 #define drgn_register_state_set_range_from_buffer(regs, first_reg, last_reg, buf) \
317 drgn_register_state_set_range_from_buffer_impl(regs, \
318 DRGN_REGISTER_NUMBER(first_reg), \
319 DRGN_REGISTER_NUMBER(last_reg), \
320 DRGN_REGISTER_OFFSET(first_reg), \
321 DRGN_REGISTER_END(last_reg), \
322 buf)
323
324 static inline void
325 drgn_register_state_set_from_u64_impl(struct drgn_program *prog,
326 struct drgn_register_state *regs,
327 drgn_register_number regno,
328 size_t reg_offset, size_t reg_size,
329 uint64_t value)
330 {
331 copy_lsbytes(&regs->buf[reg_offset], reg_size,
332 drgn_platform_is_little_endian(&prog->platform), &value,
333 sizeof(value), HOST_LITTLE_ENDIAN);
334 drgn_register_state_set_has_register(regs, regno);
335 }
336
337 /**
338 * Set the value of a register in a @ref drgn_register_state from a `uint64_t`
339 * and mark it as known.
340 *
341 * If the register is smaller than 8 bytes, then the value is truncated to the
342 * least significant bytes. If it is larger, then the value is zero-extended.
343 *
344 * @param[in] reg Identifier of register to set. Number must be less than @ref
345 * drgn_register_state::num_regs.
346 */
347 #define drgn_register_state_set_from_u64(prog, regs, reg, value) \
348 drgn_register_state_set_from_u64_impl(prog, regs, \
349 DRGN_REGISTER_NUMBER(reg), \
350 DRGN_REGISTER_OFFSET(reg), \
351 DRGN_REGISTER_SIZE(reg), value)
352
353 /** @} */
354
355 #endif /* DRGN_REGISTER_STATE_H */