src/plugins/lttng-utils/debug-info/dwarf.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright 2015 Antoine Busque <abusque@efficios.com>
   5  *
   6  * Babeltrace - DWARF Information Reader
   7  */
   8
   9 #ifndef _BABELTRACE_DWARF_H
  10 #define _BABELTRACE_DWARF_H
  11
  12 #include <stdbool.h>
  13 #include <stdint.h>
  14 #include <stdlib.h>
  15 #include <dwarf.h>
  16 #include <elfutils/libdw.h>
  17 #include "common/macros.h"
  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
 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
 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
 209  * @param contains      Out parameter, true if addr is contained,
 210  *                      false if not
 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,
 215                 bool *contains);
 216
 217 #endif  /* _BABELTRACE_DWARF_H */