1 | //===-- UnwindPlan.h --------------------------------------------*- C++ -*-===// |
2 | // |
3 | // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
4 | // See https://llvm.org/LICENSE.txt for license information. |
5 | // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
6 | // |
7 | //===----------------------------------------------------------------------===// |
8 | |
9 | #ifndef LLDB_SYMBOL_UNWINDPLAN_H |
10 | #define LLDB_SYMBOL_UNWINDPLAN_H |
11 | |
12 | #include <map> |
13 | #include <memory> |
14 | #include <vector> |
15 | |
16 | #include "lldb/Core/AddressRange.h" |
17 | #include "lldb/Utility/ConstString.h" |
18 | #include "lldb/Utility/Stream.h" |
19 | #include "lldb/lldb-private.h" |
20 | |
21 | namespace lldb_private { |
22 | |
23 | // The UnwindPlan object specifies how to unwind out of a function - where this |
24 | // function saves the caller's register values before modifying them (for non- |
25 | // volatile aka saved registers) and how to find this frame's Canonical Frame |
26 | // Address (CFA) or Aligned Frame Address (AFA). |
27 | |
28 | // CFA is a DWARF's Canonical Frame Address. |
29 | // Most commonly, registers are saved on the stack, offset some bytes from the |
30 | // Canonical Frame Address, or CFA, which is the starting address of this |
31 | // function's stack frame (the CFA is same as the eh_frame's CFA, whatever that |
32 | // may be on a given architecture). The CFA address for the stack frame does |
33 | // not change during the lifetime of the function. |
34 | |
35 | // AFA is an artificially introduced Aligned Frame Address. |
36 | // It is used only for stack frames with realignment (e.g. when some of the |
37 | // locals has an alignment requirement higher than the stack alignment right |
38 | // after the function call). It is used to access register values saved on the |
39 | // stack after the realignment (and so they are inaccessible through the CFA). |
40 | // AFA usually equals the stack pointer value right after the realignment. |
41 | |
42 | // Internally, the UnwindPlan is structured as a vector of register locations |
43 | // organized by code address in the function, showing which registers have been |
44 | // saved at that point and where they are saved. It can be thought of as the |
45 | // expanded table form of the DWARF CFI encoded information. |
46 | |
47 | // Other unwind information sources will be converted into UnwindPlans before |
48 | // being added to a FuncUnwinders object. The unwind source may be an eh_frame |
49 | // FDE, a DWARF debug_frame FDE, or assembly language based prologue analysis. |
50 | // The UnwindPlan is the canonical form of this information that the unwinder |
51 | // code will use when walking the stack. |
52 | |
53 | class UnwindPlan { |
54 | public: |
55 | class Row { |
56 | public: |
57 | class RegisterLocation { |
58 | public: |
59 | enum RestoreType { |
60 | unspecified, // not specified, we may be able to assume this |
61 | // is the same register. gcc doesn't specify all |
62 | // initial values so we really don't know... |
63 | undefined, // reg is not available, e.g. volatile reg |
64 | same, // reg is unchanged |
65 | atCFAPlusOffset, // reg = deref(CFA + offset) |
66 | isCFAPlusOffset, // reg = CFA + offset |
67 | atAFAPlusOffset, // reg = deref(AFA + offset) |
68 | isAFAPlusOffset, // reg = AFA + offset |
69 | inOtherRegister, // reg = other reg |
70 | atDWARFExpression, // reg = deref(eval(dwarf_expr)) |
71 | isDWARFExpression // reg = eval(dwarf_expr) |
72 | }; |
73 | |
74 | RegisterLocation() : m_location() {} |
75 | |
76 | bool operator==(const RegisterLocation &rhs) const; |
77 | |
78 | bool operator!=(const RegisterLocation &rhs) const { |
79 | return !(*this == rhs); |
80 | } |
81 | |
82 | void SetUnspecified() { m_type = unspecified; } |
83 | |
84 | void SetUndefined() { m_type = undefined; } |
85 | |
86 | void SetSame() { m_type = same; } |
87 | |
88 | bool IsSame() const { return m_type == same; } |
89 | |
90 | bool IsUnspecified() const { return m_type == unspecified; } |
91 | |
92 | bool IsUndefined() const { return m_type == undefined; } |
93 | |
94 | bool IsCFAPlusOffset() const { return m_type == isCFAPlusOffset; } |
95 | |
96 | bool IsAtCFAPlusOffset() const { return m_type == atCFAPlusOffset; } |
97 | |
98 | bool IsAFAPlusOffset() const { return m_type == isAFAPlusOffset; } |
99 | |
100 | bool IsAtAFAPlusOffset() const { return m_type == atAFAPlusOffset; } |
101 | |
102 | bool IsInOtherRegister() const { return m_type == inOtherRegister; } |
103 | |
104 | bool IsAtDWARFExpression() const { return m_type == atDWARFExpression; } |
105 | |
106 | bool IsDWARFExpression() const { return m_type == isDWARFExpression; } |
107 | |
108 | void SetAtCFAPlusOffset(int32_t offset) { |
109 | m_type = atCFAPlusOffset; |
110 | m_location.offset = offset; |
111 | } |
112 | |
113 | void SetIsCFAPlusOffset(int32_t offset) { |
114 | m_type = isCFAPlusOffset; |
115 | m_location.offset = offset; |
116 | } |
117 | |
118 | void SetAtAFAPlusOffset(int32_t offset) { |
119 | m_type = atAFAPlusOffset; |
120 | m_location.offset = offset; |
121 | } |
122 | |
123 | void SetIsAFAPlusOffset(int32_t offset) { |
124 | m_type = isAFAPlusOffset; |
125 | m_location.offset = offset; |
126 | } |
127 | |
128 | void SetInRegister(uint32_t reg_num) { |
129 | m_type = inOtherRegister; |
130 | m_location.reg_num = reg_num; |
131 | } |
132 | |
133 | uint32_t GetRegisterNumber() const { |
134 | if (m_type == inOtherRegister) |
135 | return m_location.reg_num; |
136 | return LLDB_INVALID_REGNUM; |
137 | } |
138 | |
139 | RestoreType GetLocationType() const { return m_type; } |
140 | |
141 | int32_t GetOffset() const { |
142 | switch(m_type) |
143 | { |
144 | case atCFAPlusOffset: |
145 | case isCFAPlusOffset: |
146 | case atAFAPlusOffset: |
147 | case isAFAPlusOffset: |
148 | return m_location.offset; |
149 | default: |
150 | return 0; |
151 | } |
152 | } |
153 | |
154 | void GetDWARFExpr(const uint8_t **opcodes, uint16_t &len) const { |
155 | if (m_type == atDWARFExpression || m_type == isDWARFExpression) { |
156 | *opcodes = m_location.expr.opcodes; |
157 | len = m_location.expr.length; |
158 | } else { |
159 | *opcodes = nullptr; |
160 | len = 0; |
161 | } |
162 | } |
163 | |
164 | void SetAtDWARFExpression(const uint8_t *opcodes, uint32_t len); |
165 | |
166 | void SetIsDWARFExpression(const uint8_t *opcodes, uint32_t len); |
167 | |
168 | const uint8_t *GetDWARFExpressionBytes() { |
169 | if (m_type == atDWARFExpression || m_type == isDWARFExpression) |
170 | return m_location.expr.opcodes; |
171 | return nullptr; |
172 | } |
173 | |
174 | int GetDWARFExpressionLength() { |
175 | if (m_type == atDWARFExpression || m_type == isDWARFExpression) |
176 | return m_location.expr.length; |
177 | return 0; |
178 | } |
179 | |
180 | void Dump(Stream &s, const UnwindPlan *unwind_plan, |
181 | const UnwindPlan::Row *row, Thread *thread, bool verbose) const; |
182 | |
183 | private: |
184 | RestoreType m_type = unspecified; // How do we locate this register? |
185 | union { |
186 | // For m_type == atCFAPlusOffset or m_type == isCFAPlusOffset |
187 | int32_t offset; |
188 | // For m_type == inOtherRegister |
189 | uint32_t reg_num; // The register number |
190 | // For m_type == atDWARFExpression or m_type == isDWARFExpression |
191 | struct { |
192 | const uint8_t *opcodes; |
193 | uint16_t length; |
194 | } expr; |
195 | } m_location; |
196 | }; |
197 | |
198 | class FAValue { |
199 | public: |
200 | enum ValueType { |
201 | unspecified, // not specified |
202 | isRegisterPlusOffset, // FA = register + offset |
203 | isRegisterDereferenced, // FA = [reg] |
204 | isDWARFExpression, // FA = eval(dwarf_expr) |
205 | isRaSearch, // FA = SP + offset + ??? |
206 | }; |
207 | |
208 | FAValue() : m_value() {} |
209 | |
210 | bool operator==(const FAValue &rhs) const; |
211 | |
212 | bool operator!=(const FAValue &rhs) const { return !(*this == rhs); } |
213 | |
214 | void SetUnspecified() { m_type = unspecified; } |
215 | |
216 | bool IsUnspecified() const { return m_type == unspecified; } |
217 | |
218 | void SetRaSearch(int32_t offset) { |
219 | m_type = isRaSearch; |
220 | m_value.ra_search_offset = offset; |
221 | } |
222 | |
223 | bool IsRegisterPlusOffset() const { |
224 | return m_type == isRegisterPlusOffset; |
225 | } |
226 | |
227 | void SetIsRegisterPlusOffset(uint32_t reg_num, int32_t offset) { |
228 | m_type = isRegisterPlusOffset; |
229 | m_value.reg.reg_num = reg_num; |
230 | m_value.reg.offset = offset; |
231 | } |
232 | |
233 | bool IsRegisterDereferenced() const { |
234 | return m_type == isRegisterDereferenced; |
235 | } |
236 | |
237 | void SetIsRegisterDereferenced(uint32_t reg_num) { |
238 | m_type = isRegisterDereferenced; |
239 | m_value.reg.reg_num = reg_num; |
240 | } |
241 | |
242 | bool IsDWARFExpression() const { return m_type == isDWARFExpression; } |
243 | |
244 | void SetIsDWARFExpression(const uint8_t *opcodes, uint32_t len) { |
245 | m_type = isDWARFExpression; |
246 | m_value.expr.opcodes = opcodes; |
247 | m_value.expr.length = len; |
248 | } |
249 | |
250 | uint32_t GetRegisterNumber() const { |
251 | if (m_type == isRegisterDereferenced || m_type == isRegisterPlusOffset) |
252 | return m_value.reg.reg_num; |
253 | return LLDB_INVALID_REGNUM; |
254 | } |
255 | |
256 | ValueType GetValueType() const { return m_type; } |
257 | |
258 | int32_t GetOffset() const { |
259 | switch (m_type) { |
260 | case isRegisterPlusOffset: |
261 | return m_value.reg.offset; |
262 | case isRaSearch: |
263 | return m_value.ra_search_offset; |
264 | default: |
265 | return 0; |
266 | } |
267 | } |
268 | |
269 | void IncOffset(int32_t delta) { |
270 | if (m_type == isRegisterPlusOffset) |
271 | m_value.reg.offset += delta; |
272 | } |
273 | |
274 | void SetOffset(int32_t offset) { |
275 | if (m_type == isRegisterPlusOffset) |
276 | m_value.reg.offset = offset; |
277 | } |
278 | |
279 | void GetDWARFExpr(const uint8_t **opcodes, uint16_t &len) const { |
280 | if (m_type == isDWARFExpression) { |
281 | *opcodes = m_value.expr.opcodes; |
282 | len = m_value.expr.length; |
283 | } else { |
284 | *opcodes = nullptr; |
285 | len = 0; |
286 | } |
287 | } |
288 | |
289 | const uint8_t *GetDWARFExpressionBytes() { |
290 | if (m_type == isDWARFExpression) |
291 | return m_value.expr.opcodes; |
292 | return nullptr; |
293 | } |
294 | |
295 | int GetDWARFExpressionLength() { |
296 | if (m_type == isDWARFExpression) |
297 | return m_value.expr.length; |
298 | return 0; |
299 | } |
300 | |
301 | void Dump(Stream &s, const UnwindPlan *unwind_plan, Thread *thread) const; |
302 | |
303 | private: |
304 | ValueType m_type = unspecified; // How do we compute CFA value? |
305 | union { |
306 | struct { |
307 | // For m_type == isRegisterPlusOffset or m_type == |
308 | // isRegisterDereferenced |
309 | uint32_t reg_num; // The register number |
310 | // For m_type == isRegisterPlusOffset |
311 | int32_t offset; |
312 | } reg; |
313 | // For m_type == isDWARFExpression |
314 | struct { |
315 | const uint8_t *opcodes; |
316 | uint16_t length; |
317 | } expr; |
318 | // For m_type == isRaSearch |
319 | int32_t ra_search_offset; |
320 | } m_value; |
321 | }; // class FAValue |
322 | |
323 | Row(); |
324 | |
325 | bool operator==(const Row &rhs) const; |
326 | |
327 | bool GetRegisterInfo(uint32_t reg_num, |
328 | RegisterLocation ®ister_location) const; |
329 | |
330 | void SetRegisterInfo(uint32_t reg_num, |
331 | const RegisterLocation register_location); |
332 | |
333 | void RemoveRegisterInfo(uint32_t reg_num); |
334 | |
335 | lldb::addr_t GetOffset() const { return m_offset; } |
336 | |
337 | void SetOffset(lldb::addr_t offset) { m_offset = offset; } |
338 | |
339 | void SlideOffset(lldb::addr_t offset) { m_offset += offset; } |
340 | |
341 | FAValue &GetCFAValue() { return m_cfa_value; } |
342 | |
343 | FAValue &GetAFAValue() { return m_afa_value; } |
344 | |
345 | bool SetRegisterLocationToAtCFAPlusOffset(uint32_t reg_num, int32_t offset, |
346 | bool can_replace); |
347 | |
348 | bool SetRegisterLocationToIsCFAPlusOffset(uint32_t reg_num, int32_t offset, |
349 | bool can_replace); |
350 | |
351 | bool SetRegisterLocationToUndefined(uint32_t reg_num, bool can_replace, |
352 | bool can_replace_only_if_unspecified); |
353 | |
354 | bool SetRegisterLocationToUnspecified(uint32_t reg_num, bool can_replace); |
355 | |
356 | bool SetRegisterLocationToRegister(uint32_t reg_num, uint32_t other_reg_num, |
357 | bool can_replace); |
358 | |
359 | bool SetRegisterLocationToSame(uint32_t reg_num, bool must_replace); |
360 | |
361 | // When this UnspecifiedRegistersAreUndefined mode is |
362 | // set, any register that is not specified by this Row will |
363 | // be described as Undefined. |
364 | // This will prevent the unwinder from iterating down the |
365 | // stack looking for a spill location, or a live register value |
366 | // at frame 0. |
367 | // It would be used for an UnwindPlan row where we can't track |
368 | // spilled registers -- for instance a jitted stack frame where |
369 | // we have no unwind information or start address -- and registers |
370 | // MAY have been spilled and overwritten, so providing the |
371 | // spilled/live value from a newer frame may show an incorrect value. |
372 | void SetUnspecifiedRegistersAreUndefined(bool unspec_is_undef) { |
373 | m_unspecified_registers_are_undefined = unspec_is_undef; |
374 | } |
375 | |
376 | bool GetUnspecifiedRegistersAreUndefined() { |
377 | return m_unspecified_registers_are_undefined; |
378 | } |
379 | |
380 | void Clear(); |
381 | |
382 | void Dump(Stream &s, const UnwindPlan *unwind_plan, Thread *thread, |
383 | lldb::addr_t base_addr) const; |
384 | |
385 | protected: |
386 | typedef std::map<uint32_t, RegisterLocation> collection; |
387 | lldb::addr_t m_offset = 0; // Offset into the function for this row |
388 | |
389 | FAValue m_cfa_value; |
390 | FAValue m_afa_value; |
391 | collection m_register_locations; |
392 | bool m_unspecified_registers_are_undefined = false; |
393 | }; // class Row |
394 | |
395 | typedef std::shared_ptr<Row> RowSP; |
396 | |
397 | UnwindPlan(lldb::RegisterKind reg_kind) |
398 | : m_register_kind(reg_kind), m_return_addr_register(LLDB_INVALID_REGNUM), |
399 | m_plan_is_sourced_from_compiler(eLazyBoolCalculate), |
400 | m_plan_is_valid_at_all_instruction_locations(eLazyBoolCalculate), |
401 | m_plan_is_for_signal_trap(eLazyBoolCalculate) {} |
402 | |
403 | // Performs a deep copy of the plan, including all the rows (expensive). |
404 | UnwindPlan(const UnwindPlan &rhs) |
405 | : m_plan_valid_address_range(rhs.m_plan_valid_address_range), |
406 | m_register_kind(rhs.m_register_kind), |
407 | m_return_addr_register(rhs.m_return_addr_register), |
408 | m_source_name(rhs.m_source_name), |
409 | m_plan_is_sourced_from_compiler(rhs.m_plan_is_sourced_from_compiler), |
410 | m_plan_is_valid_at_all_instruction_locations( |
411 | rhs.m_plan_is_valid_at_all_instruction_locations), |
412 | m_plan_is_for_signal_trap(rhs.m_plan_is_for_signal_trap), |
413 | m_lsda_address(rhs.m_lsda_address), |
414 | m_personality_func_addr(rhs.m_personality_func_addr) { |
415 | m_row_list.reserve(n: rhs.m_row_list.size()); |
416 | for (const RowSP &row_sp : rhs.m_row_list) |
417 | m_row_list.emplace_back(args: new Row(*row_sp)); |
418 | } |
419 | |
420 | ~UnwindPlan() = default; |
421 | |
422 | void Dump(Stream &s, Thread *thread, lldb::addr_t base_addr) const; |
423 | |
424 | void AppendRow(const RowSP &row_sp); |
425 | |
426 | void InsertRow(const RowSP &row_sp, bool replace_existing = false); |
427 | |
428 | // Returns a pointer to the best row for the given offset into the function's |
429 | // instructions. If offset is -1 it indicates that the function start is |
430 | // unknown - the final row in the UnwindPlan is returned. In practice, the |
431 | // UnwindPlan for a function with no known start address will be the |
432 | // architectural default UnwindPlan which will only have one row. |
433 | UnwindPlan::RowSP GetRowForFunctionOffset(int offset) const; |
434 | |
435 | lldb::RegisterKind GetRegisterKind() const { return m_register_kind; } |
436 | |
437 | void SetRegisterKind(lldb::RegisterKind kind) { m_register_kind = kind; } |
438 | |
439 | void SetReturnAddressRegister(uint32_t regnum) { |
440 | m_return_addr_register = regnum; |
441 | } |
442 | |
443 | uint32_t GetReturnAddressRegister() { return m_return_addr_register; } |
444 | |
445 | uint32_t GetInitialCFARegister() const { |
446 | if (m_row_list.empty()) |
447 | return LLDB_INVALID_REGNUM; |
448 | return m_row_list.front()->GetCFAValue().GetRegisterNumber(); |
449 | } |
450 | |
451 | // This UnwindPlan may not be valid at every address of the function span. |
452 | // For instance, a FastUnwindPlan will not be valid at the prologue setup |
453 | // instructions - only in the body of the function. |
454 | void SetPlanValidAddressRange(const AddressRange &range); |
455 | |
456 | const AddressRange &GetAddressRange() const { |
457 | return m_plan_valid_address_range; |
458 | } |
459 | |
460 | bool PlanValidAtAddress(Address addr); |
461 | |
462 | bool IsValidRowIndex(uint32_t idx) const; |
463 | |
464 | const UnwindPlan::RowSP GetRowAtIndex(uint32_t idx) const; |
465 | |
466 | const UnwindPlan::RowSP GetLastRow() const; |
467 | |
468 | lldb_private::ConstString GetSourceName() const; |
469 | |
470 | void SetSourceName(const char *); |
471 | |
472 | // Was this UnwindPlan emitted by a compiler? |
473 | lldb_private::LazyBool GetSourcedFromCompiler() const { |
474 | return m_plan_is_sourced_from_compiler; |
475 | } |
476 | |
477 | // Was this UnwindPlan emitted by a compiler? |
478 | void SetSourcedFromCompiler(lldb_private::LazyBool from_compiler) { |
479 | m_plan_is_sourced_from_compiler = from_compiler; |
480 | } |
481 | |
482 | // Is this UnwindPlan valid at all instructions? If not, then it is assumed |
483 | // valid at call sites, e.g. for exception handling. |
484 | lldb_private::LazyBool GetUnwindPlanValidAtAllInstructions() const { |
485 | return m_plan_is_valid_at_all_instruction_locations; |
486 | } |
487 | |
488 | // Is this UnwindPlan valid at all instructions? If not, then it is assumed |
489 | // valid at call sites, e.g. for exception handling. |
490 | void SetUnwindPlanValidAtAllInstructions( |
491 | lldb_private::LazyBool valid_at_all_insn) { |
492 | m_plan_is_valid_at_all_instruction_locations = valid_at_all_insn; |
493 | } |
494 | |
495 | // Is this UnwindPlan for a signal trap frame? If so, then its saved pc |
496 | // may have been set manually by the signal dispatch code and therefore |
497 | // not follow a call to the child frame. |
498 | lldb_private::LazyBool GetUnwindPlanForSignalTrap() const { |
499 | return m_plan_is_for_signal_trap; |
500 | } |
501 | |
502 | void SetUnwindPlanForSignalTrap(lldb_private::LazyBool is_for_signal_trap) { |
503 | m_plan_is_for_signal_trap = is_for_signal_trap; |
504 | } |
505 | |
506 | int GetRowCount() const; |
507 | |
508 | void Clear() { |
509 | m_row_list.clear(); |
510 | m_plan_valid_address_range.Clear(); |
511 | m_register_kind = lldb::eRegisterKindDWARF; |
512 | m_source_name.Clear(); |
513 | m_plan_is_sourced_from_compiler = eLazyBoolCalculate; |
514 | m_plan_is_valid_at_all_instruction_locations = eLazyBoolCalculate; |
515 | m_plan_is_for_signal_trap = eLazyBoolCalculate; |
516 | m_lsda_address.Clear(); |
517 | m_personality_func_addr.Clear(); |
518 | } |
519 | |
520 | const RegisterInfo *GetRegisterInfo(Thread *thread, uint32_t reg_num) const; |
521 | |
522 | Address GetLSDAAddress() const { return m_lsda_address; } |
523 | |
524 | void SetLSDAAddress(Address lsda_addr) { m_lsda_address = lsda_addr; } |
525 | |
526 | Address GetPersonalityFunctionPtr() const { return m_personality_func_addr; } |
527 | |
528 | void SetPersonalityFunctionPtr(Address presonality_func_ptr) { |
529 | m_personality_func_addr = presonality_func_ptr; |
530 | } |
531 | |
532 | private: |
533 | typedef std::vector<RowSP> collection; |
534 | collection m_row_list; |
535 | AddressRange m_plan_valid_address_range; |
536 | lldb::RegisterKind m_register_kind; // The RegisterKind these register numbers |
537 | // are in terms of - will need to be |
538 | // translated to lldb native reg nums at unwind time |
539 | uint32_t m_return_addr_register; // The register that has the return address |
540 | // for the caller frame |
541 | // e.g. the lr on arm |
542 | lldb_private::ConstString |
543 | m_source_name; // for logging, where this UnwindPlan originated from |
544 | lldb_private::LazyBool m_plan_is_sourced_from_compiler; |
545 | lldb_private::LazyBool m_plan_is_valid_at_all_instruction_locations; |
546 | lldb_private::LazyBool m_plan_is_for_signal_trap; |
547 | |
548 | Address m_lsda_address; // Where the language specific data area exists in the |
549 | // module - used |
550 | // in exception handling. |
551 | Address m_personality_func_addr; // The address of a pointer to the |
552 | // personality function - used in |
553 | // exception handling. |
554 | }; // class UnwindPlan |
555 | |
556 | } // namespace lldb_private |
557 | |
558 | #endif // LLDB_SYMBOL_UNWINDPLAN_H |
559 | |