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