Debian Codegraph @

libdrgn/elf_file.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 * ELF files.
8 *
9 * See @ref ElfFile.
10 */
11
12 #ifndef DRGN_ELF_FILE_H
13 #define DRGN_ELF_FILE_H
14
15 #include <elf.h>
16 #include <elfutils/libdw.h>
17 #include <libelf.h>
18 #include <stdbool.h>
19 #include <stdint.h>
20 #include <stdlib.h>
21
22 #include "binary_buffer.h"
23 #include "elf_sections.h" // IWYU pragma: export
24 #include "platform.h"
25
26 struct drgn_module;
27
28 /**
29 * @ingroup Internals
30 *
31 * @defgroup ElfFile ELF files
32 *
33 * ELF file handling.
34 *
35 * @{
36 */
37
38 /**
39 * Read the raw data from an ELF section, decompressing it first if it is
40 * compressed.
41 *
42 * This returns an error if the section type is `SHT_NOBITS`.
43 */
44 struct drgn_error *read_elf_section(Elf_Scn *scn, Elf_Data **ret);
45
46 /**
47 * Truncate any bytes beyond the last null character in an ELF string table.
48 *
49 * This sets `data->d_size` so that any string table index less than
50 * `data->d_size` is guaranteed to be valid.
51 */
52 void truncate_elf_string_data(Elf_Data *data);
53
54 static inline bool elf_data_contains_ptr(Elf_Data *data, const void *ptr)
55 {
56 uintptr_t bufi = (uintptr_t)data->d_buf;
57 uintptr_t ptri = (uintptr_t)ptr;
58 return ptri >= bufi && ptri - bufi < data->d_size;
59 }
60
61 /** An ELF file used by a @ref drgn_module. */
62 struct drgn_elf_file {
63 /** Module using this file. */
64 struct drgn_module *module;
65 /** Filesystem path to this file. */
66 char *path;
67 /**
68 * Memory image backing @ref elf.
69 *
70 * @c NULL if not backed by a memory image.
71 */
72 char *image;
73 /**
74 * File descriptor backing @ref elf.
75 *
76 * -1 if not backed by a file.
77 */
78 int fd;
79 /** Whether the file is loadable. */
80 bool is_loadable;
81 /** Whether the file is relocatable. */
82 bool is_relocatable;
83 /** Whether the file still need to have relocations applied. */
84 bool needs_relocation;
85 /** Whether the file is a Linux kernel image (`vmlinux`). */
86 bool is_vmlinux;
87 /** libelf handle. */
88 Elf *elf;
89 /**
90 * libdw handle.
91 *
92 * @c NULL if not yet created.
93 *
94 * Don't access this directly. Get it with @ref
95 * drgn_elf_file_get_dwarf() instead.
96 */
97 Dwarf *_dwarf;
98 /**
99 * Platform of this file.
100 *
101 * This should take precedence over @ref drgn_program::platform when
102 * parsing this file. Note that there are some cases where it doesn't
103 * make sense for the program and file platforms to differ (e.g., stack
104 * unwinding), in which case the file should be ignored if its platform
105 * doesn't match the program's.
106 */
107 struct drgn_platform platform;
108 /** Important ELF sections. */
109 Elf_Scn *scns[DRGN_SECTION_INDEX_NUM];
110 /** Data cached for important ELF sections. */
111 Elf_Data *scn_data[DRGN_SECTION_INDEX_NUM_DATA];
112 /**
113 * If the file has a debugaltlink file, the debugaltlink file's
114 * `.debug_info` section data.
115 */
116 Elf_Data *alt_debug_info_data;
117 /**
118 * If the file has a debugaltlink file, the debugaltlink file's
119 * `.debug_str` section data.
120 */
121 Elf_Data *alt_debug_str_data;
122 /**
123 * For relocatable files, a bitmap of which sections have their address
124 * set.
125 */
126 unsigned long *sections_with_address;
127 };
128
129 /**
130 * Create a @ref drgn_elf_file.
131 *
132 * On success, this takes ownership of @p fd, @p image, and @p elf. @p path is
133 * copied.
134 */
135 struct drgn_error *drgn_elf_file_create(struct drgn_module *module,
136 const char *path, int fd, char *image,
137 Elf *elf, struct drgn_elf_file **ret);
138
139 void drgn_elf_file_destroy(struct drgn_elf_file *file);
140
141 /** Apply ELF relocations to the file if needed. */
142 struct drgn_error *
143 drgn_elf_file_apply_relocations(struct drgn_elf_file *file);
144
145 /**
146 * Read an indexed ELF section.
147 *
148 * This applies ELF relocations to the file first if needed.
149 */
150 struct drgn_error *drgn_elf_file_read_section(struct drgn_elf_file *file,
151 enum drgn_section_index scn,
152 Elf_Data **ret);
153
154 struct drgn_error *drgn_elf_file_get_dwarf(struct drgn_elf_file *file,
155 Dwarf **ret);
156
157 static inline bool
158 drgn_elf_file_is_little_endian(const struct drgn_elf_file *file)
159 {
160 return drgn_platform_is_little_endian(&file->platform);
161 }
162
163 static inline bool drgn_elf_file_bswap(const struct drgn_elf_file *file)
164 {
165 return drgn_platform_bswap(&file->platform);
166 }
167
168 static inline bool
169 drgn_elf_file_is_64_bit(const struct drgn_elf_file *file)
170 {
171 return drgn_platform_is_64_bit(&file->platform);
172 }
173
174 static inline uint8_t
175 drgn_elf_file_address_size(const struct drgn_elf_file *file)
176 {
177 return drgn_platform_address_size(&file->platform);
178 }
179
180 static inline uint64_t
181 drgn_elf_file_address_mask(const struct drgn_elf_file *file)
182 {
183 return drgn_platform_address_mask(&file->platform);
184 }
185
186 static inline bool drgn_elf_file_has_dwarf(const struct drgn_elf_file *file)
187 {
188 return (file->scns[DRGN_SCN_DEBUG_INFO]
189 && file->scns[DRGN_SCN_DEBUG_ABBREV]);
190 }
191
192 struct drgn_error *
193 drgn_elf_file_section_error(struct drgn_elf_file *file, Elf_Scn *scn,
194 Elf_Data *data, const char *ptr,
195 const char *message)
196 __attribute__((__returns_nonnull__));
197
198 struct drgn_error *
199 drgn_elf_file_section_errorf(struct drgn_elf_file *file, Elf_Scn *scn,
200 Elf_Data *data, const char *ptr,
201 const char *format, ...)
202 __attribute__((__returns_nonnull__, __format__(__printf__, 5, 6)));
203
204 struct drgn_elf_file_section_buffer {
205 struct binary_buffer bb;
206 struct drgn_elf_file *file;
207 Elf_Scn *scn;
208 Elf_Data *data;
209 };
210
211 struct drgn_error *drgn_elf_file_section_buffer_error(struct binary_buffer *bb,
212 const char *ptr,
213 const char *message);
214
215 static inline void
216 drgn_elf_file_section_buffer_init(struct drgn_elf_file_section_buffer *buffer,
217 struct drgn_elf_file *file, Elf_Scn *scn,
218 Elf_Data *data)
219 {
220 binary_buffer_init(&buffer->bb, data->d_buf, data->d_size,
221 drgn_elf_file_is_little_endian(file),
222 drgn_elf_file_section_buffer_error);
223 buffer->file = file;
224 buffer->scn = scn;
225 buffer->data = data;
226 }
227
228 /**
229 * Initialize a @ref binary_buffer for an indexed ELF section that has already
230 * been read.
231 */
232 static inline void
233 drgn_elf_file_section_buffer_init_index(struct drgn_elf_file_section_buffer *buffer,
234 struct drgn_elf_file *file,
235 enum drgn_section_index scn)
236 {
237 drgn_elf_file_section_buffer_init(buffer, file, file->scns[scn],
238 file->scn_data[scn]);
239 }
240
241 /**
242 * Read an indexed ELF section (applying ELF relocations if needed) and
243 * initialize a @ref binary_buffer for it.
244 */
245 static inline struct drgn_error *
246 drgn_elf_file_section_buffer_read(struct drgn_elf_file_section_buffer *buffer,
247 struct drgn_elf_file *file,
248 enum drgn_section_index scn)
249 {
250 Elf_Data *data;
251 struct drgn_error *err = drgn_elf_file_read_section(file, scn, &data);
252 if (err)
253 return err;
254 drgn_elf_file_section_buffer_init(buffer, file, file->scns[scn], data);
255 return NULL;
256 }
257
258 /**
259 * Return the virtual address range of an ELF file.
260 *
261 * @param[out] start_ret Minimum virtual address (inclusive).
262 * @param[out] end_ret Maximum virtual address (exclusive).
263 */
264 bool drgn_elf_file_address_range(struct drgn_elf_file *file,
265 uint64_t *start_ret, uint64_t *end_ret);
266
267 /**
268 * Return whether an ELF file is a vmlinux file.
269 *
270 * @return > 0 if the file is vmlinux, 0 if it is not, < 0 on libelf error.
271 */
272 int elf_is_vmlinux(Elf *elf);
273
274 /**
275 * Get the Linux release from a vmlinux file.
276 *
277 * @param[out] ret Returned release.
278 * @return Length of @p ret on success, 0 if not found, < 0 on libelf error.
279 */
280 ssize_t elf_vmlinux_release(Elf *elf, const char **ret);
281
282 /** @} */
283
284 #endif /* DRGN_ELF_FILE_H */