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