[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

 //===-- SBThread.h ----------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_API_SBTHREAD_H
 #define LLDB_API_SBTHREAD_H
 
 #include "lldb/API/SBDefines.h"
 
 #include <stdio.h>
 
 namespace lldb {
 
 class SBFrame;
 
 class LLDB_API SBThread {
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

 //===-- SBThreadPlan.h ------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_API_SBTHREADPLAN_H
 #define LLDB_API_SBTHREADPLAN_H
 
 #include "lldb/API/SBDefines.h"
 
 #include <stdio.h>
 
 namespace lldb {
 
 class LLDB_API SBThreadPlan {
 
 public:
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

 //===-- Debug.h -------------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_HOST_DEBUG_H
 #define LLDB_HOST_DEBUG_H
 
 #include <vector>
 
 #include "lldb/lldb-private.h"
 
 namespace lldb_private {
 
 // Tells a thread what it needs to do when the process is resumed.
 struct ResumeAction {
   lldb::tid_t tid;       // The thread ID that this action applies to,
                          // LLDB_INVALID_THREAD_ID for the default thread
                          // action
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

 //===-- SBThread.cpp ------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/API/SBThread.h"
 #include "SBReproducerPrivate.h"
 #include "Utils.h"
 #include "lldb/API/SBAddress.h"
 #include "lldb/API/SBDebugger.h"
 #include "lldb/API/SBEvent.h"
 #include "lldb/API/SBFileSpec.h"
 #include "lldb/API/SBFrame.h"
 #include "lldb/API/SBProcess.h"
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

 //===-- GDBRemoteCommunicationServerLLGS.cpp ------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include <errno.h>
 
 #include "lldb/Host/Config.h"
 
 
 #include <chrono>
 #include <cstring>
 #include <thread>
 
 #include "GDBRemoteCommunicationServerLLGS.h"
 #include "lldb/Host/ConnectionFileDescriptor.h"
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) {
+    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

 //===-- Process.cpp -------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include <atomic>
 #include <memory>
 #include <mutex>
 
 #include "llvm/Support/ScopedPrinter.h"
 #include "llvm/Support/Threading.h"
 
 #include "lldb/Breakpoint/BreakpointLocation.h"
 #include "lldb/Breakpoint/StoppointCallbackContext.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/Module.h"
 #include "lldb/Core/ModuleSpec.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Expression/DiagnosticManager.h"
 #include "lldb/Expression/DynamicCheckerFunctions.h"
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

 //===-- StackFrameList.cpp ------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Target/StackFrameList.h"
 #include "lldb/Breakpoint/Breakpoint.h"
 #include "lldb/Breakpoint/BreakpointLocation.h"
 #include "lldb/Core/SourceManager.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Symbol/Block.h"
 #include "lldb/Symbol/Function.h"
 #include "lldb/Symbol/Symbol.h"
 #include "lldb/Target/Process.h"
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

 //===-- Thread.cpp --------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Target/Thread.h"
 #include "lldb/Breakpoint/BreakpointLocation.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/FormatEntity.h"
 #include "lldb/Core/Module.h"
 #include "lldb/Core/StructuredDataImpl.h"
 #include "lldb/Core/ValueObject.h"
 #include "lldb/Host/Host.h"
 #include "lldb/Interpreter/OptionValueFileSpecList.h"
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

 #include <iomanip>
 #include <sstream>
 
 #include "llvm/ADT/Optional.h"
 #include "llvm/Support/FormatAdapters.h"
 #include "llvm/Support/Path.h"
 #include "llvm/Support/ScopedPrinter.h"
 
 #include "lldb/API/SBBreakpoint.h"
 #include "lldb/API/SBBreakpointLocation.h"
 #include "lldb/API/SBValue.h"
 #include "lldb/Host/PosixApi.h"
 
 #include "ExceptionBreakpoint.h"
 #include "JSONUtils.h"
 #include "LLDBUtils.h"
 #include "VSCode.h"
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;
 }