1 //===-- PluginManager.h -----------------------------------------*- 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 #ifndef LLDB_CORE_PLUGINMANAGER_H 10 #define LLDB_CORE_PLUGINMANAGER_H 11 12 #include "lldb/Core/Architecture.h" 13 #include "lldb/Symbol/TypeSystem.h" 14 #include "lldb/Utility/CompletionRequest.h" 15 #include "lldb/Utility/FileSpec.h" 16 #include "lldb/Utility/Status.h" 17 #include "lldb/lldb-enumerations.h" 18 #include "lldb/lldb-forward.h" 19 #include "lldb/lldb-private-interfaces.h" 20 #include "llvm/ADT/StringRef.h" 21 22 #include <cstddef> 23 #include <cstdint> 24 25 #define LLDB_PLUGIN_DEFINE_ADV(ClassName, PluginName) \ 26 namespace lldb_private { \ 27 void lldb_initialize_##PluginName() { ClassName::Initialize(); } \ 28 void lldb_terminate_##PluginName() { ClassName::Terminate(); } \ 29 } 30 31 #define LLDB_PLUGIN_DEFINE(PluginName) \ 32 LLDB_PLUGIN_DEFINE_ADV(PluginName, PluginName) 33 34 // FIXME: Generate me with CMake 35 #define LLDB_PLUGIN_DECLARE(PluginName) \ 36 namespace lldb_private { \ 37 extern void lldb_initialize_##PluginName(); \ 38 extern void lldb_terminate_##PluginName(); \ 39 } 40 41 #define LLDB_PLUGIN_INITIALIZE(PluginName) lldb_initialize_##PluginName() 42 #define LLDB_PLUGIN_TERMINATE(PluginName) lldb_terminate_##PluginName() 43 44 namespace lldb_private { 45 class CommandInterpreter; 46 class Debugger; 47 class StringList; 48 49 class PluginManager { 50 public: 51 static void Initialize(); 52 53 static void Terminate(); 54 55 // ABI 56 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 57 ABICreateInstance create_callback); 58 59 static bool UnregisterPlugin(ABICreateInstance create_callback); 60 61 static ABICreateInstance GetABICreateCallbackAtIndex(uint32_t idx); 62 63 // Architecture 64 static void RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 65 ArchitectureCreateInstance create_callback); 66 67 static void UnregisterPlugin(ArchitectureCreateInstance create_callback); 68 69 static std::unique_ptr<Architecture> 70 CreateArchitectureInstance(const ArchSpec &arch); 71 72 // Disassembler 73 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 74 DisassemblerCreateInstance create_callback); 75 76 static bool UnregisterPlugin(DisassemblerCreateInstance create_callback); 77 78 static DisassemblerCreateInstance 79 GetDisassemblerCreateCallbackAtIndex(uint32_t idx); 80 81 static DisassemblerCreateInstance 82 GetDisassemblerCreateCallbackForPluginName(llvm::StringRef name); 83 84 // DynamicLoader 85 static bool 86 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 87 DynamicLoaderCreateInstance create_callback, 88 DebuggerInitializeCallback debugger_init_callback = nullptr); 89 90 static bool UnregisterPlugin(DynamicLoaderCreateInstance create_callback); 91 92 static DynamicLoaderCreateInstance 93 GetDynamicLoaderCreateCallbackAtIndex(uint32_t idx); 94 95 static DynamicLoaderCreateInstance 96 GetDynamicLoaderCreateCallbackForPluginName(llvm::StringRef name); 97 98 // JITLoader 99 static bool 100 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 101 JITLoaderCreateInstance create_callback, 102 DebuggerInitializeCallback debugger_init_callback = nullptr); 103 104 static bool UnregisterPlugin(JITLoaderCreateInstance create_callback); 105 106 static JITLoaderCreateInstance 107 GetJITLoaderCreateCallbackAtIndex(uint32_t idx); 108 109 // EmulateInstruction 110 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 111 EmulateInstructionCreateInstance create_callback); 112 113 static bool 114 UnregisterPlugin(EmulateInstructionCreateInstance create_callback); 115 116 static EmulateInstructionCreateInstance 117 GetEmulateInstructionCreateCallbackAtIndex(uint32_t idx); 118 119 static EmulateInstructionCreateInstance 120 GetEmulateInstructionCreateCallbackForPluginName(llvm::StringRef name); 121 122 // OperatingSystem 123 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 124 OperatingSystemCreateInstance create_callback, 125 DebuggerInitializeCallback debugger_init_callback); 126 127 static bool UnregisterPlugin(OperatingSystemCreateInstance create_callback); 128 129 static OperatingSystemCreateInstance 130 GetOperatingSystemCreateCallbackAtIndex(uint32_t idx); 131 132 static OperatingSystemCreateInstance 133 GetOperatingSystemCreateCallbackForPluginName(llvm::StringRef name); 134 135 // Language 136 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 137 LanguageCreateInstance create_callback); 138 139 static bool UnregisterPlugin(LanguageCreateInstance create_callback); 140 141 static LanguageCreateInstance GetLanguageCreateCallbackAtIndex(uint32_t idx); 142 143 // LanguageRuntime 144 static bool RegisterPlugin( 145 llvm::StringRef name, llvm::StringRef description, 146 LanguageRuntimeCreateInstance create_callback, 147 LanguageRuntimeGetCommandObject command_callback = nullptr, 148 LanguageRuntimeGetExceptionPrecondition precondition_callback = nullptr); 149 150 static bool UnregisterPlugin(LanguageRuntimeCreateInstance create_callback); 151 152 static LanguageRuntimeCreateInstance 153 GetLanguageRuntimeCreateCallbackAtIndex(uint32_t idx); 154 155 static LanguageRuntimeGetCommandObject 156 GetLanguageRuntimeGetCommandObjectAtIndex(uint32_t idx); 157 158 static LanguageRuntimeGetExceptionPrecondition 159 GetLanguageRuntimeGetExceptionPreconditionAtIndex(uint32_t idx); 160 161 // SystemRuntime 162 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 163 SystemRuntimeCreateInstance create_callback); 164 165 static bool UnregisterPlugin(SystemRuntimeCreateInstance create_callback); 166 167 static SystemRuntimeCreateInstance 168 GetSystemRuntimeCreateCallbackAtIndex(uint32_t idx); 169 170 // ObjectFile 171 static bool 172 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 173 ObjectFileCreateInstance create_callback, 174 ObjectFileCreateMemoryInstance create_memory_callback, 175 ObjectFileGetModuleSpecifications get_module_specifications, 176 ObjectFileSaveCore save_core = nullptr, 177 DebuggerInitializeCallback debugger_init_callback = nullptr); 178 179 static bool UnregisterPlugin(ObjectFileCreateInstance create_callback); 180 181 static ObjectFileCreateInstance 182 GetObjectFileCreateCallbackAtIndex(uint32_t idx); 183 184 static ObjectFileCreateMemoryInstance 185 GetObjectFileCreateMemoryCallbackAtIndex(uint32_t idx); 186 187 static ObjectFileGetModuleSpecifications 188 GetObjectFileGetModuleSpecificationsCallbackAtIndex(uint32_t idx); 189 190 static ObjectFileCreateMemoryInstance 191 GetObjectFileCreateMemoryCallbackForPluginName(llvm::StringRef name); 192 193 static Status SaveCore(const lldb::ProcessSP &process_sp, 194 const FileSpec &outfile, 195 lldb::SaveCoreStyle &core_style, 196 llvm::StringRef plugin_name); 197 198 // ObjectContainer 199 static bool RegisterPlugin( 200 llvm::StringRef name, llvm::StringRef description, 201 ObjectContainerCreateInstance create_callback, 202 ObjectFileGetModuleSpecifications get_module_specifications, 203 ObjectContainerCreateMemoryInstance create_memory_callback = nullptr); 204 205 static bool UnregisterPlugin(ObjectContainerCreateInstance create_callback); 206 207 static ObjectContainerCreateInstance 208 GetObjectContainerCreateCallbackAtIndex(uint32_t idx); 209 210 static ObjectContainerCreateMemoryInstance 211 GetObjectContainerCreateMemoryCallbackAtIndex(uint32_t idx); 212 213 static ObjectFileGetModuleSpecifications 214 GetObjectContainerGetModuleSpecificationsCallbackAtIndex(uint32_t idx); 215 216 // Platform 217 static bool 218 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 219 PlatformCreateInstance create_callback, 220 DebuggerInitializeCallback debugger_init_callback = nullptr); 221 222 static bool UnregisterPlugin(PlatformCreateInstance create_callback); 223 224 static PlatformCreateInstance GetPlatformCreateCallbackAtIndex(uint32_t idx); 225 226 static PlatformCreateInstance 227 GetPlatformCreateCallbackForPluginName(llvm::StringRef name); 228 229 static llvm::StringRef GetPlatformPluginNameAtIndex(uint32_t idx); 230 231 static llvm::StringRef GetPlatformPluginDescriptionAtIndex(uint32_t idx); 232 233 static void AutoCompletePlatformName(llvm::StringRef partial_name, 234 CompletionRequest &request); 235 // Process 236 static bool 237 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 238 ProcessCreateInstance create_callback, 239 DebuggerInitializeCallback debugger_init_callback = nullptr); 240 241 static bool UnregisterPlugin(ProcessCreateInstance create_callback); 242 243 static ProcessCreateInstance GetProcessCreateCallbackAtIndex(uint32_t idx); 244 245 static ProcessCreateInstance 246 GetProcessCreateCallbackForPluginName(llvm::StringRef name); 247 248 static llvm::StringRef GetProcessPluginNameAtIndex(uint32_t idx); 249 250 static llvm::StringRef GetProcessPluginDescriptionAtIndex(uint32_t idx); 251 252 static void AutoCompleteProcessName(llvm::StringRef partial_name, 253 CompletionRequest &request); 254 255 // Register Type Provider 256 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 257 RegisterTypeBuilderCreateInstance create_callback); 258 259 static bool 260 UnregisterPlugin(RegisterTypeBuilderCreateInstance create_callback); 261 262 static lldb::RegisterTypeBuilderSP GetRegisterTypeBuilder(Target &target); 263 264 // ScriptInterpreter 265 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 266 lldb::ScriptLanguage script_lang, 267 ScriptInterpreterCreateInstance create_callback); 268 269 static bool UnregisterPlugin(ScriptInterpreterCreateInstance create_callback); 270 271 static ScriptInterpreterCreateInstance 272 GetScriptInterpreterCreateCallbackAtIndex(uint32_t idx); 273 274 static lldb::ScriptInterpreterSP 275 GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang, 276 Debugger &debugger); 277 278 // StructuredDataPlugin 279 280 /// Register a StructuredDataPlugin class along with optional 281 /// callbacks for debugger initialization and Process launch info 282 /// filtering and manipulation. 283 /// 284 /// \param[in] name 285 /// The name of the plugin. 286 /// 287 /// \param[in] description 288 /// A description string for the plugin. 289 /// 290 /// \param[in] create_callback 291 /// The callback that will be invoked to create an instance of 292 /// the callback. This may not be nullptr. 293 /// 294 /// \param[in] debugger_init_callback 295 /// An optional callback that will be made when a Debugger 296 /// instance is initialized. 297 /// 298 /// \param[in] filter_callback 299 /// An optional callback that will be invoked before LLDB 300 /// launches a process for debugging. The callback must 301 /// do the following: 302 /// 1. Only do something if the plugin's behavior is enabled. 303 /// 2. Only make changes for processes that are relevant to the 304 /// plugin. The callback gets a pointer to the Target, which 305 /// can be inspected as needed. The ProcessLaunchInfo is 306 /// provided in read-write mode, and may be modified by the 307 /// plugin if, for instance, additional environment variables 308 /// are needed to support the feature when enabled. 309 /// 310 /// \return 311 /// Returns true upon success; otherwise, false. 312 static bool 313 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 314 StructuredDataPluginCreateInstance create_callback, 315 DebuggerInitializeCallback debugger_init_callback = nullptr, 316 StructuredDataFilterLaunchInfo filter_callback = nullptr); 317 318 static bool 319 UnregisterPlugin(StructuredDataPluginCreateInstance create_callback); 320 321 static StructuredDataPluginCreateInstance 322 GetStructuredDataPluginCreateCallbackAtIndex(uint32_t idx); 323 324 static StructuredDataFilterLaunchInfo 325 GetStructuredDataFilterCallbackAtIndex(uint32_t idx, 326 bool &iteration_complete); 327 328 // SymbolFile 329 static bool 330 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 331 SymbolFileCreateInstance create_callback, 332 DebuggerInitializeCallback debugger_init_callback = nullptr); 333 334 static bool UnregisterPlugin(SymbolFileCreateInstance create_callback); 335 336 static SymbolFileCreateInstance 337 GetSymbolFileCreateCallbackAtIndex(uint32_t idx); 338 339 // SymbolVendor 340 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 341 SymbolVendorCreateInstance create_callback); 342 343 static bool UnregisterPlugin(SymbolVendorCreateInstance create_callback); 344 345 static SymbolVendorCreateInstance 346 GetSymbolVendorCreateCallbackAtIndex(uint32_t idx); 347 348 // Trace 349 static bool RegisterPlugin( 350 llvm::StringRef name, llvm::StringRef description, 351 TraceCreateInstanceFromBundle create_callback_from_bundle, 352 TraceCreateInstanceForLiveProcess create_callback_for_live_process, 353 llvm::StringRef schema, 354 DebuggerInitializeCallback debugger_init_callback); 355 356 static bool 357 UnregisterPlugin(TraceCreateInstanceFromBundle create_callback); 358 359 static TraceCreateInstanceFromBundle 360 GetTraceCreateCallback(llvm::StringRef plugin_name); 361 362 static TraceCreateInstanceForLiveProcess 363 GetTraceCreateCallbackForLiveProcess(llvm::StringRef plugin_name); 364 365 /// Get the JSON schema for a trace bundle description file corresponding to 366 /// the given plugin. 367 /// 368 /// \param[in] plugin_name 369 /// The name of the plugin. 370 /// 371 /// \return 372 /// An empty \a StringRef if no plugin was found with that plugin name, 373 /// otherwise the actual schema is returned. 374 static llvm::StringRef GetTraceSchema(llvm::StringRef plugin_name); 375 376 /// Get the JSON schema for a trace bundle description file corresponding to 377 /// the plugin given by its index. 378 /// 379 /// \param[in] index 380 /// The index of the plugin to get the schema of. 381 /// 382 /// \return 383 /// An empty \a StringRef if the index is greater than or equal to the 384 /// number plugins, otherwise the actual schema is returned. 385 static llvm::StringRef GetTraceSchema(size_t index); 386 387 // TraceExporter 388 389 /// \param[in] create_thread_trace_export_command 390 /// This callback is used to create a CommandObject that will be listed 391 /// under "thread trace export". Can be \b null. 392 static bool RegisterPlugin( 393 llvm::StringRef name, llvm::StringRef description, 394 TraceExporterCreateInstance create_callback, 395 ThreadTraceExportCommandCreator create_thread_trace_export_command); 396 397 static TraceExporterCreateInstance 398 GetTraceExporterCreateCallback(llvm::StringRef plugin_name); 399 400 static bool UnregisterPlugin(TraceExporterCreateInstance create_callback); 401 402 static llvm::StringRef GetTraceExporterPluginNameAtIndex(uint32_t index); 403 404 /// Return the callback used to create the CommandObject that will be listed 405 /// under "thread trace export". Can be \b null. 406 static ThreadTraceExportCommandCreator 407 GetThreadTraceExportCommandCreatorAtIndex(uint32_t index); 408 409 // UnwindAssembly 410 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 411 UnwindAssemblyCreateInstance create_callback); 412 413 static bool UnregisterPlugin(UnwindAssemblyCreateInstance create_callback); 414 415 static UnwindAssemblyCreateInstance 416 GetUnwindAssemblyCreateCallbackAtIndex(uint32_t idx); 417 418 // MemoryHistory 419 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 420 MemoryHistoryCreateInstance create_callback); 421 422 static bool UnregisterPlugin(MemoryHistoryCreateInstance create_callback); 423 424 static MemoryHistoryCreateInstance 425 GetMemoryHistoryCreateCallbackAtIndex(uint32_t idx); 426 427 // InstrumentationRuntime 428 static bool 429 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 430 InstrumentationRuntimeCreateInstance create_callback, 431 InstrumentationRuntimeGetType get_type_callback); 432 433 static bool 434 UnregisterPlugin(InstrumentationRuntimeCreateInstance create_callback); 435 436 static InstrumentationRuntimeGetType 437 GetInstrumentationRuntimeGetTypeCallbackAtIndex(uint32_t idx); 438 439 static InstrumentationRuntimeCreateInstance 440 GetInstrumentationRuntimeCreateCallbackAtIndex(uint32_t idx); 441 442 // TypeSystem 443 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 444 TypeSystemCreateInstance create_callback, 445 LanguageSet supported_languages_for_types, 446 LanguageSet supported_languages_for_expressions); 447 448 static bool UnregisterPlugin(TypeSystemCreateInstance create_callback); 449 450 static TypeSystemCreateInstance 451 GetTypeSystemCreateCallbackAtIndex(uint32_t idx); 452 453 static LanguageSet GetAllTypeSystemSupportedLanguagesForTypes(); 454 455 static LanguageSet GetAllTypeSystemSupportedLanguagesForExpressions(); 456 457 // REPL 458 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 459 REPLCreateInstance create_callback, 460 LanguageSet supported_languages); 461 462 static bool UnregisterPlugin(REPLCreateInstance create_callback); 463 464 static REPLCreateInstance GetREPLCreateCallbackAtIndex(uint32_t idx); 465 466 static LanguageSet GetREPLSupportedLanguagesAtIndex(uint32_t idx); 467 468 static LanguageSet GetREPLAllTypeSystemSupportedLanguages(); 469 470 // Some plug-ins might register a DebuggerInitializeCallback callback when 471 // registering the plug-in. After a new Debugger instance is created, this 472 // DebuggerInitialize function will get called. This allows plug-ins to 473 // install Properties and do any other initialization that requires a 474 // debugger instance. 475 static void DebuggerInitialize(Debugger &debugger); 476 477 static lldb::OptionValuePropertiesSP 478 GetSettingForDynamicLoaderPlugin(Debugger &debugger, 479 llvm::StringRef setting_name); 480 481 static bool CreateSettingForDynamicLoaderPlugin( 482 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 483 llvm::StringRef description, bool is_global_property); 484 485 static lldb::OptionValuePropertiesSP 486 GetSettingForPlatformPlugin(Debugger &debugger, llvm::StringRef setting_name); 487 488 static bool CreateSettingForPlatformPlugin( 489 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 490 llvm::StringRef description, bool is_global_property); 491 492 static lldb::OptionValuePropertiesSP 493 GetSettingForProcessPlugin(Debugger &debugger, llvm::StringRef setting_name); 494 495 static bool CreateSettingForProcessPlugin( 496 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 497 llvm::StringRef description, bool is_global_property); 498 499 static bool CreateSettingForTracePlugin( 500 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 501 llvm::StringRef description, bool is_global_property); 502 503 static lldb::OptionValuePropertiesSP 504 GetSettingForObjectFilePlugin(Debugger &debugger, 505 llvm::StringRef setting_name); 506 507 static bool CreateSettingForObjectFilePlugin( 508 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 509 llvm::StringRef description, bool is_global_property); 510 511 static lldb::OptionValuePropertiesSP 512 GetSettingForSymbolFilePlugin(Debugger &debugger, 513 llvm::StringRef setting_name); 514 515 static bool CreateSettingForSymbolFilePlugin( 516 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 517 llvm::StringRef description, bool is_global_property); 518 519 static lldb::OptionValuePropertiesSP 520 GetSettingForJITLoaderPlugin(Debugger &debugger, 521 llvm::StringRef setting_name); 522 523 static bool CreateSettingForJITLoaderPlugin( 524 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 525 llvm::StringRef description, bool is_global_property); 526 527 static lldb::OptionValuePropertiesSP 528 GetSettingForOperatingSystemPlugin(Debugger &debugger, 529 llvm::StringRef setting_name); 530 531 static bool CreateSettingForOperatingSystemPlugin( 532 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 533 llvm::StringRef description, bool is_global_property); 534 535 static lldb::OptionValuePropertiesSP 536 GetSettingForStructuredDataPlugin(Debugger &debugger, 537 llvm::StringRef setting_name); 538 539 static bool CreateSettingForStructuredDataPlugin( 540 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 541 llvm::StringRef description, bool is_global_property); 542 }; 543 544 } // namespace lldb_private 545 546 #endif // LLDB_CORE_PLUGINMANAGER_H 547