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