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