LLDB mainline
DynamicLoaderDarwinKernel.h
Go to the documentation of this file.
1//===-- DynamicLoaderDarwinKernel.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_DARWIN_KERNEL_DYNAMICLOADERDARWINKERNEL_H
10#define LLDB_SOURCE_PLUGINS_DYNAMICLOADER_DARWIN_KERNEL_DYNAMICLOADERDARWINKERNEL_H
11
12#include <mutex>
13#include <string>
14#include <vector>
15
16
17#include "lldb/Host/SafeMachO.h"
18
20#include "lldb/Target/Process.h"
22#include "lldb/Utility/UUID.h"
23
25public:
27 lldb::addr_t kernel_addr);
28
30
31 // Static Functions
32 static void Initialize();
33
34 static void Terminate();
35
36 static llvm::StringRef GetPluginNameStatic() { return "darwin-kernel"; }
37
38 static llvm::StringRef GetPluginDescriptionStatic();
39
41 CreateInstance(lldb_private::Process *process, bool force);
42
43 static void DebuggerInitialize(lldb_private::Debugger &debugger);
44
46
47 /// Called after attaching a process.
48 ///
49 /// Allow DynamicLoader plug-ins to execute some code after
50 /// attaching to a process.
51 void DidAttach() override;
52
53 void DidLaunch() override;
54
56 bool stop_others) override;
57
59
60 // PluginInterface protocol
61 llvm::StringRef GetPluginName() override { return GetPluginNameStatic(); }
62
63protected:
65
67 lldb::StateType state);
68
69 void UpdateIfNeeded();
70
72
73 void Clear(bool clear_process);
74
75 void PutToLog(lldb_private::Log *log) const;
76
77 static bool
78 BreakpointHitCallback(void *baton,
80 lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
81
83 lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
85
86 static lldb::ByteOrder GetByteOrderFromMagic(uint32_t magic);
87
88 enum {
90 // Versions less than 2 didn't have an entry size,
91 // they had a 64 bit name, 16 byte UUID, 8 byte addr,
92 // 8 byte size, 8 byte version, 4 byte load tag, and
93 // 4 byte flags
94 KERNEL_MODULE_ENTRY_SIZE_VERSION_1 = 64u + 16u + 8u + 8u + 8u + 4u + 4u
95 };
96
97 // class KextImageInfo represents a single kext or kernel binary image.
98 // The class was designed to hold the information from the
99 // OSKextLoadedKextSummary
100 // structure (in libkern/libkern/OSKextLibPrivate.h from xnu). The kernel
101 // maintains
102 // a list of loded kexts in memory (the OSKextLoadedKextSummaryHeader
103 // structure,
104 // which points to an array of OSKextLoadedKextSummary's).
105 //
106 // A KextImageInfos may have -
107 //
108 // 1. The load address, name, UUID, and size of a kext/kernel binary in memory
109 // (read straight out of the kernel's list-of-kexts loaded)
110 // 2. A ModuleSP based on a MemoryModule read out of the kernel's memory
111 // (very unlikely to have any symbolic information)
112 // 3. A ModuleSP for an on-disk copy of the kext binary, possibly with debug
113 // info
114 // or a dSYM
115 //
116 // For performance reasons, the developer may prefer that lldb not load the
117 // kexts out
118 // of memory at the start of a kernel session. But we should build up /
119 // maintain a
120 // list of kexts that the kernel has told us about so we can relocate a kext
121 // module
122 // later if the user explicitly adds it to the target.
123
125 public:
127
128 void Clear() {
130 m_size = 0;
131 m_name.clear();
132 m_uuid.Clear();
133 m_module_sp.reset();
134 m_memory_module_sp.reset();
136 }
137
139
141
143
144 void SetLoadAddress(
145 lldb::addr_t load_addr); // Address of the Mach-O header for this binary
146
148 GetLoadAddress() const; // Address of the Mach-O header for this binary
149
151
152 void SetUUID(const lldb_private::UUID &uuid);
153
154 void SetName(const char *);
155
156 std::string GetName() const;
157
158 void SetModule(lldb::ModuleSP module);
159
161
162 // try to fill in m_memory_module_sp from memory based on the m_load_address
164
165 bool IsKernel()
166 const; // true if this is the mach_kernel; false if this is a kext
167
168 void SetIsKernel(bool is_kernel);
169
170 uint64_t GetSize() const;
171
172 void SetSize(uint64_t size);
173
174 uint32_t
175 GetProcessStopId() const; // the stop-id when this binary was first noticed
176
177 void SetProcessStopId(uint32_t stop_id);
178
179 bool operator==(const KextImageInfo &rhs) const;
180
181 uint32_t GetAddressByteSize(); // as determined by Mach-O header
182
183 lldb::ByteOrder GetByteOrder(); // as determined by Mach-O header
184
186 GetArchitecture() const; // as determined by Mach-O header
187
188 void PutToLog(lldb_private::Log *log) const;
189
190 typedef std::vector<KextImageInfo> collection;
191 typedef collection::iterator iterator;
192 typedef collection::const_iterator const_iterator;
193
194 private:
195 std::string m_name;
199 UINT32_MAX; // the stop-id when this module was added
200 // to the Target
202 m_uuid; // UUID for this dylib if it has one, else all zeros
204 uint64_t m_size = 0;
206 false; // true if this is the kernel, false if this is a kext
207 };
208
210 uint32_t version = 0;
211 uint32_t entry_size = 0;
212 uint32_t entry_count = 0;
214
216
217 uint32_t GetSize() {
218 switch (version) {
219 case 0:
220 return 0; // Can't know the size without a valid version
221 case 1:
222 return 8; // Version 1 only had a version + entry_count
223 default:
224 break;
225 }
226 // Version 2 and above has version, entry_size, entry_count, and reserved
227 return 16;
228 }
229
230 void Clear() {
231 version = 0;
232 entry_size = 0;
233 entry_count = 0;
235 }
236
237 bool IsValid() const { return version >= 1 && version <= 2; }
238 };
239
241
243
245
247
249
250 bool ParseKextSummaries(const lldb_private::Address &kext_summary_addr,
251 uint32_t count);
252
253 void
255 uint32_t infos_count,
256 bool update_executable);
257
258 uint32_t ReadKextSummaries(const lldb_private::Address &kext_summary_addr,
259 uint32_t image_infos_count,
260 KextImageInfo::collection &image_infos);
261
262 static lldb::addr_t
264
265 static lldb::addr_t
267
269
270 static lldb::addr_t
272
273 static bool
274 ReadMachHeader(lldb::addr_t addr, lldb_private::Process *process, llvm::MachO::mach_header &mh,
275 bool *read_error = nullptr);
276
277 static lldb_private::UUID
279 lldb_private::Process *process,
280 bool *read_error = nullptr);
281
283 KextImageInfo m_kernel; // Info about the current kernel image being used
284
289 mutable std::recursive_mutex m_mutex;
291
292private:
296};
297
298#endif // LLDB_SOURCE_PLUGINS_DYNAMICLOADER_DARWIN_KERNEL_DYNAMICLOADERDARWINKERNEL_H
static bool is_kernel(Module *module)
bool operator==(const KextImageInfo &rhs) const
bool ReadMemoryModule(lldb_private::Process *process)
void SetUUID(const lldb_private::UUID &uuid)
bool LoadImageAtFileAddress(lldb_private::Process *process)
bool LoadImageUsingMemoryModule(lldb_private::Process *process)
const DynamicLoaderDarwinKernel & operator=(const DynamicLoaderDarwinKernel &)=delete
void DidLaunch() override
Called after attaching a process.
lldb_private::Address m_kext_summary_header_ptr_addr
void PrivateProcessStateChanged(lldb_private::Process *process, lldb::StateType state)
lldb::ThreadPlanSP GetStepThroughTrampolinePlan(lldb_private::Thread &thread, bool stop_others) override
Provides a plan to step through the dynamic loader trampoline for the current state of thread.
static lldb_private::DynamicLoader * CreateInstance(lldb_private::Process *process, bool force)
lldb_private::Address m_kext_summary_header_addr
static void DebuggerInitialize(lldb_private::Debugger &debugger)
static bool ReadMachHeader(lldb::addr_t addr, lldb_private::Process *process, llvm::MachO::mach_header &mh, bool *read_error=nullptr)
void PutToLog(lldb_private::Log *log) const
static lldb::addr_t SearchForKernelViaExhaustiveSearch(lldb_private::Process *process)
void UpdateImageInfosHeaderAndLoadCommands(KextImageInfo::collection &image_infos, uint32_t infos_count, bool update_executable)
static llvm::StringRef GetPluginDescriptionStatic()
lldb_private::Status CanLoadImage() override
Ask if it is ok to try and load or unload an shared library (image).
void DidAttach() override
Called after attaching a process.
static lldb::addr_t SearchForKernelAtSameLoadAddr(lldb_private::Process *process)
static llvm::StringRef GetPluginNameStatic()
llvm::StringRef GetPluginName() override
OSKextLoadedKextSummaryHeader m_kext_summary_header
void PrivateInitialize(lldb_private::Process *process)
static lldb_private::UUID CheckForKernelImageAtAddress(lldb::addr_t addr, lldb_private::Process *process, bool *read_error=nullptr)
static bool BreakpointHitCallback(void *baton, lldb_private::StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id)
static lldb::ByteOrder GetByteOrderFromMagic(uint32_t magic)
bool BreakpointHit(lldb_private::StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id)
static lldb::addr_t SearchForKernelNearPC(lldb_private::Process *process)
DynamicLoaderDarwinKernel(const DynamicLoaderDarwinKernel &)=delete
uint32_t ReadKextSummaries(const lldb_private::Address &kext_summary_addr, uint32_t image_infos_count, KextImageInfo::collection &image_infos)
static lldb::addr_t SearchForDarwinKernel(lldb_private::Process *process)
KextImageInfo::collection m_known_kexts
static lldb::addr_t SearchForKernelWithDebugHints(lldb_private::Process *process)
bool ParseKextSummaries(const lldb_private::Address &kext_summary_addr, uint32_t count)
A section + offset based address class.
Definition: Address.h:62
An architecture specification class.
Definition: ArchSpec.h:31
A class to manage flag bits.
Definition: Debugger.h:79
A plug-in interface definition class for dynamic loaders.
Definition: DynamicLoader.h:52
A plug-in interface definition class for debugging a process.
Definition: Process.h:340
An error handling class.
Definition: Status.h:44
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
void Clear()
Definition: UUID.h:62
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:82
#define UINT32_MAX
Definition: lldb-defines.h:19
std::shared_ptr< lldb_private::ThreadPlan > ThreadPlanSP
Definition: lldb-forward.h:441
StateType
Process and Thread States.
ByteOrder
Byte ordering definitions.
uint64_t user_id_t
Definition: lldb-types.h:80
uint64_t addr_t
Definition: lldb-types.h:79
std::shared_ptr< lldb_private::Module > ModuleSP
Definition: lldb-forward.h:365