Debian Codegraph @

libdrgn/platform.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 * Platform internals
8 *
9 * See @ref PlatformInternals.
10 */
11
12 #ifndef DRGN_PLATFORM_H
13 #define DRGN_PLATFORM_H
14
15 #include <gelf.h>
16 #include <inttypes.h>
17
18 #include "cfi.h"
19 #include "drgn_internal.h"
20 #include "util.h"
21
22 struct drgn_orc_entry;
23 struct drgn_register_state;
24
25 /**
26 * @ingroup Internals
27 *
28 * @defgroup PlatformInternals Platforms
29 *
30 * Platform internals.
31 *
32 * drgn's external representation of a platform is @ref drgn_platform.
33 * Internally, architecture-specific handling is mainly in @ref
34 * drgn_architecture_info. See @ref drgn_architecture_info for instructions on
35 * adding support for a new architecture.
36 *
37 * @{
38 */
39
40 struct drgn_register {
41 /** Human-readable names of this register. */
42 const char * const *names;
43 /** Number of names in @ref names. */
44 size_t num_names;
45 /** Internal register number. */
46 drgn_register_number regno;
47 };
48
49 /** Offset and size of a register in @ref drgn_register_state::buf. */
50 struct drgn_register_layout {
51 uint32_t offset;
52 uint32_t size;
53 };
54
55 // This is an ugly layering violation needed for DW_CFA_AARCH64_negate_ra_state.
56 // We enforce that it stays up to date with a static_assert() in arch_aarch64.c.
57 #define DRGN_AARCH64_RA_SIGN_STATE_REGNO 0
58
59 struct drgn_error *
60 drgn_orc_to_cfi_x86_64(const struct drgn_orc_entry *orc,
61 struct drgn_cfi_row **row_ret, bool *interrupted_ret,
62 drgn_register_number *ret_addr_regno_ret);
63
64 /** ELF section to apply relocations to. */
65 struct drgn_relocating_section {
66 char *buf;
67 size_t buf_size;
68 uint64_t addr;
69 bool bswap;
70 };
71
72 extern struct drgn_error drgn_invalid_relocation_offset;
73
74 #ifdef DOXYGEN
75 /**
76 * Apply an ELF relocation as:
77 *
78 * - `*dst = addend + *r_addend` if `r_addend` is not `NULL` (for `ElfN_Rela`)
79 * - `*dst += addend` if `r_addend` is `NULL` (for `ElfN_Rel`)
80 *
81 * Where `dst = (uintN_t *)(relocating->buf + r_offset)`.
82 *
83 * This checks bounds and handles unaligned destinations and byte swapping. It
84 * does not check for overflow.
85 *
86 * This is defined for N of 8, 16, 32, and 64.
87 */
88 struct drgn_error *
89 drgn_reloc_addN(const struct drgn_relocating_section *relocating,
90 uint64_t r_offset, const int64_t *r_addend, uintN_t addend);
91 #endif
92
93 struct drgn_error *
94 drgn_reloc_add64(const struct drgn_relocating_section *relocating,
95 uint64_t r_offset, const int64_t *r_addend, uint64_t addend);
96 struct drgn_error *
97 drgn_reloc_add32(const struct drgn_relocating_section *relocating,
98 uint64_t r_offset, const int64_t *r_addend, uint32_t addend);
99 struct drgn_error *
100 drgn_reloc_add16(const struct drgn_relocating_section *relocating,
101 uint64_t r_offset, const int64_t *r_addend, uint16_t addend);
102 struct drgn_error *
103 drgn_reloc_add8(const struct drgn_relocating_section *relocating,
104 uint64_t r_offset, const int64_t *r_addend, uint8_t addend);
105
106 /** Create an error for an unknown ELF relocation type. */
107 #define DRGN_UNKNOWN_RELOCATION_TYPE(r_type) \
108 drgn_error_format(DRGN_ERROR_OTHER, \
109 "unknown relocation type %" PRIu32 " in %s; " \
110 "please report this to %s", \
111 (r_type), __func__, PACKAGE_BUGREPORT)
112
113 /**
114 * Apply an ELF relocation. If @p r_addend is `NULL`, then this is an `ElfN_Rel`
115 * relocation. Otherwise, this is an `ElfN_Rela` relocation.
116 */
117 typedef struct drgn_error *
118 apply_elf_reloc_fn(const struct drgn_relocating_section *relocating,
119 uint64_t r_offset, uint32_t r_type, const int64_t *r_addend,
120 uint64_t sym_value);
121
122 /** Page table iterator. */
123 struct pgtable_iterator {
124 /** Address of the top-level page table to iterate. */
125 uint64_t pgtable;
126 /** Current virtual address to translate. */
127 uint64_t virt_addr;
128 };
129
130 /**
131 * Translate the current virtual address from a page table iterator.
132 *
133 * Abstractly, a virtual address lies in a range of addresses in the address
134 * space. A range may be a mapped page, a page table gap, or a range of invalid
135 * addresses (e.g., non-canonical addresses on x86-64). This finds the range
136 * containing the current virtual address (`it->virt_addr`), returns the first
137 * virtual address of that range and the physical address it maps to (if any),
138 * and updates `it->virt_addr` to the end of the range.
139 *
140 * This does not merge contiguous ranges. For example, if two adjacent mapped
141 * pages have adjacent physical addresses, this returns each page separately.
142 * This makes it possible to distinguish between contiguous pages and "huge
143 * pages" on architectures that support different page sizes. Similarly, if two
144 * adjacent entries at level 2 of the page table are empty, this returns each
145 * gap separately.
146 *
147 * @param[in] it Iterator.
148 * @param[out] virt_addr_ret Returned first virtual address in the range
149 * containing the current virtual address.
150 * @param[out] phys_addr_ret Returned physical address that @p virt_addr_ret
151 * maps to, or @c UINT64_MAX if it is not mapped.
152 */
153 typedef struct drgn_error *
154 (pgtable_iterator_next_fn)(struct drgn_program *prog,
155 struct pgtable_iterator *it, uint64_t *virt_addr_ret,
156 uint64_t *phys_addr_ret);
157
158 /**
159 * Architecture-specific information and callbacks.
160 *
161 * To add the bare minimum support for recognizing a new architecture:
162 *
163 * - Add a `DRGN_ARCH_FOO` enumerator to @ref drgn_architecture.
164 * - Add the constant to `class Architecture` in `_drgn.pyi`.
165 * - Create a new `libdrgn/arch_foo.c` file and add it to
166 * `libdrgnimpl_la_SOURCES` in `libdrgn/Makefile.am`.
167 * - Define `struct drgn_architecture_info arch_info_foo` in
168 * `libdrgn/arch_foo.c` with the following members:
169 * - @ref name
170 * - @ref arch
171 * - @ref default_flags
172 * - @ref scalar_alignment
173 * - @ref register_by_name = @ref drgn_register_by_name_unknown
174 * - Add an `extern` declaration of `arch_info_foo` to `libdrgn/platform.h`.
175 * - Handle the architecture in @ref drgn_platform_from_kdump(), @ref
176 * drgn_host_platform, @ref drgn_platform_create(), @ref
177 * drgn_platform_from_elf(), and @ref qmp_detect_platform().
178 * - Update `docs/support_matrix.rst`.
179 *
180 * To support Linux kernel loadable modules:
181 *
182 * - Define @ref apply_elf_reloc.
183 * - Update `docs/support_matrix.rst`.
184 *
185 * To support stack unwinding:
186 *
187 * - Create a new `libdrgn/arch_foo_defs.py` file. See
188 * `libdrgn/build-aux/gen_arch_inc_strswitch.py`.
189 * - Add `arch_foo_defs.py` to `ARCH_DEFS_PYS` and remove `libdrgn/arch_foo.c`
190 * from `libdrgnimpl_la_SOURCES` in `libdrgn/Makefile.am`.
191 * - Add `#include "arch_foo_defs.inc"` to `libdrgn/arch_foo.c`.
192 * - Add `DRGN_ARCHITECTURE_REGISTERS` to `arch_info_foo` and remove @ref
193 * register_by_name.
194 * - Define the following @ref drgn_architecture_info members:
195 * - @ref default_dwarf_cfi_row (use @ref DRGN_CFI_ROW)
196 * - @ref fallback_unwind
197 * - @ref bad_call_unwind
198 * - @ref pt_regs_get_initial_registers
199 * - @ref prstatus_get_initial_registers
200 * - @ref linux_kernel_get_initial_registers
201 * - @ref demangle_cfi_registers (only if needed)
202 * - Implement `drgn_test_get_pt_regs()` in
203 * `tests/linux_kernel/kmod/drgn_test.c` (usually by copying
204 * `crash_setup_regs()` from the Linux kernel).
205 * - Add the architecture name to `skip_unless_have_stack_tracing()` in
206 * `tests/linux_kernel/__init__.py`.
207 * - Update `docs/support_matrix.rst`.
208 *
209 * To support virtual address translation:
210 *
211 * - Define the @ref drgn_architecture_info page table iterator members:
212 * - @ref linux_kernel_pgtable_iterator_create
213 * - @ref linux_kernel_pgtable_iterator_destroy
214 * - @ref linux_kernel_pgtable_iterator_init
215 * - @ref linux_kernel_pgtable_iterator_next
216 * - Define the SPARSEMEM constant fallback getters if applicable:
217 * - @ref linux_kernel_section_size_bits_fallback
218 * - @ref linux_kernel_max_physmem_bits_fallback
219 * - Add the architecture name to `HAVE_FULL_MM_SUPPORT` in
220 * `tests/linux_kernel/__init__.py`.
221 * - Update `docs/support_matrix.rst`.
222 *
223 * This is an example of how the page table iterator members may be used
224 * (ignoring error handling):
225 *
226 * ```
227 * // Create the iterator.
228 * struct pgtable_iterator *it;
229 * arch->linux_kernel_pgtable_iterator_create(prog, &it);
230 *
231 * // Initialize the iterator to translate virtual address 0x80000000 using
232 * // the page table "pgtable".
233 * it->pgtable = pgtable;
234 * it->virt_addr = 0x80000000;
235 * arch->linux_kernel_pgtable_iterator_init(prog, it);
236 * // Iterate up to virtual address 0x90000000.
237 * while (it->virt_addr < 0x90000000) {
238 * uint64_t virt_addr, phys_addr;
239 * arch->linux_kernel_pgtable_iterator_next(prog, it, &virt_addr,
240 * &phys_addr);
241 * if (phys_addr == UINT64_MAX) {
242 * printf("Virtual address range 0x%" PRIx64 "-0x%" PRIx64
243 * " is not mapped\n",
244 * virt_addr, it->virt_addr);
245 * } else {
246 * printf("Virtual address range 0x%" PRIx64 "-0x%" PRIx64
247 * " maps to physical address 0x%" PRIx64 "\n",
248 * virt_addr, phys_addr);
249 * }
250 * }
251 *
252 * // Reuse the iterator to translate a different address using a different page
253 * // table.
254 * it->pgtable = another_pgtable;
255 * it->virt_addr = 0x11110000;
256 * uint64_t virt_addr, phys_addr;
257 * arch->linux_kernel_pgtable_iterator_next(prog, it, &virt_addr, &phys_addr);
258 * if (phys_addr != UINT64_MAX) {
259 * printf("Virtual address 0x11110000 maps to physical address 0x%" PRIx64 "\n",
260 * phys_addr + (0x11110000 - virt_addr));
261 * }
262 *
263 * // Free the iterator now that we're done with it.
264 * arch->linux_kernel_pgtable_iterator_destroy(prog, &it);
265 * ```
266 */
267 struct drgn_architecture_info {
268 /** Human-readable name of this architecture. */
269 const char *name;
270 /** Architecture identifier. */
271 enum drgn_architecture arch;
272 /**
273 * Flags to set for the platform if we're not getting them from
274 * elsewhere (like from an ELF file).
275 */
276 enum drgn_platform_flags default_flags;
277 /**
278 * Default alignment of scalar types by size.
279 *
280 * `scalar_alignment[i]` is the default alignment of a scalar type with
281 * 2<sup>i</sup> &le; `sizeof(type)` < 2<sup>i+1</sup>.
282 *
283 * This may not be enough to get the correct alignment of some
284 * implementation-defined extended types, but for now it's good enough.
285 *
286 * You can generate this for a new architecture using
287 * `scripts/scalar_alignment.c`.
288 */
289 unsigned char scalar_alignment[5];
290 /**
291 * Registers visible to the public API.
292 *
293 * This is set by `DRGN_ARCHITECTURE_REGISTERS`.
294 */
295 const struct drgn_register *registers;
296 /**
297 * Number of registers in @ref registers.
298 *
299 * This is set by `DRGN_ARCHITECTURE_REGISTERS`.
300 */
301 size_t num_registers;
302 /**
303 * Internal register number of stack pointer.
304 *
305 * This is set by `DRGN_ARCHITECTURE_REGISTERS`.
306 */
307 drgn_register_number stack_pointer_regno;
308 /**
309 * Return the API-visible register with the given name, or @c NULL if it
310 * is not recognized.
311 *
312 * This is set by `DRGN_ARCHITECTURE_REGISTERS`. It cannot be `NULL`.
313 * Set it to @ref drgn_register_by_name_unknown if not using
314 * `DRGN_ARCHITECTURE_REGISTERS`.
315 */
316 const struct drgn_register *(*register_by_name)(const char *name);
317 /**
318 * Internal register layouts indexed by internal register number.
319 *
320 * This is set by `DRGN_ARCHITECTURE_REGISTERS`.
321 */
322 const struct drgn_register_layout *register_layout;
323 /**
324 * Return the internal register number for the given DWARF register
325 * number, or @ref DRGN_REGISTER_NUMBER_UNKNOWN if it is not recognized.
326 *
327 * This is set by `DRGN_ARCHITECTURE_REGISTERS`.
328 */
329 drgn_register_number (*dwarf_regno_to_internal)(uint64_t);
330 /** CFI row containing default rules for DWARF CFI. */
331 const struct drgn_cfi_row *default_dwarf_cfi_row;
332 /**
333 * Replace mangled registers unwound by CFI with their actual values.
334 *
335 * This should be `NULL` if not needed.
336 */
337 void (*demangle_cfi_registers)(struct drgn_program *,
338 struct drgn_register_state *);
339 /**
340 * Try to unwind a stack frame if CFI wasn't found. Returns &@ref
341 * drgn_stop if we couldn't.
342 *
343 * This typically uses something like frame pointers. If this has to
344 * read memory, translate @ref DRGN_ERROR_FAULT errors to &@ref
345 * drgn_stop.
346 */
347 struct drgn_error *(*fallback_unwind)(struct drgn_program *,
348 struct drgn_register_state *,
349 struct drgn_register_state **);
350 /**
351 * Try to unwind a stack frame assuming that a call was made to a bad
352 * program counter.
353 *
354 * This should typically undo the effects of a single call instruction
355 * and nothing more. If this has to read memory, translate @ref
356 * DRGN_ERROR_FAULT errors to &@ref drgn_stop.
357 */
358 struct drgn_error *(*bad_call_unwind)(struct drgn_program *,
359 struct drgn_register_state *,
360 struct drgn_register_state **);
361 /**
362 * Create a @ref drgn_register_state from a Linux `struct pt_regs`.
363 *
364 * This should check that the object is sufficiently large with @ref
365 * drgn_object_size(), call @ref drgn_register_state_create() with
366 * `interrupted = true`, and initialize it from the contents of @ref
367 * drgn_object_buffer().
368 *
369 * @param[in] obj `struct pt_regs` as a value buffer object.
370 * @param[out] ret Returned registers.
371 */
372 struct drgn_error *(*pt_regs_get_initial_registers)(const struct drgn_object *obj,
373 struct drgn_register_state **ret);
374 /**
375 * Create a @ref drgn_register_state from the contents of an ELF
376 * `NT_PRSTATUS` note.
377 *
378 * This should check that @p size is sufficiently large, call @ref
379 * drgn_register_state_create() with `interrupted = true`, and
380 * initialize it from @p prstatus.
381 *
382 * Refer to `struct elf_prstatus` in the Linux kernel source for the
383 * format, and in particular, the `elf_gregset_t pr_reg` member.
384 * `elf_gregset_t` has an architecture-specific layout; on many
385 * architectures, it is identical to or a prefix of `struct pt_regs`.
386 * `pr_reg` is typically at offset 112 on 64-bit platforms and 72 on
387 * 32-bit platforms.
388 *
389 * @param[in] prstatus Buffer of `NT_PRSTATUS` contents.
390 * @param[in] size Size of @p prstatus in bytes.
391 * @param[out] ret Returned registers.
392 */
393 struct drgn_error *(*prstatus_get_initial_registers)(struct drgn_program *prog,
394 const void *prstatus,
395 size_t size,
396 struct drgn_register_state **ret);
397 /**
398 * Create a @ref drgn_register_state from the `struct task_struct` of a
399 * scheduled-out Linux kernel thread.
400 *
401 * This should should call @ref drgn_register_state_create() with
402 * `interrupted = false` and initialize it from the saved thread
403 * context.
404 *
405 * Refer to this architecture's implementation of `switch_to()` in the
406 * Linux kernel, which usually saves the context to one of these places:
407 *
408 * - `struct thread_struct` (`struct task_struct::thread`).
409 * - The thread stack (`struct task_struct::stack`).
410 * - `struct thread_info` (either `struct task_struct::thread_info` or
411 * on the stack, see `task_thread_info()` in the Linux kernel).
412 *
413 * @param[in] task_obj `struct task_struct` object.
414 * @param[out] ret Returned registers.
415 */
416 struct drgn_error *(*linux_kernel_get_initial_registers)(const struct drgn_object *task_obj,
417 struct drgn_register_state **ret);
418 /**
419 * Apply an ELF relocation.
420 *
421 * This should use the pre-defined @ref drgn_reloc_addN() functions
422 * whenever possible. Note that this is only used to relocate debugging
423 * information sections, so typically only simple absolute and
424 * PC-relative relocations need to be implemented.
425 */
426 apply_elf_reloc_fn *apply_elf_reloc;
427 /**
428 * Return the address and size of the direct mapping virtual address
429 * range.
430 *
431 * This is a hack which is only called when debugging a live Linux
432 * kernel older than v4.11.
433 */
434 struct drgn_error *(*linux_kernel_live_direct_mapping_fallback)(struct drgn_program *prog,
435 uint64_t *address_ret,
436 uint64_t *size_ret);
437 /**
438 * Return the address of the direct mapping virtual address range.
439 *
440 * This hook is used for @ref linux_helper_direct_mapping_offset(). It
441 * is optional: if not provided, we can infer it using a page table walk
442 * and a symbol from the direct mapping.
443 */
444 struct drgn_error *(*linux_kernel_direct_mapping_offset)(struct drgn_program *prog,
445 uint64_t *address_ret);
446 /** Allocate a Linux kernel page table iterator. */
447 struct drgn_error *(*linux_kernel_pgtable_iterator_create)(struct drgn_program *,
448 struct pgtable_iterator **);
449 /** Free a Linux kernel page table iterator. */
450 void (*linux_kernel_pgtable_iterator_destroy)(struct pgtable_iterator *);
451 /**
452 * (Re)initialize a Linux kernel page table iterator.
453 *
454 * This is called each time that the iterator will be used to translate
455 * a contiguous range of virtual addresses from a single page table. It
456 * is called with @ref pgtable_iterator::pgtable set to the address of
457 * the page table to use and @ref pgtable_iterator::virt_addr set to the
458 * starting virtual address to translate.
459 */
460 void (*linux_kernel_pgtable_iterator_init)(struct drgn_program *,
461 struct pgtable_iterator *);
462 /**
463 * Iterate a (user or kernel) page table in the Linux kernel.
464 *
465 * This is called after @ref linux_kernel_pgtable_iterator_init() to
466 * translate the starting address and may be called again without
467 * reinitializing the iterator to translate subsequent adjacent
468 * addresses in the same page table.
469 *
470 * If the caller needs to translate from a different page table or
471 * virtual address, it will call @ref
472 * linux_kernel_pgtable_iterator_init() before calling this function
473 * again.
474 *
475 * @see pgtable_iterator_next_fn
476 */
477 pgtable_iterator_next_fn *linux_kernel_pgtable_iterator_next;
478 /**
479 * Get the value of `SECTION_SIZE_BITS` for Linux kernel versions before
480 * v5.13.
481 */
482 int (*linux_kernel_section_size_bits_fallback)(struct drgn_program *);
483 /**
484 * Get the value of `MAX_PHYSMEM_BITS` for Linux kernel versions before
485 * v5.9.
486 *
487 * If this is omitted but @ref linux_kernel_section_size_bits_fallback
488 * is defined, then this will be computed from `NR_SECTION_ROOTS` and
489 * `SECTION_SIZE_BITS` instead.
490 */
491 int (*linux_kernel_max_physmem_bits_fallback)(struct drgn_program *);
492 /**
493 * Return the canonical form of a virtual address, i.e. apply any
494 * transformations that the CPU applies to the address before page
495 * table walking.
496 */
497 uint64_t (*untagged_addr)(uint64_t addr);
498 };
499
500 /**
501 * Implementation of @ref drgn_architecture_info::register_by_name that always
502 * returns `NULL`.
503 */
504 const struct drgn_register *drgn_register_by_name_unknown(const char *name);
505
506 extern const struct drgn_architecture_info arch_info_unknown;
507 extern const struct drgn_architecture_info arch_info_x86_64;
508 extern const struct drgn_architecture_info arch_info_i386;
509 extern const struct drgn_architecture_info arch_info_aarch64;
510 extern const struct drgn_architecture_info arch_info_arm;
511 extern const struct drgn_architecture_info arch_info_ppc64;
512 extern const struct drgn_architecture_info arch_info_riscv64;
513 extern const struct drgn_architecture_info arch_info_riscv32;
514 extern const struct drgn_architecture_info arch_info_s390x;
515 extern const struct drgn_architecture_info arch_info_s390;
516
517 struct drgn_platform {
518 const struct drgn_architecture_info *arch;
519 enum drgn_platform_flags flags;
520 };
521
522 static inline bool drgn_platforms_equal(const struct drgn_platform *a,
523 const struct drgn_platform *b)
524 {
525 return a->arch == b->arch && a->flags == b->flags;
526 }
527
528 static inline bool
529 drgn_platform_is_little_endian(const struct drgn_platform *platform)
530 {
531 return platform->flags & DRGN_PLATFORM_IS_LITTLE_ENDIAN;
532 }
533
534 static inline bool drgn_platform_bswap(const struct drgn_platform *platform)
535 {
536 return drgn_platform_is_little_endian(platform) != HOST_LITTLE_ENDIAN;
537 }
538
539 static inline bool drgn_platform_is_64_bit(const struct drgn_platform *platform)
540 {
541 return platform->flags & DRGN_PLATFORM_IS_64_BIT;
542 }
543
544 static inline uint8_t
545 drgn_platform_address_size(const struct drgn_platform *platform)
546 {
547 return drgn_platform_is_64_bit(platform) ? 8 : 4;
548 }
549
550 static inline uint64_t
551 drgn_platform_address_mask(const struct drgn_platform *platform)
552 {
553 return drgn_platform_is_64_bit(platform) ? UINT64_MAX : UINT32_MAX;
554 }
555
556 /**
557 * Initialize a @ref drgn_platform from an architecture, word size, and
558 * endianness.
559 *
560 * The default flags for the architecture are used other than the word size and
561 * endianness.
562 */
563 void drgn_platform_from_arch(const struct drgn_architecture_info *arch,
564 bool is_64_bit, bool is_little_endian,
565 struct drgn_platform *ret);
566
567 /** Initialize a @ref drgn_platform from an ELF header. */
568 void drgn_platform_from_elf(GElf_Ehdr *ehdr, struct drgn_platform *ret);
569
570 /** @} */
571
572 #endif /* DRGN_PLATFORM_H */