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 19 #include "lldb/Target/DynamicLoader.h" 20 #include "lldb/Target/Process.h" 21 #include "lldb/Utility/FileSpec.h" 22 #include "lldb/Utility/UUID.h" 23 24 class DynamicLoaderDarwinKernel : public lldb_private::DynamicLoader { 25 public: 26 DynamicLoaderDarwinKernel(lldb_private::Process *process, 27 lldb::addr_t kernel_addr); 28 29 ~DynamicLoaderDarwinKernel() override; 30 31 // Static Functions 32 static void Initialize(); 33 34 static void Terminate(); 35 36 static lldb_private::ConstString GetPluginNameStatic(); 37 38 static const char *GetPluginDescriptionStatic(); 39 40 static lldb_private::DynamicLoader * 41 CreateInstance(lldb_private::Process *process, bool force); 42 43 static void DebuggerInitialize(lldb_private::Debugger &debugger); 44 45 static lldb::addr_t SearchForDarwinKernel(lldb_private::Process *process); 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 55 lldb::ThreadPlanSP GetStepThroughTrampolinePlan(lldb_private::Thread &thread, 56 bool stop_others) override; 57 58 lldb_private::Status CanLoadImage() override; 59 60 // PluginInterface protocol 61 lldb_private::ConstString GetPluginName() override; 62 63 protected: 64 void PrivateInitialize(lldb_private::Process *process); 65 66 void PrivateProcessStateChanged(lldb_private::Process *process, 67 lldb::StateType state); 68 69 void UpdateIfNeeded(); 70 71 void LoadKernelModuleIfNeeded(); 72 73 void Clear(bool clear_process); 74 75 void PutToLog(lldb_private::Log *log) const; 76 77 static bool 78 BreakpointHitCallback(void *baton, 79 lldb_private::StoppointCallbackContext *context, 80 lldb::user_id_t break_id, lldb::user_id_t break_loc_id); 81 82 bool BreakpointHit(lldb_private::StoppointCallbackContext *context, 83 lldb::user_id_t break_id, lldb::user_id_t break_loc_id); GetAddrByteSize()84 uint32_t GetAddrByteSize() { return m_kernel.GetAddressByteSize(); } 85 86 static lldb::ByteOrder GetByteOrderFromMagic(uint32_t magic); 87 88 enum { 89 KERNEL_MODULE_MAX_NAME = 64u, 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 124 class KextImageInfo { 125 public: KextImageInfo()126 KextImageInfo() : m_name(), m_module_sp(), m_memory_module_sp(), m_uuid() {} 127 Clear()128 void Clear() { 129 m_load_address = LLDB_INVALID_ADDRESS; 130 m_size = 0; 131 m_name.clear(); 132 m_uuid.Clear(); 133 m_module_sp.reset(); 134 m_memory_module_sp.reset(); 135 m_load_process_stop_id = UINT32_MAX; 136 } 137 138 bool LoadImageAtFileAddress(lldb_private::Process *process); 139 140 bool LoadImageUsingMemoryModule(lldb_private::Process *process); 141 IsLoaded()142 bool IsLoaded() { return m_load_process_stop_id != UINT32_MAX; } 143 144 void SetLoadAddress( 145 lldb::addr_t load_addr); // Address of the Mach-O header for this binary 146 147 lldb::addr_t 148 GetLoadAddress() const; // Address of the Mach-O header for this binary 149 150 lldb_private::UUID GetUUID() const; 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 160 lldb::ModuleSP GetModule(); 161 162 // try to fill in m_memory_module_sp from memory based on the m_load_address 163 bool ReadMemoryModule(lldb_private::Process *process); 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); 180 181 uint32_t GetAddressByteSize(); // as determined by Mach-O header 182 183 lldb::ByteOrder GetByteOrder(); // as determined by Mach-O header 184 185 lldb_private::ArchSpec 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; 196 lldb::ModuleSP m_module_sp; 197 lldb::ModuleSP m_memory_module_sp; 198 uint32_t m_load_process_stop_id = 199 UINT32_MAX; // the stop-id when this module was added 200 // to the Target 201 lldb_private::UUID 202 m_uuid; // UUID for this dylib if it has one, else all zeros 203 lldb::addr_t m_load_address = LLDB_INVALID_ADDRESS; 204 uint64_t m_size = 0; 205 bool m_kernel_image = 206 false; // true if this is the kernel, false if this is a kext 207 }; 208 209 struct OSKextLoadedKextSummaryHeader { 210 uint32_t version = 0; 211 uint32_t entry_size = 0; 212 uint32_t entry_count = 0; 213 lldb::addr_t image_infos_addr = LLDB_INVALID_ADDRESS; 214 215 OSKextLoadedKextSummaryHeader() = default; 216 GetSizeOSKextLoadedKextSummaryHeader217 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 ClearOSKextLoadedKextSummaryHeader230 void Clear() { 231 version = 0; 232 entry_size = 0; 233 entry_count = 0; 234 image_infos_addr = LLDB_INVALID_ADDRESS; 235 } 236 IsValidOSKextLoadedKextSummaryHeader237 bool IsValid() const { return version >= 1 && version <= 2; } 238 }; 239 240 void RegisterNotificationCallbacks(); 241 242 void UnregisterNotificationCallbacks(); 243 244 void SetNotificationBreakpointIfNeeded(); 245 246 bool ReadAllKextSummaries(); 247 248 bool ReadKextSummaryHeader(); 249 250 bool ParseKextSummaries(const lldb_private::Address &kext_summary_addr, 251 uint32_t count); 252 253 void 254 UpdateImageInfosHeaderAndLoadCommands(KextImageInfo::collection &image_infos, 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 263 SearchForKernelAtSameLoadAddr(lldb_private::Process *process); 264 265 static lldb::addr_t 266 SearchForKernelWithDebugHints(lldb_private::Process *process); 267 268 static lldb::addr_t SearchForKernelNearPC(lldb_private::Process *process); 269 270 static lldb::addr_t 271 SearchForKernelViaExhaustiveSearch(lldb_private::Process *process); 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 278 CheckForKernelImageAtAddress(lldb::addr_t addr, 279 lldb_private::Process *process, 280 bool *read_error = nullptr); 281 282 lldb::addr_t m_kernel_load_address; 283 KextImageInfo m_kernel; // Info about the current kernel image being used 284 285 lldb_private::Address m_kext_summary_header_ptr_addr; 286 lldb_private::Address m_kext_summary_header_addr; 287 OSKextLoadedKextSummaryHeader m_kext_summary_header; 288 KextImageInfo::collection m_known_kexts; 289 mutable std::recursive_mutex m_mutex; 290 lldb::user_id_t m_break_id; 291 292 private: 293 DynamicLoaderDarwinKernel(const DynamicLoaderDarwinKernel &) = delete; 294 const DynamicLoaderDarwinKernel & 295 operator=(const DynamicLoaderDarwinKernel &) = delete; 296 }; 297 298 #endif // LLDB_SOURCE_PLUGINS_DYNAMICLOADER_DARWIN_KERNEL_DYNAMICLOADERDARWINKERNEL_H 299