Add runToBinaryEntry option for lldb-vscode

[yinghuitan]

Summary

This patch adds a new runToBinaryEntry option which sets a one-shot breakpoint
at program entry. This option is useful for synchronizing module loading with
dynamic loader to measure debugger startup performance: when program entry
one-short breakpoint hits most of the dependency modules should have been
loaded so this provides a good sample point for debugger startup time.

More explicitly for lldb-vscode, when this option is enabled, "Initialized" DAP
event is synchronously sent after most dependency modules are loaded.

Note: this is re-submission of https://reviews.llvm.org/D135798

[clayborg]

We have to let the IDE set breakpoints after the "initialized" packet is sent and _then_ do this functionality. So this patch needs to be modified to make that happen.

lldb/tools/lldb-vscode/lldb-vscode.cpp

1807–1809

If this synchronously runs to the entry point of the program prior to letting the IDE set breakpoints (which happens when the "initialized" packet is sent), then we can't do this. We can miss breakpoints if they are set in the C++ global initializer lists. The flow with this in here will not stop at the entry point and allow the IDE to set breakpoints first and this must happen.

lldb/tools/lldb-vscode/package.json

162

Description should be capitalized correct and the language is a bit off "run to program entry one-shot breakpoint"? Did you mean "run to program entry using a one-shot breakpoint"?

[clayborg]

Ideally this feature would enable a one shot breakpoint and let the startup happen just like it was before this patch.

We don't want the user to see this stop right? It seems like we should allow some commands to be run with this one shot breakpoint and have it auto continue? What is supposed to happen now? the IDE knows that it set this startup option and then does something on the first stop?

[yinghuitan]

Discussed offline. We can't rely on initialized event because it has to happen before all breakpoints are set. Will create a new design for htis.

lldb/packages/Python/lldbsuite/test/tools/lldb-vscode/lldbvscode_testcase.py

def get_source_and_line(self, threadId=None, frameIndex=0):
         return ('', 0)
 
     def get_stdout(self, timeout=0.0):
         return self.vscode.get_output('stdout', timeout=timeout)
 
     def get_console(self, timeout=0.0):
         return self.vscode.get_output('console', timeout=timeout)
 
+    def get_telemetry(self, timeout=0.0):
+        return self.vscode.get_output('telemetry', timeout=timeout)
+
     def collect_console(self, duration):
         return self.vscode.collect_output('console', duration=duration)
 
     def get_local_as_int(self, name, threadId=None):
         value = self.vscode.get_local_variable_value(name, threadId=threadId)
         if value.startswith('0x'):
             return int(value, 16)
         elif value.startswith('0'):
class VSCodeTestCaseBase(TestBase):
 
     def launch(self, program=None, args=None, cwd=None, env=None,
                stopOnEntry=False, disableASLR=True,
                disableSTDIO=False, shellExpandArguments=False,
                trace=False, initCommands=None, preRunCommands=None,
                stopCommands=None, exitCommands=None, terminateCommands=None,
                sourcePath=None, debuggerRoot=None, sourceInitFile=False, launchCommands=None,
                sourceMap=None, disconnectAutomatically=True, runInTerminal=False,
-               expectFailure=False, postRunCommands=None):
+               expectFailure=False, postRunCommands=None, runToBinaryEntry=False):
         '''Sending launch request to vscode
         '''
 
         # Make sure we disconnect and terminate the VSCode debug adapter,
         # if we throw an exception during the test case
         def cleanup():
             if disconnectAutomatically:
                 self.vscode.request_disconnect(terminateDebuggee=True)
def launch(self, program=None, args=None, cwd=None, env=None,
             exitCommands=exitCommands,
             terminateCommands=terminateCommands,
             sourcePath=sourcePath,
             debuggerRoot=debuggerRoot,
             launchCommands=launchCommands,
             sourceMap=sourceMap,
             runInTerminal=runInTerminal,
             expectFailure=expectFailure,
-            postRunCommands=postRunCommands)
+            postRunCommands=postRunCommands,
+            runToBinaryEntry=runToBinaryEntry)
 
         if expectFailure:
             return response
 
         if not (response and response['success']):
             self.assertTrue(response['success'],
                             'launch failed (%s)' % (response['message']))
         # We need to trigger a request_configurationDone after we've successfully
         # attached a runInTerminal process to finish initialization.
         if runInTerminal:
             self.vscode.request_configurationDone()
         return response
 
 
     def build_and_launch(self, program, args=None, cwd=None, env=None,
                          stopOnEntry=False, disableASLR=True,
                          disableSTDIO=False, shellExpandArguments=False,
                          trace=False, initCommands=None, preRunCommands=None,
                          stopCommands=None, exitCommands=None,
                          terminateCommands=None, sourcePath=None,
                          debuggerRoot=None, sourceInitFile=False, runInTerminal=False,
                          disconnectAutomatically=True, postRunCommands=None,
-                         lldbVSCodeEnv=None):
+                         lldbVSCodeEnv=None, runToBinaryEntry=False):
         '''Build the default Makefile target, create the VSCode debug adaptor,
            and launch the process.
         '''
         self.build_and_create_debug_adaptor(lldbVSCodeEnv)
         self.assertTrue(os.path.exists(program), 'executable must exist')
 
         return self.launch(program, args, cwd, env, stopOnEntry, disableASLR,
                     disableSTDIO, shellExpandArguments, trace,
                     initCommands, preRunCommands, stopCommands, exitCommands,
                     terminateCommands, sourcePath, debuggerRoot, sourceInitFile,
                     runInTerminal=runInTerminal,
                     disconnectAutomatically=disconnectAutomatically,
-                    postRunCommands=postRunCommands)
+                    postRunCommands=postRunCommands,
+                    runToBinaryEntry=runToBinaryEntry)

lldb/packages/Python/lldbsuite/test/tools/lldb-vscode/vscode.py

class DebugCommunication(object):
     def request_launch(self, program, args=None, cwd=None, env=None,
                        stopOnEntry=False, disableASLR=True,
                        disableSTDIO=False, shellExpandArguments=False,
                        trace=False, initCommands=None, preRunCommands=None,
                        stopCommands=None, exitCommands=None,
                        terminateCommands=None ,sourcePath=None,
                        debuggerRoot=None, launchCommands=None, sourceMap=None,
                        runInTerminal=False, expectFailure=False,
-                       postRunCommands=None):
+                       postRunCommands=None, runToBinaryEntry=False):
         args_dict = {
             'program': program
         }
         if args:
             args_dict['args'] = args
         if cwd:
             args_dict['cwd'] = cwd
         if env:
             args_dict['env'] = env
         if stopOnEntry:
             args_dict['stopOnEntry'] = stopOnEntry
+        if runToBinaryEntry:
+            args_dict['runToBinaryEntry'] = runToBinaryEntry
         if disableASLR:
             args_dict['disableASLR'] = disableASLR
         if disableSTDIO:
             args_dict['disableSTDIO'] = disableSTDIO
         if shellExpandArguments:
             args_dict['shellExpandArguments'] = shellExpandArguments
         if trace:
             args_dict['trace'] = trace

lldb/test/API/tools/lldb-vscode/launch/TestVSCode_launch.py

def test_stopOnEntry(self):
                 if 'reason' in body:
                     reason = body['reason']
                     self.assertNotEqual(
                         reason, 'breakpoint',
                         'verify stop isn\'t "main" breakpoint')
 
     @skipIfWindows
     @skipIfRemote
+    def test_runToBinaryEntry(self):
+        '''
+            Tests the runToBinaryEntry option can successfully launch a simple
+            program and hit a breakpoint and does not interupt the launch.
+        '''
+        program = self.getBuildArtifact("a.out")
+        self.build_and_launch(program, runToBinaryEntry=True)
+        self.set_function_breakpoints(['main'])
+        stopped_events = self.continue_to_next_stop()
+        telemetry = self.get_telemetry()
+        self.assertIn("Process stopped successfully at the binary's entry point", telemetry)
+
+        for stopped_event in stopped_events:
+            if 'body' in stopped_event:
+                body = stopped_event['body']
+                if 'reason' in body:
+                    reason = body['reason']
+                    self.assertTrue(
+                        reason == 'breakpoint',
+                        'verify successfully stop at "main" breakpoint')
+
+    @skipIfWindows
+    @skipIfRemote
     def test_cwd(self):
         '''
             Tests the default launch of a simple program with a current working
             directory.
         '''
         program = self.getBuildArtifact("a.out")
         program_parent_dir = os.path.realpath(
             os.path.dirname(os.path.dirname(program)))

lldb/tools/lldb-vscode/VSCode.h

struct VSCode {
   std::vector<std::string> init_commands;
   std::vector<std::string> pre_run_commands;
   std::vector<std::string> exit_commands;
   std::vector<std::string> stop_commands;
   std::vector<std::string> terminate_commands;
   lldb::tid_t focus_tid;
   bool sent_terminated_event;
   bool stop_at_entry;
+  bool run_to_binary_entry = false;
   bool is_attach;
   bool configuration_done_sent;
   uint32_t reverse_request_seq;
   std::map<std::string, RequestCallback> request_handlers;
   bool waiting_for_run_in_terminal;
   ProgressEventReporter progress_event_reporter;
   // Keep track of the last stop thread index IDs as threads won't go away
   // unless we send a "thread" event to indicate the thread exited.
struct VSCode {
   /// process state change events depending on if the user modifies the async
   /// setting in the debugger. Since both "attachCommands" and "launchCommands"
   /// could end up using any combination of LLDB commands, we must ensure we can
   /// also catch when the process stops, so we must poll the process to make
   /// sure we handle all cases.
   ///
   /// \param[in] seconds
   ///   The number of seconds to poll the process to wait until it is stopped.
+  /// \param[in] old_stop_id
+  ///   Optional old stop id which we should only check for stopped state if
+  ///   the new stop id is greater than it. This is needed if the previous state
+  ///   is stopped so that we can ensure we are checking new stopped state not
+  ///   the old one in async mode.
   ///
   /// \return Error if waiting for the process fails, no error if succeeds.
-  lldb::SBError WaitForProcessToStop(uint32_t seconds);
+  lldb::SBError WaitForProcessToStop(uint32_t seconds, uint32_t old_stop_id = 0);
 
 private:
   // Send the JSON in "json_str" to the "out" stream. Correctly send the
   // "Content-Length:" field followed by the length, followed by the raw
   // JSON bytes.
   void SendJSON(const std::string &json_str);
 };
 
 extern VSCode g_vsc;
 
 } // namespace lldb_vscode
 
 #endif

lldb/tools/lldb-vscode/VSCode.cpp

PacketStatus VSCode::SendReverseRequest(llvm::json::Object request,
   return PacketStatus::EndOfFile;
 }
 
 void VSCode::RegisterRequestCallback(std::string request,
                                      RequestCallback callback) {
   request_handlers[request] = callback;
 }
 
-lldb::SBError VSCode::WaitForProcessToStop(uint32_t seconds) {
+lldb::SBError VSCode::WaitForProcessToStop(uint32_t seconds,
+                                           uint32_t old_stop_id) {
   lldb::SBError error;
   lldb::SBProcess process = target.GetProcess();
   if (!process.IsValid()) {
     error.SetErrorString("invalid process");
     return error;
   }
   auto timeout_time =
       std::chrono::steady_clock::now() + std::chrono::seconds(seconds);
   while (std::chrono::steady_clock::now() < timeout_time) {
+    // Wait for stop id changed before checking for stopped state.
+    // This is needed to make sure we are not checking old stopped state in
+    // async mode.
+    if (old_stop_id > 0 && process.GetStopID() <= old_stop_id)
+      continue;
     const auto state = process.GetState();
     switch (state) {
-      case lldb::eStateAttaching:
-      case lldb::eStateConnected:
-      case lldb::eStateInvalid:
-      case lldb::eStateLaunching:
-      case lldb::eStateRunning:
-      case lldb::eStateStepping:
-      case lldb::eStateSuspended:
-        break;
-      case lldb::eStateDetached:
-        error.SetErrorString("process detached during launch or attach");
-        return error;
-      case lldb::eStateExited:
-        error.SetErrorString("process exited during launch or attach");
-        return error;
-      case lldb::eStateUnloaded:
-        error.SetErrorString("process unloaded during launch or attach");
-        return error;
-      case lldb::eStateCrashed:
-      case lldb::eStateStopped:
-        return lldb::SBError(); // Success!
     }
     std::this_thread::sleep_for(std::chrono::microseconds(250));
   }
   error.SetErrorStringWithFormat("process failed to stop within %u seconds",
                                  seconds);
   return error;
 }
 

lldb/tools/lldb-vscode/lldb-vscode.cpp

llvm::Error request_runInTerminal(const llvm::json::Object &launch_request) {
   did_attach_message_success.wait();
   error = did_attach_message_success.get();
   if (error.Success())
     return llvm::Error::success();
   return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                  error.GetCString());
 }
 
+lldb::SBError RunToBinaryEntry() {
+  lldb::SBError error;
+  if (!g_vsc.run_to_binary_entry)
+    return error;
+
+  if (g_vsc.stop_at_entry) {
+    g_vsc.SendOutput(OutputType::Console,
+                     "RunToBinaryEntry is ignored due to StopOnEntry\n");
+    return error;
+  }
+
+  lldb::SBTarget target = g_vsc.debugger.GetSelectedTarget();
+  if (!target.IsValid())
+    return error;
+  lldb::SBFileSpec exe_file = target.GetExecutable();
+  if (!exe_file.IsValid())
+    return error;
+  lldb::SBModule exe_module = target.FindModule(exe_file);
+  if (!exe_module.IsValid()) {
+    g_vsc.SendOutput(OutputType::Console,
+                     "RunToBinaryEntry failed: invalid executable module\n");
+    return error;
+  }
+
+  lldb::SBAddress entry_point = exe_module.GetObjectFileEntryPointAddress();
+  if (!entry_point.IsValid()) {
+    g_vsc.SendOutput(OutputType::Console,
+                     "RunToBinaryEntry failed: can't find entry point\n");
+    return error;
+  }
+  lldb::SBBreakpoint entry_breakpoint =
+      target.BreakpointCreateBySBAddress(entry_point);
+  if (!entry_breakpoint.IsValid() || entry_breakpoint.GetNumLocations() == 0) {
+    g_vsc.SendOutput(OutputType::Console,
+                     "RunToBinaryEntry failed: can't resolve the entry point breakpoint\n");
+    return error;
+  }
+
+  uint32_t old_stop_id = target.GetProcess().GetStopID();
+  entry_breakpoint.SetOneShot(true);
+  error = target.GetProcess().Continue();
+  if (error.Fail())
+    return error;
+
+  const uint64_t timeout_seconds = 600;
+  error = g_vsc.WaitForProcessToStop(timeout_seconds, old_stop_id);
+  if (error.Fail())
+    return error;
+
+  // Successfully got a process stop; we still need to check if the stop is what
+  // we expected.
+  if (entry_breakpoint.GetHitCount() == 0)
+    g_vsc.SendOutput(OutputType::Telemetry,
+                     "RunToBinaryEntry failed: process stopped not at the "
+                     "binary's entry point\n");
+  else
+    g_vsc.SendOutput(OutputType::Telemetry,
+                     "RunToBinaryEntry success: Process stopped successfully "
+                     "at the binary's entry point\n");
+  return error;
+}
+
 // "LaunchRequest": {
 //   "allOf": [ { "$ref": "#/definitions/Request" }, {
 //     "type": "object",
 //     "description": "Launch request; value of command field is 'launch'.",
 //     "properties": {
 //       "command": {
 //         "type": "string",
 //         "enum": [ "launch" ]
void request_launch(const llvm::json::Object &request) {
   g_vsc.pre_run_commands = GetStrings(arguments, "preRunCommands");
   g_vsc.stop_commands = GetStrings(arguments, "stopCommands");
   g_vsc.exit_commands = GetStrings(arguments, "exitCommands");
   g_vsc.terminate_commands = GetStrings(arguments, "terminateCommands");
   auto launchCommands = GetStrings(arguments, "launchCommands");
   std::vector<std::string> postRunCommands =
       GetStrings(arguments, "postRunCommands");
   g_vsc.stop_at_entry = GetBoolean(arguments, "stopOnEntry", false);
+  g_vsc.run_to_binary_entry = GetBoolean(arguments, "runToBinaryEntry", false);
   const llvm::StringRef debuggerRoot = GetString(arguments, "debuggerRoot");
   const uint64_t timeout_seconds = GetUnsigned(arguments, "timeout", 30);
 
   // This is a hack for loading DWARF in .o files on Mac where the .o files
   // in the debug map of the main executable have relative paths which require
   // the lldb-vscode binary to have its working directory set to that relative
   // root for the .o files in order to be able to load debug info.
   if (!debuggerRoot.empty())
if (GetBoolean(arguments, "runInTerminal", false)) {
     // selected target after these commands are run.
     g_vsc.target = g_vsc.debugger.GetSelectedTarget();
     // Make sure the process is launched and stopped at the entry point before
     // proceeding as the the launch commands are not run using the synchronous
     // mode.
     error = g_vsc.WaitForProcessToStop(timeout_seconds);
   }
 
+  if (error.Success())
+    error = RunToBinaryEntry();
+
   if (error.Fail()) {
     response["success"] = llvm::json::Value(false);
     EmplaceSafeString(response, "message", std::string(error.GetCString()));
   } else {
     g_vsc.RunLLDBCommands("Running postRunCommands:", postRunCommands);
   }
 
   g_vsc.SendJSON(llvm::json::Value(std::move(response)));

lldb/tools/lldb-vscode/package.json

"debuggers": [
                 "description": "Additional environment variables to set when launching the program. This is an array of strings that contains the variable name followed by an optional '=' character and the environment variable's value. Example:  [\"FOO=BAR\", \"BAZ\"]",
                 "default": []
               },
               "stopOnEntry": {
                 "type": "boolean",
                 "description": "Automatically stop after launch.",
                 "default": false
               },
+              "runToBinaryEntry": {
+                "type": "boolean",
+                "description": "run to program entry one-shot breakpoint during launch to ensure dependency modules are loaded.",
+                "default": false
+              },
               "disableASLR": {
                 "type": "boolean",
                 "description": "Enable or disable Address space layout randomization if the debugger supports it.",
                 "default": true
               },
               "disableSTDIO": {
                 "type": "boolean",
                 "description": "Don't retrieve STDIN, STDOUT and STDERR as the program is running.",