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