ExecutionEngine/Orc/DebugObjectManagerPlugin.h

0001 //===---- DebugObjectManagerPlugin.h - JITLink debug objects ---*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // ObjectLinkingLayer plugin for emitting debug objects.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_EXECUTIONENGINE_ORC_DEBUGOBJECTMANAGERPLUGIN_H
0014 #define LLVM_EXECUTIONENGINE_ORC_DEBUGOBJECTMANAGERPLUGIN_H
0015
0016 #include "llvm/ExecutionEngine/JITLink/JITLink.h"
0017 #include "llvm/ExecutionEngine/Orc/Core.h"
0018 #include "llvm/ExecutionEngine/Orc/EPCDebugObjectRegistrar.h"
0019 #include "llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h"
0020 #include "llvm/Support/Error.h"
0021 #include "llvm/Support/Memory.h"
0022 #include "llvm/Support/MemoryBufferRef.h"
0023 #include "llvm/TargetParser/Triple.h"
0024
0025 #include <functional>
0026 #include <map>
0027 #include <memory>
0028 #include <mutex>
0029
0030 namespace llvm {
0031 namespace orc {
0032
0033 class DebugObject;
0034
0035 /// Creates and manages DebugObjects for JITLink artifacts.
0036 ///
0037 /// DebugObjects are created when linking for a MaterializationResponsibility
0038 /// starts. They are pending as long as materialization is in progress.
0039 ///
0040 /// There can only be one pending DebugObject per MaterializationResponsibility.
0041 /// If materialization fails, pending DebugObjects are discarded.
0042 ///
0043 /// Once executable code for the MaterializationResponsibility is emitted, the
0044 /// corresponding DebugObject is finalized to target memory and the provided
0045 /// DebugObjectRegistrar is notified. Ownership of DebugObjects remains with the
0046 /// plugin.
0047 ///
0048 class DebugObjectManagerPlugin : public ObjectLinkingLayer::Plugin {
0049 public:
0050   // DEPRECATED - Please specify options explicitly
0051   DebugObjectManagerPlugin(ExecutionSession &ES,
0052                            std::unique_ptr<DebugObjectRegistrar> Target);
0053
0054   /// Create the plugin to submit DebugObjects for JITLink artifacts. For all
0055   /// options the recommended setting is true.
0056   ///
0057   /// RequireDebugSections:
0058   ///   Submit debug objects to the executor only if they contain actual debug
0059   ///   info. Turning this off may allow minimal debugging based on raw symbol
0060   ///   names. Note that this may cause significant memory and transport
0061   ///   overhead for objects built with a release configuration.
0062   ///
0063   /// AutoRegisterCode:
0064   ///   Notify the debugger for each new debug object. This is a good default
0065   ///   mode, but it may cause significant overhead when adding many modules in
0066   ///   sequence. When turning this off, the user has to issue the call to
0067   ///   __jit_debug_register_code() on the executor side manually.
0068   ///
0069   DebugObjectManagerPlugin(ExecutionSession &ES,
0070                            std::unique_ptr<DebugObjectRegistrar> Target,
0071                            bool RequireDebugSections, bool AutoRegisterCode);
0072   ~DebugObjectManagerPlugin();
0073
0074   void notifyMaterializing(MaterializationResponsibility &MR,
0075                            jitlink::LinkGraph &G, jitlink::JITLinkContext &Ctx,
0076                            MemoryBufferRef InputObject) override;
0077
0078   Error notifyEmitted(MaterializationResponsibility &MR) override;
0079   Error notifyFailed(MaterializationResponsibility &MR) override;
0080   Error notifyRemovingResources(JITDylib &JD, ResourceKey K) override;
0081
0082   void notifyTransferringResources(JITDylib &JD, ResourceKey DstKey,
0083                                    ResourceKey SrcKey) override;
0084
0085   void modifyPassConfig(MaterializationResponsibility &MR,
0086                         jitlink::LinkGraph &LG,
0087                         jitlink::PassConfiguration &PassConfig) override;
0088
0089 private:
0090   ExecutionSession &ES;
0091
0092   using OwnedDebugObject = std::unique_ptr<DebugObject>;
0093   std::map<MaterializationResponsibility *, OwnedDebugObject> PendingObjs;
0094   std::map<ResourceKey, std::vector<OwnedDebugObject>> RegisteredObjs;
0095
0096   std::mutex PendingObjsLock;
0097   std::mutex RegisteredObjsLock;
0098
0099   std::unique_ptr<DebugObjectRegistrar> Target;
0100   bool RequireDebugSections;
0101   bool AutoRegisterCode;
0102 };
0103
0104 } // namespace orc
0105 } // namespace llvm
0106
0107 #endif // LLVM_EXECUTIONENGINE_ORC_DEBUGOBJECTMANAGERPLUGIN_H