1 #ifndef _BABELTRACE_BIN_INFO_H
2 #define _BABELTRACE_BIN_INFO_H
5 * Babeltrace - Executable and Shared Object Debug Info Reader
7 * Copyright 2015 Antoine Busque <abusque@efficios.com>
9 * Author: Antoine Busque <abusque@efficios.com>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
30 #include <babeltrace2/logging.h>
34 #include <elfutils/libdw.h>
35 #include "common/macros.h"
36 #include "fd-cache/fd-cache.h"
38 #define DEFAULT_DEBUG_DIR "/usr/lib/debug"
39 #define DEBUG_SUBDIR ".debug"
40 #define BUILD_ID_SUBDIR ".build-id"
41 #define BUILD_ID_SUFFIX ".debug"
42 #define BUILD_ID_PREFIX_DIR_LEN 2
45 bt_logging_level log_level
;
47 /* Base virtual memory address. */
49 /* Upper bound of exec address space. */
51 /* Size of exec address space. */
53 /* Paths to ELF and DWARF files. */
56 /* libelf and libdw objects representing the files. */
59 /* Optional build ID info. */
63 /* Optional debug link info. */
64 gchar
*dbg_link_filename
;
65 uint32_t dbg_link_crc
;
66 /* fd cache handles to ELF and DWARF files. */
67 struct bt_fd_cache_handle
*elf_handle
;
68 struct bt_fd_cache_handle
*dwarf_handle
;
70 gchar
*debug_info_dir
;
71 /* Denotes whether the executable is position independent code. */
73 /* Denotes whether the build id in the trace matches to one on disk. */
74 bool file_build_id_matches
:1;
76 * Denotes whether the executable only has ELF symbols and no
80 /* Weak ref. Owned by the iterator. */
81 struct bt_fd_cache
*fd_cache
;
84 struct source_location
{
90 * Initializes the bin_info framework. Call this before calling
93 * @returns 0 on success, -1 on failure
96 int bin_info_init(bt_logging_level log_level
);
99 * Instantiate a structure representing an ELF executable, possibly
100 * with DWARF info, located at the given path.
102 * @param path Path to the ELF file
103 * @param low_addr Base address of the executable
104 * @param memsz In-memory size of the executable
105 * @param is_pic Whether the executable is position independent
107 * @param debug_info_dir Directory containing debug info or NULL.
108 * @param target_prefix Path to the root file system of the target
110 * @returns Pointer to the new bin_info on success,
114 struct bin_info
*bin_info_create(struct bt_fd_cache
*fdc
, const char *path
,
115 uint64_t low_addr
, uint64_t memsz
, bool is_pic
,
116 const char *debug_info_dir
, const char *target_prefix
,
117 bt_logging_level log_level
);
120 * Destroy the given bin_info instance
122 * @param bin bin_info instance to destroy
125 void bin_info_destroy(struct bin_info
*bin
);
128 * Sets the build ID information for a given bin_info instance.
130 * @param bin The bin_info instance for which to set
132 * @param build_id Array of bytes containing the actual ID
133 * @param build_id_len Length in bytes of the build_id
134 * @returns 0 on success, -1 on failure
137 int bin_info_set_build_id(struct bin_info
*bin
, uint8_t *build_id
,
138 size_t build_id_len
);
141 * Sets the debug link information for a given bin_info instance.
143 * @param bin The bin_info instance for which to set
145 * @param filename Name of the separate debug info file
146 * @param crc Checksum for the debug info file
147 * @returns 0 on success, -1 on failure
150 int bin_info_set_debug_link(struct bin_info
*bin
, const char *filename
,
154 * Returns whether or not the given bin info \p bin contains the
157 * @param bin bin_info instance
158 * @param addr Address to lookup
159 * @returns 1 if \p bin contains \p addr, 0 if it does not,
163 int bin_info_has_address(struct bin_info
*bin
, uint64_t addr
)
169 return addr
>= bin
->low_addr
&& addr
< bin
->high_addr
;
173 * Get the name of the function containing a given address within an
176 * If no DWARF info is available, the function falls back to ELF
177 * symbols and the "function name" is in fact the name of the closest
178 * symbol, followed by the offset between the symbol and the address.
180 * On success, if found, the out parameter `func_name` is set. The ownership
181 * of `func_name` is passed to the caller. On failure, `func_name` remains
184 * @param bin bin_info instance for the executable containing
186 * @param addr Virtual memory address for which to find the
188 * @param func_name Out parameter, the function name.
189 * @returns 0 on success, -1 on failure
192 int bin_info_lookup_function_name(struct bin_info
*bin
, uint64_t addr
,
196 * Get the source location (file name and line number) for a given
197 * address within an executable.
199 * If no DWARF info is available, the source location cannot be found
200 * and the function will return unsuccessfully.
202 * On success, if found, the out parameter `src_loc` is set. The ownership
203 * of `src_loc` is passed to the caller. On failure, `src_loc` remains
206 * @param bin bin_info instance for the executable containing
208 * @param addr Virtual memory address for which to find the
210 * @param src_loc Out parameter, the source location
211 * @returns 0 on success, -1 on failure
214 int bin_info_lookup_source_location(struct bin_info
*bin
, uint64_t addr
,
215 struct source_location
**src_loc
);
217 * Get a string representing the location within the binary of a given
220 * In the case of a PIC binary, the location is relative (+0x1234).
221 * For a non-PIC binary, the location is absolute (@0x1234)
223 * On success, the out parameter `bin_loc` is set. The ownership is
224 * passed to the caller. On failure, `bin_loc` remains unchanged.
226 * @param bin bin_info instance for the executable containing
228 * @param addr Virtual memory address for which to find the
230 * @param bin_loc Out parameter, the binary location
231 * @returns 0 on success, -1 on failure
234 int bin_info_get_bin_loc(struct bin_info
*bin
, uint64_t addr
, char **bin_loc
);
237 * Destroy the given source_location instance
239 * @param src_loc source_location instance to destroy
242 void source_location_destroy(struct source_location
*src_loc
);
244 #endif /* _BABELTRACE_BIN_INFO_H */