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