LLDB  mainline
DYLDRendezvous.h
Go to the documentation of this file.
1 //===-- DYLDRendezvous.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_SOURCE_PLUGINS_DYNAMICLOADER_POSIX_DYLD_DYLDRENDEZVOUS_H
10 #define LLDB_SOURCE_PLUGINS_DYNAMICLOADER_POSIX_DYLD_DYLDRENDEZVOUS_H
11 
12 #include <list>
13 #include <string>
14 
15 #include "lldb/Utility/FileSpec.h"
16 #include "lldb/lldb-defines.h"
17 #include "lldb/lldb-types.h"
18 
20 
22 
23 namespace lldb_private {
24 class Process;
25 }
26 
27 /// \class DYLDRendezvous
28 /// Interface to the runtime linker.
29 ///
30 /// A structure is present in a processes memory space which is updated by the
31 /// runtime liker each time a module is loaded or unloaded. This class
32 /// provides an interface to this structure and maintains a consistent
33 /// snapshot of the currently loaded modules.
35 
36  // This structure is used to hold the contents of the debug rendezvous
37  // information (struct r_debug) as found in the inferiors memory. Note that
38  // the layout of this struct is not binary compatible, it is simply large
39  // enough to hold the information on both 32 and 64 bit platforms.
40  struct Rendezvous {
41  uint64_t version;
44  uint64_t state;
46 
47  Rendezvous() : version(0), map_addr(0), brk(0), state(0), ldbase(0) {}
48  };
49 
50 public:
51  // Various metadata supplied by the inferior's threading library to describe
52  // the per-thread state.
53  struct ThreadInfo {
54  bool valid; // whether we read valid metadata
55  uint32_t dtv_offset; // offset of DTV pointer within pthread
56  uint32_t dtv_slot_size; // size of one DTV slot
57  uint32_t modid_offset; // offset of module ID within link_map
58  uint32_t tls_offset; // offset of TLS pointer within DTV slot
59  };
60 
62 
63  /// Update the cached executable path.
64  void UpdateExecutablePath();
65 
66  /// Update the internal snapshot of runtime linker rendezvous and recompute
67  /// the currently loaded modules.
68  ///
69  /// This method should be called once one start up, then once each time the
70  /// runtime linker enters the function given by GetBreakAddress().
71  ///
72  /// \returns true on success and false on failure.
73  ///
74  /// \see GetBreakAddress().
75  bool Resolve();
76 
77  /// \returns true if this rendezvous has been located in the inferiors
78  /// address space and false otherwise.
79  bool IsValid();
80 
81  /// \returns the address of the rendezvous structure in the inferiors
82  /// address space.
84 
85  /// \returns the version of the rendezvous protocol being used.
86  uint64_t GetVersion() const { return m_current.version; }
87 
88  /// \returns address in the inferiors address space containing the linked
89  /// list of shared object descriptors.
91 
92  /// A breakpoint should be set at this address and Resolve called on each
93  /// hit.
94  ///
95  /// \returns the address of a function called by the runtime linker each
96  /// time a module is loaded/unloaded, or about to be loaded/unloaded.
97  ///
98  /// \see Resolve()
100 
101  /// Returns the current state of the rendezvous structure.
102  uint64_t GetState() const { return m_current.state; }
103 
104  /// \returns the base address of the runtime linker in the inferiors address
105  /// space.
107 
108  /// \returns the thread layout metadata from the inferiors thread library.
109  const ThreadInfo &GetThreadInfo();
110 
111  /// \returns true if modules have been loaded into the inferior since the
112  /// last call to Resolve().
113  bool ModulesDidLoad() const { return !m_added_soentries.empty(); }
114 
115  /// \returns true if modules have been unloaded from the inferior since the
116  /// last call to Resolve().
117  bool ModulesDidUnload() const { return !m_removed_soentries.empty(); }
118 
119  void DumpToLog(lldb_private::Log *log) const;
120 
121  /// Constants describing the state of the rendezvous.
122  ///
123  /// \see GetState().
125 
126  /// Structure representing the shared objects currently loaded into the
127  /// inferior process.
128  ///
129  /// This object is a rough analogue to the struct link_map object which
130  /// actually lives in the inferiors memory.
131  struct SOEntry {
132  lldb::addr_t link_addr; ///< Address of this link_map.
133  lldb::addr_t base_addr; ///< Base address of the loaded object.
134  lldb::addr_t path_addr; ///< String naming the shared object.
135  lldb::addr_t dyn_addr; ///< Dynamic section of shared object.
136  lldb::addr_t next; ///< Address of next so_entry.
137  lldb::addr_t prev; ///< Address of previous so_entry.
138  lldb_private::FileSpec file_spec; ///< File spec of shared object.
139 
140  SOEntry() { clear(); }
141 
142  bool operator==(const SOEntry &entry) {
143  return file_spec == entry.file_spec;
144  }
145 
146  void clear() {
147  link_addr = 0;
148  base_addr = 0;
149  path_addr = 0;
150  dyn_addr = 0;
151  next = 0;
152  prev = 0;
153  file_spec.Clear();
154  }
155  };
156 
157 protected:
158  typedef std::list<SOEntry> SOEntryList;
159 
160 public:
161  typedef SOEntryList::const_iterator iterator;
162 
163  /// Iterators over all currently loaded modules.
164  iterator begin() const { return m_soentries.begin(); }
165  iterator end() const { return m_soentries.end(); }
166 
167  /// Iterators over all modules loaded into the inferior since the last call
168  /// to Resolve().
169  iterator loaded_begin() const { return m_added_soentries.begin(); }
170  iterator loaded_end() const { return m_added_soentries.end(); }
171 
172  /// Iterators over all modules unloaded from the inferior since the last
173  /// call to Resolve().
174  iterator unloaded_begin() const { return m_removed_soentries.begin(); }
175  iterator unloaded_end() const { return m_removed_soentries.end(); }
176 
177 protected:
179 
180  // Cached copy of executable file spec
182 
183  /// Location of the r_debug structure in the inferiors address space.
185 
186  /// Current and previous snapshots of the rendezvous structure.
189 
190  /// List of currently loaded SO modules
192 
193  /// List of SOEntry objects corresponding to the current link map state.
195 
196  /// List of SOEntry's added to the link map since the last call to
197  /// Resolve().
199 
200  /// List of SOEntry's removed from the link map since the last call to
201  /// Resolve().
203 
204  /// Threading metadata read from the inferior.
206 
207  /// Reads an unsigned integer of \p size bytes from the inferior's address
208  /// space starting at \p addr.
209  ///
210  /// \returns addr + size if the read was successful and false otherwise.
211  lldb::addr_t ReadWord(lldb::addr_t addr, uint64_t *dst, size_t size);
212 
213  /// Reads an address from the inferior's address space starting at \p addr.
214  ///
215  /// \returns addr + target address size if the read was successful and
216  /// 0 otherwise.
218 
219  /// Reads a null-terminated C string from the memory location starting at @p
220  /// addr.
222 
223  /// Reads an SOEntry starting at \p addr.
224  bool ReadSOEntryFromMemory(lldb::addr_t addr, SOEntry &entry);
225 
226  /// Updates the current set of SOEntries, the set of added entries, and the
227  /// set of removed entries.
228  bool UpdateSOEntries();
229 
230  /// Same as UpdateSOEntries but it gets the list of loaded modules from the
231  /// remote debug server (faster when supported).
233 
235  LoadedModuleInfoList::LoadedModuleInfo const &modInfo, SOEntry &entry);
236 
237  bool SaveSOEntriesFromRemote(const LoadedModuleInfoList &module_list);
238 
239  bool AddSOEntriesFromRemote(const LoadedModuleInfoList &module_list);
240 
241  bool RemoveSOEntriesFromRemote(const LoadedModuleInfoList &module_list);
242 
243  bool AddSOEntries();
244 
245  bool RemoveSOEntries();
246 
247  void UpdateBaseAddrIfNecessary(SOEntry &entry, std::string const &file_path);
248 
249  bool SOEntryIsMainExecutable(const SOEntry &entry);
250 
251  /// Reads the current list of shared objects according to the link map
252  /// supplied by the runtime linker.
253  bool TakeSnapshot(SOEntryList &entry_list);
254 
256 
257  bool FindMetadata(const char *name, PThreadField field, uint32_t &value);
258 
264  };
265 
266  /// Returns the current action to be taken given the current and previous
267  /// state
268  RendezvousAction GetAction() const;
269 };
270 
271 #endif
DYLDRendezvous::eAdd
@ eAdd
Definition: DYLDRendezvous.h:124
DYLDRendezvous::ModulesDidLoad
bool ModulesDidLoad() const
Definition: DYLDRendezvous.h:113
DYLDRendezvous::m_added_soentries
SOEntryList m_added_soentries
List of SOEntry's added to the link map since the last call to Resolve().
Definition: DYLDRendezvous.h:198
DYLDRendezvous::ThreadInfo
Definition: DYLDRendezvous.h:53
DYLDRendezvous::SaveSOEntriesFromRemote
bool SaveSOEntriesFromRemote(const LoadedModuleInfoList &module_list)
Definition: DYLDRendezvous.cpp:291
DYLDRendezvous::eNoAction
@ eNoAction
Definition: DYLDRendezvous.h:260
DYLDRendezvous::loaded_begin
iterator loaded_begin() const
Iterators over all modules loaded into the inferior since the last call to Resolve().
Definition: DYLDRendezvous.h:169
DYLDRendezvous::UpdateExecutablePath
void UpdateExecutablePath()
Update the cached executable path.
Definition: DYLDRendezvous.cpp:101
DYLDRendezvous::GetLDBase
lldb::addr_t GetLDBase() const
Definition: DYLDRendezvous.h:106
DYLDRendezvous::end
iterator end() const
Definition: DYLDRendezvous.h:165
DYLDRendezvous::m_process
lldb_private::Process * m_process
Definition: DYLDRendezvous.h:178
DYLDRendezvous::DYLDRendezvous
DYLDRendezvous(lldb_private::Process *process)
Definition: DYLDRendezvous.cpp:93
lldb-defines.h
DYLDRendezvous::SOEntryIsMainExecutable
bool SOEntryIsMainExecutable(const SOEntry &entry)
Definition: DYLDRendezvous.cpp:415
DYLDRendezvous::ThreadInfo::modid_offset
uint32_t modid_offset
Definition: DYLDRendezvous.h:57
DYLDRendezvous::RemoveSOEntries
bool RemoveSOEntries()
Definition: DYLDRendezvous.cpp:396
DYLDRendezvous::eSize
@ eSize
Definition: DYLDRendezvous.h:255
DYLDRendezvous::iterator
SOEntryList::const_iterator iterator
Definition: DYLDRendezvous.h:161
lldb_private::Process
Definition: Process.h:342
DYLDRendezvous::eConsistent
@ eConsistent
Definition: DYLDRendezvous.h:124
DYLDRendezvous::begin
iterator begin() const
Iterators over all currently loaded modules.
Definition: DYLDRendezvous.h:164
DYLDRendezvous::ThreadInfo::dtv_slot_size
uint32_t dtv_slot_size
Definition: DYLDRendezvous.h:56
DYLDRendezvous::PThreadField
PThreadField
Definition: DYLDRendezvous.h:255
DYLDRendezvous::SOEntry::prev
lldb::addr_t prev
Address of previous so_entry.
Definition: DYLDRendezvous.h:137
DYLDRendezvous::AddSOEntriesFromRemote
bool AddSOEntriesFromRemote(const LoadedModuleInfoList &module_list)
Definition: DYLDRendezvous.cpp:307
DYLDRendezvous::m_exe_file_spec
lldb_private::FileSpec m_exe_file_spec
Definition: DYLDRendezvous.h:181
DYLDRendezvous::ThreadInfo::dtv_offset
uint32_t dtv_offset
Definition: DYLDRendezvous.h:55
DYLDRendezvous::SOEntry::next
lldb::addr_t next
Address of next so_entry.
Definition: DYLDRendezvous.h:136
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::LoadedModuleInfoList
Definition: LoadedModuleInfoList.h:21
DYLDRendezvous::ReadPointer
lldb::addr_t ReadPointer(lldb::addr_t addr, lldb::addr_t *dst)
Reads an address from the inferior's address space starting at addr.
Definition: DYLDRendezvous.cpp:466
DYLDRendezvous::DumpToLog
void DumpToLog(lldb_private::Log *log) const
Definition: DYLDRendezvous.cpp:604
DYLDRendezvous::ReadStringFromMemory
std::string ReadStringFromMemory(lldb::addr_t addr)
Reads a null-terminated C string from the memory location starting at addr.
Definition: DYLDRendezvous.cpp:476
DYLDRendezvous::SOEntry::base_addr
lldb::addr_t base_addr
Base address of the loaded object.
Definition: DYLDRendezvous.h:133
DYLDRendezvous::m_previous
Rendezvous m_previous
Definition: DYLDRendezvous.h:188
DYLDRendezvous::eNElem
@ eNElem
Definition: DYLDRendezvous.h:255
DYLDRendezvous::eOffset
@ eOffset
Definition: DYLDRendezvous.h:255
DYLDRendezvous::eAddModules
@ eAddModules
Definition: DYLDRendezvous.h:262
DYLDRendezvous::ModulesDidUnload
bool ModulesDidUnload() const
Definition: DYLDRendezvous.h:117
DYLDRendezvous::FindMetadata
bool FindMetadata(const char *name, PThreadField field, uint32_t &value)
Definition: DYLDRendezvous.cpp:557
lldb_private::FileSpec
Definition: FileSpec.h:56
DYLDRendezvous::Rendezvous
Definition: DYLDRendezvous.h:40
DYLDRendezvous::GetThreadInfo
const ThreadInfo & GetThreadInfo()
Definition: DYLDRendezvous.cpp:584
DYLDRendezvous::UpdateBaseAddrIfNecessary
void UpdateBaseAddrIfNecessary(SOEntry &entry, std::string const &file_path)
Definition: DYLDRendezvous.cpp:501
DYLDRendezvous::ThreadInfo::valid
bool valid
Definition: DYLDRendezvous.h:54
DYLDRendezvous::GetBreakAddress
lldb::addr_t GetBreakAddress() const
A breakpoint should be set at this address and Resolve called on each hit.
Definition: DYLDRendezvous.h:99
DYLDRendezvous::Rendezvous::state
uint64_t state
Definition: DYLDRendezvous.h:44
DYLDRendezvous::unloaded_end
iterator unloaded_end() const
Definition: DYLDRendezvous.h:175
DYLDRendezvous::Rendezvous::version
uint64_t version
Definition: DYLDRendezvous.h:41
DYLDRendezvous::Rendezvous::brk
lldb::addr_t brk
Definition: DYLDRendezvous.h:43
DYLDRendezvous::eTakeSnapshot
@ eTakeSnapshot
Definition: DYLDRendezvous.h:261
DYLDRendezvous::RendezvousAction
RendezvousAction
Definition: DYLDRendezvous.h:259
DYLDRendezvous::TakeSnapshot
bool TakeSnapshot(SOEntryList &entry_list)
Reads the current list of shared objects according to the link map supplied by the runtime linker.
Definition: DYLDRendezvous.cpp:433
DYLDRendezvous::Rendezvous::ldbase
lldb::addr_t ldbase
Definition: DYLDRendezvous.h:45
DYLDRendezvous::Rendezvous::map_addr
lldb::addr_t map_addr
Definition: DYLDRendezvous.h:42
DYLDRendezvous::RemoveSOEntriesFromRemote
bool RemoveSOEntriesFromRemote(const LoadedModuleInfoList &module_list)
Definition: DYLDRendezvous.cpp:336
DYLDRendezvous::SOEntry::operator==
bool operator==(const SOEntry &entry)
Definition: DYLDRendezvous.h:142
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:38
DYLDRendezvous::IsValid
bool IsValid()
Definition: DYLDRendezvous.cpp:173
DYLDRendezvous::unloaded_begin
iterator unloaded_begin() const
Iterators over all modules unloaded from the inferior since the last call to Resolve().
Definition: DYLDRendezvous.h:174
DYLDRendezvous::RendezvousState
RendezvousState
Constants describing the state of the rendezvous.
Definition: DYLDRendezvous.h:124
LoadedModuleInfoList.h
DYLDRendezvous::FillSOEntryFromModuleInfo
bool FillSOEntryFromModuleInfo(LoadedModuleInfoList::LoadedModuleInfo const &modInfo, SOEntry &entry)
Definition: DYLDRendezvous.cpp:264
lldb-types.h
lldb_private::FileSpec::Clear
void Clear()
Clears the object state.
Definition: FileSpec.cpp:261
DYLDRendezvous::m_thread_info
ThreadInfo m_thread_info
Threading metadata read from the inferior.
Definition: DYLDRendezvous.h:205
DYLDRendezvous::UpdateSOEntriesFromRemote
bool UpdateSOEntriesFromRemote()
Same as UpdateSOEntries but it gets the list of loaded modules from the remote debug server (faster w...
Definition: DYLDRendezvous.cpp:211
uint32_t
DYLDRendezvous::ReadSOEntryFromMemory
bool ReadSOEntryFromMemory(lldb::addr_t addr, SOEntry &entry)
Reads an SOEntry starting at addr.
Definition: DYLDRendezvous.cpp:515
DYLDRendezvous::GetLinkMapAddress
lldb::addr_t GetLinkMapAddress() const
Definition: DYLDRendezvous.h:90
DYLDRendezvous
Definition: DYLDRendezvous.h:34
DYLDRendezvous::GetRendezvousAddress
lldb::addr_t GetRendezvousAddress() const
Definition: DYLDRendezvous.h:83
DYLDRendezvous::loaded_end
iterator loaded_end() const
Definition: DYLDRendezvous.h:170
DYLDRendezvous::GetVersion
uint64_t GetVersion() const
Definition: DYLDRendezvous.h:86
DYLDRendezvous::SOEntry::SOEntry
SOEntry()
Definition: DYLDRendezvous.h:140
DYLDRendezvous::SOEntryList
std::list< SOEntry > SOEntryList
Definition: DYLDRendezvous.h:158
DYLDRendezvous::ThreadInfo::tls_offset
uint32_t tls_offset
Definition: DYLDRendezvous.h:58
DYLDRendezvous::m_loaded_modules
LoadedModuleInfoList m_loaded_modules
List of currently loaded SO modules.
Definition: DYLDRendezvous.h:191
DYLDRendezvous::Rendezvous::Rendezvous
Rendezvous()
Definition: DYLDRendezvous.h:47
DYLDRendezvous::m_current
Rendezvous m_current
Current and previous snapshots of the rendezvous structure.
Definition: DYLDRendezvous.h:187
DYLDRendezvous::AddSOEntries
bool AddSOEntries()
Definition: DYLDRendezvous.cpp:369
DYLDRendezvous::GetState
uint64_t GetState() const
Returns the current state of the rendezvous structure.
Definition: DYLDRendezvous.h:102
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
DYLDRendezvous::Resolve
bool Resolve()
Update the internal snapshot of runtime linker rendezvous and recompute the currently loaded modules.
Definition: DYLDRendezvous.cpp:118
DYLDRendezvous::SOEntry::path_addr
lldb::addr_t path_addr
String naming the shared object.
Definition: DYLDRendezvous.h:134
DYLDRendezvous::SOEntry::file_spec
lldb_private::FileSpec file_spec
File spec of shared object.
Definition: DYLDRendezvous.h:138
DYLDRendezvous::SOEntry::link_addr
lldb::addr_t link_addr
Address of this link_map.
Definition: DYLDRendezvous.h:132
DYLDRendezvous::SOEntry::dyn_addr
lldb::addr_t dyn_addr
Dynamic section of shared object.
Definition: DYLDRendezvous.h:135
FileSpec.h
DYLDRendezvous::m_removed_soentries
SOEntryList m_removed_soentries
List of SOEntry's removed from the link map since the last call to Resolve().
Definition: DYLDRendezvous.h:202
DYLDRendezvous::UpdateSOEntries
bool UpdateSOEntries()
Updates the current set of SOEntries, the set of added entries, and the set of removed entries.
Definition: DYLDRendezvous.cpp:247
DYLDRendezvous::eRemoveModules
@ eRemoveModules
Definition: DYLDRendezvous.h:263
DYLDRendezvous::eDelete
@ eDelete
Definition: DYLDRendezvous.h:124
DYLDRendezvous::ReadWord
lldb::addr_t ReadWord(lldb::addr_t addr, uint64_t *dst, size_t size)
Reads an unsigned integer of size bytes from the inferior's address space starting at addr.
Definition: DYLDRendezvous.cpp:456
lldb_private::Log
Definition: Log.h:49
DYLDRendezvous::m_rendezvous_addr
lldb::addr_t m_rendezvous_addr
Location of the r_debug structure in the inferiors address space.
Definition: DYLDRendezvous.h:184
DYLDRendezvous::m_soentries
SOEntryList m_soentries
List of SOEntry objects corresponding to the current link map state.
Definition: DYLDRendezvous.h:194
DYLDRendezvous::SOEntry::clear
void clear()
Definition: DYLDRendezvous.h:146
DYLDRendezvous::SOEntry
Structure representing the shared objects currently loaded into the inferior process.
Definition: DYLDRendezvous.h:131
DYLDRendezvous::GetAction
RendezvousAction GetAction() const
Returns the current action to be taken given the current and previous state.
Definition: DYLDRendezvous.cpp:177