[deliverable/babeltrace.git] / include / babeltrace / dwarf.h

#ifndef _BABELTRACE_DWARF_H
#define _BABELTRACE_DWARF_H

/*
 * Babeltrace - DWARF Information Reader
 *
 * Copyright 2015 Antoine Busque <abusque@efficios.com>
 *
 * Author: Antoine Busque <abusque@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <dwarf.h>
#include <elfutils/libdw.h>
#include <babeltrace/babeltrace-internal.h>

/*
 * bt_dwarf is a wrapper over libdw providing a nicer, higher-level
 * interface, to access basic debug information.
 */

/*
 * This structure corresponds to a single compilation unit (CU) for a
 * given set of debug information (Dwarf type).
 */
struct bt_dwarf_cu {
	Dwarf *dwarf_info;
	/* Offset in bytes in the DWARF file to current CU header. */
	Dwarf_Off offset;
	/* Offset in bytes in the DWARF file to next CU header. */
	Dwarf_Off next_offset;
	/* Size in bytes of CU header */
	size_t header_size;
};

/*
 * This structure represents a single debug information entry (DIE),
 * within a compilation unit (CU).
 */
struct bt_dwarf_die {
	struct bt_dwarf_cu *cu;
	Dwarf_Die *dwarf_die;
	/*
	 * A depth of 0 represents a root DIE, located in the DWARF
	 * layout on the same level as its corresponding CU entry. Its
	 * children DIEs will have a depth of 1, and so forth.
	 */
	unsigned int depth;
};

/**
 * Instantiate a structure to access compile units (CU) from a given
 * `dwarf_info`.
 *
 * @param dwarf_info	Dwarf instance
 * @returns		Pointer to the new bt_dwarf_cu on success,
 *			NULL on failure.
 */
BT_HIDDEN
struct bt_dwarf_cu *bt_dwarf_cu_create(Dwarf *dwarf_info);

/**
 * Destroy the given bt_dwarf_cu instance.
 *
 * @param cu	bt_dwarf_cu instance
 */
BT_HIDDEN
void bt_dwarf_cu_destroy(struct bt_dwarf_cu *cu);

/**
 * Advance the compile unit `cu` to the next one.
 *
 * On success, `cu`'s offset is set to that of the current compile
 * unit in the executable. On failure, `cu` remains unchanged.
 *
 * @param cu	bt_dwarf_cu instance
 * @returns	0 on success, 1 if no next CU is available,
 *		-1 on failure
 */
BT_HIDDEN
int bt_dwarf_cu_next(struct bt_dwarf_cu *cu);

/**
 * Instantiate a structure to access debug information entries (DIE)
 * for the given compile unit `cu`.
 *
 * @param cu	bt_dwarf_cu instance
 * @returns	Pointer to the new bt_dwarf_die on success,
 *		NULL on failure.
 */
BT_HIDDEN
struct bt_dwarf_die *bt_dwarf_die_create(struct bt_dwarf_cu *cu);

/**
 * Destroy the given bt_dwarf_die instance.
 *
 * @param die	bt_dwarf_die instance
 */
BT_HIDDEN
void bt_dwarf_die_destroy(struct bt_dwarf_die *die);

/**
 * Advance the debug information entry `die` to its first child, if
 * any.
 *
 * @param die	bt_dwarf_die instance
 * @returns	0 on success, 1 if no child DIE is available,
 * 		-1 on failure
 */
BT_HIDDEN
int bt_dwarf_die_child(struct bt_dwarf_die *die);

/**
 * Advance the debug information entry `die` to the next one.
 *
 * The next DIE is considered to be its sibling on the same level. The
 * only exception is when the depth of the given DIE is 0, i.e. a
 * newly created bt_dwarf_die, in which case next returns the first
 * DIE at depth 1.
 *
 * The reason for staying at a depth of 1 is that this is where all
 * the function DIEs (those with a tag value of DW_TAG_subprogram) are
 * located, from which more specific child DIEs can then be accessed
 * if needed via bt_dwarf_die_child.
 *
 * @param die	bt_dwarf_die instance
 * @returns	0 on success, 1 if no other siblings are available, -1 on
 *		failure
 */
BT_HIDDEN
int bt_dwarf_die_next(struct bt_dwarf_die *die);

/**
 * Get a DIE's tag.
 *
 * On success, the `tag` out parameter is set to the `die`'s tag's
 * value. It remains unchanged on failure.
 *
 * @param die	bt_dwarf_die instance
 * @param tag	Out parameter, the DIE's tag value
 * @returns	0 on success, -1 on failure.
 */
BT_HIDDEN
int bt_dwarf_die_get_tag(struct bt_dwarf_die *die, int *tag);

/**
 * Get a DIE's name.
 *
 * On success, the `name` out parameter is set to the DIE's name. It
 * remains unchanged on failure.
 *
 * @param die	bt_dwarf_die instance
 * @param name	Out parameter, the DIE's name
 * @returns	0 on success, -1 on failure
 */
BT_HIDDEN
int bt_dwarf_die_get_name(struct bt_dwarf_die *die, char **name);

/**
 * Get the full path to the DIE's callsite file.
 *
 * Only applies to DW_TAG_inlined_subroutine entries. The out
 * parameter `filename` is set on success, unchanged on failure.
 *
 * @param die		bt_dwarf_die instance
 * @param filename	Out parameter, the filename for the subroutine's
 *			callsite
 * @returns		0 on success, -1 on failure
 */
BT_HIDDEN
int bt_dwarf_die_get_call_file(struct bt_dwarf_die *die, char **filename);

/**
 * Get line number for the DIE's callsite.
 *
 * Only applies to DW_TAG_inlined_subroutine entries. The out
 * parameter `line_no` is set on success, unchanged on failure.
 *
 * @param die		bt_dwarf_die instance
 * @param line_no	Out parameter, the line number for the
 *			subroutine's callsite
 * @returns		0 on success, -1 on failure
 */
BT_HIDDEN
int bt_dwarf_die_get_call_line(struct bt_dwarf_die *die,
		uint64_t *line_no);

/**
 * Verifies whether a given DIE contains the virtual memory address
 * `addr`.
 *
 * On success, the out parameter `contains` is set with the boolean
 * value indicating whether the DIE's range covers `addr`. On failure,
 * it remains unchanged.
 *
 * @param die		bt_dwarf_die instance
 * @param addr		The memory address to verify
 * @param contains	Out parameter, true if addr is contained,
 *			false if not
 * @returns		0 on succes, -1 on failure
 */
BT_HIDDEN
int bt_dwarf_die_contains_addr(struct bt_dwarf_die *die, uint64_t addr,
		bool *contains);

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