Debian Codegraph @

libdrgn/memory_reader.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 * Memory reading interface.
8 *
9 * See @ref MemoryReader.
10 */
11
12 #ifndef DRGN_MEMORY_READER_H
13 #define DRGN_MEMORY_READER_H
14
15 #include "binary_search_tree.h"
16 #include "drgn_internal.h"
17
18 /**
19 * @ingroup Internals
20 *
21 * @defgroup MemoryReader Memory reader
22 *
23 * Memory reading interface.
24 *
25 * @ref drgn_memory_reader provides a common interface for registering regions
26 * of memory in a program and reading from memory.
27 *
28 * @ref drgn_memory_reader does not have a notion of the maximum address or
29 * address overflow/wrap-around. Those must be handled at a higher layer.
30 *
31 * @{
32 */
33
34 DEFINE_BINARY_SEARCH_TREE_TYPE(drgn_memory_segment_tree,
35 struct drgn_memory_segment);
36
37 /**
38 * Memory reader.
39 *
40 * A memory reader maps the segments of memory in an address space to callbacks
41 * which can be used to read memory from those segments.
42 */
43 struct drgn_memory_reader {
44 /** Virtual memory segments. */
45 struct drgn_memory_segment_tree virtual_segments;
46 /** Physical memory segments. */
47 struct drgn_memory_segment_tree physical_segments;
48 };
49
50 /**
51 * Initialize a @ref drgn_memory_reader.
52 *
53 * The reader is initialized with no segments.
54 */
55 void drgn_memory_reader_init(struct drgn_memory_reader *reader);
56
57 /** Deinitialize a @ref drgn_memory_reader. */
58 void drgn_memory_reader_deinit(struct drgn_memory_reader *reader);
59
60 /** Remove all segments from a @ref drgn_memory_reader. */
61 void drgn_memory_reader_clear(struct drgn_memory_reader *reader);
62
63 /** Remove all virtual memory segments from a @ref drgn_memory_reader. */
64 void drgn_memory_reader_clear_virtual(struct drgn_memory_reader *reader);
65
66 /** Return whether a @ref drgn_memory_reader has no segments. */
67 bool drgn_memory_reader_empty(struct drgn_memory_reader *reader);
68
69 /**
70 * Add a segment to a @ref drgn_memory_reader.
71 *
72 * @param[in] reader Memory reader.
73 * @param[in] min_address Start address (inclusive).
74 * @param[in] max_address End address (inclusive). Must be `>= min_address`.
75 * @param[in] read_fn Callback to read from segment.
76 * @param[in] arg Argument to pass to @p read_fn.
77 * @param[in] physical Whether to add a physical memory segment.
78 * @return @c NULL on success, non-@c NULL on error.
79 */
80 struct drgn_error *
81 drgn_memory_reader_add_segment(struct drgn_memory_reader *reader,
82 uint64_t min_address, uint64_t max_address,
83 drgn_memory_read_fn read_fn, void *arg,
84 bool physical);
85
86 /**
87 * Read from a @ref drgn_memory_reader.
88 *
89 * @param[in] reader Memory reader.
90 * @param[out] buf Buffer to read into.
91 * @param[in] address Starting address in memory to read.
92 * @param[in] count Number of bytes to read. `address + count - 1` must be
93 * `<= UINT64_MAX`
94 * @param[in] physical Whether @c address is physical.
95 * @return @c NULL on success, non-@c NULL on error.
96 */
97 struct drgn_error *drgn_memory_reader_read(struct drgn_memory_reader *reader,
98 void *buf, uint64_t address,
99 size_t count, bool physical);
100
101 /** Argument for @ref drgn_read_memory_file(). */
102 struct drgn_memory_file_segment {
103 /** Offset in the file where the segment starts. */
104 uint64_t file_offset;
105 /**
106 * Size of the segment in the file. This may be less than the size of
107 * the segment in memory.
108 */
109 uint64_t file_size;
110 /** File descriptor. */
111 int fd;
112 /**
113 * If @c true, EIO is treated as a fault. Otherwise, it is treated as an
114 * OS error.
115 */
116 bool eio_is_fault;
117 /**
118 * If @c true, reads between @ref file_size and the size of the segment
119 * in memory will be returned as zeroes. Otherwise, such reads will
120 * result in a fault.
121 */
122 bool zerofill;
123 };
124
125 /** @ref drgn_memory_read_fn which reads from a file. */
126 struct drgn_error *drgn_read_memory_file(void *buf, uint64_t address,
127 size_t count, uint64_t offset,
128 void *arg, bool physical);
129
130 /** @} */
131
132 #endif /* DRGN_MEMORY_READER_H */