1 //===--- LLJITWithRemoteDebugging.cpp - LLJIT targeting a child process ---===// 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 // This example shows how to use LLJIT and JITLink for out-of-process execution 10 // with debug support. A few notes beforehand: 11 // 12 // * Debuggers must implement the GDB JIT interface (gdb, udb, lldb 12+). 13 // * Debug support is currently limited to ELF on x86-64 platforms that run 14 // Unix-like systems. 15 // * There is a test for this example and it ships an IR file that is prepared 16 // for the instructions below. 17 // 18 // 19 // The following command line session provides a complete walkthrough of the 20 // feature using LLDB 12: 21 // 22 // [Terminal 1] Prepare a debuggable out-of-process JIT session: 23 // 24 // > cd llvm-project/build 25 // > ninja LLJITWithRemoteDebugging llvm-jitlink-executor 26 // > cp ../llvm/test/Examples/OrcV2Examples/Inputs/argc_sub1_elf.ll . 27 // > bin/LLJITWithRemoteDebugging --wait-for-debugger argc_sub1_elf.ll 28 // Found out-of-process executor: bin/llvm-jitlink-executor 29 // Launched executor in subprocess: 65535 30 // Attach a debugger and press any key to continue. 31 // 32 // 33 // [Terminal 2] Attach a debugger to the child process: 34 // 35 // (lldb) log enable lldb jit 36 // (lldb) settings set plugin.jit-loader.gdb.enable on 37 // (lldb) settings set target.source-map Inputs/ \ 38 // /path/to/llvm-project/llvm/test/Examples/OrcV2Examples/Inputs/ 39 // (lldb) attach -p 65535 40 // JITLoaderGDB::SetJITBreakpoint looking for JIT register hook 41 // JITLoaderGDB::SetJITBreakpoint setting JIT breakpoint 42 // Process 65535 stopped 43 // (lldb) b sub1 44 // Breakpoint 1: no locations (pending). 45 // WARNING: Unable to resolve breakpoint to any actual locations. 46 // (lldb) c 47 // Process 65535 resuming 48 // 49 // 50 // [Terminal 1] Press a key to start code generation and execution: 51 // 52 // Parsed input IR code from: argc_sub1_elf.ll 53 // Initialized LLJIT for remote executor 54 // Running: argc_sub1_elf.ll 55 // 56 // 57 // [Terminal 2] Breakpoint hits; we change the argc value from 1 to 42: 58 // 59 // (lldb) JITLoaderGDB::JITDebugBreakpointHit hit JIT breakpoint 60 // JITLoaderGDB::ReadJITDescriptorImpl registering JIT entry at 0x106b34000 61 // 1 location added to breakpoint 1 62 // Process 65535 stopped 63 // * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1 64 // frame #0: JIT(0x106b34000)`sub1(x=1) at argc_sub1.c:1:28 65 // -> 1 int sub1(int x) { return x - 1; } 66 // 2 int main(int argc, char **argv) { return sub1(argc); } 67 // (lldb) p x 68 // (int) $0 = 1 69 // (lldb) expr x = 42 70 // (int) $1 = 42 71 // (lldb) c 72 // 73 // 74 // [Terminal 1] Example output reflects the modified value: 75 // 76 // Exit code: 41 77 // 78 //===----------------------------------------------------------------------===// 79 80 #include "llvm/ExecutionEngine/Orc/JITTargetMachineBuilder.h" 81 #include "llvm/ExecutionEngine/Orc/LLJIT.h" 82 #include "llvm/ExecutionEngine/Orc/ObjectLinkingLayer.h" 83 #include "llvm/ExecutionEngine/Orc/SimpleRemoteEPC.h" 84 #include "llvm/ExecutionEngine/Orc/ThreadSafeModule.h" 85 #include "llvm/Support/CommandLine.h" 86 #include "llvm/Support/Error.h" 87 #include "llvm/Support/FormatVariadic.h" 88 #include "llvm/Support/InitLLVM.h" 89 #include "llvm/Support/TargetSelect.h" 90 #include "llvm/Support/raw_ostream.h" 91 92 #include "../ExampleModules.h" 93 #include "RemoteJITUtils.h" 94 95 #include <memory> 96 #include <string> 97 98 using namespace llvm; 99 using namespace llvm::orc; 100 101 // The LLVM IR file to run. 102 static cl::list<std::string> InputFiles(cl::Positional, cl::OneOrMore, 103 cl::desc("<input files>")); 104 105 // Command line arguments to pass to the JITed main function. 106 static cl::list<std::string> InputArgv("args", cl::Positional, 107 cl::desc("<program arguments>..."), 108 cl::ZeroOrMore, cl::PositionalEatsArgs); 109 110 // Given paths must exist on the remote target. 111 static cl::list<std::string> 112 Dylibs("dlopen", cl::desc("Dynamic libraries to load before linking"), 113 cl::value_desc("filename"), cl::ZeroOrMore); 114 115 // File path of the executable to launch for execution in a child process. 116 // Inter-process communication will go through stdin/stdout pipes. 117 static cl::opt<std::string> 118 OOPExecutor("executor", cl::desc("Set the out-of-process executor"), 119 cl::value_desc("filename")); 120 121 // Network address of a running executor process that we can connect via TCP. It 122 // may run locally or on a remote machine. 123 static cl::opt<std::string> OOPExecutorConnectTCP( 124 "connect", 125 cl::desc("Connect to an out-of-process executor through a TCP socket"), 126 cl::value_desc("<hostname>:<port>")); 127 128 // Give the user a chance to connect a debugger. Once we connected the executor 129 // process, wait for the user to press a key (and print out its PID if it's a 130 // child process). 131 static cl::opt<bool> 132 WaitForDebugger("wait-for-debugger", 133 cl::desc("Wait for user input before entering JITed code"), 134 cl::init(false)); 135 136 ExitOnError ExitOnErr; 137 138 int main(int argc, char *argv[]) { 139 InitLLVM X(argc, argv); 140 141 InitializeNativeTarget(); 142 InitializeNativeTargetAsmPrinter(); 143 144 ExitOnErr.setBanner(std::string(argv[0]) + ": "); 145 cl::ParseCommandLineOptions(argc, argv, "LLJITWithRemoteDebugging"); 146 147 std::unique_ptr<SimpleRemoteEPC> EPC; 148 if (OOPExecutorConnectTCP.getNumOccurrences() > 0) { 149 // Connect to a running out-of-process executor through a TCP socket. 150 EPC = ExitOnErr(connectTCPSocket(OOPExecutorConnectTCP)); 151 outs() << "Connected to executor at " << OOPExecutorConnectTCP << "\n"; 152 } else { 153 // Launch an out-of-process executor locally in a child process. 154 std::string Path = 155 OOPExecutor.empty() ? findLocalExecutor(argv[0]) : OOPExecutor; 156 outs() << "Found out-of-process executor: " << Path << "\n"; 157 158 uint64_t PID; 159 std::tie(EPC, PID) = ExitOnErr(launchLocalExecutor(Path)); 160 outs() << "Launched executor in subprocess: " << PID << "\n"; 161 } 162 163 if (WaitForDebugger) { 164 outs() << "Attach a debugger and press any key to continue.\n"; 165 fflush(stdin); 166 getchar(); 167 } 168 169 // Load the given IR files. 170 std::vector<ThreadSafeModule> TSMs; 171 for (const std::string &Path : InputFiles) { 172 outs() << "Parsing input IR code from: " << Path << "\n"; 173 TSMs.push_back(ExitOnErr(parseExampleModuleFromFile(Path))); 174 } 175 176 StringRef TT; 177 StringRef MainModuleName; 178 TSMs.front().withModuleDo([&MainModuleName, &TT](Module &M) { 179 MainModuleName = M.getName(); 180 TT = M.getTargetTriple(); 181 }); 182 183 for (const ThreadSafeModule &TSM : TSMs) 184 ExitOnErr(TSM.withModuleDo([TT, MainModuleName](Module &M) -> Error { 185 if (M.getTargetTriple() != TT) 186 return make_error<StringError>( 187 formatv("Different target triples in input files:\n" 188 " '{0}' in '{1}'\n '{2}' in '{3}'", 189 TT, MainModuleName, M.getTargetTriple(), M.getName()), 190 inconvertibleErrorCode()); 191 return Error::success(); 192 })); 193 194 // Create a target machine that matches the input triple. 195 JITTargetMachineBuilder JTMB((Triple(TT))); 196 JTMB.setCodeModel(CodeModel::Small); 197 JTMB.setRelocationModel(Reloc::PIC_); 198 199 // Create LLJIT and destroy it before disconnecting the target process. 200 outs() << "Initializing LLJIT for remote executor\n"; 201 auto J = ExitOnErr(LLJITBuilder() 202 .setExecutorProcessControl(std::move(EPC)) 203 .setJITTargetMachineBuilder(std::move(JTMB)) 204 .setObjectLinkingLayerCreator([&](auto &ES, const auto &TT) { 205 return std::make_unique<ObjectLinkingLayer>(ES); 206 }) 207 .create()); 208 209 // Add plugin for debug support. 210 ExitOnErr(addDebugSupport(J->getObjLinkingLayer())); 211 212 // Load required shared libraries on the remote target and add a generator 213 // for each of it, so the compiler can lookup their symbols. 214 for (const std::string &Path : Dylibs) 215 J->getMainJITDylib().addGenerator( 216 ExitOnErr(loadDylib(J->getExecutionSession(), Path))); 217 218 // Add the loaded IR module to the JIT. This will set up symbol tables and 219 // prepare for materialization. 220 for (ThreadSafeModule &TSM : TSMs) 221 ExitOnErr(J->addIRModule(std::move(TSM))); 222 223 // The example uses a non-lazy JIT for simplicity. Thus, looking up the main 224 // function will materialize all reachable code. It also triggers debug 225 // registration in the remote target process. 226 auto MainAddr = ExitOnErr(J->lookup("main")); 227 228 outs() << "Running: main("; 229 int Pos = 0; 230 std::vector<std::string> ActualArgv{"LLJITWithRemoteDebugging"}; 231 for (const std::string &Arg : InputArgv) { 232 outs() << (Pos++ == 0 ? "" : ", ") << "\"" << Arg << "\""; 233 ActualArgv.push_back(Arg); 234 } 235 outs() << ")\n"; 236 237 // Execute the code in the remote target process and dump the result. With 238 // the debugger attached to the target, it should be possible to inspect the 239 // JITed code as if it was compiled statically. 240 { 241 ExecutorProcessControl &EPC = 242 J->getExecutionSession().getExecutorProcessControl(); 243 int Result = ExitOnErr(EPC.runAsMain(MainAddr, ActualArgv)); 244 outs() << "Exit code: " << Result << "\n"; 245 } 246 247 return 0; 248 } 249