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