1//===--------- ELFDebugObjectPlugin.cpp - JITLink debug objects -----------===//
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// FIXME: Update Plugin to poke the debug object into a new JITLink section,
10// rather than creating a new allocation.
11//
12//===----------------------------------------------------------------------===//
13
14#include "llvm/ExecutionEngine/Orc/Debugging/ELFDebugObjectPlugin.h"
15
16#include "llvm/ADT/ArrayRef.h"
17#include "llvm/ADT/StringMap.h"
18#include "llvm/ADT/StringRef.h"
19#include "llvm/BinaryFormat/ELF.h"
20#include "llvm/ExecutionEngine/JITLink/JITLink.h"
21#include "llvm/ExecutionEngine/JITLink/JITLinkDylib.h"
22#include "llvm/ExecutionEngine/JITLink/JITLinkMemoryManager.h"
23#include "llvm/ExecutionEngine/Orc/Shared/ExecutorAddress.h"
24#include "llvm/ExecutionEngine/Orc/Shared/MemoryFlags.h"
25#include "llvm/ExecutionEngine/Orc/Shared/OrcRTBridge.h"
26#include "llvm/IR/Instructions.h"
27#include "llvm/Object/ELFObjectFile.h"
28#include "llvm/Object/Error.h"
29#include "llvm/Support/Errc.h"
30#include "llvm/Support/Error.h"
31#include "llvm/Support/MSVCErrorWorkarounds.h"
32#include "llvm/Support/MemoryBuffer.h"
33#include "llvm/Support/Process.h"
34#include "llvm/Support/raw_ostream.h"
35
36#include <set>
37
38#define DEBUG_TYPE "orc"
39
40using namespace llvm::jitlink;
41using namespace llvm::object;
42
43namespace llvm {
44namespace orc {
45
46// Helper class to emit and fixup an individual debug object
47class DebugObject {
48public:
49 using FinalizedAlloc = JITLinkMemoryManager::FinalizedAlloc;
50
51 DebugObject(StringRef Name, SimpleSegmentAlloc Alloc, JITLinkContext &Ctx,
52 ExecutionSession &ES)
53 : Name(Name), WorkingMem(std::move(Alloc)),
54 MemMgr(Ctx.getMemoryManager()), ES(ES) {}
55
56 ~DebugObject() {
57 assert(!FinalizeFuture.valid());
58 if (Alloc) {
59 std::vector<FinalizedAlloc> Allocs;
60 Allocs.push_back(x: std::move(Alloc));
61 if (Error Err = MemMgr.deallocate(Allocs: std::move(Allocs)))
62 ES.reportError(Err: std::move(Err));
63 }
64 }
65
66 MutableArrayRef<char> getBuffer() {
67 auto SegInfo = WorkingMem.getSegInfo(AG: MemProt::Read);
68 return SegInfo.WorkingMem;
69 }
70
71 SimpleSegmentAlloc collectTargetAlloc() {
72 FinalizeFuture = FinalizePromise.get_future();
73 return std::move(WorkingMem);
74 }
75
76 void trackFinalizedAlloc(FinalizedAlloc FA) { Alloc = std::move(FA); }
77
78 bool hasPendingTargetMem() const { return FinalizeFuture.valid(); }
79
80 Expected<ExecutorAddrRange> awaitTargetMem() {
81 assert(FinalizeFuture.valid() &&
82 "FinalizeFuture is not valid. Perhaps there is no pending target "
83 "memory transaction?");
84 return FinalizeFuture.get();
85 }
86
87 void reportTargetMem(ExecutorAddrRange TargetMem) {
88 FinalizePromise.set_value(TargetMem);
89 }
90
91 void failMaterialization(Error Err) {
92 FinalizePromise.set_value(std::move(Err));
93 }
94
95 void releasePendingResources() {
96 if (FinalizeFuture.valid()) {
97 // Error before step 4: Finalization error was not reported
98 Expected<ExecutorAddrRange> TargetMem = FinalizeFuture.get();
99 if (!TargetMem)
100 ES.reportError(Err: TargetMem.takeError());
101 } else {
102 // Error before step 3: WorkingMem was not collected
103 WorkingMem.abandon(
104 OnAbandoned: [ES = &this->ES](Error Err) { ES->reportError(Err: std::move(Err)); });
105 }
106 }
107
108 using GetLoadAddressFn = llvm::unique_function<ExecutorAddr(StringRef)>;
109 Error visitSections(GetLoadAddressFn Callback);
110
111 template <typename ELFT>
112 Error visitSectionLoadAddresses(GetLoadAddressFn Callback);
113
114private:
115 std::string Name;
116 SimpleSegmentAlloc WorkingMem;
117 JITLinkMemoryManager &MemMgr;
118 ExecutionSession &ES;
119
120 std::promise<MSVCPExpected<ExecutorAddrRange>> FinalizePromise;
121 std::future<MSVCPExpected<ExecutorAddrRange>> FinalizeFuture;
122
123 FinalizedAlloc Alloc;
124};
125
126template <typename ELFT>
127Error DebugObject::visitSectionLoadAddresses(GetLoadAddressFn Callback) {
128 using SectionHeader = typename ELFT::Shdr;
129
130 MutableArrayRef<char> Buffer = getBuffer();
131 StringRef BufferRef(Buffer.data(), Buffer.size());
132 Expected<ELFFile<ELFT>> ObjRef = ELFFile<ELFT>::create(BufferRef);
133 if (!ObjRef)
134 return ObjRef.takeError();
135
136 Expected<ArrayRef<SectionHeader>> Sections = ObjRef->sections();
137 if (!Sections)
138 return Sections.takeError();
139
140 for (const SectionHeader &Header : *Sections) {
141 Expected<StringRef> Name = ObjRef->getSectionName(Header);
142 if (!Name)
143 return Name.takeError();
144 if (Name->empty())
145 continue;
146 ExecutorAddr LoadAddress = Callback(*Name);
147 if (LoadAddress)
148 const_cast<SectionHeader &>(Header).sh_addr =
149 static_cast<typename ELFT::uint>(LoadAddress.getValue());
150 }
151
152 LLVM_DEBUG({
153 dbgs() << "Section load-addresses in debug object for \"" << Name
154 << "\":\n";
155 for (const SectionHeader &Header : *Sections) {
156 StringRef Name = cantFail(ObjRef->getSectionName(Header));
157 if (uint64_t Addr = Header.sh_addr) {
158 dbgs() << formatv(" {0:x16} {1}\n", Addr, Name);
159 } else {
160 dbgs() << formatv(" {0}\n", Name);
161 }
162 }
163 });
164
165 return Error::success();
166}
167
168Error DebugObject::visitSections(GetLoadAddressFn Callback) {
169 unsigned char Class, Endian;
170 MutableArrayRef<char> Buf = getBuffer();
171 std::tie(args&: Class, args&: Endian) = getElfArchType(Object: StringRef(Buf.data(), Buf.size()));
172
173 switch (Class) {
174 case ELF::ELFCLASS32:
175 if (Endian == ELF::ELFDATA2LSB)
176 return visitSectionLoadAddresses<ELF32LE>(Callback: std::move(Callback));
177 if (Endian == ELF::ELFDATA2MSB)
178 return visitSectionLoadAddresses<ELF32BE>(Callback: std::move(Callback));
179 break;
180
181 case ELF::ELFCLASS64:
182 if (Endian == ELF::ELFDATA2LSB)
183 return visitSectionLoadAddresses<ELF64LE>(Callback: std::move(Callback));
184 if (Endian == ELF::ELFDATA2MSB)
185 return visitSectionLoadAddresses<ELF64BE>(Callback: std::move(Callback));
186 break;
187
188 default:
189 break;
190 }
191 llvm_unreachable("Checked class and endian in notifyMaterializing()");
192}
193
194ELFDebugObjectPlugin::ELFDebugObjectPlugin(ExecutionSession &ES,
195 bool RequireDebugSections,
196 Error &Err)
197 : ES(ES), RequireDebugSections(RequireDebugSections) {
198 // Pass bootstrap symbol for registration function to enable debugging
199 ErrorAsOutParameter _(&Err);
200 Err = ES.getExecutorProcessControl().getBootstrapSymbols(
201 Pairs: {{RegistrationAction, rt::RegisterJITLoaderGDBAllocActionName}});
202}
203
204ELFDebugObjectPlugin::~ELFDebugObjectPlugin() = default;
205
206static const std::set<StringRef> DwarfSectionNames = {
207#define HANDLE_DWARF_SECTION(ENUM_NAME, ELF_NAME, CMDLINE_NAME, OPTION) \
208 ELF_NAME,
209#include "llvm/BinaryFormat/Dwarf.def"
210#undef HANDLE_DWARF_SECTION
211};
212
213static bool isDwarfSection(StringRef SectionName) {
214 return DwarfSectionNames.count(x: SectionName) == 1;
215}
216
217void ELFDebugObjectPlugin::notifyMaterializing(
218 MaterializationResponsibility &MR, LinkGraph &G, JITLinkContext &Ctx,
219 MemoryBufferRef InputObj) {
220 if (InputObj.getBufferSize() == 0)
221 return;
222 if (G.getTargetTriple().getObjectFormat() != Triple::ELF)
223 return;
224
225 unsigned char Class, Endian;
226 std::tie(args&: Class, args&: Endian) = getElfArchType(Object: InputObj.getBuffer());
227 if (Class != ELF::ELFCLASS64 && Class != ELF::ELFCLASS32)
228 return ES.reportError(
229 Err: createStringError(EC: object_error::invalid_file_type,
230 Fmt: "Skipping debug object registration: Invalid arch "
231 "0x%02x in ELF LinkGraph %s",
232 Vals: Class, Vals: G.getName().c_str()));
233 if (Endian != ELF::ELFDATA2LSB && Endian != ELF::ELFDATA2MSB)
234 return ES.reportError(
235 Err: createStringError(EC: object_error::invalid_file_type,
236 Fmt: "Skipping debug object registration: Invalid endian "
237 "0x%02x in ELF LinkGraph %s",
238 Vals: Endian, Vals: G.getName().c_str()));
239
240 // Step 1: We copy the raw input object into the working memory of a
241 // single-segment read-only allocation
242 size_t Size = InputObj.getBufferSize();
243 auto Alignment = sys::Process::getPageSizeEstimate();
244 SimpleSegmentAlloc::Segment Segment{Size, Align(Alignment)};
245
246 auto Alloc = SimpleSegmentAlloc::Create(
247 MemMgr&: Ctx.getMemoryManager(), SSP: ES.getSymbolStringPool(), TT: ES.getTargetTriple(),
248 JD: Ctx.getJITLinkDylib(), Segments: {{MemProt::Read, Segment}});
249 if (!Alloc) {
250 ES.reportError(Err: Alloc.takeError());
251 return;
252 }
253
254 std::lock_guard<std::mutex> Lock(PendingObjsLock);
255 assert(PendingObjs.count(&MR) == 0 && "One debug object per materialization");
256 PendingObjs[&MR] = std::make_unique<DebugObject>(
257 args: InputObj.getBufferIdentifier(), args: std::move(*Alloc), args&: Ctx, args&: ES);
258
259 MutableArrayRef<char> Buffer = PendingObjs[&MR]->getBuffer();
260 memcpy(dest: Buffer.data(), src: InputObj.getBufferStart(), n: Size);
261}
262
263DebugObject *
264ELFDebugObjectPlugin::getPendingDebugObj(MaterializationResponsibility &MR) {
265 std::lock_guard<std::mutex> Lock(PendingObjsLock);
266 auto It = PendingObjs.find(x: &MR);
267 return It == PendingObjs.end() ? nullptr : It->second.get();
268}
269
270void ELFDebugObjectPlugin::modifyPassConfig(MaterializationResponsibility &MR,
271 LinkGraph &G,
272 PassConfiguration &PassConfig) {
273 if (!getPendingDebugObj(MR))
274 return;
275
276 PassConfig.PostAllocationPasses.push_back(x: [this, &MR](LinkGraph &G) -> Error {
277 size_t SectionsPatched = 0;
278 bool HasDebugSections = false;
279 DebugObject *DebugObj = getPendingDebugObj(MR);
280 assert(DebugObj && "Don't inject passes if we have no debug object");
281
282 // Step 2: Once the target memory layout is ready, we write the
283 // addresses of the LinkGraph sections into the load-address fields of the
284 // section headers in our debug object allocation
285 Error Err = DebugObj->visitSections(
286 Callback: [&G, &SectionsPatched, &HasDebugSections](StringRef Name) {
287 Section *S = G.findSectionByName(Name);
288 if (!S) {
289 // The section may have been merged into a different one during
290 // linking, ignore it.
291 return ExecutorAddr();
292 }
293
294 SectionsPatched += 1;
295 if (isDwarfSection(SectionName: Name))
296 HasDebugSections = true;
297 return SectionRange(*S).getStart();
298 });
299
300 if (Err)
301 return Err;
302 if (!SectionsPatched) {
303 LLVM_DEBUG(dbgs() << "Skipping debug registration for LinkGraph '"
304 << G.getName() << "': no debug info\n");
305 return Error::success();
306 }
307
308 if (RequireDebugSections && !HasDebugSections) {
309 LLVM_DEBUG(dbgs() << "Skipping debug registration for LinkGraph '"
310 << G.getName() << "': no debug info\n");
311 return Error::success();
312 }
313
314 // Step 3: We start copying the debug object into target memory
315 SimpleSegmentAlloc Alloc = DebugObj->collectTargetAlloc();
316
317 // FIXME: FA->getAddress() below is supposed to be the address of the memory
318 // range on the target, but InProcessMemoryManager returns the address of a
319 // FinalizedAllocInfo helper instead
320 auto ROSeg = Alloc.getSegInfo(AG: MemProt::Read);
321 ExecutorAddrRange R(ROSeg.Addr, ROSeg.WorkingMem.size());
322 Alloc.finalize(OnFinalized: [this, R, &MR](Expected<DebugObject::FinalizedAlloc> FA) {
323 // Bail out if materialization failed in the meantime
324 std::lock_guard<std::mutex> Lock(PendingObjsLock);
325 auto It = PendingObjs.find(x: &MR);
326 if (It == PendingObjs.end()) {
327 if (!FA)
328 ES.reportError(Err: FA.takeError());
329 return;
330 }
331
332 DebugObject *DebugObj = It->second.get();
333 if (!FA)
334 DebugObj->failMaterialization(Err: FA.takeError());
335
336 // Keep allocation alive until the corresponding code is removed
337 DebugObj->trackFinalizedAlloc(FA: std::move(*FA));
338
339 // Unblock post-fixup pass
340 DebugObj->reportTargetMem(TargetMem: R);
341 });
342
343 return Error::success();
344 });
345
346 PassConfig.PostFixupPasses.push_back(x: [this, &MR](LinkGraph &G) -> Error {
347 // Step 4: We wait for the debug object copy to finish, so we can
348 // register the memory range with the GDB JIT Interface in an allocation
349 // action of the LinkGraph's own allocation
350 DebugObject *DebugObj = getPendingDebugObj(MR);
351 assert(DebugObj && "Don't inject passes if we have no debug object");
352 // Post-allocation phases would bail out if there is no debug section,
353 // in which case we wouldn't collect target memory and therefore shouldn't
354 // wait for the transaction to finish.
355 if (!DebugObj->hasPendingTargetMem())
356 return Error::success();
357 Expected<ExecutorAddrRange> R = DebugObj->awaitTargetMem();
358 if (!R)
359 return R.takeError();
360
361 // Step 5: We have to keep the allocation alive until the corresponding
362 // code is removed
363 Error Err = MR.withResourceKeyDo(F: [&](ResourceKey K) {
364 std::lock_guard<std::mutex> LockPending(PendingObjsLock);
365 std::lock_guard<std::mutex> LockRegistered(RegisteredObjsLock);
366 auto It = PendingObjs.find(x: &MR);
367 RegisteredObjs[K].push_back(x: std::move(It->second));
368 PendingObjs.erase(position: It);
369 });
370
371 if (Err)
372 return Err;
373
374 if (R->empty())
375 return Error::success();
376
377 using namespace shared;
378 G.allocActions().push_back(
379 x: {.Finalize: cantFail(ValOrErr: WrapperFunctionCall::Create<SPSArgList<SPSExecutorAddrRange>>(
380 FnAddr: RegistrationAction, Args: *R)),
381 .Dealloc: {/* no deregistration */}});
382 return Error::success();
383 });
384}
385
386Error ELFDebugObjectPlugin::notifyFailed(MaterializationResponsibility &MR) {
387 std::lock_guard<std::mutex> Lock(PendingObjsLock);
388 auto It = PendingObjs.find(x: &MR);
389 It->second->releasePendingResources();
390 PendingObjs.erase(position: It);
391 return Error::success();
392}
393
394void ELFDebugObjectPlugin::notifyTransferringResources(JITDylib &JD,
395 ResourceKey DstKey,
396 ResourceKey SrcKey) {
397 // Debug objects are stored by ResourceKey only after registration.
398 // Thus, pending objects don't need to be updated here.
399 std::lock_guard<std::mutex> Lock(RegisteredObjsLock);
400 auto SrcIt = RegisteredObjs.find(x: SrcKey);
401 if (SrcIt != RegisteredObjs.end()) {
402 // Resources from distinct MaterializationResponsibilitys can get merged
403 // after emission, so we can have multiple debug objects per resource key.
404 for (std::unique_ptr<DebugObject> &DebugObj : SrcIt->second)
405 RegisteredObjs[DstKey].push_back(x: std::move(DebugObj));
406 RegisteredObjs.erase(position: SrcIt);
407 }
408}
409
410Error ELFDebugObjectPlugin::notifyRemovingResources(JITDylib &JD,
411 ResourceKey Key) {
412 // Removing the resource for a pending object fails materialization, so they
413 // get cleaned up in the notifyFailed() handler.
414 std::lock_guard<std::mutex> Lock(RegisteredObjsLock);
415 RegisteredObjs.erase(x: Key);
416
417 // TODO: Implement unregister notifications.
418 return Error::success();
419}
420
421} // namespace orc
422} // namespace llvm
423