1 #ifndef _BABELTRACE_DWARF_H
2 #define _BABELTRACE_DWARF_H
5 * Babeltrace - DWARF Information 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
34 #include <elfutils/libdw.h>
35 #include <babeltrace/babeltrace-internal.h>
38 * bt_dwarf is a wrapper over libdw providing a nicer, higher-level
39 * interface, to access basic debug information.
43 * This structure corresponds to a single compilation unit (CU) for a
44 * given set of debug information (Dwarf type).
48 /* Offset in bytes in the DWARF file to current CU header. */
50 /* Offset in bytes in the DWARF file to next CU header. */
51 Dwarf_Off next_offset
;
52 /* Size in bytes of CU header */
57 * This structure represents a single debug information entry (DIE),
58 * within a compilation unit (CU).
61 struct bt_dwarf_cu
*cu
;
64 * A depth of 0 represents a root DIE, located in the DWARF
65 * layout on the same level as its corresponding CU entry. Its
66 * children DIEs will have a depth of 1, and so forth.
72 * Instantiate a structure to access compile units (CU) from a given
75 * @param dwarf_info Dwarf instance
76 * @returns Pointer to the new bt_dwarf_cu on success,
80 struct bt_dwarf_cu
*bt_dwarf_cu_create(Dwarf
*dwarf_info
);
83 * Destroy the given bt_dwarf_cu instance.
85 * @param cu bt_dwarf_cu instance
88 void bt_dwarf_cu_destroy(struct bt_dwarf_cu
*cu
);
91 * Advance the compile unit `cu` to the next one.
93 * On success, `cu`'s offset is set to that of the current compile
94 * unit in the executable. On failure, `cu` remains unchanged.
96 * @param cu bt_dwarf_cu instance
97 * @returns 0 on success, 1 if no next CU is available,
101 int bt_dwarf_cu_next(struct bt_dwarf_cu
*cu
);
104 * Instantiate a structure to access debug information entries (DIE)
105 * for the given compile unit `cu`.
107 * @param cu bt_dwarf_cu instance
108 * @returns Pointer to the new bt_dwarf_die on success,
112 struct bt_dwarf_die
*bt_dwarf_die_create(struct bt_dwarf_cu
*cu
);
115 * Destroy the given bt_dwarf_die instance.
117 * @param die bt_dwarf_die instance
120 void bt_dwarf_die_destroy(struct bt_dwarf_die
*die
);
123 * Indicates if the debug information entry `die` has children DIEs.
125 * @param die bt_dwarf_die instance
126 * @returns 0 if the die no child, 1 otherwise
129 int bt_dwarf_die_has_children(struct bt_dwarf_die
*die
);
132 * Advance the debug information entry `die` to its first child, if
135 * @param die bt_dwarf_die instance
136 * @returns 0 on success, 1 if no child DIE is available,
140 int bt_dwarf_die_child(struct bt_dwarf_die
*die
);
143 * Advance the debug information entry `die` to the next one.
145 * The next DIE is considered to be its sibling on the same level. The
146 * only exception is when the depth of the given DIE is 0, i.e. a
147 * newly created bt_dwarf_die, in which case next returns the first
150 * The reason for staying at a depth of 1 is that this is where all
151 * the function DIEs (those with a tag value of DW_TAG_subprogram) are
152 * located, from which more specific child DIEs can then be accessed
153 * if needed via bt_dwarf_die_child.
155 * @param die bt_dwarf_die instance
156 * @returns 0 on success, 1 if no other siblings are available, -1 on
160 int bt_dwarf_die_next(struct bt_dwarf_die
*die
);
165 * On success, the `tag` out parameter is set to the `die`'s tag's
166 * value. It remains unchanged on failure.
168 * @param die bt_dwarf_die instance
169 * @param tag Out parameter, the DIE's tag value
170 * @returns 0 on success, -1 on failure.
173 int bt_dwarf_die_get_tag(struct bt_dwarf_die
*die
, int *tag
);
178 * On success, the `name` out parameter is set to the DIE's name. It
179 * remains unchanged on failure.
181 * @param die bt_dwarf_die instance
182 * @param name Out parameter, the DIE's name
183 * @returns 0 on success, -1 on failure
186 int bt_dwarf_die_get_name(struct bt_dwarf_die
*die
, char **name
);
189 * Get the full path to the DIE's callsite file.
191 * Only applies to DW_TAG_inlined_subroutine entries. The out
192 * parameter `filename` is set on success, unchanged on failure.
194 * @param die bt_dwarf_die instance
195 * @param filename Out parameter, the filename for the subroutine's
197 * @returns 0 on success, -1 on failure
200 int bt_dwarf_die_get_call_file(struct bt_dwarf_die
*die
, char **filename
);
203 * Get line number for the DIE's callsite.
205 * Only applies to DW_TAG_inlined_subroutine entries. The out
206 * parameter `line_no` is set on success, unchanged on failure.
208 * @param die bt_dwarf_die instance
209 * @param line_no Out parameter, the line number for the
210 * subroutine's callsite
211 * @returns 0 on success, -1 on failure
214 int bt_dwarf_die_get_call_line(struct bt_dwarf_die
*die
,
218 * Verifies whether a given DIE contains the virtual memory address
221 * On success, the out parameter `contains` is set with the boolean
222 * value indicating whether the DIE's range covers `addr`. On failure,
223 * it remains unchanged.
225 * @param die bt_dwarf_die instance
226 * @param addr The memory address to verify
227 * @param contains Out parameter, true if addr is contained,
229 * @returns 0 on succes, -1 on failure
232 int bt_dwarf_die_contains_addr(struct bt_dwarf_die
*die
, uint64_t addr
,
235 #endif /* _BABELTRACE_DWARF_H */
This page took 0.033173 seconds and 4 git commands to generate.