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 liblldb_PluginManager_h_
10 #define liblldb_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 <stddef.h>
23 #include <stdint.h>
24 
25 namespace lldb_private {
26 class CommandInterpreter;
27 class ConstString;
28 class Debugger;
29 class StringList;
30 
31 class PluginManager {
32 public:
33   static void Initialize();
34 
35   static void Terminate();
36 
37   // ABI
38   static bool RegisterPlugin(ConstString name, const char *description,
39                              ABICreateInstance create_callback);
40 
41   static bool UnregisterPlugin(ABICreateInstance create_callback);
42 
43   static ABICreateInstance GetABICreateCallbackAtIndex(uint32_t idx);
44 
45   static ABICreateInstance
46   GetABICreateCallbackForPluginName(ConstString name);
47 
48   // Architecture
49   using ArchitectureCreateInstance =
50       std::unique_ptr<Architecture> (*)(const ArchSpec &);
51 
52   static void RegisterPlugin(ConstString name,
53                              llvm::StringRef description,
54                              ArchitectureCreateInstance create_callback);
55 
56   static void UnregisterPlugin(ArchitectureCreateInstance create_callback);
57 
58   static std::unique_ptr<Architecture>
59   CreateArchitectureInstance(const ArchSpec &arch);
60 
61   // Disassembler
62   static bool RegisterPlugin(ConstString name, const char *description,
63                              DisassemblerCreateInstance create_callback);
64 
65   static bool UnregisterPlugin(DisassemblerCreateInstance create_callback);
66 
67   static DisassemblerCreateInstance
68   GetDisassemblerCreateCallbackAtIndex(uint32_t idx);
69 
70   static DisassemblerCreateInstance
71   GetDisassemblerCreateCallbackForPluginName(ConstString name);
72 
73   // DynamicLoader
74   static bool
75   RegisterPlugin(ConstString name, const char *description,
76                  DynamicLoaderCreateInstance create_callback,
77                  DebuggerInitializeCallback debugger_init_callback = nullptr);
78 
79   static bool UnregisterPlugin(DynamicLoaderCreateInstance create_callback);
80 
81   static DynamicLoaderCreateInstance
82   GetDynamicLoaderCreateCallbackAtIndex(uint32_t idx);
83 
84   static DynamicLoaderCreateInstance
85   GetDynamicLoaderCreateCallbackForPluginName(ConstString name);
86 
87   // JITLoader
88   static bool
89   RegisterPlugin(ConstString name, const char *description,
90                  JITLoaderCreateInstance create_callback,
91                  DebuggerInitializeCallback debugger_init_callback = nullptr);
92 
93   static bool UnregisterPlugin(JITLoaderCreateInstance create_callback);
94 
95   static JITLoaderCreateInstance
96   GetJITLoaderCreateCallbackAtIndex(uint32_t idx);
97 
98   static JITLoaderCreateInstance
99   GetJITLoaderCreateCallbackForPluginName(ConstString name);
100 
101   // EmulateInstruction
102   static bool RegisterPlugin(ConstString name, const char *description,
103                              EmulateInstructionCreateInstance create_callback);
104 
105   static bool
106   UnregisterPlugin(EmulateInstructionCreateInstance create_callback);
107 
108   static EmulateInstructionCreateInstance
109   GetEmulateInstructionCreateCallbackAtIndex(uint32_t idx);
110 
111   static EmulateInstructionCreateInstance
112   GetEmulateInstructionCreateCallbackForPluginName(ConstString name);
113 
114   // OperatingSystem
115   static bool RegisterPlugin(ConstString name, const char *description,
116                              OperatingSystemCreateInstance create_callback,
117                              DebuggerInitializeCallback debugger_init_callback);
118 
119   static bool UnregisterPlugin(OperatingSystemCreateInstance create_callback);
120 
121   static OperatingSystemCreateInstance
122   GetOperatingSystemCreateCallbackAtIndex(uint32_t idx);
123 
124   static OperatingSystemCreateInstance
125   GetOperatingSystemCreateCallbackForPluginName(ConstString name);
126 
127   // Language
128   static bool RegisterPlugin(ConstString name, const char *description,
129                              LanguageCreateInstance create_callback);
130 
131   static bool UnregisterPlugin(LanguageCreateInstance create_callback);
132 
133   static LanguageCreateInstance GetLanguageCreateCallbackAtIndex(uint32_t idx);
134 
135   static LanguageCreateInstance
136   GetLanguageCreateCallbackForPluginName(ConstString name);
137 
138   // LanguageRuntime
139   static bool RegisterPlugin(
140       ConstString name, const char *description,
141       LanguageRuntimeCreateInstance create_callback,
142       LanguageRuntimeGetCommandObject command_callback = nullptr,
143       LanguageRuntimeGetExceptionPrecondition precondition_callback = nullptr);
144 
145   static bool UnregisterPlugin(LanguageRuntimeCreateInstance create_callback);
146 
147   static LanguageRuntimeCreateInstance
148   GetLanguageRuntimeCreateCallbackAtIndex(uint32_t idx);
149 
150   static LanguageRuntimeGetCommandObject
151   GetLanguageRuntimeGetCommandObjectAtIndex(uint32_t idx);
152 
153   static LanguageRuntimeGetExceptionPrecondition
154   GetLanguageRuntimeGetExceptionPreconditionAtIndex(uint32_t idx);
155 
156   static LanguageRuntimeCreateInstance
157   GetLanguageRuntimeCreateCallbackForPluginName(ConstString name);
158 
159   // SystemRuntime
160   static bool RegisterPlugin(ConstString name, const char *description,
161                              SystemRuntimeCreateInstance create_callback);
162 
163   static bool UnregisterPlugin(SystemRuntimeCreateInstance create_callback);
164 
165   static SystemRuntimeCreateInstance
166   GetSystemRuntimeCreateCallbackAtIndex(uint32_t idx);
167 
168   static SystemRuntimeCreateInstance
169   GetSystemRuntimeCreateCallbackForPluginName(ConstString name);
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 ObjectFileCreateInstance
191   GetObjectFileCreateCallbackForPluginName(ConstString name);
192 
193   static ObjectFileCreateMemoryInstance
194   GetObjectFileCreateMemoryCallbackForPluginName(ConstString name);
195 
196   static Status SaveCore(const lldb::ProcessSP &process_sp,
197                          const FileSpec &outfile);
198 
199   // ObjectContainer
200   static bool
201   RegisterPlugin(ConstString name, const char *description,
202                  ObjectContainerCreateInstance create_callback,
203                  ObjectFileGetModuleSpecifications get_module_specifications);
204 
205   static bool UnregisterPlugin(ObjectContainerCreateInstance create_callback);
206 
207   static ObjectContainerCreateInstance
208   GetObjectContainerCreateCallbackAtIndex(uint32_t idx);
209 
210   static ObjectContainerCreateInstance
211   GetObjectContainerCreateCallbackForPluginName(ConstString name);
212 
213   static ObjectFileGetModuleSpecifications
214   GetObjectContainerGetModuleSpecificationsCallbackAtIndex(uint32_t idx);
215 
216   // Platform
217   static bool
218   RegisterPlugin(ConstString name, const char *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(ConstString name);
228 
229   static const char *GetPlatformPluginNameAtIndex(uint32_t idx);
230 
231   static const char *GetPlatformPluginDescriptionAtIndex(uint32_t idx);
232 
233   static void AutoCompletePlatformName(llvm::StringRef partial_name,
234                                        CompletionRequest &request);
235   // Process
236   static bool
237   RegisterPlugin(ConstString name, const char *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(ConstString name);
247 
248   static const char *GetProcessPluginNameAtIndex(uint32_t idx);
249 
250   static const char *GetProcessPluginDescriptionAtIndex(uint32_t idx);
251 
252   // ScriptInterpreter
253   static bool RegisterPlugin(ConstString name, const char *description,
254                              lldb::ScriptLanguage script_lang,
255                              ScriptInterpreterCreateInstance create_callback);
256 
257   static bool UnregisterPlugin(ScriptInterpreterCreateInstance create_callback);
258 
259   static ScriptInterpreterCreateInstance
260   GetScriptInterpreterCreateCallbackAtIndex(uint32_t idx);
261 
262   static lldb::ScriptInterpreterSP
263   GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang,
264                                   Debugger &debugger);
265 
266   // StructuredDataPlugin
267 
268   /// Register a StructuredDataPlugin class along with optional
269   /// callbacks for debugger initialization and Process launch info
270   /// filtering and manipulation.
271   ///
272   /// \param[in] name
273   ///    The name of the plugin.
274   ///
275   /// \param[in] description
276   ///    A description string for the plugin.
277   ///
278   /// \param[in] create_callback
279   ///    The callback that will be invoked to create an instance of
280   ///    the callback.  This may not be nullptr.
281   ///
282   /// \param[in] debugger_init_callback
283   ///    An optional callback that will be made when a Debugger
284   ///    instance is initialized.
285   ///
286   /// \param[in] filter_callback
287   ///    An optional callback that will be invoked before LLDB
288   ///    launches a process for debugging.  The callback must
289   ///    do the following:
290   ///    1. Only do something if the plugin's behavior is enabled.
291   ///    2. Only make changes for processes that are relevant to the
292   ///       plugin.  The callback gets a pointer to the Target, which
293   ///       can be inspected as needed.  The ProcessLaunchInfo is
294   ///       provided in read-write mode, and may be modified by the
295   ///       plugin if, for instance, additional environment variables
296   ///       are needed to support the feature when enabled.
297   ///
298   /// \return
299   ///    Returns true upon success; otherwise, false.
300   static bool
301   RegisterPlugin(ConstString name, const char *description,
302                  StructuredDataPluginCreateInstance create_callback,
303                  DebuggerInitializeCallback debugger_init_callback = nullptr,
304                  StructuredDataFilterLaunchInfo filter_callback = nullptr);
305 
306   static bool
307   UnregisterPlugin(StructuredDataPluginCreateInstance create_callback);
308 
309   static StructuredDataPluginCreateInstance
310   GetStructuredDataPluginCreateCallbackAtIndex(uint32_t idx);
311 
312   static StructuredDataPluginCreateInstance
313   GetStructuredDataPluginCreateCallbackForPluginName(ConstString name);
314 
315   static StructuredDataFilterLaunchInfo
316   GetStructuredDataFilterCallbackAtIndex(uint32_t idx,
317                                          bool &iteration_complete);
318 
319   // SymbolFile
320   static bool
321   RegisterPlugin(ConstString name, const char *description,
322                  SymbolFileCreateInstance create_callback,
323                  DebuggerInitializeCallback debugger_init_callback = nullptr);
324 
325   static bool UnregisterPlugin(SymbolFileCreateInstance create_callback);
326 
327   static SymbolFileCreateInstance
328   GetSymbolFileCreateCallbackAtIndex(uint32_t idx);
329 
330   static SymbolFileCreateInstance
331   GetSymbolFileCreateCallbackForPluginName(ConstString name);
332 
333   // SymbolVendor
334   static bool RegisterPlugin(ConstString name, const char *description,
335                              SymbolVendorCreateInstance create_callback);
336 
337   static bool UnregisterPlugin(SymbolVendorCreateInstance create_callback);
338 
339   static SymbolVendorCreateInstance
340   GetSymbolVendorCreateCallbackAtIndex(uint32_t idx);
341 
342   static SymbolVendorCreateInstance
343   GetSymbolVendorCreateCallbackForPluginName(ConstString name);
344 
345   // UnwindAssembly
346   static bool RegisterPlugin(ConstString name, const char *description,
347                              UnwindAssemblyCreateInstance create_callback);
348 
349   static bool UnregisterPlugin(UnwindAssemblyCreateInstance create_callback);
350 
351   static UnwindAssemblyCreateInstance
352   GetUnwindAssemblyCreateCallbackAtIndex(uint32_t idx);
353 
354   static UnwindAssemblyCreateInstance
355   GetUnwindAssemblyCreateCallbackForPluginName(ConstString name);
356 
357   // MemoryHistory
358   static bool RegisterPlugin(ConstString name, const char *description,
359                              MemoryHistoryCreateInstance create_callback);
360 
361   static bool UnregisterPlugin(MemoryHistoryCreateInstance create_callback);
362 
363   static MemoryHistoryCreateInstance
364   GetMemoryHistoryCreateCallbackAtIndex(uint32_t idx);
365 
366   static MemoryHistoryCreateInstance
367   GetMemoryHistoryCreateCallbackForPluginName(ConstString name);
368 
369   // InstrumentationRuntime
370   static bool
371   RegisterPlugin(ConstString name, const char *description,
372                  InstrumentationRuntimeCreateInstance create_callback,
373                  InstrumentationRuntimeGetType get_type_callback);
374 
375   static bool
376   UnregisterPlugin(InstrumentationRuntimeCreateInstance create_callback);
377 
378   static InstrumentationRuntimeGetType
379   GetInstrumentationRuntimeGetTypeCallbackAtIndex(uint32_t idx);
380 
381   static InstrumentationRuntimeCreateInstance
382   GetInstrumentationRuntimeCreateCallbackAtIndex(uint32_t idx);
383 
384   static InstrumentationRuntimeCreateInstance
385   GetInstrumentationRuntimeCreateCallbackForPluginName(ConstString name);
386 
387   // TypeSystem
388   static bool RegisterPlugin(ConstString name, const char *description,
389                              TypeSystemCreateInstance create_callback,
390                              LanguageSet supported_languages_for_types,
391                              LanguageSet supported_languages_for_expressions);
392 
393   static bool UnregisterPlugin(TypeSystemCreateInstance create_callback);
394 
395   static TypeSystemCreateInstance
396   GetTypeSystemCreateCallbackAtIndex(uint32_t idx);
397 
398   static TypeSystemCreateInstance
399   GetTypeSystemCreateCallbackForPluginName(ConstString name);
400 
401   static LanguageSet GetAllTypeSystemSupportedLanguagesForTypes();
402 
403   static LanguageSet GetAllTypeSystemSupportedLanguagesForExpressions();
404 
405   // REPL
406   static bool RegisterPlugin(ConstString name, const char *description,
407                              REPLCreateInstance create_callback,
408                              LanguageSet supported_languages);
409 
410   static bool UnregisterPlugin(REPLCreateInstance create_callback);
411 
412   static REPLCreateInstance GetREPLCreateCallbackAtIndex(uint32_t idx);
413 
414   static REPLCreateInstance
415   GetREPLCreateCallbackForPluginName(ConstString name);
416 
417   static LanguageSet GetREPLAllTypeSystemSupportedLanguages();
418 
419   // Some plug-ins might register a DebuggerInitializeCallback callback when
420   // registering the plug-in. After a new Debugger instance is created, this
421   // DebuggerInitialize function will get called. This allows plug-ins to
422   // install Properties and do any other initialization that requires a
423   // debugger instance.
424   static void DebuggerInitialize(Debugger &debugger);
425 
426   static lldb::OptionValuePropertiesSP
427   GetSettingForDynamicLoaderPlugin(Debugger &debugger,
428                                    ConstString setting_name);
429 
430   static bool CreateSettingForDynamicLoaderPlugin(
431       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
432       ConstString description, bool is_global_property);
433 
434   static lldb::OptionValuePropertiesSP
435   GetSettingForPlatformPlugin(Debugger &debugger, ConstString setting_name);
436 
437   static bool CreateSettingForPlatformPlugin(
438       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
439       ConstString description, bool is_global_property);
440 
441   static lldb::OptionValuePropertiesSP
442   GetSettingForProcessPlugin(Debugger &debugger, ConstString setting_name);
443 
444   static bool CreateSettingForProcessPlugin(
445       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
446       ConstString description, bool is_global_property);
447 
448   static lldb::OptionValuePropertiesSP
449   GetSettingForSymbolFilePlugin(Debugger &debugger, ConstString setting_name);
450 
451   static bool CreateSettingForSymbolFilePlugin(
452       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
453       ConstString description, bool is_global_property);
454 
455   static lldb::OptionValuePropertiesSP
456   GetSettingForJITLoaderPlugin(Debugger &debugger, ConstString setting_name);
457 
458   static bool CreateSettingForJITLoaderPlugin(
459       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
460       ConstString description, bool is_global_property);
461 
462   static lldb::OptionValuePropertiesSP
463   GetSettingForOperatingSystemPlugin(Debugger &debugger,
464                                      ConstString setting_name);
465 
466   static bool CreateSettingForOperatingSystemPlugin(
467       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
468       ConstString description, bool is_global_property);
469 
470   static lldb::OptionValuePropertiesSP
471   GetSettingForStructuredDataPlugin(Debugger &debugger,
472                                     ConstString setting_name);
473 
474   static bool CreateSettingForStructuredDataPlugin(
475       Debugger &debugger, const lldb::OptionValuePropertiesSP &properties_sp,
476       ConstString description, bool is_global_property);
477 };
478 
479 } // namespace lldb_private
480 
481 #endif // liblldb_PluginManager_h_
482