288eb9c23cc02d2a28aeda2ec9265b38c055d9a0
2 * SPDX-License-Identifier: MIT
4 * Copyright 2015 Antoine Busque <abusque@efficios.com>
6 * Babeltrace - DWARF Information Reader
9 #ifndef BABELTRACE_PLUGINS_LTTNG_UTILS_DEBUG_INFO_DWARF_H
10 #define BABELTRACE_PLUGINS_LTTNG_UTILS_DEBUG_INFO_DWARF_H
16 #include <elfutils/libdw.h>
17 #include "common/macros.h"
20 * bt_dwarf is a wrapper over libdw providing a nicer, higher-level
21 * interface, to access basic debug information.
25 * This structure corresponds to a single compilation unit (CU) for a
26 * given set of debug information (Dwarf type).
30 /* Offset in bytes in the DWARF file to current CU header. */
32 /* Offset in bytes in the DWARF file to next CU header. */
33 Dwarf_Off next_offset
;
34 /* Size in bytes of CU header */
39 * This structure represents a single debug information entry (DIE),
40 * within a compilation unit (CU).
43 struct bt_dwarf_cu
*cu
;
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.
54 * Instantiate a structure to access compile units (CU) from a given
57 * @param dwarf_info Dwarf instance
58 * @returns Pointer to the new bt_dwarf_cu on success,
61 struct bt_dwarf_cu
*bt_dwarf_cu_create(Dwarf
*dwarf_info
);
64 * Destroy the given bt_dwarf_cu instance.
66 * @param cu bt_dwarf_cu instance
68 void bt_dwarf_cu_destroy(struct bt_dwarf_cu
*cu
);
71 * Advance the compile unit `cu` to the next one.
73 * On success, `cu`'s offset is set to that of the current compile
74 * unit in the executable. On failure, `cu` remains unchanged.
76 * @param cu bt_dwarf_cu instance
77 * @returns 0 on success, 1 if no next CU is available,
80 int bt_dwarf_cu_next(struct bt_dwarf_cu
*cu
);
83 * Instantiate a structure to access debug information entries (DIE)
84 * for the given compile unit `cu`.
86 * @param cu bt_dwarf_cu instance
87 * @returns Pointer to the new bt_dwarf_die on success,
90 struct bt_dwarf_die
*bt_dwarf_die_create(struct bt_dwarf_cu
*cu
);
93 * Destroy the given bt_dwarf_die instance.
95 * @param die bt_dwarf_die instance
97 void bt_dwarf_die_destroy(struct bt_dwarf_die
*die
);
100 * Indicates if the debug information entry `die` has children DIEs.
102 * @param die bt_dwarf_die instance
103 * @returns 0 if the die no child, 1 otherwise
105 int bt_dwarf_die_has_children(struct bt_dwarf_die
*die
);
108 * Advance the debug information entry `die` to its first child, if
111 * @param die bt_dwarf_die instance
112 * @returns 0 on success, 1 if no child DIE is available,
115 int bt_dwarf_die_child(struct bt_dwarf_die
*die
);
118 * Advance the debug information entry `die` to the next one.
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
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.
130 * @param die bt_dwarf_die instance
131 * @returns 0 on success, 1 if no other siblings are available, -1 on
134 int bt_dwarf_die_next(struct bt_dwarf_die
*die
);
139 * On success, the `tag` out parameter is set to the `die`'s tag's
140 * value. It remains unchanged on failure.
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.
146 int bt_dwarf_die_get_tag(struct bt_dwarf_die
*die
, int *tag
);
151 * On success, the `name` out parameter is set to the DIE's name. It
152 * remains unchanged on failure.
154 * @param die bt_dwarf_die instance
155 * @param name Out parameter, the DIE's name
156 * @returns 0 on success, -1 on failure
158 int bt_dwarf_die_get_name(struct bt_dwarf_die
*die
, char **name
);
161 * Get the full path to the DIE's callsite file.
163 * Only applies to DW_TAG_inlined_subroutine entries. The out
164 * parameter `filename` is set on success, unchanged on failure.
166 * @param die bt_dwarf_die instance
167 * @param filename Out parameter, the filename for the subroutine's
169 * @returns 0 on success, -1 on failure
171 int bt_dwarf_die_get_call_file(struct bt_dwarf_die
*die
, char **filename
);
174 * Get line number for the DIE's callsite.
176 * Only applies to DW_TAG_inlined_subroutine entries. The out
177 * parameter `line_no` is set on success, unchanged on failure.
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
184 int bt_dwarf_die_get_call_line(struct bt_dwarf_die
*die
,
188 * Verifies whether a given DIE contains the virtual memory address
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.
195 * @param die bt_dwarf_die instance
196 * @param addr The memory address to verify
197 * @param contains Out parameter, true if addr is contained,
199 * @returns 0 on success, -1 on failure
201 int bt_dwarf_die_contains_addr(struct bt_dwarf_die
*die
, uint64_t addr
,
204 #endif /* BABELTRACE_PLUGINS_LTTNG_UTILS_DEBUG_INFO_DWARF_H */
This page took 0.034125 seconds and 5 git commands to generate.