| =============================== |
| MCJIT Design and Implementation |
| =============================== |
| |
| Introduction |
| ============ |
| |
| This document describes the internal workings of the MCJIT execution |
| engine and the RuntimeDyld component. It is intended as a high level |
| overview of the implementation, showing the flow and interactions of |
| objects throughout the code generation and dynamic loading process. |
| |
| Engine Creation |
| =============== |
| |
| In most cases, an EngineBuilder object is used to create an instance of |
| the MCJIT execution engine. The EngineBuilder takes an llvm::Module |
| object as an argument to its constructor. The client may then set various |
| options that we control the later be passed along to the MCJIT engine, |
| including the selection of MCJIT as the engine type to be created. |
| Of particular interest is the EngineBuilder::setMCJITMemoryManager |
| function. If the client does not explicitly create a memory manager at |
| this time, a default memory manager (specifically SectionMemoryManager) |
| will be created when the MCJIT engine is instantiated. |
| |
| Once the options have been set, a client calls EngineBuilder::create to |
| create an instance of the MCJIT engine. If the client does not use the |
| form of this function that takes a TargetMachine as a parameter, a new |
| TargetMachine will be created based on the target triple associated with |
| the Module that was used to create the EngineBuilder. |
| |
| .. image:: MCJIT-engine-builder.png |
| |
| EngineBuilder::create will call the static MCJIT::createJIT function, |
| passing in its pointers to the module, memory manager and target machine |
| objects, all of which will subsequently be owned by the MCJIT object. |
| |
| The MCJIT class has a member variable, Dyld, which contains an instance of |
| the RuntimeDyld wrapper class. This member will be used for |
| communications between MCJIT and the actual RuntimeDyldImpl object that |
| gets created when an object is loaded. |
| |
| .. image:: MCJIT-creation.png |
| |
| Upon creation, MCJIT holds a pointer to the Module object that it received |
| from EngineBuilder but it does not immediately generate code for this |
| module. Code generation is deferred until either the |
| MCJIT::finalizeObject method is called explicitly or a function such as |
| MCJIT::getPointerToFunction is called which requires the code to have been |
| generated. |
| |
| Code Generation |
| =============== |
| |
| When code generation is triggered, as described above, MCJIT will first |
| attempt to retrieve an object image from its ObjectCache member, if one |
| has been set. If a cached object image cannot be retrieved, MCJIT will |
| call its emitObject method. MCJIT::emitObject uses a local PassManager |
| instance and creates a new ObjectBufferStream instance, both of which it |
| passes to TargetMachine::addPassesToEmitMC before calling PassManager::run |
| on the Module with which it was created. |
| |
| .. image:: MCJIT-load.png |
| |
| The PassManager::run call causes the MC code generation mechanisms to emit |
| a complete relocatable binary object image (either in either ELF or MachO |
| format, depending on the target) into the ObjectBufferStream object, which |
| is flushed to complete the process. If an ObjectCache is being used, the |
| image will be passed to the ObjectCache here. |
| |
| At this point, the ObjectBufferStream contains the raw object image. |
| Before the code can be executed, the code and data sections from this |
| image must be loaded into suitable memory, relocations must be applied and |
| memory permission and code cache invalidation (if required) must be completed. |
| |
| Object Loading |
| ============== |
| |
| Once an object image has been obtained, either through code generation or |
| having been retrieved from an ObjectCache, it is passed to RuntimeDyld to |
| be loaded. The RuntimeDyld wrapper class examines the object to determine |
| its file format and creates an instance of either RuntimeDyldELF or |
| RuntimeDyldMachO (both of which derive from the RuntimeDyldImpl base |
| class) and calls the RuntimeDyldImpl::loadObject method to perform that |
| actual loading. |
| |
| .. image:: MCJIT-dyld-load.png |
| |
| RuntimeDyldImpl::loadObject begins by creating an ObjectImage instance |
| from the ObjectBuffer it received. ObjectImage, which wraps the |
| ObjectFile class, is a helper class which parses the binary object image |
| and provides access to the information contained in the format-specific |
| headers, including section, symbol and relocation information. |
| |
| RuntimeDyldImpl::loadObject then iterates through the symbols in the |
| image. Information about common symbols is collected for later use. For |
| each function or data symbol, the associated section is loaded into memory |
| and the symbol is stored in a symbol table map data structure. When the |
| iteration is complete, a section is emitted for the common symbols. |
| |
| Next, RuntimeDyldImpl::loadObject iterates through the sections in the |
| object image and for each section iterates through the relocations for |
| that sections. For each relocation, it calls the format-specific |
| processRelocationRef method, which will examine the relocation and store |
| it in one of two data structures, a section-based relocation list map and |
| an external symbol relocation map. |
| |
| .. image:: MCJIT-load-object.png |
| |
| When RuntimeDyldImpl::loadObject returns, all of the code and data |
| sections for the object will have been loaded into memory allocated by the |
| memory manager and relocation information will have been prepared, but the |
| relocations have not yet been applied and the generated code is still not |
| ready to be executed. |
| |
| [Currently (as of August 2013) the MCJIT engine will immediately apply |
| relocations when loadObject completes. However, this shouldn't be |
| happening. Because the code may have been generated for a remote target, |
| the client should be given a chance to re-map the section addresses before |
| relocations are applied. It is possible to apply relocations multiple |
| times, but in the case where addresses are to be re-mapped, this first |
| application is wasted effort.] |
| |
| Address Remapping |
| ================= |
| |
| At any time after initial code has been generated and before |
| finalizeObject is called, the client can remap the address of sections in |
| the object. Typically this is done because the code was generated for an |
| external process and is being mapped into that process' address space. |
| The client remaps the section address by calling MCJIT::mapSectionAddress. |
| This should happen before the section memory is copied to its new |
| location. |
| |
| When MCJIT::mapSectionAddress is called, MCJIT passes the call on to |
| RuntimeDyldImpl (via its Dyld member). RuntimeDyldImpl stores the new |
| address in an internal data structure but does not update the code at this |
| time, since other sections are likely to change. |
| |
| When the client is finished remapping section addresses, it will call |
| MCJIT::finalizeObject to complete the remapping process. |
| |
| Final Preparations |
| ================== |
| |
| When MCJIT::finalizeObject is called, MCJIT calls |
| RuntimeDyld::resolveRelocations. This function will attempt to locate any |
| external symbols and then apply all relocations for the object. |
| |
| External symbols are resolved by calling the memory manager's |
| getPointerToNamedFunction method. The memory manager will return the |
| address of the requested symbol in the target address space. (Note, this |
| may not be a valid pointer in the host process.) RuntimeDyld will then |
| iterate through the list of relocations it has stored which are associated |
| with this symbol and invoke the resolveRelocation method which, through an |
| format-specific implementation, will apply the relocation to the loaded |
| section memory. |
| |
| Next, RuntimeDyld::resolveRelocations iterates through the list of |
| sections and for each section iterates through a list of relocations that |
| have been saved which reference that symbol and call resolveRelocation for |
| each entry in this list. The relocation list here is a list of |
| relocations for which the symbol associated with the relocation is located |
| in the section associated with the list. Each of these locations will |
| have a target location at which the relocation will be applied that is |
| likely located in a different section. |
| |
| .. image:: MCJIT-resolve-relocations.png |
| |
| Once relocations have been applied as described above, MCJIT calls |
| RuntimeDyld::getEHFrameSection, and if a non-zero result is returned |
| passes the section data to the memory manager's registerEHFrames method. |
| This allows the memory manager to call any desired target-specific |
| functions, such as registering the EH frame information with a debugger. |
| |
| Finally, MCJIT calls the memory manager's finalizeMemory method. In this |
| method, the memory manager will invalidate the target code cache, if |
| necessary, and apply final permissions to the memory pages it has |
| allocated for code and data memory. |