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