Initial implementation of the debuginfo API
[babeltrace.git] / include / babeltrace / dwarf.h
1 #ifndef _BABELTRACE_DWARF_H
2 #define _BABELTRACE_DWARF_H
3
4 /*
5 * Babeltrace - DWARF Information 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 <stdlib.h>
32 #include <dwarf.h>
33 #include <elfutils/libdw.h>
34 #include <babeltrace/babeltrace-internal.h>
35
36 /*
37 * bt_dwarf is a wrapper over libdw providing a nicer, higher-level
38 * interface, to access basic debug information.
39 */
40
41 /*
42 * This structure corresponds to a single compilation unit (CU) for a
43 * given set of debug information (Dwarf type).
44 */
45 struct bt_dwarf_cu {
46 Dwarf *dwarf_info;
47 /* Offset in bytes in the DWARF file to current CU header. */
48 Dwarf_Off offset;
49 /* Offset in bytes in the DWARF file to next CU header. */
50 Dwarf_Off next_offset;
51 /* Size in bytes of CU header */
52 size_t header_size;
53 };
54
55 /*
56 * This structure represents a single debug information entry (DIE),
57 * within a compilation unit (CU).
58 */
59 struct bt_dwarf_die {
60 struct bt_dwarf_cu *cu;
61 Dwarf_Die *dwarf_die;
62 /*
63 * A depth of 0 represents a root DIE, located in the DWARF
64 * layout on the same level as its corresponding CU entry. Its
65 * children DIEs will have a depth of 1, and so forth.
66 */
67 unsigned int depth;
68 };
69
70 /**
71 * Instantiate a structure to access compile units (CU) from a given
72 * `dwarf_info`.
73 *
74 * @param dwarf_info Dwarf instance
75 * @returns Pointer to the new bt_dwarf_cu on success,
76 * NULL on failure.
77 */
78 BT_HIDDEN
79 struct bt_dwarf_cu *bt_dwarf_cu_create(Dwarf *dwarf_info);
80
81 /**
82 * Destroy the given bt_dwarf_cu instance.
83 *
84 * @param cu bt_dwarf_cu instance
85 */
86 BT_HIDDEN
87 void bt_dwarf_cu_destroy(struct bt_dwarf_cu *cu);
88
89 /**
90 * Advance the compile unit `cu` to the next one.
91 *
92 * On success, `cu`'s offset is set to that of the current compile
93 * unit in the executable. On failure, `cu` remains unchanged.
94 *
95 * @param cu bt_dwarf_cu instance
96 * @returns 0 on success, 1 if no next CU is available,
97 * -1 on failure
98 */
99 BT_HIDDEN
100 int bt_dwarf_cu_next(struct bt_dwarf_cu *cu);
101
102 /**
103 * Instantiate a structure to access debug information entries (DIE)
104 * for the given compile unit `cu`.
105 *
106 * @param cu bt_dwarf_cu instance
107 * @returns Pointer to the new bt_dwarf_die on success,
108 * NULL on failure.
109 */
110 BT_HIDDEN
111 struct bt_dwarf_die *bt_dwarf_die_create(struct bt_dwarf_cu *cu);
112
113 /**
114 * Destroy the given bt_dwarf_die instance.
115 *
116 * @param die bt_dwarf_die instance
117 */
118 BT_HIDDEN
119 void bt_dwarf_die_destroy(struct bt_dwarf_die *die);
120
121 /**
122 * Advance the debug information entry `die` to its first child, if
123 * any.
124 *
125 * @param die bt_dwarf_die instance
126 * @returns 0 on success, 1 if no child DIE is available,
127 * -1 on failure
128 */
129 BT_HIDDEN
130 int bt_dwarf_die_child(struct bt_dwarf_die *die);
131
132 /**
133 * Advance the debug information entry `die` to the next one.
134 *
135 * The next DIE is considered to be its sibling on the same level. The
136 * only exception is when the depth of the given DIE is 0, i.e. a
137 * newly created bt_dwarf_die, in which case next returns the first
138 * DIE at depth 1.
139 *
140 * The reason for staying at a depth of 1 is that this is where all
141 * the function DIEs (those with a tag value of DW_TAG_subprogram) are
142 * located, from which more specific child DIEs can then be accessed
143 * if needed via bt_dwarf_die_child.
144 *
145 * @param die bt_dwarf_die instance
146 * @returns 0 on success, 1 if no other siblings are available, -1 on
147 * failure
148 */
149 BT_HIDDEN
150 int bt_dwarf_die_next(struct bt_dwarf_die *die);
151
152 /**
153 * Get a DIE's tag.
154 *
155 * On success, the `tag` out parameter is set to the `die`'s tag's
156 * value. It remains unchanged on failure.
157 *
158 * @param die bt_dwarf_die instance
159 * @param tag Out parameter, the DIE's tag value
160 * @returns 0 on success, -1 on failure.
161 */
162 BT_HIDDEN
163 int bt_dwarf_die_get_tag(struct bt_dwarf_die *die, int *tag);
164
165 /**
166 * Get a DIE's name.
167 *
168 * On success, the `name` out parameter is set to the DIE's name. It
169 * remains unchanged on failure.
170 *
171 * @param die bt_dwarf_die instance
172 * @param name Out parameter, the DIE's name
173 * @returns 0 on success, -1 on failure
174 */
175 BT_HIDDEN
176 int bt_dwarf_die_get_name(struct bt_dwarf_die *die, char **name);
177
178 /**
179 * Get the full path to the DIE's callsite file.
180 *
181 * Only applies to DW_TAG_inlined_subroutine entries. The out
182 * parameter `filename` is set on success, unchanged on failure.
183 *
184 * @param die bt_dwarf_die instance
185 * @param filename Out parameter, the filename for the subroutine's
186 * callsite
187 * @returns 0 on success, -1 on failure
188 */
189 BT_HIDDEN
190 int bt_dwarf_die_get_call_file(struct bt_dwarf_die *die, char **filename);
191
192 /**
193 * Get line number for the DIE's callsite.
194 *
195 * Only applies to DW_TAG_inlined_subroutine entries. The out
196 * parameter `line_no` is set on success, unchanged on failure.
197 *
198 * @param die bt_dwarf_die instance
199 * @param line_no Out parameter, the line number for the
200 * subroutine's callsite
201 * @returns 0 on success, -1 on failure
202 */
203 BT_HIDDEN
204 int bt_dwarf_die_get_call_line(struct bt_dwarf_die *die,
205 uint64_t *line_no);
206
207 /**
208 * Verifies whether a given DIE contains the virtual memory address
209 * `addr`.
210 *
211 * On success, the out parameter `contains` is set with the boolean
212 * value indicating whether the DIE's range covers `addr`. On failure,
213 * it remains unchanged.
214 *
215 * @param die bt_dwarf_die instance
216 * @param addr The memory address to verify
217 * @param contains Out parameter, 1 if addr is contained,
218 * 0 if not
219 * @returns 0 on succes, -1 on failure
220 */
221 BT_HIDDEN
222 int bt_dwarf_die_contains_addr(struct bt_dwarf_die *die, uint64_t addr,
223 int *contains);
224
225 #endif /* _BABELTRACE_DWARF_H */
This page took 0.032968 seconds and 4 git commands to generate.