1 //===-- PluginManager.h -----------------------------------------*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef liblldb_PluginManager_h_
11 #define liblldb_PluginManager_h_
12 
13 #include "lldb/Core/Architecture.h"
14 #include "lldb/Utility/FileSpec.h"
15 #include "lldb/Utility/Status.h"
16 #include "lldb/lldb-enumerations.h"
17 #include "lldb/lldb-forward.h"
18 #include "lldb/lldb-private-interfaces.h"
19 #include "llvm/ADT/StringRef.h"
20 
21 #include <stddef.h>
22 #include <stdint.h>
23 
24 namespace lldb_private {
25 class CommandInterpreter;
26 }
27 namespace lldb_private {
28 class ConstString;
29 }
30 namespace lldb_private {
31 class Debugger;
32 }
33 namespace lldb_private {
34 class StringList;
35 }
36 namespace lldb_private {
37 
38 class PluginManager {
39 public:
40   static void Initialize();
41 
42   static void Terminate();
43 
44   //------------------------------------------------------------------
45   // ABI
46   //------------------------------------------------------------------
47   static bool RegisterPlugin(const ConstString &name, const char *description,
48                              ABICreateInstance create_callback);
49 
50   static bool UnregisterPlugin(ABICreateInstance create_callback);
51 
52   static ABICreateInstance GetABICreateCallbackAtIndex(uint32_t idx);
53 
54   static ABICreateInstance
55   GetABICreateCallbackForPluginName(const ConstString &name);
56 
57   //------------------------------------------------------------------
58   // Architecture
59   //------------------------------------------------------------------
60   using ArchitectureCreateInstance =
61       std::unique_ptr<Architecture> (*)(const ArchSpec &);
62 
63   static void RegisterPlugin(const ConstString &name,
64                              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   //------------------------------------------------------------------
73   // Disassembler
74   //------------------------------------------------------------------
75   static bool RegisterPlugin(const ConstString &name, const char *description,
76                              DisassemblerCreateInstance create_callback);
77 
78   static bool UnregisterPlugin(DisassemblerCreateInstance create_callback);
79 
80   static DisassemblerCreateInstance
81   GetDisassemblerCreateCallbackAtIndex(uint32_t idx);
82 
83   static DisassemblerCreateInstance
84   GetDisassemblerCreateCallbackForPluginName(const ConstString &name);
85 
86   //------------------------------------------------------------------
87   // DynamicLoader
88   //------------------------------------------------------------------
89   static bool
90   RegisterPlugin(const ConstString &name, const char *description,
91                  DynamicLoaderCreateInstance create_callback,
92                  DebuggerInitializeCallback debugger_init_callback = nullptr);
93 
94   static bool UnregisterPlugin(DynamicLoaderCreateInstance create_callback);
95 
96   static DynamicLoaderCreateInstance
97   GetDynamicLoaderCreateCallbackAtIndex(uint32_t idx);
98 
99   static DynamicLoaderCreateInstance
100   GetDynamicLoaderCreateCallbackForPluginName(const ConstString &name);
101 
102   //------------------------------------------------------------------
103   // JITLoader
104   //------------------------------------------------------------------
105   static bool
106   RegisterPlugin(const ConstString &name, const char *description,
107                  JITLoaderCreateInstance create_callback,
108                  DebuggerInitializeCallback debugger_init_callback = nullptr);
109 
110   static bool UnregisterPlugin(JITLoaderCreateInstance create_callback);
111 
112   static JITLoaderCreateInstance
113   GetJITLoaderCreateCallbackAtIndex(uint32_t idx);
114 
115   static JITLoaderCreateInstance
116   GetJITLoaderCreateCallbackForPluginName(const ConstString &name);
117 
118   //------------------------------------------------------------------
119   // EmulateInstruction
120   //------------------------------------------------------------------
121   static bool RegisterPlugin(const ConstString &name, const char *description,
122                              EmulateInstructionCreateInstance create_callback);
123 
124   static bool
125   UnregisterPlugin(EmulateInstructionCreateInstance create_callback);
126 
127   static EmulateInstructionCreateInstance
128   GetEmulateInstructionCreateCallbackAtIndex(uint32_t idx);
129 
130   static EmulateInstructionCreateInstance
131   GetEmulateInstructionCreateCallbackForPluginName(const ConstString &name);
132 
133   //------------------------------------------------------------------
134   // OperatingSystem
135   //------------------------------------------------------------------
136   static bool RegisterPlugin(const ConstString &name, const char *description,
137                              OperatingSystemCreateInstance create_callback,
138                              DebuggerInitializeCallback debugger_init_callback);
139 
140   static bool UnregisterPlugin(OperatingSystemCreateInstance create_callback);
141 
142   static OperatingSystemCreateInstance
143   GetOperatingSystemCreateCallbackAtIndex(uint32_t idx);
144 
145   static OperatingSystemCreateInstance
146   GetOperatingSystemCreateCallbackForPluginName(const ConstString &name);
147 
148   //------------------------------------------------------------------
149   // Language
150   //------------------------------------------------------------------
151   static bool RegisterPlugin(const ConstString &name, const char *description,
152                              LanguageCreateInstance create_callback);
153 
154   static bool UnregisterPlugin(LanguageCreateInstance create_callback);
155 
156   static LanguageCreateInstance GetLanguageCreateCallbackAtIndex(uint32_t idx);
157 
158   static LanguageCreateInstance
159   GetLanguageCreateCallbackForPluginName(const ConstString &name);
160 
161   //------------------------------------------------------------------
162   // LanguageRuntime
163   //------------------------------------------------------------------
164   static bool
165   RegisterPlugin(const ConstString &name, const char *description,
166                  LanguageRuntimeCreateInstance create_callback,
167                  LanguageRuntimeGetCommandObject command_callback = nullptr);
168 
169   static bool UnregisterPlugin(LanguageRuntimeCreateInstance create_callback);
170 
171   static LanguageRuntimeCreateInstance
172   GetLanguageRuntimeCreateCallbackAtIndex(uint32_t idx);
173 
174   static LanguageRuntimeGetCommandObject
175   GetLanguageRuntimeGetCommandObjectAtIndex(uint32_t idx);
176 
177   static LanguageRuntimeCreateInstance
178   GetLanguageRuntimeCreateCallbackForPluginName(const ConstString &name);
179 
180   //------------------------------------------------------------------
181   // SystemRuntime
182   //------------------------------------------------------------------
183   static bool RegisterPlugin(const ConstString &name, const char *description,
184                              SystemRuntimeCreateInstance create_callback);
185 
186   static bool UnregisterPlugin(SystemRuntimeCreateInstance create_callback);
187 
188   static SystemRuntimeCreateInstance
189   GetSystemRuntimeCreateCallbackAtIndex(uint32_t idx);
190 
191   static SystemRuntimeCreateInstance
192   GetSystemRuntimeCreateCallbackForPluginName(const ConstString &name);
193 
194   //------------------------------------------------------------------
195   // ObjectFile
196   //------------------------------------------------------------------
197   static bool
198   RegisterPlugin(const ConstString &name, const char *description,
199                  ObjectFileCreateInstance create_callback,
200                  ObjectFileCreateMemoryInstance create_memory_callback,
201                  ObjectFileGetModuleSpecifications get_module_specifications,
202                  ObjectFileSaveCore save_core = nullptr);
203 
204   static bool UnregisterPlugin(ObjectFileCreateInstance create_callback);
205 
206   static ObjectFileCreateInstance
207   GetObjectFileCreateCallbackAtIndex(uint32_t idx);
208 
209   static ObjectFileCreateMemoryInstance
210   GetObjectFileCreateMemoryCallbackAtIndex(uint32_t idx);
211 
212   static ObjectFileGetModuleSpecifications
213   GetObjectFileGetModuleSpecificationsCallbackAtIndex(uint32_t idx);
214 
215   static ObjectFileCreateInstance
216   GetObjectFileCreateCallbackForPluginName(const ConstString &name);
217 
218   static ObjectFileCreateMemoryInstance
219   GetObjectFileCreateMemoryCallbackForPluginName(const ConstString &name);
220 
221   static Status SaveCore(const lldb::ProcessSP &process_sp,
222                          const FileSpec &outfile);
223 
224   //------------------------------------------------------------------
225   // ObjectContainer
226   //------------------------------------------------------------------
227   static bool
228   RegisterPlugin(const ConstString &name, const char *description,
229                  ObjectContainerCreateInstance create_callback,
230                  ObjectFileGetModuleSpecifications get_module_specifications);
231 
232   static bool UnregisterPlugin(ObjectContainerCreateInstance create_callback);
233 
234   static ObjectContainerCreateInstance
235   GetObjectContainerCreateCallbackAtIndex(uint32_t idx);
236 
237   static ObjectContainerCreateInstance
238   GetObjectContainerCreateCallbackForPluginName(const ConstString &name);
239 
240   static ObjectFileGetModuleSpecifications
241   GetObjectContainerGetModuleSpecificationsCallbackAtIndex(uint32_t idx);
242 
243   //------------------------------------------------------------------
244   // Platform
245   //------------------------------------------------------------------
246   static bool
247   RegisterPlugin(const ConstString &name, const char *description,
248                  PlatformCreateInstance create_callback,
249                  DebuggerInitializeCallback debugger_init_callback = nullptr);
250 
251   static bool UnregisterPlugin(PlatformCreateInstance create_callback);
252 
253   static PlatformCreateInstance GetPlatformCreateCallbackAtIndex(uint32_t idx);
254 
255   static PlatformCreateInstance
256   GetPlatformCreateCallbackForPluginName(const ConstString &name);
257 
258   static const char *GetPlatformPluginNameAtIndex(uint32_t idx);
259 
260   static const char *GetPlatformPluginDescriptionAtIndex(uint32_t idx);
261 
262   static size_t AutoCompletePlatformName(llvm::StringRef partial_name,
263                                          StringList &matches);
264   //------------------------------------------------------------------
265   // Process
266   //------------------------------------------------------------------
267   static bool
268   RegisterPlugin(const ConstString &name, const char *description,
269                  ProcessCreateInstance create_callback,
270                  DebuggerInitializeCallback debugger_init_callback = nullptr);
271 
272   static bool UnregisterPlugin(ProcessCreateInstance create_callback);
273 
274   static ProcessCreateInstance GetProcessCreateCallbackAtIndex(uint32_t idx);
275 
276   static ProcessCreateInstance
277   GetProcessCreateCallbackForPluginName(const ConstString &name);
278 
279   static const char *GetProcessPluginNameAtIndex(uint32_t idx);
280 
281   static const char *GetProcessPluginDescriptionAtIndex(uint32_t idx);
282 
283   //------------------------------------------------------------------
284   // ScriptInterpreter
285   //------------------------------------------------------------------
286   static bool RegisterPlugin(const ConstString &name, const char *description,
287                              lldb::ScriptLanguage script_lang,
288                              ScriptInterpreterCreateInstance create_callback);
289 
290   static bool UnregisterPlugin(ScriptInterpreterCreateInstance create_callback);
291 
292   static ScriptInterpreterCreateInstance
293   GetScriptInterpreterCreateCallbackAtIndex(uint32_t idx);
294 
295   static lldb::ScriptInterpreterSP
296   GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang,
297                                   CommandInterpreter &interpreter);
298 
299   //------------------------------------------------------------------
300   // StructuredDataPlugin
301   //------------------------------------------------------------------
302 
303   //------------------------------------------------------------------
304   /// Register a StructuredDataPlugin class along with optional
305   /// callbacks for debugger initialization and Process launch info
306   /// filtering and manipulation.
307   ///
308   /// @param[in] name
309   ///    The name of the plugin.
310   ///
311   /// @param[in] description
312   ///    A description string for the plugin.
313   ///
314   /// @param[in] create_callback
315   ///    The callback that will be invoked to create an instance of
316   ///    the callback.  This may not be nullptr.
317   ///
318   /// @param[in] debugger_init_callback
319   ///    An optional callback that will be made when a Debugger
320   ///    instance is initialized.
321   ///
322   /// @param[in] filter_callback
323   ///    An optional callback that will be invoked before LLDB
324   ///    launches a process for debugging.  The callback must
325   ///    do the following:
326   ///    1. Only do something if the plugin's behavior is enabled.
327   ///    2. Only make changes for processes that are relevant to the
328   ///       plugin.  The callback gets a pointer to the Target, which
329   ///       can be inspected as needed.  The ProcessLaunchInfo is
330   ///       provided in read-write mode, and may be modified by the
331   ///       plugin if, for instance, additional environment variables
332   ///       are needed to support the feature when enabled.
333   ///
334   /// @return
335   ///    Returns true upon success; otherwise, false.
336   //------------------------------------------------------------------
337   static bool
338   RegisterPlugin(const ConstString &name, const char *description,
339                  StructuredDataPluginCreateInstance create_callback,
340                  DebuggerInitializeCallback debugger_init_callback = nullptr,
341                  StructuredDataFilterLaunchInfo filter_callback = nullptr);
342 
343   static bool
344   UnregisterPlugin(StructuredDataPluginCreateInstance create_callback);
345 
346   static StructuredDataPluginCreateInstance
347   GetStructuredDataPluginCreateCallbackAtIndex(uint32_t idx);
348 
349   static StructuredDataPluginCreateInstance
350   GetStructuredDataPluginCreateCallbackForPluginName(const ConstString &name);
351 
352   static StructuredDataFilterLaunchInfo
353   GetStructuredDataFilterCallbackAtIndex(uint32_t idx,
354                                          bool &iteration_complete);
355 
356   //------------------------------------------------------------------
357   // SymbolFile
358   //------------------------------------------------------------------
359   static bool
360   RegisterPlugin(const ConstString &name, const char *description,
361                  SymbolFileCreateInstance create_callback,
362                  DebuggerInitializeCallback debugger_init_callback = nullptr);
363 
364   static bool UnregisterPlugin(SymbolFileCreateInstance create_callback);
365 
366   static SymbolFileCreateInstance
367   GetSymbolFileCreateCallbackAtIndex(uint32_t idx);
368 
369   static SymbolFileCreateInstance
370   GetSymbolFileCreateCallbackForPluginName(const ConstString &name);
371 
372   //------------------------------------------------------------------
373   // SymbolVendor
374   //------------------------------------------------------------------
375   static bool RegisterPlugin(const ConstString &name, const char *description,
376                              SymbolVendorCreateInstance create_callback);
377 
378   static bool UnregisterPlugin(SymbolVendorCreateInstance create_callback);
379 
380   static SymbolVendorCreateInstance
381   GetSymbolVendorCreateCallbackAtIndex(uint32_t idx);
382 
383   static SymbolVendorCreateInstance
384   GetSymbolVendorCreateCallbackForPluginName(const ConstString &name);
385 
386   //------------------------------------------------------------------
387   // UnwindAssembly
388   //------------------------------------------------------------------
389   static bool RegisterPlugin(const ConstString &name, const char *description,
390                              UnwindAssemblyCreateInstance create_callback);
391 
392   static bool UnregisterPlugin(UnwindAssemblyCreateInstance create_callback);
393 
394   static UnwindAssemblyCreateInstance
395   GetUnwindAssemblyCreateCallbackAtIndex(uint32_t idx);
396 
397   static UnwindAssemblyCreateInstance
398   GetUnwindAssemblyCreateCallbackForPluginName(const ConstString &name);
399 
400   //------------------------------------------------------------------
401   // MemoryHistory
402   //------------------------------------------------------------------
403   static bool RegisterPlugin(const ConstString &name, const char *description,
404                              MemoryHistoryCreateInstance create_callback);
405 
406   static bool UnregisterPlugin(MemoryHistoryCreateInstance create_callback);
407 
408   static MemoryHistoryCreateInstance
409   GetMemoryHistoryCreateCallbackAtIndex(uint32_t idx);
410 
411   static MemoryHistoryCreateInstance
412   GetMemoryHistoryCreateCallbackForPluginName(const ConstString &name);
413 
414   //------------------------------------------------------------------
415   // InstrumentationRuntime
416   //------------------------------------------------------------------
417   static bool
418   RegisterPlugin(const ConstString &name, const char *description,
419                  InstrumentationRuntimeCreateInstance create_callback,
420                  InstrumentationRuntimeGetType get_type_callback);
421 
422   static bool
423   UnregisterPlugin(InstrumentationRuntimeCreateInstance create_callback);
424 
425   static InstrumentationRuntimeGetType
426   GetInstrumentationRuntimeGetTypeCallbackAtIndex(uint32_t idx);
427 
428   static InstrumentationRuntimeCreateInstance
429   GetInstrumentationRuntimeCreateCallbackAtIndex(uint32_t idx);
430 
431   static InstrumentationRuntimeCreateInstance
432   GetInstrumentationRuntimeCreateCallbackForPluginName(const ConstString &name);
433 
434   //------------------------------------------------------------------
435   // TypeSystem
436   //------------------------------------------------------------------
437   static bool RegisterPlugin(
438       const ConstString &name, const char *description,
439       TypeSystemCreateInstance create_callback,
440       TypeSystemEnumerateSupportedLanguages enumerate_languages_callback);
441 
442   static bool UnregisterPlugin(TypeSystemCreateInstance create_callback);
443 
444   static TypeSystemCreateInstance
445   GetTypeSystemCreateCallbackAtIndex(uint32_t idx);
446 
447   static TypeSystemCreateInstance
448   GetTypeSystemCreateCallbackForPluginName(const ConstString &name);
449 
450   static TypeSystemEnumerateSupportedLanguages
451   GetTypeSystemEnumerateSupportedLanguagesCallbackAtIndex(uint32_t idx);
452 
453   static TypeSystemEnumerateSupportedLanguages
454   GetTypeSystemEnumerateSupportedLanguagesCallbackForPluginName(
455       const ConstString &name);
456 
457   //------------------------------------------------------------------
458   // REPL
459   //------------------------------------------------------------------
460   static bool
461   RegisterPlugin(const ConstString &name, const char *description,
462                  REPLCreateInstance create_callback,
463                  REPLEnumerateSupportedLanguages enumerate_languages_callback);
464 
465   static bool UnregisterPlugin(REPLCreateInstance create_callback);
466 
467   static REPLCreateInstance GetREPLCreateCallbackAtIndex(uint32_t idx);
468 
469   static REPLCreateInstance
470   GetREPLCreateCallbackForPluginName(const ConstString &name);
471 
472   static REPLEnumerateSupportedLanguages
473   GetREPLEnumerateSupportedLanguagesCallbackAtIndex(uint32_t idx);
474 
475   static REPLEnumerateSupportedLanguages
476   GetREPLSystemEnumerateSupportedLanguagesCallbackForPluginName(
477       const ConstString &name);
478 
479   //------------------------------------------------------------------
480   // Some plug-ins might register a DebuggerInitializeCallback callback when
481   // registering the plug-in. After a new Debugger instance is created, this
482   // DebuggerInitialize function will get called. This allows plug-ins to
483   // install Properties and do any other initialization that requires a
484   // debugger instance.
485   //------------------------------------------------------------------
486   static void DebuggerInitialize(Debugger &debugger);
487 
488   static lldb::OptionValuePropertiesSP
489   GetSettingForDynamicLoaderPlugin(Debugger &debugger,
490                                    const ConstString &setting_name);
491 
492   static bool CreateSettingForDynamicLoaderPlugin(
493       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
494       const ConstString &description, bool is_global_property);
495 
496   static lldb::OptionValuePropertiesSP
497   GetSettingForPlatformPlugin(Debugger &debugger,
498                               const ConstString &setting_name);
499 
500   static bool CreateSettingForPlatformPlugin(
501       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
502       const ConstString &description, bool is_global_property);
503 
504   static lldb::OptionValuePropertiesSP
505   GetSettingForProcessPlugin(Debugger &debugger,
506                              const ConstString &setting_name);
507 
508   static bool CreateSettingForProcessPlugin(
509       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
510       const ConstString &description, bool is_global_property);
511 
512   static lldb::OptionValuePropertiesSP
513   GetSettingForSymbolFilePlugin(Debugger &debugger,
514                                 const ConstString &setting_name);
515 
516   static bool CreateSettingForSymbolFilePlugin(
517       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
518       const ConstString &description, bool is_global_property);
519 
520   static lldb::OptionValuePropertiesSP
521   GetSettingForJITLoaderPlugin(Debugger &debugger,
522                                const ConstString &setting_name);
523 
524   static bool CreateSettingForJITLoaderPlugin(
525       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
526       const ConstString &description, bool is_global_property);
527 
528   static lldb::OptionValuePropertiesSP
529   GetSettingForOperatingSystemPlugin(Debugger &debugger,
530                                      const ConstString &setting_name);
531 
532   static bool CreateSettingForOperatingSystemPlugin(
533       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
534       const ConstString &description, bool is_global_property);
535 
536   static lldb::OptionValuePropertiesSP
537   GetSettingForStructuredDataPlugin(Debugger &debugger,
538                                     const ConstString &setting_name);
539 
540   static bool CreateSettingForStructuredDataPlugin(
541       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
542       const ConstString &description, bool is_global_property);
543 };
544 
545 } // namespace lldb_private
546 
547 #endif // liblldb_PluginManager_h_
548