| 1 |
// Copyright (c) Meta Platforms, Inc. and affiliates. |
| 2 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 3 |
|
| 4 |
/** |
| 5 |
* @file |
| 6 |
* |
| 7 |
* Call frame information |
| 8 |
* |
| 9 |
* See @ref CallFrameInformation. |
| 10 |
*/ |
| 11 |
|
| 12 |
#ifndef DRGN_CFI_H |
| 13 |
#define DRGN_CFI_H |
| 14 |
|
| 15 |
#include <stdbool.h> |
| 16 |
#include <stdint.h> |
| 17 |
#include <stdlib.h> |
| 18 |
|
| 19 |
/** |
| 20 |
* @ingroup Internals |
| 21 |
* |
| 22 |
* @defgroup CallFrameInformation Call frame information |
| 23 |
* |
| 24 |
* Call frame information for stack unwinding. |
| 25 |
* |
| 26 |
* This defines a generic representation for Call Frame Information (CFI), which |
| 27 |
* describes how to determine the Canonical Frame Address (CFA) and previous |
| 28 |
* register values while unwinding a stack trace. |
| 29 |
* |
| 30 |
* @{ |
| 31 |
*/ |
| 32 |
|
| 33 |
/** |
| 34 |
* Numeric identifier for a register. |
| 35 |
* |
| 36 |
* These are only unique within an architecture, and they are not necessarily |
| 37 |
* the same as the register numbers used by DWARF. |
| 38 |
*/ |
| 39 |
typedef uint16_t drgn_register_number; |
| 40 |
|
| 41 |
/** Maximum valid register number. */ |
| 42 |
#define DRGN_MAX_REGISTER_NUMBER ((drgn_register_number)-3) |
| 43 |
/** Placeholder number for unknown register. */ |
| 44 |
#define DRGN_REGISTER_NUMBER_UNKNOWN ((drgn_register_number)-1) |
| 45 |
|
| 46 |
/** Kinds of CFI rules. */ |
| 47 |
enum drgn_cfi_rule_kind { |
| 48 |
/** Register value in the caller is not known. */ |
| 49 |
DRGN_CFI_RULE_UNDEFINED, |
| 50 |
/** |
| 51 |
* Register value in the caller is stored at the CFA in the current |
| 52 |
* frame plus an offset: `*(cfa + offset)`. |
| 53 |
*/ |
| 54 |
DRGN_CFI_RULE_AT_CFA_PLUS_OFFSET, |
| 55 |
/** |
| 56 |
* Register value in the caller is the CFA in the current frame plus an |
| 57 |
* offset: `cfa + offset`. |
| 58 |
*/ |
| 59 |
DRGN_CFI_RULE_CFA_PLUS_OFFSET, |
| 60 |
/** |
| 61 |
* Register value in the caller is stored at the value of a register in |
| 62 |
* the current frame plus an offset: `*(reg + offset)`. |
| 63 |
*/ |
| 64 |
DRGN_CFI_RULE_AT_REGISTER_PLUS_OFFSET, |
| 65 |
/** |
| 66 |
* Register value in the caller is an offset plus the value stored at |
| 67 |
* the value of a register in the current frame: `(*reg) + offset`. |
| 68 |
*/ |
| 69 |
DRGN_CFI_RULE_AT_REGISTER_ADD_OFFSET, |
| 70 |
/** |
| 71 |
* Register value in the caller is the value of a register in the |
| 72 |
* current frame plus an offset: `reg + offset`. |
| 73 |
* |
| 74 |
* Note that this can also be used to represent DWARF's "same value" |
| 75 |
* rule by using the same register with an offset of 0. |
| 76 |
*/ |
| 77 |
DRGN_CFI_RULE_REGISTER_PLUS_OFFSET, |
| 78 |
/** |
| 79 |
* Register value in the caller is stored at the address given by a |
| 80 |
* DWARF expression. |
| 81 |
*/ |
| 82 |
DRGN_CFI_RULE_AT_DWARF_EXPRESSION, |
| 83 |
/** Register value in the caller is given by a DWARF expression. */ |
| 84 |
DRGN_CFI_RULE_DWARF_EXPRESSION, |
| 85 |
/** Register value in the caller has a constant value. */ |
| 86 |
DRGN_CFI_RULE_CONSTANT, |
| 87 |
} __attribute__((__packed__)); |
| 88 |
|
| 89 |
/** Rule for determining a single register value or CFA. */ |
| 90 |
struct drgn_cfi_rule { |
| 91 |
/** Rule kind. */ |
| 92 |
enum drgn_cfi_rule_kind kind; |
| 93 |
/** |
| 94 |
* Whether to push the CFA before evaluating the DWARF |
| 95 |
* expression for @ref DRGN_CFI_RULE_AT_DWARF_EXPRESSION or @ref |
| 96 |
* DRGN_CFI_RULE_DWARF_EXPRESSION. |
| 97 |
*/ |
| 98 |
bool push_cfa; |
| 99 |
/** Register number for @ref DRGN_CFI_RULE_REGISTER_PLUS_OFFSET. */ |
| 100 |
drgn_register_number regno; |
| 101 |
union { |
| 102 |
/** |
| 103 |
* Offset for @ref DRGN_CFI_RULE_AT_CFA_PLUS_OFFSET, @ref |
| 104 |
* DRGN_CFI_RULE_CFA_PLUS_OFFSET, @ref |
| 105 |
* DRGN_CFI_RULE_AT_REGISTER_PLUS_OFFSET, @ref |
| 106 |
* DRGN_CFI_RULE_AT_REGISTER_ADD_OFFSET, and @ref |
| 107 |
* DRGN_CFI_RULE_REGISTER_PLUS_OFFSET. |
| 108 |
*/ |
| 109 |
int64_t offset; |
| 110 |
/** Constant for @ref DRGN_CFI_RULE_CONSTANT. */ |
| 111 |
uint64_t constant; |
| 112 |
/** |
| 113 |
* DWARF expression for @ref DRGN_CFI_RULE_AT_DWARF_EXPRESSION |
| 114 |
* and @ref DRGN_CFI_RULE_DWARF_EXPRESSION. |
| 115 |
*/ |
| 116 |
struct { |
| 117 |
/** Pointer to expression data. */ |
| 118 |
const char *expr; |
| 119 |
/** Size of @ref drgn_cfi_rule::expr. */ |
| 120 |
size_t expr_size; |
| 121 |
}; |
| 122 |
}; |
| 123 |
}; |
| 124 |
|
| 125 |
/** |
| 126 |
* "Row" of call frame information, i.e., how to get the CFA and the previous |
| 127 |
* value of each register at a single location in the program. |
| 128 |
* |
| 129 |
* A row may be allocated statically or on the heap. Static rows are created |
| 130 |
* with @ref DRGN_CFI_ROW(). The first time a static row would be modified (with |
| 131 |
* @ref drgn_cfi_row_copy(), @ref drgn_cfi_row_set_cfa(), or @ref |
| 132 |
* drgn_cfi_row_set_register()), it is first copied to the heap. Subsequent |
| 133 |
* modifications reuse the heap allocation, growing it if necessary. The |
| 134 |
* allocation must be freed with @ref drgn_cfi_row_destroy(). |
| 135 |
*/ |
| 136 |
struct drgn_cfi_row { |
| 137 |
/** |
| 138 |
* Number of rules allocated, including the CFA rule. |
| 139 |
* |
| 140 |
* If the row is statically allocated, then this is zero, even if |
| 141 |
* `num_regs` is non-zero. Otherwise, it is at least `num_regs + 1`. |
| 142 |
*/ |
| 143 |
uint16_t allocated_rules; |
| 144 |
/** Number of initialized elements in `reg_rules`. */ |
| 145 |
uint16_t num_regs; |
| 146 |
/** Canonical Frame Address rule. */ |
| 147 |
struct drgn_cfi_rule cfa_rule; |
| 148 |
/** Register rules. */ |
| 149 |
struct drgn_cfi_rule reg_rules[]; |
| 150 |
}; |
| 151 |
|
| 152 |
/** |
| 153 |
* Initializer for a static @ref drgn_cfi_row given initializers for @ref |
| 154 |
* drgn_cfi_row::reg_rules. |
| 155 |
*/ |
| 156 |
#define DRGN_CFI_ROW(...) { \ |
| 157 |
.num_regs = (sizeof((struct drgn_cfi_rule []){ __VA_ARGS__ }) \ |
| 158 |
/ sizeof(struct drgn_cfi_rule)), \ |
| 159 |
.reg_rules = { __VA_ARGS__ }, \ |
| 160 |
} |
| 161 |
|
| 162 |
/** |
| 163 |
* Initializer for a rule in @ref drgn_cfi_row::reg_rules specifying that the |
| 164 |
* register with the given number has the same value in the caller. |
| 165 |
*/ |
| 166 |
#define DRGN_CFI_SAME_VALUE_INIT(number) \ |
| 167 |
[(number)] = { \ |
| 168 |
.kind = DRGN_CFI_RULE_REGISTER_PLUS_OFFSET, \ |
| 169 |
.regno = (number), \ |
| 170 |
} |
| 171 |
|
| 172 |
extern const struct drgn_cfi_row drgn_empty_cfi_row_impl; |
| 173 |
/** |
| 174 |
* Static @ref drgn_cfi_row with all rules set to @ref DRGN_CFI_RULE_UNDEFINED. |
| 175 |
*/ |
| 176 |
#define drgn_empty_cfi_row ((struct drgn_cfi_row *)&drgn_empty_cfi_row_impl) |
| 177 |
|
| 178 |
/** Free a @ref drgn_cfi_row. */ |
| 179 |
static inline void drgn_cfi_row_destroy(struct drgn_cfi_row *row) |
| 180 |
{ |
| 181 |
if (row->allocated_rules > 0) |
| 182 |
free(row); |
| 183 |
} |
| 184 |
|
| 185 |
/** Copy the rules from one @ref drgn_cfi_row to another. */ |
| 186 |
bool drgn_cfi_row_copy(struct drgn_cfi_row **dst, |
| 187 |
const struct drgn_cfi_row *src); |
| 188 |
|
| 189 |
/** |
| 190 |
* Get the rule for the Canonical Frame Address in a @ref drgn_cfi_row. |
| 191 |
* |
| 192 |
* @param[out] ret Returned rule. |
| 193 |
*/ |
| 194 |
static inline void drgn_cfi_row_get_cfa(const struct drgn_cfi_row *row, |
| 195 |
struct drgn_cfi_rule *ret) |
| 196 |
{ |
| 197 |
*ret = row->cfa_rule; |
| 198 |
} |
| 199 |
|
| 200 |
/** |
| 201 |
* Set the rule for the Canonical Frame Address in a @ref drgn_cfi_row. |
| 202 |
* |
| 203 |
* @param[in] rule Rule to set to. |
| 204 |
* @return @c true on success, @c false on failure to allocate memory. |
| 205 |
*/ |
| 206 |
bool drgn_cfi_row_set_cfa(struct drgn_cfi_row **row, |
| 207 |
const struct drgn_cfi_rule *rule); |
| 208 |
|
| 209 |
/** |
| 210 |
* Get the rule for a register in a @ref drgn_cfi_row. |
| 211 |
* |
| 212 |
* @param[in] regno Register number. |
| 213 |
*/ |
| 214 |
void drgn_cfi_row_get_register(const struct drgn_cfi_row *row, |
| 215 |
drgn_register_number regno, |
| 216 |
struct drgn_cfi_rule *ret); |
| 217 |
|
| 218 |
/** |
| 219 |
* Set the rule for a register in a @ref drgn_cfi_row. |
| 220 |
* |
| 221 |
* @param[in] regno Register number. |
| 222 |
* @param[in] rule Rule to set to. |
| 223 |
* @return @c true on success, @c false on failure to allocate memory. |
| 224 |
*/ |
| 225 |
bool drgn_cfi_row_set_register(struct drgn_cfi_row **row, |
| 226 |
drgn_register_number regno, |
| 227 |
const struct drgn_cfi_rule *rule); |
| 228 |
|
| 229 |
/** @} */ |
| 230 |
|
| 231 |
#endif /* DRGN_CFI_H */ |