[lldb] [gdb-remote server] Introduce new stop reasons for fork and vfork

[mgorny]

Summary

Introduce three new stop reasons for fork, vfork and vforkdone events.
This includes server support for serializing fork/vfork events into
gdb-remote protocol. The stop infos for the two base events take a pair
of PID and TID for the newly forked process.

[mgorny]

Add 'vforkdone' stop reason. Move overrideable actions to this patch.

[mgorny]

@labath, does this subset look better?

[mgorny]

For other readers: as discussed in D100191, I've stripped client part of this (except for trivial enumerations). The server part will be used in tests but the stop reasons won't be reported to regular clients as they don't report fork-events support.

[labath]

lldb/source/Plugins/Process/gdb-remote/GDBRemoteCommunicationServerLLGS.cpp

946–948

I just realized this is implicitly assuming the multiprocess extension is enabled/supported. That makes sense since forking always involves multiple processes, though maybe the server should check that the client actually reports it as supported.

[mgorny]

lldb/source/Plugins/Process/gdb-remote/GDBRemoteCommunicationServerLLGS.cpp

946–948

Makes sense. I'll add it to the extension patch since that's where we determine if fork/vfork is supported.

[mgorny]

Add an assert to make sure that process doesn't report fork/vfork stop reason without multiprocess support.

[mgorny]

Actually, add asserts for fork/vfork extensions too.

[labath]

In D100196#2713684, @mgorny wrote:

Add an assert to make sure that process doesn't report fork/vfork stop reason without multiprocess support.

I guess this is the reason for that..

What I meant here was to do a sanity check on the client extensions -- like if a client claims to support "vfork-events" but not "multiprocess", then its probably broken (though it's a question what we should actually do about that). In the server our gdb-remote class always (I hope) supports multiprocess, so there's no danger of inconsistency.

lldb/bindings/interface/SBThread.i

~SBThread();
     ======================== ===== =========================================
     eStopReasonNone          0
     eStopReasonTrace         0
     eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
     eStopReasonWatchpoint    1     watchpoint id
     eStopReasonSignal        1     unix signal number
     eStopReasonException     N     exception data
     eStopReasonExec          0
+    eStopReasonFork          1     pid of the child process
+    eStopReasonVFork         1     pid of the child process
+    eStopReasonVForkDone     0
     eStopReasonPlanComplete  0") GetStopReasonDataAtIndex;
     uint64_t
     GetStopReasonDataAtIndex(uint32_t idx);
 
     %feature("autodoc", "
     Collects a thread's stop reason extended information dictionary and prints it
     into the SBStream in a JSON format. The format of this JSON dictionary depends
     on the stop reason and is currently used only for instrumentation plugins.") GetStopReasonExtendedInfoAsJSON;

lldb/bindings/interface/SBThreadPlan.i

~SBThreadPlan ();
     ======================== ===== =========================================
     eStopReasonNone          0
     eStopReasonTrace         0
     eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
     eStopReasonWatchpoint    1     watchpoint id
     eStopReasonSignal        1     unix signal number
     eStopReasonException     N     exception data
     eStopReasonExec          0
+    eStopReasonFork          1     pid of the child process
+    eStopReasonVFork         1     pid of the child process
+    eStopReasonVForkDone     0
     eStopReasonPlanComplete  0") GetStopReasonDataAtIndex;
     uint64_t
     GetStopReasonDataAtIndex(uint32_t idx);
 
     SBThread
     GetThread () const;
 
     bool

lldb/docs/python_api_enums.rst

 .. py:data:: eStopReasonInvalid
 .. py:data:: eStopReasonNone
 .. py:data:: eStopReasonTrace
 .. py:data:: eStopReasonBreakpoint
 .. py:data:: eStopReasonWatchpoint
 .. py:data:: eStopReasonSignal
 .. py:data:: eStopReasonException
 .. py:data:: eStopReasonExec
+.. py:data:: eStopReasonFork
+.. py:data:: eStopReasonVFork
+.. py:data:: eStopReasonVForkDone
 .. py:data:: eStopReasonPlanComplete
 .. py:data:: eStopReasonThreadExiting
 .. py:data:: eStopReasonInstrumentation
 
 ReturnStatus
 ------------
 
 .. py:data:: eReturnStatusInvalid

lldb/examples/python/performance.py

def WaitForNextProcessEvent(self):
                             elif stop_reason == lldb.eStopReasonWatchpoint:
                                 select_thread = True
                                 if self.verbose:
                                     print("watchpoint id = %d" % (thread.GetStopReasonDataAtIndex(0)))
                             elif stop_reason == lldb.eStopReasonSignal:
                                 select_thread = True
                                 if self.verbose:
                                     print("signal %d" % (thread.GetStopReasonDataAtIndex(0)))
+                            elif stop_reason == lldb.eStopReasonFork:
+                                if self.verbose:
+                                    print("fork pid = %d" % (thread.GetStopReasonDataAtIndex(0)))
+                            elif stop_reason == lldb.eStopReasonVFork:
+                                if self.verbose:
+                                    print("vfork pid = %d" % (thread.GetStopReasonDataAtIndex(0)))
+                            elif stop_reason == lldb.eStopReasonVForkDone:
+                                if self.verbose:
+                                    print("vfork done")
 
                             if select_thread and not selected_thread:
                                 self.thread = thread
                                 selected_thread = self.process.SetSelectedThread(
                                     thread)
 
                             for action in self.user_actions:
                                 action.ThreadStopped(thread)

lldb/include/lldb/API/SBThread.h

public:
   /// ======================== ===== =========================================
   /// eStopReasonNone          0
   /// eStopReasonTrace         0
   /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
   /// eStopReasonWatchpoint    1     watchpoint id
   /// eStopReasonSignal        1     unix signal number
   /// eStopReasonException     N     exception data
   /// eStopReasonExec          0
+  /// eStopReasonFork          1     pid of the child process
+  /// eStopReasonVFork         1     pid of the child process
+  /// eStopReasonVForkDone     0
   /// eStopReasonPlanComplete  0
   uint64_t GetStopReasonDataAtIndex(uint32_t idx);
 
   bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream);
 
   SBThreadCollection
   GetStopReasonExtendedBacktraces(InstrumentationRuntimeType type);
 

lldb/include/lldb/API/SBThreadPlan.h

public:
   /// ======================== ===== =========================================
   /// eStopReasonNone          0
   /// eStopReasonTrace         0
   /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
   /// eStopReasonWatchpoint    1     watchpoint id
   /// eStopReasonSignal        1     unix signal number
   /// eStopReasonException     N     exception data
   /// eStopReasonExec          0
+  /// eStopReasonFork          1     pid of the child process
+  /// eStopReasonVFork         1     pid of the child process
+  /// eStopReasonVForkDone     0
   /// eStopReasonPlanComplete  0
   uint64_t GetStopReasonDataAtIndex(uint32_t idx);
 
   SBThread GetThread() const;
 
   const lldb::SBThreadPlan &operator=(const lldb::SBThreadPlan &rhs);
 
   bool GetDescription(lldb::SBStream &description) const;

lldb/include/lldb/Host/Debug.h

union {
     } signal;
 
     // eStopReasonException
     struct {
       uint64_t type;
       uint32_t data_count;
       lldb::addr_t data[8];
     } exception;
+
+    // eStopReasonFork / eStopReasonVFork
+    struct {
+      lldb::pid_t child_pid;
+      lldb::tid_t child_tid;
+    } fork;
   } details;
 };
 }
 
 #endif // LLDB_HOST_DEBUG_H

lldb/include/lldb/lldb-enumerations.h

enum StopReason {
   eStopReasonWatchpoint,
   eStopReasonSignal,
   eStopReasonException,
   eStopReasonExec, ///< Program was re-exec'ed
   eStopReasonPlanComplete,
   eStopReasonThreadExiting,
   eStopReasonInstrumentation,
   eStopReasonProcessorTrace,
+  eStopReasonFork,
+  eStopReasonVFork,
+  eStopReasonVForkDone,
 };
 
 /// Command Return Status Types.
 enum ReturnStatus {
   eReturnStatusInvalid,
   eReturnStatusSuccessFinishNoResult,
   eReturnStatusSuccessFinishResult,
   eReturnStatusSuccessContinuingNoResult,

lldb/packages/Python/lldbsuite/test/lldbutil.py

def stop_reason_to_str(enum):
     elif enum == lldb.eStopReasonTrace:
         return "trace"
     elif enum == lldb.eStopReasonBreakpoint:
         return "breakpoint"
     elif enum == lldb.eStopReasonWatchpoint:
         return "watchpoint"
     elif enum == lldb.eStopReasonExec:
         return "exec"
+    elif enum == lldb.eStopReasonFork:
+        return "fork"
+    elif enum == lldb.eStopReasonVFork:
+        return "vfork"
+    elif enum == lldb.eStopReasonVForkDone:
+        return "vforkdone"
     elif enum == lldb.eStopReasonSignal:
         return "signal"
     elif enum == lldb.eStopReasonException:
         return "exception"
     elif enum == lldb.eStopReasonPlanComplete:
         return "plancomplete"
     elif enum == lldb.eStopReasonThreadExiting:
         return "threadexiting"

lldb/source/API/SBThread.cpp

if (stop_locker.TryLock(&exe_ctx.GetProcessPtr()->GetRunLock())) {
         case eStopReasonInvalid:
         case eStopReasonNone:
         case eStopReasonTrace:
         case eStopReasonExec:
         case eStopReasonPlanComplete:
         case eStopReasonThreadExiting:
         case eStopReasonInstrumentation:
         case eStopReasonProcessorTrace:
+        case eStopReasonVForkDone:
           // There is no data for these stop reasons.
           return 0;
 
         case eStopReasonBreakpoint: {
           break_id_t site_id = stop_info_sp->GetValue();
           lldb::BreakpointSiteSP bp_site_sp(
               exe_ctx.GetProcessPtr()->GetBreakpointSiteList().FindByID(
                   site_id));
           if (bp_site_sp)
             return bp_site_sp->GetNumberOfOwners() * 2;
           else
             return 0; // Breakpoint must have cleared itself...
         } break;
 
         case eStopReasonWatchpoint:
           return 1;
 
         case eStopReasonSignal:
           return 1;
 
         case eStopReasonException:
           return 1;
+
+        case eStopReasonFork:
+          return 1;
+
+        case eStopReasonVFork:
+          return 1;
         }
       }
     }
   }
   return 0;
 }
 
 uint64_t SBThread::GetStopReasonDataAtIndex(uint32_t idx) {
if (stop_locker.TryLock(&exe_ctx.GetProcessPtr()->GetRunLock())) {
         case eStopReasonInvalid:
         case eStopReasonNone:
         case eStopReasonTrace:
         case eStopReasonExec:
         case eStopReasonPlanComplete:
         case eStopReasonThreadExiting:
         case eStopReasonInstrumentation:
         case eStopReasonProcessorTrace:
+        case eStopReasonVForkDone:
           // There is no data for these stop reasons.
           return 0;
 
         case eStopReasonBreakpoint: {
           break_id_t site_id = stop_info_sp->GetValue();
           lldb::BreakpointSiteSP bp_site_sp(
               exe_ctx.GetProcessPtr()->GetBreakpointSiteList().FindByID(
                   site_id));
if (stop_locker.TryLock(&exe_ctx.GetProcessPtr()->GetRunLock())) {
         case eStopReasonWatchpoint:
           return stop_info_sp->GetValue();
 
         case eStopReasonSignal:
           return stop_info_sp->GetValue();
 
         case eStopReasonException:
           return stop_info_sp->GetValue();
+
+        case eStopReasonFork:
+          return stop_info_sp->GetValue();
+
+        case eStopReasonVFork:
+          return stop_info_sp->GetValue();
         }
       }
     }
   }
   return 0;
 }
 
 bool SBThread::GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream) {

lldb/source/Plugins/Process/gdb-remote/GDBRemoteCommunicationServerLLGS.cpp

static const char *GetStopReasonString(StopReason stop_reason) {
   case eStopReasonSignal:
     return "signal";
   case eStopReasonException:
     return "exception";
   case eStopReasonExec:
     return "exec";
   case eStopReasonProcessorTrace:
     return "processor trace";
+  case eStopReasonFork:
+    return "fork";
+  case eStopReasonVFork:
+    return "vfork";
+  case eStopReasonVForkDone:
+    return "vforkdone";
   case eStopReasonInstrumentation:
   case eStopReasonInvalid:
   case eStopReasonPlanComplete:
   case eStopReasonThreadExiting:
   case eStopReasonNone:
     break; // ignored
   }
   return nullptr;
if (!description.empty()) {
 
     for (uint32_t i = 0; i < tid_stop_info.details.exception.data_count; ++i) {
       response.PutCString("medata:");
       response.PutHex64(tid_stop_info.details.exception.data[i]);
       response.PutChar(';');
     }
   }
 
+  // Include child process PID/TID for forks.
+  if (tid_stop_info.reason == eStopReasonFork ||
+      tid_stop_info.reason == eStopReasonVFork) {
+    assert(bool(m_extensions_supported &
+                NativeProcessProtocol::Extension::multiprocess));
+    if (tid_stop_info.reason == eStopReasonFork)
+      assert(bool(m_extensions_supported &
+                  NativeProcessProtocol::Extension::fork));
+    if (tid_stop_info.reason == eStopReasonVFork)
+      assert(bool(m_extensions_supported &
+                  NativeProcessProtocol::Extension::vfork));
+    response.Printf("%s:p%" PRIx64 ".%" PRIx64 ";", reason_str,
+                    tid_stop_info.details.fork.child_pid,
+                    tid_stop_info.details.fork.child_tid);
+  }
+
   return SendPacketNoLock(response.GetString());
 }
 
 void GDBRemoteCommunicationServerLLGS::HandleInferiorState_Exited(
     NativeProcessProtocol *process) {
   assert(process && "process cannot be NULL");
 
   Log *log(GetLogIfAnyCategoriesSet(LIBLLDB_LOG_PROCESS));

lldb/source/Target/Process.cpp

if (Process::ProcessEventData::GetRestartedFromEvent(event_sp.get())) {
               }
               break;
             }
             case eStopReasonTrace:
             case eStopReasonBreakpoint:
             case eStopReasonWatchpoint:
             case eStopReasonException:
             case eStopReasonExec:
+            case eStopReasonFork:
+            case eStopReasonVFork:
+            case eStopReasonVForkDone:
             case eStopReasonThreadExiting:
             case eStopReasonInstrumentation:
             case eStopReasonProcessorTrace:
               if (!other_thread)
                 other_thread = thread;
               break;
             case eStopReasonPlanComplete:
               if (!plan_thread)

lldb/source/Target/StackFrameList.cpp

void StackFrameList::ResetCurrentInlinedDepth() {
   // valid inlined depth set.
   StopInfoSP stop_info_sp = m_thread.GetStopInfo();
   if (!stop_info_sp)
     return;
   switch (stop_info_sp->GetStopReason()) {
   case eStopReasonWatchpoint:
   case eStopReasonException:
   case eStopReasonExec:
+  case eStopReasonFork:
+  case eStopReasonVFork:
+  case eStopReasonVForkDone:
   case eStopReasonSignal:
     // In all these cases we want to stop in the deepest frame.
     m_current_inlined_pc = curr_pc;
     m_current_inlined_depth = 0;
     break;
   case eStopReasonBreakpoint: {
     // FIXME: Figure out what this break point is doing, and set the inline
     // depth appropriately.  Be careful to take into account breakpoints that

lldb/source/Target/Thread.cpp

std::string Thread::StopReasonAsString(lldb::StopReason reason) {
   case eStopReasonWatchpoint:
     return "watchpoint";
   case eStopReasonSignal:
     return "signal";
   case eStopReasonException:
     return "exception";
   case eStopReasonExec:
     return "exec";
+  case eStopReasonFork:
+    return "fork";
+  case eStopReasonVFork:
+    return "vfork";
+  case eStopReasonVForkDone:
+    return "vfork done";
   case eStopReasonPlanComplete:
     return "plan complete";
   case eStopReasonThreadExiting:
     return "thread exiting";
   case eStopReasonInstrumentation:
     return "instrumentation break";
   case eStopReasonProcessorTrace:
     return "processor trace";

lldb/tools/lldb-vscode/JSONUtils.cpp

case lldb::eStopReasonProcessorTrace:
     break;
   case lldb::eStopReasonSignal:
   case lldb::eStopReasonException:
     body.try_emplace("reason", "exception");
     break;
   case lldb::eStopReasonExec:
     body.try_emplace("reason", "entry");
     break;
+  case lldb::eStopReasonFork:
+    body.try_emplace("reason", "fork");
+    break;
+  case lldb::eStopReasonVFork:
+    body.try_emplace("reason", "vfork");
+    break;
+  case lldb::eStopReasonVForkDone:
+    body.try_emplace("reason", "vforkdone");
+    break;
   case lldb::eStopReasonThreadExiting:
   case lldb::eStopReasonInvalid:
   case lldb::eStopReasonNone:
     break;
   }
   if (stop_id == 0)
     body.try_emplace("reason", "entry");
   const lldb::tid_t tid = thread.GetThreadID();

lldb/tools/lldb-vscode/LLDBUtils.cpp

bool ThreadHasStopReason(lldb::SBThread &thread) {
   case lldb::eStopReasonPlanComplete:
   case lldb::eStopReasonBreakpoint:
   case lldb::eStopReasonWatchpoint:
   case lldb::eStopReasonInstrumentation:
   case lldb::eStopReasonSignal:
   case lldb::eStopReasonException:
   case lldb::eStopReasonExec:
   case lldb::eStopReasonProcessorTrace:
+  case lldb::eStopReasonFork:
+  case lldb::eStopReasonVFork:
+  case lldb::eStopReasonVForkDone:
     return true;
   case lldb::eStopReasonThreadExiting:
   case lldb::eStopReasonInvalid:
   case lldb::eStopReasonNone:
     break;
   }
   return false;
 }