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