Add binary location information
[babeltrace.git] / include / babeltrace / so-info.h
1 #ifndef _BABELTRACE_SO_INFO_H
2 #define _BABELTRACE_SO_INFO_H
3
4 /*
5 * Babeltrace - Executable and Shared Object Debug Info Reader
6 *
7 * Copyright 2015 Antoine Busque <abusque@efficios.com>
8 *
9 * Author: Antoine Busque <abusque@efficios.com>
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 */
29
30 #include <stdint.h>
31 #include <stdbool.h>
32 #include <gelf.h>
33 #include <elfutils/libdw.h>
34 #include <babeltrace/babeltrace-internal.h>
35
36 #define DEFAULT_DEBUG_DIR "/usr/lib/debug"
37 #define DEBUG_SUBDIR ".debug/"
38 #define BUILD_ID_SUBDIR ".build-id/"
39 #define BUILD_ID_SUFFIX ".debug"
40
41 struct so_info {
42 /* Base virtual memory address. */
43 uint64_t low_addr;
44 /* Upper bound of exec address space. */
45 uint64_t high_addr;
46 /* Size of exec address space. */
47 uint64_t memsz;
48 /* Paths to ELF and DWARF files. */
49 char *elf_path;
50 char *dwarf_path;
51 /* libelf and libdw objects representing the files. */
52 Elf *elf_file;
53 Dwarf *dwarf_info;
54 /* Optional build ID info. */
55 uint8_t *build_id;
56 size_t build_id_len;
57 /* Optional debug link info. */
58 char *dbg_link_filename;
59 uint32_t dbg_link_crc;
60 /* FDs to ELF and DWARF files. */
61 int elf_fd;
62 int dwarf_fd;
63 /* Denotes whether the executable is position independent code. */
64 bool is_pic:1;
65 /* Denotes whether the SO only has ELF symbols and no DWARF info. */
66 bool is_elf_only:1;
67 };
68
69 struct source_location {
70 uint64_t line_no;
71 char *filename;
72 };
73
74 /**
75 * Initializes the so_info framework. Call this before calling
76 * anything else.
77 *
78 * @returns 0 on success, -1 on failure
79 */
80 BT_HIDDEN
81 int so_info_init(void);
82
83 /**
84 * Instantiate a structure representing an ELF executable, possibly
85 * with DWARF info, located at the given path.
86 *
87 * @param path Path to the ELF file
88 * @param low_addr Base address of the executable
89 * @param memsz In-memory size of the executable
90 * @param is_pic Whether the executable is position independent
91 * code (PIC)
92 * @returns Pointer to the new so_info on success,
93 * NULL on failure.
94 */
95 BT_HIDDEN
96 struct so_info *so_info_create(const char *path, uint64_t low_addr,
97 uint64_t memsz, bool is_pic);
98
99 /**
100 * Destroy the given so_info instance
101 *
102 * @param so so_info instance to destroy
103 */
104 BT_HIDDEN
105 void so_info_destroy(struct so_info *so);
106
107 /**
108 * Sets the build ID information for a given so_info instance.
109 *
110 * @param so The so_info instance for which to set
111 * the build ID
112 * @param build_id Array of bytes containing the actual ID
113 * @param build_id_len Length in bytes of the build_id
114 * @returns 0 on success, -1 on failure
115 */
116 BT_HIDDEN
117 int so_info_set_build_id(struct so_info *so, uint8_t *build_id,
118 size_t build_id_len);
119
120 /**
121 * Sets the debug link information for a given so_info instance.
122 *
123 * @param so The so_info instance for which to set
124 * the debug link
125 * @param filename Name of the separate debug info file
126 * @param crc Checksum for the debug info file
127 * @returns 0 on success, -1 on failure
128 */
129 BT_HIDDEN
130 int so_info_set_debug_link(struct so_info *so, char *filename, uint32_t crc);
131
132 /**
133 * Returns whether or not the given SO info \p so contains the address
134 * \p addr.
135 *
136 * @param so so_info instance
137 * @param addr Address to lookup
138 * @returns 1 if \p so contains \p addr, 0 if it does not,
139 * -1 on failure
140 */
141 static inline
142 int so_info_has_address(struct so_info *so, uint64_t addr)
143 {
144 if (!so) {
145 return -1;
146 }
147
148 return addr >= so->low_addr && addr < so->high_addr;
149 }
150
151 /**
152 * Get the name of the function containing a given address within an
153 * executable.
154 *
155 * If no DWARF info is available, the function falls back to ELF
156 * symbols and the "function name" is in fact the name of the closest
157 * symbol, followed by the offset between the symbol and the address.
158 *
159 * On success, if found, the out parameter `func_name` is set. The ownership
160 * of `func_name` is passed to the caller. On failure, `func_name` remains
161 * unchanged.
162 *
163 * @param so so_info instance for the executable containing
164 * the address
165 * @param addr Virtual memory address for which to find the
166 * function name
167 * @param func_name Out parameter, the function name.
168 * @returns 0 on success, -1 on failure
169 */
170 BT_HIDDEN
171 int so_info_lookup_function_name(struct so_info *so, uint64_t addr,
172 char **func_name);
173
174 /**
175 * Get the source location (file name and line number) for a given
176 * address within an executable.
177 *
178 * If no DWARF info is available, the source location cannot be found
179 * and the function will return unsuccesfully.
180 *
181 * On success, if found, the out parameter `src_loc` is set. The ownership
182 * of `src_loc` is passed to the caller. On failure, `src_loc` remains
183 * unchanged.
184 *
185 * @param so so_info instance for the executable containing
186 * the address
187 * @param addr Virtual memory address for which to find the
188 * source location
189 * @param src_loc Out parameter, the source location
190 * @returns 0 on success, -1 on failure
191 */
192 BT_HIDDEN
193 int so_info_lookup_source_location(struct so_info *so, uint64_t addr,
194 struct source_location **src_loc);
195 /**
196 * Get a string representing the location within the binary of a given
197 * address.
198 *
199 * In the case of a PIC binary, the location is relative (+0x1234).
200 * For a non-PIC binary, the location is absolute (@0x1234)
201 *
202 * On success, the out parameter `bin_loc` is set. The ownership is
203 * passed to the caller. On failure, `bin_loc` remains unchanged.
204 *
205 * @param so so_info instance for the executable containing
206 * the address
207 * @param addr Virtual memory address for which to find the
208 * binary location
209 * @param bin_loc Out parameter, the binary location
210 * @returns 0 on success, -1 on failure
211 */
212 BT_HIDDEN
213 int so_info_get_bin_loc(struct so_info *so, uint64_t addr, char **bin_loc);
214
215 /**
216 * Destroy the given source_location instance
217 *
218 * @param src_loc source_location instance to destroy
219 */
220 BT_HIDDEN
221 void source_location_destroy(struct source_location *src_loc);
222
223 #endif /* _BABELTRACE_SO_INFO_H */
This page took 0.032735 seconds and 4 git commands to generate.