[WIP] Implement JITLoaderGDB ObjectLinkingLayer plugin for ELF x86-64

[sgraenitz]

Summary

First proposal for debugging support in JITLink. For now, only in-process x86-64 ELF. Please consider it a work-in-progress.

The JITLinkGDBLoaderPlugin forwards object files from ObjectLinkingLayer to an attached debugger through the GDB JIT Interface [1]. It implements ObjectLinkingLayer::Plugin::notifyLoaded() and expects an additional argument: a callback function that prepares a in-memory debug object for the given MaterializationResponsibility on request. The patch aims to keep overhead in generic execution paths minimal. Additional efforts for debug registration should reside in the callback.

Furthermore, responsibility for the preparation of the actual debug object buffer lies with the respective JITLink backend, so we can keep all format/architecture-specific code in one place. In this first sketch it's accomplished with another callback from linkPhase1 to the backend. While the JITLinkContext might be considered the natural owner of the function pointer, it is currently stored in the LinkGraph, because this is our only connection to the backend. The goal was to keep patch small and seek feedback first.

[1] https://sourceware.org/gdb/current/onlinedocs/gdb/JIT-Interface.html

[sgraenitz]

This should work with the current state:

> cat jitbp.cpp
int jitbp() { return 0; }
int main() { return jitbp(); }
> clang -c -g -fPIC --target=x86_64-unknown-unknown-elf -o jitbp.o jitbp.cpp
> bin/lldb -o 'settings set plugin.jit-loader.gdb.enable on' -o 'b runAsMain' -o 'run jitbp.o' bin/llvm-jitlink
Process 65394 stopped
(lldb) b jitbp
Breakpoint 2: where = JIT(0x7ffff7fcd000)`jitbp() + 6 at jitbp.cpp:1:15, address = 0x00007ffff7fce006
(lldb) c
Process 65394 resuming
(lldb) Process 65394 stopped
* thread #1, name = 'llvm-jitlink', stop reason = breakpoint 2.1
    frame #0: 0x00007ffff7fce006 JIT(0x7ffff7fcd000)`jitbp() at jitbp.cpp:1:15
-> 1    int jitbp() { return 0; }
   2    int main() { return jitbp(); }

[lhames]

This is very exciting.

This is adopting RuntimeDyld's approach of patching section addresses to inform the debugger about final locations. I think this is ideal for a prototype, but probably not the right approach to the final version. I've only got two loosely formed thoughts on this so far:

(1) We shouldn't special-case the JITLinkContext callbacks except as a last resort. If we have to use them at all we should prefer making any information required available via generic structures like the LinkGraph. In this case I think you could build a SectionRange for each JITLink::Section rather than rely on the SegmentLayout.

(2) If we constructed the debug object file from scratch (rather than mutating the existing one) then we could

• support debug info for raw LinkGraphs (very attractive for long term performance -- avoids serializing / deserializing to objects),
• reduce memory usage by not redundantly representing non-debug sections in the debug object
• potentially dead strip debug info to further reduce memory overhead

Whether any of this is reasonable, and how much would it would be is another question. Probably time for me to learn some DWARF. :)

Dave -- do you have any immediate thoughts?

[sgraenitz]

Hi Lang, thanks for your feedback!

In D96627#2561402, @lhames wrote:

(2) If we constructed the debug object file from scratch (rather than mutating the existing one)

Let me see if I understand that right. At the moment LinkGraphBuilder skips DWARF sections in createNormalizedSections() so they will not appear in the linker's resulting target memory allocation. Instead we decide about requesting the debug object i the plugin after we built the LinkGraph and make a separate allocation for it. You propose that we could change that and let the LinkGraph prepare the debug sections in a format that could be passed to the debugger? The plugin could query the target memory addresses from the LinkGraph and pass them to the debugger.

I think we'd still need to patch section addresses to inform the debugger about final locations, but otherwise it sounds reasonable. We will need a way to tell the LinkGraphBuilder whether or not to include them (i.e. the ObjectLinkingLayer plugin is present/enabled or not) in order to avoid overhead in non-debug sessions right? ObjectLinkingLayer::emit() could accomplish it by passing a flag to createLinkGraphFromObject(), but I don't see a way to hook into it from a plugin context currently. How could we solve that?

(1) We shouldn't special-case the JITLinkContext callbacks except as a last resort.

We'd avoid the extra callback parameter in notifyLoaded(), but we'd need some other API function instead. Or would you propose not to use an ObjectLinkingLayer plugin altogether?

• support debug info for raw LinkGraphs (very attractive for long term performance -- avoids serializing / deserializing to objects),

Oh interesting. Thinking about synthetic debug info for compiler/linker injected code..

• reduce memory usage by not redundantly representing non-debug sections in the debug object

I think we could already strip them in the current approach. LLDB at least doesn't seem to touch it.

[lhames]

In D96627#2562274, @sgraenitz wrote:

Hi Lang, thanks for your feedback!

In D96627#2561402, @lhames wrote:

(2) If we constructed the debug object file from scratch (rather than mutating the existing one)

Let me see if I understand that right. At the moment LinkGraphBuilder skips DWARF sections in createNormalizedSections() so they will not appear in the linker's resulting target memory allocation. Instead we decide about requesting the debug object i the plugin after we built the LinkGraph and make a separate allocation for it. You propose that we could change that and let the LinkGraph prepare the debug sections in a format that could be passed to the debugger? The plugin could query the target memory addresses from the LinkGraph and pass them to the debugger.

That's not quite what I had in mind (though it's also something we could discuss).

What I meant was that right now RuntimeDyld copies the entire incoming object (text, data and all) then mutates the load addresses in the header and passes the resulting object to the debugger. What I'm suggesting is that we consider constructing a new object file (ELF, MachO, COFF) from scratch to hold the debug info that we want to pass to the debugger. This synthesized object file should (ideally) not need to carry anything but the headers and debug info. How we transport that to the target process would be a separate question.

I think we'd still need to patch section addresses to inform the debugger about final locations, but otherwise it sounds reasonable.

In the scheme I'm suggesting we'd just be synthesizing new load commands for the sections in the LinkGraph. This would be a post-allocation pass, so we could inspect the graph to see where each section referred to by the debug info starts and ends.

We will need a way to tell the LinkGraphBuilder whether or not to include them (i.e. the ObjectLinkingLayer plugin is present/enabled or not) in order to avoid overhead in non-debug sessions right? ObjectLinkingLayer::emit() could accomplish it by passing a flag to createLinkGraphFromObject(), but I don't see a way to hook into it from a plugin context currently. How could we solve that?

I think the aim would be that we just don't install the debugging support plugin if debugging is not enabled.

(1) We shouldn't special-case the JITLinkContext callbacks except as a last resort.

We'd avoid the extra callback parameter in notifyLoaded(), but we'd need some other API function instead. Or would you propose not to use an ObjectLinkingLayer plugin altogether?

No, this should definitely be an object linking layer plugin, but I think we should be synthesizing / modifying the debug object in a jitlink pass installed by the plugin. That's the way EH-frame registration now works in the runtime prototype: https://github.com/lhames/llvm-project/blob/315f9f15e7233a5c956022201ac898f94196802a/llvm/lib/ExecutionEngine/Orc/MachOPlatform.cpp#L825 .

• support debug info for raw LinkGraphs (very attractive for long term performance -- avoids serializing / deserializing to objects),

Oh interesting. Thinking about synthetic debug info for compiler/linker injected code..

Exactly. One day

• reduce memory usage by not redundantly representing non-debug sections in the debug object

I think we could already strip them in the current approach. LLDB at least doesn't seem to touch it.

Yeah. I think we're converging on the same solution from different ends: You can think of this as stripping the incoming object back to contain only what's needed for the debugger, or you can think of it as building up a new object (using some source of debug info) for the debugger. The latter generalizes to support debug info in LinkGraphs.

If we take the synthesizing-a-new-object approach it means that we'll need to represent the debug info in the graphs, at least initially. I guess a sketch of the approach would look like this:

1. LinkGraphBuilders stop skipping debug info (this adds some overhead in the case where objects have debug info, but debug info is not used by the JIT. I think that's tolerable for now, we can revisit later if we want to make this optional).
2. JITLinkGDBLoaderPlugin installs two plugins that cooperate to synthesize and register a debug object:
   1. A pre-allocation pass synthesizes a debug object by copying the data out of the debug sections in the graph. In the synthesized object section and symbol target addresses are initially zero. The pass then deletes the debug sections from the graph.
   2. A post-allocation pass mutates the synthesized debug object based on the final target addresses in the graph. It then calls the runtime to register the debug info with the gdb registration API.

Does that sound reasonable?

[sgraenitz]

In D96627#2562565, @lhames wrote:

we should be synthesizing / modifying the debug object in a jitlink pass installed by the plugin

Aha, plugins can install linker passes! I didn't give enough attention to this. Sounds like it could make some extra infra in the current proposal obsolete (i.e. the callback and from the plugin to the linker driver).

1. LinkGraphBuilders stop skipping debug info (this adds some overhead in the case where objects have debug info, but debug info is not used by the JIT. I think that's tolerable for now, we can revisit later if we want to make this optional).
2. JITLinkGDBLoaderPlugin installs two plugins that cooperate to synthesize and register a debug object:
   1. A pre-allocation pass synthesizes a debug object by copying the data out of the debug sections in the graph. In the synthesized object section and symbol target addresses are initially zero. The pass then deletes the debug sections from the graph.
   2. A post-allocation pass mutates the synthesized debug object based on the final target addresses in the graph. It then calls the runtime to register the debug info with the gdb registration API.

Does that sound reasonable?

Yes, I will have a look at the API to install linker passes and see how far I come.

[dblaikie]

In D96627#2561402, @lhames wrote:

This is very exciting.

This is adopting RuntimeDyld's approach of patching section addresses to inform the debugger about final locations. I think this is ideal for a prototype, but probably not the right approach to the final version. I've only got two loosely formed thoughts on this so far:

(1) We shouldn't special-case the JITLinkContext callbacks except as a last resort. If we have to use them at all we should prefer making any information required available via generic structures like the LinkGraph. In this case I think you could build a SectionRange for each JITLink::Section rather than rely on the SegmentLayout.

(2) If we constructed the debug object file from scratch (rather than mutating the existing one) then we could

• support debug info for raw LinkGraphs (very attractive for long term performance -- avoids serializing / deserializing to objects),
• reduce memory usage by not redundantly representing non-debug sections in the debug object
• potentially dead strip debug info to further reduce memory overhead

Whether any of this is reasonable, and how much would it would be is another question. Probably time for me to learn some DWARF. :)

Dave -- do you have any immediate thoughts?

No immediate thoughts - happy to chat more about it, though. We might have to meet in the middle with regards to learning things here - I don't know too much about these JIT debugger APIs or what options they might have with regards to their input formats, resolution of addresses, etc.

[sgraenitz]

If we constructed the debug object file from scratch (rather than mutating the existing one)

While this sounds reasonable to me, it appears to add quite some effort. I guess we could grow our own writer that can emit in-memory ELF objects in some specific format, but there's a load of details that would need consideration sooner or later (recalculating offsets, compressed sections, etc.). Eventually, doing it right would probably mean something like llvm-objcopy --only-keep-debug. The implementation of it is buried with the tool implementation currently, so I can hardly "just use" it: https://reviews.llvm.org/rG5ad0103d8a04cb066dfae4fc20b0dfcd9413f4d4

What do you think?

(I will try a hack in the next days to see whether it's viable at all, but I'd would keep hopes low that we get there anytime soon.)

[lhames]

In D96627#2566871, @sgraenitz wrote:

If we constructed the debug object file from scratch (rather than mutating the existing one)

While this sounds reasonable to me, it appears to add quite some effort. I guess we could grow our own writer that can emit in-memory ELF objects in some specific format, but there's a load of details that would need consideration sooner or later (recalculating offsets, compressed sections, etc.). Eventually, doing it right would probably mean something like llvm-objcopy --only-keep-debug. The implementation of it is buried with the tool implementation currently, so I can hardly "just use" it: https://reviews.llvm.org/rG5ad0103d8a04cb066dfae4fc20b0dfcd9413f4d4

What do you think?

(I will try a hack in the next days to see whether it's viable at all, but I'd would keep hopes low that we get there anytime soon.)

I think MachOWriter and ELFWriter seem very useful outside llvm-objcopy. @MaskRay -- Do you think it would be reasonable to move those classes into a library? Maybe Object? Or BinaryFormat?

[MaskRay]

In D96627#2567468, @lhames wrote:

In D96627#2566871, @sgraenitz wrote:

If we constructed the debug object file from scratch (rather than mutating the existing one)

While this sounds reasonable to me, it appears to add quite some effort. I guess we could grow our own writer that can emit in-memory ELF objects in some specific format, but there's a load of details that would need consideration sooner or later (recalculating offsets, compressed sections, etc.). Eventually, doing it right would probably mean something like llvm-objcopy --only-keep-debug. The implementation of it is buried with the tool implementation currently, so I can hardly "just use" it: https://reviews.llvm.org/rG5ad0103d8a04cb066dfae4fc20b0dfcd9413f4d4

What do you think?

(I will try a hack in the next days to see whether it's viable at all, but I'd would keep hopes low that we get there anytime soon.)

I think MachOWriter and ELFWriter seem very useful outside llvm-objcopy. @MaskRay -- Do you think it would be reasonable to move those classes into a library? Maybe Object? Or BinaryFormat?

Hey. I am happy to share what I know about ELF, but I never look into jit in detail. (I should do that at some point..)

There is a feature request about "librarify llvm-objcopy": https://bugs.llvm.org/show_bug.cgi?id=41044
There was incomplete work in 2019. The latest attempt is https://lists.llvm.org/pipermail/llvm-dev/2021-January/147892.html (I haven't followed it).

As someone who implemented llvm-objcopy --only-keep-debug, I know that llvm-objcopy has two writers, one placing segments than sections, the other one (--only-keep-debug) placing sections then segments.
If you look at objcopy/llvm-objcopy --add-section and think it can do JIT job,,, you may get disappointed😓 The feature does not affect program headers (especially the most important PT_LOAD)...
so generally --add-section is probably only meaningful for relocatable object files (ET_REL) and non-SHF_ALLOC sections in executable and shared object files (ET_EXEC, ET_DYN).

With my current limited understanding about JIT, I think you may be able to take inspiration from some llvm-objcopy code, but using it as a library to do what you intend to do ... may be really difficult.

I think you can probably take more inspiration from the link editor LLD than llvm-objcopy... Placing sections & segments in a usable way is difficult. lld/ELF/Writer.cpp has fairly sophisticated (complicated) code doing that.

[sgraenitz]

In D96627#2567598, @MaskRay wrote:

Hey. I am happy to share what I know about ELF, but I never look into jit in detail. (I should do that at some point..)

Thanks for your pointers and estimation!

There is a feature request about "librarify llvm-objcopy": https://bugs.llvm.org/show_bug.cgi?id=41044
There was incomplete work in 2019. The latest attempt is https://lists.llvm.org/pipermail/llvm-dev/2021-January/147892.html (I haven't followed it).

Good to know that's basically in-progress already. It seems the overall refactoring in D88827 stagnated only because it requires some additional work in preparation (i.e. D91028 and D91693 which are both in active development). That's reinforcing my first impression: might be helpful, but it's a lot of work.

As someone who implemented llvm-objcopy --only-keep-debug, I know that llvm-objcopy has two writers, one placing segments than sections, the other one (--only-keep-debug) placing sections then segments.
If you look at objcopy/llvm-objcopy --add-section and think it can do JIT job,,, you may get disappointed😓 The feature does not affect program headers (especially the most important PT_LOAD)...
so generally --add-section is probably only meaningful for relocatable object files (ET_REL) and non-SHF_ALLOC sections in executable and shared object files (ET_EXEC, ET_DYN).

With my current limited understanding about JIT, I think you may be able to take inspiration from some llvm-objcopy code, but using it as a library to do what you intend to do ... may be really difficult.

JITLink does deal with relocatable object files (both, input and debug-output to LLDB), so maybe the functionality behind --add-section would be applicable in our case? However, I didn't have a closer look and it's really not something I'd want to judge.

Meanwhile, my quick hack is backing your thesis: I stripped my jitbp.o input object with llvm-objcopy --only-keep-debug on disk and fed that into LLDB as the debug-object for jitbp.o (including patched load-addresses for .text and .eh_frame). Now LLDB fails to calculate the correct address for the breakpoint site in my initial example:

(lldb) b jitbp
warning: failed to set breakpoint site at 0x6 for breakpoint 3.1: error: 9 sending the breakpoint request
Breakpoint 3: where = JIT(0x7ffff7fcd000)`jitbp() + 6 at jitbp.cpp:1:15, address = 0x0000000000000006

Maybe this is easy to fix. LLDB might just ignore .text sections of type NOBITS and so doesn't apply the load addresses or so, but given your concerns and my unfamiliarity with the code, I'd rather not debug that now. I'd say we keep the option in mind, let the refactoring land and consider it a task for further improvement.

BTW @MaskRay llvm-objcopy --only-keep-debug reduced the size of my minimal test object by only 128 byte (4%). That matches the size of .text plus .eh_frame, which disappeared (but yes, they still get reported in the headers). However, their relocation sections .rela.text and .rela.eh_frame still exist and occupy 90 additional bytes (3%). How are they required for debug?

[sgraenitz]

@lhames In my first proposal I used the ResourceKey value to identify a MaterializationResponsibility. Now I found that the EHFrameRegistrationPlugin uses ResourceKey and MaterializationResponsibility * as keys for different purposes (EHFrameRanges and InProcessLinks respectively).

Are there conceptual reasons for it? Any pros and cons?
Is the mapping between ResourceKey and MaterializationResponsibility always unique in both directions?

Thanks

[sgraenitz]

Add notifyMaterializing() handlers for Plugin and JITLinkContext. The JITLoaderGDBPlugin uses it to obtain a copy of the input object file, so we don't need to touch Plugin::notifyLoaded(). Furthermore the plugin uses a JITLink post-allocation pass to record section load-addresses in target memory. Instead of reaching out to the backend, it now applies format-specific transformations of the debug object itself based on the triple provided by the pass configuration.

[sgraenitz]

Unregistering, failure handling, tests and out-of-process support are still to do. I made some notes and highlighted current open questions inline.

Going forward, I think the most pressing question is testing. LLDB will have an end-to-end test, which checks that a JIT breakpoint in a minimal C++ file gets hit. It will cover all of the mandatory code paths. I am not sure though what's the best way to test cases with multiple MRs, splitting MRs, multi-threading, removing resources, etc. EHFrameRegistrationPlugin seems to have coverage for most of its code from LLJIT tests. Maybe that could be an option here too?

llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h

1320

New API function. The ObjectLinkingLayerJITLinkContext forwards it to the plugins. It feels quite symmetric to notifyFailed().

1370

New API function. Doesn't give the API client access to the underlying buffer.

llvm/include/llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h

75

New API function. We don't really need the LinkGraph, but only providing the context seems weird.

llvm/lib/ExecutionEngine/JITLink/ELF_x86_64.cpp

338

In order to make the plugin usable, we have to "ProcessAllSections". The good news is that the pruning step in linkPhase1 seems to remove all this.

llvm/tools/llvm-jitlink/llvm-jitlink-gdb-loader.cpp

207

It's quite far away from this patch, but I had a look at JITDylib::delegate(). It splits a MR in two and it looks like they both share one tracker. That might break my code currently. For now, I kept tracking debug objects by ResourceKey here, because I can get them from a MR, but not the other way around.

290

TODO: lock_guard

345

I can't reach the ExecutionSession here and there is no Error return value. Any chance we can report that?

This is due to the "never have more than one pending debug object" restriction above. Otherwise there is no way to determine the right debug object for a MR in the modifyPassConfig() and notifyLoaded() handlers. Or am I missing something?

[sgraenitz]

Obtain reference to ExecutionSession in ctor and use it for error reporting

[sgraenitz]

llvm/tools/llvm-jitlink/llvm-jitlink-gdb-loader.cpp

345

Error reporting done. The "never have more than one pending debug object" restriction still holds.

[sgraenitz]

New proposal posted with D97335

llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h

public:
   virtual ~JITLinkContext();
 
   /// Return the JITLinkDylib that this link is targeting, if any.
   const JITLinkDylib *getJITLinkDylib() const { return JD; }
 
   /// Return the MemoryManager to be used for this link.
   virtual JITLinkMemoryManager &getMemoryManager() = 0;
 
+  /// Notify this context that linking is about to start.
+  virtual void notifyMaterializing(const jitlink::LinkGraph &G) = 0;
+
   /// Notify this context that linking failed.
   /// Called by JITLink if linking cannot be completed.
   virtual void notifyFailed(Error Err) = 0;
 
   /// Called by JITLink to resolve external symbols. This method is passed a
   /// lookup continutation which it must call with a result to continue the
   /// linking process.
   virtual void lookup(const LookupMap &Symbols,
public:
   /// otherwise the JITContext is responsible for adding a mark-live pass in
   /// modifyPassConfig.
   virtual LinkGraphPassFunction getMarkLivePass(const Triple &TT) const;
 
   /// Called by JITLink to modify the pass pipeline prior to linking.
   /// The default version performs no modification.
   virtual Error modifyPassConfig(const Triple &TT, PassConfiguration &Config);
 
+  virtual Expected<std::unique_ptr<JITLinkMemoryManager::Allocation>>
+  allocateDebugObj(sys::Memory::ProtectionFlags Segment) const {
+    return nullptr;
+  }
+
 private:
   const JITLinkDylib *JD = nullptr;
 };
 
 /// Marks all symbols in a graph live. This can be used as a default,
 /// conservative mark-live implementation.
 Error markAllSymbolsLive(LinkGraph &G);
 

llvm/include/llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h

public:
     using JITLinkSymbolVector = std::vector<const jitlink::Symbol *>;
     using LocalDependenciesMap = DenseMap<SymbolStringPtr, JITLinkSymbolVector>;
 
     virtual ~Plugin();
     virtual void modifyPassConfig(MaterializationResponsibility &MR,
                                   const Triple &TT,
                                   jitlink::PassConfiguration &Config) {}
 
+    virtual void notifyMaterializing(MaterializationResponsibility &MR,
+                                     const jitlink::LinkGraph &G,
+                                     const jitlink::JITLinkContext &Ctx) {}
+
     virtual void notifyLoaded(MaterializationResponsibility &MR) {}
     virtual Error notifyEmitted(MaterializationResponsibility &MR) {
       return Error::success();
     }
     virtual Error notifyFailed(MaterializationResponsibility &MR) = 0;
     virtual Error notifyRemovingResources(ResourceKey K) = 0;
     virtual void notifyTransferringResources(ResourceKey DstKey,
                                              ResourceKey SrcKey) = 0;

llvm/lib/ExecutionEngine/JITLink/ELF_x86_64.cpp

private:
 
   Error createNormalizedSections() {
     LLVM_DEBUG(dbgs() << "Creating normalized sections...\n");
     for (auto &SecRef : sections) {
       auto Name = Obj.getSectionName(SecRef);
       if (!Name)
         return Name.takeError();
 
-      // Skip Dwarf sections.
-      if (isDwarfSection(*Name)) {
-        LLVM_DEBUG({
-          dbgs() << *Name
-                 << " is a debug section: No graph section will be created.\n";
-        });
-        continue;
-      }
-
       sys::Memory::ProtectionFlags Prot;
       if (SecRef.sh_flags & ELF::SHF_EXECINSTR) {
         Prot = static_cast<sys::Memory::ProtectionFlags>(sys::Memory::MF_READ |
                                                          sys::Memory::MF_EXEC);
       } else {
         Prot = static_cast<sys::Memory::ProtectionFlags>(sys::Memory::MF_READ |
                                                          sys::Memory::MF_WRITE);
       }

llvm/lib/ExecutionEngine/Orc/ObjectLinkingLayer.cpp

 //===------- ObjectLinkingLayer.cpp - JITLink backed ORC ObjectLayer ------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h"
 
 #include "llvm/ADT/Optional.h"
 #include "llvm/ExecutionEngine/JITLink/EHFrameSupport.h"
+#include "llvm/ExecutionEngine/JITLink/JITLink.h"
+#include "llvm/Support/Process.h"
 
 #include <vector>
 
 #define DEBUG_TYPE "orc"
 
 using namespace llvm;
 using namespace llvm::jitlink;
 using namespace llvm::orc;
~ObjectLinkingLayerJITLinkContext() {
     // If there is an object buffer return function then use it to
     // return ownership of the buffer.
     if (Layer.ReturnObjectBuffer && ObjBuffer)
       Layer.ReturnObjectBuffer(std::move(ObjBuffer));
   }
 
   JITLinkMemoryManager &getMemoryManager() override { return Layer.MemMgr; }
 
+  void notifyMaterializing(const jitlink::LinkGraph &G) override {
+    for (auto &P : Layer.Plugins)
+      P->notifyMaterializing(*MR, G, *this);
+  }
+
   void notifyFailed(Error Err) override {
     for (auto &P : Layer.Plugins)
       Err = joinErrors(std::move(Err), P->notifyFailed(*MR));
     Layer.getExecutionSession().reportError(std::move(Err));
     MR->failMaterialization();
   }
 
   void lookup(const LookupMap &Symbols,
for (auto &NamedDepsEntry : ExternalNamedSymbolDeps) {
         if (DepsForJD.empty())
           SymbolDeps.erase(&SourceJD);
       }
 
       MR->addDependencies(Name, SymbolDeps);
     }
   }
 
+  Expected<std::unique_ptr<JITLinkMemoryManager::Allocation>>
+  allocateDebugObj(sys::Memory::ProtectionFlags Segment) const override {
+    // TODO: This works, but what actual alignment requirements do we have?
+    unsigned Alignment = sys::Process::getPageSizeEstimate();
+
+    StringRef ObjMem = ObjBuffer->getBuffer();
+    Expected<std::unique_ptr<JITLinkMemoryManager::Allocation>> AllocOrErr =
+        Layer.MemMgr.allocate(&MR->getTargetJITDylib(),
+                              {{Segment, {Alignment, ObjMem.size(), 0}}});
+    if (!AllocOrErr)
+      return AllocOrErr.takeError();
+
+    JITLinkMemoryManager::Allocation &DebugObjAlloc = **AllocOrErr;
+    MutableArrayRef<char> DebugObjMem = DebugObjAlloc.getWorkingMemory(Segment);
+    memcpy(DebugObjMem.data(), ObjMem.data(), ObjMem.size());
+
+    return std::move(*AllocOrErr);
+  }
+
   ObjectLinkingLayer &Layer;
   std::unique_ptr<MaterializationResponsibility> MR;
   std::unique_ptr<MemoryBuffer> ObjBuffer;
   DenseMap<SymbolStringPtr, SymbolNameSet> ExternalNamedSymbolDeps;
   DenseMap<SymbolStringPtr, SymbolNameSet> InternalNamedSymbolDeps;
 };
 
 ObjectLinkingLayer::Plugin::~Plugin() {}

 ObjectLinkingLayer::~ObjectLinkingLayer() {
   assert(Allocs.empty() && "Layer destroyed with resources still attached");
   getExecutionSession().deregisterResourceManager(*this);
 }
 
 void ObjectLinkingLayer::emit(std::unique_ptr<MaterializationResponsibility> R,
                               std::unique_ptr<MemoryBuffer> O) {
   assert(O && "Object must not be null");
-  auto ObjBuffer = O->getMemBufferRef();
-  auto Ctx = std::make_unique<ObjectLinkingLayerJITLinkContext>(
-      *this, std::move(R), std::move(O));
-  if (auto G = createLinkGraphFromObject(std::move(ObjBuffer)))
+  MemoryBufferRef ObjBuffer = O->getMemBufferRef();
+
+  std::unique_ptr<JITLinkContext> Ctx =
+      std::make_unique<ObjectLinkingLayerJITLinkContext>(*this, std::move(R),
+                                                         std::move(O));
+  if (auto G = createLinkGraphFromObject(ObjBuffer)) {
+    Ctx->notifyMaterializing(**G);
     link(std::move(*G), std::move(Ctx));
-  else
+  } else {
     Ctx->notifyFailed(G.takeError());
   }
+}
 
 void ObjectLinkingLayer::emit(std::unique_ptr<MaterializationResponsibility> R,
                               std::unique_ptr<LinkGraph> G) {
-  link(std::move(G), std::make_unique<ObjectLinkingLayerJITLinkContext>(
-                         *this, std::move(R), nullptr));
+  std::unique_ptr<JITLinkContext> Ctx =
+      std::make_unique<ObjectLinkingLayerJITLinkContext>(*this, std::move(R),
+                                                         nullptr);
+  Ctx->notifyMaterializing(*G);
+  link(std::move(G), std::move(Ctx));
 }
 
 void ObjectLinkingLayer::modifyPassConfig(MaterializationResponsibility &MR,
                                           const Triple &TT,
                                           PassConfiguration &PassConfig) {
   for (auto &P : Plugins)
     P->modifyPassConfig(MR, TT, PassConfig);
 }

llvm/tools/llvm-jitlink/CMakeLists.txt

set(LLVM_LINK_COMPONENTS
   RuntimeDyld
   Support
   )
 
 add_llvm_tool(llvm-jitlink
   llvm-jitlink.cpp
   llvm-jitlink-elf.cpp
   llvm-jitlink-macho.cpp
+  llvm-jitlink-gdb-loader.cpp
   )
 
 export_executable_symbols(llvm-jitlink)

llvm/tools/llvm-jitlink/llvm-jitlink-gdb-loader.h

+#ifndef LLVM_TOOLS_LLVM_JITLINK_JITLINKGDBLOADERPLUGIN_H
+#define LLVM_TOOLS_LLVM_JITLINK_JITLINKGDBLOADERPLUGIN_H
+
+#include "llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h"
+
+#include "llvm/ADT/DenseMap.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/ExecutionEngine/JITLink/JITLink.h"
+#include "llvm/ExecutionEngine/JITLink/JITLinkMemoryManager.h"
+#include "llvm/ExecutionEngine/JITSymbol.h"
+#include "llvm/ExecutionEngine/Orc/Core.h"
+#include "llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h"
+#include "llvm/Object/ELFObjectFile.h"
+#include "llvm/Object/ObjectFile.h"
+#include "llvm/Support/Error.h"
+#include "llvm/Support/MemoryBuffer.h"
+
+#include <memory>
+#include <mutex>
+
+struct jit_code_entry;
+
+namespace llvm {
+namespace orc {
+
+class JITLoaderGDBPlugin : public ObjectLinkingLayer::Plugin {
+  using DebugAllocation =
+      std::unique_ptr<jitlink::JITLinkMemoryManager::Allocation>;
+
+  static constexpr sys::Memory::ProtectionFlags ReadOnlySegment =
+      static_cast<sys::Memory::ProtectionFlags>(sys::Memory::MF_READ);
+
+public:
+  void notifyMaterializing(MaterializationResponsibility &MR,
+                           const jitlink::LinkGraph &G,
+                           const jitlink::JITLinkContext &Ctx) override;
+
+  void notifyLoaded(MaterializationResponsibility &MR) override;
+  Error notifyFailed(MaterializationResponsibility &MR) override;
+  Error notifyRemovingResources(ResourceKey K) override;
+
+  void notifyTransferringResources(ResourceKey DstKey,
+                                   ResourceKey SrcKey) override;
+
+  void modifyPassConfig(MaterializationResponsibility &MR, const Triple &TT,
+                        jitlink::PassConfiguration &PassConfig) override;
+
+private:
+  DenseMap<ResourceKey, std::vector<DebugAllocation>> DebugAllocs;
+  DenseMap<ResourceKey, DebugAllocation> PendingDebugAllocs;
+  std::mutex DebugAllocLock;
+
+  static ResourceKey getResourceKey(MaterializationResponsibility &MR);
+};
+
+} // namespace orc
+} // namespace llvm
+
+#endif // LLVM_TOOLS_LLVM_JITLINK_JITLINKGDBLOADERPLUGIN_H

llvm/tools/llvm-jitlink/llvm-jitlink-gdb-loader.cpp

+#include "llvm-jitlink-gdb-loader.h"
+
+#include "llvm/Support/ManagedStatic.h"
+
+#include <cstdint>
+#include <mutex>
+
+#define DEBUG_TYPE "llvm_jitlink"
+
+using namespace llvm::object;
+
+// This must be kept in sync with gdb/gdb/jit.h .
+extern "C" {
+
+typedef enum {
+  JIT_NOACTION = 0,
+  JIT_REGISTER_FN,
+  JIT_UNREGISTER_FN
+} jit_actions_t;
+
+struct jit_code_entry {
+  struct jit_code_entry *next_entry;
+  struct jit_code_entry *prev_entry;
+  const char *symfile_addr;
+  uint64_t symfile_size;
+};
+
+struct jit_descriptor {
+  uint32_t version;
+  // This should be jit_actions_t, but we want to be specific about the
+  // bit-width.
+  uint32_t action_flag;
+  struct jit_code_entry *relevant_entry;
+  struct jit_code_entry *first_entry;
+};
+
+// We put information about the JITed function in this global, which the
+// debugger reads.  Make sure to specify the version statically, because the
+// debugger checks the version before we can set it during runtime.
+struct jit_descriptor __jit_debug_descriptor = {1, 0, nullptr, nullptr};
+
+// Debuggers that implement the GDB JIT interface put a special breakpoint in
+// this function.
+LLVM_ATTRIBUTE_NOINLINE void __jit_debug_register_code() {
+  // The noinline and the asm prevent calls to this function from being
+  // optimized out.
+#if !defined(_MSC_VER)
+  asm volatile("" ::: "memory");
+#endif
+}
+}
+
+namespace llvm {
+namespace orc {
+
+// Serialize rendezvous as well as access to shared data globally.
+ManagedStatic<std::mutex> JITDebugLock;
+
+// Append an entry to the list in the JIT descriptor symbol and call the debug
+// trap function. TODO: Implement removal.
+void AppendJITCodeEntry(const char *DebugObj, uint64_t DebugObjSize) {
+  std::lock_guard<std::mutex> Lock(*JITDebugLock);
+
+  jit_code_entry *JITCodeEntry = new jit_code_entry;
+  JITCodeEntry->symfile_addr = DebugObj;
+  JITCodeEntry->symfile_size = DebugObjSize;
+
+  // Insert this entry at the head of the list.
+  JITCodeEntry->prev_entry = nullptr;
+  jit_code_entry *NextEntry = __jit_debug_descriptor.first_entry;
+  JITCodeEntry->next_entry = NextEntry;
+  if (NextEntry) {
+    NextEntry->prev_entry = JITCodeEntry;
+  }
+
+  __jit_debug_descriptor.first_entry = JITCodeEntry;
+  __jit_debug_descriptor.relevant_entry = JITCodeEntry;
+}
+
+void NotifyDebugger(jit_actions_t Action) {
+  std::lock_guard<std::mutex> Lock(*JITDebugLock);
+  __jit_debug_descriptor.action_flag = Action;
+  __jit_debug_register_code();
+}
+
+class LoadedObjectView {
+public:
+  virtual ~LoadedObjectView(){};
+  virtual void
+  submitSectionLoadAddress(StringRef Name,
+                           JITTargetAddress AddrInTargetMemory) = 0;
+  virtual void dumpSectionLoadAddresses(raw_ostream &OS) = 0;
+};
+
+template <typename ELFT> class ELFLoadedObjectView : public LoadedObjectView {
+  using SectionHeader = typename ELFT::Shdr;
+
+  static bool isSectionTextOrData(unsigned Type, unsigned Flags) {
+    switch (Type) {
+    case ELF::SHT_PROGBITS:
+    case ELF::SHT_X86_64_UNWIND:
+      return Flags & (ELF::SHF_EXECINSTR | ELF::SHF_ALLOC);
+    }
+    return false;
+  }
+
+public:
+  static Expected<std::unique_ptr<ELFLoadedObjectView<ELFT>>>
+  Create(MutableArrayRef<char> Buffer) {
+    Expected<std::unique_ptr<ObjectFile>> ObjFile =
+        object::ObjectFile::createELFObjectFile(MemoryBufferRef(
+            StringRef(Buffer.data(), Buffer.size()), "ELFLoadedObjectView"));
+    if (!ObjFile)
+      return ObjFile.takeError();
+
+    auto &ELFObjFile = cast<object::ELFObjectFile<ELFT>>(**ObjFile);
+    const ELFFile<ELFT> &ELFFile = ELFObjFile.getELFFile();
+
+    Expected<ArrayRef<SectionHeader>> Sections = ELFFile.sections();
+    if (!Sections)
+      return Sections.takeError();
+
+    auto ObjView = std::make_unique<ELFLoadedObjectView<ELFT>>();
+    for (const SectionHeader &Section : *Sections) {
+      Expected<StringRef> Name = ELFFile.getSectionName(Section);
+      if (!Name)
+        consumeError(Name.takeError());
+      if (!Name || Name->empty())
+        continue;
+      if (!isSectionTextOrData(Section.sh_type, Section.sh_flags))
+        continue;
+
+      assert((const char *)&Section >= Buffer.data() &&
+             (const char *)&Section < Buffer.data() + Buffer.size() &&
+             "Section header outside memory range of given buffer");
+      ObjView->SectionHeaders[*Name] = const_cast<SectionHeader *>(&Section);
+    }
+
+    return std::move(ObjView);
+  }
+
+  void submitSectionLoadAddress(StringRef Name,
+                                JITTargetAddress AddrInTargetMemory) override {
+    auto It = SectionHeaders.find(Name);
+    if (It != SectionHeaders.end()) {
+      SectionHeader *Section = It->second;
+      Section->sh_addr = static_cast<typename ELFT::uint>(AddrInTargetMemory);
+    }
+  }
+
+  void dumpSectionLoadAddresses(raw_ostream &OS) override {
+    for (const auto &KV : SectionHeaders) {
+      if (auto Addr = static_cast<JITTargetAddress>(KV.second->sh_addr)) {
+        OS << formatv("  {0:x16} {1}\n", Addr, KV.first());
+      } else {
+        OS << formatv("                     {0}\n", KV.first());
+      }
+    }
+  }
+
+private:
+  StringMap<SectionHeader *> SectionHeaders;
+};
+
+static Expected<std::unique_ptr<LoadedObjectView>>
+createLoadedObjectELF(unsigned char Class, unsigned char Endian,
+                      MutableArrayRef<char> Buffer) {
+  if (Class == ELF::ELFCLASS32) {
+    if (Endian == ELF::ELFDATA2LSB)
+      return ELFLoadedObjectView<ELF32LE>::Create(Buffer);
+    if (Endian == ELF::ELFDATA2MSB)
+      return ELFLoadedObjectView<ELF32BE>::Create(Buffer);
+    return nullptr;
+  }
+  if (Class == ELF::ELFCLASS64) {
+    if (Endian == ELF::ELFDATA2LSB)
+      return ELFLoadedObjectView<ELF64LE>::Create(Buffer);
+    if (Endian == ELF::ELFDATA2MSB)
+      return ELFLoadedObjectView<ELF64BE>::Create(Buffer);
+    return nullptr;
+  }
+  return nullptr;
+}
+
+static Expected<std::unique_ptr<LoadedObjectView>>
+createLoadedObject(const Triple &TT, MutableArrayRef<char> Buffer) {
+  switch (TT.getObjectFormat()) {
+  case Triple::ELF: {
+    auto Ident = getElfArchType(StringRef(Buffer.data(), Buffer.size()));
+    return createLoadedObjectELF(Ident.first, Ident.second, Buffer);
+  }
+  default:
+    // TODO: Add debug support for other formats.
+    return nullptr;
+  }
+}
+
+ResourceKey
+JITLoaderGDBPlugin::getResourceKey(MaterializationResponsibility &MR) {
+  ResourceKey Key;
+  if (auto Err = MR.withResourceKeyDo([&](ResourceKey K) { Key = K; })) {
+    MR.getExecutionSession().reportError(std::move(Err));
+    return ResourceKey{};
+  }
+  assert(Key && "Invalid key value");
+  return Key;
+}
+
+void JITLoaderGDBPlugin::notifyMaterializing(
+    MaterializationResponsibility &MR, const jitlink::LinkGraph &G,
+    const jitlink::JITLinkContext &Ctx) {
+
+  std::lock_guard<std::mutex> Lock(DebugAllocLock);
+
+  // We should never have more than one pending debug object.
+  ResourceKey Key = getResourceKey(MR);
+  auto It = PendingDebugAllocs.find(Key);
+  if (It != PendingDebugAllocs.end()) {
+    MR.getExecutionSession().reportError(make_error<StringError>(
+        formatv("Materializing new LinkGraph '{0}' for pending resource: {1}",
+                G.getName(), Key),
+        inconvertibleErrorCode()));
+    return;
+  }
+
+  Expected<DebugAllocation> Alloc = Ctx.allocateDebugObj(ReadOnlySegment);
+  if (!Alloc) {
+    MR.getExecutionSession().reportError(Alloc.takeError());
+    return;
+  }
+
+  // Not all linker artifacts support debugging.
+  if (*Alloc)
+    PendingDebugAllocs[Key] = std::move(*Alloc);
+}
+
+void JITLoaderGDBPlugin::modifyPassConfig(
+    MaterializationResponsibility &MR, const Triple &TT,
+    jitlink::PassConfiguration &PassConfig) {
+
+  std::lock_guard<std::mutex> Lock(DebugAllocLock);
+
+  // We allocate debug objects for LinkGraphs built from an object file.
+  // We cannot synthesize debug objects for raw LinkGraphs yet.
+  ResourceKey Key = getResourceKey(MR);
+  auto It = PendingDebugAllocs.find(Key);
+  if (It == PendingDebugAllocs.end())
+    return;
+
+  Expected<std::unique_ptr<LoadedObjectView>> ObjView =
+      createLoadedObject(TT, It->second->getWorkingMemory(ReadOnlySegment));
+  if (!ObjView) {
+    MR.getExecutionSession().reportError(ObjView.takeError());
+    return;
+  }
+
+  if (*ObjView) {
+    PassConfig.PostAllocationPasses.push_back(
+        [OV = ObjView->release()](jitlink::LinkGraph &Graph) -> Error {
+          std::unique_ptr<LoadedObjectView> ObjView(OV);
+
+          // Enter load addresses in target memory for all executable sections.
+          for (const jitlink::Section &Section : Graph.sections()) {
+            jitlink::SectionRange TargetMemRange(Section);
+            if (!TargetMemRange.isEmpty())
+              ObjView->submitSectionLoadAddress(Section.getName(),
+                                                TargetMemRange.getStart());
+          }
+
+          LLVM_DEBUG({
+            dbgs() << formatv("Section load-addresses in debug object {0:x}\n",
+                              pointerToJITTargetAddress(ObjView.get()));
+            ObjView->dumpSectionLoadAddresses(dbgs());
+          });
+
+          return Error::success();
+        });
+  }
+}
+
+Error JITLoaderGDBPlugin::notifyFailed(MaterializationResponsibility &MR) {
+  // TODO: Drop DebugAlloc for MR?
+  return Error::success();
+}
+
+void JITLoaderGDBPlugin::notifyLoaded(MaterializationResponsibility &MR) {
+  ResourceKey Key = getResourceKey(MR);
+  DebugAllocation Alloc = nullptr;
+  {
+    std::unique_lock<std::mutex> Lock(DebugAllocLock);
+    auto It = PendingDebugAllocs.find(Key);
+    if (It != PendingDebugAllocs.end()) {
+      Alloc = std::move(It->second);
+      PendingDebugAllocs.erase(It);
+    }
+  }
+
+  if (Alloc)
+    Alloc->finalizeAsync([this, Key, RawAlloc = Alloc.release()](Error Unused) {
+      DebugAllocation Alloc(RawAlloc);
+
+      // TODO: Move to TargetProcessControl for out-of-process execution.
+      uint64_t DebugObjSize = Alloc->getWorkingMemory(ReadOnlySegment).size();
+      const char *DebugObjInTargetMemory =
+          jitTargetAddressToPointer<const char *>(
+              Alloc->getTargetMemory(ReadOnlySegment));
+
+      AppendJITCodeEntry(DebugObjInTargetMemory, DebugObjSize);
+      NotifyDebugger(JIT_REGISTER_FN);
+
+      std::lock_guard<std::mutex> Lock(DebugAllocLock);
+      DebugAllocs[Key].push_back(std::move(Alloc));
+
+      consumeError(std::move(Unused));
+    });
+}
+
+void JITLoaderGDBPlugin::notifyTransferringResources(ResourceKey DstKey,
+                                                     ResourceKey SrcKey) {
+  std::lock_guard<std::mutex> Lock(DebugAllocLock);
+
+  // Transfer registered debug objects.
+  auto SrcIt = DebugAllocs.find(SrcKey);
+  if (SrcIt != DebugAllocs.end()) {
+    auto DstIt = DebugAllocs.find(DstKey);
+    if (DstIt == DebugAllocs.end()) {
+      bool Inserted;
+      std::tie(DstIt, Inserted) = DebugAllocs.try_emplace(DstKey);
+    }
+
+    for (DebugAllocation &Alloc : SrcIt->second) {
+      DstIt->second.push_back(std::move(Alloc));
+    }
+  }
+
+  // Transfer pending debug objects.
+  auto SrcItPending = PendingDebugAllocs.find(SrcKey);
+  if (SrcItPending != PendingDebugAllocs.end()) {
+    if (PendingDebugAllocs.count(DstKey)) {
+      // TODO: Report it.
+      consumeError(make_error<StringError>(
+          formatv("Destination '{0}' for transferring pending debug object has "
+                  "a pending resource already: {1}",
+                  DstKey, SrcKey),
+          inconvertibleErrorCode()));
+    } else {
+      PendingDebugAllocs[DstKey] = std::move(SrcItPending->second);
+    }
+  }
+}
+
+Error JITLoaderGDBPlugin::notifyRemovingResources(ResourceKey K) {
+  std::lock_guard<std::mutex> Lock(DebugAllocLock);
+
+  auto It = DebugAllocs.find(K);
+  if (It != DebugAllocs.end()) {
+    // TODO: Unregister submitted JITCodeEntries.
+    DebugAllocs.erase(K);
+  }
+
+  if (PendingDebugAllocs.find(K) != PendingDebugAllocs.end())
+    PendingDebugAllocs.erase(K);
+
+  return Error::success();
+}
+
+} // namespace orc
+} // namespace llvm

llvm/tools/llvm-jitlink/llvm-jitlink.cpp

 //===- llvm-jitlink.cpp -- Command line interface/tester for llvm-jitlink -===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 // This utility provides a simple command line interface to the llvm jitlink
 // library, which makes relocatable object files executable in memory. Its
 // primary function is as a testing utility for the jitlink library.
 //
 //===----------------------------------------------------------------------===//
 
 #include "llvm-jitlink.h"
 
+#include "llvm-jitlink-gdb-loader.h"
+
 #include "llvm/BinaryFormat/Magic.h"
 #include "llvm/ExecutionEngine/Orc/ExecutionUtils.h"
 #include "llvm/ExecutionEngine/Orc/TPCDynamicLibrarySearchGenerator.h"
 #include "llvm/ExecutionEngine/Orc/TPCEHFrameRegistrar.h"
 #include "llvm/MC/MCAsmInfo.h"
 #include "llvm/MC/MCContext.h"
 #include "llvm/MC/MCDisassembler/MCDisassembler.h"
 #include "llvm/MC/MCInstPrinter.h"
else {
     return;
   }
 
   if (!NoExec && !this->TPC->getTargetTriple().isOSWindows())
     ObjLayer.addPlugin(std::make_unique<EHFrameRegistrationPlugin>(
         ES, ExitOnErr(TPCEHFrameRegistrar::Create(*this->TPC))));
 
   ObjLayer.addPlugin(std::make_unique<JITLinkSessionPlugin>(*this));
+  ObjLayer.addPlugin(std::make_unique<JITLoaderGDBPlugin>());
 
   // Process any harness files.
   for (auto &HarnessFile : TestHarnesses) {
     HarnessFiles.insert(HarnessFile);
 
     auto ObjBuffer =
         ExitOnErr(errorOrToExpected(MemoryBuffer::getFile(HarnessFile)));