1//===----- GDBRegistrationListener.cpp - Registers objects with GDB -------===//
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#include "llvm-c/ExecutionEngine.h"
10#include "llvm/ADT/DenseMap.h"
11#include "llvm/ExecutionEngine/JITEventListener.h"
12#include "llvm/Object/ObjectFile.h"
13#include "llvm/Support/Compiler.h"
14#include "llvm/Support/ErrorHandling.h"
15#include "llvm/Support/Mutex.h"
16#include <mutex>
17
18using namespace llvm;
19using namespace llvm::object;
20
21// This must be kept in sync with gdb/gdb/jit.h .
22extern "C" {
23
24 typedef enum {
25 JIT_NOACTION = 0,
26 JIT_REGISTER_FN,
27 JIT_UNREGISTER_FN
28 } jit_actions_t;
29
30 struct jit_code_entry {
31 struct jit_code_entry *next_entry;
32 struct jit_code_entry *prev_entry;
33 const char *symfile_addr;
34 uint64_t symfile_size;
35 };
36
37 struct jit_descriptor {
38 uint32_t version;
39 // This should be jit_actions_t, but we want to be specific about the
40 // bit-width.
41 uint32_t action_flag;
42 struct jit_code_entry *relevant_entry;
43 struct jit_code_entry *first_entry;
44 };
45
46 // We put information about the JITed function in this global, which the
47 // debugger reads. Make sure to specify the version statically, because the
48 // debugger checks the version before we can set it during runtime.
49 extern struct jit_descriptor __jit_debug_descriptor;
50
51 // Debuggers puts a breakpoint in this function.
52 extern "C" void __jit_debug_register_code();
53}
54
55namespace {
56
57// FIXME: lli aims to provide both, RuntimeDyld and JITLink, as the dynamic
58// loaders for its JIT implementations. And they both offer debugging via the
59// GDB JIT interface, which builds on the two well-known symbol names below.
60// As these symbols must be unique across the linked executable, we can only
61// define them in one of the libraries and make the other depend on it.
62// OrcTargetProcess is a minimal stub for embedding a JIT client in remote
63// executors. For the moment it seems reasonable to have the definition there
64// and let ExecutionEngine depend on it, until we find a better solution.
65//
66LLVM_ATTRIBUTE_USED void requiredSymbolDefinitionsFromOrcTargetProcess() {
67 errs() << (void *)&__jit_debug_register_code
68 << (void *)&__jit_debug_descriptor;
69}
70
71struct RegisteredObjectInfo {
72 RegisteredObjectInfo() = default;
73
74 RegisteredObjectInfo(std::size_t Size, jit_code_entry *Entry,
75 OwningBinary<ObjectFile> Obj)
76 : Size(Size), Entry(Entry), Obj(std::move(Obj)) {}
77
78 std::size_t Size;
79 jit_code_entry *Entry;
80 OwningBinary<ObjectFile> Obj;
81};
82
83// Buffer for an in-memory object file in executable memory
84typedef llvm::DenseMap<JITEventListener::ObjectKey, RegisteredObjectInfo>
85 RegisteredObjectBufferMap;
86
87/// Global access point for the JIT debugging interface designed for use with a
88/// singleton toolbox. Handles thread-safe registration and deregistration of
89/// object files that are in executable memory managed by the client of this
90/// class.
91class GDBJITRegistrationListener : public JITEventListener {
92 /// Lock used to serialize all jit registration events, since they
93 /// modify global variables.
94 ///
95 /// Only a single instance of GDBJITRegistrationListener is ever created,
96 /// and so the lock can be a member variable of that instance. This ensures
97 /// destructors are run in the correct order.
98 sys::Mutex JITDebugLock;
99
100 /// A map of in-memory object files that have been registered with the
101 /// JIT interface.
102 RegisteredObjectBufferMap ObjectBufferMap;
103
104 /// Instantiates the JIT service.
105 GDBJITRegistrationListener() = default;
106
107 /// Unregisters each object that was previously registered and releases all
108 /// internal resources.
109 ~GDBJITRegistrationListener() override;
110
111public:
112 static GDBJITRegistrationListener &instance() {
113 static GDBJITRegistrationListener Instance;
114 return Instance;
115 }
116
117 /// Creates an entry in the JIT registry for the buffer @p Object,
118 /// which must contain an object file in executable memory with any
119 /// debug information for the debugger.
120 void notifyObjectLoaded(ObjectKey K, const ObjectFile &Obj,
121 const RuntimeDyld::LoadedObjectInfo &L) override;
122
123 /// Removes the internal registration of @p Object, and
124 /// frees associated resources.
125 /// Returns true if @p Object was found in ObjectBufferMap.
126 void notifyFreeingObject(ObjectKey K) override;
127
128private:
129 /// Deregister the debug info for the given object file from the debugger
130 /// and delete any temporary copies. This private method does not remove
131 /// the function from Map so that it can be called while iterating over Map.
132 void deregisterObjectInternal(RegisteredObjectBufferMap::iterator I);
133};
134
135/// Do the registration.
136void NotifyDebugger(jit_code_entry* JITCodeEntry) {
137 __jit_debug_descriptor.action_flag = JIT_REGISTER_FN;
138
139 // Insert this entry at the head of the list.
140 JITCodeEntry->prev_entry = nullptr;
141 jit_code_entry* NextEntry = __jit_debug_descriptor.first_entry;
142 JITCodeEntry->next_entry = NextEntry;
143 if (NextEntry) {
144 NextEntry->prev_entry = JITCodeEntry;
145 }
146 __jit_debug_descriptor.first_entry = JITCodeEntry;
147 __jit_debug_descriptor.relevant_entry = JITCodeEntry;
148 __jit_debug_register_code();
149}
150
151GDBJITRegistrationListener::~GDBJITRegistrationListener() {
152 // Free all registered object files.
153 std::lock_guard<llvm::sys::Mutex> locked(JITDebugLock);
154 for (RegisteredObjectBufferMap::iterator I = ObjectBufferMap.begin(),
155 E = ObjectBufferMap.end();
156 I != E; ++I) {
157 // Call the private method that doesn't update the map so our iterator
158 // doesn't break.
159 deregisterObjectInternal(I);
160 }
161 ObjectBufferMap.clear();
162}
163
164void GDBJITRegistrationListener::notifyObjectLoaded(
165 ObjectKey K, const ObjectFile &Obj,
166 const RuntimeDyld::LoadedObjectInfo &L) {
167
168 OwningBinary<ObjectFile> DebugObj = L.getObjectForDebug(Obj);
169
170 // Bail out if debug objects aren't supported.
171 if (!DebugObj.getBinary())
172 return;
173
174 const char *Buffer = DebugObj.getBinary()->getMemoryBufferRef().getBufferStart();
175 size_t Size = DebugObj.getBinary()->getMemoryBufferRef().getBufferSize();
176
177 std::lock_guard<llvm::sys::Mutex> locked(JITDebugLock);
178 assert(!ObjectBufferMap.contains(K) &&
179 "Second attempt to perform debug registration.");
180 jit_code_entry* JITCodeEntry = new jit_code_entry();
181
182 if (!JITCodeEntry) {
183 llvm::report_fatal_error(
184 reason: "Allocation failed when registering a JIT entry!\n");
185 } else {
186 JITCodeEntry->symfile_addr = Buffer;
187 JITCodeEntry->symfile_size = Size;
188
189 ObjectBufferMap[K] =
190 RegisteredObjectInfo(Size, JITCodeEntry, std::move(DebugObj));
191 NotifyDebugger(JITCodeEntry);
192 }
193}
194
195void GDBJITRegistrationListener::notifyFreeingObject(ObjectKey K) {
196 std::lock_guard<llvm::sys::Mutex> locked(JITDebugLock);
197 RegisteredObjectBufferMap::iterator I = ObjectBufferMap.find(Val: K);
198
199 if (I != ObjectBufferMap.end()) {
200 deregisterObjectInternal(I);
201 ObjectBufferMap.erase(I);
202 }
203}
204
205void GDBJITRegistrationListener::deregisterObjectInternal(
206 RegisteredObjectBufferMap::iterator I) {
207
208 jit_code_entry*& JITCodeEntry = I->second.Entry;
209
210 // Do the unregistration.
211 {
212 __jit_debug_descriptor.action_flag = JIT_UNREGISTER_FN;
213
214 // Remove the jit_code_entry from the linked list.
215 jit_code_entry* PrevEntry = JITCodeEntry->prev_entry;
216 jit_code_entry* NextEntry = JITCodeEntry->next_entry;
217
218 if (NextEntry) {
219 NextEntry->prev_entry = PrevEntry;
220 }
221 if (PrevEntry) {
222 PrevEntry->next_entry = NextEntry;
223 }
224 else {
225 assert(__jit_debug_descriptor.first_entry == JITCodeEntry);
226 __jit_debug_descriptor.first_entry = NextEntry;
227 }
228
229 // Tell the debugger which entry we removed, and unregister the code.
230 __jit_debug_descriptor.relevant_entry = JITCodeEntry;
231 __jit_debug_register_code();
232 }
233
234 delete JITCodeEntry;
235 JITCodeEntry = nullptr;
236}
237
238} // end namespace
239
240namespace llvm {
241
242JITEventListener* JITEventListener::createGDBRegistrationListener() {
243 return &GDBJITRegistrationListener::instance();
244}
245
246} // namespace llvm
247
248LLVMJITEventListenerRef LLVMCreateGDBRegistrationListener(void)
249{
250 return wrap(P: JITEventListener::createGDBRegistrationListener());
251}
252