Go to the documentation of this file.
41 #include "llvm/Support/Threading.h"
43 #define USEC_PER_SEC 1000000
58 #define LLDB_PROPERTIES_processkdp
59 #include "ProcessKDPProperties.inc"
62 #define LLDB_PROPERTIES_processkdp
63 #include "ProcessKDPPropertiesEnum.inc"
73 m_collection_sp = std::make_shared<OptionValueProperties>(GetSettingName());
74 m_collection_sp->Initialize(g_processkdp_properties);
77 ~PluginProperties()
override =
default;
79 uint64_t GetPacketTimeout() {
80 const uint32_t idx = ePropertyKDPPacketTimeout;
81 return m_collection_sp->GetPropertyAtIndexAsUInt64(
82 NULL, idx, g_processkdp_properties[idx].default_uint_value);
86 static PluginProperties &GetGlobalPluginProperties() {
87 static PluginProperties g_settings;
96 return "KDP Remote protocol based debugging plug-in for darwin kernel "
105 ListenerSP listener_sp,
108 lldb::ProcessSP process_sp;
109 if (crash_file_path == NULL)
110 process_sp = std::make_shared<ProcessKDP>(target_sp, listener_sp);
115 if (plugin_specified_by_name)
119 Module *exe_module = target_sp->GetExecutableModulePointer();
122 switch (triple_ref.getOS()) {
123 case llvm::Triple::Darwin:
125 case llvm::Triple::MacOSX:
126 case llvm::Triple::IOS:
127 case llvm::Triple::TvOS:
128 case llvm::Triple::WatchOS:
129 if (triple_ref.getVendor() == llvm::Triple::Apple) {
131 if (exe_objfile->
GetType() == ObjectFile::eTypeExecutable &&
132 exe_objfile->
GetStrata() == ObjectFile::eStrataKernel)
146 :
Process(target_sp, listener_sp),
147 m_comm(
"lldb.process.kdp-remote.communication"),
148 m_async_broadcaster(NULL,
"lldb.process.kdp-remote.async-broadcaster"),
150 m_kernel_thread_wp() {
152 "async thread should exit");
154 "async thread continue");
155 const uint64_t timeout_seconds =
156 GetGlobalPluginProperties().GetPacketTimeout();
157 if (timeout_seconds > 0)
173 error.SetErrorString(
"launching not supported in kdp-remote plug-in");
179 error.SetErrorString(
180 "attaching to a by process ID not supported in kdp-remote plug-in");
185 bool wait_for_launch) {
187 error.SetErrorString(
188 "attaching to a by process name not supported in kdp-remote plug-in");
198 arch.
GetTriple().setVendor(llvm::Triple::UnknownVendor);
199 arch.
GetTriple().setVendorName(llvm::StringRef());
214 if (remote_url.empty()) {
215 error.SetErrorStringWithFormat(
"empty connection URL");
219 std::unique_ptr<ConnectionFileDescriptor> conn_up(
225 for (
uint32_t retry_count = 0; retry_count < max_retry_count;
233 if (conn_up->IsConnected()) {
235 static_cast<const TCPSocket &
>(*conn_up->GetReadObject());
238 if (reply_port != 0) {
243 "Greetings from LLDB...")) {
274 module_spec.
GetUUID() = kernel_uuid;
278 FileSpecList search_paths =
279 Target::GetDefaultDebugFileSearchPaths();
281 Symbols::LocateExecutableSymbolFile(module_spec,
285 Symbols::LocateExecutableObjectFile(module_spec);
286 if (FileSystem::Instance().Exists(
295 Symbols::DownloadObjectAndSymbolFile(module_spec, symbl_error,
299 if (FileSystem::Instance().Exists(module_spec.
GetFileSpec())) {
300 ModuleSP module_sp(
new Module(module_spec));
301 if (module_sp.get() && module_sp->GetObjectFile()) {
307 if (exe_module_sp.get() != module_sp.get())
329 async_strm_sp->Printf(
"Version: %s\n", cstr);
330 async_strm_sp->Flush();
340 error.SetErrorString(
"KDP_REATTACH failed");
343 error.SetErrorString(
"KDP_REATTACH failed");
346 error.SetErrorString(
"invalid reply port from UDP connection");
350 error.SetErrorStringWithFormat(
"failed to connect to '%s'",
351 remote_url.str().c_str());
363 error.SetErrorString(
"launching not supported in kdp-remote plug-in");
371 error.SetErrorString(
372 "attach to process by ID is not supported in kdp remote debugging");
380 error.SetErrorString(
381 "attach to process by name is not supported in kdp remote debugging");
386 Process::DidAttach(process_arch);
389 LLDB_LOGF(log,
"ProcessKDP::DidAttach()");
417 if (kernel_thread_sp) {
419 kernel_thread_sp->GetTemporaryResumeState();
421 LLDB_LOGF(log,
"ProcessKDP::DoResume() thread_resume_state = %s",
423 switch (thread_resume_state) {
427 LLDB_LOGF(log,
"ProcessKDP::DoResume() = suspended???");
431 lldb::RegisterContextSP reg_ctx_sp(
432 kernel_thread_sp->GetRegisterContext());
437 "ProcessKDP::DoResume () reg_ctx_sp->HardwareSingleStep (true);");
438 reg_ctx_sp->HardwareSingleStep(
true);
441 error.SetErrorStringWithFormat(
442 "KDP thread 0x%llx has no register context",
443 kernel_thread_sp->GetID());
448 lldb::RegisterContextSP reg_ctx_sp(
449 kernel_thread_sp->GetRegisterContext());
452 LLDB_LOGF(log,
"ProcessKDP::DoResume () reg_ctx_sp->HardwareSingleStep "
454 reg_ctx_sp->HardwareSingleStep(
false);
457 error.SetErrorStringWithFormat(
458 "KDP thread 0x%llx has no register context",
459 kernel_thread_sp->GetID());
465 llvm_unreachable(
"invalid thread resume state");
470 LLDB_LOGF(log,
"ProcessKDP::DoResume () sending resume");
476 error.SetErrorString(
"KDP resume failed");
478 error.SetErrorString(
"kernel thread is suspended");
490 thread_sp = std::make_shared<ThreadKDP>(*
this,
g_kernel_tid);
510 return new_thread_list.
GetSize(
false) > 0;
529 error.SetErrorString(
"KDP cannot interrupt a running kernel");
538 LLDB_LOGF(log,
"ProcessKDP::DoDetach(keep_stopped = %i)", keep_stopped);
551 "ProcessKDP::DoDetach() detach packet sent successfully");
554 "ProcessKDP::DoDetach() connection channel shutdown failed");
571 bool keep_stopped =
false;
584 uint8_t *data_buffer = (uint8_t *)buf;
586 const size_t max_read_size = 512;
587 size_t total_bytes_read = 0;
590 while (total_bytes_read < size) {
591 size_t bytes_to_read_this_request = size - total_bytes_read;
592 if (bytes_to_read_this_request > max_read_size) {
593 bytes_to_read_this_request = max_read_size;
596 addr + total_bytes_read, data_buffer + total_bytes_read,
597 bytes_to_read_this_request,
error);
598 total_bytes_read += bytes_read;
599 if (
error.Fail() || bytes_read == 0) {
600 return total_bytes_read;
604 return total_bytes_read;
606 error.SetErrorString(
"not connected");
614 error.SetErrorString(
"not connected");
620 error.SetErrorString(
621 "memory allocation not supported in kdp remote debugging");
627 error.SetErrorString(
628 "memory deallocation not supported in kdp remote debugging");
634 return Status(
"Hardware breakpoints are not supported.");
641 bp_site->
SetType(BreakpointSite::eExternal);
643 error.SetErrorString(
"KDP set breakpoint failed");
656 if (bp_type == BreakpointSite::eExternal) {
664 error.SetErrorString(
"KDP remove breakpoint failed");
677 error.SetErrorString(
678 "watchpoints are not supported in kdp remote debugging");
684 error.SetErrorString(
685 "watchpoints are not supported in kdp remote debugging");
693 error.SetErrorString(
694 "sending signals is not supported in kdp remote debugging");
699 static llvm::once_flag g_once_flag;
701 llvm::call_once(g_once_flag, []() {
706 ProcessKDPLog::Initialize();
711 if (!PluginManager::GetSettingForProcessPlugin(
712 debugger, PluginProperties::GetSettingName())) {
713 const bool is_global_setting =
true;
714 PluginManager::CreateSettingForProcessPlugin(
716 ConstString(
"Properties for the kdp-remote process plug-in."),
724 LLDB_LOGF(log,
"ProcessKDP::StartAsyncThread ()");
729 llvm::Expected<HostThread> async_thread = ThreadLauncher::LaunchThread(
730 "<lldb.process.kdp-remote.async>", [
this] {
return AsyncThread(); });
733 "failed to launch host thread: {}");
743 LLDB_LOGF(log,
"ProcessKDP::StopAsyncThread ()");
757 "ProcessKDP::AsyncThread(pid = %" PRIu64
") thread starting...",
760 ListenerSP listener_sp(Listener::MakeListener(
"ProcessKDP::AsyncThread"));
765 if (listener_sp->StartListeningForEvents(
770 "ProcessKDP::AsyncThread (pid = %" PRIu64
771 ") listener.WaitForEvent (NULL, event_sp)...",
773 if (listener_sp->GetEvent(event_sp, llvm::None)) {
774 uint32_t event_type = event_sp->GetType();
776 "ProcessKDP::AsyncThread (pid = %" PRIu64
777 ") Got an event of type: %d...",
783 bool is_running =
false;
786 switch (event_type) {
793 lldb::RegisterContextSP reg_ctx_sp(
794 thread_sp->GetRegisterContext());
796 reg_ctx_sp->InvalidateAllRegisters();
797 static_cast<ThreadKDP *
>(thread_sp.get())
798 ->SetStopInfoFrom_KDP_EXCEPTION(exc_reply_packet);
808 if (listener_sp->GetEvent(event_sp,
809 std::chrono::microseconds(0))) {
811 event_type = event_sp->GetType();
818 "ProcessKDP::AsyncThread (pid = %" PRIu64
819 ") got eBroadcastBitAsyncThreadShouldExit...",
827 "ProcessKDP::AsyncThread (pid = %" PRIu64
828 ") got unknown event 0x%8.8x",
834 }
while (is_running);
837 "ProcessKDP::AsyncThread (pid = %" PRIu64
838 ") listener.WaitForEvent (NULL, event_sp) => false",
845 LLDB_LOGF(log,
"ProcessKDP::AsyncThread(pid = %" PRIu64
") thread exiting...",
863 "Send a custom packet through the KDP protocol by "
864 "specifying the command byte and the packet "
865 "payload data. A packet will be sent with a "
866 "correct header and payload, and the raw result "
867 "bytes will be displayed as a string value. ",
871 "Specify the command byte to use when sending the KDP "
875 "Specify packet payload bytes as a hex ASCII string with "
876 "no spaces or hex prefixes.",
890 "the --command option must be set to a valid command byte");
892 const uint64_t command_byte =
894 if (command_byte > 0 && command_byte <= UINT8_MAX) {
901 std::vector<uint8_t> payload_bytes;
902 const char *ascii_hex_bytes_cstr =
904 if (ascii_hex_bytes_cstr && ascii_hex_bytes_cstr[0]) {
906 const size_t ascii_hex_bytes_cstr_len =
908 if (ascii_hex_bytes_cstr_len & 1) {
910 "even number of ASCII hex "
912 ascii_hex_bytes_cstr);
915 payload_bytes.resize(ascii_hex_bytes_cstr_len / 2);
916 if (extractor.
GetHexBytes(payload_bytes,
'\xdd') !=
917 payload_bytes.size()) {
919 "ASCII hex characters (no "
920 "spaces or hex prefixes): '%s'",
921 ascii_hex_bytes_cstr);
929 payload_bytes.empty() ? NULL : payload_bytes.data(),
930 payload_bytes.size(), reply,
error);
932 if (
error.Success()) {
942 const char *error_cstr =
error.AsCString();
943 if (error_cstr && error_cstr[0])
952 "to send KDP packets, state is %s",
960 ", valid values are 1 - 255",
977 "Commands that deal with KDP remote packets.",
991 interpreter,
"process plugin",
992 "Commands for operating on a ProcessKDP process.",
993 "process plugin <subcommand> [<subcommand-options>]") {
1003 m_command_sp = std::make_shared<CommandObjectMultiwordProcessKDP>(
1004 GetTarget().GetDebugger().GetCommandInterpreter());
bool CanDebug(lldb::TargetSP target_sp, bool plugin_specified_by_name) override
Check if a plug-in instance can debug the file in module.
CommunicationKDP m_comm
Broadcaster event bits definitions.
virtual lldb::addr_t GetLoadAddress() const
virtual ObjectFile * GetObjectFile()
Get the object file representation for the current architecture.
virtual lldb::OptionValuePropertiesSP GetValueProperties() const
ThreadList m_thread_list
The threads for this process as the user will see them.
bool OptionWasSet() const
OptionValueUInt64 & GetOptionValue()
#define LLDB_INVALID_PROCESS_ID
OptionGroupOptions m_option_group
Process * GetProcessPtr() const
Returns a pointer to the process object.
void DidAttach(lldb_private::ArchSpec &process_arch) override
Called after attaching a process.
lldb::addr_t GetImageInfoAddress() override
Get the image information address for the current process.
bool DoExecute(Args &command, CommandReturnObject &result) override
lldb_private::Status DoResume() override
Resumes all of a process's threads as configured using the Thread run control functions.
bool LocalBreakpointsAreSupported()
lldb_private::Status WillResume() override
Called before resuming to a process.
virtual Status EnableSoftwareBreakpoint(BreakpointSite *bp_site)
#define LLDB_LOGF(log,...)
bool RemoteIsDarwinKernel()
lldb_private::CommandObject * GetPluginCommandObject() override
Return a multi-word command object that can be used to expose plug-in specific commands.
void MergeFrom(const ArchSpec &other)
Merges fields from another ArchSpec into this ArchSpec.
lldb::ModuleSP GetExecutableModule()
Gets the module for the main executable.
void SetEventName(uint32_t event_mask, const char *name)
Set the name for an event bit.
lldb_private::Broadcaster m_async_broadcaster
ThreadList & GetThreadList()
Target & GetTarget()
Get the target object pointer for this module.
const char * StateAsCString(lldb::StateType state)
Converts a StateType to a C string.
lldb_private::Status DoAttachToProcessWithID(lldb::pid_t pid, const lldb_private::ProcessAttachInfo &attach_info) override
Attach to an existing process using a process ID.
BreakpointSite::Type GetType() const
lldb_private::Status DisableBreakpointSite(lldb_private::BreakpointSite *bp_site) override
~CommandObjectProcessKDPPacket() override=default
void RefreshStateAfterStop()
lldb_private::Status DoDestroy() override
uint64_t GetUInt64Value(uint64_t fail_value, bool *success_ptr)
Options * GetOptions() override
void SetID(lldb::pid_t new_pid)
Sets the stored pid.
llvm::Triple & GetTriple()
Architecture triple accessor.
lldb_private::UUID GetUUID()
void SetPrivateState(lldb::StateType state)
#define LLDB_LOGV(log,...)
LLDB_PLUGIN_DEFINE_ADV(ObjectContainerUniversalMachO, ObjectContainerMachOArchive) void ObjectContainerUniversalMachO
llvm::StringRef GetString() const
FileSpec & GetSymbolFileSpec()
lldb::StateType GetState()
Get accessor for the current process state.
bool DoUpdateThreadList(lldb_private::ThreadList &old_thread_list, lldb_private::ThreadList &new_thread_list) override
Update the thread list following process plug-in's specific logic.
static llvm::StringRef GetPluginNameStatic()
uint32_t SendRequestReadMemory(lldb::addr_t addr, void *dst, uint32_t dst_size, lldb_private::Status &error)
@ eStateStopped
Process or thread is stopped and can be examined.
void SetConnection(std::unique_ptr< Connection > connection)
Sets the connection that it to be used by this class.
static llvm::raw_ostream & error(Stream &strm)
OptionGroupString m_packet_data
bool GetHostArchitecture(lldb_private::ArchSpec &arch)
bool StateIsStoppedState(lldb::StateType state, bool must_exist)
Check if a state represents a state where the process or thread is stopped.
CommandObjectMultiwordProcessKDP(CommandInterpreter &interpreter)
~CommandObjectProcessKDPPacketSend() override=default
virtual Status DisableSoftwareBreakpoint(BreakpointSite *bp_site)
bool LoadSubCommand(llvm::StringRef cmd_name, const lldb::CommandObjectSP &command_obj) override
void SetStatus(lldb::ReturnStatus status)
bool SendRequestDisconnect()
lldb::StreamSP GetAsyncOutputStream()
bool HardwareRequired() const
lldb::DynamicLoaderUP m_dyld_up
void SetEnabled(bool enabled)
Sets whether the current breakpoint site is enabled or not.
size_t DoReadMemory(lldb::addr_t addr, void *buf, size_t size, lldb_private::Status &error) override
Actually do the reading of memory from a process.
virtual void Finalize()
This object is about to be destroyed, do any necessary cleanup.
lldb::addr_t m_kernel_load_addr
void UpdateThreadListIfNeeded()
@ eStateDetached
Process has been detached and can't be examined.
lldb_private::HostThread m_async_thread
bool SetArchitecture(const ArchSpec &arch_spec, bool set_platform=false)
Set the architecture for this target.
lldb_private::Status WillLaunch(lldb_private::Module *module) override
Called before launching to a process.
CommandInterpreter & m_interpreter
lldb::ThreadSP FindThreadByProtocolID(lldb::tid_t tid, bool can_update=true)
const char * GetCurrentValue() const
CommandObjectProcessKDPPacket(CommandInterpreter &interpreter)
static const lldb::tid_t g_kernel_tid
lldb_private::Status DoLaunch(lldb_private::Module *exe_module, lldb_private::ProcessLaunchInfo &launch_info) override
Launch a new process.
static void DebuggerInitialize(lldb_private::Debugger &debugger)
void ResumePrivateStateThread()
lldb_private::Status DoDeallocateMemory(lldb::addr_t ptr) override
Actually deallocate memory in the process.
void SetExecutableModule(lldb::ModuleSP &module_sp, LoadDependentFiles load_dependent_files=eLoadDependentsDefault)
Set the main executable module.
bool SendRawRequest(uint8_t command_byte, const void *src, uint32_t src_len, lldb_private::DataExtractor &reply, lldb_private::Status &error)
lldb::addr_t DoAllocateMemory(size_t size, uint32_t permissions, lldb_private::Status &error) override
Actually allocate memory in the process.
bool SendRequestBreakpoint(bool set, lldb::addr_t addr)
CommandObjectProcessKDPPacketSend(CommandInterpreter &interpreter)
@ eStateStepping
Process or thread is in the process of stepping and can not be examined.
@ eBroadcastBitAsyncContinue
bool SetArchitecture(ArchitectureType arch_type, uint32_t cpu, uint32_t sub, uint32_t os=0)
Change the architecture object type, CPU type and OS type.
@ eStateSuspended
Process or thread is in a suspended state as far as the debugger is concerned while other processes o...
void BroadcastEvent(lldb::EventSP &event_sp)
Broadcast an event which has no associated data.
lldb::ConnectionStatus Disconnect(Status *error_ptr=nullptr)
Disconnect the communications connection if one is currently connected.
const ArchSpec & GetArchitecture() const
Status Join(lldb::thread_result_t *result)
size_t PutBytesAsRawHex8(const void *src, size_t src_len, lldb::ByteOrder src_byte_order=lldb::eByteOrderInvalid, lldb::ByteOrder dst_byte_order=lldb::eByteOrderInvalid)
lldb_private::Status DoAttachToProcessWithName(const char *process_name, const lldb_private::ProcessAttachInfo &attach_info) override
Attach to an existing process using a partial process name.
lldb_private::Status DoHalt(bool &caused_stop) override
Halts a running process.
bool SendRequestConnect(uint16_t reply_port, uint16_t exc_port, const char *greeting)
lldb_private::DynamicLoader * GetDynamicLoader() override
Get the dynamic loader plug-in for this process.
OptionGroupUInt64 m_command_byte
lldb_private::Status DoDetach(bool keep_stopped) override
Detaches from a running or stopped process.
@ eReturnStatusSuccessFinishResult
lldb::ThreadWP m_kernel_thread_wp
void RefreshStateAfterStop() override
Currently called as part of ShouldStop.
static lldb::ProcessSP CreateInstance(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp, const lldb_private::FileSpec *crash_file_path, bool can_connect)
lldb::ByteOrder InlHostByteOrder()
lldb_private::Status DoConnectRemote(llvm::StringRef remote_url) override
Attach to a remote system via a URL.
lldb_private::Status DisableWatchpoint(lldb_private::Watchpoint *wp, bool notify=true) override
lldb::ThreadSP GetKernelThread()
uint32_t GetSize(bool can_update=true)
bool IsAlive() override
Check if a process is still alive.
bool IsConnected() const
Check if the connection is valid.
bool IsEnabled() const
Tells whether the current breakpoint site is enabled or not.
static llvm::StringRef GetPluginNameStatic()
#define LLDB_INVALID_ADDRESS
ArchSpec & GetArchitecture()
lldb::pid_t GetID() const
Returns the pid of the process or LLDB_INVALID_PROCESS_ID if there is no known pid.
ProcessKDP(lldb::TargetSP target_sp, lldb::ListenerSP listener)
lldb_private::Status EnableWatchpoint(lldb_private::Watchpoint *wp, bool notify=true) override
lldb_private::Status WillAttachToProcessWithID(lldb::pid_t pid) override
Called before attaching to a process.
void AppendErrorWithFormat(const char *format,...) __attribute__((format(printf
@ eConnectionStatusSuccess
Success.
llvm::StringRef m_dyld_plugin_name
lldb_private::Status WillAttachToProcessWithName(const char *process_name, bool wait_for_launch) override
Called before attaching to a process.
void Append(OptionGroup *group)
Append options from a OptionGroup class.
A class that represents a running process on the host machine.
bool m_destroy_in_process
lldb_private::Status EnableBreakpointSite(lldb_private::BreakpointSite *bp_site) override
size_t WaitForPacketWithTimeoutMicroSeconds(lldb_private::DataExtractor &response, uint32_t usec)
lldb_private::Status DoSignal(int signal) override
Sends a process a UNIX signal signal.
ExecutionContext GetExecutionContext() const
std::chrono::seconds SetPacketTimeout(std::chrono::seconds packet_timeout)
void AddThread(const lldb::ThreadSP &thread_sp)
StateType
Process and Thread States.
bool SendRequestReattach(uint16_t reply_port)
const ArchSpec & GetArchitecture() const
Get const accessor for the module architecture.
void SetCanJIT(bool can_jit)
Sets whether executing JIT-compiled code in this process is possible.
uint32_t SendRequestWriteMemory(lldb::addr_t addr, const void *src, uint32_t src_len, lldb_private::Status &error)
void Clear()
Clears the object state.
Log * GetLog(Cat mask)
Retrieve the Log object for the channel associated with the given log enum.
void SetType(BreakpointSite::Type type)
void void AppendError(llvm::StringRef in_string)
uint16_t GetLocalPortNumber() const
const char * GetKernelVersion()
size_t GetArgumentCount() const
Gets the number of arguments left in this command object.
~CommandObjectMultiwordProcessKDP() override=default
@ eBroadcastBitAsyncThreadShouldExit
static llvm::StringRef GetPluginDescriptionStatic()
@ eStateRunning
Process or thread is running and can't be examined.
lldb::addr_t GetLoadAddress()
#define LLDB_LOG_ERROR(log, error,...)
size_t DoWriteMemory(lldb::addr_t addr, const void *buf, size_t size, lldb_private::Status &error) override
Actually do the writing of memory to a process.
void AppendMessage(llvm::StringRef in_string)
lldb::CommandObjectSP m_command_sp
CommunicationKDP & GetCommunication()
OptionValueString & GetOptionValue()
void PutCString(const char *cstr)