1//===-- DWARFCallFrameInfo.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_DWARFCALLFRAMEINFO_H
10#define LLDB_SYMBOL_DWARFCALLFRAMEINFO_H
11
12#include <map>
13#include <mutex>
14#include <optional>
15
16#include "lldb/Core/AddressRange.h"
17#include "lldb/Core/dwarf.h"
18#include "lldb/Symbol/ObjectFile.h"
19#include "lldb/Symbol/UnwindPlan.h"
20#include "lldb/Utility/Flags.h"
21#include "lldb/Utility/RangeMap.h"
22#include "lldb/Utility/VMRange.h"
23#include "lldb/lldb-private.h"
24
25namespace lldb_private {
26
27// DWARFCallFrameInfo is a class which can read eh_frame and DWARF Call Frame
28// Information FDEs.  It stores little information internally. Only two APIs
29// are exported - one to find the high/low pc values of a function given a text
30// address via the information in the eh_frame / debug_frame, and one to
31// generate an UnwindPlan based on the FDE in the eh_frame / debug_frame
32// section.
33
34class DWARFCallFrameInfo {
35public:
36  enum Type { EH, DWARF };
37
38  DWARFCallFrameInfo(ObjectFile &objfile, lldb::SectionSP &section, Type type);
39
40  ~DWARFCallFrameInfo() = default;
41
42  // Locate an AddressRange that includes the provided Address in this object's
43  // eh_frame/debug_info Returns true if a range is found to cover that
44  // address.
45  bool GetAddressRange(Address addr, AddressRange &range);
46
47  /// Return an UnwindPlan based on the call frame information encoded in the
48  /// FDE of this DWARFCallFrameInfo section. The returned plan will be valid
49  /// (at least) for the given address.
50  bool GetUnwindPlan(const Address &addr, UnwindPlan &unwind_plan);
51
52  /// Return an UnwindPlan based on the call frame information encoded in the
53  /// FDE of this DWARFCallFrameInfo section. The returned plan will be valid
54  /// (at least) for some address in the given range.
55  bool GetUnwindPlan(const AddressRange &range, UnwindPlan &unwind_plan);
56
57  typedef RangeVector<lldb::addr_t, uint32_t> FunctionAddressAndSizeVector;
58
59  // Build a vector of file address and size for all functions in this Module
60  // based on the eh_frame FDE entries.
61  //
62  // The eh_frame information can be a useful source of file address and size
63  // of the functions in a Module.  Often a binary's non-exported symbols are
64  // stripped before shipping so lldb won't know the start addr / size of many
65  // functions in the Module.  But the eh_frame can help to give the addresses
66  // of these stripped symbols, at least.
67  //
68  // \param[out] function_info
69  //      A vector provided by the caller is filled out.  May be empty if no
70  //      FDEs/no eh_frame
71  //      is present in this Module.
72
73  void
74  GetFunctionAddressAndSizeVector(FunctionAddressAndSizeVector &function_info);
75
76  void ForEachFDEEntries(
77      const std::function<bool(lldb::addr_t, uint32_t, dw_offset_t)> &callback);
78
79private:
80  enum { CFI_AUG_MAX_SIZE = 8, CFI_HEADER_SIZE = 8 };
81  enum CFIVersion {
82    CFI_VERSION1 = 1, // DWARF v.2
83    CFI_VERSION3 = 3, // DWARF v.3
84    CFI_VERSION4 = 4  // DWARF v.4, v.5
85  };
86
87  struct CIE {
88    dw_offset_t cie_offset;
89    uint8_t version;
90    char augmentation[CFI_AUG_MAX_SIZE]; // This is typically empty or very
91                                         // short.
92    uint8_t address_size = sizeof(uint32_t); // The size of a target address.
93    uint8_t segment_size = 0;                // The size of a segment selector.
94
95    uint32_t code_align;
96    int32_t data_align;
97    uint32_t return_addr_reg_num;
98    dw_offset_t inst_offset; // offset of CIE instructions in mCFIData
99    uint32_t inst_length;    // length of CIE instructions in mCFIData
100    uint8_t ptr_encoding;
101    uint8_t lsda_addr_encoding;   // The encoding of the LSDA address in the FDE
102                                  // augmentation data
103    lldb::addr_t personality_loc; // (file) address of the pointer to the
104                                  // personality routine
105    lldb_private::UnwindPlan::Row initial_row;
106
107    CIE(dw_offset_t offset)
108        : cie_offset(offset), version(-1), code_align(0), data_align(0),
109          return_addr_reg_num(LLDB_INVALID_REGNUM), inst_offset(0),
110          inst_length(0), ptr_encoding(0),
111          lsda_addr_encoding(llvm::dwarf::DW_EH_PE_omit),
112          personality_loc(LLDB_INVALID_ADDRESS) {}
113  };
114
115  typedef std::shared_ptr<CIE> CIESP;
116
117  typedef std::map<dw_offset_t, CIESP> cie_map_t;
118
119  // Start address (file address), size, offset of FDE location used for
120  // finding an FDE for a given File address; the start address field is an
121  // offset into an individual Module.
122  typedef RangeDataVector<lldb::addr_t, uint32_t, dw_offset_t> FDEEntryMap;
123
124  bool IsEHFrame() const;
125
126  std::optional<FDEEntryMap::Entry>
127  GetFirstFDEEntryInRange(const AddressRange &range);
128
129  void GetFDEIndex();
130
131  bool FDEToUnwindPlan(dw_offset_t offset, Address startaddr,
132                       UnwindPlan &unwind_plan);
133
134  const CIE *GetCIE(dw_offset_t cie_offset);
135
136  void GetCFIData();
137
138  // Applies the specified DWARF opcode to the given row. This function handle
139  // the commands operates only on a single row (these are the ones what can
140  // appear both in
141  // CIE and in FDE).
142  // Returns true if the opcode is handled and false otherwise.
143  bool HandleCommonDwarfOpcode(uint8_t primary_opcode, uint8_t extended_opcode,
144                               int32_t data_align, lldb::offset_t &offset,
145                               UnwindPlan::Row &row);
146
147  ObjectFile &m_objfile;
148  lldb::SectionSP m_section_sp;
149  Flags m_flags = 0;
150  cie_map_t m_cie_map;
151
152  DataExtractor m_cfi_data;
153  bool m_cfi_data_initialized = false; // only copy the section into the DE once
154
155  FDEEntryMap m_fde_index;
156  bool m_fde_index_initialized = false; // only scan the section for FDEs once
157  std::mutex m_fde_index_mutex; // and isolate the thread that does it
158
159  Type m_type;
160
161  CIESP
162  ParseCIE(const dw_offset_t cie_offset);
163
164  lldb::RegisterKind GetRegisterKind() const {
165    return m_type == EH ? lldb::eRegisterKindEHFrame : lldb::eRegisterKindDWARF;
166  }
167};
168
169} // namespace lldb_private
170
171#endif // LLDB_SYMBOL_DWARFCALLFRAMEINFO_H
172