docs/MCJITDesignAndImplementation.rst

   1 ===============================\r
   2 MCJIT Design and Implementation\r
   3 ===============================\r
   4 \r
   5 Introduction\r
   6 ============\r
   7 \r
   8 This document describes the internal workings of the MCJIT execution\r
   9 engine and the RuntimeDyld component.  It is intended as a high level\r
  10 overview of the implementation, showing the flow and interactions of\r
  11 objects throughout the code generation and dynamic loading process.\r
  12 \r
  13 Engine Creation\r
  14 ===============\r
  15 \r
  16 In most cases, an EngineBuilder object is used to create an instance of\r
  17 the MCJIT execution engine.  The EngineBuilder takes an llvm::Module\r
  18 object as an argument to its constructor.  The client may then set various\r
  19 options that we control the later be passed along to the MCJIT engine,\r
  20 including the selection of MCJIT as the engine type to be created.\r
  21 Of particular interest is the EngineBuilder::setMCJITMemoryManager\r
  22 function.  If the client does not explicitly create a memory manager at\r
  23 this time, a default memory manager (specifically SectionMemoryManager)\r
  24 will be created when the MCJIT engine is instantiated.\r
  25 \r
  26 Once the options have been set, a client calls EngineBuilder::create to\r
  27 create an instance of the MCJIT engine.  If the client does not use the\r
  28 form of this function that takes a TargetMachine as a parameter, a new\r
  29 TargetMachine will be created based on the target triple associated with\r
  30 the Module that was used to create the EngineBuilder.\r
  31 \r
  32 .. image:: MCJIT-engine-builder.png\r
  33  \r
  34 EngineBuilder::create will call the static MCJIT::createJIT function,\r
  35 passing in its pointers to the module, memory manager and target machine\r
  36 objects, all of which will subsequently be owned by the MCJIT object.\r
  37 \r
  38 The MCJIT class has a member variable, Dyld, which contains an instance of\r
  39 the RuntimeDyld wrapper class.  This member will be used for\r
  40 communications between MCJIT and the actual RuntimeDyldImpl object that\r
  41 gets created when an object is loaded.\r
  42 \r
  43 .. image:: MCJIT-creation.png\r
  44  \r
  45 Upon creation, MCJIT holds a pointer to the Module object that it received\r
  46 from EngineBuilder but it does not immediately generate code for this\r
  47 module.  Code generation is deferred until either the\r
  48 MCJIT::finalizeObject method is called explicitly or a function such as\r
  49 MCJIT::getPointerToFunction is called which requires the code to have been\r
  50 generated.\r
  51 \r
  52 Code Generation\r
  53 ===============\r
  54 \r
  55 When code generation is triggered, as described above, MCJIT will first\r
  56 attempt to retrieve an object image from its ObjectCache member, if one\r
  57 has been set.  If a cached object image cannot be retrieved, MCJIT will\r
  58 call its emitObject method.  MCJIT::emitObject uses a local PassManager\r
  59 instance and creates a new ObjectBufferStream instance, both of which it\r
  60 passes to TargetMachine::addPassesToEmitMC before calling PassManager::run\r
  61 on the Module with which it was created.\r
  62 \r
  63 .. image:: MCJIT-load.png\r
  64  \r
  65 The PassManager::run call causes the MC code generation mechanisms to emit\r
  66 a complete relocatable binary object image (either in either ELF or MachO\r
  67 format, depending on the target) into the ObjectBufferStream object, which\r
  68 is flushed to complete the process.  If an ObjectCache is being used, the\r
  69 image will be passed to the ObjectCache here.\r
  70 \r
  71 At this point, the ObjectBufferStream contains the raw object image.\r
  72 Before the code can be executed, the code and data sections from this\r
  73 image must be loaded into suitable memory, relocations must be applied and\r
  74 memory permission and code cache invalidation (if required) must be completed.\r
  75 \r
  76 Object Loading\r
  77 ==============\r
  78 \r
  79 Once an object image has been obtained, either through code generation or\r
  80 having been retrieved from an ObjectCache, it is passed to RuntimeDyld to\r
  81 be loaded.  The RuntimeDyld wrapper class examines the object to determine\r
  82 its file format and creates an instance of either RuntimeDyldELF or\r
  83 RuntimeDyldMachO (both of which derive from the RuntimeDyldImpl base\r
  84 class) and calls the RuntimeDyldImpl::loadObject method to perform that\r
  85 actual loading.\r
  86 \r
  87 .. image:: MCJIT-dyld-load.png\r
  88  \r
  89 RuntimeDyldImpl::loadObject begins by creating an ObjectImage instance\r
  90 from the ObjectBuffer it received.  ObjectImage, which wraps the\r
  91 ObjectFile class, is a helper class which parses the binary object image\r
  92 and provides access to the information contained in the format-specific\r
  93 headers, including section, symbol and relocation information.\r
  94 \r
  95 RuntimeDyldImpl::loadObject then iterates through the symbols in the\r
  96 image.  Information about common symbols is collected for later use.  For\r
  97 each function or data symbol, the associated section is loaded into memory\r
  98 and the symbol is stored in a symbol table map data structure.  When the\r
  99 iteration is complete, a section is emitted for the common symbols.\r
 100 \r
 101 Next, RuntimeDyldImpl::loadObject iterates through the sections in the\r
 102 object image and for each section iterates through the relocations for\r
 103 that sections.  For each relocation, it calls the format-specific\r
 104 processRelocationRef method, which will examine the relocation and store\r
 105 it in one of two data structures, a section-based relocation list map and\r
 106 an external symbol relocation map.\r
 107 \r
 108 .. image:: MCJIT-load-object.png\r
 109  \r
 110 When RuntimeDyldImpl::loadObject returns, all of the code and data\r
 111 sections for the object will have been loaded into memory allocated by the\r
 112 memory manager and relocation information will have been prepared, but the\r
 113 relocations have not yet been applied and the generated code is still not\r
 114 ready to be executed.\r
 115 \r
 116 [Currently (as of August 2013) the MCJIT engine will immediately apply\r
 117 relocations when loadObject completes.  However, this shouldn't be\r
 118 happening.  Because the code may have been generated for a remote target,\r
 119 the client should be given a chance to re-map the section addresses before\r
 120 relocations are applied.  It is possible to apply relocations multiple\r
 121 times, but in the case where addresses are to be re-mapped, this first\r
 122 application is wasted effort.]\r
 123 \r
 124 Address Remapping\r
 125 =================\r
 126 \r
 127 At any time after initial code has been generated and before\r
 128 finalizeObject is called, the client can remap the address of sections in\r
 129 the object.  Typically this is done because the code was generated for an\r
 130 external process and is being mapped into that process' address space.\r
 131 The client remaps the section address by calling MCJIT::mapSectionAddress.\r
 132 This should happen before the section memory is copied to its new\r
 133 location.\r
 134 \r
 135 When MCJIT::mapSectionAddress is called, MCJIT passes the call on to\r
 136 RuntimeDyldImpl (via its Dyld member).  RuntimeDyldImpl stores the new\r
 137 address in an internal data structure but does not update the code at this\r
 138 time, since other sections are likely to change.\r
 139 \r
 140 When the client is finished remapping section addresses, it will call\r
 141 MCJIT::finalizeObject to complete the remapping process.\r
 142 \r
 143 Final Preparations\r
 144 ==================\r
 145 \r
 146 When MCJIT::finalizeObject is called, MCJIT calls\r
 147 RuntimeDyld::resolveRelocations.  This function will attempt to locate any\r
 148 external symbols and then apply all relocations for the object.\r
 149 \r
 150 External symbols are resolved by calling the memory manager's\r
 151 getPointerToNamedFunction method.  The memory manager will return the\r
 152 address of the requested symbol in the target address space.  (Note, this\r
 153 may not be a valid pointer in the host process.)  RuntimeDyld will then\r
 154 iterate through the list of relocations it has stored which are associated\r
 155 with this symbol and invoke the resolveRelocation method which, through an\r
 156 format-specific implementation, will apply the relocation to the loaded\r
 157 section memory.\r
 158 \r
 159 Next, RuntimeDyld::resolveRelocations iterates through the list of\r
 160 sections and for each section iterates through a list of relocations that\r
 161 have been saved which reference that symbol and call resolveRelocation for\r
 162 each entry in this list.  The relocation list here is a list of\r
 163 relocations for which the symbol associated with the relocation is located\r
 164 in the section associated with the list.  Each of these locations will\r
 165 have a target location at which the relocation will be applied that is\r
 166 likely located in a different section.\r
 167 \r
 168 .. image:: MCJIT-resolve-relocations.png\r
 169  \r
 170 Once relocations have been applied as described above, MCJIT calls\r
 171 RuntimeDyld::getEHFrameSection, and if a non-zero result is returned\r
 172 passes the section data to the memory manager's registerEHFrames method.\r
 173 This allows the memory manager to call any desired target-specific\r
 174 functions, such as registering the EH frame information with a debugger.\r
 175 \r
 176 Finally, MCJIT calls the memory manager's finalizeMemory method.  In this\r
 177 method, the memory manager will invalidate the target code cache, if\r
 178 necessary, and apply final permissions to the memory pages it has\r
 179 allocated for code and data memory.\r
 180 \r