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 | ||
0235b0db MJ |
9 | #ifndef _BABELTRACE_DWARF_H |
10 | #define _BABELTRACE_DWARF_H | |
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 | */ | |
61 | BT_HIDDEN | |
62 | struct bt_dwarf_cu *bt_dwarf_cu_create(Dwarf *dwarf_info); | |
63 | ||
64 | /** | |
65 | * Destroy the given bt_dwarf_cu instance. | |
66 | * | |
67 | * @param cu bt_dwarf_cu instance | |
68 | */ | |
69 | BT_HIDDEN | |
70 | void bt_dwarf_cu_destroy(struct bt_dwarf_cu *cu); | |
71 | ||
72 | /** | |
73 | * Advance the compile unit `cu` to the next one. | |
74 | * | |
75 | * On success, `cu`'s offset is set to that of the current compile | |
76 | * unit in the executable. On failure, `cu` remains unchanged. | |
77 | * | |
78 | * @param cu bt_dwarf_cu instance | |
79 | * @returns 0 on success, 1 if no next CU is available, | |
80 | * -1 on failure | |
81 | */ | |
82 | BT_HIDDEN | |
83 | int bt_dwarf_cu_next(struct bt_dwarf_cu *cu); | |
84 | ||
85 | /** | |
86 | * Instantiate a structure to access debug information entries (DIE) | |
87 | * for the given compile unit `cu`. | |
88 | * | |
89 | * @param cu bt_dwarf_cu instance | |
90 | * @returns Pointer to the new bt_dwarf_die on success, | |
91 | * NULL on failure. | |
92 | */ | |
93 | BT_HIDDEN | |
94 | struct bt_dwarf_die *bt_dwarf_die_create(struct bt_dwarf_cu *cu); | |
95 | ||
96 | /** | |
97 | * Destroy the given bt_dwarf_die instance. | |
98 | * | |
99 | * @param die bt_dwarf_die instance | |
100 | */ | |
101 | BT_HIDDEN | |
102 | void bt_dwarf_die_destroy(struct bt_dwarf_die *die); | |
103 | ||
e6365242 FD |
104 | /** |
105 | * Indicates if the debug information entry `die` has children DIEs. | |
106 | * | |
107 | * @param die bt_dwarf_die instance | |
108 | * @returns 0 if the die no child, 1 otherwise | |
109 | */ | |
110 | BT_HIDDEN | |
111 | int bt_dwarf_die_has_children(struct bt_dwarf_die *die); | |
112 | ||
c40a57e5 AB |
113 | /** |
114 | * Advance the debug information entry `die` to its first child, if | |
115 | * any. | |
116 | * | |
117 | * @param die bt_dwarf_die instance | |
118 | * @returns 0 on success, 1 if no child DIE is available, | |
119 | * -1 on failure | |
120 | */ | |
121 | BT_HIDDEN | |
122 | int bt_dwarf_die_child(struct bt_dwarf_die *die); | |
123 | ||
124 | /** | |
125 | * Advance the debug information entry `die` to the next one. | |
126 | * | |
127 | * The next DIE is considered to be its sibling on the same level. The | |
128 | * only exception is when the depth of the given DIE is 0, i.e. a | |
129 | * newly created bt_dwarf_die, in which case next returns the first | |
130 | * DIE at depth 1. | |
131 | * | |
132 | * The reason for staying at a depth of 1 is that this is where all | |
133 | * the function DIEs (those with a tag value of DW_TAG_subprogram) are | |
134 | * located, from which more specific child DIEs can then be accessed | |
135 | * if needed via bt_dwarf_die_child. | |
136 | * | |
137 | * @param die bt_dwarf_die instance | |
138 | * @returns 0 on success, 1 if no other siblings are available, -1 on | |
139 | * failure | |
140 | */ | |
141 | BT_HIDDEN | |
142 | int bt_dwarf_die_next(struct bt_dwarf_die *die); | |
143 | ||
144 | /** | |
145 | * Get a DIE's tag. | |
146 | * | |
147 | * On success, the `tag` out parameter is set to the `die`'s tag's | |
148 | * value. It remains unchanged on failure. | |
149 | * | |
150 | * @param die bt_dwarf_die instance | |
151 | * @param tag Out parameter, the DIE's tag value | |
152 | * @returns 0 on success, -1 on failure. | |
153 | */ | |
154 | BT_HIDDEN | |
155 | int bt_dwarf_die_get_tag(struct bt_dwarf_die *die, int *tag); | |
156 | ||
157 | /** | |
158 | * Get a DIE's name. | |
159 | * | |
160 | * On success, the `name` out parameter is set to the DIE's name. It | |
161 | * remains unchanged on failure. | |
162 | * | |
163 | * @param die bt_dwarf_die instance | |
164 | * @param name Out parameter, the DIE's name | |
165 | * @returns 0 on success, -1 on failure | |
166 | */ | |
167 | BT_HIDDEN | |
168 | int bt_dwarf_die_get_name(struct bt_dwarf_die *die, char **name); | |
169 | ||
170 | /** | |
171 | * Get the full path to the DIE's callsite file. | |
172 | * | |
173 | * Only applies to DW_TAG_inlined_subroutine entries. The out | |
174 | * parameter `filename` is set on success, unchanged on failure. | |
175 | * | |
176 | * @param die bt_dwarf_die instance | |
177 | * @param filename Out parameter, the filename for the subroutine's | |
178 | * callsite | |
179 | * @returns 0 on success, -1 on failure | |
180 | */ | |
181 | BT_HIDDEN | |
182 | int bt_dwarf_die_get_call_file(struct bt_dwarf_die *die, char **filename); | |
183 | ||
184 | /** | |
185 | * Get line number for the DIE's callsite. | |
186 | * | |
187 | * Only applies to DW_TAG_inlined_subroutine entries. The out | |
188 | * parameter `line_no` is set on success, unchanged on failure. | |
189 | * | |
190 | * @param die bt_dwarf_die instance | |
191 | * @param line_no Out parameter, the line number for the | |
192 | * subroutine's callsite | |
193 | * @returns 0 on success, -1 on failure | |
194 | */ | |
195 | BT_HIDDEN | |
196 | int bt_dwarf_die_get_call_line(struct bt_dwarf_die *die, | |
197 | uint64_t *line_no); | |
198 | ||
199 | /** | |
200 | * Verifies whether a given DIE contains the virtual memory address | |
201 | * `addr`. | |
202 | * | |
203 | * On success, the out parameter `contains` is set with the boolean | |
204 | * value indicating whether the DIE's range covers `addr`. On failure, | |
205 | * it remains unchanged. | |
206 | * | |
207 | * @param die bt_dwarf_die instance | |
208 | * @param addr The memory address to verify | |
a54aa699 AB |
209 | * @param contains Out parameter, true if addr is contained, |
210 | * false if not | |
c40a57e5 AB |
211 | * @returns 0 on succes, -1 on failure |
212 | */ | |
213 | BT_HIDDEN | |
214 | int bt_dwarf_die_contains_addr(struct bt_dwarf_die *die, uint64_t addr, | |
a54aa699 | 215 | bool *contains); |
c40a57e5 AB |
216 | |
217 | #endif /* _BABELTRACE_DWARF_H */ |