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 201 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 202 ObjectContainerCreateInstance create_callback, 203 ObjectFileGetModuleSpecifications get_module_specifications); 204 205 static bool UnregisterPlugin(ObjectContainerCreateInstance create_callback); 206 207 static ObjectContainerCreateInstance 208 GetObjectContainerCreateCallbackAtIndex(uint32_t idx); 209 210 static ObjectFileGetModuleSpecifications 211 GetObjectContainerGetModuleSpecificationsCallbackAtIndex(uint32_t idx); 212 213 // Platform 214 static bool 215 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 216 PlatformCreateInstance create_callback, 217 DebuggerInitializeCallback debugger_init_callback = nullptr); 218 219 static bool UnregisterPlugin(PlatformCreateInstance create_callback); 220 221 static PlatformCreateInstance GetPlatformCreateCallbackAtIndex(uint32_t idx); 222 223 static PlatformCreateInstance 224 GetPlatformCreateCallbackForPluginName(llvm::StringRef name); 225 226 static llvm::StringRef GetPlatformPluginNameAtIndex(uint32_t idx); 227 228 static llvm::StringRef GetPlatformPluginDescriptionAtIndex(uint32_t idx); 229 230 static void AutoCompletePlatformName(llvm::StringRef partial_name, 231 CompletionRequest &request); 232 // Process 233 static bool 234 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 235 ProcessCreateInstance create_callback, 236 DebuggerInitializeCallback debugger_init_callback = nullptr); 237 238 static bool UnregisterPlugin(ProcessCreateInstance create_callback); 239 240 static ProcessCreateInstance GetProcessCreateCallbackAtIndex(uint32_t idx); 241 242 static ProcessCreateInstance 243 GetProcessCreateCallbackForPluginName(llvm::StringRef name); 244 245 static llvm::StringRef GetProcessPluginNameAtIndex(uint32_t idx); 246 247 static llvm::StringRef GetProcessPluginDescriptionAtIndex(uint32_t idx); 248 249 static void AutoCompleteProcessName(llvm::StringRef partial_name, 250 CompletionRequest &request); 251 252 // ScriptInterpreter 253 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 254 lldb::ScriptLanguage script_lang, 255 ScriptInterpreterCreateInstance create_callback); 256 257 static bool UnregisterPlugin(ScriptInterpreterCreateInstance create_callback); 258 259 static ScriptInterpreterCreateInstance 260 GetScriptInterpreterCreateCallbackAtIndex(uint32_t idx); 261 262 static lldb::ScriptInterpreterSP 263 GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang, 264 Debugger &debugger); 265 266 // StructuredDataPlugin 267 268 /// Register a StructuredDataPlugin class along with optional 269 /// callbacks for debugger initialization and Process launch info 270 /// filtering and manipulation. 271 /// 272 /// \param[in] name 273 /// The name of the plugin. 274 /// 275 /// \param[in] description 276 /// A description string for the plugin. 277 /// 278 /// \param[in] create_callback 279 /// The callback that will be invoked to create an instance of 280 /// the callback. This may not be nullptr. 281 /// 282 /// \param[in] debugger_init_callback 283 /// An optional callback that will be made when a Debugger 284 /// instance is initialized. 285 /// 286 /// \param[in] filter_callback 287 /// An optional callback that will be invoked before LLDB 288 /// launches a process for debugging. The callback must 289 /// do the following: 290 /// 1. Only do something if the plugin's behavior is enabled. 291 /// 2. Only make changes for processes that are relevant to the 292 /// plugin. The callback gets a pointer to the Target, which 293 /// can be inspected as needed. The ProcessLaunchInfo is 294 /// provided in read-write mode, and may be modified by the 295 /// plugin if, for instance, additional environment variables 296 /// are needed to support the feature when enabled. 297 /// 298 /// \return 299 /// Returns true upon success; otherwise, false. 300 static bool 301 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 302 StructuredDataPluginCreateInstance create_callback, 303 DebuggerInitializeCallback debugger_init_callback = nullptr, 304 StructuredDataFilterLaunchInfo filter_callback = nullptr); 305 306 static bool 307 UnregisterPlugin(StructuredDataPluginCreateInstance create_callback); 308 309 static StructuredDataPluginCreateInstance 310 GetStructuredDataPluginCreateCallbackAtIndex(uint32_t idx); 311 312 static StructuredDataFilterLaunchInfo 313 GetStructuredDataFilterCallbackAtIndex(uint32_t idx, 314 bool &iteration_complete); 315 316 // SymbolFile 317 static bool 318 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 319 SymbolFileCreateInstance create_callback, 320 DebuggerInitializeCallback debugger_init_callback = nullptr); 321 322 static bool UnregisterPlugin(SymbolFileCreateInstance create_callback); 323 324 static SymbolFileCreateInstance 325 GetSymbolFileCreateCallbackAtIndex(uint32_t idx); 326 327 // SymbolVendor 328 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 329 SymbolVendorCreateInstance create_callback); 330 331 static bool UnregisterPlugin(SymbolVendorCreateInstance create_callback); 332 333 static SymbolVendorCreateInstance 334 GetSymbolVendorCreateCallbackAtIndex(uint32_t idx); 335 336 // Trace 337 static bool RegisterPlugin( 338 llvm::StringRef name, llvm::StringRef description, 339 TraceCreateInstanceFromBundle create_callback_from_bundle, 340 TraceCreateInstanceForLiveProcess create_callback_for_live_process, 341 llvm::StringRef schema); 342 343 static bool 344 UnregisterPlugin(TraceCreateInstanceFromBundle create_callback); 345 346 static TraceCreateInstanceFromBundle 347 GetTraceCreateCallback(llvm::StringRef plugin_name); 348 349 static TraceCreateInstanceForLiveProcess 350 GetTraceCreateCallbackForLiveProcess(llvm::StringRef plugin_name); 351 352 /// Get the JSON schema for a trace bundle description file corresponding to 353 /// the given plugin. 354 /// 355 /// \param[in] plugin_name 356 /// The name of the plugin. 357 /// 358 /// \return 359 /// An empty \a StringRef if no plugin was found with that plugin name, 360 /// otherwise the actual schema is returned. 361 static llvm::StringRef GetTraceSchema(llvm::StringRef plugin_name); 362 363 /// Get the JSON schema for a trace bundle description file corresponding to 364 /// the plugin given by its index. 365 /// 366 /// \param[in] index 367 /// The index of the plugin to get the schema of. 368 /// 369 /// \return 370 /// An empty \a StringRef if the index is greater than or equal to the 371 /// number plugins, otherwise the actual schema is returned. 372 static llvm::StringRef GetTraceSchema(size_t index); 373 374 // TraceExporter 375 376 /// \param[in] create_thread_trace_export_command 377 /// This callback is used to create a CommandObject that will be listed 378 /// under "thread trace export". Can be \b null. 379 static bool RegisterPlugin( 380 llvm::StringRef name, llvm::StringRef description, 381 TraceExporterCreateInstance create_callback, 382 ThreadTraceExportCommandCreator create_thread_trace_export_command); 383 384 static TraceExporterCreateInstance 385 GetTraceExporterCreateCallback(llvm::StringRef plugin_name); 386 387 static bool UnregisterPlugin(TraceExporterCreateInstance create_callback); 388 389 static llvm::StringRef GetTraceExporterPluginNameAtIndex(uint32_t index); 390 391 /// Return the callback used to create the CommandObject that will be listed 392 /// under "thread trace export". Can be \b null. 393 static ThreadTraceExportCommandCreator 394 GetThreadTraceExportCommandCreatorAtIndex(uint32_t index); 395 396 // UnwindAssembly 397 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 398 UnwindAssemblyCreateInstance create_callback); 399 400 static bool UnregisterPlugin(UnwindAssemblyCreateInstance create_callback); 401 402 static UnwindAssemblyCreateInstance 403 GetUnwindAssemblyCreateCallbackAtIndex(uint32_t idx); 404 405 // MemoryHistory 406 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 407 MemoryHistoryCreateInstance create_callback); 408 409 static bool UnregisterPlugin(MemoryHistoryCreateInstance create_callback); 410 411 static MemoryHistoryCreateInstance 412 GetMemoryHistoryCreateCallbackAtIndex(uint32_t idx); 413 414 // InstrumentationRuntime 415 static bool 416 RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 417 InstrumentationRuntimeCreateInstance create_callback, 418 InstrumentationRuntimeGetType get_type_callback); 419 420 static bool 421 UnregisterPlugin(InstrumentationRuntimeCreateInstance create_callback); 422 423 static InstrumentationRuntimeGetType 424 GetInstrumentationRuntimeGetTypeCallbackAtIndex(uint32_t idx); 425 426 static InstrumentationRuntimeCreateInstance 427 GetInstrumentationRuntimeCreateCallbackAtIndex(uint32_t idx); 428 429 // TypeSystem 430 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 431 TypeSystemCreateInstance create_callback, 432 LanguageSet supported_languages_for_types, 433 LanguageSet supported_languages_for_expressions); 434 435 static bool UnregisterPlugin(TypeSystemCreateInstance create_callback); 436 437 static TypeSystemCreateInstance 438 GetTypeSystemCreateCallbackAtIndex(uint32_t idx); 439 440 static LanguageSet GetAllTypeSystemSupportedLanguagesForTypes(); 441 442 static LanguageSet GetAllTypeSystemSupportedLanguagesForExpressions(); 443 444 // REPL 445 static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description, 446 REPLCreateInstance create_callback, 447 LanguageSet supported_languages); 448 449 static bool UnregisterPlugin(REPLCreateInstance create_callback); 450 451 static REPLCreateInstance GetREPLCreateCallbackAtIndex(uint32_t idx); 452 453 static LanguageSet GetREPLSupportedLanguagesAtIndex(uint32_t idx); 454 455 static LanguageSet GetREPLAllTypeSystemSupportedLanguages(); 456 457 // Some plug-ins might register a DebuggerInitializeCallback callback when 458 // registering the plug-in. After a new Debugger instance is created, this 459 // DebuggerInitialize function will get called. This allows plug-ins to 460 // install Properties and do any other initialization that requires a 461 // debugger instance. 462 static void DebuggerInitialize(Debugger &debugger); 463 464 static lldb::OptionValuePropertiesSP 465 GetSettingForDynamicLoaderPlugin(Debugger &debugger, 466 ConstString setting_name); 467 468 static bool CreateSettingForDynamicLoaderPlugin( 469 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 470 ConstString description, bool is_global_property); 471 472 static lldb::OptionValuePropertiesSP 473 GetSettingForPlatformPlugin(Debugger &debugger, ConstString setting_name); 474 475 static bool CreateSettingForPlatformPlugin( 476 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 477 ConstString description, bool is_global_property); 478 479 static lldb::OptionValuePropertiesSP 480 GetSettingForProcessPlugin(Debugger &debugger, ConstString setting_name); 481 482 static bool CreateSettingForProcessPlugin( 483 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 484 ConstString description, bool is_global_property); 485 486 static lldb::OptionValuePropertiesSP 487 GetSettingForObjectFilePlugin(Debugger &debugger, ConstString setting_name); 488 489 static bool CreateSettingForObjectFilePlugin( 490 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 491 ConstString description, bool is_global_property); 492 493 static lldb::OptionValuePropertiesSP 494 GetSettingForSymbolFilePlugin(Debugger &debugger, ConstString setting_name); 495 496 static bool CreateSettingForSymbolFilePlugin( 497 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 498 ConstString description, bool is_global_property); 499 500 static lldb::OptionValuePropertiesSP 501 GetSettingForJITLoaderPlugin(Debugger &debugger, ConstString setting_name); 502 503 static bool CreateSettingForJITLoaderPlugin( 504 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 505 ConstString description, bool is_global_property); 506 507 static lldb::OptionValuePropertiesSP 508 GetSettingForOperatingSystemPlugin(Debugger &debugger, 509 ConstString setting_name); 510 511 static bool CreateSettingForOperatingSystemPlugin( 512 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 513 ConstString description, bool is_global_property); 514 515 static lldb::OptionValuePropertiesSP 516 GetSettingForStructuredDataPlugin(Debugger &debugger, 517 ConstString setting_name); 518 519 static bool CreateSettingForStructuredDataPlugin( 520 Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp, 521 ConstString description, bool is_global_property); 522 }; 523 524 } // namespace lldb_private 525 526 #endif // LLDB_CORE_PLUGINMANAGER_H 527