1 //===-- IRExecutionUnit.h ---------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_IRExecutionUnit_h_
11 #define liblldb_IRExecutionUnit_h_
20 // Other libraries and framework includes
21 #include "llvm/ExecutionEngine/SectionMemoryManager.h"
22 #include "llvm/IR/Module.h"
25 #include "lldb/Expression/IRMemoryMap.h"
26 #include "lldb/Symbol/ObjectFile.h"
27 #include "lldb/Symbol/SymbolContext.h"
28 #include "lldb/Utility/DataBufferHeap.h"
29 #include "lldb/lldb-forward.h"
30 #include "lldb/lldb-private.h"
35 class ExecutionEngine;
40 namespace lldb_private {
44 //----------------------------------------------------------------------
45 /// @class IRExecutionUnit IRExecutionUnit.h "lldb/Expression/IRExecutionUnit.h"
46 /// @brief Contains the IR and, optionally, JIT-compiled code for a module.
48 /// This class encapsulates the compiled version of an expression, in IR
49 /// form (for interpretation purposes) and in raw machine code form (for
50 /// execution in the target).
52 /// This object wraps an IR module that comes from the expression parser,
53 /// and knows how to use the JIT to make it into executable code. It can
54 /// then be used as input to the IR interpreter, or the address of the
55 /// executable code can be passed to a thread plan to run in the target.
57 /// This class creates a subclass of LLVM's SectionMemoryManager, because that
59 /// how the JIT emits code. Because LLDB needs to move JIT-compiled code
60 /// into the target process, the IRExecutionUnit knows how to copy the
61 /// emitted code into the target process.
62 //----------------------------------------------------------------------
63 class IRExecutionUnit : public std::enable_shared_from_this<IRExecutionUnit>,
65 public ObjectFileJITDelegate {
67 //------------------------------------------------------------------
69 //------------------------------------------------------------------
70 IRExecutionUnit(std::unique_ptr<llvm::LLVMContext> &context_ap,
71 std::unique_ptr<llvm::Module> &module_ap, ConstString &name,
72 const lldb::TargetSP &target_sp, const SymbolContext &sym_ctx,
73 std::vector<std::string> &cpu_features);
75 //------------------------------------------------------------------
77 //------------------------------------------------------------------
78 ~IRExecutionUnit() override;
80 ConstString GetFunctionName() { return m_name; }
82 llvm::Module *GetModule() { return m_module; }
84 llvm::Function *GetFunction() {
85 return ((m_module != nullptr) ? m_module->getFunction(m_name.AsCString())
89 void GetRunnableInfo(Status &error, lldb::addr_t &func_addr,
90 lldb::addr_t &func_end);
92 //------------------------------------------------------------------
93 /// Accessors for IRForTarget and other clients that may want binary
94 /// data placed on their behalf. The binary data is owned by the
95 /// IRExecutionUnit unless the client explicitly chooses to free it.
96 //------------------------------------------------------------------
98 lldb::addr_t WriteNow(const uint8_t *bytes, size_t size, Status &error);
100 void FreeNow(lldb::addr_t allocation);
102 //------------------------------------------------------------------
103 /// ObjectFileJITDelegate overrides
104 //------------------------------------------------------------------
105 lldb::ByteOrder GetByteOrder() const override;
107 uint32_t GetAddressByteSize() const override;
109 void PopulateSymtab(lldb_private::ObjectFile *obj_file,
110 lldb_private::Symtab &symtab) override;
112 void PopulateSectionList(lldb_private::ObjectFile *obj_file,
113 lldb_private::SectionList §ion_list) override;
115 bool GetArchitecture(lldb_private::ArchSpec &arch) override;
117 lldb::ModuleSP GetJITModule();
119 lldb::addr_t FindSymbol(const ConstString &name);
121 void GetStaticInitializers(std::vector<lldb::addr_t> &static_initializers);
123 //----------------------------------------------------------------------
124 /// @class JittedFunction IRExecutionUnit.h
125 /// "lldb/Expression/IRExecutionUnit.h"
126 /// @brief Encapsulates a single function that has been generated by the JIT.
128 /// Functions that have been generated by the JIT are first resident in the
129 /// local process, and then placed in the target process. JittedFunction
130 /// represents a function possibly resident in both.
131 //----------------------------------------------------------------------
132 struct JittedEntity {
133 ConstString m_name; ///< The function's name
134 lldb::addr_t m_local_addr; ///< The address of the function in LLDB's memory
136 m_remote_addr; ///< The address of the function in the target's memory
138 //------------------------------------------------------------------
141 /// Initializes class variabes.
144 /// The name of the function.
146 /// @param[in] local_addr
147 /// The address of the function in LLDB, or LLDB_INVALID_ADDRESS if
148 /// it is not present in LLDB's memory.
150 /// @param[in] remote_addr
151 /// The address of the function in the target, or LLDB_INVALID_ADDRESS
152 /// if it is not present in the target's memory.
153 //------------------------------------------------------------------
154 JittedEntity(const char *name,
155 lldb::addr_t local_addr = LLDB_INVALID_ADDRESS,
156 lldb::addr_t remote_addr = LLDB_INVALID_ADDRESS)
157 : m_name(name), m_local_addr(local_addr), m_remote_addr(remote_addr) {}
160 struct JittedFunction : JittedEntity {
162 JittedFunction(const char *name, bool external,
163 lldb::addr_t local_addr = LLDB_INVALID_ADDRESS,
164 lldb::addr_t remote_addr = LLDB_INVALID_ADDRESS)
165 : JittedEntity(name, local_addr, remote_addr), m_external(external) {}
168 struct JittedGlobalVariable : JittedEntity {
169 JittedGlobalVariable(const char *name,
170 lldb::addr_t local_addr = LLDB_INVALID_ADDRESS,
171 lldb::addr_t remote_addr = LLDB_INVALID_ADDRESS)
172 : JittedEntity(name, local_addr, remote_addr) {}
175 const std::vector<JittedFunction> &GetJittedFunctions() {
176 return m_jitted_functions;
179 const std::vector<JittedGlobalVariable> &GetJittedGlobalVariables() {
180 return m_jitted_global_variables;
184 //------------------------------------------------------------------
185 /// Look up the object in m_address_map that contains a given address,
186 /// find where it was copied to, and return the remote address at the
187 /// same offset into the copied entity
189 /// @param[in] local_address
190 /// The address in the debugger.
193 /// The address in the target process.
194 //------------------------------------------------------------------
195 lldb::addr_t GetRemoteAddressForLocal(lldb::addr_t local_address);
197 //------------------------------------------------------------------
198 /// Look up the object in m_address_map that contains a given address,
199 /// find where it was copied to, and return its address range in the
202 /// @param[in] local_address
203 /// The address in the debugger.
206 /// The range of the containing object in the target process.
207 //------------------------------------------------------------------
208 typedef std::pair<lldb::addr_t, uintptr_t> AddrRange;
209 AddrRange GetRemoteRangeForLocal(lldb::addr_t local_address);
211 //------------------------------------------------------------------
212 /// Commit all allocations to the process and record where they were stored.
214 /// @param[in] process
215 /// The process to allocate memory in.
218 /// True <=> all allocations were performed successfully.
219 /// This method will attempt to free allocated memory if the
221 //------------------------------------------------------------------
222 bool CommitAllocations(lldb::ProcessSP &process_sp);
224 //------------------------------------------------------------------
225 /// Report all committed allocations to the execution engine.
227 /// @param[in] engine
228 /// The execution engine to notify.
229 //------------------------------------------------------------------
230 void ReportAllocations(llvm::ExecutionEngine &engine);
232 //------------------------------------------------------------------
233 /// Write the contents of all allocations to the process.
235 /// @param[in] local_address
236 /// The process containing the allocations.
239 /// True <=> all allocations were performed successfully.
240 //------------------------------------------------------------------
241 bool WriteData(lldb::ProcessSP &process_sp);
243 Status DisassembleFunction(Stream &stream, lldb::ProcessSP &process_sp);
247 void CollectCandidateCNames(std::vector<SearchSpec> &C_specs,
248 const ConstString &name);
250 void CollectCandidateCPlusPlusNames(std::vector<SearchSpec> &CPP_specs,
251 const std::vector<SearchSpec> &C_specs,
252 const SymbolContext &sc);
254 void CollectFallbackNames(std::vector<SearchSpec> &fallback_specs,
255 const std::vector<SearchSpec> &C_specs);
257 lldb::addr_t FindInSymbols(const std::vector<SearchSpec> &specs,
258 const lldb_private::SymbolContext &sc);
260 lldb::addr_t FindInRuntimes(const std::vector<SearchSpec> &specs,
261 const lldb_private::SymbolContext &sc);
263 lldb::addr_t FindInUserDefinedSymbols(const std::vector<SearchSpec> &specs,
264 const lldb_private::SymbolContext &sc);
266 void ReportSymbolLookupError(const ConstString &name);
268 class MemoryManager : public llvm::SectionMemoryManager {
270 MemoryManager(IRExecutionUnit &parent);
272 ~MemoryManager() override;
274 //------------------------------------------------------------------
275 /// Allocate space for executable code, and add it to the
276 /// m_spaceBlocks map
279 /// The size of the area.
281 /// @param[in] Alignment
282 /// The required alignment of the area.
284 /// @param[in] SectionID
285 /// A unique identifier for the section.
289 //------------------------------------------------------------------
290 uint8_t *allocateCodeSection(uintptr_t Size, unsigned Alignment,
292 llvm::StringRef SectionName) override;
294 //------------------------------------------------------------------
295 /// Allocate space for data, and add it to the m_spaceBlocks map
298 /// The size of the area.
300 /// @param[in] Alignment
301 /// The required alignment of the area.
303 /// @param[in] SectionID
304 /// A unique identifier for the section.
306 /// @param[in] IsReadOnly
307 /// Flag indicating the section is read-only.
311 //------------------------------------------------------------------
312 uint8_t *allocateDataSection(uintptr_t Size, unsigned Alignment,
314 llvm::StringRef SectionName,
315 bool IsReadOnly) override;
317 //------------------------------------------------------------------
318 /// Called when object loading is complete and section page
319 /// permissions can be applied. Currently unimplemented for LLDB.
321 /// @param[out] ErrMsg
322 /// The error that prevented the page protection from succeeding.
325 /// True in case of failure, false in case of success.
326 //------------------------------------------------------------------
327 bool finalizeMemory(std::string *ErrMsg) override {
328 // TODO: Ensure that the instruction cache is flushed because
329 // relocations are updated by dy-load. See:
330 // sys::Memory::InvalidateInstructionCache
331 // llvm::SectionMemoryManager
335 void registerEHFrames(uint8_t *Addr, uint64_t LoadAddr,
336 size_t Size) override {}
338 uint64_t getSymbolAddress(const std::string &Name) override;
340 void *getPointerToNamedFunction(const std::string &Name,
341 bool AbortOnFailure = true) override;
344 std::unique_ptr<SectionMemoryManager> m_default_mm_ap; ///< The memory
351 IRExecutionUnit &m_parent; ///< The execution unit this is a proxy for.
354 static const unsigned eSectionIDInvalid = (unsigned)-1;
356 //----------------------------------------------------------------------
357 /// @class AllocationRecord IRExecutionUnit.h
358 /// "lldb/Expression/IRExecutionUnit.h"
359 /// @brief Encapsulates a single allocation request made by the JIT.
361 /// Allocations made by the JIT are first queued up and then applied in
362 /// bulk to the underlying process.
363 //----------------------------------------------------------------------
364 enum class AllocationKind { Stub, Code, Data, Global, Bytes };
366 static lldb::SectionType
367 GetSectionTypeFromSectionName(const llvm::StringRef &name,
368 AllocationKind alloc_kind);
370 struct AllocationRecord {
372 lldb::addr_t m_process_address;
373 uintptr_t m_host_address;
374 uint32_t m_permissions;
375 lldb::SectionType m_sect_type;
377 unsigned m_alignment;
378 unsigned m_section_id;
380 AllocationRecord(uintptr_t host_address, uint32_t permissions,
381 lldb::SectionType sect_type, size_t size,
382 unsigned alignment, unsigned section_id, const char *name)
383 : m_name(), m_process_address(LLDB_INVALID_ADDRESS),
384 m_host_address(host_address), m_permissions(permissions),
385 m_sect_type(sect_type), m_size(size), m_alignment(alignment),
386 m_section_id(section_id) {
394 bool CommitOneAllocation(lldb::ProcessSP &process_sp, Status &error,
395 AllocationRecord &record);
397 typedef std::vector<AllocationRecord> RecordVector;
398 RecordVector m_records;
400 std::unique_ptr<llvm::LLVMContext> m_context_ap;
401 std::unique_ptr<llvm::ExecutionEngine> m_execution_engine_ap;
402 std::unique_ptr<llvm::ObjectCache> m_object_cache_ap;
403 std::unique_ptr<llvm::Module>
404 m_module_ap; ///< Holder for the module until it's been handed off
405 llvm::Module *m_module; ///< Owned by the execution engine
406 std::vector<std::string> m_cpu_features;
407 std::vector<JittedFunction> m_jitted_functions; ///< A vector of all functions
408 ///that have been JITted into
410 std::vector<JittedGlobalVariable> m_jitted_global_variables; ///< A vector of
415 const ConstString m_name;
416 SymbolContext m_sym_ctx; ///< Used for symbol lookups
417 std::vector<ConstString> m_failed_lookups;
419 std::atomic<bool> m_did_jit;
421 lldb::addr_t m_function_load_addr;
422 lldb::addr_t m_function_end_load_addr;
424 bool m_strip_underscore; ///< True for platforms where global symbols have a _
426 bool m_reported_allocations; ///< True after allocations have been reported.
427 ///It is possible that
428 ///< sections will be allocated when this is true, in which case they weren't
429 ///< depended on by any function. (Top-level code defining a variable, but
430 ///< defining no functions using that variable, would do this.) If this
431 ///< is true, any allocations need to be committed immediately -- no
432 ///< opportunity for relocation.
435 } // namespace lldb_private
437 #endif // liblldb_IRExecutionUnit_h_