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