Commit | Line | Data |
---|---|---|
c40a57e5 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
c40a57e5 AB |
3 | * |
4 | * Copyright 2015 Antoine Busque <abusque@efficios.com> | |
5 | * | |
0235b0db | 6 | * Babeltrace - DWARF Information Reader |
c40a57e5 AB |
7 | */ |
8 | ||
ae2be88d SM |
9 | #ifndef BABELTRACE_PLUGINS_LTTNG_UTILS_DEBUG_INFO_DWARF_H |
10 | #define BABELTRACE_PLUGINS_LTTNG_UTILS_DEBUG_INFO_DWARF_H | |
0235b0db | 11 | |
a54aa699 | 12 | #include <stdbool.h> |
c40a57e5 AB |
13 | #include <stdint.h> |
14 | #include <stdlib.h> | |
15 | #include <dwarf.h> | |
16 | #include <elfutils/libdw.h> | |
91d81473 | 17 | #include "common/macros.h" |
c40a57e5 AB |
18 | |
19 | /* | |
20 | * bt_dwarf is a wrapper over libdw providing a nicer, higher-level | |
21 | * interface, to access basic debug information. | |
22 | */ | |
23 | ||
24 | /* | |
25 | * This structure corresponds to a single compilation unit (CU) for a | |
26 | * given set of debug information (Dwarf type). | |
27 | */ | |
28 | struct bt_dwarf_cu { | |
29 | Dwarf *dwarf_info; | |
30 | /* Offset in bytes in the DWARF file to current CU header. */ | |
31 | Dwarf_Off offset; | |
32 | /* Offset in bytes in the DWARF file to next CU header. */ | |
33 | Dwarf_Off next_offset; | |
34 | /* Size in bytes of CU header */ | |
35 | size_t header_size; | |
36 | }; | |
37 | ||
38 | /* | |
39 | * This structure represents a single debug information entry (DIE), | |
40 | * within a compilation unit (CU). | |
41 | */ | |
42 | struct bt_dwarf_die { | |
43 | struct bt_dwarf_cu *cu; | |
44 | Dwarf_Die *dwarf_die; | |
45 | /* | |
46 | * A depth of 0 represents a root DIE, located in the DWARF | |
47 | * layout on the same level as its corresponding CU entry. Its | |
48 | * children DIEs will have a depth of 1, and so forth. | |
49 | */ | |
50 | unsigned int depth; | |
51 | }; | |
52 | ||
53 | /** | |
54 | * Instantiate a structure to access compile units (CU) from a given | |
55 | * `dwarf_info`. | |
56 | * | |
57 | * @param dwarf_info Dwarf instance | |
58 | * @returns Pointer to the new bt_dwarf_cu on success, | |
59 | * NULL on failure. | |
60 | */ | |
c40a57e5 AB |
61 | struct bt_dwarf_cu *bt_dwarf_cu_create(Dwarf *dwarf_info); |
62 | ||
63 | /** | |
64 | * Destroy the given bt_dwarf_cu instance. | |
65 | * | |
66 | * @param cu bt_dwarf_cu instance | |
67 | */ | |
c40a57e5 AB |
68 | void bt_dwarf_cu_destroy(struct bt_dwarf_cu *cu); |
69 | ||
70 | /** | |
71 | * Advance the compile unit `cu` to the next one. | |
72 | * | |
73 | * On success, `cu`'s offset is set to that of the current compile | |
74 | * unit in the executable. On failure, `cu` remains unchanged. | |
75 | * | |
76 | * @param cu bt_dwarf_cu instance | |
77 | * @returns 0 on success, 1 if no next CU is available, | |
78 | * -1 on failure | |
79 | */ | |
c40a57e5 AB |
80 | int bt_dwarf_cu_next(struct bt_dwarf_cu *cu); |
81 | ||
82 | /** | |
83 | * Instantiate a structure to access debug information entries (DIE) | |
84 | * for the given compile unit `cu`. | |
85 | * | |
86 | * @param cu bt_dwarf_cu instance | |
87 | * @returns Pointer to the new bt_dwarf_die on success, | |
88 | * NULL on failure. | |
89 | */ | |
c40a57e5 AB |
90 | struct bt_dwarf_die *bt_dwarf_die_create(struct bt_dwarf_cu *cu); |
91 | ||
92 | /** | |
93 | * Destroy the given bt_dwarf_die instance. | |
94 | * | |
95 | * @param die bt_dwarf_die instance | |
96 | */ | |
c40a57e5 AB |
97 | void bt_dwarf_die_destroy(struct bt_dwarf_die *die); |
98 | ||
e6365242 FD |
99 | /** |
100 | * Indicates if the debug information entry `die` has children DIEs. | |
101 | * | |
102 | * @param die bt_dwarf_die instance | |
103 | * @returns 0 if the die no child, 1 otherwise | |
104 | */ | |
e6365242 FD |
105 | int bt_dwarf_die_has_children(struct bt_dwarf_die *die); |
106 | ||
c40a57e5 AB |
107 | /** |
108 | * Advance the debug information entry `die` to its first child, if | |
109 | * any. | |
110 | * | |
111 | * @param die bt_dwarf_die instance | |
112 | * @returns 0 on success, 1 if no child DIE is available, | |
113 | * -1 on failure | |
114 | */ | |
c40a57e5 AB |
115 | int bt_dwarf_die_child(struct bt_dwarf_die *die); |
116 | ||
117 | /** | |
118 | * Advance the debug information entry `die` to the next one. | |
119 | * | |
120 | * The next DIE is considered to be its sibling on the same level. The | |
121 | * only exception is when the depth of the given DIE is 0, i.e. a | |
122 | * newly created bt_dwarf_die, in which case next returns the first | |
123 | * DIE at depth 1. | |
124 | * | |
125 | * The reason for staying at a depth of 1 is that this is where all | |
126 | * the function DIEs (those with a tag value of DW_TAG_subprogram) are | |
127 | * located, from which more specific child DIEs can then be accessed | |
128 | * if needed via bt_dwarf_die_child. | |
129 | * | |
130 | * @param die bt_dwarf_die instance | |
131 | * @returns 0 on success, 1 if no other siblings are available, -1 on | |
132 | * failure | |
133 | */ | |
c40a57e5 AB |
134 | int bt_dwarf_die_next(struct bt_dwarf_die *die); |
135 | ||
136 | /** | |
137 | * Get a DIE's tag. | |
138 | * | |
139 | * On success, the `tag` out parameter is set to the `die`'s tag's | |
140 | * value. It remains unchanged on failure. | |
141 | * | |
142 | * @param die bt_dwarf_die instance | |
143 | * @param tag Out parameter, the DIE's tag value | |
144 | * @returns 0 on success, -1 on failure. | |
145 | */ | |
c40a57e5 AB |
146 | int bt_dwarf_die_get_tag(struct bt_dwarf_die *die, int *tag); |
147 | ||
148 | /** | |
149 | * Get a DIE's name. | |
150 | * | |
151 | * On success, the `name` out parameter is set to the DIE's name. It | |
152 | * remains unchanged on failure. | |
153 | * | |
154 | * @param die bt_dwarf_die instance | |
155 | * @param name Out parameter, the DIE's name | |
156 | * @returns 0 on success, -1 on failure | |
157 | */ | |
c40a57e5 AB |
158 | int bt_dwarf_die_get_name(struct bt_dwarf_die *die, char **name); |
159 | ||
160 | /** | |
161 | * Get the full path to the DIE's callsite file. | |
162 | * | |
163 | * Only applies to DW_TAG_inlined_subroutine entries. The out | |
164 | * parameter `filename` is set on success, unchanged on failure. | |
165 | * | |
166 | * @param die bt_dwarf_die instance | |
167 | * @param filename Out parameter, the filename for the subroutine's | |
168 | * callsite | |
169 | * @returns 0 on success, -1 on failure | |
170 | */ | |
c40a57e5 AB |
171 | int bt_dwarf_die_get_call_file(struct bt_dwarf_die *die, char **filename); |
172 | ||
173 | /** | |
174 | * Get line number for the DIE's callsite. | |
175 | * | |
176 | * Only applies to DW_TAG_inlined_subroutine entries. The out | |
177 | * parameter `line_no` is set on success, unchanged on failure. | |
178 | * | |
179 | * @param die bt_dwarf_die instance | |
180 | * @param line_no Out parameter, the line number for the | |
181 | * subroutine's callsite | |
182 | * @returns 0 on success, -1 on failure | |
183 | */ | |
c40a57e5 AB |
184 | int bt_dwarf_die_get_call_line(struct bt_dwarf_die *die, |
185 | uint64_t *line_no); | |
186 | ||
187 | /** | |
188 | * Verifies whether a given DIE contains the virtual memory address | |
189 | * `addr`. | |
190 | * | |
191 | * On success, the out parameter `contains` is set with the boolean | |
192 | * value indicating whether the DIE's range covers `addr`. On failure, | |
193 | * it remains unchanged. | |
194 | * | |
195 | * @param die bt_dwarf_die instance | |
196 | * @param addr The memory address to verify | |
a54aa699 AB |
197 | * @param contains Out parameter, true if addr is contained, |
198 | * false if not | |
e7401568 | 199 | * @returns 0 on success, -1 on failure |
c40a57e5 | 200 | */ |
c40a57e5 | 201 | int bt_dwarf_die_contains_addr(struct bt_dwarf_die *die, uint64_t addr, |
a54aa699 | 202 | bool *contains); |
c40a57e5 | 203 | |
ae2be88d | 204 | #endif /* BABELTRACE_PLUGINS_LTTNG_UTILS_DEBUG_INFO_DWARF_H */ |