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