1 //===-- SWIG Interface for SBDebugger ---------------------------*- C++ -*-===// 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 9 namespace lldb { 10 11 %feature("docstring", 12 "SBDebugger is the primordial object that creates SBTargets and provides 13 access to them. It also manages the overall debugging experiences. 14 15 For example (from example/disasm.py), 16 17 import lldb 18 import os 19 import sys 20 21 def disassemble_instructions (insts): 22 for i in insts: 23 print i 24 25 ... 26 27 # Create a new debugger instance 28 debugger = lldb.SBDebugger.Create() 29 30 # When we step or continue, don't return from the function until the process 31 # stops. We do this by setting the async mode to false. 32 debugger.SetAsync (False) 33 34 # Create a target from a file and arch 35 print('Creating a target for \'%s\'' % exe) 36 37 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT) 38 39 if target: 40 # If the target is valid set a breakpoint at main 41 main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename()); 42 43 print main_bp 44 45 # Launch the process. Since we specified synchronous mode, we won't return 46 # from this function until we hit the breakpoint at main 47 process = target.LaunchSimple (None, None, os.getcwd()) 48 49 # Make sure the launch went ok 50 if process: 51 # Print some simple process info 52 state = process.GetState () 53 print process 54 if state == lldb.eStateStopped: 55 # Get the first thread 56 thread = process.GetThreadAtIndex (0) 57 if thread: 58 # Print some simple thread info 59 print thread 60 # Get the first frame 61 frame = thread.GetFrameAtIndex (0) 62 if frame: 63 # Print some simple frame info 64 print frame 65 function = frame.GetFunction() 66 # See if we have debug info (a function) 67 if function: 68 # We do have a function, print some info for the function 69 print function 70 # Now get all instructions for this function and print them 71 insts = function.GetInstructions(target) 72 disassemble_instructions (insts) 73 else: 74 # See if we have a symbol in the symbol table for where we stopped 75 symbol = frame.GetSymbol(); 76 if symbol: 77 # We do have a symbol, print some info for the symbol 78 print symbol 79 # Now get all instructions for this symbol and print them 80 insts = symbol.GetInstructions(target) 81 disassemble_instructions (insts) 82 83 registerList = frame.GetRegisters() 84 print('Frame registers (size of register set = %d):' % registerList.GetSize()) 85 for value in registerList: 86 #print value 87 print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren())) 88 for child in value: 89 print('Name: ', child.GetName(), ' Value: ', child.GetValue()) 90 91 print('Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program') 92 next = sys.stdin.readline() 93 if not next or next.rstrip('\n') == 'quit': 94 print('Terminating the inferior process...') 95 process.Kill() 96 else: 97 # Now continue to the program exit 98 process.Continue() 99 # When we return from the above function we will hopefully be at the 100 # program exit. Print out some process info 101 print process 102 elif state == lldb.eStateExited: 103 print('Didn\'t hit the breakpoint at main, program has exited...') 104 else: 105 print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state)) 106 process.Kill() 107 108 Sometimes you need to create an empty target that will get filled in later. The most common use for this 109 is to attach to a process by name or pid where you don't know the executable up front. The most convenient way 110 to do this is: 111 112 target = debugger.CreateTarget('') 113 error = lldb.SBError() 114 process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error) 115 116 or the equivalent arguments for AttachToProcessWithID.") SBDebugger; 117 class SBDebugger 118 { 119 public: 120 121 static void 122 Initialize(); 123 124 static SBError 125 InitializeWithErrorHandling(); 126 127 static void 128 Terminate(); 129 130 static lldb::SBDebugger 131 Create(); 132 133 static lldb::SBDebugger 134 Create(bool source_init_files); 135 136 static lldb::SBDebugger 137 Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton); 138 139 static void 140 Destroy (lldb::SBDebugger &debugger); 141 142 static void 143 MemoryPressureDetected(); 144 145 SBDebugger(); 146 147 SBDebugger(const lldb::SBDebugger &rhs); 148 149 ~SBDebugger(); 150 151 bool 152 IsValid() const; 153 154 explicit operator bool() const; 155 156 void 157 Clear (); 158 159 void 160 SetAsync (bool b); 161 162 bool 163 GetAsync (); 164 165 void 166 SkipLLDBInitFiles (bool b); 167 168 #ifdef SWIGPYTHON 169 %pythoncode %{ 170 def SetOutputFileHandle(self, file, transfer_ownership): 171 "DEPRECATED, use SetOutputFile" 172 if file is None: 173 import sys 174 file = sys.stdout 175 self.SetOutputFile(SBFile.Create(file, borrow=True)) 176 177 def SetInputFileHandle(self, file, transfer_ownership): 178 "DEPRECATED, use SetInputFile" 179 if file is None: 180 import sys 181 file = sys.stdin 182 self.SetInputFile(SBFile.Create(file, borrow=True)) 183 184 def SetErrorFileHandle(self, file, transfer_ownership): 185 "DEPRECATED, use SetErrorFile" 186 if file is None: 187 import sys 188 file = sys.stderr 189 self.SetErrorFile(SBFile.Create(file, borrow=True)) 190 %} 191 #endif 192 193 194 %extend { 195 GetInputFileHandle()196 lldb::FileSP GetInputFileHandle() { 197 return self->GetInputFile().GetFile(); 198 } 199 GetOutputFileHandle()200 lldb::FileSP GetOutputFileHandle() { 201 return self->GetOutputFile().GetFile(); 202 } 203 GetErrorFileHandle()204 lldb::FileSP GetErrorFileHandle() { 205 return self->GetErrorFile().GetFile(); 206 } 207 } 208 209 SBError 210 SetInputFile (SBFile file); 211 212 SBError 213 SetOutputFile (SBFile file); 214 215 SBError 216 SetErrorFile (SBFile file); 217 218 SBError 219 SetInputFile (FileSP file); 220 221 SBError 222 SetOutputFile (FileSP file); 223 224 SBError 225 SetErrorFile (FileSP file); 226 227 SBFile 228 GetInputFile (); 229 230 SBFile 231 GetOutputFile (); 232 233 SBFile 234 GetErrorFile (); 235 236 lldb::SBCommandInterpreter 237 GetCommandInterpreter (); 238 239 void 240 HandleCommand (const char *command); 241 242 lldb::SBListener 243 GetListener (); 244 245 void 246 HandleProcessEvent (const lldb::SBProcess &process, 247 const lldb::SBEvent &event, 248 SBFile out, 249 SBFile err); 250 251 void 252 HandleProcessEvent (const lldb::SBProcess &process, 253 const lldb::SBEvent &event, 254 FileSP BORROWED, 255 FileSP BORROWED); 256 257 lldb::SBTarget 258 CreateTarget (const char *filename, 259 const char *target_triple, 260 const char *platform_name, 261 bool add_dependent_modules, 262 lldb::SBError& sb_error); 263 264 lldb::SBTarget 265 CreateTargetWithFileAndTargetTriple (const char *filename, 266 const char *target_triple); 267 268 lldb::SBTarget 269 CreateTargetWithFileAndArch (const char *filename, 270 const char *archname); 271 272 lldb::SBTarget 273 CreateTarget (const char *filename); 274 275 %feature("docstring", 276 "The dummy target holds breakpoints and breakpoint names that will prime newly created targets." 277 ) GetDummyTarget; 278 lldb::SBTarget GetDummyTarget(); 279 280 %feature("docstring", 281 "Return true if target is deleted from the target list of the debugger." 282 ) DeleteTarget; 283 bool 284 DeleteTarget (lldb::SBTarget &target); 285 286 lldb::SBTarget 287 GetTargetAtIndex (uint32_t idx); 288 289 uint32_t 290 GetIndexOfTarget (lldb::SBTarget target); 291 292 lldb::SBTarget 293 FindTargetWithProcessID (pid_t pid); 294 295 lldb::SBTarget 296 FindTargetWithFileAndArch (const char *filename, 297 const char *arch); 298 299 uint32_t 300 GetNumTargets (); 301 302 lldb::SBTarget 303 GetSelectedTarget (); 304 305 void 306 SetSelectedTarget (lldb::SBTarget &target); 307 308 lldb::SBPlatform 309 GetSelectedPlatform(); 310 311 void 312 SetSelectedPlatform(lldb::SBPlatform &platform); 313 314 %feature("docstring", 315 "Get the number of currently active platforms." 316 ) GetNumPlatforms; 317 uint32_t 318 GetNumPlatforms (); 319 320 %feature("docstring", 321 "Get one of the currently active platforms." 322 ) GetPlatformAtIndex; 323 lldb::SBPlatform 324 GetPlatformAtIndex (uint32_t idx); 325 326 %feature("docstring", 327 "Get the number of available platforms." 328 ) GetNumAvailablePlatforms; 329 uint32_t 330 GetNumAvailablePlatforms (); 331 332 %feature("docstring", " 333 Get the name and description of one of the available platforms. 334 335 @param idx Zero-based index of the platform for which info should be 336 retrieved, must be less than the value returned by 337 GetNumAvailablePlatforms().") GetAvailablePlatformInfoAtIndex; 338 lldb::SBStructuredData 339 GetAvailablePlatformInfoAtIndex (uint32_t idx); 340 341 lldb::SBSourceManager 342 GetSourceManager (); 343 344 // REMOVE: just for a quick fix, need to expose platforms through 345 // SBPlatform from this class. 346 lldb::SBError 347 SetCurrentPlatform (const char *platform_name); 348 349 bool 350 SetCurrentPlatformSDKRoot (const char *sysroot); 351 352 // FIXME: Once we get the set show stuff in place, the driver won't need 353 // an interface to the Set/Get UseExternalEditor. 354 bool 355 SetUseExternalEditor (bool input); 356 357 bool 358 GetUseExternalEditor (); 359 360 bool 361 SetUseColor (bool use_color); 362 363 bool 364 GetUseColor () const; 365 366 static bool 367 GetDefaultArchitecture (char *arch_name, size_t arch_name_len); 368 369 static bool 370 SetDefaultArchitecture (const char *arch_name); 371 372 lldb::ScriptLanguage 373 GetScriptingLanguage (const char *script_language_name); 374 375 static const char * 376 GetVersionString (); 377 378 static const char * 379 StateAsCString (lldb::StateType state); 380 381 static SBStructuredData GetBuildConfiguration(); 382 383 static bool 384 StateIsRunningState (lldb::StateType state); 385 386 static bool 387 StateIsStoppedState (lldb::StateType state); 388 389 bool 390 EnableLog (const char *channel, const char ** types); 391 392 void 393 SetLoggingCallback (lldb::LogOutputCallback log_callback, void *baton); 394 395 void 396 DispatchInput (const void *data, size_t data_len); 397 398 void 399 DispatchInputInterrupt (); 400 401 void 402 DispatchInputEndOfFile (); 403 404 const char * 405 GetInstanceName (); 406 407 static SBDebugger 408 FindDebuggerWithID (int id); 409 410 static lldb::SBError 411 SetInternalVariable (const char *var_name, const char *value, const char *debugger_instance_name); 412 413 static lldb::SBStringList 414 GetInternalVariableValue (const char *var_name, const char *debugger_instance_name); 415 416 bool 417 GetDescription (lldb::SBStream &description); 418 419 uint32_t 420 GetTerminalWidth () const; 421 422 void 423 SetTerminalWidth (uint32_t term_width); 424 425 lldb::user_id_t 426 GetID (); 427 428 const char * 429 GetPrompt() const; 430 431 void 432 SetPrompt (const char *prompt); 433 434 const char * 435 GetReproducerPath() const; 436 437 lldb::ScriptLanguage 438 GetScriptLanguage() const; 439 440 void 441 SetScriptLanguage (lldb::ScriptLanguage script_lang); 442 443 bool 444 GetCloseInputOnEOF () const; 445 446 void 447 SetCloseInputOnEOF (bool b); 448 449 lldb::SBTypeCategory 450 GetCategory (const char* category_name); 451 452 SBTypeCategory 453 GetCategory (lldb::LanguageType lang_type); 454 455 lldb::SBTypeCategory 456 CreateCategory (const char* category_name); 457 458 bool 459 DeleteCategory (const char* category_name); 460 461 uint32_t 462 GetNumCategories (); 463 464 lldb::SBTypeCategory 465 GetCategoryAtIndex (uint32_t); 466 467 lldb::SBTypeCategory 468 GetDefaultCategory(); 469 470 lldb::SBTypeFormat 471 GetFormatForType (lldb::SBTypeNameSpecifier); 472 473 lldb::SBTypeSummary 474 GetSummaryForType (lldb::SBTypeNameSpecifier); 475 476 lldb::SBTypeFilter 477 GetFilterForType (lldb::SBTypeNameSpecifier); 478 479 lldb::SBTypeSynthetic 480 GetSyntheticForType (lldb::SBTypeNameSpecifier); 481 482 STRING_EXTENSION(SBDebugger) 483 484 %feature("docstring", 485 "Launch a command interpreter session. Commands are read from standard input or 486 from the input handle specified for the debugger object. Output/errors are 487 similarly redirected to standard output/error or the configured handles. 488 489 @param[in] auto_handle_events If true, automatically handle resulting events. 490 @param[in] spawn_thread If true, start a new thread for IO handling. 491 @param[in] options Parameter collection of type SBCommandInterpreterRunOptions. 492 @param[in] num_errors Initial error counter. 493 @param[in] quit_requested Initial quit request flag. 494 @param[in] stopped_for_crash Initial crash flag. 495 496 @return 497 A tuple with the number of errors encountered by the interpreter, a boolean 498 indicating whether quitting the interpreter was requested and another boolean 499 set to True in case of a crash. 500 501 Example: 502 503 # Start an interactive lldb session from a script (with a valid debugger object 504 # created beforehand): 505 n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True, 506 False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter; 507 %apply int& INOUT { int& num_errors }; 508 %apply bool& INOUT { bool& quit_requested }; 509 %apply bool& INOUT { bool& stopped_for_crash }; 510 void 511 RunCommandInterpreter (bool auto_handle_events, 512 bool spawn_thread, 513 SBCommandInterpreterRunOptions &options, 514 int &num_errors, 515 bool &quit_requested, 516 bool &stopped_for_crash); 517 518 lldb::SBError 519 RunREPL (lldb::LanguageType language, const char *repl_options); 520 521 #ifdef SWIGPYTHON 522 %pythoncode%{ 523 def __iter__(self): 524 '''Iterate over all targets in a lldb.SBDebugger object.''' 525 return lldb_iter(self, 'GetNumTargets', 'GetTargetAtIndex') 526 527 def __len__(self): 528 '''Return the number of targets in a lldb.SBDebugger object.''' 529 return self.GetNumTargets() 530 %} 531 #endif 532 533 }; // class SBDebugger 534 535 } // namespace lldb 536