LLDB mainline
DynamicLoaderDarwinKernel.cpp
Go to the documentation of this file.
1//===-- DynamicLoaderDarwinKernel.cpp -------------------------------------===//
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
12#include "lldb/Core/Debugger.h"
13#include "lldb/Core/Module.h"
16#include "lldb/Core/Section.h"
22#include "lldb/Target/Target.h"
23#include "lldb/Target/Thread.h"
29#include "lldb/Utility/Log.h"
30#include "lldb/Utility/State.h"
31
33
34#include <algorithm>
35#include <memory>
36
37//#define ENABLE_DEBUG_PRINTF // COMMENT THIS LINE OUT PRIOR TO CHECKIN
38#ifdef ENABLE_DEBUG_PRINTF
39#include <cstdio>
40#define DEBUG_PRINTF(fmt, ...) printf(fmt, ##__VA_ARGS__)
41#else
42#define DEBUG_PRINTF(fmt, ...)
43#endif
44
45using namespace lldb;
46using namespace lldb_private;
47
49
50// Progressively greater amounts of scanning we will allow For some targets
51// very early in startup, we can't do any random reads of memory or we can
52// crash the device so a setting is needed that can completely disable the
53// KASLR scans.
54
56 eKASLRScanNone = 0, // No reading into the inferior at all
57 eKASLRScanLowgloAddresses, // Check one word of memory for a possible kernel
58 // addr, then see if a kernel is there
59 eKASLRScanNearPC, // Scan backwards from the current $pc looking for kernel;
60 // checking at 96 locations total
61 eKASLRScanExhaustiveScan // Scan through the entire possible kernel address
62 // range looking for a kernel
63};
64
66 {
68 "none",
69 "Do not read memory looking for a Darwin kernel when attaching.",
70 },
71 {
73 "basic",
74 "Check for the Darwin kernel's load addr in the lowglo page "
75 "(boot-args=debug) only.",
76 },
77 {
79 "fast-scan",
80 "Scan near the pc value on attach to find the Darwin kernel's load "
81 "address.",
82 },
83 {
85 "exhaustive-scan",
86 "Scan through the entire potential address range of Darwin kernel "
87 "(only on 32-bit targets).",
88 },
89};
90
91#define LLDB_PROPERTIES_dynamicloaderdarwinkernel
92#include "DynamicLoaderDarwinKernelProperties.inc"
93
94enum {
95#define LLDB_PROPERTIES_dynamicloaderdarwinkernel
96#include "DynamicLoaderDarwinKernelPropertiesEnum.inc"
97};
98
100public:
101 static llvm::StringRef GetSettingName() {
102 static constexpr llvm::StringLiteral g_setting_name("darwin-kernel");
103 return g_setting_name;
104 }
105
107 m_collection_sp = std::make_shared<OptionValueProperties>(GetSettingName());
108 m_collection_sp->Initialize(g_dynamicloaderdarwinkernel_properties);
109 }
110
112
113 bool GetLoadKexts() const {
114 const uint32_t idx = ePropertyLoadKexts;
115 return GetPropertyAtIndexAs<bool>(
116 idx,
117 g_dynamicloaderdarwinkernel_properties[idx].default_uint_value != 0);
118 }
119
121 const uint32_t idx = ePropertyScanType;
122 return GetPropertyAtIndexAs<KASLRScanType>(
123 idx,
124 static_cast<KASLRScanType>(
125 g_dynamicloaderdarwinkernel_properties[idx].default_uint_value));
126 }
127};
128
130 static DynamicLoaderDarwinKernelProperties g_settings;
131 return g_settings;
132}
133
134static bool is_kernel(Module *module) {
135 if (!module)
136 return false;
137 ObjectFile *objfile = module->GetObjectFile();
138 if (!objfile)
139 return false;
140 if (objfile->GetType() != ObjectFile::eTypeExecutable)
141 return false;
142 if (objfile->GetStrata() != ObjectFile::eStrataKernel)
143 return false;
144
145 return true;
146}
147
148// Create an instance of this class. This function is filled into the plugin
149// info class that gets handed out by the plugin factory and allows the lldb to
150// instantiate an instance of this class.
152 bool force) {
153 if (!force) {
154 // If the user provided an executable binary and it is not a kernel, this
155 // plugin should not create an instance.
156 Module *exec = process->GetTarget().GetExecutableModulePointer();
157 if (exec && !is_kernel(exec))
158 return nullptr;
159
160 // If the target's architecture does not look like an Apple environment,
161 // this plugin should not create an instance.
162 const llvm::Triple &triple_ref =
163 process->GetTarget().GetArchitecture().GetTriple();
164 switch (triple_ref.getOS()) {
165 case llvm::Triple::Darwin:
166 case llvm::Triple::MacOSX:
167 case llvm::Triple::IOS:
168 case llvm::Triple::TvOS:
169 case llvm::Triple::WatchOS:
170 case llvm::Triple::XROS:
171 case llvm::Triple::BridgeOS:
172 if (triple_ref.getVendor() != llvm::Triple::Apple) {
173 return nullptr;
174 }
175 break;
176 // If we have triple like armv7-unknown-unknown, we should try looking for
177 // a Darwin kernel.
178 case llvm::Triple::UnknownOS:
179 break;
180 default:
181 return nullptr;
182 break;
183 }
184 }
185
186 // At this point if there is an ExecutableModule, it is a kernel and the
187 // Target is some variant of an Apple system. If the Process hasn't provided
188 // the kernel load address, we need to look around in memory to find it.
189 const addr_t kernel_load_address = SearchForDarwinKernel(process);
190 if (CheckForKernelImageAtAddress(kernel_load_address, process).IsValid()) {
191 return new DynamicLoaderDarwinKernel(process, kernel_load_address);
192 }
193 return nullptr;
194}
195
198 addr_t kernel_load_address = process->GetImageInfoAddress();
199 if (kernel_load_address == LLDB_INVALID_ADDRESS)
200 kernel_load_address = SearchForKernelAtSameLoadAddr(process);
201 if (kernel_load_address == LLDB_INVALID_ADDRESS)
202 kernel_load_address = SearchForKernelWithDebugHints(process);
203 if (kernel_load_address == LLDB_INVALID_ADDRESS)
204 kernel_load_address = SearchForKernelNearPC(process);
205 if (kernel_load_address == LLDB_INVALID_ADDRESS)
206 kernel_load_address = SearchForKernelViaExhaustiveSearch(process);
207
208 return kernel_load_address;
209}
210
211// Check if the kernel binary is loaded in memory without a slide. First verify
212// that the ExecutableModule is a kernel before we proceed. Returns the address
213// of the kernel if one was found, else LLDB_INVALID_ADDRESS.
216 Module *exe_module = process->GetTarget().GetExecutableModulePointer();
217
220
221 ObjectFile *exe_objfile = exe_module->GetObjectFile();
222
223 if (!exe_objfile->GetBaseAddress().IsValid())
225
227 exe_objfile->GetBaseAddress().GetFileAddress(), process) ==
228 exe_module->GetUUID())
229 return exe_objfile->GetBaseAddress().GetFileAddress();
230
232}
233
234// If the debug flag is included in the boot-args nvram setting, the kernel's
235// load address will be noted in the lowglo page at a fixed address Returns the
236// address of the kernel if one was found, else LLDB_INVALID_ADDRESS.
239 if (GetGlobalProperties().GetScanType() == eKASLRScanNone)
241
242 Status read_err;
243 addr_t kernel_addresses_64[] = {
244 0xfffffff000002010ULL,
245 0xfffffff000004010ULL, // newest arm64 devices
246 0xffffff8000004010ULL, // 2014-2015-ish arm64 devices
247 0xffffff8000002010ULL, // oldest arm64 devices
249 addr_t kernel_addresses_32[] = {0xffff0110, // 2016 and earlier armv7 devices
250 0xffff1010, LLDB_INVALID_ADDRESS};
251
252 uint8_t uval[8];
253 if (process->GetAddressByteSize() == 8) {
254 for (size_t i = 0; kernel_addresses_64[i] != LLDB_INVALID_ADDRESS; i++) {
255 if (process->ReadMemoryFromInferior (kernel_addresses_64[i], uval, 8, read_err) == 8)
256 {
257 DataExtractor data (&uval, 8, process->GetByteOrder(), process->GetAddressByteSize());
258 offset_t offset = 0;
259 uint64_t addr = data.GetU64 (&offset);
260 if (CheckForKernelImageAtAddress(addr, process).IsValid()) {
261 return addr;
262 }
263 }
264 }
265 }
266
267 if (process->GetAddressByteSize() == 4) {
268 for (size_t i = 0; kernel_addresses_32[i] != LLDB_INVALID_ADDRESS; i++) {
269 if (process->ReadMemoryFromInferior (kernel_addresses_32[i], uval, 4, read_err) == 4)
270 {
271 DataExtractor data (&uval, 4, process->GetByteOrder(), process->GetAddressByteSize());
272 offset_t offset = 0;
273 uint32_t addr = data.GetU32 (&offset);
274 if (CheckForKernelImageAtAddress(addr, process).IsValid()) {
275 return addr;
276 }
277 }
278 }
279 }
280
282}
283
284// If the kernel is currently executing when lldb attaches, and we don't have a
285// better way of finding the kernel's load address, try searching backwards
286// from the current pc value looking for the kernel's Mach header in memory.
287// Returns the address of the kernel if one was found, else
288// LLDB_INVALID_ADDRESS.
291 if (GetGlobalProperties().GetScanType() == eKASLRScanNone ||
294 }
295
296 ThreadSP thread = process->GetThreadList().GetSelectedThread();
297 if (thread.get() == nullptr)
299 addr_t pc = thread->GetRegisterContext()->GetPC(LLDB_INVALID_ADDRESS);
300
301 int ptrsize = process->GetTarget().GetArchitecture().GetAddressByteSize();
302
303 // The kernel is always loaded in high memory, if the top bit is zero,
304 // this isn't a kernel.
305 if (ptrsize == 8) {
306 if ((pc & (1ULL << 63)) == 0) {
308 }
309 } else {
310 if ((pc & (1ULL << 31)) == 0) {
312 }
313 }
314
317
318 int pagesize = 0x4000; // 16k pages on 64-bit targets
319 if (ptrsize == 4)
320 pagesize = 0x1000; // 4k pages on 32-bit targets
321
322 // The kernel will be loaded on a page boundary.
323 // Round the current pc down to the nearest page boundary.
324 addr_t addr = pc & ~(pagesize - 1ULL);
325
326 // Search backwards for 128 megabytes, or first memory read error.
327 while (pc - addr < 128 * 0x100000) {
328 bool read_error;
329 if (CheckForKernelImageAtAddress(addr, process, &read_error).IsValid())
330 return addr;
331
332 // Stop scanning on the first read error we encounter; we've walked
333 // past this executable block of memory.
334 if (read_error == true)
335 break;
336
337 addr -= pagesize;
338 }
339
341}
342
343// Scan through the valid address range for a kernel binary. This is uselessly
344// slow in 64-bit environments so we don't even try it. This scan is not
345// enabled by default even for 32-bit targets. Returns the address of the
346// kernel if one was found, else LLDB_INVALID_ADDRESS.
348 Process *process) {
349 if (GetGlobalProperties().GetScanType() != eKASLRScanExhaustiveScan) {
351 }
352
353 addr_t kernel_range_low, kernel_range_high;
354 if (process->GetTarget().GetArchitecture().GetAddressByteSize() == 8) {
355 kernel_range_low = 1ULL << 63;
356 kernel_range_high = UINT64_MAX;
357 } else {
358 kernel_range_low = 1ULL << 31;
359 kernel_range_high = UINT32_MAX;
360 }
361
362 // Stepping through memory at one-megabyte resolution looking for a kernel
363 // rarely works (fast enough) with a 64-bit address space -- for now, let's
364 // not even bother. We may be attaching to something which *isn't* a kernel
365 // and we don't want to spin for minutes on-end looking for a kernel.
366 if (process->GetTarget().GetArchitecture().GetAddressByteSize() == 8)
368
369 addr_t addr = kernel_range_low;
370
371 while (addr >= kernel_range_low && addr < kernel_range_high) {
372 // x86_64 kernels are at offset 0
373 if (CheckForKernelImageAtAddress(addr, process).IsValid())
374 return addr;
375 // 32-bit arm kernels are at offset 0x1000 (one 4k page)
376 if (CheckForKernelImageAtAddress(addr + 0x1000, process).IsValid())
377 return addr + 0x1000;
378 // 64-bit arm kernels are at offset 0x4000 (one 16k page)
379 if (CheckForKernelImageAtAddress(addr + 0x4000, process).IsValid())
380 return addr + 0x4000;
381 addr += 0x100000;
382 }
384}
385
386// Read the mach_header struct out of memory and return it.
387// Returns true if the mach_header was successfully read,
388// Returns false if there was a problem reading the header, or it was not
389// a Mach-O header.
390
391bool
392DynamicLoaderDarwinKernel::ReadMachHeader(addr_t addr, Process *process, llvm::MachO::mach_header &header,
393 bool *read_error) {
395 if (read_error)
396 *read_error = false;
397
398 // Read the mach header and see whether it looks like a kernel
399 if (process->ReadMemory(addr, &header, sizeof(header), error) !=
400 sizeof(header)) {
401 if (read_error)
402 *read_error = true;
403 return false;
404 }
405
406 const uint32_t magicks[] = { llvm::MachO::MH_MAGIC_64, llvm::MachO::MH_MAGIC, llvm::MachO::MH_CIGAM, llvm::MachO::MH_CIGAM_64};
407
408 bool found_matching_pattern = false;
409 for (size_t i = 0; i < std::size(magicks); i++)
410 if (::memcmp (&header.magic, &magicks[i], sizeof (uint32_t)) == 0)
411 found_matching_pattern = true;
412
413 if (!found_matching_pattern)
414 return false;
415
416 if (header.magic == llvm::MachO::MH_CIGAM ||
417 header.magic == llvm::MachO::MH_CIGAM_64) {
418 header.magic = llvm::byteswap<uint32_t>(header.magic);
419 header.cputype = llvm::byteswap<uint32_t>(header.cputype);
420 header.cpusubtype = llvm::byteswap<uint32_t>(header.cpusubtype);
421 header.filetype = llvm::byteswap<uint32_t>(header.filetype);
422 header.ncmds = llvm::byteswap<uint32_t>(header.ncmds);
423 header.sizeofcmds = llvm::byteswap<uint32_t>(header.sizeofcmds);
424 header.flags = llvm::byteswap<uint32_t>(header.flags);
425 }
426
427 return true;
428}
429
430// Given an address in memory, look to see if there is a kernel image at that
431// address.
432// Returns a UUID; if a kernel was not found at that address, UUID.IsValid()
433// will be false.
436 Process *process,
437 bool *read_error) {
438 Log *log = GetLog(LLDBLog::DynamicLoader);
439 if (addr == LLDB_INVALID_ADDRESS) {
440 if (read_error)
441 *read_error = true;
442 return UUID();
443 }
444
445 LLDB_LOGF(log,
446 "DynamicLoaderDarwinKernel::CheckForKernelImageAtAddress: "
447 "looking for kernel binary at 0x%" PRIx64,
448 addr);
449
450 llvm::MachO::mach_header header;
451
452 if (!ReadMachHeader(addr, process, header, read_error))
453 return UUID();
454
455 // First try a quick test -- read the first 4 bytes and see if there is a
456 // valid Mach-O magic field there
457 // (the first field of the mach_header/mach_header_64 struct).
458 // A kernel is an executable which does not have the dynamic link object flag
459 // set.
460 if (header.filetype == llvm::MachO::MH_EXECUTE &&
461 (header.flags & llvm::MachO::MH_DYLDLINK) == 0) {
462 // Create a full module to get the UUID
463 ModuleSP memory_module_sp =
464 process->ReadModuleFromMemory(FileSpec("temp_mach_kernel"), addr);
465 if (!memory_module_sp.get())
466 return UUID();
467
468 ObjectFile *exe_objfile = memory_module_sp->GetObjectFile();
469 if (exe_objfile == nullptr) {
470 LLDB_LOGF(log,
471 "DynamicLoaderDarwinKernel::CheckForKernelImageAtAddress "
472 "found a binary at 0x%" PRIx64
473 " but could not create an object file from memory",
474 addr);
475 return UUID();
476 }
477
478 if (is_kernel(memory_module_sp.get())) {
479 ArchSpec kernel_arch(eArchTypeMachO, header.cputype, header.cpusubtype);
481 kernel_arch)) {
482 process->GetTarget().SetArchitecture(kernel_arch);
483 }
484 if (log) {
485 std::string uuid_str;
486 if (memory_module_sp->GetUUID().IsValid()) {
487 uuid_str = "with UUID ";
488 uuid_str += memory_module_sp->GetUUID().GetAsString();
489 } else {
490 uuid_str = "and no LC_UUID found in load commands ";
491 }
492 LLDB_LOGF(
493 log,
494 "DynamicLoaderDarwinKernel::CheckForKernelImageAtAddress: "
495 "kernel binary image found at 0x%" PRIx64 " with arch '%s' %s",
496 addr, kernel_arch.GetTriple().str().c_str(), uuid_str.c_str());
497 }
498 return memory_module_sp->GetUUID();
499 }
500 }
501
502 return UUID();
503}
504
505// Constructor
507 lldb::addr_t kernel_addr)
508 : DynamicLoader(process), m_kernel_load_address(kernel_addr), m_kernel(),
509 m_kext_summary_header_ptr_addr(), m_kext_summary_header_addr(),
510 m_kext_summary_header(), m_known_kexts(), m_mutex(),
511 m_break_id(LLDB_INVALID_BREAK_ID) {
513 process->SetCanRunCode(false);
514 PlatformSP platform_sp =
517 if (platform_sp.get())
518 process->GetTarget().SetPlatform(platform_sp);
519}
520
521// Destructor
523
527}
528
529/// We've attached to a remote connection, or read a corefile.
530/// Now load the kernel binary and potentially the kexts, add
531/// them to the Target.
535}
536
537/// Called after attaching a process.
538///
539/// Allow DynamicLoader plug-ins to execute some code after
540/// attaching to a process.
544}
545
546// Clear out the state of this class.
547void DynamicLoaderDarwinKernel::Clear(bool clear_process) {
548 std::lock_guard<std::recursive_mutex> guard(m_mutex);
549
552
553 if (clear_process)
554 m_process = nullptr;
555 m_kernel.Clear();
556 m_known_kexts.clear();
560}
561
563 Process *process) {
564 if (IsLoaded())
565 return true;
566
567 if (m_module_sp) {
568 bool changed = false;
569 if (m_module_sp->SetLoadAddress(process->GetTarget(), 0, true, changed))
571 }
572 return false;
573}
574
576 m_module_sp = module_sp;
577 m_kernel_image = is_kernel(module_sp.get());
578}
579
581 return m_module_sp;
582}
583
585 addr_t load_addr) {
586 m_load_address = load_addr;
587}
588
590 return m_load_address;
591}
592
594 return m_size;
595}
596
598 m_size = size;
599}
600
602 return m_load_process_stop_id;
603}
604
606 uint32_t stop_id) {
607 m_load_process_stop_id = stop_id;
608}
609
611 const KextImageInfo &rhs) const {
612 if (m_uuid.IsValid() || rhs.GetUUID().IsValid()) {
613 return m_uuid == rhs.GetUUID();
614 }
615
616 return m_name == rhs.GetName() && m_load_address == rhs.GetLoadAddress();
617}
618
620 m_name = name;
621}
622
624 return m_name;
625}
626
628 m_uuid = uuid;
629}
630
632 return m_uuid;
633}
634
635// Given the m_load_address from the kext summaries, and a UUID, try to create
636// an in-memory Module at that address. Require that the MemoryModule have a
637// matching UUID and detect if this MemoryModule is a kernel or a kext.
638//
639// Returns true if m_memory_module_sp is now set to a valid Module.
640
642 Process *process) {
643 Log *log = GetLog(LLDBLog::Host);
644 if (m_memory_module_sp.get() != nullptr)
645 return true;
646 if (m_load_address == LLDB_INVALID_ADDRESS)
647 return false;
648
649 FileSpec file_spec(m_name.c_str());
650
651 llvm::MachO::mach_header mh;
652 size_t size_to_read = 512;
653 if (ReadMachHeader(m_load_address, process, mh)) {
654 if (mh.magic == llvm::MachO::MH_CIGAM || mh.magic == llvm::MachO::MH_MAGIC)
655 size_to_read = sizeof(llvm::MachO::mach_header) + mh.sizeofcmds;
656 if (mh.magic == llvm::MachO::MH_CIGAM_64 ||
657 mh.magic == llvm::MachO::MH_MAGIC_64)
658 size_to_read = sizeof(llvm::MachO::mach_header_64) + mh.sizeofcmds;
659 }
660
661 ModuleSP memory_module_sp =
662 process->ReadModuleFromMemory(file_spec, m_load_address, size_to_read);
663
664 if (memory_module_sp.get() == nullptr)
665 return false;
666
667 bool this_is_kernel = is_kernel(memory_module_sp.get());
668
669 // If this is a kext, and the kernel specified what UUID we should find at
670 // this load address, require that the memory module have a matching UUID or
671 // something has gone wrong and we should discard it.
672 if (m_uuid.IsValid()) {
673 if (m_uuid != memory_module_sp->GetUUID()) {
674 if (log) {
675 LLDB_LOGF(log,
676 "KextImageInfo::ReadMemoryModule the kernel said to find "
677 "uuid %s at 0x%" PRIx64
678 " but instead we found uuid %s, throwing it away",
679 m_uuid.GetAsString().c_str(), m_load_address,
680 memory_module_sp->GetUUID().GetAsString().c_str());
681 }
682 return false;
683 }
684 }
685
686 // If the in-memory Module has a UUID, let's use that.
687 if (!m_uuid.IsValid() && memory_module_sp->GetUUID().IsValid()) {
688 m_uuid = memory_module_sp->GetUUID();
689 }
690
691 m_memory_module_sp = memory_module_sp;
692 m_kernel_image = this_is_kernel;
693 if (this_is_kernel) {
694 if (log) {
695 // This is unusual and probably not intended
696 LLDB_LOGF(log,
697 "KextImageInfo::ReadMemoryModule read the kernel binary out "
698 "of memory");
699 }
700 if (memory_module_sp->GetArchitecture().IsValid()) {
701 process->GetTarget().SetArchitecture(memory_module_sp->GetArchitecture());
702 }
703 }
704
705 return true;
706}
707
709 return m_kernel_image;
710}
711
713 m_kernel_image = is_kernel;
714}
715
717 Process *process) {
718 Log *log = GetLog(LLDBLog::DynamicLoader);
719 if (IsLoaded())
720 return true;
721
722 Target &target = process->GetTarget();
723
724 // kexts will have a uuid from the table.
725 // for the kernel, we'll need to read the load commands out of memory to get it.
726 if (m_uuid.IsValid() == false) {
727 if (ReadMemoryModule(process) == false) {
728 Log *log = GetLog(LLDBLog::DynamicLoader);
729 LLDB_LOGF(log,
730 "Unable to read '%s' from memory at address 0x%" PRIx64
731 " to get the segment load addresses.",
732 m_name.c_str(), m_load_address);
733 return false;
734 }
735 }
736
737 if (IsKernel() && m_uuid.IsValid()) {
738 Stream &s = target.GetDebugger().GetOutputStream();
739 s.Printf("Kernel UUID: %s\n", m_uuid.GetAsString().c_str());
740 s.Printf("Load Address: 0x%" PRIx64 "\n", m_load_address);
741
742 // Start of a kernel debug session, we have the UUID of the kernel.
743 // Go through the target's list of modules and if there are any kernel
744 // modules with non-matching UUIDs, remove them. The user may have added
745 // the wrong kernel binary manually and it will only confuse things.
746 ModuleList incorrect_kernels;
747 for (ModuleSP module_sp : target.GetImages().Modules()) {
748 if (is_kernel(module_sp.get()) && module_sp->GetUUID() != m_uuid)
749 incorrect_kernels.Append(module_sp);
750 }
751 target.GetImages().Remove(incorrect_kernels);
752 }
753
754 if (!m_module_sp) {
755 // See if the kext has already been loaded into the target, probably by the
756 // user doing target modules add.
757 const ModuleList &target_images = target.GetImages();
758 m_module_sp = target_images.FindModule(m_uuid);
759
760 // Search for the kext on the local filesystem via the UUID
761 if (!m_module_sp && m_uuid.IsValid()) {
762 ModuleSpec module_spec;
763 module_spec.GetUUID() = m_uuid;
764 module_spec.GetArchitecture() = target.GetArchitecture();
765
766 // If the current platform is PlatformDarwinKernel, create a ModuleSpec
767 // with the filename set to be the bundle ID for this kext, e.g.
768 // "com.apple.filesystems.msdosfs", and ask the platform to find it.
769 // PlatformDarwinKernel does a special scan for kexts on the local
770 // system.
771 PlatformSP platform_sp(target.GetPlatform());
772 if (platform_sp) {
773 static ConstString g_platform_name(
775 if (platform_sp->GetPluginName() == g_platform_name.GetStringRef()) {
776 ModuleSpec kext_bundle_module_spec(module_spec);
777 FileSpec kext_filespec(m_name.c_str());
778 FileSpecList search_paths = target.GetExecutableSearchPaths();
779 kext_bundle_module_spec.GetFileSpec() = kext_filespec;
780 platform_sp->GetSharedModule(kext_bundle_module_spec, process,
781 m_module_sp, &search_paths, nullptr,
782 nullptr);
783 }
784 }
785
786 // Ask the Target to find this file on the local system, if possible.
787 // This will search in the list of currently-loaded files, look in the
788 // standard search paths on the system, and on a Mac it will try calling
789 // the DebugSymbols framework with the UUID to find the binary via its
790 // search methods.
791 if (!m_module_sp) {
792 m_module_sp = target.GetOrCreateModule(module_spec, true /* notify */);
793 }
794
795 // For the kernel, we really do need an on-disk file copy of the binary
796 // to do anything useful. This will force a call to dsymForUUID if it
797 // exists, instead of depending on the DebugSymbols preferences being
798 // set.
799 Status kernel_search_error;
800 if (IsKernel() &&
801 (!m_module_sp || !m_module_sp->GetSymbolFileFileSpec())) {
803 module_spec, kernel_search_error, true)) {
804 if (FileSystem::Instance().Exists(module_spec.GetFileSpec())) {
805 m_module_sp = std::make_shared<Module>(module_spec.GetFileSpec(),
806 target.GetArchitecture());
807 }
808 }
809 }
810
811 if (IsKernel() && !m_module_sp) {
812 Stream &s = target.GetDebugger().GetErrorStream();
813 s.Printf("WARNING: Unable to locate kernel binary on the debugger "
814 "system.\n");
815 if (kernel_search_error.Fail() && kernel_search_error.AsCString("") &&
816 kernel_search_error.AsCString("")[0] != '\0') {
817 s << kernel_search_error.AsCString();
818 }
819 }
820 }
821
822 if (m_module_sp && m_uuid.IsValid() && m_module_sp->GetUUID() == m_uuid &&
823 m_module_sp->GetObjectFile()) {
824 if (ObjectFileMachO *ondisk_objfile_macho =
825 llvm::dyn_cast<ObjectFileMachO>(m_module_sp->GetObjectFile())) {
826 if (!IsKernel() && !ondisk_objfile_macho->IsKext()) {
827 // We have a non-kext, non-kernel binary. If we already have this
828 // loaded in the Target with load addresses, don't re-load it again.
829 ModuleSP existing_module_sp = target.GetImages().FindModule(m_uuid);
830 if (existing_module_sp &&
831 existing_module_sp->IsLoadedInTarget(&target)) {
832 LLDB_LOGF(log,
833 "'%s' with UUID %s is not a kext or kernel, and is "
834 "already registered in target, not loading.",
835 m_name.c_str(), m_uuid.GetAsString().c_str());
836 // It's already loaded, return true.
837 return true;
838 }
839 }
840 }
841 }
842
843 // If we managed to find a module, append it to the target's list of
844 // images. If we also have a memory module, require that they have matching
845 // UUIDs
846 if (m_module_sp) {
847 if (m_uuid.IsValid() && m_module_sp->GetUUID() == m_uuid) {
848 target.GetImages().AppendIfNeeded(m_module_sp, false);
849 }
850 }
851 }
852
853 // If we've found a binary, read the load commands out of memory so we
854 // can set the segment load addresses.
855 if (m_module_sp)
856 ReadMemoryModule (process);
857
858 static ConstString g_section_name_LINKEDIT("__LINKEDIT");
859
860 if (m_memory_module_sp && m_module_sp) {
861 if (m_module_sp->GetUUID() == m_memory_module_sp->GetUUID()) {
862 ObjectFile *ondisk_object_file = m_module_sp->GetObjectFile();
863 ObjectFile *memory_object_file = m_memory_module_sp->GetObjectFile();
864
865 if (memory_object_file && ondisk_object_file) {
866 // The memory_module for kexts may have an invalid __LINKEDIT seg; skip
867 // it.
868 const bool ignore_linkedit = !IsKernel();
869
870 // Normally a kext will have its segment load commands
871 // (LC_SEGMENT vmaddrs) corrected in memory to have their
872 // actual segment addresses.
873 // Userland proceses have their libraries updated the same way
874 // by dyld. The Mach-O load commands in memory are the canonical
875 // addresses.
876 //
877 // If the kernel gives us a binary where the in-memory segment
878 // vmaddr is incorrect, then this binary was put in memory without
879 // updating its Mach-O load commands. We should assume a static
880 // slide value will be applied to every segment; we don't have the
881 // correct addresses for each individual segment.
882 addr_t fixed_slide = LLDB_INVALID_ADDRESS;
883 if (ObjectFileMachO *memory_objfile_macho =
884 llvm::dyn_cast<ObjectFileMachO>(memory_object_file)) {
885 if (Section *header_sect =
886 memory_objfile_macho->GetMachHeaderSection()) {
887 if (header_sect->GetFileAddress() != m_load_address) {
888 fixed_slide = m_load_address - header_sect->GetFileAddress();
889 LLDB_LOGF(
890 log,
891 "kext %s in-memory LC_SEGMENT vmaddr is not correct, using a "
892 "fixed slide of 0x%" PRIx64,
893 m_name.c_str(), fixed_slide);
894 }
895 }
896 }
897
898 SectionList *ondisk_section_list = ondisk_object_file->GetSectionList();
899 SectionList *memory_section_list = memory_object_file->GetSectionList();
900 if (memory_section_list && ondisk_section_list) {
901 const uint32_t num_ondisk_sections = ondisk_section_list->GetSize();
902 // There may be CTF sections in the memory image so we can't always
903 // just compare the number of sections (which are actually segments
904 // in mach-o parlance)
905 uint32_t sect_idx = 0;
906
907 // Use the memory_module's addresses for each section to set the file
908 // module's load address as appropriate. We don't want to use a
909 // single slide value for the entire kext - different segments may be
910 // slid different amounts by the kext loader.
911
912 uint32_t num_sections_loaded = 0;
913 for (sect_idx = 0; sect_idx < num_ondisk_sections; ++sect_idx) {
914 SectionSP ondisk_section_sp(
915 ondisk_section_list->GetSectionAtIndex(sect_idx));
916 if (ondisk_section_sp) {
917 // Don't ever load __LINKEDIT as it may or may not be actually
918 // mapped into memory and there is no current way to tell. Until
919 // such an ability exists, do not load the __LINKEDIT.
920 if (ignore_linkedit &&
921 ondisk_section_sp->GetName() == g_section_name_LINKEDIT)
922 continue;
923
924 if (fixed_slide != LLDB_INVALID_ADDRESS) {
926 ondisk_section_sp,
927 ondisk_section_sp->GetFileAddress() + fixed_slide);
928 } else {
929 const Section *memory_section =
930 memory_section_list
931 ->FindSectionByName(ondisk_section_sp->GetName())
932 .get();
933 if (memory_section) {
935 ondisk_section_sp, memory_section->GetFileAddress());
936 ++num_sections_loaded;
937 }
938 }
939 }
940 }
941 if (num_sections_loaded > 0)
942 m_load_process_stop_id = process->GetStopID();
943 else
944 m_module_sp.reset(); // No sections were loaded
945 } else
946 m_module_sp.reset(); // One or both section lists
947 } else
948 m_module_sp.reset(); // One or both object files missing
949 } else
950 m_module_sp.reset(); // UUID mismatch
951 }
952
953 bool is_loaded = IsLoaded();
954
955 if (is_loaded && m_module_sp && IsKernel()) {
956 Stream &s = target.GetDebugger().GetOutputStream();
957 ObjectFile *kernel_object_file = m_module_sp->GetObjectFile();
958 if (kernel_object_file) {
959 addr_t file_address =
960 kernel_object_file->GetBaseAddress().GetFileAddress();
961 if (m_load_address != LLDB_INVALID_ADDRESS &&
962 file_address != LLDB_INVALID_ADDRESS) {
963 s.Printf("Kernel slid 0x%" PRIx64 " in memory.\n",
964 m_load_address - file_address);
965 }
966 }
967 {
968 s.Printf("Loaded kernel file %s\n",
969 m_module_sp->GetFileSpec().GetPath().c_str());
970 }
971 s.Flush();
972 }
973
974 // Notify the target about the module being added;
975 // set breakpoints, load dSYM scripts, etc. as needed.
976 if (is_loaded && m_module_sp) {
977 ModuleList loaded_module_list;
978 loaded_module_list.Append(m_module_sp);
979 target.ModulesDidLoad(loaded_module_list);
980 }
981
982 return is_loaded;
983}
984
986 if (m_memory_module_sp)
987 return m_memory_module_sp->GetArchitecture().GetAddressByteSize();
988 if (m_module_sp)
989 return m_module_sp->GetArchitecture().GetAddressByteSize();
990 return 0;
991}
992
994 if (m_memory_module_sp)
995 return m_memory_module_sp->GetArchitecture().GetByteOrder();
996 if (m_module_sp)
997 return m_module_sp->GetArchitecture().GetByteOrder();
999}
1000
1003 if (m_memory_module_sp)
1004 return m_memory_module_sp->GetArchitecture();
1005 if (m_module_sp)
1006 return m_module_sp->GetArchitecture();
1007 return lldb_private::ArchSpec();
1008}
1009
1010// Load the kernel module and initialize the "m_kernel" member. Return true
1011// _only_ if the kernel is loaded the first time through (subsequent calls to
1012// this function should return false after the kernel has been already loaded).
1015 m_kernel.Clear();
1017 if (is_kernel(module_sp.get())) {
1018 m_kernel.SetModule(module_sp);
1019 m_kernel.SetIsKernel(true);
1020 }
1021
1022 ConstString kernel_name("mach_kernel");
1023 if (m_kernel.GetModule().get() && m_kernel.GetModule()->GetObjectFile() &&
1025 ->GetObjectFile()
1026 ->GetFileSpec()
1027 .GetFilename()
1028 .IsEmpty()) {
1029 kernel_name =
1030 m_kernel.GetModule()->GetObjectFile()->GetFileSpec().GetFilename();
1031 }
1032 m_kernel.SetName(kernel_name.AsCString());
1033
1037 m_kernel.GetModule()) {
1038 // We didn't get a hint from the process, so we will try the kernel at
1039 // the address that it exists at in the file if we have one
1040 ObjectFile *kernel_object_file = m_kernel.GetModule()->GetObjectFile();
1041 if (kernel_object_file) {
1042 addr_t load_address =
1043 kernel_object_file->GetBaseAddress().GetLoadAddress(
1044 &m_process->GetTarget());
1045 addr_t file_address =
1046 kernel_object_file->GetBaseAddress().GetFileAddress();
1047 if (load_address != LLDB_INVALID_ADDRESS && load_address != 0) {
1048 m_kernel.SetLoadAddress(load_address);
1049 if (load_address != file_address) {
1050 // Don't accidentally relocate the kernel to the File address --
1051 // the Load address has already been set to its actual in-memory
1052 // address. Mark it as IsLoaded.
1054 }
1055 } else {
1056 m_kernel.SetLoadAddress(file_address);
1057 }
1058 }
1059 }
1060 }
1061
1065 }
1066 }
1067
1068 // The operating system plugin gets loaded and initialized in
1069 // LoadImageUsingMemoryModule when we discover the kernel dSYM. For a core
1070 // file in particular, that's the wrong place to do this, since we haven't
1071 // fixed up the section addresses yet. So let's redo it here.
1073
1074 if (m_kernel.IsLoaded() && m_kernel.GetModule()) {
1075 static ConstString kext_summary_symbol("gLoadedKextSummaries");
1076 static ConstString arm64_T1Sz_value("gT1Sz");
1077 const Symbol *symbol =
1078 m_kernel.GetModule()->FindFirstSymbolWithNameAndType(
1079 kext_summary_symbol, eSymbolTypeData);
1080 if (symbol) {
1082 // Update all image infos
1084 }
1085 // If the kernel global with the T1Sz setting is available,
1086 // update the target.process.virtual-addressable-bits to be correct.
1087 // NB the xnu kernel always has T0Sz and T1Sz the same value. If
1088 // it wasn't the same, we would need to set
1089 // target.process.virtual-addressable-bits = T0Sz
1090 // target.process.highmem-virtual-addressable-bits = T1Sz
1091 symbol = m_kernel.GetModule()->FindFirstSymbolWithNameAndType(
1092 arm64_T1Sz_value, eSymbolTypeData);
1093 if (symbol) {
1094 const addr_t orig_code_mask = m_process->GetCodeAddressMask();
1095 const addr_t orig_data_mask = m_process->GetDataAddressMask();
1096
1099 Status error;
1100 // gT1Sz is 8 bytes. We may run on a stripped kernel binary
1101 // where we can't get the size accurately. Hardcode it.
1102 const size_t sym_bytesize = 8; // size of gT1Sz value
1103 uint64_t sym_value =
1105 symbol->GetAddress(), sym_bytesize, 0, error);
1106 if (error.Success()) {
1107 // 64 - T1Sz is the highest bit used for auth.
1108 // The value we pass in to SetVirtualAddressableBits is
1109 // the number of bits used for addressing, so if
1110 // T1Sz is 25, then 64-25 == 39, bits 0..38 are used for
1111 // addressing, bits 39..63 are used for PAC/TBI or whatever.
1112 uint32_t virt_addr_bits = 64 - sym_value;
1113 addr_t mask = AddressableBits::AddressableBitToMask(virt_addr_bits);
1116 } else {
1117 m_process->SetCodeAddressMask(orig_code_mask);
1118 m_process->SetDataAddressMask(orig_data_mask);
1119 }
1120 }
1121 } else {
1122 m_kernel.Clear();
1123 }
1124 }
1125}
1126
1127// Static callback function that gets called when our DYLD notification
1128// breakpoint gets hit. We update all of our image infos and then let our super
1129// class DynamicLoader class decide if we should stop or not (based on global
1130// preference).
1132 void *baton, StoppointCallbackContext *context, user_id_t break_id,
1133 user_id_t break_loc_id) {
1134 return static_cast<DynamicLoaderDarwinKernel *>(baton)->BreakpointHit(
1135 context, break_id, break_loc_id);
1136}
1137
1139 user_id_t break_id,
1140 user_id_t break_loc_id) {
1141 Log *log = GetLog(LLDBLog::DynamicLoader);
1142 LLDB_LOGF(log, "DynamicLoaderDarwinKernel::BreakpointHit (...)\n");
1143
1145
1146 if (log)
1147 PutToLog(log);
1148
1149 return GetStopWhenImagesChange();
1150}
1151
1153 std::lock_guard<std::recursive_mutex> guard(m_mutex);
1154
1155 // the all image infos is already valid for this process stop ID
1156
1158 const uint32_t addr_size = m_kernel.GetAddressByteSize();
1159 const ByteOrder byte_order = m_kernel.GetByteOrder();
1160 Status error;
1161 // Read enough bytes for a "OSKextLoadedKextSummaryHeader" structure which
1162 // is currently 4 uint32_t and a pointer.
1163 uint8_t buf[24];
1164 DataExtractor data(buf, sizeof(buf), byte_order, addr_size);
1165 const size_t count = 4 * sizeof(uint32_t) + addr_size;
1166 const bool force_live_memory = true;
1169 m_kext_summary_header_addr, force_live_memory)) {
1170 // We got a valid address for our kext summary header and make sure it
1171 // isn't NULL
1174 const size_t bytes_read = m_process->GetTarget().ReadMemory(
1175 m_kext_summary_header_addr, buf, count, error, force_live_memory);
1176 if (bytes_read == count) {
1177 lldb::offset_t offset = 0;
1178 m_kext_summary_header.version = data.GetU32(&offset);
1179 if (m_kext_summary_header.version > 128) {
1181 s.Printf("WARNING: Unable to read kext summary header, got "
1182 "improbable version number %u\n",
1184 // If we get an improbably large version number, we're probably
1185 // getting bad memory.
1187 return false;
1188 }
1189 if (m_kext_summary_header.version >= 2) {
1190 m_kext_summary_header.entry_size = data.GetU32(&offset);
1191 if (m_kext_summary_header.entry_size > 4096) {
1192 // If we get an improbably large entry_size, we're probably
1193 // getting bad memory.
1194 Stream &s =
1196 s.Printf("WARNING: Unable to read kext summary header, got "
1197 "improbable entry_size %u\n",
1200 return false;
1201 }
1202 } else {
1203 // Versions less than 2 didn't have an entry size, it was hard
1204 // coded
1207 }
1209 if (m_kext_summary_header.entry_count > 10000) {
1210 // If we get an improbably large number of kexts, we're probably
1211 // getting bad memory.
1213 s.Printf("WARNING: Unable to read kext summary header, got "
1214 "improbable number of kexts %u\n",
1217 return false;
1218 }
1219 return true;
1220 }
1221 }
1222 }
1223 }
1225 return false;
1226}
1227
1228// We've either (a) just attached to a new kernel, or (b) the kexts-changed
1229// breakpoint was hit and we need to figure out what kexts have been added or
1230// removed. Read the kext summaries from the inferior kernel memory, compare
1231// them against the m_known_kexts vector and update the m_known_kexts vector as
1232// needed to keep in sync with the inferior.
1233
1235 const Address &kext_summary_addr, uint32_t count) {
1236 KextImageInfo::collection kext_summaries;
1237 Log *log = GetLog(LLDBLog::DynamicLoader);
1238 LLDB_LOGF(log,
1239 "Kexts-changed breakpoint hit, there are %d kexts currently.\n",
1240 count);
1241
1242 std::lock_guard<std::recursive_mutex> guard(m_mutex);
1243
1244 if (!ReadKextSummaries(kext_summary_addr, count, kext_summaries))
1245 return false;
1246
1247 // read the plugin.dynamic-loader.darwin-kernel.load-kexts setting -- if the
1248 // user requested no kext loading, don't print any messages about kexts &
1249 // don't try to read them.
1250 const bool load_kexts = GetGlobalProperties().GetLoadKexts();
1251
1252 // By default, all kexts we've loaded in the past are marked as "remove" and
1253 // all of the kexts we just found out about from ReadKextSummaries are marked
1254 // as "add".
1255 std::vector<bool> to_be_removed(m_known_kexts.size(), true);
1256 std::vector<bool> to_be_added(count, true);
1257
1258 int number_of_new_kexts_being_added = 0;
1259 int number_of_old_kexts_being_removed = m_known_kexts.size();
1260
1261 const uint32_t new_kexts_size = kext_summaries.size();
1262 const uint32_t old_kexts_size = m_known_kexts.size();
1263
1264 // The m_known_kexts vector may have entries that have been Cleared, or are a
1265 // kernel.
1266 for (uint32_t old_kext = 0; old_kext < old_kexts_size; old_kext++) {
1267 bool ignore = false;
1268 KextImageInfo &image_info = m_known_kexts[old_kext];
1269 if (image_info.IsKernel()) {
1270 ignore = true;
1271 } else if (image_info.GetLoadAddress() == LLDB_INVALID_ADDRESS &&
1272 !image_info.GetModule()) {
1273 ignore = true;
1274 }
1275
1276 if (ignore) {
1277 number_of_old_kexts_being_removed--;
1278 to_be_removed[old_kext] = false;
1279 }
1280 }
1281
1282 // Scan over the list of kexts we just read from the kernel, note those that
1283 // need to be added and those already loaded.
1284 for (uint32_t new_kext = 0; new_kext < new_kexts_size; new_kext++) {
1285 bool add_this_one = true;
1286 for (uint32_t old_kext = 0; old_kext < old_kexts_size; old_kext++) {
1287 if (m_known_kexts[old_kext] == kext_summaries[new_kext]) {
1288 // We already have this kext, don't re-load it.
1289 to_be_added[new_kext] = false;
1290 // This kext is still present, do not remove it.
1291 to_be_removed[old_kext] = false;
1292
1293 number_of_old_kexts_being_removed--;
1294 add_this_one = false;
1295 break;
1296 }
1297 }
1298 // If this "kext" entry is actually an alias for the kernel -- the kext was
1299 // compiled into the kernel or something -- then we don't want to load the
1300 // kernel's text section at a different address. Ignore this kext entry.
1301 if (kext_summaries[new_kext].GetUUID().IsValid() &&
1302 m_kernel.GetUUID().IsValid() &&
1303 kext_summaries[new_kext].GetUUID() == m_kernel.GetUUID()) {
1304 to_be_added[new_kext] = false;
1305 break;
1306 }
1307 if (add_this_one) {
1308 number_of_new_kexts_being_added++;
1309 }
1310 }
1311
1312 if (number_of_new_kexts_being_added == 0 &&
1313 number_of_old_kexts_being_removed == 0)
1314 return true;
1315
1317 if (load_kexts) {
1318 if (number_of_new_kexts_being_added > 0 &&
1319 number_of_old_kexts_being_removed > 0) {
1320 s.Printf("Loading %d kext modules and unloading %d kext modules ",
1321 number_of_new_kexts_being_added,
1322 number_of_old_kexts_being_removed);
1323 } else if (number_of_new_kexts_being_added > 0) {
1324 s.Printf("Loading %d kext modules ", number_of_new_kexts_being_added);
1325 } else if (number_of_old_kexts_being_removed > 0) {
1326 s.Printf("Unloading %d kext modules ", number_of_old_kexts_being_removed);
1327 }
1328 }
1329
1330 if (log) {
1331 if (load_kexts) {
1332 LLDB_LOGF(log,
1333 "DynamicLoaderDarwinKernel::ParseKextSummaries: %d kexts "
1334 "added, %d kexts removed",
1335 number_of_new_kexts_being_added,
1336 number_of_old_kexts_being_removed);
1337 } else {
1338 LLDB_LOGF(log,
1339 "DynamicLoaderDarwinKernel::ParseKextSummaries kext loading is "
1340 "disabled, else would have %d kexts added, %d kexts removed",
1341 number_of_new_kexts_being_added,
1342 number_of_old_kexts_being_removed);
1343 }
1344 }
1345
1346 // Build up a list of <kext-name, uuid> for any kexts that fail to load
1347 std::vector<std::pair<std::string, UUID>> kexts_failed_to_load;
1348 if (number_of_new_kexts_being_added > 0) {
1349 ModuleList loaded_module_list;
1350
1351 const uint32_t num_of_new_kexts = kext_summaries.size();
1352 for (uint32_t new_kext = 0; new_kext < num_of_new_kexts; new_kext++) {
1353 if (to_be_added[new_kext]) {
1354 KextImageInfo &image_info = kext_summaries[new_kext];
1355 bool kext_successfully_added = true;
1356 if (load_kexts) {
1357 if (!image_info.LoadImageUsingMemoryModule(m_process)) {
1358 kexts_failed_to_load.push_back(std::pair<std::string, UUID>(
1359 kext_summaries[new_kext].GetName(),
1360 kext_summaries[new_kext].GetUUID()));
1362 kext_successfully_added = false;
1363 }
1364 }
1365
1366 m_known_kexts.push_back(image_info);
1367
1368 if (image_info.GetModule() &&
1369 m_process->GetStopID() == image_info.GetProcessStopId())
1370 loaded_module_list.AppendIfNeeded(image_info.GetModule());
1371
1372 if (load_kexts) {
1373 if (kext_successfully_added)
1374 s.Printf(".");
1375 else
1376 s.Printf("-");
1377 }
1378
1379 if (log)
1380 kext_summaries[new_kext].PutToLog(log);
1381 }
1382 }
1383 m_process->GetTarget().ModulesDidLoad(loaded_module_list);
1384 }
1385
1386 if (number_of_old_kexts_being_removed > 0) {
1387 ModuleList loaded_module_list;
1388 const uint32_t num_of_old_kexts = m_known_kexts.size();
1389 for (uint32_t old_kext = 0; old_kext < num_of_old_kexts; old_kext++) {
1390 ModuleList unloaded_module_list;
1391 if (to_be_removed[old_kext]) {
1392 KextImageInfo &image_info = m_known_kexts[old_kext];
1393 // You can't unload the kernel.
1394 if (!image_info.IsKernel()) {
1395 if (image_info.GetModule()) {
1396 unloaded_module_list.AppendIfNeeded(image_info.GetModule());
1397 }
1398 s.Printf(".");
1399 image_info.Clear();
1400 // should pull it out of the KextImageInfos vector but that would
1401 // mutate the list and invalidate the to_be_removed bool vector;
1402 // leaving it in place once Cleared() is relatively harmless.
1403 }
1404 }
1405 m_process->GetTarget().ModulesDidUnload(unloaded_module_list, false);
1406 }
1407 }
1408
1409 if (load_kexts) {
1410 s.Printf(" done.\n");
1411 if (kexts_failed_to_load.size() > 0 && number_of_new_kexts_being_added > 0) {
1412 s.Printf("Failed to load %d of %d kexts:\n",
1413 (int)kexts_failed_to_load.size(),
1414 number_of_new_kexts_being_added);
1415 // print a sorted list of <kext-name, uuid> kexts which failed to load
1416 unsigned longest_name = 0;
1417 std::sort(kexts_failed_to_load.begin(), kexts_failed_to_load.end());
1418 for (const auto &ku : kexts_failed_to_load) {
1419 if (ku.first.size() > longest_name)
1420 longest_name = ku.first.size();
1421 }
1422 for (const auto &ku : kexts_failed_to_load) {
1423 std::string uuid;
1424 if (ku.second.IsValid())
1425 uuid = ku.second.GetAsString();
1426 s.Printf(" %-*s %s\n", longest_name, ku.first.c_str(), uuid.c_str());
1427 }
1428 }
1429 s.Flush();
1430 }
1431
1432 return true;
1433}
1434
1436 const Address &kext_summary_addr, uint32_t image_infos_count,
1437 KextImageInfo::collection &image_infos) {
1438 const ByteOrder endian = m_kernel.GetByteOrder();
1439 const uint32_t addr_size = m_kernel.GetAddressByteSize();
1440
1441 image_infos.resize(image_infos_count);
1442 const size_t count = image_infos.size() * m_kext_summary_header.entry_size;
1443 DataBufferHeap data(count, 0);
1444 Status error;
1445
1446 const bool force_live_memory = true;
1447 const size_t bytes_read = m_process->GetTarget().ReadMemory(
1448 kext_summary_addr, data.GetBytes(), data.GetByteSize(), error, force_live_memory);
1449 if (bytes_read == count) {
1450
1451 DataExtractor extractor(data.GetBytes(), data.GetByteSize(), endian,
1452 addr_size);
1453 uint32_t i = 0;
1454 for (uint32_t kext_summary_offset = 0;
1455 i < image_infos.size() &&
1456 extractor.ValidOffsetForDataOfSize(kext_summary_offset,
1458 ++i, kext_summary_offset += m_kext_summary_header.entry_size) {
1459 lldb::offset_t offset = kext_summary_offset;
1460 const void *name_data =
1461 extractor.GetData(&offset, KERNEL_MODULE_MAX_NAME);
1462 if (name_data == nullptr)
1463 break;
1464 image_infos[i].SetName((const char *)name_data);
1465 UUID uuid(extractor.GetData(&offset, 16), 16);
1466 image_infos[i].SetUUID(uuid);
1467 image_infos[i].SetLoadAddress(extractor.GetU64(&offset));
1468 image_infos[i].SetSize(extractor.GetU64(&offset));
1469 }
1470 if (i < image_infos.size())
1471 image_infos.resize(i);
1472 } else {
1473 image_infos.clear();
1474 }
1475 return image_infos.size();
1476}
1477
1479 std::lock_guard<std::recursive_mutex> guard(m_mutex);
1480
1481 if (ReadKextSummaryHeader()) {
1484 Address summary_addr(m_kext_summary_header_addr);
1485 summary_addr.Slide(m_kext_summary_header.GetSize());
1486 if (!ParseKextSummaries(summary_addr,
1488 m_known_kexts.clear();
1489 }
1490 return true;
1491 }
1492 }
1493 return false;
1494}
1495
1496// Dump an image info structure to the file handle provided.
1498 if (m_load_address == LLDB_INVALID_ADDRESS) {
1499 LLDB_LOG(log, "uuid={0} name=\"{1}\" (UNLOADED)", m_uuid.GetAsString(),
1500 m_name);
1501 } else {
1502 LLDB_LOG(log, "addr={0:x+16} size={1:x+16} uuid={2} name=\"{3}\"",
1503 m_load_address, m_size, m_uuid.GetAsString(), m_name);
1504 }
1505}
1506
1507// Dump the _dyld_all_image_infos members and all current image infos that we
1508// have parsed to the file handle provided.
1510 if (log == nullptr)
1511 return;
1512
1513 std::lock_guard<std::recursive_mutex> guard(m_mutex);
1514 LLDB_LOGF(log,
1515 "gLoadedKextSummaries = 0x%16.16" PRIx64
1516 " { version=%u, entry_size=%u, entry_count=%u }",
1520
1521 size_t i;
1522 const size_t count = m_known_kexts.size();
1523 if (count > 0) {
1524 log->PutCString("Loaded:");
1525 for (i = 0; i < count; i++)
1526 m_known_kexts[i].PutToLog(log);
1527 }
1528}
1529
1531 DEBUG_PRINTF("DynamicLoaderDarwinKernel::%s() process state = %s\n",
1532 __FUNCTION__, StateAsCString(m_process->GetState()));
1533 Clear(true);
1534 m_process = process;
1535}
1536
1539 DEBUG_PRINTF("DynamicLoaderDarwinKernel::%s() process state = %s\n",
1540 __FUNCTION__, StateAsCString(m_process->GetState()));
1541
1542 const bool internal_bp = true;
1543 const bool hardware = false;
1544 const LazyBool skip_prologue = eLazyBoolNo;
1545 FileSpecList module_spec_list;
1546 module_spec_list.Append(m_kernel.GetModule()->GetFileSpec());
1547 Breakpoint *bp =
1549 .CreateBreakpoint(&module_spec_list, nullptr,
1550 "OSKextLoadedKextSummariesUpdated",
1551 eFunctionNameTypeFull, eLanguageTypeUnknown, 0,
1552 skip_prologue, internal_bp, hardware)
1553 .get();
1554
1556 true);
1557 m_break_id = bp->GetID();
1558 }
1559}
1560
1561// Member function that gets called when the process state changes.
1563 StateType state) {
1564 DEBUG_PRINTF("DynamicLoaderDarwinKernel::%s(%s)\n", __FUNCTION__,
1565 StateAsCString(state));
1566 switch (state) {
1567 case eStateConnected:
1568 case eStateAttaching:
1569 case eStateLaunching:
1570 case eStateInvalid:
1571 case eStateUnloaded:
1572 case eStateExited:
1573 case eStateDetached:
1574 Clear(false);
1575 break;
1576
1577 case eStateStopped:
1579 break;
1580
1581 case eStateRunning:
1582 case eStateStepping:
1583 case eStateCrashed:
1584 case eStateSuspended:
1585 break;
1586 }
1587}
1588
1591 bool stop_others) {
1592 ThreadPlanSP thread_plan_sp;
1593 Log *log = GetLog(LLDBLog::Step);
1594 LLDB_LOGF(log, "Could not find symbol for step through.");
1595 return thread_plan_sp;
1596}
1597
1599 Status error;
1600 error.SetErrorString(
1601 "always unsafe to load or unload shared libraries in the darwin kernel");
1602 return error;
1603}
1604
1609}
1610
1613}
1614
1616 lldb_private::Debugger &debugger) {
1619 const bool is_global_setting = true;
1621 debugger, GetGlobalProperties().GetValueProperties(),
1622 "Properties for the DynamicLoaderDarwinKernel plug-in.",
1623 is_global_setting);
1624 }
1625}
1626
1628 return "Dynamic loader plug-in that watches for shared library loads/unloads "
1629 "in the MacOSX kernel.";
1630}
1631
1634 switch (magic) {
1635 case llvm::MachO::MH_MAGIC:
1636 case llvm::MachO::MH_MAGIC_64:
1637 return endian::InlHostByteOrder();
1638
1639 case llvm::MachO::MH_CIGAM:
1640 case llvm::MachO::MH_CIGAM_64:
1643 else
1644 return lldb::eByteOrderBig;
1645
1646 default:
1647 break;
1648 }
1650}
static llvm::raw_ostream & error(Stream &strm)
static const char * GetName(DWARFDeclContext::Entry entry)
Returns the name of entry if it has one, or the appropriate "anonymous {namespace,...
static constexpr OptionEnumValueElement g_kaslr_kernel_scan_enum_values[]
@ eKASLRScanLowgloAddresses
@ eKASLRScanExhaustiveScan
#define DEBUG_PRINTF(fmt,...)
static bool is_kernel(Module *module)
static DynamicLoaderDarwinKernelProperties & GetGlobalProperties()
#define LLDB_LOG(log,...)
The LLDB_LOG* macros defined below are the way to emit log messages.
Definition: Log.h:359
#define LLDB_LOGF(log,...)
Definition: Log.h:366
#define LLDB_PLUGIN_DEFINE(PluginName)
Definition: PluginManager.h:31
~DynamicLoaderDarwinKernelProperties() override=default
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)
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)
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()
OSKextLoadedKextSummaryHeader m_kext_summary_header
void PrivateInitialize(lldb_private::Process *process)
DynamicLoaderDarwinKernel(lldb_private::Process *process, lldb::addr_t kernel_addr)
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)
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
lldb::addr_t GetLoadAddress(Target *target) const
Get the load address.
Definition: Address.cpp:313
void Clear()
Clear the object's state.
Definition: Address.h:181
bool Slide(int64_t offset)
Definition: Address.h:459
lldb::addr_t GetFileAddress() const
Get the file address.
Definition: Address.cpp:293
bool IsValid() const
Check if the object state is valid.
Definition: Address.h:355
static lldb::addr_t AddressableBitToMask(uint32_t addressable_bits)
An architecture specification class.
Definition: ArchSpec.h:31
uint32_t GetAddressByteSize() const
Returns the size in bytes of an address of the current architecture.
Definition: ArchSpec.cpp:691
llvm::Triple & GetTriple()
Architecture triple accessor.
Definition: ArchSpec.h:450
bool IsCompatibleMatch(const ArchSpec &rhs) const
Shorthand for IsMatch(rhs, CompatibleMatch).
Definition: ArchSpec.h:502
General Outline: A breakpoint has four main parts, a filter, a resolver, the list of breakpoint locat...
Definition: Breakpoint.h:81
void SetCallback(BreakpointHitCallback callback, void *baton, bool is_synchronous=false)
Set the callback action invoked when the breakpoint is hit.
Definition: Breakpoint.cpp:408
A uniqued constant string class.
Definition: ConstString.h:40
const char * AsCString(const char *value_if_empty=nullptr) const
Get the string value as a C string.
Definition: ConstString.h:188
llvm::StringRef GetStringRef() const
Get the string value as a llvm::StringRef.
Definition: ConstString.h:197
A subclass of DataBuffer that stores a data buffer on the heap.
lldb::offset_t GetByteSize() const override
Get the number of bytes in the data buffer.
An data extractor class.
Definition: DataExtractor.h:48
uint64_t GetU64(lldb::offset_t *offset_ptr) const
Extract a uint64_t value from *offset_ptr.
bool ValidOffsetForDataOfSize(lldb::offset_t offset, lldb::offset_t length) const
Test the availability of length bytes of data from offset.
const void * GetData(lldb::offset_t *offset_ptr, lldb::offset_t length) const
Extract length bytes from *offset_ptr.
uint32_t GetU32(lldb::offset_t *offset_ptr) const
Extract a uint32_t value from *offset_ptr.
A class to manage flag bits.
Definition: Debugger.h:80
StreamFile & GetOutputStream()
Definition: Debugger.h:146
StreamFile & GetErrorStream()
Definition: Debugger.h:148
PlatformList & GetPlatformList()
Definition: Debugger.h:200
A plug-in interface definition class for dynamic loaders.
Definition: DynamicLoader.h:52
void LoadOperatingSystemPlugin(bool flush)
Process * m_process
The process that this dynamic loader plug-in is tracking.
bool GetStopWhenImagesChange() const
Get whether the process should stop when images change.
A file collection class.
Definition: FileSpecList.h:85
void Append(const FileSpec &file)
Append a FileSpec object to the list.
A file utility class.
Definition: FileSpec.h:56
static FileSystem & Instance()
void PutCString(const char *cstr)
Definition: Log.cpp:135
A collection class for Module objects.
Definition: ModuleList.h:103
bool AppendIfNeeded(const lldb::ModuleSP &new_module, bool notify=true)
Append a module to the module list, if it is not already there.
Definition: ModuleList.cpp:280
lldb::ModuleSP FindModule(const Module *module_ptr) const
Definition: ModuleList.cpp:552
bool Remove(const lldb::ModuleSP &module_sp, bool notify=true)
Remove a module from the module list.
Definition: ModuleList.cpp:334
void Append(const lldb::ModuleSP &module_sp, bool notify=true)
Append a module to the module list.
Definition: ModuleList.cpp:247
ModuleIterable Modules() const
Definition: ModuleList.h:527
FileSpec & GetFileSpec()
Definition: ModuleSpec.h:53
ArchSpec & GetArchitecture()
Definition: ModuleSpec.h:89
A class that describes an executable image and its associated object and symbol files.
Definition: Module.h:88
const lldb_private::UUID & GetUUID()
Get a reference to the UUID value contained in this object.
Definition: Module.cpp:340
virtual ObjectFile * GetObjectFile()
Get the object file representation for the current architecture.
Definition: Module.cpp:1184
A plug-in interface definition class for object file parsers.
Definition: ObjectFile.h:44
@ eTypeExecutable
A normal executable.
Definition: ObjectFile.h:53
virtual SectionList * GetSectionList(bool update_module_section_list=true)
Gets the section list for the currently selected architecture (and object for archives).
Definition: ObjectFile.cpp:590
virtual lldb_private::Address GetBaseAddress()
Returns base address of this object file.
Definition: ObjectFile.h:479
static llvm::StringRef GetPluginNameStatic()
lldb::PlatformSP Create(llvm::StringRef name)
Definition: Platform.cpp:2285
static bool DownloadObjectAndSymbolFile(ModuleSpec &module_spec, Status &error, bool force_lookup=true, bool copy_executable=true)
static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, ABICreateInstance create_callback)
static lldb::OptionValuePropertiesSP GetSettingForDynamicLoaderPlugin(Debugger &debugger, llvm::StringRef setting_name)
static bool CreateSettingForDynamicLoaderPlugin(Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, llvm::StringRef description, bool is_global_property)
static bool UnregisterPlugin(ABICreateInstance create_callback)
A plug-in interface definition class for debugging a process.
Definition: Process.h:341
ThreadList & GetThreadList()
Definition: Process.h:2213
size_t ReadMemoryFromInferior(lldb::addr_t vm_addr, void *buf, size_t size, Status &error)
Read of memory from a process.
Definition: Process.cpp:2051
virtual size_t ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size, Status &error)
Read of memory from a process.
Definition: Process.cpp:1939
lldb::ByteOrder GetByteOrder() const
Definition: Process.cpp:3400
void SetCodeAddressMask(lldb::addr_t code_address_mask)
Definition: Process.cpp:5715
lldb::StateType GetState()
Get accessor for the current process state.
Definition: Process.cpp:1301
void SetDataAddressMask(lldb::addr_t data_address_mask)
Definition: Process.cpp:5721
virtual lldb::addr_t GetImageInfoAddress()
Get the image information address for the current process.
Definition: Process.cpp:1495
void SetCanRunCode(bool can_run_code)
Sets whether executing code in this process is possible.
Definition: Process.cpp:2346
Status ClearBreakpointSiteByID(lldb::user_id_t break_id)
Definition: Process.cpp:1592
virtual bool IsAlive()
Check if a process is still alive.
Definition: Process.cpp:1093
uint32_t GetAddressByteSize() const
Definition: Process.cpp:3404
uint32_t GetStopID() const
Definition: Process.h:1476
lldb::addr_t GetDataAddressMask()
Definition: Process.cpp:5690
lldb::addr_t GetCodeAddressMask()
Get the current address mask in the Process.
Definition: Process.cpp:5683
lldb::ModuleSP ReadModuleFromMemory(const FileSpec &file_spec, lldb::addr_t header_addr, size_t size_to_read=512)
Definition: Process.cpp:2388
Target & GetTarget()
Get the target object pointer for this module.
Definition: Process.h:1277
lldb::OptionValuePropertiesSP m_collection_sp
lldb::SectionSP FindSectionByName(ConstString section_dstr) const
Definition: Section.cpp:552
size_t GetSize() const
Definition: Section.h:75
lldb::SectionSP GetSectionAtIndex(size_t idx) const
Definition: Section.cpp:544
lldb::addr_t GetFileAddress() const
Definition: Section.cpp:193
An error handling class.
Definition: Status.h:44
bool Fail() const
Test for error condition.
Definition: Status.cpp:180
const char * AsCString(const char *default_error_str="unknown error") const
Get the error string associated with the current error.
Definition: Status.cpp:129
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
lldb::break_id_t GetID() const
Definition: Stoppoint.cpp:22
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
size_t Printf(const char *format,...) __attribute__((format(printf
Output printf formatted output to the stream.
Definition: Stream.cpp:134
virtual void Flush()=0
Flush the stream.
Address GetAddress() const
Definition: Symbol.h:88
FileSpecList GetExecutableSearchPaths()
Definition: Target.cpp:4476
void ModulesDidLoad(ModuleList &module_list)
Definition: Target.cpp:1690
Module * GetExecutableModulePointer()
Definition: Target.cpp:1436
Debugger & GetDebugger()
Definition: Target.h:1064
lldb::ModuleSP GetOrCreateModule(const ModuleSpec &module_spec, bool notify, Status *error_ptr=nullptr)
Find a binary on the system and return its Module, or return an existing Module that is already in th...
Definition: Target.cpp:2158
bool ReadPointerFromMemory(const Address &addr, Status &error, Address &pointer_addr, bool force_live_memory=false)
Definition: Target.cpp:2128
size_t ReadMemory(const Address &addr, void *dst, size_t dst_len, Status &error, bool force_live_memory=false, lldb::addr_t *load_addr_ptr=nullptr)
Definition: Target.cpp:1828
bool SetArchitecture(const ArchSpec &arch_spec, bool set_platform=false, bool merge=true)
Set the architecture for this target.
Definition: Target.cpp:1538
lldb::ModuleSP GetExecutableModule()
Gets the module for the main executable.
Definition: Target.cpp:1422
void ModulesDidUnload(ModuleList &module_list, bool delete_locations)
Definition: Target.cpp:1724
lldb::PlatformSP GetPlatform()
Definition: Target.h:1442
lldb::BreakpointSP CreateBreakpoint(const FileSpecList *containingModules, const FileSpec &file, uint32_t line_no, uint32_t column, lldb::addr_t offset, LazyBool check_inlines, LazyBool skip_prologue, bool internal, bool request_hardware, LazyBool move_to_nearest_code)
Definition: Target.cpp:395
const ModuleList & GetImages() const
Get accessor for the images for this process.
Definition: Target.h:981
const ArchSpec & GetArchitecture() const
Definition: Target.h:1023
uint64_t ReadUnsignedIntegerFromMemory(const Address &addr, size_t integer_byte_size, uint64_t fail_value, Status &error, bool force_live_memory=false)
Definition: Target.cpp:2117
void SetPlatform(const lldb::PlatformSP &platform_sp)
Definition: Target.h:1444
bool SetSectionLoadAddress(const lldb::SectionSP &section, lldb::addr_t load_addr, bool warn_multiple=false)
Definition: Target.cpp:3114
lldb::ThreadSP GetSelectedThread()
Definition: ThreadList.cpp:684
bool IsValid() const
Definition: UUID.h:69
uint8_t * GetBytes()
Get a pointer to the data.
Definition: DataBuffer.h:108
#define UINT64_MAX
Definition: lldb-defines.h:23
#define LLDB_INVALID_BREAK_ID
Definition: lldb-defines.h:37
#define LLDB_BREAK_ID_IS_VALID(bid)
Definition: lldb-defines.h:39
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:82
#define UINT32_MAX
Definition: lldb-defines.h:19
lldb::ByteOrder InlHostByteOrder()
Definition: Endian.h:25
A class that represents a running process on the host machine.
Log * GetLog(Cat mask)
Retrieve the Log object for the channel associated with the given log enum.
Definition: Log.h:331
const char * StateAsCString(lldb::StateType state)
Converts a StateType to a C string.
Definition: State.cpp:14
Definition: SBAddress.h:15
std::shared_ptr< lldb_private::ThreadPlan > ThreadPlanSP
Definition: lldb-forward.h:444
std::shared_ptr< lldb_private::Thread > ThreadSP
Definition: lldb-forward.h:441
std::shared_ptr< lldb_private::Platform > PlatformSP
Definition: lldb-forward.h:383
uint64_t offset_t
Definition: lldb-types.h:85
StateType
Process and Thread States.
@ eStateUnloaded
Process is object is valid, but not currently loaded.
@ eStateConnected
Process is connected to remote debug services, but not launched or attached to anything yet.
@ eStateDetached
Process has been detached and can't be examined.
@ eStateStopped
Process or thread is stopped and can be examined.
@ eStateSuspended
Process or thread is in a suspended state as far as the debugger is concerned while other processes o...
@ eStateRunning
Process or thread is running and can't be examined.
@ eStateLaunching
Process is in the process of launching.
@ eStateAttaching
Process is currently trying to attach.
@ eStateExited
Process has exited and can't be examined.
@ eStateStepping
Process or thread is in the process of stepping and can not be examined.
@ eStateCrashed
Process or thread has crashed and can be examined.
@ eLanguageTypeUnknown
Unknown or invalid language value.
ByteOrder
Byte ordering definitions.
@ eByteOrderInvalid
@ eByteOrderLittle
uint64_t user_id_t
Definition: lldb-types.h:82
std::shared_ptr< lldb_private::Section > SectionSP
Definition: lldb-forward.h:409
uint64_t addr_t
Definition: lldb-types.h:80
std::shared_ptr< lldb_private::Module > ModuleSP
Definition: lldb-forward.h:368