plugins/lttng-utils/debug-info/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 <stdbool.h>
  31 #include <stdint.h>
  32 #include <stdlib.h>
  33 #include <dwarf.h>
  34 #include <elfutils/libdw.h>
  35 #include <babeltrace2/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  * Indicates if the debug information entry `die` has children DIEs.
 124  *
 125  * @param die   bt_dwarf_die instance
 126  * @returns     0 if the die no child, 1 otherwise
 127  */
 128 BT_HIDDEN
 129 int bt_dwarf_die_has_children(struct bt_dwarf_die *die);
 130
 131 /**
 132  * Advance the debug information entry `die` to its first child, if
 133  * any.
 134  *
 135  * @param die   bt_dwarf_die instance
 136  * @returns     0 on success, 1 if no child DIE is available,
 137  *              -1 on failure
 138  */
 139 BT_HIDDEN
 140 int bt_dwarf_die_child(struct bt_dwarf_die *die);
 141
 142 /**
 143  * Advance the debug information entry `die` to the next one.
 144  *
 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
 148  * DIE at depth 1.
 149  *
 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.
 154  *
 155  * @param die   bt_dwarf_die instance
 156  * @returns     0 on success, 1 if no other siblings are available, -1 on
 157  *              failure
 158  */
 159 BT_HIDDEN
 160 int bt_dwarf_die_next(struct bt_dwarf_die *die);
 161
 162 /**
 163  * Get a DIE's tag.
 164  *
 165  * On success, the `tag` out parameter is set to the `die`'s tag's
 166  * value. It remains unchanged on failure.
 167  *
 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.
 171  */
 172 BT_HIDDEN
 173 int bt_dwarf_die_get_tag(struct bt_dwarf_die *die, int *tag);
 174
 175 /**
 176  * Get a DIE's name.
 177  *
 178  * On success, the `name` out parameter is set to the DIE's name. It
 179  * remains unchanged on failure.
 180  *
 181  * @param die   bt_dwarf_die instance
 182  * @param name  Out parameter, the DIE's name
 183  * @returns     0 on success, -1 on failure
 184  */
 185 BT_HIDDEN
 186 int bt_dwarf_die_get_name(struct bt_dwarf_die *die, char **name);
 187
 188 /**
 189  * Get the full path to the DIE's callsite file.
 190  *
 191  * Only applies to DW_TAG_inlined_subroutine entries. The out
 192  * parameter `filename` is set on success, unchanged on failure.
 193  *
 194  * @param die           bt_dwarf_die instance
 195  * @param filename      Out parameter, the filename for the subroutine's
 196  *                      callsite
 197  * @returns             0 on success, -1 on failure
 198  */
 199 BT_HIDDEN
 200 int bt_dwarf_die_get_call_file(struct bt_dwarf_die *die, char **filename);
 201
 202 /**
 203  * Get line number for the DIE's callsite.
 204  *
 205  * Only applies to DW_TAG_inlined_subroutine entries. The out
 206  * parameter `line_no` is set on success, unchanged on failure.
 207  *
 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
 212  */
 213 BT_HIDDEN
 214 int bt_dwarf_die_get_call_line(struct bt_dwarf_die *die,
 215                 uint64_t *line_no);
 216
 217 /**
 218  * Verifies whether a given DIE contains the virtual memory address
 219  * `addr`.
 220  *
 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.
 224  *
 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,
 228  *                      false if not
 229  * @returns             0 on succes, -1 on failure
 230  */
 231 BT_HIDDEN
 232 int bt_dwarf_die_contains_addr(struct bt_dwarf_die *die, uint64_t addr,
 233                 bool *contains);
 234
 235 #endif  /* _BABELTRACE_DWARF_H */